Skip to content

Commit cfe9cdb

Browse files
authored
feat(normalize-see-links): autofix delimiter-colliding labels via escape round-trip (#1734)
* feat(normalize-see-links): autofix delimiter-colliding labels via escape round-trip * docs(normalize-see-links): drop the implementation-detail note
1 parent e62e746 commit cfe9cdb

4 files changed

Lines changed: 373 additions & 54 deletions

File tree

‎.README/rules/normalize-see-links.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,21 @@ only a lowercase `http:` or `https:` URL in a plain, no-label `{@link}` tag.
77
This option defaults to `false`, and its output is independent of
88
`canonicalForm` because there is no label to position.
99

10+
Labels that contain the destination form's closing delimiter are fixable. For
11+
pipe form, the fixer escapes `}` in the label:
12+
13+
```js
14+
/** @see [See {options}](https://example.com/api) */
15+
/** @see {@link https://example.com/api|See {options\}} */
16+
```
17+
18+
For prefix form, the fixer escapes `]` in the label:
19+
20+
```js
21+
/** @see {@link https://example.com|A]B} */
22+
/** @see [A\]B]{@link https://example.com} */
23+
```
24+
1025
## Options
1126

1227
{"gitdown": "options"}

‎docs/rules/normalize-see-links.md‎

Lines changed: 82 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,21 @@ only a lowercase `http:` or `https:` URL in a plain, no-label `{@link}` tag.
99
This option defaults to `false`, and its output is independent of
1010
`canonicalForm` because there is no label to position.
1111

12+
Labels that contain the destination form's closing delimiter are fixable. For
13+
pipe form, the fixer escapes `}` in the label:
14+
15+
```js
16+
/** @see [See {options}](https://example.com/api) */
17+
/** @see {@link https://example.com/api|See {options\}} */
18+
```
19+
20+
For prefix form, the fixer escapes `]` in the label:
21+
22+
```js
23+
/** @see {@link https://example.com|A]B} */
24+
/** @see [A\]B]{@link https://example.com} */
25+
```
26+
1227
<a name="user-content-normalize-see-links-options"></a>
1328
<a name="normalize-see-links-options"></a>
1429
## Options
@@ -57,12 +72,23 @@ The following patterns are considered problems:
5772
/**
5873
* @see [See {options}](https://example.com/api)
5974
*/
60-
// Message: @see link cannot be safely normalized.
75+
// Message: Expected @see link to use the pipe form.
6176

6277
/**
6378
* @see [a}b](https://example.com)
6479
*/
65-
// Message: @see link cannot be safely normalized.
80+
// Message: Expected @see link to use the pipe form.
81+
82+
/**
83+
* @see [a\}b](https://example.com)
84+
*/
85+
// Message: Expected @see link to use the pipe form.
86+
87+
/**
88+
* @see [A\]B](https://example.com)
89+
*/
90+
// "jsdoc/normalize-see-links": ["error"|"warn", {"canonicalForm":"prefix"}]
91+
// Message: Expected @see link to use the prefix form.
6692

6793
/**
6894
* @see [Foo](https://example.com/a|b)
@@ -79,7 +105,7 @@ The following patterns are considered problems:
79105
* @see {@link https://example.com|A]B}
80106
*/
81107
// "jsdoc/normalize-see-links": ["error"|"warn", {"canonicalForm":"prefix"}]
82-
// Message: @see link cannot be safely normalized.
108+
// Message: Expected @see link to use the prefix form.
83109

84110
/**
85111
* @see [ ]{@link https://example.com}
@@ -137,19 +163,41 @@ The following patterns are considered problems:
137163
// Message: Expected @see link to use the prefix form.
138164

139165
/**
140-
* @see [a\}b](https://example.com)
166+
* @see {@link https://example.com|a\}b}
141167
*/
142-
// Message: @see link cannot be safely normalized.
168+
// "jsdoc/normalize-see-links": ["error"|"warn", {"canonicalForm":"prefix"}]
169+
// Message: Expected @see link to use the prefix form.
170+
171+
/**
172+
* @see [A\]B]{@link https://example.com}
173+
*/
174+
// Message: Expected @see link to use the pipe form.
175+
176+
/**
177+
* @see {@link https://example.com|A]B\}C}
178+
*/
179+
// "jsdoc/normalize-see-links": ["error"|"warn", {"canonicalForm":"prefix"}]
180+
// Message: Expected @see link to use the prefix form.
181+
182+
/**
183+
* @see [A}B\]C]{@link https://example.com}
184+
*/
185+
// Message: Expected @see link to use the pipe form.
186+
187+
/**
188+
* @see [Trailing\\](https://example.com)
189+
*/
190+
// Message: Expected @see link to use the pipe form.
143191

144192
/**
145193
* @see [See {{one} and {two}}](https://example.com)
146194
*/
147-
// Message: @see link cannot be safely normalized.
195+
// Message: Expected @see link to use the pipe form.
148196

149197
/**
150198
* @see [A}B|C](https://example.com)
151199
*/
152-
// Message: @see link cannot be safely normalized.
200+
// Message: Expected @see link to use the pipe form.
153201

154202
/**
155203
* @see [Read the guide](https://example.com/read)
@@ -321,7 +369,7 @@ const value: string = 'value';
321369
* @see [See {options}](https://example.com/labeled)
322370
*/
323371
// "jsdoc/normalize-see-links": ["error"|"warn", {"wrapBareUrls":true}]
324-
// Message: @see link cannot be safely normalized.
372+
// Message: Expected @see link to use the pipe form.
325373

326374
/**
327375
* @see [No fix](https://example.com/labeled)
@@ -360,6 +408,32 @@ const value: string = 'value';
360408
The following patterns are not considered problems:
361409

362410
````ts
411+
/**
412+
* @see {@link https://example.com/api|See {options\}}
413+
*/
414+
415+
/**
416+
* @see [A\]B]{@link https://example.com}
417+
*/
418+
// "jsdoc/normalize-see-links": ["error"|"warn", {"canonicalForm":"prefix"}]
419+
420+
/**
421+
* @see [A\]B}C]{@link https://example.com}
422+
*/
423+
// "jsdoc/normalize-see-links": ["error"|"warn", {"canonicalForm":"prefix"}]
424+
425+
/**
426+
* @see {@link https://example.com|A\}B]C}
427+
*/
428+
429+
/**
430+
* @see {@link https://example.com|Trailing\\}
431+
*/
432+
433+
/**
434+
* @see {@link https://example.com|See {{one\} and {two\}\}}
435+
*/
436+
363437
/**
364438
* @see {@link https://api.example.com/v1?ids=1%7C2%7C3|Docs}
365439
*/

‎src/rules/normalizeSeeLinks.js‎

Lines changed: 36 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
import iterateJsdoc from '../iterateJsdoc.js';
22

3-
const markdownLinkRegex = /(?<!\\)\[([^`\]\r\n]+)\]\(([^`\(\)\s]+)\)/gv;
4-
const prefixLinkRegex = /(?<!\\)\[([^\]\r\n]+)\]\{@link\s+([^\}\s\|]+)\}/gv;
5-
const pipeLinkRegex = /\{@link\s+([^\}\s\|]+)\s*\|\s*([^\}\r\n]+)\}/gv;
3+
const markdownLinkRegex = /(?<!\\)\[((?:[^\\`\]\r\n]|\\[^\r\n])+)\]\(([^`\(\)\s]+)\)/gv;
4+
const prefixLinkRegex = /(?<!\\)\[((?:[^\\\]\r\n]|\\[^\r\n])+)\]\{@link\s+([^\}\s\|]+)\}/gv;
5+
const pipeLinkRegex = /\{@link\s+([^\}\s\|]+)\s*\|\s*((?:[^\\\}\r\n]|\\[^\r\n])+)\}/gv;
66

77
const markdownLinkAttemptRegex = /(?<!\\)\[[^\]\r\n]*\]\([^\r\n]*(?:\)|$)/v;
88
const prefixLinkAttemptRegex = /(?<!\\)\[[^\]\r\n]*\]\{@link[^\}\r\n]*(?:\}|$)/v;
@@ -13,20 +13,33 @@ const markdownCodeSpanRegex = /(?<!\\)(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/gv;
1313
const bareHttpUrlRegex = /^https?:\S+$/v;
1414

1515
/**
16-
* @param {'pipe'|'prefix'} canonicalForm
1716
* @param {string} label
1817
* @returns {boolean}
1918
*/
20-
const cannotSafelyFormatLink = (canonicalForm, label) => {
21-
if (!label.trim()) {
22-
return true;
23-
}
24-
25-
if (canonicalForm === 'pipe') {
26-
return label.includes('}');
27-
}
19+
const cannotSafelyFormatLink = (label) => {
20+
return !label.trim();
21+
};
2822

29-
return label.includes(']');
23+
/**
24+
* @param {'pipe'|'prefix'} canonicalForm
25+
* @param {string} label
26+
* @param {'markdown'|'pipe'|'prefix'} sourceForm
27+
* @returns {string}
28+
*/
29+
const escapeLinkLabel = (canonicalForm, label, sourceForm) => {
30+
const sourceEscapePattern = sourceForm === 'pipe' ?
31+
/\\([\\\}])/gv :
32+
(sourceForm === 'prefix' ?
33+
/\\([\\\]])/gv :
34+
/\\([\\\}\]])/gv);
35+
const targetEscapePattern = canonicalForm === 'pipe' ?
36+
/\\(?=$|[\\\}])|\}/gv :
37+
/\\(?=$|[\\\]])|\]/gv;
38+
const decodedLabel = label.trim().replaceAll(sourceEscapePattern, '$1');
39+
40+
return decodedLabel.replaceAll(targetEscapePattern, (character) => {
41+
return `\\${character}`;
42+
});
3043
};
3144

3245
/**
@@ -95,15 +108,17 @@ const isInsideMarkdownCodeSpan = (description, index) => {
95108
/**
96109
* @param {'pipe'|'prefix'} canonicalForm
97110
* @param {string} label
111+
* @param {'markdown'|'pipe'|'prefix'} sourceForm
98112
* @param {string} target
99113
* @returns {string}
100114
*/
101-
const formatLink = (canonicalForm, label, target) => {
115+
const formatLink = (canonicalForm, label, sourceForm, target) => {
102116
const encodedTarget = encodeLinkTarget(target);
117+
const escapedLabel = escapeLinkLabel(canonicalForm, label, sourceForm);
103118

104119
return canonicalForm === 'pipe' ?
105-
`{@link ${encodedTarget}|${label.trim()}}` :
106-
`[${label.trim()}]{@link ${encodedTarget}}`;
120+
`{@link ${encodedTarget}|${escapedLabel}}` :
121+
`[${escapedLabel}]{@link ${encodedTarget}}`;
107122
};
108123

109124
/**
@@ -115,23 +130,23 @@ const normalizeDescription = (description, canonicalForm) => {
115130
const markdownNormalized = description.replaceAll(
116131
new RegExp(markdownLinkRegex, 'gv'),
117132
(_match, label, target) => {
118-
return formatLink(canonicalForm, label, target);
133+
return formatLink(canonicalForm, label, 'markdown', target);
119134
},
120135
);
121136

122137
if (canonicalForm === 'pipe') {
123138
return markdownNormalized.replaceAll(
124139
new RegExp(prefixLinkRegex, 'gv'),
125140
(_match, label, target) => {
126-
return formatLink(canonicalForm, label, target);
141+
return formatLink(canonicalForm, label, 'prefix', target);
127142
},
128143
);
129144
}
130145

131146
return markdownNormalized.replaceAll(
132147
new RegExp(pipeLinkRegex, 'gv'),
133148
(_match, target, label) => {
134-
return formatLink(canonicalForm, label, target);
149+
return formatLink(canonicalForm, label, 'pipe', target);
135150
},
136151
);
137152
};
@@ -183,7 +198,7 @@ export default iterateJsdoc(({
183198
if (
184199
isInsideMarkdownCodeSpan(rawDescription, match.index) ||
185200
scopedPackageNameRegex.test(target) ||
186-
cannotSafelyFormatLink(canonicalForm, label)
201+
cannotSafelyFormatLink(label)
187202
) {
188203
hasAmbiguousLink = true;
189204
} else {
@@ -201,10 +216,7 @@ export default iterateJsdoc(({
201216
continue;
202217
}
203218

204-
if (cannotSafelyFormatLink(
205-
canonicalForm,
206-
inlineTag.text,
207-
)) {
219+
if (cannotSafelyFormatLink(inlineTag.text)) {
208220
hasAmbiguousLink = true;
209221
continue;
210222
}

0 commit comments

Comments
 (0)