From 0da7941ffbb203df6ce0374483779c4322327f2e Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Sun, 1 Jun 2025 12:21:58 +0800 Subject: [PATCH 1/3] feat(`getJsdocProcessorPlugin`): add `allowedLanguagesToProcess` option --- .README/processors.md | 10 +++++ docs/processors.md | 12 ++++++ src/bin/generateRule.js | 2 +- src/getJsdocProcessorPlugin.js | 15 ++++++- test/getJsdocProcessPlugin.js | 74 ++++++++++++++++++++++++++++++++++ 5 files changed, 110 insertions(+), 3 deletions(-) diff --git a/.README/processors.md b/.README/processors.md index 75f9b7c5..cd375782 100644 --- a/.README/processors.md +++ b/.README/processors.md @@ -134,6 +134,16 @@ same name. See the [`check-examples`](./rules/check-examples.md#readme) option of the same name. +#### `allowedLanguagesToProcess` + +This is an array which will narrow the allowable languages of fenced blocks +down to those within the array. + +Set to `false` to ensure all present languages (not excluded by +any `exampleCodeRegex` and `rejectExampleCodeRegex` options) will be processed. + +Defaults to `['js', 'ts', 'javascript', 'typescript']`. + #### `sourceType` Whether to use "script" or "module" with the parser. Defaults to `"module"`. diff --git a/docs/processors.md b/docs/processors.md index d7863e5d..af7f0681 100644 --- a/docs/processors.md +++ b/docs/processors.md @@ -160,6 +160,18 @@ same name. See the [`check-examples`](./rules/check-examples.md#readme) option of the same name. + + +#### allowedLanguagesToProcess + +This is an array which will narrow the allowable languages of fenced blocks +down to those within the array. + +Set to `false` to ensure all present languages (not excluded by +any `exampleCodeRegex` and `rejectExampleCodeRegex` options) will be processed. + +Defaults to `['js', 'ts', 'javascript', 'typescript']`. + #### sourceType diff --git a/src/bin/generateRule.js b/src/bin/generateRule.js index 1db383ca..3de87b40 100644 --- a/src/bin/generateRule.js +++ b/src/bin/generateRule.js @@ -6,7 +6,7 @@ import { } from 'fs'; import fs from 'fs/promises'; /** - * + * @example * ```shell * npm run create-rule my-new-rule -- --recommended * ``` diff --git a/src/getJsdocProcessorPlugin.js b/src/getJsdocProcessorPlugin.js index 1fbe9533..9adf1854 100644 --- a/src/getJsdocProcessorPlugin.js +++ b/src/getJsdocProcessorPlugin.js @@ -1,5 +1,3 @@ -// Todo: Support TS by fenced block type - import { forEachPreferredTag, getPreferredTagName, @@ -94,6 +92,7 @@ const getLinesCols = (text) => { * @property {string} [matchingFileNameProperties] See docs * @property {string} [exampleCodeRegex] See docs * @property {string} [rejectExampleCodeRegex] See docs + * @property {string[]} [allowedLanguagesToProcess] See docs * @property {"script"|"module"} [sourceType] See docs * @property {import('eslint').Linter.ESTreeParser|import('eslint').Linter.NonESTreeParser} [parser] See docs */ @@ -105,6 +104,9 @@ const getLinesCols = (text) => { */ export const getJsdocProcessorPlugin = (options = {}) => { const { + allowedLanguagesToProcess = [ + 'js', 'ts', 'javascript', 'typescript', + ], captionRequired = false, checkDefaults = false, checkExamples = true, @@ -374,6 +376,15 @@ export const getJsdocProcessorPlugin = (options = {}) => { return; } + if (allowedLanguagesToProcess) { + const matches = (/^\s*```(?\S+)([\s\S]*)```\s*$/u).exec(source); + if (matches?.groups && !allowedLanguagesToProcess.includes( + matches.groups.language, + )) { + return; + } + } + const sources = []; let skipInit = false; if (exampleCodeRegex) { diff --git a/test/getJsdocProcessPlugin.js b/test/getJsdocProcessPlugin.js index bbd0d5a5..ad2d0459 100644 --- a/test/getJsdocProcessPlugin.js +++ b/test/getJsdocProcessPlugin.js @@ -749,4 +749,78 @@ describe('`getJsdocProcessorPlugin`', () => { text, }); }); + + it('ignores language not present in default `allowedLanguagesToProcess`', () => { + const options = {}; + const filename = 'something.js'; + const text = ` + /** + * @example + * \`\`\`shell + * node doSth.js + * \`\`\` + */ + function doSth () {} + `; + check({ + filename, + options, + result: [ + text, + ], + text, + }); + }); + + it('ignores language not present in supplied `allowedLanguagesToProcess`', () => { + const options = { + allowedLanguagesToProcess: [ + 'javascript', + ], + }; + const filename = 'something.js'; + const text = ` + /** + * @example + * \`\`\`js + * doSth(); + * \`\`\` + */ + function doSth () {} + `; + check({ + filename, + options, + result: [ + text, + ], + text, + }); + }); + + it('checks language present in default `allowedLanguagesToProcess`', () => { + const options = {}; + const filename = 'something.js'; + const text = ` + /** + * @example + * \`\`\`js + * doSth(); + * \`\`\` + */ + function doSth () {} + `; + check({ + filename, + options, + result: [ + text, + { + filename: 'something.md/*.js', + text: '\n```js\ndoSth();\n```', + }, + ], + text, + }); + }); }); From 5edefd23681ba22c2fc6beca3137629614340e87 Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Sun, 1 Jun 2025 12:27:34 +0800 Subject: [PATCH 2/3] Update src/getJsdocProcessorPlugin.js Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/getJsdocProcessorPlugin.js | 1 + 1 file changed, 1 insertion(+) diff --git a/src/getJsdocProcessorPlugin.js b/src/getJsdocProcessorPlugin.js index 9adf1854..631d04c0 100644 --- a/src/getJsdocProcessorPlugin.js +++ b/src/getJsdocProcessorPlugin.js @@ -376,6 +376,7 @@ export const getJsdocProcessorPlugin = (options = {}) => { return; } + // If `allowedLanguagesToProcess` is falsy, all languages should be processed. if (allowedLanguagesToProcess) { const matches = (/^\s*```(?\S+)([\s\S]*)```\s*$/u).exec(source); if (matches?.groups && !allowedLanguagesToProcess.includes( From 117ed91dca2a763cd8af26163d9c41cb9004e8a6 Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Sun, 1 Jun 2025 12:28:17 +0800 Subject: [PATCH 3/3] Update src/getJsdocProcessorPlugin.js Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/getJsdocProcessorPlugin.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/getJsdocProcessorPlugin.js b/src/getJsdocProcessorPlugin.js index 631d04c0..96958577 100644 --- a/src/getJsdocProcessorPlugin.js +++ b/src/getJsdocProcessorPlugin.js @@ -380,7 +380,7 @@ export const getJsdocProcessorPlugin = (options = {}) => { if (allowedLanguagesToProcess) { const matches = (/^\s*```(?\S+)([\s\S]*)```\s*$/u).exec(source); if (matches?.groups && !allowedLanguagesToProcess.includes( - matches.groups.language, + matches.groups.language.toLowerCase(), )) { return; }