Add some types to AI Assistance script

I was making them to aid my debugging as I was getting familiar with the
code, and thought we might as well land some to help others too.

Bug: 704639063
Change-Id: Ia4678cc136e6414438d19c7652fd9f5b390c0cae
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6085698
Commit-Queue: Alex Rudenko <[email protected]>
Auto-Submit: Jack Franklin <[email protected]>
Reviewed-by: Alex Rudenko <[email protected]>

Author: jackfranklin

scripts/ai_assistance/auto-run.js

@@ -17,6 +17,7 @@ function formatElapsedTime() {
 }
 
 /* clang-format off */
+/** @type {import('./types').YargsInput} */
 const yargsObject = yargs
   .option('example-urls', {
     string: true,
@@ -42,6 +43,7 @@ const OUTPUT_DIR = path.resolve(__dirname, 'data');
 const {exampleUrls, label} = yargsObject;
 
 class Logger {
+  /** @type {import('./types').Logs} */
   #logs = {};
   #updateElapsedTimeInterval = 0;
   constructor() {
@@ -72,6 +74,11 @@ class Logger {
     this.log('head', -1, `${text}\n`);
   }
 
+  /**
+   * @param {string} id
+   * @param {number} index
+   * @param {string} text
+   */
   log(id, index, text) {
     this.#updateElapsedTime();
     this.#logs[id] = {index, text};
@@ -259,6 +266,10 @@ class Example {
     });
 
     const results = [];
+
+    /**
+     * @returns {Promise<import('./types').ExecutedExample>}
+     */
     const prompt = async query => {
       await this.#devtoolsPage.locator('aria/Ask a question about the selected element').click();
 
@@ -291,11 +302,12 @@ class Example {
       await done;
       abort.abort();
 
-      const result = JSON.parse(await this.#devtoolsPage.evaluate(() => {
+      /** @type {import('./types').IndividualPromptRequestResponse[]} */
+      const results = JSON.parse(await this.#devtoolsPage.evaluate(() => {
         return localStorage.getItem('freestylerStructuredLog');
       }));
 
-      return result.map(r => ({...r, exampleId: this.id()}));
+      return results.map(r => ({...r, exampleId: this.id()}));
     };
 
     for (const query of this.#queries) {
@@ -307,6 +319,8 @@ class Example {
     await this.#page.close();
     const elapsedTime = numberFormatter.format((performance.now() - executionStartTime) / 1000);
     this.log(`Finished (${elapsedTime}s)`);
+
+    /** @type {import('./types').ExecutedExample} */
     return {results, metadata: {exampleId: this.id(), explanation: this.#explanation}};
   }
 
@@ -326,6 +340,11 @@ class Example {
 }
 
 const logger = new Logger();
+
+/**
+ * @param {Example[]} examples
+ * @return {Promise<RunResult>}
+ */
 async function runInParallel(examples) {
   logger.head('Preparing examples...');
   for (const example of examples) {
@@ -348,8 +367,15 @@ async function runInParallel(examples) {
   return {allExampleResults, metadata};
 }
 
+/**
+ * @param {Example[]} examples
+ * @return {Promise<import('./types').RunResult>}
+ */
 async function runSequentially(examples) {
+  /** @type {import('./types').ExecutedExample[]} */
   const allExampleResults = [];
+
+  /** @type {import('./types').ExampleMetadata} */
   const metadata = [];
   logger.head('Running examples sequentially...');
   for (const example of examples) {
@@ -401,8 +427,11 @@ async function main() {
 
   logger.head('Preparing examples...');
   const examples = exampleUrls.map(exampleUrl => new Example(exampleUrl, browser));
+  /** @type {import('./types').IndividualPromptRequestResponse[]} */
   let allExampleResults = [];
+  /** @type {import('./types').ExampleMetadata[]} */
   let metadata = [];
+
   if (yargsObject.parallel) {
     ({allExampleResults, metadata} = await runInParallel(examples));
   } else {

scripts/ai_assistance/types.d.ts

@@ -0,0 +1,54 @@
+import {AidaRequest} from '../../front_end/core/host/AidaClient.ts'
+
+/**
+ * Some types used in auto-run.js. They only exist here because it's
+ * nicer to define these types in a .d.ts file than JSDOc syntax.
+ */
+
+/**
+ * The result of running auto_freestyler against all the provided examples.
+ */
+export interface RunResult {
+  allExampleResults: ExecutedExample[];
+  metadata: ExampleMetadata[]
+}
+
+/**
+ * The result of running a single example.
+ */
+export interface ExecutedExample {
+  results: IndividualPromptRequestResponse[];
+  metadata: ExampleMetadata;
+}
+
+/**
+ * The result of making a single request to Aida.
+ */
+export interface IndividualPromptRequestResponse {
+  request: AidaRequest;
+  response: string;
+  exampleId: string;
+}
+
+export interface ExampleMetadata {
+  exampleId: string;
+  explanation: string;
+}
+
+/**
+ * The CLI arguments people can use to configure the run.
+ */
+export interface YargsInput {
+  exampleUrls: string[];
+  label: string;
+  parallel: boolean;
+  includeFollowUp: boolean;
+}
+
+// Clang cannot handle the Record<> syntax over multiple lines, it seems.
+/* clang-format off */
+export type Logs = Record<string, {
+  index: number;
+  text: string;
+}> ;
+/* clang-format on */