refactor: fix generateRule.js

Also:
- refactor: TypeScript for `checkJs`

Author: brettz9

.eslintrc.json

@@ -37,6 +37,8 @@
     "unicorn/no-unsafe-regex": 0,
     "unicorn/prefer-array-some": 0,
     "unicorn/prevent-abbreviations": 0,
-    "linebreak-style": 0
+    "linebreak-style": 0,
+    "no-inline-comments": 0,
+    "no-extra-parens": 0
   }
 }

.husky/pre-push

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-npm test && npm run build && npm run check-readme
+npm test && npm run build && npm run check-docs

CONTRIBUTING.md

@@ -42,7 +42,7 @@ modify files within the `.README` directory. `.README/README.md` contains the
 main README skeleton and details on the project, its global `settings`, etc.,
 while the documentation for specific rules (that will be pulled into the
 README) ought to be modified within the relevant file within `.README/rules`.
-Once these files are modified, you can run `pnpm create-readme` to have
+Once these files are modified, you can run `pnpm create-docs` to have
 these files integrated into the main `/README.md`. While you should include
 the built file in your PR, you will not want to make manual changes
 directly to this file, as they will be overwritten.

package.json

@@ -29,15 +29,17 @@
     "@semantic-release/commit-analyzer": "^9.0.2",
     "@semantic-release/github": "^8.0.7",
     "@semantic-release/npm": "^10.0.3",
+    "@types/eslint": "^8.37.0",
+    "@types/node": "^20.1.1",
     "@typescript-eslint/parser": "^5.59.2",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^6.1.1",
     "camelcase": "^6.3.0",
     "chai": "^4.3.7",
     "cross-env": "^7.0.3",
     "decamelize": "^5.0.1",
-    "eslint-config-canonical": "~33.0.1",
     "eslint": "^8.39.0",
+    "eslint-config-canonical": "~33.0.1",
     "gitdown": "^3.1.5",
     "glob": "^10.2.2",
     "husky": "^8.0.3",
@@ -107,9 +109,10 @@
     "package-lock.json": "npm run install-offline"
   },
   "scripts": {
+    "tsc": "tsc",
     "build": "rimraf ./dist && cross-env NODE_ENV=production babel ./src --out-dir ./dist --copy-files --source-maps --ignore ./src/bin/*.js --no-copy-ignored",
-    "check-readme": "babel-node ./src/bin/generateDocs.js --check",
-    "create-readme": "babel-node ./src/bin/generateDocs.js",
+    "check-docs": "babel-node ./src/bin/generateDocs.js --check",
+    "create-docs": "babel-node ./src/bin/generateDocs.js",
     "create-rule": "babel-node ./src/bin/generateRule.js",
     "install-offline": "pnpm install --prefer-offline --no-audit",
     "lint": "npm run lint-arg -- .",

pnpm-lock.yaml

@@ -6,20 +6,28 @@ const WarnSettings = function () {
     /**
      * Warn only once for each context and setting
      *
-     * @param {object} context
+     * @param {import('eslint').Rule.RuleContext} context
      * @param {string} setting
+     * @returns {boolean}
      */
     hasBeenWarned (context, setting) {
-      return warnedSettings.has(context) && warnedSettings.get(context).has(setting);
+      return warnedSettings.has(context) && /** @type {Set<string>} */ (
+        warnedSettings.get(context)
+      ).has(setting);
     },
 
+    /**
+     * @param {import('eslint').Rule.RuleContext} context
+     * @param {string} setting
+     * @returns {void}
+     */
     markSettingAsWarned (context, setting) {
       // istanbul ignore else
       if (!warnedSettings.has(context)) {
         warnedSettings.set(context, new Set());
       }
 
-      warnedSettings.get(context).add(setting);
+      /** @type {Set<string>} */ (warnedSettings.get(context)).add(setting);
     },
   };
 };

src/WarnSettings.js

@@ -9,6 +9,10 @@ import {
   glob,
 } from 'glob';
 
+/**
+ * @param {string} code
+ * @returns {string}
+ */
 const trimCode = (code) => {
   let lines = code.replace(/^\n/u, '').trimEnd().split('\n');
 
@@ -29,6 +33,11 @@ const trimCode = (code) => {
   return lines.join('\n').replaceAll('\r', '\\r');
 };
 
+/**
+ * @param {import('eslint').RuleTester.InvalidTestCase|import('eslint').RuleTester.ValidTestCase} setup
+ * @param {string} ruleName
+ * @returns {string}
+ */
 const formatCodeSnippet = (setup, ruleName) => {
   const paragraphs = [];
 
@@ -42,8 +51,11 @@ const formatCodeSnippet = (setup, ruleName) => {
     paragraphs.push(`// "jsdoc/${ruleName}": ["error"|"warn", ${JSON.stringify(setup.options).slice(1)}`);
   }
 
-  if (setup.errors) {
-    paragraphs.push(`// Message: ${setup.errors[0].message}`);
+  if ('errors' in setup) {
+    paragraphs.push(`// Message: ${
+      /** @type {Array<import('eslint').RuleTester.TestCaseError>} */ (
+        setup.errors
+      )[0].message}`);
   }
 
   return paragraphs.join('\n');
@@ -58,9 +70,14 @@ const getAssertions = async () => {
     return path.basename(filePath, '.js');
   });
 
-  const assertionCodes = assertionFiles.map((filePath, idx) => {
-    // eslint-disable-next-line import/no-dynamic-require
-    const codes = require(filePath);
+  const assertionCodes = await Promise.all(assertionFiles.map(async (filePath, idx) => {
+    /**
+     * @type {{
+     *   invalid: (import('eslint').RuleTester.InvalidTestCase & {ignoreReadme?: true})[],
+     *   valid: (import('eslint').RuleTester.ValidTestCase & {ignoreReadme?: true})[]
+     * }}
+     */
+    const codes = await import(filePath);
 
     const ruleName = decamelize(assertionNames[idx], {
       separator: '-',
@@ -82,7 +99,7 @@ const getAssertions = async () => {
         return formatCodeSnippet(setup, ruleName);
       }),
     };
-  });
+  }));
 
   return {
     assertionNames,
@@ -145,7 +162,13 @@ const generateDocs = async () => {
   return docContents.map((docContent) => {
     return docContent.replace(
       /<!-- assertions-(passing|failing) ([a-z]+?) -->/gui,
-      (assertionsBlock, passingFailing, ruleName) => {
+      /**
+       * @param {string} _assertionsBlock
+       * @param {string} passingFailing
+       * @param {string} ruleName
+       * @returns {string}
+       */
+      (_assertionsBlock, passingFailing, ruleName) => {
         const ruleAssertions = assertions[ruleName];
 
         if (!ruleAssertions) {
@@ -164,10 +187,13 @@ const generateDocs = async () => {
   });
 };
 
+/**
+ * @returns {string[]}
+ */
 const getDocPaths = () => {
   const basePath = path.join(__dirname, '..', '..', '.README');
   const writeBasePath = path.join(__dirname, '..', '..', 'docs');
-  const docPaths = fs.readdirSync(basePath).flatMap((docFile) => {
+  const docPaths = /** @type {string[]} */ (fs.readdirSync(basePath).flatMap((docFile) => {
     if (extraFiles.includes(docFile)) {
       // Will get path separately below
       return null;
@@ -190,7 +216,7 @@ const getDocPaths = () => {
     return null;
   }).filter((file) => {
     return file;
-  });
+  }));
 
   return [
     ...docPaths,
@@ -232,7 +258,7 @@ const assertDocsAreUpToDate = async () => {
     const isUpToDate = fs.readFileSync(docPath, 'utf8') === docContent;
 
     if (!isUpToDate) {
-      throw new Error('Readme is not up to date, please run `npm run create-readme` to update it.');
+      throw new Error('Readme is not up to date, please run `npm run create-docs` to update it.');
     }
   }
 };