@dita-viewer/core 0.2.0 → 0.2.2

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 (44) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +90 -58
  3. package/dist/editor/renderContext.d.ts +7 -0
  4. package/dist/editor/renderContext.js +24 -0
  5. package/dist/editor/topicRender.d.ts +9 -0
  6. package/dist/editor/topicRender.js +4 -2
  7. package/dist/index.js +3 -3
  8. package/dist/language/ditaLanguageUtils.js +2 -0
  9. package/dist/profiling.d.ts +9 -3
  10. package/dist/profiling.js +12 -6
  11. package/dist/render/baseTypeMap.js +28 -2
  12. package/dist/render/mapTypeMap.js +23 -23
  13. package/dist/render/renderer.d.ts +24 -0
  14. package/dist/render/renderer.js +36 -9
  15. package/dist-esm/bookRender.js +145 -0
  16. package/dist-esm/completion.js +142 -0
  17. package/dist-esm/completionData.js +155 -0
  18. package/dist-esm/diagnostics.js +378 -0
  19. package/dist-esm/editor/conkeyref.js +104 -0
  20. package/dist-esm/editor/keySpace.js +201 -0
  21. package/dist-esm/editor/refResolvers.js +633 -0
  22. package/dist-esm/editor/renderContext.js +138 -0
  23. package/dist-esm/editor/sourceText.js +142 -0
  24. package/dist-esm/editor/topicRender.js +328 -0
  25. package/dist-esm/index.js +66 -0
  26. package/dist-esm/keyMapForDocument.js +23 -0
  27. package/dist-esm/language/ditaLanguageUtils.js +659 -0
  28. package/dist-esm/language/referenceableFiles.js +108 -0
  29. package/dist-esm/mapRender.js +24 -0
  30. package/dist-esm/package.json +1 -0
  31. package/dist-esm/parser/ditaParser.js +409 -0
  32. package/dist-esm/parser/domTypes.js +1 -0
  33. package/dist-esm/parser/mapTagMap.js +77 -0
  34. package/dist-esm/parser/namedEntities.js +321 -0
  35. package/dist-esm/parser/standardTagMap.js +393 -0
  36. package/dist-esm/profiling.js +224 -0
  37. package/dist-esm/render/baseTypeMap.js +1057 -0
  38. package/dist-esm/render/cjkSpacing.js +94 -0
  39. package/dist-esm/render/mapTypeMap.js +568 -0
  40. package/dist-esm/render/renderer.js +519 -0
  41. package/dist-esm/siteRender.js +261 -0
  42. package/package.json +55 -53
  43. package/styles/TOKENS.md +59 -38
  44. package/styles/dita-content.css +1171 -1157
@@ -0,0 +1,23 @@
1
+ // Host-neutral key map lookup for one document.
2
+ //
3
+ // The VS Code host builds this in editor/keyMap.ts, which also talks to the
4
+ // workspace (context map picker, caches, warnings) and so imports `vscode`.
5
+ // This is the part a host without those features needs: find the ditamaps
6
+ // near the document and resolve their key definitions, the same way the VS
7
+ // Code preview does when no context map is set.
8
+ import { dirname } from 'path';
9
+ import { collectDitamapFilesUpward } from './editor/topicRender';
10
+ import { buildKeySpace } from './editor/keySpace';
11
+ import { readSourceText } from './editor/sourceText';
12
+ /**
13
+ * The whole key space for one document: the key values, each key's resource
14
+ * target, and the map files they were read from. Diagnostics want the values
15
+ * and the files (to watch); render paths and completion want the values map.
16
+ */
17
+ export function buildKeySpaceForDocument(docFile, options) {
18
+ const maps = collectDitamapFilesUpward(dirname(docFile), options.root, options.nearestOnly ?? true);
19
+ return buildKeySpace(undefined, maps, readSourceText, options.onError);
20
+ }
21
+ export function buildKeyMapForDocument(docFile, options) {
22
+ return buildKeySpaceForDocument(docFile, options).keys;
23
+ }
@@ -0,0 +1,659 @@
1
+ // Pure, editor-agnostic logic behind the DITA language features
2
+ // (go-to-definition, completion, diagnostics, document symbols).
3
+ // Everything here works on raw text + offsets so it stays unit-testable;
4
+ // the VS Code glue lives in ditaLanguageFeatures.ts.
5
+ import { createBookRoleLabeler } from '../render/mapTypeMap';
6
+ // ── Reference attribute scanning ──
7
+ /** Attributes whose values reference other files/keys/elements. */
8
+ const REF_ATTRS = new Set(['href', 'conref', 'conkeyref', 'keyref']);
9
+ const TAG_RE = /<([A-Za-z][\w.-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
10
+ const ATTR_RE = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
11
+ /** Collects every reference-bearing attribute in the document text. */
12
+ export function collectRefEntries(text) {
13
+ const entries = [];
14
+ TAG_RE.lastIndex = 0;
15
+ let tagMatch;
16
+ while ((tagMatch = TAG_RE.exec(text)) !== null) {
17
+ const tagName = tagMatch[1];
18
+ const attrSegment = tagMatch[2];
19
+ if (!attrSegment)
20
+ continue;
21
+ const segmentOffset = tagMatch.index + 1 + tagName.length;
22
+ // First pass: pick up scope/format so hrefs can be classified
23
+ let scope;
24
+ let format;
25
+ ATTR_RE.lastIndex = 0;
26
+ let am;
27
+ while ((am = ATTR_RE.exec(attrSegment)) !== null) {
28
+ const val = am[2] ?? am[3];
29
+ if (am[1] === 'scope')
30
+ scope = val;
31
+ else if (am[1] === 'format')
32
+ format = val;
33
+ }
34
+ ATTR_RE.lastIndex = 0;
35
+ while ((am = ATTR_RE.exec(attrSegment)) !== null) {
36
+ if (!REF_ATTRS.has(am[1]))
37
+ continue;
38
+ const eqAndQuote = am[0].indexOf('=') + 1 + (am[0].slice(am[0].indexOf('=') + 1).match(/["']/)?.index ?? 0);
39
+ const valueStart = segmentOffset + am.index + eqAndQuote + 1;
40
+ const val = am[2] ?? am[3];
41
+ entries.push({
42
+ attr: am[1],
43
+ value: val,
44
+ valueStart,
45
+ valueEnd: valueStart + val.length,
46
+ tagName,
47
+ scope,
48
+ format,
49
+ });
50
+ }
51
+ }
52
+ return entries;
53
+ }
54
+ /** Finds the reference attribute whose value contains the given offset. */
55
+ export function findRefAttrAt(text, offset) {
56
+ return collectRefEntries(text).find((e) => offset >= e.valueStart && offset <= e.valueEnd);
57
+ }
58
+ const URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
59
+ const WIN_ABS_RE = /^([a-zA-Z]:[\\/]|\\\\|\/)/;
60
+ /** True when the reference points outside the local project (not resolvable from disk). */
61
+ export function isExternalRef(value, scope) {
62
+ if (!value)
63
+ return true;
64
+ if (scope === 'external' || scope === 'peer')
65
+ return true;
66
+ if (URL_SCHEME_RE.test(value))
67
+ return true;
68
+ if (WIN_ABS_RE.test(value))
69
+ return true;
70
+ return false;
71
+ }
72
+ // ── Key definition lookup ──
73
+ function escapeRegExp(s) {
74
+ return s.replace(/[.*+?^$\{\}()|[\]\\]/g, '\\$&');
75
+ }
76
+ /**
77
+ * Returns the offset of the keys="..." attribute that defines the given key
78
+ * inside a ditamap source text, or -1. A keys attribute may hold a
79
+ * space-separated list of key names.
80
+ */
81
+ export function findKeyDefinitionOffset(mapText, key) {
82
+ const re = /\bkeys\s*=\s*"([^"]*)"/g;
83
+ let m;
84
+ while ((m = re.exec(mapText)) !== null) {
85
+ const names = m[1].split(/\s+/).filter(Boolean);
86
+ if (names.includes(key))
87
+ return m.index;
88
+ }
89
+ return -1;
90
+ }
91
+ /**
92
+ * Strips the same-document marker some authors prefix onto a conref/href
93
+ * fragment -- the "./id" (or "./topicId/elementId") shorthand, carried over
94
+ * from relative-file-path conventions, that some tools accept as another
95
+ * way of writing a bare "#id". Once stripped, the rest of the fragment
96
+ * parses exactly like a plain "topicId/elementId" or bare "elementId"
97
+ * fragment. A fragment with no such prefix is returned unchanged.
98
+ *
99
+ * This is the single place that understands the "./" shorthand -- every
100
+ * caller that splits a fragment into a topic-scope part and an element-id
101
+ * part should normalize through here first, rather than special-casing
102
+ * "." locally, so the same-document marker is handled consistently
103
+ * wherever fragments are parsed (go-to-definition, find-references, and
104
+ * this file's own findConrefTargetOffset all split fragments this way).
105
+ */
106
+ export function stripSameDocumentFragmentPrefix(fragment) {
107
+ return fragment.replace(/^\.\/+/, '');
108
+ }
109
+ /**
110
+ * Splits a conref/href fragment into the two parts the DITA addressing
111
+ * grammar defines -- "topicId" or "topicId/elementId" -- after normalizing
112
+ * the "./" same-document shorthand. A one-part fragment addresses the topic
113
+ * itself, so topicId is undefined and the whole fragment is the id named.
114
+ *
115
+ * This is the single place that splits a fragment. Callers must not do their
116
+ * own split('/')[0]: that answers "which topic" when the question is nearly
117
+ * always "which element", and for the standard two-part form the two are
118
+ * different strings by definition. ditaRenderUtils resolves conref content
119
+ * this way already (parts.length > 1 ? parts[1] : parts[0]); find-references
120
+ * took parts[0] instead, which is why conrefs rendered fine but could not be
121
+ * found from their declaration.
122
+ */
123
+ export function splitRefFragment(fragment) {
124
+ const normalized = stripSameDocumentFragmentPrefix(fragment);
125
+ const slashIdx = normalized.indexOf('/');
126
+ return slashIdx >= 0
127
+ ? { topicId: normalized.substring(0, slashIdx), elementId: normalized.substring(slashIdx + 1) }
128
+ : { topicId: undefined, elementId: normalized };
129
+ }
130
+ /**
131
+ * Resolves a conref/href fragment ("topicId" or "topicId/elementId") to the
132
+ * offset of the target id="..." attribute in the target file's text, or -1.
133
+ */
134
+ export function findConrefTargetOffset(text, fragment) {
135
+ const { topicId, elementId } = splitRefFragment(fragment);
136
+ if (!elementId)
137
+ return -1;
138
+ const findId = (id, from) => {
139
+ const re = new RegExp(`\\bid\\s*=\\s*"${escapeRegExp(id)}"`, 'g');
140
+ re.lastIndex = from;
141
+ const m = re.exec(text);
142
+ return m ? m.index : -1;
143
+ };
144
+ // A bare elementId (no "/" at all) has no real topic to scope the search
145
+ // by. Before the stripSameDocumentFragmentPrefix normalization above, a
146
+ // same-document self-reference marker (e.g. conref="#./noteId") landed
147
+ // here as a literal "." topicId, which could never match a real
148
+ // id="..." and always reported the target as missing -- normalizing the
149
+ // fragment first means that case now falls into the same "no scope"
150
+ // bucket as a plain "#noteId" bare id.
151
+ if (topicId === undefined || topicId === '') {
152
+ return findId(elementId, 0);
153
+ }
154
+ const topicOff = findId(topicId, 0);
155
+ if (topicOff < 0)
156
+ return -1;
157
+ return findId(elementId, topicOff);
158
+ }
159
+ /** If the offset falls inside an id="..." attribute value, returns that id
160
+ * and the value's span; otherwise undefined. */
161
+ export function findIdAttrAt(text, offset) {
162
+ const re = /\bid\s*=\s*"([^"]*)"/g;
163
+ let m;
164
+ while ((m = re.exec(text)) !== null) {
165
+ const valueStart = m.index + m[0].indexOf('"') + 1;
166
+ const valueEnd = valueStart + m[1].length;
167
+ if (offset >= valueStart && offset <= valueEnd) {
168
+ return { id: m[1], valueStart, valueEnd };
169
+ }
170
+ }
171
+ return undefined;
172
+ }
173
+ /** If the offset falls inside one key of a keydef's keys="..." attribute
174
+ * value, returns that specific key token (not the whole space-separated
175
+ * list) and its span; otherwise undefined. Only matches on a <keydef> (or
176
+ * <topicref>/<mapref> carrying its own keys attribute) tag, not any other
177
+ * element that happens to have a "keys" attribute. */
178
+ export function findKeysAttrAt(text, offset) {
179
+ const re = /\bkeys\s*=\s*"([^"]*)"/g;
180
+ let m;
181
+ while ((m = re.exec(text)) !== null) {
182
+ const listStart = m.index + m[0].indexOf('"') + 1;
183
+ const listEnd = listStart + m[1].length;
184
+ if (offset < listStart || offset > listEnd)
185
+ continue;
186
+ const relOffset = offset - listStart;
187
+ let tokenStart = 0;
188
+ for (const token of m[1].split(/(\s+)/)) {
189
+ const tokenEnd = tokenStart + token.length;
190
+ if (!/^\s*$/.test(token) && relOffset >= tokenStart && relOffset <= tokenEnd) {
191
+ return { key: token, valueStart: listStart + tokenStart, valueEnd: listStart + tokenEnd };
192
+ }
193
+ tokenStart = tokenEnd;
194
+ }
195
+ return undefined;
196
+ }
197
+ return undefined;
198
+ }
199
+ /** If the offset falls ANYWHERE inside a <keydef> element -- not just
200
+ * literally inside its keys="..." attribute value the way findKeysAttrAt
201
+ * above requires -- returns every key that keydef declares.
202
+ *
203
+ * This exists specifically for Find All References: clicking on some
204
+ * OTHER part of a keydef (its <keyword> display text, its href, its
205
+ * topicmeta, whitespace inside a multi-line keydef) is an easy mistake
206
+ * for someone unfamiliar with the extension to make when trying to find
207
+ * where a key is used -- especially the keyword text, which is the
208
+ * human-readable label a reader would naturally click on. Silently
209
+ * falling through to the generic "who references this ditamap file"
210
+ * answer in that case is actively confusing: it still returns results,
211
+ * so it looks like it worked, but it answers a different question than
212
+ * the one being asked. findKeysAttrAt's narrower, attribute-value-only
213
+ * match still takes priority when it hits (see ditaLanguageFeatures.ts'
214
+ * resolveReferenceTarget) so clicking the exact key name still resolves
215
+ * to just that one key rather than every alias on the keydef. */
216
+ export function findEnclosingKeydefKeys(text, offset) {
217
+ const tagRe = /<keydef\b[^>]*>/g;
218
+ let m;
219
+ while ((m = tagRe.exec(text)) !== null) {
220
+ const tagStart = m.index;
221
+ const tagText = m[0];
222
+ const selfClosing = /\/\s*>$/.test(tagText);
223
+ let elementEnd;
224
+ if (selfClosing) {
225
+ elementEnd = tagStart + tagText.length;
226
+ }
227
+ else {
228
+ const closeTag = '</keydef>';
229
+ const closeIdx = text.indexOf(closeTag, tagStart + tagText.length);
230
+ elementEnd = closeIdx >= 0 ? closeIdx + closeTag.length : tagStart + tagText.length;
231
+ }
232
+ if (offset < tagStart || offset > elementEnd)
233
+ continue;
234
+ const keysMatch = /\bkeys\s*=\s*"([^"]*)"/.exec(tagText);
235
+ if (!keysMatch)
236
+ return undefined;
237
+ const keys = keysMatch[1].split(/\s+/).filter(Boolean);
238
+ return keys.length ? { keys } : undefined;
239
+ }
240
+ return undefined;
241
+ }
242
+ /** Collects all id="..." values declared in a document text. */
243
+ export function collectIds(text) {
244
+ const ids = [];
245
+ const re = /\bid\s*=\s*"([^"]+)"/g;
246
+ let m;
247
+ while ((m = re.exec(text)) !== null)
248
+ ids.push(m[1]);
249
+ return ids;
250
+ }
251
+ /** Converts a character offset into a 0-based line/column pair. */
252
+ export function offsetToLineCol(text, offset) {
253
+ let line = 0;
254
+ let lineStart = 0;
255
+ for (let i = 0; i < offset && i < text.length; i++) {
256
+ if (text.charCodeAt(i) === 10) {
257
+ line++;
258
+ lineStart = i + 1;
259
+ }
260
+ }
261
+ return { line, col: offset - lineStart };
262
+ }
263
+ /** Classifies what kind of completion applies at the given offset. */
264
+ export function getCompletionContext(text, offset) {
265
+ const lastLt = text.lastIndexOf('<', offset - 1);
266
+ if (lastLt < 0)
267
+ return { kind: 'none' };
268
+ const between = text.substring(lastLt, offset);
269
+ // Comments / processing instructions / closed tags → no structural completion
270
+ if (between.includes('>') || between.startsWith('<!') || between.startsWith('<?')) {
271
+ return { kind: 'none' };
272
+ }
273
+ // Still typing the tag name itself: "<", "<no", "</se"
274
+ const tagTyping = /^<(\/?)([\w.-]*)$/.exec(between);
275
+ if (tagTyping)
276
+ return { kind: 'tag', prefix: tagTyping[2], closing: tagTyping[1] === '/' };
277
+ const tagNameMatch = /^<\/?([\w.-]+)/.exec(between);
278
+ const tagName = tagNameMatch ? tagNameMatch[1] : undefined;
279
+ // Inside an attribute value: attr="partial
280
+ const valueMatch = /([\w:.-]+)\s*=\s*"([^"]*)$/.exec(between);
281
+ if (valueMatch) {
282
+ return {
283
+ kind: 'attrValue',
284
+ tagName,
285
+ attrName: valueMatch[1],
286
+ prefix: valueMatch[2],
287
+ valueStart: offset - valueMatch[2].length,
288
+ };
289
+ }
290
+ // After whitespace inside the tag → attribute name position
291
+ if (/[\s"']([\w:.-]*)$/.test(between)) {
292
+ const anm = /([\w:.-]*)$/.exec(between);
293
+ return { kind: 'attrName', tagName, prefix: anm ? anm[1] : '' };
294
+ }
295
+ return { kind: 'none' };
296
+ }
297
+ // ── Tag auto-closing ──
298
+ /**
299
+ * When the character just typed before `offset` is the '>' of an opening
300
+ * tag, returns the tag name to auto-close. Closing tags, self-closing tags,
301
+ * comments, PIs and '>' inside attribute values yield undefined.
302
+ */
303
+ export function getAutoCloseTag(text, offset) {
304
+ if (text[offset - 1] !== '>')
305
+ return undefined;
306
+ const lastLt = text.lastIndexOf('<', offset - 2);
307
+ if (lastLt < 0)
308
+ return undefined;
309
+ const tagText = text.substring(lastLt, offset);
310
+ if (tagText.startsWith('</') || tagText.startsWith('<!') || tagText.startsWith('<?')) {
311
+ return undefined;
312
+ }
313
+ if (/\/\s*>$/.test(tagText))
314
+ return undefined;
315
+ // An odd number of quotes means the '>' was typed inside an attribute value
316
+ if (((tagText.match(/"/g) || []).length) % 2 === 1)
317
+ return undefined;
318
+ const m = /^<([A-Za-z][\w.-]*)(?:[\s>]|$)/.exec(tagText);
319
+ return m ? m[1] : undefined;
320
+ }
321
+ /** Innermost tag left unclosed at the end of the given text. */
322
+ export function findUnclosedTag(text) {
323
+ // Strip constructs whose content must not feed the tag stack
324
+ const cleaned = text
325
+ .replace(/<!--[\s\S]*?-->/g, ' ')
326
+ .replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, ' ')
327
+ .replace(/<\?[\s\S]*?\?>/g, ' ')
328
+ .replace(/<![^>]*>/g, ' ');
329
+ const stack = [];
330
+ const re = /<(\/?)([A-Za-z][\w.-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
331
+ let m;
332
+ while ((m = re.exec(cleaned)) !== null) {
333
+ if (m[1]) {
334
+ // Pop down to the matching open tag (tolerates malformed nesting)
335
+ const idx = stack.lastIndexOf(m[2]);
336
+ if (idx >= 0)
337
+ stack.length = idx;
338
+ }
339
+ else if (!/\/\s*$/.test(m[3])) {
340
+ stack.push(m[2]);
341
+ }
342
+ }
343
+ return stack[stack.length - 1];
344
+ }
345
+ /**
346
+ * When the two characters ending at `offset` are '</', returns the tag name
347
+ * that completes the closing tag, or undefined.
348
+ */
349
+ export function getCloseTagCompletion(text, offset) {
350
+ if (text.substring(offset - 2, offset) !== '</')
351
+ return undefined;
352
+ return findUnclosedTag(text.substring(0, offset - 2));
353
+ }
354
+ // ── Attribute knowledge for completion ──
355
+ const UNIVERSAL_ATTRS = [
356
+ 'id',
357
+ 'conref',
358
+ 'conkeyref',
359
+ 'keyref',
360
+ 'outputclass',
361
+ 'props',
362
+ 'audience',
363
+ 'platform',
364
+ 'product',
365
+ 'otherprops',
366
+ 'deliveryTarget',
367
+ 'rev',
368
+ 'importance',
369
+ 'translate',
370
+ 'xml:lang',
371
+ ];
372
+ const REF_TAG_ATTRS = ['href', 'keys', 'keyref', 'navtitle', 'format', 'scope', 'processing-role', 'toc', 'type', 'collection-type'];
373
+ export const TAG_SPECIFIC_ATTRS = {
374
+ xref: ['href', 'format', 'scope', 'type'],
375
+ link: ['href', 'format', 'scope', 'type'],
376
+ image: ['href', 'height', 'width', 'placement', 'align', 'scale'],
377
+ note: ['type', 'othertype'],
378
+ topicref: REF_TAG_ATTRS,
379
+ keydef: ['keys', 'href', 'format', 'scope', 'processing-role'],
380
+ mapref: ['href', 'format', 'processing-role'],
381
+ chapter: REF_TAG_ATTRS,
382
+ part: REF_TAG_ATTRS,
383
+ appendix: REF_TAG_ATTRS,
384
+ preface: REF_TAG_ATTRS,
385
+ glossaryref: REF_TAG_ATTRS,
386
+ topichead: ['navtitle', 'collection-type'],
387
+ table: ['frame', 'colsep', 'rowsep', 'pgwide'],
388
+ tgroup: ['cols'],
389
+ colspec: ['colname', 'colwidth', 'colnum'],
390
+ entry: ['colname', 'namest', 'nameend', 'morerows', 'valign', 'align'],
391
+ codeblock: ['outputclass', 'scale'],
392
+ ph: ['keyref'],
393
+ keyword: ['keyref'],
394
+ term: ['keyref'],
395
+ lq: ['href', 'reftitle'],
396
+ fig: ['frame', 'expanse'],
397
+ section: ['spectitle'],
398
+ };
399
+ /** Attribute names offered for a tag: tag-specific first, then universal. */
400
+ export function getAttributesForTag(tag) {
401
+ const specific = tag ? TAG_SPECIFIC_ATTRS[tag] || [] : [];
402
+ const merged = [...specific];
403
+ for (const a of UNIVERSAL_ATTRS)
404
+ if (!merged.includes(a))
405
+ merged.push(a);
406
+ return merged;
407
+ }
408
+ function plainText(node) {
409
+ if (node.type === 'text')
410
+ return node.text || '';
411
+ return (node.children || []).map(plainText).join('');
412
+ }
413
+ function findTitleText(node) {
414
+ const titleChild = (node.children || []).find((c) => c.type === 'element' && c.baseType === 'topic/title');
415
+ if (!titleChild)
416
+ return undefined;
417
+ const t = plainText(titleChild).trim();
418
+ return t || undefined;
419
+ }
420
+ /** Outline for a .dita topic file: topics, sections and examples. */
421
+ // Topic specializations are recognized by tag name too: authored source
422
+ // files carry no @class attribute, so their baseType stays undefined.
423
+ const TOPIC_ROOT_TAGS = new Set([
424
+ 'topic',
425
+ 'concept',
426
+ 'task',
427
+ 'reference',
428
+ 'glossentry',
429
+ 'glossgroup',
430
+ 'troubleshooting',
431
+ ]);
432
+ function isTopicNode(node) {
433
+ return node.baseType === 'topic/topic' || (!!node.tagName && TOPIC_ROOT_TAGS.has(node.tagName));
434
+ }
435
+ export function collectTopicSymbols(root) {
436
+ function walk(node) {
437
+ const result = [];
438
+ for (const child of node.children || []) {
439
+ if (child.type !== 'element')
440
+ continue;
441
+ const bt = child.baseType;
442
+ if (isTopicNode(child)) {
443
+ result.push({
444
+ name: findTitleText(child) || child.attributes?.id || '(topic)',
445
+ detail: child.tagName,
446
+ kind: 'topic',
447
+ range: child.sourceRange,
448
+ children: walk(child),
449
+ });
450
+ }
451
+ else if (bt === 'topic/section' || bt === 'topic/example') {
452
+ result.push({
453
+ name: findTitleText(child) || (bt === 'topic/example' ? '(example)' : '(section)'),
454
+ detail: child.tagName,
455
+ kind: 'section',
456
+ range: child.sourceRange,
457
+ children: walk(child),
458
+ });
459
+ }
460
+ else {
461
+ result.push(...walk(child));
462
+ }
463
+ }
464
+ return result;
465
+ }
466
+ // The root topic itself is represented too, so breadcrumbs show it
467
+ if (isTopicNode(root)) {
468
+ return [
469
+ {
470
+ name: findTitleText(root) || root.attributes?.id || '(topic)',
471
+ detail: root.tagName,
472
+ kind: 'topic',
473
+ range: root.sourceRange,
474
+ children: walk(root),
475
+ },
476
+ ];
477
+ }
478
+ return walk(root);
479
+ }
480
+ /** Display name for a map reference node (navtitle > linktext > href > keys). */
481
+ export function getMapRefName(node) {
482
+ const topicmeta = (node.children || []).find((c) => c.type === 'element' && c.baseType === 'map/topicmeta');
483
+ if (topicmeta) {
484
+ for (const bt of ['map/navtitle', 'map/linktext']) {
485
+ const child = (topicmeta.children || []).find((c) => c.type === 'element' && c.baseType === bt);
486
+ if (child) {
487
+ const t = plainText(child).trim();
488
+ if (t)
489
+ return t;
490
+ }
491
+ }
492
+ }
493
+ const navtitleAttr = node.attributes?.navtitle;
494
+ if (navtitleAttr)
495
+ return navtitleAttr;
496
+ const href = node.attributes?.href;
497
+ if (href)
498
+ return href;
499
+ const keys = node.attributes?.keys;
500
+ if (keys)
501
+ return keys;
502
+ return '(unnamed)';
503
+ }
504
+ /** Outline for a .ditamap file: topicref hierarchy with structural containers. */
505
+ export function collectMapSymbols(root, roleFormat) {
506
+ const roleLabel = createBookRoleLabeler(roleFormat);
507
+ function walk(node, depth) {
508
+ const result = [];
509
+ for (const child of node.children || []) {
510
+ if (child.type !== 'element')
511
+ continue;
512
+ const bt = child.baseType;
513
+ if (bt === 'map/topicref' || bt === 'map/mapref') {
514
+ // Book divisions surface their numbered role ("Chapter 1", …)
515
+ const label = roleLabel(child.tagName, depth);
516
+ result.push({
517
+ name: getMapRefName(child),
518
+ detail: label || child.tagName,
519
+ kind: 'ref',
520
+ range: child.sourceRange,
521
+ children: walk(child, depth + 1),
522
+ });
523
+ }
524
+ else if (bt === 'map/keydef') {
525
+ result.push({
526
+ name: child.attributes?.keys || '(keydef)',
527
+ detail: child.tagName,
528
+ kind: 'keydef',
529
+ range: child.sourceRange,
530
+ children: walk(child, depth + 1),
531
+ });
532
+ }
533
+ else if (bt === 'map/topichead') {
534
+ result.push({
535
+ name: getMapRefName(child),
536
+ detail: child.tagName,
537
+ kind: 'head',
538
+ range: child.sourceRange,
539
+ children: walk(child, depth + 1),
540
+ });
541
+ }
542
+ else if (bt === 'map/bookmap-structural') {
543
+ result.push({
544
+ name: child.tagName || '(container)',
545
+ kind: 'structural',
546
+ range: child.sourceRange,
547
+ children: walk(child, depth),
548
+ });
549
+ }
550
+ else if (bt === 'map/reltable') {
551
+ continue;
552
+ }
553
+ else {
554
+ result.push(...walk(child, depth));
555
+ }
556
+ }
557
+ return result;
558
+ }
559
+ return walk(root, 0);
560
+ }
561
+ // Base types whose own renderer takes full, exclusive ownership of its
562
+ // subtree instead of generically dispatching to each child by its own
563
+ // baseType. An unmapped tag name underneath one of these causes no silent
564
+ // content loss -- the reason this diagnostic exists at all -- because
565
+ // nothing under them is shown via the generic per-child path regardless of
566
+ // whether the parser could classify it:
567
+ //
568
+ // - topic/foreign (<foreign>, <mathml>, and this project's 'svg-container'
569
+ // convenience mapping in standardTagMap.ts): BASE_TYPE_RENDERERS in
570
+ // baseTypeMap.ts serializes its children as raw markup directly, without
571
+ // ever consulting each descendant's own baseType. Every MathML/SVG tag
572
+ // underneath is correctly unrecognized by parseBaseType() -- that is the
573
+ // point, it is not DITA -- so walking in and reporting its contents would
574
+ // just relabel valid MathML/SVG markup as "unknown DITA elements".
575
+ // - topic/prolog: its renderer (baseTypeMap.ts) extracts only top-level
576
+ // indexterm chips via a dedicated traversal and returns '' for
577
+ // everything else -- by its own comment, "every OTHER prolog descendant
578
+ // ... is still fully suppressed". author, critdate, metadata, audience,
579
+ // keywords and the rest of DITA's prolog vocabulary are real, valid,
580
+ // commonly-used elements; several (metadata, keywords, navtitle, author,
581
+ // critdate, ...) simply have no entry of their own in standardTagMap.ts,
582
+ // because nothing before this diagnostic ever needed one -- prolog's own
583
+ // renderer already hides the entire subtree, mapped or not.
584
+ // - map/topicmeta: the same shape one level up, for maps -- its renderer
585
+ // (mapTypeMap.ts) also returns '' unconditionally, with the topicref's
586
+ // navtitle/keyword text pulled out separately via getNodeText() rather
587
+ // than the generic per-child dispatch. indexterm is valid inside a map's
588
+ // <topicmeta><keywords> (DITA maps reuse several topic-level metadata
589
+ // elements verbatim) but was never given its own entry in mapTagMap.ts
590
+ // for the same reason: nothing needed it before.
591
+ // - map/map-title: the map's own <title> (and <booktitle>/<mainbooktitle>/
592
+ // <booktitlealt>/<subtitle>, which specialize the same base type) is
593
+ // rendered by extractText() -- a dedicated, baseType-agnostic recursive
594
+ // text walk with its own <ph keyref="..."> substitution built in, not
595
+ // the generic per-child dispatch either. Nothing under a map's <title>
596
+ // goes missing for being unmapped: extractText() walks every descendant
597
+ // by its .children/.text shape alone and does not consult baseType at
598
+ // all, which is exactly why a keyref-only <ph/> in a map title already
599
+ // resolves correctly -- and why flagging it here was never accurate.
600
+ //
601
+ // Skipping these four is about what the renderer actually does with a
602
+ // subtree, not about the elements in it being any less real or valid DITA
603
+ // than a <p> or a <note> -- unlike topic/foreign, which is correctly
604
+ // non-DITA content.
605
+ const SUBTREE_OWNED_BASETYPES = new Set([
606
+ 'topic/foreign',
607
+ 'topic/prolog',
608
+ 'map/topicmeta',
609
+ 'map/map-title',
610
+ // topic/indexterm's own renderer (collectIndextermChips() in
611
+ // baseTypeMap.ts) walks node.children itself -- direct text nodes plus
612
+ // nested topic/indexterm, topic/index-see and topic/index-see-also by
613
+ // baseType -- and never dispatches through the generic recursive
614
+ // renderer for anything else, so an unmapped tag anywhere inside an
615
+ // indexterm causes no additional silent content loss to report here.
616
+ // topic/index-see-also (and its siblings, all only ever valid inside an
617
+ // indexterm) are included defensively for the case where the enclosing
618
+ // indexterm itself failed to classify and so was not skipped.
619
+ 'topic/indexterm',
620
+ 'topic/index-see',
621
+ 'topic/index-see-also',
622
+ 'topic/index-sort-as',
623
+ 'topic/index-base',
624
+ // map/relheader falls back to a baseType-agnostic extractText() walk for
625
+ // a relcolspec's column title whenever @navtitle is absent (mapTypeMap.ts)
626
+ // -- same shape as map/map-title above, content is never actually lost.
627
+ 'map/relcolspec',
628
+ ]);
629
+ /**
630
+ * Walks a parsed document and collects every element the parser fell
631
+ * through on: neither its tag name nor an explicit @class attribute (DITA's
632
+ * own mechanism for a specialized element to say what it specializes)
633
+ * resolved to a known base type. renderEffectiveNode() in renderer.ts
634
+ * treats exactly this case as "render the children, drop the element" --
635
+ * silently, with no visual indication -- so from the reader's side a typo
636
+ * here looks identical to the content simply not being there. Reusing
637
+ * node.baseType, already computed by the same parseBaseType() the renderer
638
+ * itself relies on, means this can never disagree with what actually gets
639
+ * dropped: there is one source of truth for "does DITA Viewer recognize
640
+ * this element", not a second copy of the classification logic that could
641
+ * drift from it.
642
+ */
643
+ export function collectUnknownElements(root) {
644
+ const results = [];
645
+ function walk(node) {
646
+ if (node.type !== 'element')
647
+ return;
648
+ if (node.baseType && SUBTREE_OWNED_BASETYPES.has(node.baseType))
649
+ return;
650
+ if (!node.baseType && node.tagName) {
651
+ results.push({ tagName: node.tagName, sourceRange: node.sourceRange });
652
+ }
653
+ for (const child of node.children) {
654
+ walk(child);
655
+ }
656
+ }
657
+ walk(root);
658
+ return results;
659
+ }