feat: Programmatic building of type-checkable JS and declaration files

.eslintignore

@@ -2,3 +2,4 @@
 /tests/fixtures
 /dist
 tools/create-test-example.js
+tmp

.eslintrc.cjs

@@ -12,7 +12,7 @@ module.exports = {
         }
     },
     parserOptions: {
-        ecmaVersion: 2020,
+        ecmaVersion: 2022,
         sourceType: "module"
     },
     overrides: [
@@ -34,5 +34,10 @@ module.exports = {
                 "no-console": "off"
             }
         }
-    ]
+    ],
+    rules: {
+        "jsdoc/check-tag-names": ["error", {
+            definedTags: ["local", "export"]
+        }]
+    }
 };

.gitignore

@@ -10,3 +10,4 @@ _test.js
 .eslint-release-info.json
 yarn.lock
 package-lock.json
+tmp

espree.js

@@ -56,6 +56,68 @@
  */
 /* eslint no-undefined:0, no-use-before-define: 0 */
 
+// ----------------------------------------------------------------------------
+// Types exported from file
+// ----------------------------------------------------------------------------
+/**
+ * @typedef {3|5|6|7|8|9|10|11|12|13|2015|2016|2017|2018|2019|2020|2021|2022|'latest'} ecmaVersion
+ */
+
+/**
+ * @typedef {import('./lib/token-translator').EsprimaToken} EspreeToken
+ */
+
+/**
+ * @typedef {import('./lib/espree').EsprimaComment} EspreeComment
+ */
+
+/**
+ * @typedef {{
+ *   comments?: EspreeComment[]
+ * } & EspreeToken[]} EspreeTokens
+ */
+
+/**
+ * `jsx.Options` gives us 2 optional properties, so extend it
+ *
+ * `allowReserved`, `ranges`, `locations`, `allowReturnOutsideFunction`,
+ * `onToken`, and `onComment` are as in `acorn.Options`
+ *
+ * `ecmaVersion` currently as in `acorn.Options` though optional
+ *
+ * `sourceType` as in `acorn.Options` but also allows `commonjs`
+ *
+ * `ecmaFeatures`, `range`, `loc`, `tokens` are not in `acorn.Options`
+ *
+ * `comment` is not in `acorn.Options` and doesn't err without it, but is used
+ */
+/**
+ * @typedef {{
+ *   allowReserved?: boolean,
+ *   ecmaVersion?: ecmaVersion,
+ *   sourceType?: "script"|"module"|"commonjs",
+ *   ecmaFeatures?: {
+ *     jsx?: boolean,
+ *     globalReturn?: boolean,
+ *     impliedStrict?: boolean
+ *   },
+ *   range?: boolean,
+ *   loc?: boolean,
+ *   tokens?: boolean,
+ *   comment?: boolean,
+ * }} ParserOptions
+ */
+
+// ----------------------------------------------------------------------------
+// Local type imports
+// ----------------------------------------------------------------------------
+/**
+ * @local
+ * @typedef {import('acorn')} acorn
+ * @typedef {import('./lib/espree').EnhancedSyntaxError} EnhancedSyntaxError
+ * @typedef {typeof import('./lib/espree').EspreeParser} IEspreeParser
+ */
+
 import * as acorn from "acorn";
 import jsx from "acorn-jsx";
 import espree from "./lib/espree.js";
@@ -66,23 +128,54 @@ import { getLatestEcmaVersion, getSupportedEcmaVersions } from "./lib/options.js
 
 // To initialize lazily.
 const parsers = {
-    _regular: null,
-    _jsx: null,
+    _regular: /** @type {IEspreeParser|null} */ (null),
+    _jsx: /** @type {IEspreeParser|null} */ (null),
 
+    /**
+     * Returns regular Parser
+     * @returns {IEspreeParser} Regular Acorn parser
+     */
     get regular() {
         if (this._regular === null) {
-            this._regular = acorn.Parser.extend(espree());
+            const espreeParserFactory = /** @type {unknown} */ (espree());
+
+            this._regular = /** @type {IEspreeParser} */ (
+                acorn.Parser.extend(
+
+                    /** @type {(BaseParser: typeof acorn.Parser) => typeof acorn.Parser} */
+                    (espreeParserFactory)
+                )
+            );
         }
         return this._regular;
     },
 
+    /**
+     * Returns JSX Parser
+     * @returns {IEspreeParser} JSX Acorn parser
+     */
     get jsx() {
         if (this._jsx === null) {
-            this._jsx = acorn.Parser.extend(jsx(), espree());
+            const espreeParserFactory = /** @type {unknown} */ (espree());
+            const jsxFactory = jsx();
+
+            this._jsx = /** @type {IEspreeParser} */ (
+                acorn.Parser.extend(
+                    jsxFactory,
+
+                    /** @type {(BaseParser: typeof acorn.Parser) => typeof acorn.Parser} */
+                    (espreeParserFactory)
+                )
+            );
         }
         return this._jsx;
     },
 
+    /**
+     * Returns Regular or JSX Parser
+     * @param {ParserOptions} options Parser options
+     * @returns {IEspreeParser} Regular or JSX Acorn parser
+     */
     get(options) {
         const useJsx = Boolean(
             options &&
@@ -101,9 +194,9 @@ const parsers = {
 /**
  * Tokenizes the given code.
  * @param {string} code The code to tokenize.
- * @param {Object} options Options defining how to tokenize.
- * @returns {Token[]} An array of tokens.
- * @throws {SyntaxError} If the input code is invalid.
+ * @param {ParserOptions} options Options defining how to tokenize.
+ * @returns {EspreeTokens} An array of tokens.
+ * @throws {EnhancedSyntaxError} If the input code is invalid.
  * @private
  */
 export function tokenize(code, options) {
@@ -114,7 +207,7 @@ export function tokenize(code, options) {
         options = Object.assign({}, options, { tokens: true }); // eslint-disable-line no-param-reassign
     }
 
-    return new Parser(options, code).tokenize();
+    return /** @type {EspreeTokens} */ (new Parser(options, code).tokenize());
 }
 
 //------------------------------------------------------------------------------
@@ -124,9 +217,9 @@ export function tokenize(code, options) {
 /**
  * Parses the given code.
  * @param {string} code The code to tokenize.
- * @param {Object} options Options defining how to tokenize.
- * @returns {ASTNode} The "Program" AST node.
- * @throws {SyntaxError} If the input code is invalid.
+ * @param {ParserOptions} options Options defining how to tokenize.
+ * @returns {acorn.Node} The "Program" AST node.
+ * @throws {EnhancedSyntaxError} If the input code is invalid.
  */
 export function parse(code, options) {
     const Parser = parsers.get(options);
@@ -148,17 +241,15 @@ export const VisitorKeys = (function() {
 // Derive node types from VisitorKeys
 /* istanbul ignore next */
 export const Syntax = (function() {
-    let name,
+    let /** @type {Object<string,string>} */
         types = {};
 
     if (typeof Object.create === "function") {
         types = Object.create(null);
     }
 
-    for (name in VisitorKeys) {
-        if (Object.hasOwnProperty.call(VisitorKeys, name)) {
-            types[name] = name;
-        }
+    for (const name of Object.keys(VisitorKeys)) {
+        types[name] = name;
     }
 
     if (typeof Object.freeze === "function") {