@hia-doc/renderer-html 0.1.0 → 0.1.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.
package/dist/index.js CHANGED
@@ -11,6 +11,16 @@ export const HIA_PROJECT_NAVIGATION_INDEX_CONTRACT = "hia-project-navigation-ind
11
11
  * First draft version of the project navigation index; independent from the renderer manifest file-list version.
12
12
  */
13
13
  export const HIA_PROJECT_NAVIGATION_INDEX_CONTRACT_VERSION = "0.1.0-draft";
14
+ /**
15
+ * 项目级关系图的中性 contract 名称;用于表达文档入口、源码、生成物与宿主能力之间的关系。
16
+ * Neutral project-level relation-graph contract for documentation entries, sources, generated artifacts, and host capabilities.
17
+ */
18
+ export const HIA_PROJECT_RELATION_GRAPH_CONTRACT = "hia-project-relation-graph";
19
+ /**
20
+ * 项目级关系图的首个草案版本;后续 IDE/DevTools host 会按此 contract 做能力协商。
21
+ * First draft version of the project relation graph; future IDE/DevTools hosts negotiate capabilities against this contract.
22
+ */
23
+ export const HIA_PROJECT_RELATION_GRAPH_CONTRACT_VERSION = "0.1.0-draft";
14
24
  export function renderHtmlDocument(document, options = {}) {
15
25
  const pageTitle = options.title ?? document.title;
16
26
  const includeThemeAssets = options.includeThemeAssets ?? true;
@@ -39,23 +49,28 @@ export function renderHtmlDocument(document, options = {}) {
39
49
  };
40
50
  }
41
51
  export function renderProjectHtmlDocument(projectInput, options = {}) {
42
- const pageTitle = options.title ?? projectInput.project.title ?? projectInput.project.name;
52
+ const sourcePreparedProjectInput = applyProjectSourcePresentationPolicy(projectInput, options);
53
+ const normalizedProjectInput = normalizeProjectRelationGraphInput(sourcePreparedProjectInput);
54
+ const pageTitle = options.title ?? normalizedProjectInput.project.title ?? normalizedProjectInput.project.name;
43
55
  const includeThemeAssets = options.includeThemeAssets ?? true;
44
- const navigationIndex = createProjectNavigationIndex(projectInput, pageTitle, options);
45
- const files = [
46
- {
47
- path: "index.html",
48
- contents: renderProjectIndexHtml(pageTitle, projectInput, options),
49
- contentType: "text/html; charset=utf-8",
50
- role: "entry"
51
- },
52
- {
53
- path: "project-index.json",
54
- contents: `${JSON.stringify(navigationIndex, null, 2)}\n`,
55
- contentType: "application/json; charset=utf-8",
56
- role: "index"
57
- }
58
- ];
56
+ const siteLayout = options.projectSite?.layout ?? "split-site";
57
+ const navigationIndex = createProjectNavigationIndex(normalizedProjectInput, pageTitle, options);
58
+ const files = siteLayout === "single-page"
59
+ ? [
60
+ {
61
+ path: "index.html",
62
+ contents: renderProjectIndexHtml(pageTitle, normalizedProjectInput, options),
63
+ contentType: "text/html; charset=utf-8",
64
+ role: "entry"
65
+ }
66
+ ]
67
+ : createProjectSplitSiteFiles(pageTitle, normalizedProjectInput, navigationIndex, options);
68
+ files.push({
69
+ path: "project-index.json",
70
+ contents: `${JSON.stringify(navigationIndex, null, 2)}\n`,
71
+ contentType: "application/json; charset=utf-8",
72
+ role: "index"
73
+ });
59
74
  if (includeThemeAssets) {
60
75
  for (const asset of getDefaultThemeAssets()) {
61
76
  files.push({
@@ -68,8 +83,40 @@ export function renderProjectHtmlDocument(projectInput, options = {}) {
68
83
  }
69
84
  return {
70
85
  files,
71
- diagnostics: projectInput.diagnostics ?? [],
72
- manifest: createProjectManifest(projectInput, files, pageTitle, options, navigationIndex)
86
+ diagnostics: normalizedProjectInput.diagnostics ?? [],
87
+ manifest: createProjectManifest(normalizedProjectInput, files, pageTitle, options, navigationIndex)
88
+ };
89
+ }
90
+ /**
91
+ * 在 renderer 公共入口执行源码呈现边界,保证直接库调用与 CLI 调用具有同一隐私语义。
92
+ * Enforces source-presentation boundaries at the renderer API so direct library and CLI calls share the same privacy semantics.
93
+ */
94
+ function applyProjectSourcePresentationPolicy(projectInput, options) {
95
+ const presentation = options.projectSite?.source?.presentation ?? "link";
96
+ return {
97
+ ...projectInput,
98
+ entries: projectInput.entries.map((entry) => {
99
+ if (!entry.source) {
100
+ return entry;
101
+ }
102
+ const { preview, fetchUrl, linkUrl, ...locator } = entry.source;
103
+ const previewDefaultExpanded = options.projectSite?.source?.defaultExpanded ?? preview?.defaultExpanded;
104
+ const source = {
105
+ ...locator,
106
+ ...(presentation !== "none" && linkUrl ? { linkUrl } : {}),
107
+ ...(presentation === "embed" && preview ? {
108
+ preview: {
109
+ ...preview,
110
+ ...(previewDefaultExpanded !== undefined ? { defaultExpanded: previewDefaultExpanded } : {})
111
+ }
112
+ } : {}),
113
+ ...(presentation === "fetch" && fetchUrl ? { fetchUrl } : {})
114
+ };
115
+ return {
116
+ ...entry,
117
+ source
118
+ };
119
+ })
73
120
  };
74
121
  }
75
122
  function createManifest(document, files, options) {
@@ -117,7 +164,18 @@ function createProjectManifest(projectInput, files, pageTitle, options, navigati
117
164
  path: "project-index.json"
118
165
  },
119
166
  ...(projectInput.profiles && projectInput.profiles.length > 0 ? { profiles: projectInput.profiles } : {}),
120
- ...(projectInput.docSourceMaps && projectInput.docSourceMaps.length > 0 ? { docSourceMaps: projectInput.docSourceMaps } : {})
167
+ ...(projectInput.docSourceMaps && projectInput.docSourceMaps.length > 0 ? { docSourceMaps: projectInput.docSourceMaps } : {}),
168
+ ...(projectInput.relationGraph && projectInput.relationGraph.relationCount > 0
169
+ ? {
170
+ relationGraph: {
171
+ contract: projectInput.relationGraph.contract,
172
+ contractVersion: projectInput.relationGraph.contractVersion,
173
+ nodeCount: projectInput.relationGraph.nodeCount,
174
+ relationCount: projectInput.relationGraph.relationCount,
175
+ path: "project-index.json"
176
+ }
177
+ }
178
+ : {})
121
179
  }
122
180
  };
123
181
  }
@@ -149,12 +207,130 @@ function createProjectNavigationIndex(projectInput, pageTitle, options) {
149
207
  ...(entry.input ? { input: entry.input } : {}),
150
208
  ...(entry.source ? { source: omitProjectSourcePreview(entry.source) } : {}),
151
209
  ...(entry.symbolId ? { symbolId: entry.symbolId } : {}),
210
+ ...(entry.hierarchy ? { hierarchy: entry.hierarchy } : {}),
211
+ contentPath: createProjectEntryContentPath(entry.id),
152
212
  ...(entry.docSourceMap ? { docSourceMap: entry.docSourceMap } : {})
153
213
  }))
154
214
  .sort(compareProjectNavigationEntries),
215
+ groups: collectProjectNavigationGroups(projectInput.entries),
216
+ navigationTree: collectProjectNavigationTree(projectInput.entries),
155
217
  profiles: [...(projectInput.profiles ?? [])].sort(compareProjectProfiles),
156
- docSourceMaps: [...(projectInput.docSourceMaps ?? [])].sort(compareProjectDocSourceMaps)
218
+ docSourceMaps: [...(projectInput.docSourceMaps ?? [])].sort(compareProjectDocSourceMaps),
219
+ site: {
220
+ layout: options.projectSite?.layout ?? "split-site",
221
+ ...(options.projectSite?.layout === "single-page" ? {} : {
222
+ navigationRootPath: "navigation/root.json",
223
+ searchIndexPath: "search/index.json",
224
+ relationIndexPath: "relations/project.json"
225
+ }),
226
+ sourcePresentation: options.projectSite?.source?.presentation ?? "link"
227
+ },
228
+ ...(projectInput.relationGraph && projectInput.relationGraph.relationCount > 0
229
+ ? { relationGraph: projectInput.relationGraph }
230
+ : {})
231
+ };
232
+ }
233
+ /**
234
+ * 生成大型项目默认使用的 split-site 文件集合;入口页只保留应用壳。
235
+ * Generates the split-site file set used by large projects by default; the entry page only keeps the application shell.
236
+ */
237
+ function createProjectSplitSiteFiles(pageTitle, projectInput, navigationIndex, options) {
238
+ const localeModel = resolveProjectLocaleModel(projectInput, options.locale);
239
+ const files = [
240
+ {
241
+ path: "index.html",
242
+ contents: renderProjectSplitSiteHtml(pageTitle, projectInput, options),
243
+ contentType: "text/html; charset=utf-8",
244
+ role: "entry"
245
+ },
246
+ ...createProjectNavigationShardFiles(navigationIndex.navigationTree),
247
+ {
248
+ path: "search/index.json",
249
+ contents: `${JSON.stringify({
250
+ contract: "hia-project-search-index",
251
+ contractVersion: "0.1.0-draft",
252
+ entries: projectInput.entries.map((entry) => ({
253
+ id: entry.id,
254
+ name: entry.name,
255
+ kind: entry.kind,
256
+ view: entry.view,
257
+ contentPath: createProjectEntryContentPath(entry.id),
258
+ searchText: createProjectEntrySearchText(entry)
259
+ }))
260
+ }, null, 2)}\n`,
261
+ contentType: "application/json; charset=utf-8",
262
+ role: "index"
263
+ },
264
+ {
265
+ path: "relations/project.json",
266
+ contents: `${JSON.stringify(projectInput.relationGraph ?? createProjectRelationGraph(projectInput.entries), null, 2)}\n`,
267
+ contentType: "application/json; charset=utf-8",
268
+ role: "index"
269
+ }
270
+ ];
271
+ for (const entry of projectInput.entries) {
272
+ files.push({
273
+ path: createProjectEntryContentPath(entry.id),
274
+ contents: renderProjectEntry(entry, localeModel.locales, localeModel.selectedLocale),
275
+ contentType: "text/html; charset=utf-8",
276
+ role: "asset"
277
+ });
278
+ }
279
+ return files;
280
+ }
281
+ function createProjectNavigationShardFiles(nodes) {
282
+ const files = [];
283
+ const emittedPaths = new Set();
284
+ const emitChildren = (nodeId, children, root = false) => {
285
+ const shardPath = root ? "navigation/root.json" : createProjectNavigationChildrenPath(nodeId);
286
+ if (emittedPaths.has(shardPath)) {
287
+ return;
288
+ }
289
+ emittedPaths.add(shardPath);
290
+ files.push({
291
+ path: shardPath,
292
+ contents: `${JSON.stringify({
293
+ contract: "hia-project-navigation-shard",
294
+ contractVersion: "0.1.0-draft",
295
+ nodeId,
296
+ children: children.map(toLazyProjectNavigationNode)
297
+ }, null, 2)}\n`,
298
+ contentType: "application/json; charset=utf-8",
299
+ role: "index"
300
+ });
301
+ for (const child of children) {
302
+ if (child.children && child.children.length > 0) {
303
+ emitChildren(child.id, child.children);
304
+ }
305
+ }
157
306
  };
307
+ emitChildren("root", nodes, true);
308
+ return files;
309
+ }
310
+ function toLazyProjectNavigationNode(node) {
311
+ const { children: _children, ...lazyNode } = node;
312
+ return {
313
+ ...lazyNode,
314
+ ...(node.children && node.children.length > 0
315
+ ? { childrenPath: createProjectNavigationChildrenPath(node.id) }
316
+ : {}),
317
+ ...(node.entryId ? { contentPath: createProjectEntryContentPath(node.entryId) } : {})
318
+ };
319
+ }
320
+ function createProjectEntryContentPath(entryId) {
321
+ return `entries/${stableProjectArtifactName(entryId)}.html`;
322
+ }
323
+ function createProjectNavigationChildrenPath(nodeId) {
324
+ return `navigation/${stableProjectArtifactName(nodeId)}.json`;
325
+ }
326
+ function stableProjectArtifactName(value) {
327
+ let hash = 2166136261;
328
+ for (const character of value) {
329
+ hash ^= character.codePointAt(0) ?? 0;
330
+ hash = Math.imul(hash, 16777619);
331
+ }
332
+ const slug = value.toLowerCase().replace(/[^a-z0-9._-]+/gu, "-").replace(/^-|-$/gu, "").slice(0, 72) || "item";
333
+ return `${slug}-${(hash >>> 0).toString(16).padStart(8, "0")}`;
158
334
  }
159
335
  function omitProjectSourcePreview(source) {
160
336
  const { preview: _preview, ...sourceWithoutPreview } = source;
@@ -205,11 +381,261 @@ function renderIndexHtml(pageTitle, document, options) {
205
381
  "</html>"
206
382
  ].join("");
207
383
  }
384
+ function renderProjectSplitSiteHtml(pageTitle, projectInput, options) {
385
+ const projectName = projectInput.project.title ?? projectInput.project.name;
386
+ const localeModel = resolveProjectLocaleModel(projectInput, options.locale);
387
+ const views = collectProjectViews(projectInput.entries);
388
+ const entryCounts = countEntriesByView(projectInput.entries);
389
+ const selectedChinese = localeModel.selectedLocale.toLowerCase().startsWith("zh");
390
+ const labels = selectedChinese
391
+ ? {
392
+ hierarchy: "层级导航",
393
+ loading: "正在加载文档导航...",
394
+ open: "打开",
395
+ relations: "项目关系",
396
+ select: "请从左侧层级树选择一个文档节点。",
397
+ search: "搜索",
398
+ searchPlaceholder: "名称、类型、源码或选择器",
399
+ requiresServer: "按需加载站点需要通过 HTTP(S) 提供;请使用本地静态服务器打开该目录。"
400
+ }
401
+ : {
402
+ hierarchy: "Hierarchy",
403
+ loading: "Loading documentation navigation...",
404
+ open: "Open",
405
+ relations: "Project relations",
406
+ select: "Select a documentation node from the hierarchy.",
407
+ search: "Search",
408
+ searchPlaceholder: "Name, kind, source, selector",
409
+ requiresServer: "The lazy site must be served over HTTP(S); open this directory through a local static server."
410
+ };
411
+ return [
412
+ "<!doctype html>",
413
+ `<html lang="${escapeHtml(localeModel.selectedLocale)}">`,
414
+ "<head>",
415
+ "<meta charset=\"utf-8\">",
416
+ "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">",
417
+ `<title>${escapeHtml(pageTitle)}</title>`,
418
+ "<link rel=\"icon\" href=\"data:,\">",
419
+ `<link rel="stylesheet" href="${escapeHtml(DEFAULT_THEME_CSS_PATH)}">`,
420
+ "</head>",
421
+ "<body>",
422
+ "<div class=\"hia-shell hia-project-shell hia-project-split-site\">",
423
+ "<aside class=\"hia-sidebar\">",
424
+ `<h1>${escapeHtml(projectName)}</h1>`,
425
+ renderLocaleControl(localeModel.locales, localeModel.selectedLocale),
426
+ renderProjectViewControl(views, entryCounts),
427
+ [
428
+ "<label class=\"hia-project-search\">",
429
+ `<span>${escapeHtml(labels.search)}</span>`,
430
+ `<input type="search" data-hia-project-search placeholder="${escapeHtml(labels.searchPlaceholder)}">`,
431
+ "</label>"
432
+ ].join(""),
433
+ `<section class="hia-project-summary hia-project-hierarchy"><h2>${escapeHtml(labels.hierarchy)}</h2><div data-hia-project-tree><p class="hia-project-loading">${escapeHtml(labels.loading)}</p></div></section>`,
434
+ `<button type="button" class="hia-project-secondary-action" data-hia-project-relations>${escapeHtml(labels.relations)}</button>`,
435
+ "</aside>",
436
+ `<main class="hia-main hia-project-main" data-hia-project-content><p class="hia-project-empty">${escapeHtml(labels.select)}</p></main>`,
437
+ "</div>",
438
+ `<script src="${escapeHtml(DEFAULT_THEME_JS_PATH)}"></script>`,
439
+ renderProjectSplitSiteScript(labels.requiresServer, labels.open),
440
+ "</body>",
441
+ "</html>"
442
+ ].join("");
443
+ }
444
+ function renderProjectSplitSiteScript(fileProtocolMessage, openLabel) {
445
+ return [
446
+ "<script>",
447
+ "(() => {",
448
+ " const config = { navigation: 'navigation/root.json', search: 'search/index.json', relations: 'relations/project.json' };",
449
+ " const treeHost = document.querySelector('[data-hia-project-tree]');",
450
+ " const contentHost = document.querySelector('[data-hia-project-content]');",
451
+ " const search = document.querySelector('[data-hia-project-search]');",
452
+ " const locale = document.querySelector('[data-hia-locale-control]');",
453
+ " const viewButtons = Array.from(document.querySelectorAll('[data-hia-project-view]'));",
454
+ " let rootNodes = [];",
455
+ " let searchEntries = null;",
456
+ " let activeView = 'all';",
457
+ " async function readJson(target) {",
458
+ " const response = await fetch(target, { credentials: 'omit' });",
459
+ " if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);",
460
+ " return response.json();",
461
+ " }",
462
+ " function showLoadError(error) {",
463
+ ` const hint = location.protocol === 'file:' ? ${JSON.stringify(fileProtocolMessage)} : String(error?.message || error);`,
464
+ " if (contentHost) contentHost.innerHTML = '';",
465
+ " const message = document.createElement('p');",
466
+ " message.className = 'hia-project-load-error';",
467
+ " message.textContent = hint;",
468
+ " (contentHost || treeHost)?.append(message);",
469
+ " }",
470
+ " function nodeMatchesView(node) {",
471
+ " return activeView === 'all' || (Array.isArray(node.views) && node.views.includes(activeView));",
472
+ " }",
473
+ " function createTreeList(nodes) {",
474
+ " const list = document.createElement('ul');",
475
+ " list.className = 'hia-project-hierarchy-list';",
476
+ " for (const node of nodes.filter(nodeMatchesView)) list.append(createTreeNode(node));",
477
+ " return list;",
478
+ " }",
479
+ " function createTreeNode(node) {",
480
+ " const item = document.createElement('li');",
481
+ " item.dataset.hiaProjectNav = node.views?.[0] || 'other';",
482
+ " if (node.childrenPath) {",
483
+ " const details = document.createElement('details');",
484
+ " const summary = document.createElement('summary');",
485
+ " const summaryLabel = document.createElement('span');",
486
+ " summaryLabel.textContent = `${node.label} (${node.entryCount})`;",
487
+ " summary.append(summaryLabel);",
488
+ " if (node.entryId && node.contentPath) {",
489
+ " const openButton = document.createElement('button');",
490
+ " openButton.type = 'button';",
491
+ " openButton.className = 'hia-project-entry-link hia-project-tree-open';",
492
+ ` openButton.textContent = ${JSON.stringify(openLabel)};`,
493
+ " openButton.addEventListener('click', (event) => {",
494
+ " event.preventDefault();",
495
+ " event.stopPropagation();",
496
+ " loadEntry(node.entryId, node.contentPath, true);",
497
+ " });",
498
+ " summary.append(openButton);",
499
+ " }",
500
+ " details.append(summary);",
501
+ " details.addEventListener('toggle', async () => {",
502
+ " if (!details.open || details.dataset.loaded === 'true') return;",
503
+ " details.dataset.loaded = 'true';",
504
+ " const loading = document.createElement('p');",
505
+ " loading.className = 'hia-project-loading';",
506
+ " loading.textContent = '...';",
507
+ " details.append(loading);",
508
+ " try {",
509
+ " const shard = await readJson(node.childrenPath);",
510
+ " loading.replaceWith(createTreeList(Array.isArray(shard.children) ? shard.children : []));",
511
+ " } catch (error) {",
512
+ " loading.textContent = String(error?.message || error);",
513
+ " }",
514
+ " });",
515
+ " item.append(details);",
516
+ " } else if (node.entryId && node.contentPath) {",
517
+ " const button = document.createElement('button');",
518
+ " button.type = 'button';",
519
+ " button.className = 'hia-project-entry-link';",
520
+ " button.textContent = node.label;",
521
+ " button.addEventListener('click', () => loadEntry(node.entryId, node.contentPath, true));",
522
+ " item.append(button);",
523
+ " } else {",
524
+ " const label = document.createElement('span');",
525
+ " label.textContent = node.label;",
526
+ " item.append(label);",
527
+ " }",
528
+ " return item;",
529
+ " }",
530
+ " function renderRoot() {",
531
+ " if (!treeHost) return;",
532
+ " treeHost.innerHTML = '';",
533
+ " treeHost.append(createTreeList(rootNodes));",
534
+ " }",
535
+ " function applyLocale() {",
536
+ " const selected = String(locale?.value || document.documentElement.lang || 'und');",
537
+ " document.documentElement.lang = selected;",
538
+ " for (const block of document.querySelectorAll('[data-hia-locale]')) {",
539
+ " block.hidden = block.getAttribute('data-hia-locale') !== selected;",
540
+ " }",
541
+ " }",
542
+ " function bindSourceFetch() {",
543
+ " for (const button of contentHost?.querySelectorAll('[data-hia-source-fetch]') || []) {",
544
+ " button.addEventListener('click', async () => {",
545
+ " if (button.dataset.loaded === 'true') return;",
546
+ " const code = button.parentElement?.querySelector('code');",
547
+ " try {",
548
+ " const response = await fetch(button.dataset.hiaSourceFetch || '', { credentials: 'omit' });",
549
+ " if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);",
550
+ " const lines = (await response.text()).split(/\\r?\\n/u);",
551
+ " const start = Math.max(1, Number(button.dataset.hiaSourceStart || 1));",
552
+ " const end = Math.max(start, Number(button.dataset.hiaSourceEnd || lines.length));",
553
+ " if (code) code.textContent = lines.slice(start - 1, end).join('\\n');",
554
+ " button.dataset.loaded = 'true';",
555
+ " button.hidden = true;",
556
+ " } catch (error) {",
557
+ " button.textContent = String(error?.message || error);",
558
+ " }",
559
+ " });",
560
+ " }",
561
+ " }",
562
+ " async function loadEntry(entryId, contentPath, updateHash) {",
563
+ " if (!contentHost) return;",
564
+ " contentHost.innerHTML = '<p class=\"hia-project-loading\">...</p>';",
565
+ " try {",
566
+ " const response = await fetch(contentPath, { credentials: 'omit' });",
567
+ " if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);",
568
+ " contentHost.innerHTML = await response.text();",
569
+ " applyLocale();",
570
+ " bindSourceFetch();",
571
+ " if (updateHash) history.replaceState(null, '', `#entry=${encodeURIComponent(entryId)}`);",
572
+ " } catch (error) {",
573
+ " showLoadError(error);",
574
+ " }",
575
+ " }",
576
+ " async function ensureSearchIndex() {",
577
+ " if (searchEntries) return searchEntries;",
578
+ " const index = await readJson(config.search);",
579
+ " searchEntries = Array.isArray(index.entries) ? index.entries : [];",
580
+ " return searchEntries;",
581
+ " }",
582
+ " async function runSearch() {",
583
+ " const query = String(search?.value || '').trim().toLowerCase();",
584
+ " if (!query) { renderRoot(); return; }",
585
+ " try {",
586
+ " const entries = await ensureSearchIndex();",
587
+ " const matches = entries.filter((entry) => (activeView === 'all' || entry.view === activeView) && String(entry.searchText || '').includes(query)).slice(0, 200);",
588
+ " if (!treeHost) return;",
589
+ " treeHost.innerHTML = '';",
590
+ " const nodes = matches.map((entry) => ({ id: entry.id, label: `${entry.name} · ${entry.kind}`, entryId: entry.id, contentPath: entry.contentPath, views: [entry.view], entryCount: 1 }));",
591
+ " treeHost.append(createTreeList(nodes));",
592
+ " } catch (error) { showLoadError(error); }",
593
+ " }",
594
+ " for (const button of viewButtons) {",
595
+ " button.addEventListener('click', () => {",
596
+ " activeView = button.dataset.hiaProjectView || 'all';",
597
+ " for (const candidate of viewButtons) candidate.setAttribute('aria-pressed', String(candidate === button));",
598
+ " runSearch();",
599
+ " });",
600
+ " }",
601
+ " search?.addEventListener('input', runSearch);",
602
+ " locale?.addEventListener('change', applyLocale);",
603
+ " document.querySelector('[data-hia-project-relations]')?.addEventListener('click', async () => {",
604
+ " try {",
605
+ " const graph = await readJson(config.relations);",
606
+ " if (!contentHost) return;",
607
+ " contentHost.innerHTML = '';",
608
+ " const article = document.createElement('article');",
609
+ " article.className = 'hia-symbol';",
610
+ " const heading = document.createElement('h2');",
611
+ " heading.textContent = 'Relations';",
612
+ " const summary = document.createElement('p');",
613
+ " summary.textContent = `${graph.nodeCount || 0} node(s), ${graph.relationCount || 0} relation(s).`;",
614
+ " article.append(heading, summary);",
615
+ " contentHost.append(article);",
616
+ " } catch (error) { showLoadError(error); }",
617
+ " });",
618
+ " readJson(config.navigation).then((shard) => {",
619
+ " rootNodes = Array.isArray(shard.children) ? shard.children : [];",
620
+ " renderRoot();",
621
+ " const hash = location.hash.startsWith('#entry=') ? decodeURIComponent(location.hash.slice(7)) : '';",
622
+ " if (hash) ensureSearchIndex().then((entries) => {",
623
+ " const entry = entries.find((candidate) => candidate.id === hash);",
624
+ " if (entry) loadEntry(entry.id, entry.contentPath, false);",
625
+ " });",
626
+ " }).catch(showLoadError);",
627
+ " viewButtons.find((button) => button.dataset.hiaProjectView === 'all')?.setAttribute('aria-pressed', 'true');",
628
+ "})();",
629
+ "</script>"
630
+ ].join("");
631
+ }
208
632
  function renderProjectIndexHtml(pageTitle, projectInput, options) {
209
633
  const projectName = projectInput.project.title ?? projectInput.project.name;
210
634
  const localeModel = resolveProjectLocaleModel(projectInput, options.locale);
211
635
  const views = collectProjectViews(projectInput.entries);
212
636
  const entryCounts = countEntriesByView(projectInput.entries);
637
+ const groups = collectProjectNavigationGroups(projectInput.entries);
638
+ const navigationTree = collectProjectNavigationTree(projectInput.entries);
213
639
  const navigation = projectInput.entries
214
640
  .map((entry) => renderProjectNavItem(entry))
215
641
  .join("");
@@ -218,6 +644,8 @@ function renderProjectIndexHtml(pageTitle, projectInput, options) {
218
644
  .join("");
219
645
  const profileSummary = renderProjectProfiles(projectInput.profiles ?? []);
220
646
  const docSourceMapSummary = renderProjectDocSourceMaps(projectInput.docSourceMaps ?? []);
647
+ const relationGraphSummary = renderProjectRelationGraphSummary(projectInput.relationGraph);
648
+ const relationGraph = renderProjectRelationGraph(projectInput.relationGraph);
221
649
  const diagnostics = renderProjectDiagnostics(projectInput.diagnostics ?? []);
222
650
  return [
223
651
  "<!doctype html>",
@@ -236,12 +664,16 @@ function renderProjectIndexHtml(pageTitle, projectInput, options) {
236
664
  renderLocaleControl(localeModel.locales, localeModel.selectedLocale),
237
665
  renderProjectViewControl(views, entryCounts),
238
666
  renderProjectSearchControl(),
667
+ renderProjectHierarchy(navigationTree),
668
+ renderProjectGroupSummary(groups),
239
669
  navigation ? `<nav><ul>${navigation}</ul></nav>` : "",
240
670
  profileSummary,
241
671
  docSourceMapSummary,
672
+ relationGraphSummary,
242
673
  diagnostics,
243
674
  "</aside>",
244
675
  "<main class=\"hia-main hia-project-main\">",
676
+ relationGraph,
245
677
  entries || "<p>No project documentation entries.</p>",
246
678
  "<p class=\"hia-project-empty\" data-hia-project-empty hidden>No entries match the current filters.</p>",
247
679
  "</main>",
@@ -266,6 +698,56 @@ function renderProjectSearchControl() {
266
698
  "</label>"
267
699
  ].join("");
268
700
  }
701
+ function renderProjectGroupSummary(groups) {
702
+ if (groups.length === 0) {
703
+ return "";
704
+ }
705
+ const sections = [
706
+ ["kind", "Kinds"],
707
+ ["profile-layer", "Profile Layers"],
708
+ ["source-root", "Source Roots"]
709
+ ]
710
+ .map(([kind, label]) => {
711
+ const items = groups
712
+ .filter((group) => group.kind === kind)
713
+ .sort(compareProjectNavigationGroups)
714
+ .slice(0, 12)
715
+ .map((group) => `<li><span>${escapeHtml(group.label)}</span><strong>${escapeHtml(String(group.entryCount))}</strong></li>`)
716
+ .join("");
717
+ return items ? `<section><h3>${escapeHtml(label)}</h3><ul class="hia-project-group-list">${items}</ul></section>` : "";
718
+ })
719
+ .join("");
720
+ return sections ? `<section class="hia-project-summary hia-project-groups"><h2>Groups</h2>${sections}</section>` : "";
721
+ }
722
+ function renderProjectHierarchy(nodes) {
723
+ if (nodes.length === 0) {
724
+ return "";
725
+ }
726
+ return `<section class="hia-project-summary hia-project-hierarchy"><h2>Hierarchy</h2>${renderProjectHierarchyList(nodes)}</section>`;
727
+ }
728
+ function renderProjectHierarchyList(nodes) {
729
+ const items = nodes
730
+ .map((node) => renderProjectHierarchyNode(node))
731
+ .join("");
732
+ return `<ul class="hia-project-hierarchy-list">${items}</ul>`;
733
+ }
734
+ function renderProjectHierarchyNode(node) {
735
+ const children = node.children && node.children.length > 0 ? renderProjectHierarchyList(node.children) : "";
736
+ const label = node.entryId
737
+ ? `<a href="#${escapeHtml(node.entryId)}">${escapeHtml(node.label)}</a>`
738
+ : `<span>${escapeHtml(node.label)}</span>`;
739
+ const meta = node.kind === "entry"
740
+ ? ""
741
+ : `<small>${escapeHtml(node.kind)} / ${escapeHtml(String(node.entryCount))}</small>`;
742
+ const searchText = createProjectNavigationTreeSearchText(node);
743
+ return [
744
+ `<li data-hia-project-nav="${escapeHtml(node.views[0] ?? "other")}" data-hia-project-search-text="${escapeHtml(searchText)}">`,
745
+ label,
746
+ meta,
747
+ children,
748
+ "</li>"
749
+ ].join("");
750
+ }
269
751
  function renderProjectNavItem(entry) {
270
752
  const searchText = createProjectEntrySearchText(entry);
271
753
  return [
@@ -282,6 +764,7 @@ function renderProjectEntry(entry, locales, selectedLocale) {
282
764
  const summary = renderProjectEntrySummary(entry, locales, selectedLocale);
283
765
  const input = entry.input ? renderProjectEntryInput(entry.input) : "";
284
766
  const profile = entry.profile ? renderProjectEntryProfile(entry.profile) : "";
767
+ const hierarchy = entry.hierarchy ? renderProjectEntryHierarchy(entry.hierarchy) : "";
285
768
  const source = entry.source ? renderProjectEntrySource(entry.source) : "";
286
769
  const docSourceMap = entry.docSourceMap ? renderProjectEntryDocSourceMap(entry.docSourceMap) : "";
287
770
  const diagnostics = renderProjectDiagnostics(entry.diagnostics ?? []);
@@ -295,14 +778,31 @@ function renderProjectEntry(entry, locales, selectedLocale) {
295
778
  summary,
296
779
  input,
297
780
  profile,
781
+ hierarchy,
298
782
  source,
299
783
  docSourceMap,
300
784
  diagnostics,
301
785
  "</article>"
302
786
  ].join("");
303
787
  }
788
+ function renderProjectEntryHierarchy(hierarchy) {
789
+ const details = [
790
+ hierarchy.assembly ? `<dt>Assembly</dt><dd>${escapeHtml(hierarchy.assembly)}</dd>` : "",
791
+ hierarchy.namespace ? `<dt>Namespace</dt><dd>${escapeHtml(hierarchy.namespace)}</dd>` : "",
792
+ hierarchy.containingType ? `<dt>Containing Type</dt><dd>${escapeHtml(hierarchy.containingType)}</dd>` : "",
793
+ hierarchy.symbolDocumentationId ? `<dt>Documentation ID</dt><dd>${escapeHtml(hierarchy.symbolDocumentationId)}</dd>` : "",
794
+ hierarchy.parentSymbolId ? `<dt>Parent</dt><dd>${escapeHtml(hierarchy.parentSymbolId)}</dd>` : "",
795
+ hierarchy.baseTypeIds && hierarchy.baseTypeIds.length > 0
796
+ ? `<dt>Inheritance</dt><dd>${escapeHtml(hierarchy.baseTypeIds.join(" -> "))}</dd>`
797
+ : "",
798
+ hierarchy.interfaceIds && hierarchy.interfaceIds.length > 0
799
+ ? `<dt>Interfaces</dt><dd>${escapeHtml(hierarchy.interfaceIds.join(", "))}</dd>`
800
+ : ""
801
+ ].join("");
802
+ return details ? `<dl class="hia-project-meta hia-project-hierarchy-meta">${details}</dl>` : "";
803
+ }
304
804
  function renderProjectEntrySummary(entry, locales, selectedLocale) {
305
- const field = entry.i18n?.fields.description;
805
+ const field = entry.i18n?.fields.description ?? entry.i18n?.fields.summary;
306
806
  if (!field && !entry.summary) {
307
807
  return "";
308
808
  }
@@ -338,7 +838,19 @@ function renderProjectEntrySource(source) {
338
838
  source.confidence ? `<dt>Confidence</dt><dd>${escapeHtml(source.confidence)}</dd>` : ""
339
839
  ].join("");
340
840
  const preview = source.preview ? renderProjectSourcePreview(source.preview, source.path) : "";
341
- return `<section class="hia-source-section"><h3>Source</h3><dl class="hia-project-meta">${sourceDetails}</dl>${preview}</section>`;
841
+ const fetchPreview = source.fetchUrl ? renderProjectSourceFetch(source) : "";
842
+ return `<section class="hia-source-section"><h3>Source</h3><dl class="hia-project-meta">${sourceDetails}</dl>${preview}${fetchPreview}</section>`;
843
+ }
844
+ function renderProjectSourceFetch(source) {
845
+ const startLine = source.range?.start.line ?? 1;
846
+ const endLine = source.range?.end?.line ?? startLine;
847
+ return [
848
+ "<details class=\"hia-source-preview hia-project-source-preview\">",
849
+ `<summary>${escapeHtml(`${source.path}:${startLine}-${endLine}`)}</summary>`,
850
+ `<button type="button" class="hia-source-fetch-button" data-hia-source-fetch="${escapeHtml(source.fetchUrl ?? "")}" data-hia-source-start="${escapeHtml(String(startLine))}" data-hia-source-end="${escapeHtml(String(endLine))}">Load source / 加载源码</button>`,
851
+ `<pre class="hia-source-code"><code data-language="${escapeHtml(source.language ?? "")}"></code></pre>`,
852
+ "</details>"
853
+ ].join("");
342
854
  }
343
855
  function renderProjectEntryDocSourceMap(docSourceMap) {
344
856
  const sourceRange = docSourceMap.sourceRange ? `:${docSourceMap.sourceRange.start.line}${docSourceMap.sourceRange.end ? `-${docSourceMap.sourceRange.end.line}` : ""}` : "";
@@ -425,6 +937,55 @@ function renderProjectDocSourceMaps(docSourceMaps) {
425
937
  .join("");
426
938
  return `<section class="hia-project-summary"><h2>Doc Source Maps</h2><ul>${items}</ul></section>`;
427
939
  }
940
+ function renderProjectRelationGraphSummary(relationGraph) {
941
+ if (!relationGraph || relationGraph.relationCount === 0) {
942
+ return "";
943
+ }
944
+ const items = [
945
+ `<li><span>Nodes</span><strong>${escapeHtml(String(relationGraph.nodeCount))}</strong></li>`,
946
+ `<li><span>Relations</span><strong>${escapeHtml(String(relationGraph.relationCount))}</strong></li>`,
947
+ `<li><span>Contract</span><strong>${escapeHtml(relationGraph.contractVersion)}</strong></li>`
948
+ ].join("");
949
+ return `<section class="hia-project-summary hia-project-relations-summary"><h2>Relations</h2><ul class="hia-project-group-list">${items}</ul></section>`;
950
+ }
951
+ function renderProjectRelationGraph(relationGraph) {
952
+ if (!relationGraph || relationGraph.relationCount === 0) {
953
+ return "";
954
+ }
955
+ const nodesById = new Map(relationGraph.nodes.map((node) => [node.id, node]));
956
+ const items = relationGraph.relations
957
+ .map((relation) => renderProjectRelation(relation, nodesById))
958
+ .join("");
959
+ return [
960
+ "<section class=\"hia-symbol hia-project-relations\">",
961
+ "<h2>Relations</h2>",
962
+ `<p>${escapeHtml(String(relationGraph.relationCount))} relation(s), ${escapeHtml(String(relationGraph.nodeCount))} node(s).</p>`,
963
+ `<ul class="hia-project-relation-list">${items}</ul>`,
964
+ "</section>"
965
+ ].join("");
966
+ }
967
+ function renderProjectRelation(relation, nodesById) {
968
+ const from = nodesById.get(relation.from);
969
+ const to = nodesById.get(relation.to);
970
+ const confidence = relation.confidence ? `, confidence=${relation.confidence}` : "";
971
+ const metadata = relation.metadata
972
+ ? Object.entries(relation.metadata)
973
+ .map(([key, value]) => `${key}=${String(value)}`)
974
+ .join(", ")
975
+ : "";
976
+ const detail = [
977
+ `${from?.label ?? relation.from} -> ${to?.label ?? relation.to}`,
978
+ confidence,
979
+ metadata ? `, ${metadata}` : ""
980
+ ].join("");
981
+ return [
982
+ "<li>",
983
+ `<span class="hia-kind">${escapeHtml(relation.kind)}</span> `,
984
+ `<strong>${escapeHtml(relation.label)}</strong>`,
985
+ `<small>${escapeHtml(detail)}</small>`,
986
+ "</li>"
987
+ ].join("");
988
+ }
428
989
  function renderProjectDiagnostics(diagnostics) {
429
990
  if (diagnostics.length === 0) {
430
991
  return "";
@@ -482,9 +1043,538 @@ function renderProjectViewScript() {
482
1043
  "</script>"
483
1044
  ].join("");
484
1045
  }
1046
+ function normalizeProjectRelationGraphInput(projectInput) {
1047
+ if (projectInput.relationGraph) {
1048
+ return {
1049
+ ...projectInput,
1050
+ relationGraph: normalizeProjectRelationGraph(projectInput.relationGraph)
1051
+ };
1052
+ }
1053
+ const relationGraph = createProjectRelationGraph(projectInput.entries);
1054
+ return relationGraph.relationCount > 0
1055
+ ? { ...projectInput, relationGraph }
1056
+ : projectInput;
1057
+ }
1058
+ function normalizeProjectRelationGraph(relationGraph) {
1059
+ const nodes = [...relationGraph.nodes].sort(compareProjectRelationNodes);
1060
+ const relations = [...relationGraph.relations].sort(compareProjectRelations);
1061
+ return {
1062
+ contract: HIA_PROJECT_RELATION_GRAPH_CONTRACT,
1063
+ contractVersion: HIA_PROJECT_RELATION_GRAPH_CONTRACT_VERSION,
1064
+ nodeCount: nodes.length,
1065
+ relationCount: relations.length,
1066
+ nodes,
1067
+ relations
1068
+ };
1069
+ }
1070
+ function createProjectRelationGraph(entries) {
1071
+ const nodes = new Map();
1072
+ const relations = new Map();
1073
+ for (const entry of entries) {
1074
+ const entryNodeId = createProjectEntryRelationNodeId(entry.id);
1075
+ addProjectRelationNode(nodes, {
1076
+ id: entryNodeId,
1077
+ kind: "entry",
1078
+ label: entry.name,
1079
+ entryId: entry.id,
1080
+ view: entry.view
1081
+ });
1082
+ addProjectSourceRelation(nodes, relations, entry, entry.source?.path, entry.source?.confidence, {
1083
+ language: entry.source?.language ?? null,
1084
+ rangeStartLine: entry.source?.range?.start.line ?? null,
1085
+ rangeEndLine: entry.source?.range?.end?.line ?? null,
1086
+ rangeSource: entry.source?.rangeSource ?? null
1087
+ });
1088
+ addProjectSourceRelation(nodes, relations, entry, entry.docSourceMap?.sourcePath, entry.docSourceMap?.sourceConfidence, {
1089
+ manifest: entry.docSourceMap?.path ?? null,
1090
+ rangeStartLine: entry.docSourceMap?.sourceRange?.start.line ?? null,
1091
+ rangeEndLine: entry.docSourceMap?.sourceRange?.end?.line ?? null,
1092
+ rangeSource: entry.docSourceMap?.sourceRangeSource ?? null
1093
+ });
1094
+ addProjectArtifactRelation(nodes, relations, entry);
1095
+ addProjectEndpointRelation(nodes, relations, entry);
1096
+ }
1097
+ const graph = {
1098
+ contract: HIA_PROJECT_RELATION_GRAPH_CONTRACT,
1099
+ contractVersion: HIA_PROJECT_RELATION_GRAPH_CONTRACT_VERSION,
1100
+ nodeCount: nodes.size,
1101
+ relationCount: relations.size,
1102
+ nodes: [...nodes.values()],
1103
+ relations: [...relations.values()]
1104
+ };
1105
+ return normalizeProjectRelationGraph(graph);
1106
+ }
1107
+ function addProjectSourceRelation(nodes, relations, entry, sourcePath, confidence, metadata) {
1108
+ if (!sourcePath) {
1109
+ return;
1110
+ }
1111
+ const entryNodeId = createProjectEntryRelationNodeId(entry.id);
1112
+ const sourceNodeId = createProjectPathRelationNodeId("source", sourcePath);
1113
+ addProjectRelationNode(nodes, {
1114
+ id: sourceNodeId,
1115
+ kind: "source",
1116
+ label: sourcePath,
1117
+ path: sourcePath
1118
+ });
1119
+ const compactMetadata = compactProjectRelationMetadata(metadata);
1120
+ addProjectRelation(relations, {
1121
+ id: createProjectRelationId(inferProjectSourceRelationKind(entry), entryNodeId, sourceNodeId),
1122
+ kind: inferProjectSourceRelationKind(entry),
1123
+ from: entryNodeId,
1124
+ to: sourceNodeId,
1125
+ label: `Source: ${sourcePath}`,
1126
+ ...(confidence ? { confidence } : {}),
1127
+ entryId: entry.id,
1128
+ ...(compactMetadata ? { metadata: compactMetadata } : {})
1129
+ });
1130
+ }
1131
+ function addProjectArtifactRelation(nodes, relations, entry) {
1132
+ if (!entry.docSourceMap?.artifactPath) {
1133
+ return;
1134
+ }
1135
+ const entryNodeId = createProjectEntryRelationNodeId(entry.id);
1136
+ const artifactNodeId = createProjectPathRelationNodeId("artifact", entry.docSourceMap.artifactPath);
1137
+ addProjectRelationNode(nodes, {
1138
+ id: artifactNodeId,
1139
+ kind: "artifact",
1140
+ label: entry.docSourceMap.artifactPath,
1141
+ path: entry.docSourceMap.artifactPath
1142
+ });
1143
+ const compactMetadata = compactProjectRelationMetadata({
1144
+ manifest: entry.docSourceMap.path,
1145
+ selector: entry.docSourceMap.artifactSelector ?? null
1146
+ });
1147
+ addProjectRelation(relations, {
1148
+ id: createProjectRelationId("documents-generated-artifact", entryNodeId, artifactNodeId),
1149
+ kind: "documents-generated-artifact",
1150
+ from: entryNodeId,
1151
+ to: artifactNodeId,
1152
+ label: `Generated: ${entry.docSourceMap.artifactPath}`,
1153
+ ...(entry.docSourceMap.artifactConfidence ? { confidence: entry.docSourceMap.artifactConfidence } : {}),
1154
+ entryId: entry.id,
1155
+ ...(compactMetadata ? { metadata: compactMetadata } : {})
1156
+ });
1157
+ }
1158
+ function addProjectEndpointRelation(nodes, relations, entry) {
1159
+ if (entry.kind !== "aspnet-endpoint" && !entry.kind.startsWith("aspnet-")) {
1160
+ return;
1161
+ }
1162
+ const entryNodeId = createProjectEntryRelationNodeId(entry.id);
1163
+ const endpointNodeId = `endpoint:${entry.id}`;
1164
+ addProjectRelationNode(nodes, {
1165
+ id: endpointNodeId,
1166
+ kind: "endpoint",
1167
+ label: entry.name,
1168
+ entryId: entry.id,
1169
+ view: entry.view
1170
+ });
1171
+ addProjectRelation(relations, {
1172
+ id: createProjectRelationId("documents-endpoint", entryNodeId, endpointNodeId),
1173
+ kind: "documents-endpoint",
1174
+ from: entryNodeId,
1175
+ to: endpointNodeId,
1176
+ label: `Endpoint: ${entry.name}`,
1177
+ entryId: entry.id
1178
+ });
1179
+ }
1180
+ function addProjectRelationNode(nodes, node) {
1181
+ if (!nodes.has(node.id)) {
1182
+ nodes.set(node.id, node);
1183
+ }
1184
+ }
1185
+ function addProjectRelation(relations, relation) {
1186
+ const current = relations.get(relation.id);
1187
+ if (!current) {
1188
+ relations.set(relation.id, relation);
1189
+ return;
1190
+ }
1191
+ if (!current.confidence && relation.confidence) {
1192
+ relations.set(relation.id, { ...current, confidence: relation.confidence });
1193
+ }
1194
+ }
1195
+ function inferProjectSourceRelationKind(entry) {
1196
+ if (entry.kind.startsWith("dotnet-")) {
1197
+ return "semantic-member";
1198
+ }
1199
+ if (entry.kind === "vue-exposed-api") {
1200
+ return "exposes-api";
1201
+ }
1202
+ return "documents-source";
1203
+ }
1204
+ function createProjectEntryRelationNodeId(entryId) {
1205
+ return `entry:${entryId}`;
1206
+ }
1207
+ function createProjectPathRelationNodeId(kind, path) {
1208
+ return `${kind}:${path.replaceAll("\\", "/")}`;
1209
+ }
1210
+ function createProjectRelationId(kind, from, to) {
1211
+ return `${kind}:${from}->${to}`;
1212
+ }
1213
+ function compactProjectRelationMetadata(metadata) {
1214
+ const entries = Object.entries(metadata)
1215
+ .filter((entry) => entry[1] !== undefined && entry[1] !== null);
1216
+ return entries.length > 0 ? Object.fromEntries(entries) : undefined;
1217
+ }
1218
+ function compareProjectRelationNodes(left, right) {
1219
+ return compareStableText(left.id, right.id);
1220
+ }
1221
+ function compareProjectRelations(left, right) {
1222
+ return compareStableText(left.id, right.id);
1223
+ }
1224
+ const PROJECT_VIEW_ORDER = ["all", "dotnet", "js", "powershell", "css", "html", "other"];
1225
+ function collectProjectNavigationGroups(entries) {
1226
+ return [
1227
+ ...collectProjectNavigationGroupsBy(entries, "kind", (entry) => entry.kind || "unknown-kind"),
1228
+ ...collectProjectNavigationGroupsBy(entries, "profile-layer", (entry) => entry.profile?.layer || entry.profile?.profileId || "unknown-profile"),
1229
+ ...collectProjectNavigationGroupsBy(entries, "source-root", (entry) => getProjectSourceRoot(entry.source?.path))
1230
+ ].sort(compareProjectNavigationGroups);
1231
+ }
1232
+ function collectProjectNavigationTree(entries) {
1233
+ return PROJECT_VIEW_ORDER
1234
+ .filter((view) => view !== "all")
1235
+ .flatMap((view) => {
1236
+ const viewEntries = entries.filter((entry) => entry.view === view);
1237
+ if (viewEntries.length === 0) {
1238
+ return [];
1239
+ }
1240
+ const children = view === "dotnet"
1241
+ ? collectDotNetNavigationTree(viewEntries)
1242
+ : collectSemanticSourceNavigationTree(viewEntries);
1243
+ return [{
1244
+ id: `view:${view}`,
1245
+ kind: "view",
1246
+ label: formatProjectViewLabel(view),
1247
+ entryCount: viewEntries.length,
1248
+ views: [view],
1249
+ children
1250
+ }];
1251
+ });
1252
+ }
1253
+ function collectDotNetNavigationTree(entries) {
1254
+ const roots = new Map();
1255
+ for (const entry of entries) {
1256
+ const parts = getDotNetNavigationParts(entry);
1257
+ const assemblyNode = getOrCreateProjectTreeChild(roots, `dotnet:${parts.rootKind}:${slugProjectGroupLabel(parts.assemblyLabel)}`, parts.rootKind, parts.assemblyLabel);
1258
+ addProjectTreeEntry(assemblyNode, entry);
1259
+ let namespaceParent = assemblyNode;
1260
+ const namespaceSegments = parts.namespaceLabel === "(global namespace)"
1261
+ ? [parts.namespaceLabel]
1262
+ : parts.namespaceLabel.split(".").filter(Boolean);
1263
+ let qualifiedNamespace = "";
1264
+ for (const namespaceSegment of namespaceSegments) {
1265
+ qualifiedNamespace = qualifiedNamespace
1266
+ ? `${qualifiedNamespace}.${namespaceSegment}`
1267
+ : namespaceSegment;
1268
+ const namespaceNode = getOrCreateProjectTreeChild(namespaceParent.childrenById, `${assemblyNode.id}:namespace:${slugProjectGroupLabel(qualifiedNamespace)}`, "namespace", namespaceSegment);
1269
+ namespaceParent.children = [...namespaceParent.childrenById.values()];
1270
+ addProjectTreeEntry(namespaceNode, entry);
1271
+ namespaceParent = namespaceNode;
1272
+ }
1273
+ const typeNode = getOrCreateProjectTreeChild(namespaceParent.childrenById, `${namespaceParent.id}:type:${slugProjectGroupLabel(parts.typeId)}`, "type", parts.typeLabel);
1274
+ namespaceParent.children = [...namespaceParent.childrenById.values()];
1275
+ addProjectTreeEntry(typeNode, entry);
1276
+ if (isDotNetTypeNavigationEntry(entry)) {
1277
+ typeNode.entryId = entry.id;
1278
+ assignProjectTreeEntryRefs(typeNode, entry);
1279
+ if (entry.kind === "dotnet-type") {
1280
+ addDotNetInheritanceNodes(typeNode, entry);
1281
+ }
1282
+ continue;
1283
+ }
1284
+ const entryNode = getOrCreateProjectTreeChild(typeNode.childrenById, `${typeNode.id}:entry:${entry.id}`, "entry", parts.memberLabel);
1285
+ typeNode.children = [...typeNode.childrenById.values()];
1286
+ addProjectTreeEntry(entryNode, entry);
1287
+ entryNode.entryId = entry.id;
1288
+ assignProjectTreeEntryRefs(entryNode, entry);
1289
+ }
1290
+ return sortProjectTreeNodes([...roots.values()].map(finalizeProjectTreeBuilder));
1291
+ }
1292
+ function addDotNetInheritanceNodes(typeNode, entry) {
1293
+ for (const baseTypeId of entry.hierarchy?.baseTypeIds ?? []) {
1294
+ const relationNode = getOrCreateProjectTreeChild(typeNode.childrenById, `${typeNode.id}:base:${slugProjectGroupLabel(baseTypeId)}`, "relation", `Base: ${baseTypeId.replace(/^T:/u, "")}`);
1295
+ relationNode.views.add(entry.view);
1296
+ }
1297
+ for (const interfaceId of entry.hierarchy?.interfaceIds ?? []) {
1298
+ const relationNode = getOrCreateProjectTreeChild(typeNode.childrenById, `${typeNode.id}:interface:${slugProjectGroupLabel(interfaceId)}`, "relation", `Interface: ${interfaceId.replace(/^T:/u, "")}`);
1299
+ relationNode.views.add(entry.view);
1300
+ }
1301
+ typeNode.children = [...typeNode.childrenById.values()];
1302
+ }
1303
+ /**
1304
+ * 为非 .NET 领域保留源码目录,同时在 adapter 提供 parentSymbolId 时恢复 module/class/member 层级。
1305
+ * Preserves source grouping for non-.NET domains while restoring module/class/member hierarchy when adapters provide parentSymbolId.
1306
+ */
1307
+ function collectSemanticSourceNavigationTree(entries) {
1308
+ const roots = new Map();
1309
+ const nodesByEntryId = new Map();
1310
+ const entriesBySymbolId = new Map();
1311
+ const fileNodesByEntryId = new Map();
1312
+ for (const entry of entries) {
1313
+ if (entry.symbolId) {
1314
+ entriesBySymbolId.set(entry.symbolId, entry);
1315
+ }
1316
+ const entryNode = getOrCreateProjectTreeChild(nodesByEntryId, `entry:${entry.id}`, isProjectTypeLikeKind(entry.kind) ? "type" : "entry", entry.name);
1317
+ addProjectTreeEntry(entryNode, entry);
1318
+ entryNode.entryId = entry.id;
1319
+ assignProjectTreeEntryRefs(entryNode, entry);
1320
+ const sourceRootLabel = getProjectSourceRoot(entry.source?.path);
1321
+ const sourcePathLabel = entry.source?.path?.replaceAll("\\", "/") || "unknown-source";
1322
+ const rootNode = getOrCreateProjectTreeChild(roots, `source-root:${slugProjectGroupLabel(sourceRootLabel)}`, "source-root", sourceRootLabel);
1323
+ addProjectTreeEntry(rootNode, entry);
1324
+ const fileNode = getOrCreateProjectTreeChild(rootNode.childrenById, `${rootNode.id}:source-file:${slugProjectGroupLabel(sourcePathLabel)}`, "source-file", sourcePathLabel);
1325
+ rootNode.children = [...rootNode.childrenById.values()];
1326
+ addProjectTreeEntry(fileNode, entry);
1327
+ assignProjectTreeSourcePath(fileNode, entry.source?.path);
1328
+ fileNodesByEntryId.set(entry.id, fileNode);
1329
+ }
1330
+ for (const entry of entries) {
1331
+ const entryNode = nodesByEntryId.get(`entry:${entry.id}`);
1332
+ const parentEntry = entry.hierarchy?.parentSymbolId
1333
+ ? entriesBySymbolId.get(entry.hierarchy.parentSymbolId)
1334
+ : undefined;
1335
+ const parentNode = parentEntry
1336
+ ? nodesByEntryId.get(`entry:${parentEntry.id}`)
1337
+ : undefined;
1338
+ const sameSource = parentEntry?.source?.path === entry.source?.path;
1339
+ if (entryNode && parentEntry && parentNode && sameSource && parentNode !== entryNode) {
1340
+ parentNode.childrenById.set(entryNode.id, entryNode);
1341
+ incrementProjectNavigationAncestorCounts(parentEntry, entriesBySymbolId, nodesByEntryId);
1342
+ continue;
1343
+ }
1344
+ const fileNode = fileNodesByEntryId.get(entry.id);
1345
+ if (entryNode && fileNode) {
1346
+ fileNode.childrenById.set(entryNode.id, entryNode);
1347
+ }
1348
+ }
1349
+ return sortProjectTreeNodes([...roots.values()].map(finalizeProjectTreeBuilder));
1350
+ }
1351
+ function incrementProjectNavigationAncestorCounts(parentEntry, entriesBySymbolId, nodesByEntryId) {
1352
+ const visited = new Set();
1353
+ let current = parentEntry;
1354
+ while (current && !visited.has(current.id)) {
1355
+ visited.add(current.id);
1356
+ const node = nodesByEntryId.get(`entry:${current.id}`);
1357
+ if (node) {
1358
+ node.entryCount += 1;
1359
+ }
1360
+ current = current.hierarchy?.parentSymbolId
1361
+ ? entriesBySymbolId.get(current.hierarchy.parentSymbolId)
1362
+ : undefined;
1363
+ }
1364
+ }
1365
+ function isProjectTypeLikeKind(kind) {
1366
+ return /(?:^|[-_])(class|interface|type|module|namespace|enum|struct|record)(?:$|[-_])/iu.test(kind);
1367
+ }
1368
+ function getOrCreateProjectTreeChild(map, id, kind, label) {
1369
+ const existing = map.get(id);
1370
+ if (existing) {
1371
+ return existing;
1372
+ }
1373
+ const created = {
1374
+ id,
1375
+ kind,
1376
+ label,
1377
+ entryCount: 0,
1378
+ views: new Set(),
1379
+ children: [],
1380
+ childrenById: new Map()
1381
+ };
1382
+ map.set(id, created);
1383
+ return created;
1384
+ }
1385
+ function addProjectTreeEntry(node, entry) {
1386
+ node.entryCount += 1;
1387
+ node.views.add(entry.view);
1388
+ }
1389
+ function assignProjectTreeEntryRefs(node, entry) {
1390
+ if (entry.symbolId) {
1391
+ node.symbolId = entry.symbolId;
1392
+ }
1393
+ assignProjectTreeSourcePath(node, entry.source?.path);
1394
+ }
1395
+ function assignProjectTreeSourcePath(node, sourcePath) {
1396
+ if (sourcePath) {
1397
+ node.sourcePath = sourcePath;
1398
+ }
1399
+ }
1400
+ function finalizeProjectTreeBuilder(node) {
1401
+ const childBuilders = node.childrenById.size > 0 ? [...node.childrenById.values()] : node.children;
1402
+ const children = sortProjectTreeNodes(childBuilders.map(finalizeProjectTreeBuilder));
1403
+ return {
1404
+ id: node.id,
1405
+ kind: node.kind,
1406
+ label: node.label,
1407
+ entryCount: node.entryCount,
1408
+ views: sortProjectViews([...node.views]),
1409
+ ...(children.length > 0 ? { children } : {}),
1410
+ ...(node.entryId ? { entryId: node.entryId } : {}),
1411
+ ...(node.sourcePath ? { sourcePath: node.sourcePath } : {}),
1412
+ ...(node.symbolId ? { symbolId: node.symbolId } : {})
1413
+ };
1414
+ }
1415
+ function sortProjectTreeNodes(nodes) {
1416
+ return nodes.sort((left, right) => {
1417
+ const kindOrder = compareStableNumber(projectTreeKindOrder(left.kind), projectTreeKindOrder(right.kind));
1418
+ if (kindOrder !== 0) {
1419
+ return kindOrder;
1420
+ }
1421
+ return compareStableText(left.label, right.label);
1422
+ });
1423
+ }
1424
+ function projectTreeKindOrder(kind) {
1425
+ if (kind === "view") {
1426
+ return 0;
1427
+ }
1428
+ if (kind === "surface" || kind === "project") {
1429
+ return 2;
1430
+ }
1431
+ if (kind === "namespace") {
1432
+ return 3;
1433
+ }
1434
+ if (kind === "type") {
1435
+ return 4;
1436
+ }
1437
+ if (kind === "relation") {
1438
+ return 5;
1439
+ }
1440
+ if (kind === "assembly") {
1441
+ return 1;
1442
+ }
1443
+ if (kind === "source-root") {
1444
+ return 6;
1445
+ }
1446
+ if (kind === "source-file") {
1447
+ return 7;
1448
+ }
1449
+ return 8;
1450
+ }
1451
+ function getDotNetNavigationParts(entry) {
1452
+ const fallback = getDotNetNonAssemblyNavigationParts(entry);
1453
+ const assemblyLabel = entry.hierarchy?.assembly || fallback.assemblyLabel;
1454
+ const semanticNamespace = entry.hierarchy?.namespace;
1455
+ const semanticContainingType = entry.hierarchy?.containingType;
1456
+ const symbolId = entry.hierarchy?.symbolDocumentationId
1457
+ || (entry.symbolId?.match(/^[A-Z]:/) ? entry.symbolId : "")
1458
+ || (entry.id.match(/^[A-Z]:/) ? entry.id : "");
1459
+ const symbolBody = symbolId.match(/^[A-Z]:/) ? symbolId.slice(2) : "";
1460
+ const normalizedSymbol = symbolBody.replace(/\(.+$/, "");
1461
+ const segments = normalizedSymbol.split(".").filter((segment) => segment.length > 0);
1462
+ if (segments.length >= 2) {
1463
+ const memberLabel = entry.kind === "dotnet-type" ? entry.name : segments[segments.length - 1] ?? entry.name;
1464
+ const typeIndex = entry.kind === "dotnet-type" ? segments.length - 1 : Math.max(0, segments.length - 2);
1465
+ const typeLabel = segments[typeIndex] ?? entry.name;
1466
+ const namespaceLabel = segments.slice(0, typeIndex).join(".") || "(global namespace)";
1467
+ return {
1468
+ assemblyLabel,
1469
+ memberLabel,
1470
+ namespaceLabel: semanticNamespace || namespaceLabel,
1471
+ rootKind: entry.hierarchy?.assembly ? "assembly" : fallback.rootKind,
1472
+ typeId: semanticContainingType ? `T:${semanticContainingType}` : `T:${segments.slice(0, typeIndex + 1).join(".")}`,
1473
+ typeLabel: semanticContainingType?.split(".").pop() || typeLabel
1474
+ };
1475
+ }
1476
+ const sourceStem = entry.source?.path
1477
+ ? entry.source.path.replaceAll("\\", "/").split("/").pop()?.replace(/\.[^.]+$/, "")
1478
+ : undefined;
1479
+ return {
1480
+ assemblyLabel,
1481
+ memberLabel: entry.name,
1482
+ namespaceLabel: semanticNamespace || fallback.namespaceLabel,
1483
+ rootKind: entry.hierarchy?.assembly ? "assembly" : fallback.rootKind,
1484
+ typeId: semanticContainingType ? `T:${semanticContainingType}` : symbolId || entry.id,
1485
+ typeLabel: semanticContainingType?.split(".").pop() || sourceStem || entry.name
1486
+ };
1487
+ }
1488
+ function getDotNetNonAssemblyNavigationParts(entry) {
1489
+ if (entry.kind === "dotnet-project" || entry.kind === "dotnet-solution") {
1490
+ return {
1491
+ assemblyLabel: ".NET Project Structure",
1492
+ namespaceLabel: entry.kind === "dotnet-solution" ? "Solutions" : "Projects",
1493
+ rootKind: "project"
1494
+ };
1495
+ }
1496
+ if (entry.kind === "aspnet-endpoint" || entry.kind === "dotnet-markup-comment") {
1497
+ const sourceDirectories = (entry.source?.path ?? "")
1498
+ .replaceAll("\\", "/")
1499
+ .split("/")
1500
+ .slice(0, -1)
1501
+ .filter((segment) => segment && segment !== "src" && segment !== "Portal");
1502
+ const category = entry.kind === "aspnet-endpoint" ? "Endpoints" : "Markup";
1503
+ return {
1504
+ assemblyLabel: "ASP.NET Surfaces",
1505
+ namespaceLabel: [category, ...sourceDirectories].join("."),
1506
+ rootKind: "surface"
1507
+ };
1508
+ }
1509
+ return {
1510
+ assemblyLabel: ".NET Other",
1511
+ namespaceLabel: "(global namespace)",
1512
+ rootKind: "assembly"
1513
+ };
1514
+ }
1515
+ function isDotNetTypeNavigationEntry(entry) {
1516
+ return entry.kind === "dotnet-type"
1517
+ || entry.kind === "dotnet-project"
1518
+ || entry.kind === "dotnet-solution"
1519
+ || entry.kind === "aspnet-endpoint";
1520
+ }
1521
+ function collectProjectNavigationGroupsBy(entries, kind, keyFactory) {
1522
+ const groups = new Map();
1523
+ for (const entry of entries) {
1524
+ const label = keyFactory(entry);
1525
+ const current = groups.get(label) ?? { entryCount: 0, views: new Set() };
1526
+ current.entryCount += 1;
1527
+ current.views.add(entry.view);
1528
+ groups.set(label, current);
1529
+ }
1530
+ return [...groups.entries()].map(([label, group]) => ({
1531
+ id: `${kind}:${slugProjectGroupLabel(label)}`,
1532
+ kind,
1533
+ label,
1534
+ entryCount: group.entryCount,
1535
+ views: sortProjectViews([...group.views])
1536
+ }));
1537
+ }
1538
+ function getProjectSourceRoot(sourcePath) {
1539
+ if (!sourcePath) {
1540
+ return "unknown-source";
1541
+ }
1542
+ const normalized = sourcePath.replaceAll("\\", "/");
1543
+ const firstSegment = normalized.split("/").find((segment) => segment.length > 0);
1544
+ return firstSegment || "unknown-source";
1545
+ }
1546
+ function compareProjectNavigationGroups(left, right) {
1547
+ const kindOrder = compareStableNumber(projectGroupKindOrder(left.kind), projectGroupKindOrder(right.kind));
1548
+ if (kindOrder !== 0) {
1549
+ return kindOrder;
1550
+ }
1551
+ const countOrder = compareStableNumber(right.entryCount, left.entryCount);
1552
+ if (countOrder !== 0) {
1553
+ return countOrder;
1554
+ }
1555
+ return compareStableText(left.label, right.label);
1556
+ }
1557
+ function projectGroupKindOrder(kind) {
1558
+ if (kind === "kind") {
1559
+ return 0;
1560
+ }
1561
+ if (kind === "profile-layer") {
1562
+ return 1;
1563
+ }
1564
+ return 2;
1565
+ }
1566
+ function compareStableNumber(left, right) {
1567
+ return left < right ? -1 : left > right ? 1 : 0;
1568
+ }
1569
+ function slugProjectGroupLabel(value) {
1570
+ return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-|-$/g, "") || "group";
1571
+ }
1572
+ function sortProjectViews(views) {
1573
+ return views.sort((left, right) => PROJECT_VIEW_ORDER.indexOf(left) - PROJECT_VIEW_ORDER.indexOf(right));
1574
+ }
485
1575
  function collectProjectViews(entries) {
486
1576
  const views = ["all"];
487
- for (const view of ["js", "css", "html", "other"]) {
1577
+ for (const view of PROJECT_VIEW_ORDER.filter((view) => view !== "all")) {
488
1578
  if (entries.some((entry) => entry.view === view)) {
489
1579
  views.push(view);
490
1580
  }
@@ -500,6 +1590,18 @@ function countEntriesByView(entries) {
500
1590
  }
501
1591
  return counts;
502
1592
  }
1593
+ function createProjectNavigationTreeSearchText(node) {
1594
+ return [
1595
+ node.id,
1596
+ node.kind,
1597
+ node.label,
1598
+ node.entryId,
1599
+ node.sourcePath,
1600
+ node.symbolId,
1601
+ ...node.views,
1602
+ ...(node.children ?? []).map(createProjectNavigationTreeSearchText)
1603
+ ].filter((item) => typeof item === "string" && item.length > 0).join(" ").toLowerCase();
1604
+ }
503
1605
  function createProjectEntrySearchText(entry) {
504
1606
  return [
505
1607
  entry.id,
@@ -508,13 +1610,18 @@ function createProjectEntrySearchText(entry) {
508
1610
  entry.summary,
509
1611
  entry.signature,
510
1612
  entry.symbolId,
1613
+ entry.hierarchy?.assembly,
1614
+ entry.hierarchy?.namespace,
1615
+ entry.hierarchy?.containingType,
1616
+ entry.hierarchy?.parentSymbolId,
1617
+ ...(entry.hierarchy?.baseTypeIds ?? []),
1618
+ ...(entry.hierarchy?.interfaceIds ?? []),
511
1619
  entry.view,
512
1620
  entry.profile?.profileId,
513
1621
  entry.input?.kind,
514
1622
  entry.input?.path,
515
1623
  entry.source?.path,
516
1624
  entry.source?.language,
517
- entry.source?.preview?.content,
518
1625
  entry.docSourceMap?.path,
519
1626
  entry.docSourceMap?.entryId,
520
1627
  entry.docSourceMap?.sourcePath,
@@ -537,6 +1644,12 @@ function formatProjectViewLabel(view) {
537
1644
  if (view === "html") {
538
1645
  return "HTML";
539
1646
  }
1647
+ if (view === "dotnet") {
1648
+ return ".NET";
1649
+ }
1650
+ if (view === "powershell") {
1651
+ return "PowerShell";
1652
+ }
540
1653
  if (view === "all") {
541
1654
  return "All";
542
1655
  }