Jsdoc type declarations to Typescript types (#71)

* First pass on JSDoc types -> Typescript Types conversion

* Second pass, declared namespaces

* Handle merge with updated main

* TS types for FileRecord, expect-errors for incorrectly typed EventEmitter, TextEncoder, TextDecoder objects

* Remove incorrect autoimport

* Remove remaining jsdoc imports

* Preserve property description

---------

Co-authored-by: Mike Pennisi <mike@mikepennisi.com>

src/host/cli.js

@@ -1,5 +1,3 @@
-/// <reference path="./types.js" />
-
 /**
  * @module host
  */

src/host/main.js

@@ -1,5 +1,3 @@
-/// <reference path="types.js" />
-
 /**
  * @module host
  */
@@ -129,6 +127,7 @@ export async function hostMain(options) {
           plan = addTestLogToTestPlan(plan, test);
         }
       };
+      /** @ts-expect-error EventEmitter is not correctly typed */
       logger.emitter.on('message', addLogtoPlan);
 
       try {
@@ -153,6 +152,7 @@ export async function hostMain(options) {
         await lastCallbackRequest;
         throw exception;
       } finally {
+        /** @ts-expect-error EventEmitter is not correctly typed */
         logger.emitter.off('message', addLogtoPlan);
       }
     }

src/host/messages.js

@@ -1,5 +1,3 @@
-/// <reference path="types.js" />
-
 /**
  * @module host
  */

src/host/plan-from.js

@@ -1,6 +1,3 @@
-/// <reference path="../shared/file-record-types.js" />
-/// <reference path="types.js" />
-
 /**
  * @module host
  */

src/host/plan-object.js

@@ -1,6 +1,3 @@
-/// <reference path="../shared/file-record.js" />
-/// <reference path="types.js" />
-
 /**
  * @module host
  */

src/host/server.js

@@ -1,5 +1,3 @@
-/// <reference path="types.js" />
-
 /**
  * @module host
  */

src/host/tests/plan-from.js

@@ -1,5 +1,3 @@
-/// <reference path="../types.js"/>
-
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 
@@ -114,6 +112,7 @@ function isTextFile(filePath) {
 function normalizeTextRecordEOL(file, { textEncoder, textDecoder } = textCoders()) {
   return {
     ...file,
+    // @ts-expect-error - TextEncoder and TextDecoder are not typed as classes.
     bufferData: textEncoder.encode(textDecoder.decode(file.bufferData).replace(/\r\n/g, '\n')),
   };
 }
@@ -122,5 +121,6 @@ function normalizeTextRecordEOL(file, { textEncoder, textDecoder } = textCoders(
  * @returns {{textEncoder: TextEncoder, textDecoder: TextDecoder}}
  */
 function textCoders() {
+  // @ts-expect-error - TextEncoder and TextDecoder are not typed as classes.
   return { textEncoder: new TextEncoder(), textDecoder: new TextDecoder() };
 }

src/host/types.d.ts

@@ -0,0 +1,65 @@
+declare namespace AriaATCIHost {
+  export type HostLogType =
+    | 'start'
+    | 'uncaughtError'
+    | 'willStop'
+    | 'startServer'
+    | 'planRead'
+    | 'serverListening'
+    | 'stopServer'
+    | 'stopDrivers'
+    | 'addServerDirectory'
+    | 'removeServerDirectory'
+    | 'serverLog'
+    | 'startTest'
+    | 'reportingError'
+    | 'testError'
+    | 'atDriverComms'
+    | 'openPage'
+    | 'pressKeys'
+    | 'speechEvent'
+    | 'invalidKeys'
+    | 'noRunTestSetup'
+    | 'capabilities';
+
+  export type Log = AriaATCIShared.Log<HostLogType>;
+
+  export interface Logger {
+    log: Log;
+    emitter: typeof import('events').EventEmitter;
+  }
+
+  export interface TestPlan {
+    name: string;
+    serverOptions: {
+      baseUrl: AriaATCIShared.BaseURL;
+    };
+    tests: Array<{
+      id: string;
+      filepath: string;
+      log: number[];
+      results: any[];
+    }>;
+    files: FileRecord.NamedRecord[];
+    log: AriaATCIData.Log[];
+  }
+
+  export interface TestPlanServerOptionsPartial {
+    baseUrl?: AriaATCIShared.BaseURL;
+  }
+
+  export interface ReferenceFileServer {
+    addFiles: (files: FileRecord.NamedRecord[]) => ReferenceFileServerSlice;
+    removeFiles: (slice: ReferenceFileServerSlice) => void;
+    close: () => Promise<void>;
+    ready: Promise<void>;
+    baseUrl: string;
+  }
+
+  export interface ReferenceFileServerSlice {
+    id: string;
+    baseUrl: AriaATCIShared.BaseURL;
+  }
+
+  export type EmitPlanResults = (plan: TestPlan) => Promise<void> | void;
+}

src/runner/browser-driver/create-safari-apple-script-driver.js

@@ -41,7 +41,7 @@ const evalJavaScript = source => {
 };
 
 /**
- * @param {AriaATCIShared.timesOption} timesOption
+ * @param {AriaATCIShared.TimesOption} timesOption
  */
 export default async timesOption => {
   await execScript(`tell application "Safari"

src/runner/browser-driver/create-web-driver.js

@@ -1,7 +1,7 @@
 import { Builder } from 'selenium-webdriver';
 import { until, By } from 'selenium-webdriver';
 
-/** @returns {Promise<BrowserDriver>} */
+/** @returns {Promise<AriaATCIRunner.BrowserDriver>} */
 export default async (browser, serverUrl) => {
   const driver = await new Builder().forBrowser(browser).usingServer(serverUrl).build();
 

src/runner/browser-driver/create.js

@@ -6,9 +6,9 @@ import createSafariAppleScriptDriver from './create-safari-apple-script-driver.j
  * @param {{toString: function(): string}} options.url
  * @param {AriaATCIRunner.Browser} [options.browser]
  * @param {Promise<void>} options.abortSignal
- * @param {AriaATCIShared.timesOption} options.timesOption
+ * @param {AriaATCIShared.TimesOption} options.timesOption
  *
- * @returns {Promise<BrowserDriver>}
+ * @returns {Promise<AriaATCIRunner.BrowserDriver>}
  */
 export async function createBrowserDriver({ url, browser = 'firefox', abortSignal, timesOption }) {
   const driver =

src/runner/create-test-runner.js

@@ -1,6 +1,3 @@
-/// <reference path="../shared/types.js" />
-/// <reference path="types.js" />
-
 /**
  * @module agent
  */
@@ -18,7 +15,7 @@ import { createATDriver } from './at-driver.js';
  * @param {Promise<void>} options.abortSignal
  * @param {boolean} [options.mock]
  * @param {AriaATCIRunner.Browser} [options.webDriverBrowser]
- * @param {AriaATCIShared.timesOption} options.timesOption
+ * @param {AriaATCIShared.TimesOption} options.timesOption
  * @param {{toString: function(): string}} options.webDriverUrl
  * @returns {Promise<AriaATCIRunner.TestRunner>}
  */

src/runner/driver-test-runner.js

@@ -1,7 +1,3 @@
-/// <reference path="../data/types.js" />
-/// <reference path="../shared/types.js" />
-/// <reference path="types.js" />
-
 import { startJob } from '../shared/job.js';
 
 import { ATDriver, ATKey, webDriverCodePoints } from './at-driver.js';
@@ -15,10 +11,10 @@ export class DriverTestRunner {
   /**
    * @param {object} options
    * @param {URL} options.baseUrl
-   * @param {AriaATCIHost.Log} options.log
-   * @param {BrowserDriver} options.browserDriver
+   * @param {AriaATCIRunner.Log} options.log
+   * @param {AriaATCIRunner.BrowserDriver} options.browserDriver
    * @param {ATDriver} options.atDriver
-   * @param {AriaATCIShared.timesOption} options.timesOption
+   * @param {AriaATCIShared.TimesOption} options.timesOption
    */
   constructor({ baseUrl, log, browserDriver, atDriver, timesOption }) {
     this.baseUrl = baseUrl;

src/runner/messages.js

@@ -1,6 +1,3 @@
-/// <reference path="../shared/types.js" />
-/// <reference path="types.js" />
-
 /**
  * @module runner
  */

src/runner/mock-test-runner.js

@@ -1,7 +1,3 @@
-/// <reference path="../data/types.js" />
-/// <reference path="../shared/types.js" />
-/// <reference path="types.js" />
-
 /**
  * @module agent
  */

src/runner/types.d.ts

@@ -0,0 +1,51 @@
+declare namespace AriaATCIRunner {
+  type Message =
+    | 'start'
+    | 'uncaughtError'
+    | 'willStop'
+    | 'startTest'
+    | 'openPage'
+    | 'invalidKeys'
+    | 'pressKeys'
+    | 'speechEvent'
+    | 'noRunTestSetup'
+    | 'atDriverComms'
+    | 'capabilities';
+
+  type Log = AriaATCIShared.Log<Message>;
+
+  type TestIterable = AsyncIterable<AriaATCIData.Test>;
+
+  interface TestRunner {
+    run(test: AriaATCIData.Test): Promise<AriaATCIData.TestResultOutput>;
+  }
+
+  type ReportResult = (result: AriaATCIData.TestResult) => Promise<void>;
+
+  type Browser = 'chrome' | 'firefox' | 'safari';
+
+  interface CliOptions {
+    debug?: boolean;
+    quiet?: boolean;
+    verbose?: Message[];
+    referenceBaseUrl?: AriaATCIShared.BaseURL;
+    mock?: boolean;
+    webDriverUrl?: AriaATCIShared.BaseURL;
+    webDriverBrowser?: Browser;
+    atDriverUrl?: AriaATCIShared.BaseURL;
+    timesOption?: AriaATCIShared.TimesOption;
+  }
+
+  interface BrowserCapabilities {
+    browserName: string;
+    browserVersion: string;
+  }
+
+  interface BrowserDriver {
+    navigate(url: string): Promise<void>;
+    documentReady(): Promise<void>;
+    clickWhenPresent(selector: string, timeout: number): Promise<void>;
+    getCapabilities(): Promise<BrowserCapabilities>;
+    quit(): Promise<void>;
+  }
+}