feat: validate type comments and generate .d.ts (take 2) (#251)

Author: ota-meshi

.eslintignore

@@ -3,6 +3,7 @@
 /node_modules
 /index.*
 /test.*
+/dist
 
 !.vitepress
 /docs/.vitepress/dist

.gitignore

@@ -5,3 +5,4 @@
 /node_modules
 /index.*
 /test.*
+/dist

.knip.jsonc

@@ -1,4 +1,5 @@
 {
     "$schema": "https://unpkg.com/knip@5/schema.json",
+    "entry": ["src/index.mjs", "test/**/*.mjs"],
     "ignore": ["./docs/.vitepress/**/*"]
 }

.npmrc

@@ -1 +1,2 @@
 package-lock = false
+force = true

.vscode/settings.json

@@ -4,6 +4,11 @@
         "editor.formatOnSave": true,
         "editor.codeActionsOnSave": ["source.organizeImports", "source.fixAll"]
     },
+    "[typescript]": {
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": ["source.organizeImports", "source.fixAll"]
+    },
     "[json]": {
         "editor.defaultFormatter": "esbenp.prettier-vscode",
         "editor.formatOnSave": true,

package.json

@@ -30,8 +30,10 @@
     ],
     "scripts": {
         "prebuild": "npm run -s clean",
-        "build": "rollup -c",
-        "clean": "rimraf .nyc_output coverage index.*",
+        "build": "npm run build:dts && npm run build:rollup",
+        "build:dts": "tsc -p tsconfig.build.json",
+        "build:rollup": "rollup -c",
+        "clean": "rimraf .nyc_output coverage index.* dist",
         "coverage": "opener ./coverage/lcov-report/index.html",
         "docs:build": "vitepress build docs",
         "docs:watch": "vitepress dev docs",
@@ -40,7 +42,7 @@
         "format:check": "npm run -s format:prettier -- --check",
         "lint:eslint": "eslint .",
         "lint:format": "npm run -s format:check",
-        "lint:installed-check": "installed-check -v -i installed-check -i npm-run-all2 -i knip",
+        "lint:installed-check": "installed-check -v -i installed-check -i npm-run-all2 -i knip -i rollup-plugin-dts",
         "lint:knip": "knip",
         "lint": "run-p lint:*",
         "test": "c8 mocha --reporter dot \"test/*.mjs\"",
@@ -54,6 +56,8 @@
     },
     "devDependencies": {
         "@eslint-community/eslint-plugin-mysticatea": "^15.6.1",
+        "@types/eslint": "^9.6.1",
+        "@types/estree": "^1.0.7",
         "c8": "^8.0.1",
         "dot-prop": "^7.2.0",
         "eslint": "^8.57.1",
@@ -65,8 +69,10 @@
         "prettier": "2.8.8",
         "rimraf": "^3.0.2",
         "rollup": "^2.79.2",
+        "rollup-plugin-dts": "^4.2.3",
         "rollup-plugin-sourcemaps": "^0.6.3",
         "semver": "^7.6.3",
+        "typescript": "^4.9.5",
         "vitepress": "^1.4.1",
         "warun": "^1.0.0"
     },

rollup.config.js

@@ -2,26 +2,54 @@
  * @author Toru Nagashima
  * See LICENSE file in root directory for full license.
  */
+import fs from "fs"
+import path from "path"
+import dts from "rollup-plugin-dts"
 import sourcemaps from "rollup-plugin-sourcemaps"
 import packageInfo from "./package.json"
 
 /**
  * Define the output configuration.
  * @param {string} ext The extension for generated files.
- * @returns {object} The output configuration
+ * @returns {object[]} The output configuration
  */
 function config(ext) {
-    return {
-        input: "src/index.mjs",
-        output: {
-            exports: ext === ".mjs" ? undefined : "named",
-            file: `index${ext}`,
-            format: ext === ".mjs" ? "es" : "cjs",
-            sourcemap: true,
+    return [
+        {
+            input: "src/index.mjs",
+            output: {
+                exports: ext === ".mjs" ? undefined : "named",
+                file: `index${ext}`,
+                format: ext === ".mjs" ? "es" : "cjs",
+                sourcemap: true,
+            },
+            plugins: [sourcemaps()],
+            external: Object.keys(packageInfo.dependencies),
         },
-        plugins: [sourcemaps()],
-        external: Object.keys(packageInfo.dependencies),
+        {
+            input: "./dist/index.d.ts",
+            output: {
+                exports: "named",
+                file: `index.d${ext.replace(/js$/u, "ts")}`,
+                format: "es",
+            },
+            plugins: [dts()],
+        },
+    ]
+}
+
+/* eslint-disable @eslint-community/mysticatea/node/no-sync */
+// Replace extension `.mts` to `.ts` in the `dist/*.d.mts` file name.
+// This is needed because rollup-plugin-dts<=v4 doesn't support `.mts` extension.
+for (const file of fs.readdirSync(path.resolve("dist"))) {
+    if (file.endsWith(".d.mts")) {
+        const content = fs.readFileSync(path.resolve("dist", file), "utf8")
+        const newContent = content.replace(/\.mjs(['"])/gu, ".js$1")
+        const newName = file.replace(/\.d\.mts$/u, ".d.ts")
+        fs.writeFileSync(path.resolve("dist", newName), newContent, "utf8")
+        fs.unlinkSync(path.resolve("dist", file))
     }
 }
+/* eslint-enable @eslint-community/mysticatea/node/no-sync */
 
-export default [config(".js"), config(".mjs")]
+export default [...config(".js"), ...config(".mjs")]

src/find-variable.mjs

@@ -1,13 +1,17 @@
 import { getInnermostScope } from "./get-innermost-scope.mjs"
+/** @typedef {import("eslint").Scope.Scope} Scope */
+/** @typedef {import("eslint").Scope.Variable} Variable */
+/** @typedef {import("estree").Identifier} Identifier */
 
 /**
  * Find the variable of a given name.
  * @param {Scope} initialScope The scope to start finding.
- * @param {string|Node} nameOrNode The variable name to find. If this is a Node object then it should be an Identifier node.
+ * @param {string|Identifier} nameOrNode The variable name to find. If this is a Node object then it should be an Identifier node.
  * @returns {Variable|null} The found variable or null.
  */
 export function findVariable(initialScope, nameOrNode) {
     let name = ""
+    /** @type {Scope|null} */
     let scope = initialScope
 
     if (typeof nameOrNode === "string") {

src/get-function-head-location.mjs

@@ -1,30 +1,47 @@
 import { isArrowToken, isOpeningParenToken } from "./token-predicate.mjs"
+/** @typedef {import("eslint").Rule.Node} RuleNode */
+/** @typedef {import("eslint").SourceCode} SourceCode */
+/** @typedef {import("eslint").AST.Token} Token */
+/** @typedef {import("estree").Function} FunctionNode */
+/** @typedef {import("estree").FunctionDeclaration} FunctionDeclaration */
+/** @typedef {import("estree").FunctionExpression} FunctionExpression */
+/** @typedef {import("estree").SourceLocation} SourceLocation */
+/** @typedef {import("estree").Position} Position */
 
 /**
  * Get the `(` token of the given function node.
- * @param {Node} node - The function node to get.
+ * @param {FunctionExpression | FunctionDeclaration} node - The function node to get.
  * @param {SourceCode} sourceCode - The source code object to get tokens.
  * @returns {Token} `(` token.
  */
 function getOpeningParenOfParams(node, sourceCode) {
     return node.id
-        ? sourceCode.getTokenAfter(node.id, isOpeningParenToken)
-        : sourceCode.getFirstToken(node, isOpeningParenToken)
+        ? /** @type {Token} */ (
+              sourceCode.getTokenAfter(node.id, isOpeningParenToken)
+          )
+        : /** @type {Token} */ (
+              sourceCode.getFirstToken(node, isOpeningParenToken)
+          )
 }
 
 /**
  * Get the location of the given function node for reporting.
- * @param {Node} node - The function node to get.
+ * @param {FunctionNode} node - The function node to get.
  * @param {SourceCode} sourceCode - The source code object to get tokens.
- * @returns {string} The location of the function node for reporting.
+ * @returns {SourceLocation|null} The location of the function node for reporting.
  */
 export function getFunctionHeadLocation(node, sourceCode) {
-    const parent = node.parent
+    const parent = /** @type {RuleNode} */ (node).parent
+
+    /** @type {Position|null} */
     let start = null
+    /** @type {Position|null} */
     let end = null
 
     if (node.type === "ArrowFunctionExpression") {
-        const arrowToken = sourceCode.getTokenBefore(node.body, isArrowToken)
+        const arrowToken = /** @type {Token} */ (
+            sourceCode.getTokenBefore(node.body, isArrowToken)
+        )
 
         start = arrowToken.loc.start
         end = arrowToken.loc.end
@@ -33,11 +50,11 @@ export function getFunctionHeadLocation(node, sourceCode) {
         parent.type === "MethodDefinition" ||
         parent.type === "PropertyDefinition"
     ) {
-        start = parent.loc.start
-        end = getOpeningParenOfParams(node, sourceCode).loc.start
+        start = /** @type {SourceLocation} */ (parent.loc).start
+        end = getOpeningParenOfParams(node, sourceCode)?.loc.start
     } else {
-        start = node.loc.start
-        end = getOpeningParenOfParams(node, sourceCode).loc.start
+        start = /** @type {SourceLocation} */ (node.loc).start
+        end = getOpeningParenOfParams(node, sourceCode)?.loc.start
     }
 
     return {

src/get-function-name-with-kind.mjs

@@ -1,14 +1,20 @@
 import { getPropertyName } from "./get-property-name.mjs"
+/** @typedef {import("eslint").Rule.Node} RuleNode */
+/** @typedef {import("eslint").SourceCode} SourceCode */
+/** @typedef {import("estree").Function} FunctionNode */
+/** @typedef {import("estree").FunctionDeclaration} FunctionDeclaration */
+/** @typedef {import("estree").FunctionExpression} FunctionExpression */
+/** @typedef {import("estree").Identifier} Identifier */
 
 /**
  * Get the name and kind of the given function node.
- * @param {ASTNode} node - The function node to get.
+ * @param {FunctionNode} node - The function node to get.
  * @param {SourceCode} [sourceCode] The source code object to get the code of computed property keys.
  * @returns {string} The name and kind of the function node.
  */
 // eslint-disable-next-line complexity
 export function getFunctionNameWithKind(node, sourceCode) {
-    const parent = node.parent
+    const parent = /** @type {RuleNode} */ (node).parent
     const tokens = []
     const isObjectMethod = parent.type === "Property" && parent.value === node
     const isClassMethod =
@@ -68,7 +74,7 @@ export function getFunctionNameWithKind(node, sourceCode) {
                 }
             }
         }
-    } else if (node.id) {
+    } else if (hasId(node)) {
         tokens.push(`'${node.id.name}'`)
     } else if (
         parent.type === "VariableDeclarator" &&
@@ -92,3 +98,14 @@ export function getFunctionNameWithKind(node, sourceCode) {
 
     return tokens.join(" ")
 }
+
+/**
+ * @param {FunctionNode} node
+ * @returns {node is FunctionDeclaration | FunctionExpression & { id: Identifier }}
+ */
+function hasId(node) {
+    return Boolean(
+        /** @type {Partial<FunctionDeclaration | FunctionExpression>} */ (node)
+            .id,
+    )
+}

src/get-innermost-scope.mjs

@@ -1,18 +1,23 @@
+/** @typedef {import("eslint").Scope.Scope} Scope */
+/** @typedef {import("estree").Node} Node */
+
 /**
  * Get the innermost scope which contains a given location.
  * @param {Scope} initialScope The initial scope to search.
  * @param {Node} node The location to search.
  * @returns {Scope} The innermost scope.
  */
 export function getInnermostScope(initialScope, node) {
-    const location = node.range[0]
+    const location = /** @type {[number, number]} */ (node.range)[0]
 
     let scope = initialScope
     let found = false
     do {
         found = false
         for (const childScope of scope.childScopes) {
-            const range = childScope.block.range
+            const range = /** @type {[number, number]} */ (
+                childScope.block.range
+            )
 
             if (range[0] <= location && location < range[1]) {
                 scope = childScope

src/get-property-name.mjs

@@ -1,10 +1,16 @@
 import { getStringIfConstant } from "./get-string-if-constant.mjs"
+/** @typedef {import("eslint").Scope.Scope} Scope */
+/** @typedef {import("estree").MemberExpression} MemberExpression */
+/** @typedef {import("estree").MethodDefinition} MethodDefinition */
+/** @typedef {import("estree").Property} Property */
+/** @typedef {import("estree").PropertyDefinition} PropertyDefinition */
+/** @typedef {import("estree").Identifier} Identifier */
 
 /**
  * Get the property name from a MemberExpression node or a Property node.
- * @param {Node} node The node to get.
+ * @param {MemberExpression | MethodDefinition | Property | PropertyDefinition} node The node to get.
  * @param {Scope} [initialScope] The scope to start finding variable. Optional. If the node is a computed property node and this scope was given, this checks the computed property name by the `getStringIfConstant` function with the scope, and returns the value of it.
- * @returns {string|null} The property name of the node.
+ * @returns {string|null|undefined} The property name of the node.
  */
 export function getPropertyName(node, initialScope) {
     switch (node.type) {
@@ -15,7 +21,7 @@ export function getPropertyName(node, initialScope) {
             if (node.property.type === "PrivateIdentifier") {
                 return null
             }
-            return node.property.name
+            return /** @type {Partial<Identifier>} */ (node.property).name
 
         case "Property":
         case "MethodDefinition":
@@ -29,9 +35,10 @@ export function getPropertyName(node, initialScope) {
             if (node.key.type === "PrivateIdentifier") {
                 return null
             }
-            return node.key.name
+            return /** @type {Partial<Identifier>} */ (node.key).name
 
-        // no default
+        default:
+            break
     }
 
     return null