Merge branch 'main' into ci/perms

Author: Fdawgs

.README/rules/text-escaping.md

@@ -10,6 +10,8 @@ Markdown and you therefore do not wish for it to be accidentally interpreted
 as such by the likes of Visual Studio Code or if you wish to view it escaped
 within it or your documentation.
 
+`@example` tag content will not be checked.
+
 ## Fixer
 
 (TODO)

docs/rules/empty-tags.md

@@ -216,5 +216,10 @@ function quux () {
  * @returns {string[]} The array of nodes.
  */
 function quux () {}
+
+/** Application boot function.
+  @async
+  @private **/
+function quux () {}
 ````
 

docs/rules/no-undefined-types.md

@@ -807,6 +807,15 @@ function quux(foo) {
 
 quux(0);
 
+function quux() {
+  const foo = 1;
+  /** {@link foo} */
+  const bar = foo;
+  console.log(bar);
+}
+
+quux();
+
 /**
  * @import BadImportIgnoredByThisRule
  */

docs/rules/text-escaping.md

@@ -19,6 +19,8 @@ Markdown and you therefore do not wish for it to be accidentally interpreted
 as such by the likes of Visual Studio Code or if you wish to view it escaped
 within it or your documentation.
 
+`@example` tag content will not be checked.
+
 <a name="user-content-text-escaping-fixer"></a>
 <a name="text-escaping-fixer"></a>
 ## Fixer
@@ -175,5 +177,21 @@ The following patterns are not considered problems:
  * to escape
  */
 // "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+
+/**
+ * @example
+ * ```
+ * Some things to escape: <a> and &gt; and &#xabc; and `test`
+ * ```
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+
+/**
+ * @example
+ * ```
+ * Some things to escape: <a> and &gt; and &#xabc; and `test`
+ * ```
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeMarkdown":true}]
 ````
 

src/bin/generateDocs.js

@@ -202,6 +202,9 @@ const getDocPaths = () => {
       // Will get path separately below
       return null;
     }
+    if (docFile === '.DS_Store') {
+      return null;
+    }
 
     const innerBasePath = path.join(basePath, docFile);
     const writeInnerBasePath = path.join(writeBasePath, docFile);

src/index.js

@@ -59,7 +59,7 @@ import validTypes from './rules/validTypes.js';
 import { getJsdocProcessorPlugin } from './getJsdocProcessorPlugin.js';
 
 /**
- * @typedef {"recommended" | "stylistic" | "contents" | "logical"} ConfigGroups
+ * @typedef {"recommended" | "stylistic" | "contents" | "logical" | "requirements"} ConfigGroups
  * @typedef {"" | "-typescript" | "-typescript-flavor"} ConfigVariants
  * @typedef {"" | "-error"} ErrorLevelVariants
  * @type {import('eslint').ESLint.Plugin & {

src/rules/emptyTags.js

@@ -42,9 +42,12 @@ export default iterateJsdoc(({
       settings.mode !== 'closure' && emptyIfNotClosure.has(tagName);
   });
 
-  for (const tag of emptyTags) {
+  for (const [key, tag] of emptyTags.entries()) {
     const content = tag.name || tag.description || tag.type;
-    if (content.trim()) {
+    if (content.trim() && (
+      // Allow for JSDoc-block final asterisks
+      key !== emptyTags.length - 1 || !(/^\s*\*+$/u).test(content)
+    )) {
       const fix = () => {
         // By time of call in fixer, `tag` will have `line` added
         utils.setTag(

src/rules/noUndefinedTypes.js

@@ -222,6 +222,21 @@ export default iterateJsdoc(({
   //  Program scope inside
   const cjsOrESMScope = globalScope.childScopes[0]?.block?.type === 'Program';
 
+  /**
+   * @param {import("eslint").Scope.Scope | null} scope
+   * @returns {Set<string>}
+   */
+  const getValidRuntimeIdentifiers = (scope) => {
+    const result = new Set()
+    while (scope) {
+      for (const {name} of scope.variables) {
+        result.add(name)
+      }
+      scope = scope.upper
+    }
+    return result
+  };
+
   const allDefinedTypes = new Set(globalScope.variables.map(({
     name,
   }) => {
@@ -247,6 +262,7 @@ export default iterateJsdoc(({
     .concat(importTags)
     .concat(definedTypes)
     .concat(/** @type {string[]} */ (definedPreferredTypes))
+    .concat(...getValidRuntimeIdentifiers(node && sourceCode.getScope(node)))
     .concat(
       settings.mode === 'jsdoc' ?
         [] :

src/rules/textEscaping.js

@@ -73,6 +73,9 @@ export default iterateJsdoc(({
     }
 
     for (const tag of jsdoc.tags) {
+      if (tag.tag === 'example') {
+        continue;
+      }
       if (/** @type {string[]} */ (
         utils.getTagDescription(tag, true)
       ).some((desc) => {
@@ -100,6 +103,9 @@ export default iterateJsdoc(({
   }
 
   for (const tag of jsdoc.tags) {
+    if (tag.tag === 'example') {
+      continue;
+    }
     if (/** @type {string[]} */ (
       utils.getTagDescription(tag, true)
     ).some((desc) => {

test/rules/assertions/emptyTags.js

@@ -308,5 +308,13 @@ export default /** @type {import('../index.js').TestCases} */ ({
       function quux () {}
       `,
     },
+    {
+      code: `
+      /** Application boot function.
+        @async
+        @private **/
+      function quux () {}
+      `,
+    },
   ],
 });

test/rules/assertions/noUndefinedTypes.js

@@ -1482,6 +1482,18 @@ export default /** @type {import('../index.js').TestCases} */ ({
         'no-unused-vars': 'error',
       },
     },
+    {
+      code: `
+          function quux() {
+            const foo = 1;
+            /** {@link foo} */
+            const bar = foo;
+            console.log(bar);
+          }
+
+          quux();
+      `,
+    },
     {
       code: `
         /**

test/rules/assertions/textEscaping.js

@@ -316,5 +316,35 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+        /**
+         * @example
+         * \`\`\`
+         * Some things to escape: <a> and &gt; and &#xabc; and \`test\`
+         * \`\`\`
+         */
+      `,
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ]
+    },
+    {
+      code: `
+        /**
+         * @example
+         * \`\`\`
+         * Some things to escape: <a> and &gt; and &#xabc; and \`test\`
+         * \`\`\`
+         */
+      `,
+      options: [
+        {
+          escapeMarkdown: true,
+        },
+      ]
+    },
   ],
 });