Skip to content

Commit d3306a2

Browse files
authored
fix: fix resolution of various type annotation edge cases (#968)
* fix: fix resolution of various type annotation edge cases Signed-off-by: Tim Perry <pimterry@gmail.com> * Fix review comments This now correctly warns on || in annotations, and updates tests to avoid hardcoding colours, and avoid looking like we're trying to do XSS filtering which seems to have confused the bot checks. * Move MODULE_QUALIFIED_NAME into constants, simplify slightly Signed-off-by: Tim Perry <pimterry@gmail.com> --------- Signed-off-by: Tim Perry <pimterry@gmail.com>
1 parent bacccc3 commit d3306a2

11 files changed

Lines changed: 380 additions & 42 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@node-core/doc-kit': patch
3+
---
4+
5+
Resolve unions and arrays of display-name types (`{HTTP/2 Headers Object | vm.Module}`, `{HTTP/2 Headers Object[]}`), and stop capturing prose such as `U+007B ({), and U+007D (}).` as a type annotation.

‎packages/core/bin/cli.mjs‎

100644100755
File mode changed.

‎packages/core/src/generators/metadata/constants.mjs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@ export const DOC_API_SLUGS_REPLACEMENTS = [
1515
// Matches Node.js deprecation headings such as "DEP0001: Description".
1616
export const DEPRECATION_HEADING_REGEX = /^(DEP\d+):/;
1717

18+
// A dotted identifier path, e.g. `vm.Module` or `os.constants.dlopen`. Names
19+
// that merely contain a dot (prose, `Object.<string, string>`, `1.5`) must not
20+
// be turned into a module link.
21+
export const MODULE_QUALIFIED_NAME = /^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)+$/;
22+
1823
// These are regular expressions used to determine if a given Markdown heading
1924
// is a specific type of API Doc entry (e.g., Event, Class, Method, etc)
2025
// and to extract the inner content of said Heading to be used as the API doc entry name
Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
import assert from 'node:assert/strict';
2+
import { describe, it, mock, beforeEach } from 'node:test';
3+
4+
const warnings = [];
5+
6+
mock.module('../../../../logger/index.mjs', {
7+
defaultExport: {
8+
warn: message => warnings.push(message),
9+
},
10+
});
11+
12+
const { resolveTypeAnnotations } = await import('../resolveTypes.mjs');
13+
14+
const HTTP2_TYPE_MAP = {
15+
'HTTP/2 Headers Object': 'http2.html#headers-object',
16+
};
17+
18+
/**
19+
* Resolves a single annotation and returns its node
20+
*
21+
* @param {string} value The type value
22+
* @param {Record<string, string>} typeMap The mapping of types to links
23+
*/
24+
const resolve = (value, typeMap = {}) => {
25+
const node = { type: 'typeAnnotation', value };
26+
27+
resolveTypeAnnotations(
28+
{ type: 'root', children: [node] },
29+
typeMap,
30+
'test.md'
31+
);
32+
33+
return node;
34+
};
35+
36+
/**
37+
* Resolves a single annotation and returns its links as `[text, href]` pairs,
38+
* asserting that every range lines up with the text it links
39+
*
40+
* @param {string} value The type value
41+
* @param {Record<string, string>} typeMap The mapping of types to links
42+
*/
43+
const linksIn = (value, typeMap = {}) => {
44+
const { data } = resolve(value, typeMap);
45+
46+
for (const link of data.links) {
47+
assert.equal(value.slice(link.start, link.end), link.text);
48+
}
49+
50+
return data.links.map(({ text, href }) => [text, href]);
51+
};
52+
53+
describe('resolveTypeAnnotations', () => {
54+
beforeEach(() => {
55+
warnings.length = 0;
56+
});
57+
58+
it('links a type that is a whole map key', () => {
59+
assert.deepEqual(linksIn('HTTP/2 Headers Object', HTTP2_TYPE_MAP), [
60+
['HTTP/2 Headers Object', 'http2.html#headers-object'],
61+
]);
62+
assert.deepEqual(warnings, []);
63+
});
64+
65+
it('links an array of a display name', () => {
66+
assert.deepEqual(linksIn('HTTP/2 Headers Object[]', HTTP2_TYPE_MAP), [
67+
['HTTP/2 Headers Object', 'http2.html#headers-object'],
68+
]);
69+
assert.deepEqual(warnings, []);
70+
});
71+
72+
it('resolves module-qualified names alongside display names', () => {
73+
assert.deepEqual(linksIn('Module Namespace Object | vm.Module'), [
74+
[
75+
'Module Namespace Object',
76+
'https://tc39.github.io/ecma262/#sec-module-namespace-exotic-objects',
77+
],
78+
['vm.Module', 'vm.html#class-vmmodule'],
79+
]);
80+
assert.deepEqual(warnings, []);
81+
});
82+
83+
it('keeps the resolvable parts of a partly unknown union', () => {
84+
assert.deepEqual(
85+
linksIn('HTTP/2 Headers Object | HTTP/2 Raw Headers', HTTP2_TYPE_MAP),
86+
[['HTTP/2 Headers Object', 'http2.html#headers-object']]
87+
);
88+
assert.deepEqual(warnings, []);
89+
});
90+
91+
it('warns when no part of an unparsable type resolves', () => {
92+
const node = resolve('HTTP/2 Raw Headers', HTTP2_TYPE_MAP);
93+
94+
assert.equal(node.data.parseError, true);
95+
assert.deepEqual(node.data.links, []);
96+
assert.deepEqual(warnings, [
97+
'Invalid type annotation: {HTTP/2 Raw Headers}',
98+
]);
99+
});
100+
101+
it('does not read `||` in default-value prose as a union', () => {
102+
const node = resolve("req.url || '/'");
103+
104+
assert.deepEqual(node.data.links, []);
105+
assert.deepEqual(warnings, ["Invalid type annotation: {req.url || '/'}"]);
106+
});
107+
108+
it('marks which values are TypeScript, for the highlighter', () => {
109+
const isTypeScript = (value, typeMap) =>
110+
resolve(value, typeMap).data.typescript;
111+
112+
assert.equal(isTypeScript('Promise<string> | null'), true);
113+
assert.equal(isTypeScript('HTTP/2 Headers Object', HTTP2_TYPE_MAP), false);
114+
assert.equal(isTypeScript('Module Namespace Object | vm.Module'), false);
115+
assert.equal(isTypeScript('HTTP/2 Raw Headers', HTTP2_TYPE_MAP), false);
116+
});
117+
118+
it('parses valid TypeScript rather than splitting it', () => {
119+
assert.deepEqual(
120+
linksIn('Promise<string> | Buffer', { Buffer: 'buffer.html#buffer' }),
121+
[
122+
[
123+
'Promise',
124+
'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise',
125+
],
126+
[
127+
'string',
128+
'https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#string_type',
129+
],
130+
['Buffer', 'buffer.html#buffer'],
131+
]
132+
);
133+
assert.deepEqual(warnings, []);
134+
});
135+
136+
it('resolves every annotation in a nested tree', () => {
137+
const STRING_URL =
138+
'https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#string_type';
139+
140+
// Two per paragraph: a visitor that skips siblings still reaches the first
141+
const nodes = ['string', 'HTTP/2 Headers Object', 'string', 'string'].map(
142+
value => ({ type: 'typeAnnotation', value })
143+
);
144+
145+
resolveTypeAnnotations(
146+
{
147+
type: 'root',
148+
children: [
149+
{ type: 'paragraph', children: nodes.slice(0, 2) },
150+
{ type: 'paragraph', children: nodes.slice(2) },
151+
],
152+
},
153+
HTTP2_TYPE_MAP,
154+
'test.md'
155+
);
156+
157+
assert.deepEqual(
158+
nodes.map(({ data }) => data.links.map(({ href }) => href)),
159+
[[STRING_URL], ['http2.html#headers-object'], [STRING_URL], [STRING_URL]]
160+
);
161+
});
162+
});

‎packages/core/src/generators/metadata/utils/__tests__/transformers.test.mjs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,4 +61,15 @@ describe('resolveTypeReference', () => {
6161
it('returns an empty string for unknown plain names', () => {
6262
strictEqual(resolveTypeReference('NotAThing'), '');
6363
});
64+
65+
it('applies the dotted heuristic to identifier paths only', () => {
66+
strictEqual(
67+
resolveTypeReference('os.constants.dlopen'),
68+
'os.html#osconstantsdlopen'
69+
);
70+
71+
for (const name of ['Buffer or fs.Stats', 'Object.<string, string>']) {
72+
strictEqual(resolveTypeReference(name), '');
73+
}
74+
});
6475
});

‎packages/core/src/generators/metadata/utils/resolveTypes.mjs‎

Lines changed: 76 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -112,52 +112,93 @@ export const parseTypeValues = values => {
112112
};
113113

114114
/**
115-
* Resolves every `typeAnnotation` node in a file's tree
115+
* Resolves a type value as a `|`-separated union of display names (e.g.
116+
* `HTTP/2 Headers Object | HTTP/2 Raw Headers`). Map keys may contain spaces
117+
* and slashes, so such values may not parse as TypeScript, but each part is
118+
* still resolvable on its own.
119+
*
120+
* @param {string} value The type value
121+
* @param {Record<string, string>} typeMap The toolchain mapping of types to links
122+
* @returns {Array<{ start: number, end: number, text: string, href: string }>} The resolved links
116123
*/
117-
export const resolveTypeAnnotations = (tree, typeMap, path) => {
118-
const pending = [];
124+
const resolveDisplayNames = (value, typeMap) => {
125+
const links = [];
119126

120-
visit(tree, 'typeAnnotation', node => {
121-
node.data = { links: [] };
127+
for (const { 0: part, index } of value.matchAll(/(?:[^|]|\|\|)+/g)) {
128+
// An array of a type links to the type itself
129+
const name = part.trim().replace(/(\[\])+$/, '');
130+
const href = name && resolveTypeReference(name, typeMap);
122131

123-
const url = lookupTypeName(node.value, typeMap);
132+
if (href) {
133+
const start = index + part.indexOf(name);
124134

125-
if (url) {
126-
node.data.links.push({
127-
start: 0,
128-
end: node.value.length,
129-
text: node.value,
130-
href: url,
131-
});
132-
} else {
133-
pending.push(node);
135+
links.push({ start, end: start + name.length, text: name, href });
134136
}
135-
});
137+
}
138+
139+
return links;
140+
};
141+
142+
/**
143+
* Resolves a type value's links: the whole value when it is a map key in its
144+
* own right, then its parsed identifiers, then its display names
145+
*
146+
* @param {string} value The type value
147+
* @param {Record<string, string>} typeMap The toolchain mapping of types to links
148+
* @param {{ error?: boolean, identifiers?: Array<object> }} result The parse of `value`
149+
* @returns {Array<{ start: number, end: number, text: string, href: string }>} The resolved links
150+
*/
151+
const resolveLinks = (value, typeMap, result) => {
152+
const url = lookupTypeName(value, typeMap);
153+
154+
if (url) {
155+
return [{ start: 0, end: value.length, text: value, href: url }];
156+
}
157+
158+
if (result.error) {
159+
return resolveDisplayNames(value, typeMap);
160+
}
136161

137-
parseTypeValues(pending.map(({ value }) => value)).forEach(
138-
(result, index) => {
139-
const node = pending[index];
162+
return (
163+
result.identifiers
164+
.map(({ start, end, text, lookup }) => ({
165+
start,
166+
end,
167+
text,
168+
href: resolveTypeReference(lookup, typeMap),
169+
}))
170+
.filter(({ href }) => href)
171+
// The hast handlers slice the value by these ranges in order
172+
.sort((a, b) => a.start - b.start)
173+
);
174+
};
140175

141-
if (result.error) {
142-
node.data.parseError = true;
176+
/**
177+
* Resolves every `typeAnnotation` node in a file's tree
178+
*/
179+
export const resolveTypeAnnotations = (tree, typeMap, path) => {
180+
const nodes = [];
143181

144-
logger.warn(`Invalid type annotation: {${node.value}}`, {
145-
file: { path, position: node.position },
146-
});
182+
// A visitor must not return a value: `visit` reads a number as the index to
183+
// continue from, which would skip siblings
184+
visit(tree, 'typeAnnotation', node => {
185+
nodes.push(node);
186+
});
147187

148-
return;
149-
}
188+
parseTypeValues(nodes.map(({ value }) => value)).forEach((result, index) => {
189+
const node = nodes[index];
190+
const links = resolveLinks(node.value, typeMap, result);
150191

151-
for (const { start, end, text, lookup } of result.identifiers) {
152-
const href = resolveTypeReference(lookup, typeMap);
192+
// Unparseable display names must not be highlighted as the TypeScript
193+
// they are not (which colours the `/` and `2` of `HTTP/2`)
194+
node.data = { links, typescript: !result.error };
153195

154-
if (href) {
155-
node.data.links.push({ start, end, text, href });
156-
}
157-
}
196+
if (result.error && !links.length) {
197+
node.data.parseError = true;
158198

159-
// The hast handlers slice the value by these ranges in order
160-
node.data.links.sort((a, b) => a.start - b.start);
199+
logger.warn(`Invalid type annotation: {${node.value}}`, {
200+
file: { path, position: node.position },
201+
});
161202
}
162-
);
203+
});
163204
};

‎packages/core/src/generators/metadata/utils/transformers.mjs‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
import { DOC_MAN_BASE_URL, DOC_API_HEADING_TYPES } from '../constants.mjs';
1+
import {
2+
DOC_MAN_BASE_URL,
3+
DOC_API_HEADING_TYPES,
4+
MODULE_QUALIFIED_NAME,
5+
} from '../constants.mjs';
26
import { slug } from './slugger.mjs';
37
import { transformNodesToString } from '../../../utils/unist.mjs';
48
import BUILTIN_TYPE_MAP from '../maps/builtin.json' with { type: 'json' };
@@ -65,7 +69,7 @@ export const resolveTypeReference = (name, typeMap) => {
6569
}
6670

6771
// Transform Node.js types like 'vm.Something'.
68-
if (name.indexOf('.') >= 0) {
72+
if (MODULE_QUALIFIED_NAME.test(name)) {
6973
const [mod, ...pieces] = name.split('.');
7074
const isClass = pieces.at(-1).match(/^[A-Z][a-z]/);
7175

0 commit comments

Comments
 (0)