feat(getJsdocProcessorPlugin): add allowedLanguagesToProcess option (#1392)

* feat(`getJsdocProcessorPlugin`): add `allowedLanguagesToProcess` option

* Update src/getJsdocProcessorPlugin.js

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update src/getJsdocProcessorPlugin.js

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: brettz9

.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"`.

docs/processors.md

@@ -160,6 +160,18 @@ same name.
 See the [`check-examples`](./rules/check-examples.md#readme) option of the
 same name.
 
+<a name="user-content-processors-options-allowedlanguagestoprocess"></a>
+<a name="processors-options-allowedlanguagestoprocess"></a>
+#### <code>allowedLanguagesToProcess</code>
+
+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']`.
+
 <a name="user-content-processors-options-sourcetype"></a>
 <a name="processors-options-sourcetype"></a>
 #### <code>sourceType</code>

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
  * ```

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,16 @@ export const getJsdocProcessorPlugin = (options = {}) => {
         return;
       }
 
+      // If `allowedLanguagesToProcess` is falsy, all languages should be processed.
+      if (allowedLanguagesToProcess) {
+        const matches = (/^\s*```(?<language>\S+)([\s\S]*)```\s*$/u).exec(source);
+        if (matches?.groups && !allowedLanguagesToProcess.includes(
+          matches.groups.language.toLowerCase(),
+        )) {
+          return;
+        }
+      }
+
       const sources = [];
       let skipInit = false;
       if (exampleCodeRegex) {

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,
+    });
+  });
 });