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')) {