|
| 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 | +}); |
0 commit comments