style: add typescript-eslint

eslint.config.js

@@ -1,12 +1,19 @@
 import js from "@eslint/js";
 import globals from "globals";
 import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
-import importPlugin from 'eslint-plugin-import';
+import importPlugin from "eslint-plugin-import";
+import tseslint from "typescript-eslint";
 
 export default [
   js.configs.recommended,
   eslintPluginPrettierRecommended,
   importPlugin.flatConfigs.recommended,
+  ...tseslint.configs.recommendedTypeCheckedOnly.map((config) => {
+    return {
+      files: ["lib/**"],
+      ...config,
+    };
+  }),
   {
     languageOptions: {
       ecmaVersion: "latest",
@@ -15,19 +22,31 @@ export default [
         ...globals.browser,
         ...globals.node,
         ...globals.mocha,
-      }
+      },
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
     },
     rules: {
       "eol-last": "error",
       "import/extensions": ["error", "always"],
-      'import/no-unresolved': 0, // https://github.com/import-js/eslint-plugin-import/issues/3082
+      "import/no-unresolved": 0, // https://github.com/import-js/eslint-plugin-import/issues/3082
       "no-console": "error",
-      "no-constant-condition": ["error", { "checkLoops": false }],
+      "no-constant-condition": ["error", { checkLoops: false }],
       "no-eval": "error",
       "no-implied-eval": "error",
       "no-trailing-spaces": "error",
       "prefer-const": "error",
-      "semi": "error"
+      semi: "error",
+
+      // For now we want to focus on the exposed types rather than the internals.
+      "@typescript-eslint/no-unsafe-argument": 0,
+      "@typescript-eslint/no-unsafe-assignment": 0,
+      "@typescript-eslint/no-unsafe-call": 0,
+      "@typescript-eslint/no-unsafe-member-access": 0,
+      // Incorrectly yells at static functions
+      "@typescript-eslint/unbound-method": 0
     },
   },
 ];

lib/error.js

@@ -1,3 +1,6 @@
+/** @import { Base } from "./productions/base.js" */
+/** @import { Source } from "./tokeniser.js" */
+
 /**
  * @param {string} text
  */
@@ -6,6 +9,10 @@ function lastLine(text) {
   return splitted[splitted.length - 1];
 }
 
+/**
+ * @param {string} base
+ * @param {string} target
+ */
 function appendIfExist(base, target) {
   let result = base;
   if (target) {
@@ -14,6 +21,9 @@ function appendIfExist(base, target) {
   return result;
 }
 
+/**
+ * @param {Base} node
+ */
 function contextAsText(node) {
   const hierarchy = [node];
   while (node && node.parent) {
@@ -32,10 +42,10 @@ function contextAsText(node) {
  *
  * @typedef {ReturnType<typeof error>} WebIDLErrorData
  *
- * @param {string} message error message
- * @param {*} position
+ * @param {Source} source
+ * @param {number} position
  * @param {*} current
- * @param {*} message
+ * @param {string} message error message
  * @param {"Syntax" | "Validation"} kind error type
  * @param {WebIDL2ErrorOptions=} options
  */

lib/productions/argument.js

@@ -14,7 +14,14 @@
   dictionaryIncludesRequiredField,
 } from "../validators/helpers.js";
 
+/** @import {Type} from "./type.js" */
+
 export class Argument extends Base {
+  /** @type {Type} */
+  idlType;
+  /** @type {Default | null} */
+  default;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */
@@ -109,7 +116,7 @@
 
   /** @param {import("../writer.js").Writer} w */
   write(w) {
     return w.ts.wrap([
       this.extAttrs.write(w),
       w.token(this.tokens.optional),
       w.ts.type(this.idlType.write(w)),

lib/productions/array-base.js

@@ -1,4 +1,12 @@
+/** @import {Token} from "../tokeniser.js" */
+
 export class ArrayBase extends Array {
+  /** @type {Record<string, Token | undefined>} */
+  tokens;
+  /** @type {Token[]} */
+  source;
+  parent;
+
   constructor({ source, tokens }) {
     super();
     Object.defineProperties(this, {

lib/productions/attribute.js

@@ -10,7 +10,12 @@
   autoParenter,
 } from "./helpers.js";
 
+/** @import {Type} from "./type.js" */
+
 export class Attribute extends Base {
+  /** @type {Type} */
+  idlType;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    * @param {object} [options]
@@ -110,7 +115,7 @@
   /** @param {import("../writer.js").Writer} w */
   write(w) {
     const { parent } = this;
     return w.ts.definition(
       w.ts.wrap([
         this.extAttrs.write(w),
         w.token(this.tokens.special),

lib/productions/base.js

@@ -1,26 +1,65 @@
+/** @import {ExtendedAttributes} from "./extended-attributes.js" */
+/** @import {Token} from "../tokeniser.js" */
+/** @import {Definitions} from "../validator.js" */
+/** @import {Writer} from "../writer.js" */
+
 export class Base {
+  /** @type {Record<string, Token | undefined>} */
+  tokens;
+  /** @type {Token[]} */
+  source;
+  /** @type {ExtendedAttributes | undefined} */
+  extAttrs;
+  /** @type {this} */
+  this;
+  /** @type {*} */
+  parent;
+
   /**
    * @param {object} initializer
    * @param {Base["source"]} initializer.source
    * @param {Base["tokens"]} initializer.tokens
    */
   constructor({ source, tokens }) {
     Object.defineProperties(this, {
-      source: { value: source },
-      tokens: { value: tokens, writable: true },
-      parent: { value: null, writable: true },
-      this: { value: this }, // useful when escaping from proxy
+      source: { value: source, enumerable: false },
+      tokens: { value: tokens, writable: true, enumerable: false },
+      parent: { value: null, writable: true, enumerable: false },
+      this: { value: this, enumerable: false }, // useful when escaping from proxy
     });
   }
 
+  get type() {
+    return undefined;
+  }
+  get name() {
+    return undefined;
+  }
+
+  /**
+   * @param {Definitions} defs
+   * @returns {IterableIterator<any>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  *validate(defs) {}
+
+  /**
+   * @template T
+   * @param {Writer<T>} w
+   * @returns {T | string}
+   */
+  // eslint-disable-next-line no-unused-vars
+  write(w) {
+    return "";
+  }
+
   toJSON() {
     const json = { type: undefined, name: undefined, inheritance: undefined };
     let proto = this;
     while (proto !== Object.prototype) {
       const descMap = Object.getOwnPropertyDescriptors(proto);
       for (const [key, value] of Object.entries(descMap)) {
         if (value.enumerable || value.get) {
-          // @ts-ignore - allow indexing here
           json[key] = this[key];
         }
       }

lib/productions/callback-interface.js

@@ -1,4 +1,4 @@
-import { Container } from "./container.js";
+import { Container, parseContainer } from "./container.js";
 import { Operation } from "./operation.js";
 import { Constant } from "./constant.js";
 
@@ -15,7 +15,7 @@ export class CallbackInterface extends Container {
     if (!tokens.base) {
       return;
     }
-    return Container.parse(
+    return parseContainer(
       tokeniser,
       new CallbackInterface({ source: tokeniser.source, tokens }),
       {

lib/productions/callback.js

@@ -7,7 +7,15 @@
 } from "./helpers.js";
 import { validationError } from "../error.js";
 
+/** @import {Type} from "./type.js" */
+/** @import {Argument} from "./argument.js" */
+
 export class CallbackFunction extends Base {
+  /** @type {Type} */
+  idlType;
+  /** @type {Argument[]} */
+  arguments;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */
@@ -62,7 +70,7 @@
 
   /** @param {import("../writer.js").Writer} w */
   write(w) {
     return w.ts.definition(
       w.ts.wrap([
         this.extAttrs.write(w),
         w.token(this.tokens.base),
@@ -70,7 +78,7 @@
         w.token(this.tokens.assign),
         w.ts.type(this.idlType.write(w)),
         w.token(this.tokens.open),
         ...this.arguments.map((arg) => arg.write(w)),
         w.token(this.tokens.close),
         w.token(this.tokens.termination),
       ]),

lib/productions/constant.js

@@ -9,6 +9,9 @@
 } from "./helpers.js";
 
 export class Constant extends Base {
+  /** @type {Type} */
+  idlType;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */
@@ -58,7 +61,7 @@
   /** @param {import("../writer.js").Writer} w */
   write(w) {
     const { parent } = this;
     return w.ts.definition(
       w.ts.wrap([
         this.extAttrs.write(w),
         w.token(this.tokens.base),

lib/productions/constructor.js

@@ -1,7 +1,12 @@
 import { Base } from "./base.js";
 import { argument_list, autoParenter } from "./helpers.js";
 
+/** @import {Argument} from "./argument.js" */
+
 export class Constructor extends Base {
+  /** @type {Argument[]} */
+  arguments;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */
@@ -39,12 +44,12 @@
   /** @param {import("../writer.js").Writer} w */
   write(w) {
     const { parent } = this;
     return w.ts.definition(
       w.ts.wrap([
         this.extAttrs.write(w),
         w.token(this.tokens.base, w.ts.nameless, { data: this, parent }),
         w.token(this.tokens.open),
         w.ts.wrap(this.arguments.map((arg) => arg.write(w))),
         w.token(this.tokens.close),
         w.token(this.tokens.termination),
       ]),

lib/productions/container.js

@@ -2,8 +2,10 @@
 import { ExtendedAttributes } from "./extended-attributes.js";
 import { unescape, autoParenter } from "./helpers.js";
 
+/** @import {Tokeniser} from "../tokeniser.js" */
+
 /**
- * @param {import("../tokeniser.js").Tokeniser} tokeniser
+ * @param {Tokeniser} tokeniser
  */
 function inheritance(tokeniser) {
   const colon = tokeniser.consume(":");
@@ -19,7 +21,7 @@
 /**
  * Parser callback.
  * @callback ParserCallback
- * @param {import("../tokeniser.js").Tokeniser} tokeniser
+ * @param {Tokeniser} tokeniser
  * @param {...*} args
  */
 
@@ -30,45 +32,11 @@
  */
 
 export class Container extends Base {
-  /**
-   * @param {import("../tokeniser.js").Tokeniser} tokeniser
-   * @param {*} instance TODO: This should be {T extends Container}, but see https://github.com/microsoft/TypeScript/issues/4628
-   * @param {*} args
-   */
-  static parse(tokeniser, instance, { inheritable, allowedMembers }) {
-    const { tokens, type } = instance;
-    tokens.name =
-      tokeniser.consumeKind("identifier") ||
-      tokeniser.error(`Missing name in ${type}`);
-    tokeniser.current = instance;
-    instance = autoParenter(instance);
-    if (inheritable) {
-      Object.assign(tokens, inheritance(tokeniser));
-    }
-    tokens.open = tokeniser.consume("{") || tokeniser.error(`Bodyless ${type}`);
-    instance.members = [];
-    while (true) {
-      tokens.close = tokeniser.consume("}");
-      if (tokens.close) {
-        tokens.termination =
-          tokeniser.consume(";") ||
-          tokeniser.error(`Missing semicolon after ${type}`);
-        return instance.this;
-      }
-      const ea = ExtendedAttributes.parse(tokeniser);
-      let mem;
-      for (const [parser, ...args] of allowedMembers) {
-        mem = autoParenter(parser(tokeniser, ...args));
-        if (mem) {
-          break;
-        }
-      }
-      if (!mem) {
-        tokeniser.error("Unknown member");
-      }
-      mem.extAttrs = ea;
-      instance.members.push(mem.this);
-    }
+  /** @type {any[]} */
+  members;
+
+  get type() {
+    return "";
   }
 
   get partial() {
@@ -98,7 +66,7 @@
       if (!this.tokens.inheritance) {
         return "";
       }
       return w.ts.wrap([
         w.token(this.tokens.colon),
         w.ts.trivia(this.tokens.inheritance.trivia),
         w.ts.inheritance(
@@ -107,7 +75,7 @@
       ]);
     };
 
     return w.ts.definition(
       w.ts.wrap([
         this.extAttrs.write(w),
         w.token(this.tokens.callback),
@@ -117,7 +85,7 @@
         w.name_token(this.tokens.name, { data: this }),
         inheritance(),
         w.token(this.tokens.open),
         w.ts.wrap(this.members.map((m) => m.write(w))),
         w.token(this.tokens.close),
         w.token(this.tokens.termination),
       ]),
@@ -125,3 +93,50 @@
     );
   }
 }
+
+/**
+ * @param {Tokeniser} tokeniser
+ * @param {Container} instance
+ * @param {object} args
+ * @param {boolean} [args.inheritable]
+ * @param {AllowedMember[]} [args.allowedMembers]
+ */
+export function parseContainer(
+  tokeniser,
+  instance,
+  { inheritable, allowedMembers },
+) {
+  const { tokens, type } = instance;
+  tokens.name =
+    tokeniser.consumeKind("identifier") ||
+    tokeniser.error(`Missing name in ${type}`);
+  tokeniser.current = instance;
+  instance = autoParenter(instance);
+  if (inheritable) {
+    Object.assign(tokens, inheritance(tokeniser));
+  }
+  tokens.open = tokeniser.consume("{") || tokeniser.error(`Bodyless ${type}`);
+  instance.members = [];
+  while (true) {
+    tokens.close = tokeniser.consume("}");
+    if (tokens.close) {
+      tokens.termination =
+        tokeniser.consume(";") ||
+        tokeniser.error(`Missing semicolon after ${type}`);
+      return instance.this;
+    }
+    const ea = ExtendedAttributes.parse(tokeniser);
+    let mem;
+    for (const [parser, ...args] of allowedMembers) {
+      mem = autoParenter(parser(tokeniser, ...args));
+      if (mem) {
+        break;
+      }
+    }
+    if (!mem) {
+      tokeniser.error("Unknown member");
+    }
+    mem.extAttrs = ea;
+    instance.members.push(mem.this);
+  }
+}