eslint-plugin-jsdoc 63.0.13 → 63.1.0

package/dist/rules/normalizeSeeLinks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeSeeLinks.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/normalizeSeeLinks.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nconst markdownLinkRegex = /(?<!\\\\)\\[([^`\\]\\r\\n]+)\\]\\(([^`\\(\\)\\s]+)\\)/gv;\nconst prefixLinkRegex = /(?<!\\\\)\\[([^\\]\\r\\n]+)\\]\\{@link\\s+([^\\}\\s\\|]+)\\}/gv;\nconst pipeLinkRegex = /\\{@link\\s+([^\\}\\s\\|]+)\\s*\\|\\s*([^\\}\\r\\n]+)\\}/gv;\n\nconst markdownLinkAttemptRegex = /(?<!\\\\)\\[[^\\]\\r\\n]*\\]\\([^\\r\\n]*(?:\\)|$)/v;\nconst prefixLinkAttemptRegex = /(?<!\\\\)\\[[^\\]\\r\\n]*\\]\\{@link[^\\}\\r\\n]*(?:\\}|$)/v;\nconst pipeLinkAttemptRegex = /\\{@link[^\\}\\r\\n]*\\|[^\\}\\r\\n]*(?:\\}|$)/v;\n\nconst scopedPackageNameRegex = /^@[\\w.\\-]+\\/[\\w.\\-]+/v;\nconst markdownCodeSpanRegex = /(?<!\\\\)(`+)(?!`)[\\s\\S]*?(?<!`)\\1(?!`)/gv;\n\n/**\n * @param {'pipe'|'prefix'} canonicalForm\n * @param {string} label\n * @returns {boolean}\n */\nconst cannotSafelyFormatLink = (canonicalForm, label) => {\n  if (!label.trim()) {\n    return true;\n  }\n\n  if (canonicalForm === 'pipe') {\n    return label.includes('}');\n  }\n\n  return label.includes(']');\n};\n\n/**\n * @param {string} target\n * @returns {string}\n */\nconst encodeLinkTarget = (target) => {\n  return encodeURI(target).replaceAll(/%25(?=[\\dA-F]{2})/giv, '%');\n};\n\n/**\n * @param {string} description\n * @param {number} index\n * @returns {boolean}\n */\nconst isInsideMarkdownCodeSpan = (description, index) => {\n  for (const match of description.matchAll(markdownCodeSpanRegex)) {\n    const delimiterLength = match[1].length;\n    const contentStart = match.index + delimiterLength;\n    const contentEnd = match.index + match[0].length - delimiterLength;\n\n    if (index >= contentStart && index < contentEnd) {\n      return true;\n    }\n  }\n\n  return false;\n};\n\n/**\n * @param {'pipe'|'prefix'} canonicalForm\n * @param {string} label\n * @param {string} target\n * @returns {string}\n */\nconst formatLink = (canonicalForm, label, target) => {\n  const encodedTarget = encodeLinkTarget(target);\n\n  return canonicalForm === 'pipe' ?\n    `{@link ${encodedTarget}|${label.trim()}}` :\n    `[${label.trim()}]{@link ${encodedTarget}}`;\n};\n\n/**\n * @param {string} description\n * @param {'pipe'|'prefix'} canonicalForm\n * @returns {string}\n */\nconst normalizeDescription = (description, canonicalForm) => {\n  const markdownNormalized = description.replaceAll(\n    new RegExp(markdownLinkRegex, 'gv'),\n    (_match, label, target) => {\n      return formatLink(canonicalForm, label, target);\n    },\n  );\n\n  if (canonicalForm === 'pipe') {\n    return markdownNormalized.replaceAll(\n      new RegExp(prefixLinkRegex, 'gv'),\n      (_match, label, target) => {\n        return formatLink(canonicalForm, label, target);\n      },\n    );\n  }\n\n  return markdownNormalized.replaceAll(\n    new RegExp(pipeLinkRegex, 'gv'),\n    (_match, target, label) => {\n      return formatLink(canonicalForm, label, target);\n    },\n  );\n};\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  utils,\n}) => {\n  const {\n    canonicalForm = 'pipe',\n    enableFixer = true,\n  } = context.options[0] || {};\n\n  const descriptionMatcher = canonicalForm === 'pipe' ?\n    new RegExp(`${markdownLinkRegex.source}|${prefixLinkRegex.source}`, 'v') :\n    new RegExp(`${markdownLinkRegex.source}|${pipeLinkRegex.source}`, 'v');\n\n  /** @type {import('comment-parser').Spec[]} */\n  const fixableTags = [];\n\n  for (const tag of jsdoc.tags) {\n    if (tag.tag !== 'see') {\n      continue;\n    }\n\n    const firstTokens = tag.source[0].tokens;\n    const tagDescription = String(utils.getTagDescription(tag));\n    const rawDescription = firstTokens.name ?\n      firstTokens.name + firstTokens.postName + tagDescription :\n      tagDescription;\n\n    let hasAmbiguousLink = false;\n    let hasNoncanonicalLink = false;\n\n    for (const match of rawDescription.matchAll(markdownLinkRegex)) {\n      const label = match[1];\n      const target = match[2];\n\n      if (\n        isInsideMarkdownCodeSpan(rawDescription, match.index) ||\n        scopedPackageNameRegex.test(target) ||\n        cannotSafelyFormatLink(canonicalForm, label)\n      ) {\n        hasAmbiguousLink = true;\n      } else {\n        hasNoncanonicalLink = true;\n      }\n    }\n\n    for (const inlineTag of tag.inlineTags) {\n      if (inlineTag.tag !== 'link' || !inlineTag.text) {\n        continue;\n      }\n\n      if (inlineTag.format === 'space') {\n        hasAmbiguousLink = true;\n        continue;\n      }\n\n      if (cannotSafelyFormatLink(\n        canonicalForm,\n        inlineTag.text,\n      )) {\n        hasAmbiguousLink = true;\n        continue;\n      }\n\n      if (inlineTag.format === canonicalForm) {\n        continue;\n      }\n\n      const {\n        start,\n      } = /** @type {typeof inlineTag & {start: number}} */ (inlineTag);\n\n      if (\n        isInsideMarkdownCodeSpan(rawDescription, start) ||\n        scopedPackageNameRegex.test(inlineTag.namepathOrURL)\n      ) {\n        hasAmbiguousLink = true;\n      } else {\n        hasNoncanonicalLink = true;\n      }\n    }\n\n    const unrecognizedLinkText = rawDescription\n      .replaceAll(new RegExp(markdownLinkRegex, 'gv'), '')\n      .replaceAll(new RegExp(prefixLinkRegex, 'gv'), '')\n      .replaceAll(new RegExp(pipeLinkRegex, 'gv'), '');\n\n    hasAmbiguousLink ||= markdownLinkAttemptRegex.test(unrecognizedLinkText) ||\n      prefixLinkAttemptRegex.test(unrecognizedLinkText) ||\n      pipeLinkAttemptRegex.test(unrecognizedLinkText);\n\n    if (hasAmbiguousLink) {\n      utils.reportJSDoc('@see link cannot be safely normalized.', {\n        line: tag.source[0].number,\n      }, null);\n      continue;\n    }\n\n    if (!hasNoncanonicalLink) {\n      continue;\n    }\n\n    fixableTags.push(tag);\n  }\n\n  for (const [\n    reportIdx,\n    tag,\n  ] of fixableTags.entries()) {\n    utils.reportJSDoc(\n      `Expected @see link to use the ${canonicalForm} form.`,\n      {\n        line: tag.source[0].number,\n      },\n      enableFixer && reportIdx === 0 ?\n        () => {\n          for (const fixableTag of fixableTags) {\n            const firstTokens = fixableTag.source[0].tokens;\n\n            if (firstTokens.name) {\n              firstTokens.description = firstTokens.name +\n                firstTokens.postName + firstTokens.description;\n              firstTokens.name = '';\n              firstTokens.postName = '';\n            }\n\n            for (\n              let sourceIdx = 0;\n              sourceIdx < fixableTag.source.length;\n              sourceIdx++\n            ) {\n              if (!descriptionMatcher.test(\n                fixableTag.source[sourceIdx].tokens.description,\n              )) {\n                continue;\n              }\n\n              utils.setTagDescription(\n                fixableTag,\n                descriptionMatcher,\n                (description) => {\n                  return normalizeDescription(description, canonicalForm);\n                },\n              );\n            }\n          }\n        } :\n        null,\n      true,\n    );\n  }\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Normalizes labeled links in `@see` tags to a canonical `{@link}` form.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/normalize-see-links.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          canonicalForm: {\n            description: 'The canonical `{@link}` form: `\"pipe\"` produces `{@link url|label}`, while `\"prefix\"` produces `[label]{@link url}`. Defaults to `\"pipe\"`.',\n            enum: [\n              'pipe',\n              'prefix',\n            ],\n            type: 'string',\n          },\n          enableFixer: {\n            description: 'Whether to enable the fixer. Defaults to `true`.',\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/normalizeSeeLinks.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;
+//# sourceMappingURL=normalizeSeeLinks.d.ts.map

package/dist/rules.d.ts

@@ -1292,6 +1292,22 @@ export interface Rules {
         }
       ];
 
+  /** Normalizes labeled links in `@see` tags to a canonical `{@link}` form. */
+  "jsdoc/normalize-see-links": 
+    | []
+    | [
+        {
+          /**
+           * The canonical `{@link}` form: `"pipe"` produces `{@link url|label}`, while `"prefix"` produces `[label]{@link url}`. Defaults to `"pipe"`.
+           */
+          canonicalForm?: "pipe" | "prefix";
+          /**
+           * Whether to enable the fixer. Defaults to `true`.
+           */
+          enableFixer?: boolean;
+        }
+      ];
+
   /** Prefer `@import` tags to inline `import()` statements. */
   "jsdoc/prefer-import-tag": 
     | []

package/package.json

@@ -179,5 +179,5 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "63.0.13"
+  "version": "63.1.0"
 }

package/src/index-cjs.js

@@ -36,6 +36,7 @@ import noDefaults from './rules/noDefaults.js';
 import noMissingSyntax from './rules/noMissingSyntax.js';
 import noMultiAsterisks from './rules/noMultiAsterisks.js';
 import noRestrictedSyntax from './rules/noRestrictedSyntax.js';
+import normalizeSeeLinks from './rules/normalizeSeeLinks.js';
 import noTypes from './rules/noTypes.js';
 import noUndefinedTypes from './rules/noUndefinedTypes.js';
 import preferImportTag from './rules/preferImportTag.js';
@@ -128,6 +129,7 @@ index.rules = {
   'no-restricted-syntax': noRestrictedSyntax,
   'no-types': noTypes,
   'no-undefined-types': noUndefinedTypes,
+  'normalize-see-links': normalizeSeeLinks,
   'prefer-import-tag': preferImportTag,
   'reject-any-type': buildRejectOrPreferRuleDefinition({
     description: 'Reports use of `any` or `*` type',
@@ -318,6 +320,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/no-restricted-syntax': 'off',
       'jsdoc/no-types': 'off',
       'jsdoc/no-undefined-types': warnOrError,
+      'jsdoc/normalize-see-links': 'off',
       'jsdoc/prefer-import-tag': 'off',
       'jsdoc/reject-any-type': warnOrError,
       'jsdoc/reject-function-type': warnOrError,

package/src/index.js

@@ -42,6 +42,7 @@ import noDefaults from './rules/noDefaults.js';
 import noMissingSyntax from './rules/noMissingSyntax.js';
 import noMultiAsterisks from './rules/noMultiAsterisks.js';
 import noRestrictedSyntax from './rules/noRestrictedSyntax.js';
+import normalizeSeeLinks from './rules/normalizeSeeLinks.js';
 import noTypes from './rules/noTypes.js';
 import noUndefinedTypes from './rules/noUndefinedTypes.js';
 import preferImportTag from './rules/preferImportTag.js';
@@ -134,6 +135,7 @@ index.rules = {
   'no-restricted-syntax': noRestrictedSyntax,
   'no-types': noTypes,
   'no-undefined-types': noUndefinedTypes,
+  'normalize-see-links': normalizeSeeLinks,
   'prefer-import-tag': preferImportTag,
   'reject-any-type': buildRejectOrPreferRuleDefinition({
     description: 'Reports use of `any` or `*` type',
@@ -324,6 +326,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/no-restricted-syntax': 'off',
       'jsdoc/no-types': 'off',
       'jsdoc/no-undefined-types': warnOrError,
+      'jsdoc/normalize-see-links': 'off',
       'jsdoc/prefer-import-tag': 'off',
       'jsdoc/reject-any-type': warnOrError,
       'jsdoc/reject-function-type': warnOrError,

package/src/rules/escapeInlineTags.js

@@ -41,6 +41,34 @@ export default iterateJsdoc(({
     'linkplain',
   ]);
 
+  const markdownCodeSpanRegex = /(?<!\\)(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/gv;
+
+  /**
+   * @param {string} desc
+   * @param {number} index
+   * @returns {boolean}
+   */
+  const isInsideMarkdownCodeSpan = (desc, index) => {
+    markdownCodeSpanRegex.lastIndex = 0;
+
+    let match;
+    while ((match = markdownCodeSpanRegex.exec(desc)) !== null) {
+      const delimiterLength = match[1].length;
+      const contentStart = match.index + delimiterLength;
+      const contentEnd = match.index + match[0].length - delimiterLength;
+
+      if (index < contentStart) {
+        return false;
+      }
+
+      if (index < contentEnd) {
+        return true;
+      }
+    }
+
+    return false;
+  };
+
   /**
    * @param {string} desc
    * @param {number} atSignIndex
@@ -72,8 +100,9 @@ export default iterateJsdoc(({
     const atSignIndex = offset + match.lastIndexOf('@');
     const inlineTagName = getInlineTagName(desc, atSignIndex);
 
-    return declarationReferenceInlineTags.has(inlineTagName) &&
-      scopedPackageNameRegex.test(desc.slice(atSignIndex));
+    return isInsideMarkdownCodeSpan(desc, atSignIndex) ||
+      declarationReferenceInlineTags.has(inlineTagName) &&
+        scopedPackageNameRegex.test(desc.slice(atSignIndex));
   };
 
   /**

package/src/rules/normalizeSeeLinks.js

@@ -0,0 +1,283 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+const markdownLinkRegex = /(?<!\\)\[([^`\]\r\n]+)\]\(([^`\(\)\s]+)\)/gv;
+const prefixLinkRegex = /(?<!\\)\[([^\]\r\n]+)\]\{@link\s+([^\}\s\|]+)\}/gv;
+const pipeLinkRegex = /\{@link\s+([^\}\s\|]+)\s*\|\s*([^\}\r\n]+)\}/gv;
+
+const markdownLinkAttemptRegex = /(?<!\\)\[[^\]\r\n]*\]\([^\r\n]*(?:\)|$)/v;
+const prefixLinkAttemptRegex = /(?<!\\)\[[^\]\r\n]*\]\{@link[^\}\r\n]*(?:\}|$)/v;
+const pipeLinkAttemptRegex = /\{@link[^\}\r\n]*\|[^\}\r\n]*(?:\}|$)/v;
+
+const scopedPackageNameRegex = /^@[\w.\-]+\/[\w.\-]+/v;
+const markdownCodeSpanRegex = /(?<!\\)(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/gv;
+
+/**
+ * @param {'pipe'|'prefix'} canonicalForm
+ * @param {string} label
+ * @returns {boolean}
+ */
+const cannotSafelyFormatLink = (canonicalForm, label) => {
+  if (!label.trim()) {
+    return true;
+  }
+
+  if (canonicalForm === 'pipe') {
+    return label.includes('}');
+  }
+
+  return label.includes(']');
+};
+
+/**
+ * @param {string} target
+ * @returns {string}
+ */
+const encodeLinkTarget = (target) => {
+  return encodeURI(target).replaceAll(/%25(?=[\dA-F]{2})/giv, '%');
+};
+
+/**
+ * @param {string} description
+ * @param {number} index
+ * @returns {boolean}
+ */
+const isInsideMarkdownCodeSpan = (description, index) => {
+  for (const match of description.matchAll(markdownCodeSpanRegex)) {
+    const delimiterLength = match[1].length;
+    const contentStart = match.index + delimiterLength;
+    const contentEnd = match.index + match[0].length - delimiterLength;
+
+    if (index >= contentStart && index < contentEnd) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+/**
+ * @param {'pipe'|'prefix'} canonicalForm
+ * @param {string} label
+ * @param {string} target
+ * @returns {string}
+ */
+const formatLink = (canonicalForm, label, target) => {
+  const encodedTarget = encodeLinkTarget(target);
+
+  return canonicalForm === 'pipe' ?
+    `{@link ${encodedTarget}|${label.trim()}}` :
+    `[${label.trim()}]{@link ${encodedTarget}}`;
+};
+
+/**
+ * @param {string} description
+ * @param {'pipe'|'prefix'} canonicalForm
+ * @returns {string}
+ */
+const normalizeDescription = (description, canonicalForm) => {
+  const markdownNormalized = description.replaceAll(
+    new RegExp(markdownLinkRegex, 'gv'),
+    (_match, label, target) => {
+      return formatLink(canonicalForm, label, target);
+    },
+  );
+
+  if (canonicalForm === 'pipe') {
+    return markdownNormalized.replaceAll(
+      new RegExp(prefixLinkRegex, 'gv'),
+      (_match, label, target) => {
+        return formatLink(canonicalForm, label, target);
+      },
+    );
+  }
+
+  return markdownNormalized.replaceAll(
+    new RegExp(pipeLinkRegex, 'gv'),
+    (_match, target, label) => {
+      return formatLink(canonicalForm, label, target);
+    },
+  );
+};
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  const {
+    canonicalForm = 'pipe',
+    enableFixer = true,
+  } = context.options[0] || {};
+
+  const descriptionMatcher = canonicalForm === 'pipe' ?
+    new RegExp(`${markdownLinkRegex.source}|${prefixLinkRegex.source}`, 'v') :
+    new RegExp(`${markdownLinkRegex.source}|${pipeLinkRegex.source}`, 'v');
+
+  /** @type {import('comment-parser').Spec[]} */
+  const fixableTags = [];
+
+  for (const tag of jsdoc.tags) {
+    if (tag.tag !== 'see') {
+      continue;
+    }
+
+    const firstTokens = tag.source[0].tokens;
+    const tagDescription = String(utils.getTagDescription(tag));
+    const rawDescription = firstTokens.name ?
+      firstTokens.name + firstTokens.postName + tagDescription :
+      tagDescription;
+
+    let hasAmbiguousLink = false;
+    let hasNoncanonicalLink = false;
+
+    for (const match of rawDescription.matchAll(markdownLinkRegex)) {
+      const label = match[1];
+      const target = match[2];
+
+      if (
+        isInsideMarkdownCodeSpan(rawDescription, match.index) ||
+        scopedPackageNameRegex.test(target) ||
+        cannotSafelyFormatLink(canonicalForm, label)
+      ) {
+        hasAmbiguousLink = true;
+      } else {
+        hasNoncanonicalLink = true;
+      }
+    }
+
+    for (const inlineTag of tag.inlineTags) {
+      if (inlineTag.tag !== 'link' || !inlineTag.text) {
+        continue;
+      }
+
+      if (inlineTag.format === 'space') {
+        hasAmbiguousLink = true;
+        continue;
+      }
+
+      if (cannotSafelyFormatLink(
+        canonicalForm,
+        inlineTag.text,
+      )) {
+        hasAmbiguousLink = true;
+        continue;
+      }
+
+      if (inlineTag.format === canonicalForm) {
+        continue;
+      }
+
+      const {
+        start,
+      } = /** @type {typeof inlineTag & {start: number}} */ (inlineTag);
+
+      if (
+        isInsideMarkdownCodeSpan(rawDescription, start) ||
+        scopedPackageNameRegex.test(inlineTag.namepathOrURL)
+      ) {
+        hasAmbiguousLink = true;
+      } else {
+        hasNoncanonicalLink = true;
+      }
+    }
+
+    const unrecognizedLinkText = rawDescription
+      .replaceAll(new RegExp(markdownLinkRegex, 'gv'), '')
+      .replaceAll(new RegExp(prefixLinkRegex, 'gv'), '')
+      .replaceAll(new RegExp(pipeLinkRegex, 'gv'), '');
+
+    hasAmbiguousLink ||= markdownLinkAttemptRegex.test(unrecognizedLinkText) ||
+      prefixLinkAttemptRegex.test(unrecognizedLinkText) ||
+      pipeLinkAttemptRegex.test(unrecognizedLinkText);
+
+    if (hasAmbiguousLink) {
+      utils.reportJSDoc('@see link cannot be safely normalized.', {
+        line: tag.source[0].number,
+      }, null);
+      continue;
+    }
+
+    if (!hasNoncanonicalLink) {
+      continue;
+    }
+
+    fixableTags.push(tag);
+  }
+
+  for (const [
+    reportIdx,
+    tag,
+  ] of fixableTags.entries()) {
+    utils.reportJSDoc(
+      `Expected @see link to use the ${canonicalForm} form.`,
+      {
+        line: tag.source[0].number,
+      },
+      enableFixer && reportIdx === 0 ?
+        () => {
+          for (const fixableTag of fixableTags) {
+            const firstTokens = fixableTag.source[0].tokens;
+
+            if (firstTokens.name) {
+              firstTokens.description = firstTokens.name +
+                firstTokens.postName + firstTokens.description;
+              firstTokens.name = '';
+              firstTokens.postName = '';
+            }
+
+            for (
+              let sourceIdx = 0;
+              sourceIdx < fixableTag.source.length;
+              sourceIdx++
+            ) {
+              if (!descriptionMatcher.test(
+                fixableTag.source[sourceIdx].tokens.description,
+              )) {
+                continue;
+              }
+
+              utils.setTagDescription(
+                fixableTag,
+                descriptionMatcher,
+                (description) => {
+                  return normalizeDescription(description, canonicalForm);
+                },
+              );
+            }
+          }
+        } :
+        null,
+      true,
+    );
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Normalizes labeled links in `@see` tags to a canonical `{@link}` form.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/normalize-see-links.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          canonicalForm: {
+            description: 'The canonical `{@link}` form: `"pipe"` produces `{@link url|label}`, while `"prefix"` produces `[label]{@link url}`. Defaults to `"pipe"`.',
+            enum: [
+              'pipe',
+              'prefix',
+            ],
+            type: 'string',
+          },
+          enableFixer: {
+            description: 'Whether to enable the fixer. Defaults to `true`.',
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules.d.ts

@@ -1292,6 +1292,22 @@ export interface Rules {
         }
       ];
 
+  /** Normalizes labeled links in `@see` tags to a canonical `{@link}` form. */
+  "jsdoc/normalize-see-links": 
+    | []
+    | [
+        {
+          /**
+           * The canonical `{@link}` form: `"pipe"` produces `{@link url|label}`, while `"prefix"` produces `[label]{@link url}`. Defaults to `"pipe"`.
+           */
+          canonicalForm?: "pipe" | "prefix";
+          /**
+           * Whether to enable the fixer. Defaults to `true`.
+           */
+          enableFixer?: boolean;
+        }
+      ];
+
   /** Prefer `@import` tags to inline `import()` statements. */
   "jsdoc/prefer-import-tag": 
     | []