feat(typescript): allow function to supply TS-aware rules (#1485)

Author: brettz9

.README/README.md

@@ -41,14 +41,24 @@ export default [
 ];
 ```
 
-Or with settings supplied:
+Or with TypeScript-aware extra rules and settings supplied:
 
 ```js
 import {jsdoc} from 'eslint-plugin-jsdoc';
 
 export default [
   jsdoc({
     config: 'flat/recommended',
+    rules: {
+      'jsdoc/check-values': [
+        'error',
+        {
+          allowedLicenses: [
+            'MIT', 'ISC',
+          ],
+        },
+      ],
+    },
     // Uncomment this if you wish your `settings` to overwrite the config's own settings;
     //   otherwise, the default behavior is to merge recursively
     // mergeSettings: false,

README.md

@@ -60,14 +60,24 @@ export default [
 ];
 ```
 
-Or with settings supplied:
+Or with TypeScript-aware extra rules and settings supplied:
 
 ```js
 import {jsdoc} from 'eslint-plugin-jsdoc';
 
 export default [
   jsdoc({
     config: 'flat/recommended',
+    rules: {
+      'jsdoc/check-values': [
+        'error',
+        {
+          allowedLicenses: [
+            'MIT', 'ISC',
+          ],
+        },
+      ],
+    },
     // Uncomment this if you wish your `settings` to overwrite the config's own settings;
     //   otherwise, the default behavior is to merge recursively
     // mergeSettings: false,

package.json

@@ -58,6 +58,7 @@
     "husky": "^9.1.7",
     "jsdoc-type-pratt-parser": "^5.1.1",
     "json-schema": "^0.4.0",
+    "json-schema-to-typescript": "^15.0.4",
     "lint-staged": "^16.1.6",
     "mocha": "^11.7.2",
     "open-editor": "^5.1.0",
@@ -141,6 +142,7 @@
     "package-lock.json": "pnpm run install-offline"
   },
   "scripts": {
+    "ruleTypes": "node ./src/bin/generateRuleTypes.js",
     "tsc": "tsc",
     "tsc-build": "tsc -p tsconfig-prod.json",
     "build": "node ./src/bin/buildEntryFileForTS.js && rimraf ./dist && NODE_ENV=production babel ./src --out-file-extension .cjs --out-dir ./dist --copy-files --source-maps --ignore ./src/bin/*.js --no-copy-ignored && replace 'require\\(\"\\.(.*?)\\.[^.]*?\"\\)' 'require(\".$1.cjs\")' 'dist' -r --include=\"*.cjs\" && pnpm tsc-build",

pnpm-lock.yaml

@@ -0,0 +1,37 @@
+import index from '../index.js';
+import {
+  compile,
+} from 'json-schema-to-typescript';
+import {
+  writeFile,
+} from 'node:fs/promises';
+
+let str = 'export interface Rules {\n';
+
+for (const [
+  ruleName,
+  rule,
+] of Object.entries(index.rules)) {
+  if (rule.meta?.schema?.[0]) {
+    str += `  "jsdoc/${ruleName}": `;
+    const ts = await compile({
+      items: rule.meta.schema,
+      type: 'array',
+    }, 'Test', {
+      bannerComment: '',
+    });
+
+    str += ts
+      .replace(/^export type Test = ?/v, '')
+      .replace(/^export interface Test /v, '')
+      .replaceAll('\n', '\n  ').trimEnd().replace(/;$/v, '') +
+        ';\n\n';
+  }
+}
+
+str = str.replace(/\n$/v, '') + '}\n';
+
+await writeFile(import.meta.dirname + '/../rules.d.ts', str);
+
+// eslint-disable-next-line no-console -- Todo
+console.log('str', str);

src/bin/generateRuleTypes.js

@@ -16,7 +16,8 @@ export default index;
  *   cfg?: {
  *     mergeSettings?: boolean,
  *     config?: `flat/${import('./index-cjs.js').ConfigGroups}${import('./index-cjs.js').ConfigVariants}${import('./index-cjs.js').ErrorLevelVariants}`,
- *     settings?: Partial<import('./iterateJsdoc.js').Settings>
+ *     settings?: Partial<import('./iterateJsdoc.js').Settings>,
+ *     rules?: {[key in keyof import('./rules.d.ts').Rules]?: ["error"|"warn"|"off", ...import('./rules.d.ts').Rules[key]]}
  *   }
  * ) => import('eslint').Linter.Config)}
  */
@@ -39,6 +40,10 @@ export const jsdoc = function (cfg) {
     outputConfig = index.configs[cfg.config];
   }
 
+  if (cfg?.rules) {
+    outputConfig.rules = cfg.rules;
+  }
+
   outputConfig.settings = {
     jsdoc: cfg?.mergeSettings === false ?
       cfg.settings :

src/index-esm.js

@@ -539,7 +539,8 @@ export default index;
  *   cfg?: {
  *     mergeSettings?: boolean,
  *     config?: `flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}`,
- *     settings?: Partial<import('./iterateJsdoc.js').Settings>
+ *     settings?: Partial<import('./iterateJsdoc.js').Settings>,
+ *     rules?: {[key in keyof import('./rules.d.ts').Rules]?: ["error"|"warn"|"off", ...import('./rules.d.ts').Rules[key]]}
  *   }
  * ) => import('eslint').Linter.Config)}
  */
@@ -562,6 +563,10 @@ export const jsdoc = function (cfg) {
     outputConfig = index.configs[cfg.config];
   }
 
+  if (cfg?.rules) {
+    outputConfig.rules = cfg.rules;
+  }
+
   outputConfig.settings = {
     jsdoc: cfg?.mergeSettings === false ?
       cfg.settings :

src/index.js

@@ -529,7 +529,8 @@ const getTagNamesForMode = (mode, context) => {
     case 'permissive':
       return closureTags;
     case 'jsdoc':
-      return jsdocTags; case 'typescript':
+      return jsdocTags;
+    case 'typescript':
       return typeScriptTags;
     default:
       if (!modeWarnSettings.hasBeenWarned(context, 'mode')) {