@depup/eslint-plugin-jsdoc 63.3.0-depup.0 → 63.3.2-depup.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +3 -4
  2. package/changes.json +2 -6
  3. package/dist/rules/normalizeSeeLinks.cjs +1 -1
  4. package/dist/rules/normalizeSeeLinks.cjs.map +1 -1
  5. package/dist/rules/requireExample.cjs +3 -0
  6. package/dist/rules/requireExample.cjs.map +1 -1
  7. package/package.json +10 -14
  8. package/src/rules/normalizeSeeLinks.js +5 -1
  9. package/src/rules/requireExample.js +4 -0
package/README.md CHANGED
@@ -13,16 +13,15 @@ npm install @depup/eslint-plugin-jsdoc
13
13
 
14
14
  | Field | Value |
15
15
  |-------|-------|
16
- | Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 63.3.0 |
17
- | Processed | 2026-07-26 |
16
+ | Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 63.3.2 |
17
+ | Processed | 2026-07-28 |
18
18
  | Smoke test | passed |
19
- | Deps updated | 3 |
19
+ | Deps updated | 2 |
20
20
 
21
21
  ## Dependency Changes
22
22
 
23
23
  | Dependency | From | To |
24
24
  |------------|------|-----|
25
- | @es-joy/jsdoccomment | ~0.90.0 | ^0.91.0 |
26
25
  | are-docs-informative | ^0.0.2 | ^0.1.1 |
27
26
  | escape-string-regexp | ^4.0.0 | ^5.0.0 |
28
27
 
package/changes.json CHANGED
@@ -1,9 +1,5 @@
1
1
  {
2
2
  "bumped": {
3
- "@es-joy/jsdoccomment": {
4
- "from": "~0.90.0",
5
- "to": "^0.91.0"
6
- },
7
3
  "are-docs-informative": {
8
4
  "from": "^0.0.2",
9
5
  "to": "^0.1.1"
@@ -13,6 +9,6 @@
13
9
  "to": "^5.0.0"
14
10
  }
15
11
  },
16
- "timestamp": "2026-07-26T08:49:28.747Z",
17
- "totalUpdated": 3
12
+ "timestamp": "2026-07-28T16:34:46.314Z",
13
+ "totalUpdated": 2
18
14
  }
package/dist/rules/normalizeSeeLinks.cjs CHANGED
@@ -44,7 +44,7 @@ const escapeLinkLabel = (canonicalForm, label, sourceForm) => {
44
44
  * @returns {string}
45
45
  */
46
46
  const encodeLinkTarget = target => {
47
- return encodeURI(target).replaceAll(/%25(?=[\dA-F]{2})/giv, '%');
47
+ return target.replaceAll(/%(?![\dA-F]{2})/giv, '%25').replaceAll('|', '%7C').replaceAll('{', '%7B').replaceAll('}', '%7D');
48
48
  };
49
49
 
50
50
  /**
package/dist/rules/normalizeSeeLinks.cjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"normalizeSeeLinks.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/normalizeSeeLinks.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nconst markdownLinkRegex = /(?<!\\\\)\\[((?:[^\\\\`\\]\\r\\n]|\\\\[^\\r\\n])+)\\]\\(([^`\\(\\)\\s]+)\\)/gv;\nconst prefixLinkRegex = /(?<!\\\\)\\[((?:[^\\\\\\]\\r\\n]|\\\\[^\\r\\n])+)\\]\\{@link\\s+([^\\}\\s\\|]+)\\}/gv;\nconst pipeLinkRegex = /\\{@link\\s+([^\\}\\s\\|]+)\\s*\\|\\s*((?:[^\\\\\\}\\r\\n]|\\\\[^\\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;\nconst bareHttpUrlRegex = /^https?:\\S+$/v;\n\n/**\n * @param {string} label\n * @returns {boolean}\n */\nconst cannotSafelyFormatLink = (label) => {\n return !label.trim();\n};\n\n/**\n * @param {'pipe'|'prefix'} canonicalForm\n * @param {string} label\n * @param {'markdown'|'pipe'|'prefix'} sourceForm\n * @returns {string}\n */\nconst escapeLinkLabel = (canonicalForm, label, sourceForm) => {\n const sourceEscapePattern = sourceForm === 'pipe' ?\n /\\\\([\\\\\\}])/gv :\n (sourceForm === 'prefix' ?\n /\\\\([\\\\\\]])/gv :\n /\\\\([\\\\\\}\\]])/gv);\n const targetEscapePattern = canonicalForm === 'pipe' ?\n /\\\\(?=$|[\\\\\\}])|\\}/gv :\n /\\\\(?=$|[\\\\\\]])|\\]/gv;\n const decodedLabel = label.trim().replaceAll(sourceEscapePattern, '$1');\n\n return decodedLabel.replaceAll(targetEscapePattern, (character) => {\n return `\\\\${character}`;\n });\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 {boolean} enabled\n * @returns {string|null}\n */\nconst getBareHttpUrl = (description, enabled) => {\n if (!enabled) {\n return null;\n }\n\n const trimmedDescription = description.trim();\n\n return bareHttpUrlRegex.test(trimmedDescription) &&\n URL.canParse(trimmedDescription) ?\n trimmedDescription : null;\n};\n\n/**\n * @param {string} target\n * @returns {string}\n */\nconst formatBareUrl = (target) => {\n return `{@link ${encodeLinkTarget(target)}}`;\n};\n\n/**\n * @param {string|undefined} bareUrl\n * @param {'pipe'|'prefix'} canonicalForm\n * @returns {string}\n */\nconst getExpectedMessage = (bareUrl, canonicalForm) => {\n return bareUrl ?\n 'Expected bare @see URL to use a {@link} tag.' :\n `Expected @see link to use the ${canonicalForm} form.`;\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 {'markdown'|'pipe'|'prefix'} sourceForm\n * @param {string} target\n * @returns {string}\n */\nconst formatLink = (canonicalForm, label, sourceForm, target) => {\n const encodedTarget = encodeLinkTarget(target);\n const escapedLabel = escapeLinkLabel(canonicalForm, label, sourceForm);\n\n return canonicalForm === 'pipe' ?\n `{@link ${encodedTarget}|${escapedLabel}}` :\n `[${escapedLabel}]{@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, 'markdown', 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, 'prefix', target);\n },\n );\n }\n\n return markdownNormalized.replaceAll(\n new RegExp(pipeLinkRegex, 'gv'),\n (_match, target, label) => {\n return formatLink(canonicalForm, label, 'pipe', target);\n },\n );\n};\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n utils,\n}) => {\n const {\n canonicalForm = 'pipe',\n enableFixer = true,\n wrapBareUrls = false,\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 /** @type {Map<import('comment-parser').Spec, string>} */\n const bareUrlTags = new Map();\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 const bareUrl = getBareHttpUrl(rawDescription, wrapBareUrls);\n\n if (bareUrl) {\n bareUrlTags.set(tag, bareUrl);\n hasNoncanonicalLink = true;\n }\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(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(inlineTag.text)) {\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 const bareUrl = bareUrlTags.get(tag);\n\n utils.reportJSDoc(\n getExpectedMessage(bareUrl, canonicalForm),\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 const fixableBareUrl = bareUrlTags.get(fixableTag);\n\n if (fixableBareUrl) {\n for (const source of fixableTag.source) {\n if (!source.tokens.description.includes(fixableBareUrl)) {\n continue;\n }\n\n source.tokens.description = source.tokens.description.replace(\n fixableBareUrl,\n () => {\n return formatBareUrl(fixableBareUrl);\n },\n );\n break;\n }\n\n continue;\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 wrapBareUrls: {\n description: 'Whether to wrap an `@see` description containing only a lowercase `http:` or `https:` URL (for example, `@see https://example.com`) in a plain `{@link https://example.com}`. Defaults to `false`.',\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":"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","ignoreList":[]}
1
+ {"version":3,"file":"normalizeSeeLinks.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/normalizeSeeLinks.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nconst markdownLinkRegex = /(?<!\\\\)\\[((?:[^\\\\`\\]\\r\\n]|\\\\[^\\r\\n])+)\\]\\(([^`\\(\\)\\s]+)\\)/gv;\nconst prefixLinkRegex = /(?<!\\\\)\\[((?:[^\\\\\\]\\r\\n]|\\\\[^\\r\\n])+)\\]\\{@link\\s+([^\\}\\s\\|]+)\\}/gv;\nconst pipeLinkRegex = /\\{@link\\s+([^\\}\\s\\|]+)\\s*\\|\\s*((?:[^\\\\\\}\\r\\n]|\\\\[^\\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;\nconst bareHttpUrlRegex = /^https?:\\S+$/v;\n\n/**\n * @param {string} label\n * @returns {boolean}\n */\nconst cannotSafelyFormatLink = (label) => {\n return !label.trim();\n};\n\n/**\n * @param {'pipe'|'prefix'} canonicalForm\n * @param {string} label\n * @param {'markdown'|'pipe'|'prefix'} sourceForm\n * @returns {string}\n */\nconst escapeLinkLabel = (canonicalForm, label, sourceForm) => {\n const sourceEscapePattern = sourceForm === 'pipe' ?\n /\\\\([\\\\\\}])/gv :\n (sourceForm === 'prefix' ?\n /\\\\([\\\\\\]])/gv :\n /\\\\([\\\\\\}\\]])/gv);\n const targetEscapePattern = canonicalForm === 'pipe' ?\n /\\\\(?=$|[\\\\\\}])|\\}/gv :\n /\\\\(?=$|[\\\\\\]])|\\]/gv;\n const decodedLabel = label.trim().replaceAll(sourceEscapePattern, '$1');\n\n return decodedLabel.replaceAll(targetEscapePattern, (character) => {\n return `\\\\${character}`;\n });\n};\n\n/**\n * @param {string} target\n * @returns {string}\n */\nconst encodeLinkTarget = (target) => {\n return target\n .replaceAll(/%(?![\\dA-F]{2})/giv, '%25')\n .replaceAll('|', '%7C')\n .replaceAll('{', '%7B')\n .replaceAll('}', '%7D');\n};\n\n/**\n * @param {string} description\n * @param {boolean} enabled\n * @returns {string|null}\n */\nconst getBareHttpUrl = (description, enabled) => {\n if (!enabled) {\n return null;\n }\n\n const trimmedDescription = description.trim();\n\n return bareHttpUrlRegex.test(trimmedDescription) &&\n URL.canParse(trimmedDescription) ?\n trimmedDescription : null;\n};\n\n/**\n * @param {string} target\n * @returns {string}\n */\nconst formatBareUrl = (target) => {\n return `{@link ${encodeLinkTarget(target)}}`;\n};\n\n/**\n * @param {string|undefined} bareUrl\n * @param {'pipe'|'prefix'} canonicalForm\n * @returns {string}\n */\nconst getExpectedMessage = (bareUrl, canonicalForm) => {\n return bareUrl ?\n 'Expected bare @see URL to use a {@link} tag.' :\n `Expected @see link to use the ${canonicalForm} form.`;\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 {'markdown'|'pipe'|'prefix'} sourceForm\n * @param {string} target\n * @returns {string}\n */\nconst formatLink = (canonicalForm, label, sourceForm, target) => {\n const encodedTarget = encodeLinkTarget(target);\n const escapedLabel = escapeLinkLabel(canonicalForm, label, sourceForm);\n\n return canonicalForm === 'pipe' ?\n `{@link ${encodedTarget}|${escapedLabel}}` :\n `[${escapedLabel}]{@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, 'markdown', 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, 'prefix', target);\n },\n );\n }\n\n return markdownNormalized.replaceAll(\n new RegExp(pipeLinkRegex, 'gv'),\n (_match, target, label) => {\n return formatLink(canonicalForm, label, 'pipe', target);\n },\n );\n};\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n utils,\n}) => {\n const {\n canonicalForm = 'pipe',\n enableFixer = true,\n wrapBareUrls = false,\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 /** @type {Map<import('comment-parser').Spec, string>} */\n const bareUrlTags = new Map();\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 const bareUrl = getBareHttpUrl(rawDescription, wrapBareUrls);\n\n if (bareUrl) {\n bareUrlTags.set(tag, bareUrl);\n hasNoncanonicalLink = true;\n }\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(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(inlineTag.text)) {\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 const bareUrl = bareUrlTags.get(tag);\n\n utils.reportJSDoc(\n getExpectedMessage(bareUrl, canonicalForm),\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 const fixableBareUrl = bareUrlTags.get(fixableTag);\n\n if (fixableBareUrl) {\n for (const source of fixableTag.source) {\n if (!source.tokens.description.includes(fixableBareUrl)) {\n continue;\n }\n\n source.tokens.description = source.tokens.description.replace(\n fixableBareUrl,\n () => {\n return formatBareUrl(fixableBareUrl);\n },\n );\n break;\n }\n\n continue;\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 wrapBareUrls: {\n description: 'Whether to wrap an `@see` description containing only a lowercase `http:` or `https:` URL (for example, `@see https://example.com`) in a plain `{@link https://example.com}`. Defaults to `false`.',\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/requireExample.cjs CHANGED
@@ -31,6 +31,9 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
31
31
  }
32
32
  utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {
33
33
  if (enableFixer) {
34
+ if (jsdoc.source.length === 1) {
35
+ utils.makeMultiline();
36
+ }
34
37
  utils.addTag(targetTagName);
35
38
  }
36
39
  });
package/dist/rules/requireExample.cjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"requireExample.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireExample.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n report,\n utils,\n}) => {\n if (utils.avoidDocs()) {\n return;\n }\n\n const {\n enableFixer = true,\n exemptNoArguments = false,\n } = context.options[0] || {};\n\n const targetTagName = 'example';\n\n const functionExamples = jsdoc.tags.filter(({\n tag,\n }) => {\n return tag === targetTagName;\n });\n\n if (!functionExamples.length) {\n if (exemptNoArguments && utils.isIteratingFunctionOrVariable() &&\n !utils.hasParams()\n ) {\n return;\n }\n\n utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {\n if (enableFixer) {\n utils.addTag(targetTagName);\n }\n });\n\n return;\n }\n\n for (const example of functionExamples) {\n const exampleContent = `${example.name} ${utils.getTagDescription(example)}`\n .trim()\n .split('\\n')\n .filter(Boolean);\n\n if (!exampleContent.length) {\n report(`Missing JSDoc @${targetTagName} description.`, null, example);\n }\n }\n}, {\n contextDefaults: true,\n meta: {\n docs: {\n description: 'Requires that all functions (and potentially other contexts) have examples.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header',\n },\n fixable: 'code',\n schema: [\n {\n additionalProperties: false,\n properties: {\n checkConstructors: {\n default: true,\n description: `A value indicating whether \\`constructor\\`s should be checked.\nDefaults to \\`true\\`.`,\n type: 'boolean',\n },\n checkGetters: {\n default: false,\n description: 'A value indicating whether getters should be checked. Defaults to `false`.',\n type: 'boolean',\n },\n checkSetters: {\n default: false,\n description: 'A value indicating whether setters should be checked. Defaults to `false`.',\n type: 'boolean',\n },\n contexts: {\n description: `Set this to an array of strings representing the AST context (or an object with\noptional \\`context\\` and \\`comment\\` properties) where you wish the rule to be applied.\n(e.g., \\`ClassDeclaration\\` for ES6 classes).\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want the rule to apply to any\nJSDoc block throughout your files.\n\nSee the [\"AST and Selectors\"](../advanced.md#ast-and-selectors)\nsection of our Advanced docs for more on the expected format.`,\n items: {\n anyOf: [\n {\n type: 'string',\n },\n {\n additionalProperties: false,\n properties: {\n comment: {\n type: 'string',\n },\n context: {\n type: 'string',\n },\n },\n type: 'object',\n },\n ],\n },\n type: 'array',\n },\n enableFixer: {\n default: true,\n description: `A boolean on whether to enable the fixer (which adds an empty \\`@example\\` block).\nDefaults to \\`true\\`.`,\n type: 'boolean',\n },\n exemptedBy: {\n description: `Array of tags (e.g., \\`['type']\\`) whose presence on the document\nblock avoids the need for an \\`@example\\`. Defaults to an array with\n\\`inheritdoc\\`. If you set this array, it will overwrite the default,\nso be sure to add back \\`inheritdoc\\` if you wish its presence to cause\nexemption of the rule.`,\n items: {\n type: 'string',\n },\n type: 'array',\n },\n exemptNoArguments: {\n default: false,\n description: `Boolean to indicate that no-argument functions should not be reported for\nmissing \\`@example\\` declarations.`,\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":"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","ignoreList":[]}
1
+ {"version":3,"file":"requireExample.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireExample.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n report,\n utils,\n}) => {\n if (utils.avoidDocs()) {\n return;\n }\n\n const {\n enableFixer = true,\n exemptNoArguments = false,\n } = context.options[0] || {};\n\n const targetTagName = 'example';\n\n const functionExamples = jsdoc.tags.filter(({\n tag,\n }) => {\n return tag === targetTagName;\n });\n\n if (!functionExamples.length) {\n if (exemptNoArguments && utils.isIteratingFunctionOrVariable() &&\n !utils.hasParams()\n ) {\n return;\n }\n\n utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {\n if (enableFixer) {\n if (jsdoc.source.length === 1) {\n utils.makeMultiline();\n }\n\n utils.addTag(targetTagName);\n }\n });\n\n return;\n }\n\n for (const example of functionExamples) {\n const exampleContent = `${example.name} ${utils.getTagDescription(example)}`\n .trim()\n .split('\\n')\n .filter(Boolean);\n\n if (!exampleContent.length) {\n report(`Missing JSDoc @${targetTagName} description.`, null, example);\n }\n }\n}, {\n contextDefaults: true,\n meta: {\n docs: {\n description: 'Requires that all functions (and potentially other contexts) have examples.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header',\n },\n fixable: 'code',\n schema: [\n {\n additionalProperties: false,\n properties: {\n checkConstructors: {\n default: true,\n description: `A value indicating whether \\`constructor\\`s should be checked.\nDefaults to \\`true\\`.`,\n type: 'boolean',\n },\n checkGetters: {\n default: false,\n description: 'A value indicating whether getters should be checked. Defaults to `false`.',\n type: 'boolean',\n },\n checkSetters: {\n default: false,\n description: 'A value indicating whether setters should be checked. Defaults to `false`.',\n type: 'boolean',\n },\n contexts: {\n description: `Set this to an array of strings representing the AST context (or an object with\noptional \\`context\\` and \\`comment\\` properties) where you wish the rule to be applied.\n(e.g., \\`ClassDeclaration\\` for ES6 classes).\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want the rule to apply to any\nJSDoc block throughout your files.\n\nSee the [\"AST and Selectors\"](../advanced.md#ast-and-selectors)\nsection of our Advanced docs for more on the expected format.`,\n items: {\n anyOf: [\n {\n type: 'string',\n },\n {\n additionalProperties: false,\n properties: {\n comment: {\n type: 'string',\n },\n context: {\n type: 'string',\n },\n },\n type: 'object',\n },\n ],\n },\n type: 'array',\n },\n enableFixer: {\n default: true,\n description: `A boolean on whether to enable the fixer (which adds an empty \\`@example\\` block).\nDefaults to \\`true\\`.`,\n type: 'boolean',\n },\n exemptedBy: {\n description: `Array of tags (e.g., \\`['type']\\`) whose presence on the document\nblock avoids the need for an \\`@example\\`. Defaults to an array with\n\\`inheritdoc\\`. If you set this array, it will overwrite the default,\nso be sure to add back \\`inheritdoc\\` if you wish its presence to cause\nexemption of the rule.`,\n items: {\n type: 'string',\n },\n type: 'array',\n },\n exemptNoArguments: {\n default: false,\n description: `Boolean to indicate that no-argument functions should not be reported for\nmissing \\`@example\\` declarations.`,\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":";;;;;;AAAA;AAA8C;AAAA,iCAE/B,IAAAA,qBAAY,EAAC,CAAC;EAC3B,OAAO;EACP,KAAK;EACL,MAAM;EACN;AACF,CAAC,KAAK;EACJ,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE;IACrB;EACF;EAEA,MAAM;IACJ,WAAW,GAAG,IAAI;IAClB,iBAAiB,GAAG;EACtB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;EAE5B,MAAM,aAAa,GAAG,SAAS;EAE/B,MAAM,gBAAgB,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C;EACF,CAAC,KAAK;IACJ,OAAO,GAAG,KAAK,aAAa;EAC9B,CAAC,CAAC;EAEF,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE;IAC5B,IAAI,iBAAiB,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC,IAC5D,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,EAClB;MACA;IACF;IAEA,KAAK,CAAC,WAAW,CAAC,kBAAkB,aAAa,eAAe,EAAE,IAAI,EAAE,MAAM;MAC5E,IAAI,WAAW,EAAE;QACf,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE;UAC7B,KAAK,CAAC,aAAa,CAAC,CAAC;QACvB;QAEA,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC;MAC7B;IACF,CAAC,CAAC;IAEF;EACF;EAEA,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE;IACtC,MAAM,cAAc,GAAG,GAAG,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CACzE,IAAI,CAAC,CAAC,CACN,KAAK,CAAC,IAAI,CAAC,CACX,MAAM,CAAC,OAAO,CAAC;IAElB,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE;MAC1B,MAAM,CAAC,kBAAkB,aAAa,eAAe,EAAE,IAAI,EAAE,OAAO,CAAC;IACvE;EACF;AACF,CAAC,EAAE;EACD,eAAe,EAAE,IAAI;EACrB,IAAI,EAAE;IACJ,IAAI,EAAE;MACJ,WAAW,EAAE,6EAA6E;MAC1F,GAAG,EAAE;IACP,CAAC;IACD,OAAO,EAAE,MAAM;IACf,MAAM,EAAE,CACN;MACE,oBAAoB,EAAE,KAAK;MAC3B,UAAU,EAAE;QACV,iBAAiB,EAAE;UACjB,OAAO,EAAE,IAAI;UACb,WAAW,EAAE;AACzB,sBAAsB;UACV,IAAI,EAAE;QACR,CAAC;QACD,YAAY,EAAE;UACZ,OAAO,EAAE,KAAK;UACd,WAAW,EAAE,4EAA4E;UACzF,IAAI,EAAE;QACR,CAAC;QACD,YAAY,EAAE;UACZ,OAAO,EAAE,KAAK;UACd,WAAW,EAAE,4EAA4E;UACzF,IAAI,EAAE;QACR,CAAC;QACD,QAAQ,EAAE;UACR,WAAW,EAAE;AACzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,8DAA8D;UAClD,KAAK,EAAE;YACL,KAAK,EAAE,CACL;cACE,IAAI,EAAE;YACR,CAAC,EACD;cACE,oBAAoB,EAAE,KAAK;cAC3B,UAAU,EAAE;gBACV,OAAO,EAAE;kBACP,IAAI,EAAE;gBACR,CAAC;gBACD,OAAO,EAAE;kBACP,IAAI,EAAE;gBACR;cACF,CAAC;cACD,IAAI,EAAE;YACR,CAAC;UAEL,CAAC;UACD,IAAI,EAAE;QACR,CAAC;QACD,WAAW,EAAE;UACX,OAAO,EAAE,IAAI;UACb,WAAW,EAAE;AACzB,sBAAsB;UACV,IAAI,EAAE;QACR,CAAC;QACD,UAAU,EAAE;UACV,WAAW,EAAE;AACzB;AACA;AACA;AACA,uBAAuB;UACX,KAAK,EAAE;YACL,IAAI,EAAE;UACR,CAAC;UACD,IAAI,EAAE;QACR,CAAC;QACD,iBAAiB,EAAE;UACjB,OAAO,EAAE,KAAK;UACd,WAAW,EAAE;AACzB,mCAAmC;UACvB,IAAI,EAAE;QACR;MACF,CAAC;MACD,IAAI,EAAE;IACR,CAAC,CACF;IACD,IAAI,EAAE;EACR;AACF,CAAC,CAAC;AAAA","ignoreList":[]}
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "url": "http://gajus.com"
6
6
  },
7
7
  "dependencies": {
8
- "@es-joy/jsdoccomment": "^0.91.0",
8
+ "@es-joy/jsdoccomment": "~0.91.0",
9
9
  "@es-joy/resolve.exports": "1.2.0",
10
10
  "are-docs-informative": "^0.1.1",
11
11
  "comment-parser": "1.4.7",
@@ -53,22 +53,22 @@
53
53
  "camelcase": "^9.0.0",
54
54
  "chai": "^6.2.2",
55
55
  "decamelize": "^6.0.1",
56
- "eslint": "10.7.0",
56
+ "eslint": "10.8.0",
57
57
  "eslint-config-canonical": "^47.4.2",
58
58
  "gitdown": "^4.1.1",
59
59
  "glob": "^13.0.6",
60
- "globals": "^17.7.0",
60
+ "globals": "^17.8.0",
61
61
  "husky": "^9.1.7",
62
- "jsdoc-type-pratt-parser": "^7.3.0",
62
+ "jsdoc-type-pratt-parser": "^8.0.0",
63
63
  "json-schema": "^0.4.0",
64
64
  "json-schema-to-typescript": "^15.0.4",
65
65
  "lint-staged": "^17.2.0",
66
66
  "mocha": "^11.7.6",
67
67
  "open-editor": "^6.0.0",
68
- "playwright": "^1.61.1",
68
+ "playwright": "^1.62.0",
69
69
  "replace": "^1.2.2",
70
70
  "rimraf": "^6.1.3",
71
- "rollup": "^4.62.2",
71
+ "rollup": "^4.62.3",
72
72
  "semantic-release": "^25.0.8",
73
73
  "sinon": "^22.1.0",
74
74
  "ts-api-utils": "^2.5.0",
@@ -185,13 +185,9 @@
185
185
  "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
186
186
  "test-index": "pnpm run test-no-cov test/rules/index.js"
187
187
  },
188
- "version": "63.3.0-depup.0",
188
+ "version": "63.3.2-depup.0",
189
189
  "depup": {
190
190
  "changes": {
191
- "@es-joy/jsdoccomment": {
192
- "from": "~0.90.0",
193
- "to": "^0.91.0"
194
- },
195
191
  "are-docs-informative": {
196
192
  "from": "^0.0.2",
197
193
  "to": "^0.1.1"
@@ -201,10 +197,10 @@
201
197
  "to": "^5.0.0"
202
198
  }
203
199
  },
204
- "depsUpdated": 3,
200
+ "depsUpdated": 2,
205
201
  "originalPackage": "eslint-plugin-jsdoc",
206
- "originalVersion": "63.3.0",
207
- "processedAt": "2026-07-26T08:49:54.272Z",
202
+ "originalVersion": "63.3.2",
203
+ "processedAt": "2026-07-28T16:35:09.110Z",
208
204
  "smokeTest": "passed"
209
205
  }
210
206
  }
package/src/rules/normalizeSeeLinks.js CHANGED
@@ -47,7 +47,11 @@ const escapeLinkLabel = (canonicalForm, label, sourceForm) => {
47
47
  * @returns {string}
48
48
  */
49
49
  const encodeLinkTarget = (target) => {
50
- return encodeURI(target).replaceAll(/%25(?=[\dA-F]{2})/giv, '%');
50
+ return target
51
+ .replaceAll(/%(?![\dA-F]{2})/giv, '%25')
52
+ .replaceAll('|', '%7C')
53
+ .replaceAll('{', '%7B')
54
+ .replaceAll('}', '%7D');
51
55
  };
52
56
 
53
57
  /**
package/src/rules/requireExample.js CHANGED
@@ -32,6 +32,10 @@ export default iterateJsdoc(({
32
32
 
33
33
  utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {
34
34
  if (enableFixer) {
35
+ if (jsdoc.source.length === 1) {
36
+ utils.makeMultiline();
37
+ }
38
+
35
39
  utils.addTag(targetTagName);
36
40
  }
37
41
  });