@agentskit/doc-bridge 1.7.45 → 1.9.0

package/src/render/template-source.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { toPosix } from '../lib/paths.js'
+import { compileTemplate, renderCompiledTemplate, type CompiledTemplate, type TemplateVariables } from './engine.js'
+import { BUNDLED_TEMPLATES, type RenderTemplateName } from './templates.js'
+
+/**
+ * Which template renders a name: the project's, when `render.templates` names one, otherwise
+ * the bundled one. An override is a file the project owns; it replaces the bundled template
+ * entirely and is compiled against the same engine, so a project changes its house style without
+ * a code change and a template that does not parse fails before anything is written.
+ */
+export type TemplateSource = {
+  readonly name: RenderTemplateName
+  readonly source: string
+  /** `bundled`, or the override path as configured. */
+  readonly origin: string
+}
+
+export const resolveTemplateSource = (name: RenderTemplateName, config: DocBridgeConfigV1, root?: string): TemplateSource => {
+  const override = config.render?.templates?.[name]
+  if (!override) return { name, source: BUNDLED_TEMPLATES[name], origin: 'bundled' }
+  const path = root ? resolve(root, override) : resolve(override)
+  let source: string
+  try {
+    source = readFileSync(path, 'utf8')
+  } catch (error) {
+    throw new Error(`render.templates["${name}"] points at ${toPosix(override)}, which could not be read: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  return { name, source, origin: toPosix(override) }
+}
+
+/*
+ * Compiled once per distinct source. The index builder and the conformance profile render
+ * `llms.txt` on every run, and parsing the same bundled template twice per run buys nothing.
+ */
+const compiled = new Map<string, CompiledTemplate>()
+
+const compile = (template: TemplateSource): CompiledTemplate => {
+  const key = JSON.stringify([template.name, template.origin, template.source])
+  let result = compiled.get(key)
+  if (!result) {
+    result = compileTemplate(template.source, template.origin === 'bundled' ? `template "${template.name}"` : template.origin)
+    compiled.set(key, result)
+  }
+  return result
+}
+
+export const renderNamedTemplate = (name: RenderTemplateName, variables: TemplateVariables, config: DocBridgeConfigV1, root?: string): string =>
+  renderCompiledTemplate(compile(resolveTemplateSource(name, config, root)), variables)

package/src/render/templates.ts

@@ -0,0 +1,289 @@
+/**
+ * The bundled templates.
+ *
+ * They live in a TypeScript module rather than next to it as `.md` files because the package
+ * ships `dist/` built by tsup, which bundles source and nothing else: a template on disk is a
+ * template the published package does not have. `ak-docs render <name> --print-template` prints
+ * one, which is how a project starts an override under `render.templates`.
+ *
+ * knap syntax, with one rule the syntax does not advertise: a block tag whose output is empty
+ * swallows the line break after it, and a block whose output is not empty swallows the line
+ * break at its own start instead. So a list is written as `{% for %}` followed by a standalone
+ * `{% if not … %}` block for its empty state — exactly one of the two renders, exactly one line
+ * break is consumed, and the blank line before the next heading survives either way. A test
+ * renders every template through knap's own engine to keep these shapes honest.
+ */
+
+export const RENDER_TEMPLATE_NAMES = ['llms.txt', 'area', 'ownership', 'change-digest', 'overlay-review'] as const
+
+export type RenderTemplateName = (typeof RENDER_TEMPLATE_NAMES)[number]
+
+export type RenderTemplateInfo = {
+  readonly name: RenderTemplateName
+  readonly description: string
+  /** What `--data` may point at, in place of the default source. */
+  readonly data: string
+  /** Whether the output is one Markdown page per unit rather than a single file. */
+  readonly multiPage: boolean
+  /** Whether the output carries generated-region markers. `llms.txt` is a whole-file artifact with its own consumers and carries none. */
+  readonly generatedRegion: boolean
+}
+
+export const RENDER_TEMPLATES: Readonly<Record<RenderTemplateName, RenderTemplateInfo>> = {
+  'llms.txt': {
+    name: 'llms.txt',
+    description: 'The curated reading order for agents, as `ak-docs index` writes it',
+    data: 'a DocBridgeIndex (.doc-bridge/index.json)',
+    multiPage: false,
+    generatedRegion: false,
+  },
+  area: {
+    name: 'area',
+    description: 'One page per code area: purpose, modules, documents, related areas, checks and open findings',
+    data: 'a DocBridgeIndex (.doc-bridge/index.json)',
+    multiPage: true,
+    generatedRegion: true,
+  },
+  ownership: {
+    name: 'ownership',
+    description: 'One sidecar per ownership record: where to start, what to read, what to run',
+    data: 'a DocBridgeIndex (.doc-bridge/index.json)',
+    multiPage: true,
+    generatedRegion: true,
+  },
+  'change-digest': {
+    name: 'change-digest',
+    description: 'Entities and documents whose content hash moved since the last scan, and the documents that should have moved with them',
+    data: 'the previous discovery snapshot to compare against (default: the last `ak-docs scan`)',
+    multiPage: false,
+    generatedRegion: true,
+  },
+  'overlay-review': {
+    name: 'overlay-review',
+    description: 'Pending agent proposals with their evidence, for a human to judge',
+    data: 'an enrichment overlay (default: .doc-bridge/enrich/overlay.json)',
+    multiPage: false,
+    generatedRegion: true,
+  },
+}
+
+export const isRenderTemplateName = (value: string): value is RenderTemplateName =>
+  (RENDER_TEMPLATE_NAMES as readonly string[]).includes(value)
+
+/*
+ * `llms.txt` must stay byte-identical to what the string concatenation produced, including the
+ * empty corpus: a preamble, a blank line, the heading, a blank line, the entries and a final
+ * newline — which for no entries is `## Knowledge` followed by three line breaks. An empty loop
+ * swallows the line break after `{% endfor %}`, so the empty case gets its own block: its three
+ * line breaks become two after the closing tag's line is trimmed and one after the block's own
+ * trim, which is the one the loop swallowed. The template ends at `{% endif %}` on purpose.
+ */
+const LLMS_TXT = `{{ preamble }}
+
+## Knowledge
+
+{% for entry in entries %}
+- [{{ entry.title }}]({{ entry.url }}){% if entry.description %}: {{ entry.description }}{% endif %}
+{% endfor %}
+{% if not entries %}
+
+
+{% endif %}`
+
+const AREA = `{{ region.open }}
+# Area \`{{ area.path }}\`
+
+{{ area.purpose }}
+{% if area.ownership %}
+
+{{ area.ownership }}
+{% endif %}
+
+## Modules
+
+{% for module in area.modules %}
+- \`{{ module.path }}\`{% if module.symbols %}: exports {{ module.symbols }}{% endif %}
+{% endfor %}
+{% if not area.modules %}
+No module was observed in this area.
+{% endif %}
+
+## Documents
+
+{% for document in area.documents %}
+- [{{ document.title }}]({{ document.path }}): {{ document.relation }}
+{% endfor %}
+{% if not area.documents %}
+No document covers or mentions this area.
+{% endif %}
+
+## Related areas
+
+{% for related in area.related %}
+- \`{{ related.path }}\`: {{ related.direction }}, {{ related.strength }} import(s) — {{ related.evidence }}
+{% endfor %}
+{% if not area.related %}
+No import crosses this area's boundary.
+{% endif %}
+
+## Checks
+
+{% for check in area.checks %}
+- \`{{ check }}\`
+{% endfor %}
+{% if not area.checks %}
+No check is declared for this area.
+{% endif %}
+{% if area.checksSource %}
+
+Source: {{ area.checksSource }}.
+{% endif %}
+
+## Open findings
+
+{% for finding in area.findings %}
+- **{{ finding.code }}** ({{ finding.severity }}, {{ finding.status }}): {{ finding.message }} — \`{{ finding.evidence }}\`
+{% endfor %}
+{% if not area.findings %}
+{{ area.findingsEmpty }}
+{% endif %}
+{{ region.close }}
+`
+
+const OWNERSHIP = `---
+type: {{ owner.kind }}
+id: {{ owner.id }}
+editRoot: {{ owner.path }}
+{% if owner.humanDoc %}
+humanDoc: {{ owner.humanDoc }}
+{% endif %}
+---
+
+{{ region.open }}
+# {{ owner.id }}
+
+{{ owner.purpose }}
+
+## Start here
+
+{{ owner.startHere }}
+
+## Read before editing
+
+{% for path in owner.readBeforeEditing %}
+- {{ path }}
+{% endfor %}
+{% if not owner.readBeforeEditing %}
+Nothing beyond the start page.
+{% endif %}
+
+## Edit roots
+
+{% for path in owner.editRoots %}
+- \`{{ path }}\`
+{% endfor %}
+
+## Checks
+
+{% for check in owner.checks %}
+- \`{{ check }}\`
+{% endfor %}
+{% if not owner.checks %}
+No check is declared.
+{% endif %}
+{% if owner.checksSource %}
+
+Source: {{ owner.checksSource }}.
+{% endif %}
+
+## Related areas
+
+{% for related in owner.related %}
+- \`{{ related.path }}\`: {{ related.direction }}, {{ related.strength }} import(s) — {{ related.evidence }}
+{% endfor %}
+{% if not owner.related %}
+No import crosses this unit's boundary.
+{% endif %}
+{{ region.close }}
+`
+
+const CHANGE_DIGEST = `{{ region.open }}
+# Change digest
+
+Compared the current tree with the previous snapshot: {{ digest.summary }}.
+
+## Changed
+
+{% for entity in digest.changed %}
+- \`{{ entity.path }}\` ({{ entity.kind }}): {{ entity.previousHash }} → {{ entity.currentHash }}
+{% endfor %}
+{% if not digest.changed %}
+No file-backed entity changed.
+{% endif %}
+
+## Added
+
+{% for entity in digest.added %}
+- \`{{ entity.path }}\` ({{ entity.kind }}): {{ entity.currentHash }}
+{% endfor %}
+{% if not digest.added %}
+Nothing was added.
+{% endif %}
+
+## Removed
+
+{% for entity in digest.removed %}
+- \`{{ entity.path }}\` ({{ entity.kind }}): {{ entity.previousHash }}
+{% endfor %}
+{% if not digest.removed %}
+Nothing was removed.
+{% endif %}
+
+## Documentation to review
+
+{% for document in digest.documentsToReview %}
+- \`{{ document.path }}\`: {{ document.because }}
+{% endfor %}
+{% if not digest.documentsToReview %}
+No unchanged document covers or mentions a changed entity.
+{% endif %}
+{{ region.close }}
+`
+
+const OVERLAY_REVIEW = `{{ region.open }}
+# Overlay review
+
+{% if overlay.present %}
+{{ overlay.summary }}
+
+{% for proposal in overlay.pending %}
+## {{ proposal.kind }}: \`{{ proposal.entity }}\`
+
+{{ proposal.reason }}
+
+Confidence {{ proposal.confidence }} · proposal \`{{ proposal.proposalId }}\`
+
+{% for item in proposal.evidence %}
+- {{ item.link }}
+{% endfor %}
+{% if not proposal.evidence %}
+No evidence was attached to this proposal.
+{% endif %}
+
+{% endfor %}
+{% if not overlay.pending %}
+No proposal is pending review.
+{% endif %}
+{% else %}
+No enrichment overlay exists for this repository. Run \`ak-docs enrich\` to produce one, or pass \`--data <overlay.json>\`.
+{% endif %}
+{{ region.close }}
+`
+
+export const BUNDLED_TEMPLATES: Readonly<Record<RenderTemplateName, string>> = {
+  'llms.txt': LLMS_TXT,
+  area: AREA,
+  ownership: OWNERSHIP,
+  'change-digest': CHANGE_DIGEST,
+  'overlay-review': OVERLAY_REVIEW,
+}

package/src/report/html.ts

@@ -354,7 +354,7 @@ styles += String.raw`.graph-node .node-label,.graph-node text.node-label{fill:va
 styles += String.raw`.report-tabs{display:flex;gap:0;align-items:flex-end;border-bottom:1px solid var(--line);margin:24px 0 0}.report-tabs .tab{font-size:13px}.breadcrumbs{display:flex;gap:6px;align-items:center;flex-wrap:wrap;margin:0 0 14px;color:var(--muted);font-size:12px}.breadcrumbs button{border:0;background:none;color:var(--blue);padding:3px 0;font-weight:700}.breadcrumbs button:hover{text-decoration:underline}.breadcrumbs .current{color:var(--ink);font-weight:700}.scope-note{margin:0 0 12px}.report-dashboard{display:grid;grid-template-columns:minmax(0,1.35fr) minmax(280px,1fr);gap:24px}.report-table{width:100%;border-collapse:collapse;font-size:12px}.report-table th,.report-table td{border-top:1px solid var(--line);padding:10px 8px;text-align:left;vertical-align:top}.report-table th{color:var(--muted);font-size:10px;letter-spacing:.08em;text-transform:uppercase}.report-table td:first-child{font-weight:750}.bar-list{display:grid;gap:10px}.bar-item{display:grid;grid-template-columns:minmax(120px,1fr) 2fr auto;gap:10px;align-items:center;font-size:12px}.bar-item i{height:8px;background:var(--line);display:block;overflow:hidden}.bar-item i b{display:block;height:100%;background:var(--green)}.map-wrap{touch-action:none;cursor:grab}.map-wrap.dragging{cursor:grabbing}@media(max-width:700px){.report-tabs{overflow:auto}.report-tabs .tab{white-space:nowrap}.report-dashboard{grid-template-columns:1fr}.bar-item{grid-template-columns:minmax(100px,1fr) 1fr auto}}`
 
 styles += String.raw`body[data-report-view="architecture"] #insights,body[data-report-view="architecture"] .filters,body[data-report-view="architecture"] .run,body[data-report-view="architecture"] .metadata{display:none}body[data-report-view="insights"] .workspace,body[data-report-view="insights"] .filters,body[data-report-view="insights"] .run,body[data-report-view="insights"] .metadata{display:none}body[data-report-view="findings"] .workspace,body[data-report-view="findings"] #insights,body[data-report-view="findings"] #report-dashboard,body[data-report-view="findings"] #coverage-title,body[data-report-view="findings"] #coverage-title~*{display:none}body[data-report-view="findings"] .run[aria-labelledby="coverage-title"]{display:none}body[data-report-view="coverage"] .workspace,body[data-report-view="coverage"] #insights,body[data-report-view="coverage"] #report-dashboard,body[data-report-view="coverage"] .filters,body[data-report-view="coverage"] .run[aria-labelledby="run-title"],body[data-report-view="coverage"] .metadata{display:none}body[data-report-view="insights"] #report-dashboard{display:block}body[data-report-view="map"] #report-dashboard{display:none}`
-styles += String.raw`body[data-report-view="architecture"] #report-dashboard{display:none!important}.edge{fill:none}`
+styles += String.raw`body[data-report-view="architecture"] #report-dashboard{display:none!important}.edge{fill:none}.edge.proposed{stroke-dasharray:6 4}`
 
 styles += String.raw`:root{--ink:#17251f;--muted:#586b63;--paper:#f2f5f1;--panel:#fbfcf9;--line:#c9d5cc;--green:#13734a;--blue:#155f78;--amber:#995d08;--red:#a52e2b}html,body{max-width:100%;overflow-x:hidden}body{font-size:15px;line-height:1.55}.shell{width:100%;max-width:1600px;margin:0 auto;padding:28px clamp(16px,3vw,48px) 56px}.masthead{gap:32px;padding:0 0 24px;align-items:flex-start}.masthead h1{font-size:clamp(2.8rem,5.5vw,5.4rem);line-height:.94;margin:12px 0 16px;max-width:100%;overflow-wrap:anywhere}.lede{max-width:60ch;font-size:16px}.run-meta{min-width:0;max-width:300px}.summary{margin:0;padding:18px 0 20px;grid-template-columns:repeat(5,minmax(0,1fr));gap:0}.metric{min-width:0;padding:0 16px;border-inline-start:1px solid var(--line)}.metric:first-child{padding-inline-start:0;border-inline-start:0}.metric b{font-size:clamp(1.8rem,3vw,3rem);max-width:100%;overflow-wrap:anywhere}.metric span{font-size:10px;letter-spacing:.06em;line-height:1.25}.lens-bar{margin:24px 0 4px;align-items:flex-end}.lens-bar>.subtle{max-width:52ch}.report-tabs{max-width:100%;overflow-x:auto}.tab,.level{min-height:40px;padding:8px 12px}.filters{max-width:100%;align-items:center}.filters label{min-width:0}.filters input,.filters select{max-width:100%;min-width:0}.workspace{min-width:0;grid-template-columns:minmax(0,1fr) minmax(280px,340px);gap:20px}.panel{min-width:0}.map-wrap{min-width:0;max-width:100%;width:100%;overflow:hidden;contain:layout paint}#graph{display:block;width:100%!important;min-width:0!important;max-width:100%;height:clamp(480px,60vh,680px)!important}.side{min-width:0}.detail-title,.path,.list,.finding,.finding-group,.report-table{min-width:0;overflow-wrap:anywhere}.report-dashboard{min-width:0}.report-table{table-layout:fixed}.report-table th,.report-table td{overflow-wrap:anywhere}.bar-item{min-width:0}.bar-item span{min-width:0;overflow-wrap:anywhere}.tab:focus-visible,.level:focus-visible,input:focus-visible,select:focus-visible{outline:3px solid var(--blue);outline-offset:2px}@media(max-width:1100px){.workspace{grid-template-columns:1fr}.side{position:static}.summary{grid-template-columns:repeat(3,minmax(0,1fr));row-gap:16px}.summary .metric:nth-child(4){border-inline-start:0;padding-inline-start:0}}@media(max-width:700px){.shell{padding:12px 16px 32px}.masthead{padding-bottom:14px}.masthead h1{font-size:clamp(2.2rem,11vw,3.4rem);margin:6px 0 10px}.lede{font-size:14px;line-height:1.35}.run-meta{display:none}.summary{padding:10px 0 12px;grid-template-columns:repeat(2,minmax(0,1fr));row-gap:8px}.summary .metric:nth-child(even){border-inline-start:1px solid var(--line);padding-inline-start:12px}.summary .metric:nth-child(odd){border-inline-start:0;padding-inline-start:0}.metric{padding-inline:10px}.metric b{font-size:1.65rem}.lens-bar{display:block;margin-top:14px}.lens-bar>.subtle{display:none}.filters{display:grid;grid-template-columns:1fr;gap:10px}.filters label{display:grid;grid-template-columns:1fr;gap:5px}.filters input,.filters select,.filters button{width:100%;min-height:44px}.panel{padding:16px}.panel-head{display:block}.panel-head>.tabs{margin-top:12px}.finding-groups{grid-template-columns:1fr}.report-dashboard{grid-template-columns:1fr}#graph{height:520px!important}.lens-bar + #lens-caption{margin:8px 0}.lens-bar + #lens-caption + #insights{margin-top:8px}}@media(prefers-color-scheme:dark){:root{--ink:#edf5ef;--muted:#b7c6ba;--paper:#111815;--panel:#1a2821;--line:#405248;--green:#73d19d;--blue:#8bd1e6;--amber:#f0bd70;--red:#ff9389}}`
 
@@ -419,7 +419,7 @@ document.addEventListener("click",(event)=>{const node=event.target.closest?.("[
 document.addEventListener("click",(event)=>{const crumb=event.target.closest?.("[data-breadcrumb-level]");if(!crumb)return;event.preventDefault();event.stopImmediatePropagation();state.level=crumb.dataset.breadcrumbLevel;state.selected=crumb.dataset.breadcrumbSelected||null;mapState.scale=1;mapState.x=0;mapState.y=0;render()},true);
 const diagnosticsFor=(id)=>(findingIndex.get(id)||[]).filter((finding)=>finding.status!=="confirmed");
 const renderDetails=()=>{const panel=document.querySelector("#details"),entity=state.selected?byId.get(state.selected):null,group=state.selected?groupById.get(state.selected):null;if(group){const members=group.members.map((id)=>byId.get(id)).filter(Boolean),relations=new Set(),ids=groupEntityIds.get(state.selected)||new Set();ids.forEach((id)=>(relationsByEntity.get(id)||[]).forEach((relation)=>relations.add(relation)));const findings=nodeIssues(state.selected),evidence=members.flatMap((member)=>member.evidence||[]).slice(0,8),unit=group.kind==="external"?"dependencies":"packages";panel.innerHTML="<div class=\"eyebrow\">Selected group</div><h2 class=\"detail-title\">"+esc(group.name)+"</h2><span class=\"tag\">"+esc(group.kind)+"</span><p class=\"path\">"+esc(group.path||"Derived from stable package identity and repository structure")+"</p><div class=\"detail-grid\"><div><b>"+members.length+"</b><span>"+unit+"</span></div><div><b>"+relations.size+"</b><span>relations</span></div><div><b>"+findings.length+"</b><span>findings</span></div><div><b>"+evidence.length+"</b><span>evidence items</span></div></div><h3>Members</h3><ul class=\"list\">"+(members.length?members.slice(0,8).map((member)=>"<li>"+esc(label(member))+"</li>").join(""):"<li>No members recorded.</li>")+(members.length>8?"<li class=\"subtle\">+"+(members.length-8)+" more — choose Package level to inspect all.</li>":"")+"</ul>"+(findings.length?"<h3 style=\"margin-top:16px\">Attention</h3><ul class=\"list\">"+findings.slice(0,5).map((finding)=>"<li><span class=\"tag "+esc(finding.severity)+"\">"+esc(finding.severity)+"</span> "+esc(finding.code)+"</li>").join("")+"</ul>":"");return}if(!entity){panel.innerHTML="<p class=\"subtle\">Select a node in the map to inspect its evidence, connectivity, and findings.</p>";return}const relations=relationsByEntity.get(entity.id)||[],incoming=relations.filter((relation)=>relation.to===entity.id),outgoing=relations.filter((relation)=>relation.from===entity.id),findings=diagnosticsFor(entity.id),evidence=[...(entity.evidence||[]),...incoming.flatMap((relation)=>relation.evidence||[]),...outgoing.flatMap((relation)=>relation.evidence||[])].slice(0,8);panel.innerHTML="<div class=\"eyebrow\">Selected entity</div><h2 class=\"detail-title\">"+esc(label(entity))+"</h2><span class=\"tag\">"+esc(entity.kind)+"</span><p class=\"path\">"+esc(entity.path||entity.id)+"</p><div class=\"detail-grid\"><div><b>"+incoming.length+"</b><span>incoming</span></div><div><b>"+outgoing.length+"</b><span>outgoing</span></div><div><b>"+findings.length+"</b><span>findings</span></div><div><b>"+evidence.length+"</b><span>evidence items</span></div></div><h3>Evidence</h3><ul class=\"list\">"+(evidence.length?evidence.map((item)=>"<li>"+esc(item.path+(item.lineStart?":"+item.lineStart:"")+(item.context?" — "+item.context:""))+"</li>").join(""):"<li>No evidence recorded.</li>")+"</ul>"+(findings.length?"<h3 style=\"margin-top:16px\">Attention</h3><ul class=\"list\">"+findings.slice(0,5).map((finding)=>"<li><span class=\"tag "+esc(finding.severity)+"\">"+esc(finding.severity)+"</span> "+esc(finding.code)+"</li>").join("")+"</ul>":"")};
-const renderGraph=()=>{const model=graphModel(),svg=document.querySelector("#graph"),dense=model.edges.length>64,edges=dense?[...model.edges].sort((a,b)=>(b.health?1:0)-(a.health?1:0)||b.count-a.count||a.from.localeCompare(b.from)||a.to.localeCompare(b.to)).slice(0,64):model.edges;if(!model.nodes.length){svg.innerHTML="<text x=\"500\" y=\"270\" text-anchor=\"middle\" class=\"subtle\">Select an app or package to expand this view.</text>";return}const ids=new Set(model.nodes.map((node)=>node.id)),incoming=new Map(model.nodes.map((node)=>[node.id,0])),outgoing=new Map(model.nodes.map((node)=>[node.id,[]]));edges.forEach((edge)=>{if(!ids.has(edge.from)||!ids.has(edge.to))return;incoming.set(edge.to,(incoming.get(edge.to)||0)+1);outgoing.get(edge.from).push(edge.to)});const rank=new Map(),work=[];model.nodes.filter((node)=>(incoming.get(node.id)||0)===0).sort((a,b)=>label(a).localeCompare(label(b))||a.id.localeCompare(b.id)).forEach((node)=>{rank.set(node.id,0);work.push(node)});for(let index=0;index<work.length;index++){const node=work[index];for(const next of outgoing.get(node.id)||[]){const nextRank=Math.max(rank.get(next)||0,(rank.get(node.id)||0)+1);rank.set(next,nextRank);if(!work.some((item)=>item.id===next))work.push(byId.get(next)||{id:next,name:next})}}model.nodes.forEach((node)=>{if(!rank.has(node.id))rank.set(node.id,0)});const columns=new Map();model.nodes.forEach((node)=>{const items=columns.get(rank.get(node.id))||[];items.push(node);columns.set(rank.get(node.id),items)});for(const items of columns.values())items.sort((a,b)=>label(a).localeCompare(label(b))||a.id.localeCompare(b.id));if(dense){columns.clear();model.nodes.forEach((node,index)=>{const column=Math.floor(index/8),items=columns.get(column)||[];items.push(node);columns.set(column,items)})}const maxRows=Math.max(1,...[...columns.values()].map((items)=>items.length)),cellWidth=190,cellHeight=82,pad=28,columnCount=Math.max(1,...columns.keys())+1,width=Math.max(620,columnCount*cellWidth+pad*2,Math.min(1000,svg.clientWidth*1.05)),height=Math.max(520,maxRows*cellHeight+pad*2);svg.setAttribute("viewBox","0 0 "+width+" "+height);svg.style.width=dense?Math.max(1000,width)+"px":"100%";svg.style.minWidth="0";svg.style.height="100%";document.querySelector(".map-wrap")?.classList.toggle("dense",dense);const positions=new Map();for(const [column,items] of columns)items.forEach((node,row)=>positions.set(node.id,{x:pad+column*cellWidth+78,y:pad+row*cellHeight+27}));const defs="<defs><marker id=\"arrow\" markerWidth=\"8\" markerHeight=\"8\" refX=\"7\" refY=\"3\" orient=\"auto\"><path d=\"M0,0 L0,6 L7,3 z\" fill=\"#789087\"/></marker></defs>",edgeMarkup=edges.map((edge)=>{const from=positions.get(edge.from),to=positions.get(edge.to);if(!from||!to)return "";const midX=(from.x+to.x)/2,midY=(from.y+to.y)/2;return "<g><line class=\"edge "+(edge.health?"alert":"")+"\" x1=\""+from.x+"\" y1=\""+from.y+"\" x2=\""+to.x+"\" y2=\""+to.y+"\" marker-end=\"url(#arrow)\"/><text class=\"edge-label\" x=\""+midX+"\" y=\""+midY+"\">"+esc(edge.count>1?edge.count+"×":"")+"</text></g>"}).join(""),nodes=model.nodes.map((node)=>{const pos=positions.get(node.id),issues=nodeIssues(node.id),degree=degreeMap(edges).get(node.id)||0,selected=state.selected===node.id?" selected":"",issue=issues.length?" issue":"",nodeLabel=label(node),nodeKind=node.kind==="domain"?(node.memberCount||0)+" packages":node.kind;return "<g class=\"graph-node"+selected+issue+"\" transform=\"translate("+(pos.x-78)+","+(pos.y-27)+")\"><title>"+esc(nodeLabel)+" · "+esc(nodeKind)+"</title><rect width=\"156\" height=\"54\" rx=\"8\" role=\"button\" tabindex=\"0\" aria-label=\""+esc(nodeLabel+" "+nodeKind)+"\" data-node=\""+esc(node.id)+"\"></rect><text class=\"node-label\" x=\"10\" y=\"19\">"+esc(short(nodeLabel,22))+"</text><text class=\"node-kind\" x=\"10\" y=\"34\">"+esc(short(nodeKind,22))+"</text><text class=\"node-count\" x=\"144\" y=\"19\" text-anchor=\"end\">"+(degree||"")+"</text></g>"}).join("");svg.innerHTML=defs+edgeMarkup+nodes;routeGraphEdges();applyMapTransform();document.querySelector("#map-note").textContent=(state.level==="overview"?"Bounded domain view. ":state.level+" view. ")+"Directional edges are aggregated from canonical relations; "+model.edges.length+" visible connection groups"+(dense?" (showing "+edges.length+" prioritized of "+model.edges.length+").":".");};
+const renderGraph=()=>{const model=graphModel(),svg=document.querySelector("#graph"),dense=model.edges.length>64,edges=dense?[...model.edges].sort((a,b)=>(b.health?1:0)-(a.health?1:0)||b.count-a.count||a.from.localeCompare(b.from)||a.to.localeCompare(b.to)).slice(0,64):model.edges;if(!model.nodes.length){svg.innerHTML="<text x=\"500\" y=\"270\" text-anchor=\"middle\" class=\"subtle\">Select an app or package to expand this view.</text>";return}const ids=new Set(model.nodes.map((node)=>node.id)),incoming=new Map(model.nodes.map((node)=>[node.id,0])),outgoing=new Map(model.nodes.map((node)=>[node.id,[]]));edges.forEach((edge)=>{if(!ids.has(edge.from)||!ids.has(edge.to))return;incoming.set(edge.to,(incoming.get(edge.to)||0)+1);outgoing.get(edge.from).push(edge.to)});const rank=new Map(),work=[];model.nodes.filter((node)=>(incoming.get(node.id)||0)===0).sort((a,b)=>label(a).localeCompare(label(b))||a.id.localeCompare(b.id)).forEach((node)=>{rank.set(node.id,0);work.push(node)});for(let index=0;index<work.length;index++){const node=work[index];for(const next of outgoing.get(node.id)||[]){const nextRank=Math.max(rank.get(next)||0,(rank.get(node.id)||0)+1);rank.set(next,nextRank);if(!work.some((item)=>item.id===next))work.push(byId.get(next)||{id:next,name:next})}}model.nodes.forEach((node)=>{if(!rank.has(node.id))rank.set(node.id,0)});const columns=new Map();model.nodes.forEach((node)=>{const items=columns.get(rank.get(node.id))||[];items.push(node);columns.set(rank.get(node.id),items)});for(const items of columns.values())items.sort((a,b)=>label(a).localeCompare(label(b))||a.id.localeCompare(b.id));if(dense){columns.clear();model.nodes.forEach((node,index)=>{const column=Math.floor(index/8),items=columns.get(column)||[];items.push(node);columns.set(column,items)})}const maxRows=Math.max(1,...[...columns.values()].map((items)=>items.length)),cellWidth=190,cellHeight=82,pad=28,columnCount=Math.max(1,...columns.keys())+1,width=Math.max(620,columnCount*cellWidth+pad*2,Math.min(1000,svg.clientWidth*1.05)),height=Math.max(520,maxRows*cellHeight+pad*2);svg.setAttribute("viewBox","0 0 "+width+" "+height);svg.style.width=dense?Math.max(1000,width)+"px":"100%";svg.style.minWidth="0";svg.style.height="100%";document.querySelector(".map-wrap")?.classList.toggle("dense",dense);const positions=new Map();for(const [column,items] of columns)items.forEach((node,row)=>positions.set(node.id,{x:pad+column*cellWidth+78,y:pad+row*cellHeight+27}));const defs="<defs><marker id=\"arrow\" markerWidth=\"8\" markerHeight=\"8\" refX=\"7\" refY=\"3\" orient=\"auto\"><path d=\"M0,0 L0,6 L7,3 z\" fill=\"#789087\"/></marker></defs>",edgeMarkup=edges.map((edge)=>{const from=positions.get(edge.from),to=positions.get(edge.to);if(!from||!to)return "";const midX=(from.x+to.x)/2,midY=(from.y+to.y)/2;const proposed=[...edge.relationIds].length>0&&[...edge.relationIds].every((id)=>relationById.get(id)?.provenance==="proposed");return "<g><line class=\"edge "+(edge.health?"alert":"")+(proposed?" proposed":"")+"\" x1=\""+from.x+"\" y1=\""+from.y+"\" x2=\""+to.x+"\" y2=\""+to.y+"\" marker-end=\"url(#arrow)\"/><text class=\"edge-label\" x=\""+midX+"\" y=\""+midY+"\">"+esc(edge.count>1?edge.count+"×":"")+"</text></g>"}).join(""),nodes=model.nodes.map((node)=>{const pos=positions.get(node.id),issues=nodeIssues(node.id),degree=degreeMap(edges).get(node.id)||0,selected=state.selected===node.id?" selected":"",issue=issues.length?" issue":"",nodeLabel=label(node),nodeKind=node.kind==="domain"?(node.memberCount||0)+" packages":node.kind;return "<g class=\"graph-node"+selected+issue+"\" transform=\"translate("+(pos.x-78)+","+(pos.y-27)+")\"><title>"+esc(nodeLabel)+" · "+esc(nodeKind)+"</title><rect width=\"156\" height=\"54\" rx=\"8\" role=\"button\" tabindex=\"0\" aria-label=\""+esc(nodeLabel+" "+nodeKind)+"\" data-node=\""+esc(node.id)+"\"></rect><text class=\"node-label\" x=\"10\" y=\"19\">"+esc(short(nodeLabel,22))+"</text><text class=\"node-kind\" x=\"10\" y=\"34\">"+esc(short(nodeKind,22))+"</text><text class=\"node-count\" x=\"144\" y=\"19\" text-anchor=\"end\">"+(degree||"")+"</text></g>"}).join("");svg.innerHTML=defs+edgeMarkup+nodes;routeGraphEdges();applyMapTransform();document.querySelector("#map-note").textContent=(state.level==="overview"?"Bounded domain view. ":state.level+" view. ")+"Directional edges are aggregated from canonical relations; "+model.edges.length+" visible connection groups"+(dense?" (showing "+edges.length+" prioritized of "+model.edges.length+").":".");};
 const findingMatches=(finding)=>{const query=state.query.toLowerCase();return(!query||[finding.id,finding.code,finding.message,...finding.entityIds,...finding.relationIds].join(" ").toLowerCase().includes(query))&&(!state.status||finding.status===state.status)&&(!state.severity||finding.severity===state.severity)};
 const findingScope=(finding)=>data.view?.diagnosticGroup?.[finding.id]?.[0]||(()=>{const ids=[...(finding.entityIds||[])];(finding.relationIds||[]).forEach((id)=>{const relation=relationById.get(id);if(relation)ids.push(relation.from,relation.to)});return ids.map(groupFor).sort()[0]||"repository"})();
 const findingGroups=(findings)=>{const groups=new Map();findings.forEach((finding)=>{const scope=findingScope(finding),key=[scope,finding.code,finding.status,finding.severity].join("|"),group=groups.get(key)||{key,scope,code:finding.code,status:finding.status,severity:finding.severity,findings:[]};group.findings.push(finding);groups.set(key,group)});return[...groups.values()].sort((left,right)=>right.findings.length-left.findings.length||left.code.localeCompare(right.code)||left.key.localeCompare(right.key))};

package/src/retrieval/bm25.ts

@@ -0,0 +1,161 @@
+import { searchTokens } from '../query/text.js'
+
+/**
+ * Field-weighted BM25 (BM25F).
+ *
+ * Retrieval used to score a record by summing token lengths over one flattened haystack, which
+ * made a long document beat a short exact match and gave every field the same authority. BM25
+ * fixes both: a term that appears in nearly every record earns almost nothing (IDF), a term in a
+ * short title outranks the same term buried in a body (per-field length normalization), and the
+ * field a term matched in is part of the result, so ranking can be explained rather than guessed.
+ *
+ * Ordering is total: score descending, then `ref` ascending. Scores are rounded before comparison
+ * so a ranking is reproducible and never depends on floating-point accumulation order.
+ */
+
+export const BM25_VERSION = 1 as const
+
+const DEFAULT_K1 = 1.2
+const DEFAULT_B = 0.75
+const SCORE_PRECISION = 1_000_000
+
+/** Per-field multipliers. A field absent from the map is not indexed at all. */
+export type Bm25FieldWeights = Readonly<Record<string, number>>
+
+export type Bm25Params = {
+  /** Term-frequency saturation. Higher rewards repetition more. */
+  readonly k1?: number
+  /** Length-normalization strength, 0 to 1. */
+  readonly b?: number
+}
+
+export type Bm25FieldValue = string | readonly string[] | undefined
+
+export type Bm25Input = {
+  readonly ref: string
+  readonly fields: Readonly<Record<string, Bm25FieldValue>>
+}
+
+export type Bm25Hit = {
+  readonly ref: string
+  readonly score: number
+  /** Query terms that matched, per field, sorted. The raw material for an explain view. */
+  readonly matched: Readonly<Record<string, readonly string[]>>
+}
+
+type FieldPosting = {
+  readonly frequency: number
+  readonly length: number
+}
+
+type IndexedDocument = {
+  readonly ref: string
+  /** field -> term -> frequency, plus the field's token length. */
+  readonly fields: ReadonlyMap<string, { readonly tokens: ReadonlyMap<string, number>; readonly length: number }>
+}
+
+export type Bm25Index = {
+  readonly documents: readonly IndexedDocument[]
+  readonly documentFrequency: ReadonlyMap<string, number>
+  readonly averageFieldLength: ReadonlyMap<string, number>
+  readonly weights: Bm25FieldWeights
+  readonly k1: number
+  readonly b: number
+}
+
+const fieldText = (value: Bm25FieldValue): string =>
+  value === undefined ? '' : Array.isArray(value) ? value.join(' ') : String(value)
+
+const round = (value: number): number => Math.round(value * SCORE_PRECISION) / SCORE_PRECISION
+
+export const buildBm25Index = (
+  inputs: readonly Bm25Input[],
+  weights: Bm25FieldWeights,
+  params: Bm25Params = {},
+): Bm25Index => {
+  const fieldNames = Object.keys(weights).sort()
+  const documents: IndexedDocument[] = []
+  const documentFrequency = new Map<string, number>()
+  const fieldLengthTotal = new Map<string, number>(fieldNames.map((name) => [name, 0]))
+
+  for (const input of inputs) {
+    const fields = new Map<string, { tokens: ReadonlyMap<string, number>; length: number }>()
+    const seen = new Set<string>()
+    for (const name of fieldNames) {
+      const tokens = searchTokens(fieldText(input.fields[name]))
+      const frequencies = new Map<string, number>()
+      for (const token of tokens) {
+        frequencies.set(token, (frequencies.get(token) ?? 0) + 1)
+        seen.add(token)
+      }
+      fields.set(name, { tokens: frequencies, length: tokens.length })
+      fieldLengthTotal.set(name, (fieldLengthTotal.get(name) ?? 0) + tokens.length)
+    }
+    for (const token of seen) documentFrequency.set(token, (documentFrequency.get(token) ?? 0) + 1)
+    documents.push({ ref: input.ref, fields })
+  }
+
+  const count = documents.length || 1
+  return {
+    documents,
+    documentFrequency,
+    averageFieldLength: new Map(fieldNames.map((name) => [name, (fieldLengthTotal.get(name) ?? 0) / count])),
+    weights,
+    k1: params.k1 ?? DEFAULT_K1,
+    b: params.b ?? DEFAULT_B,
+  }
+}
+
+/** Probabilistic IDF, floored at zero so a term in every document can never subtract score. */
+export const bm25Idf = (documentCount: number, documentFrequency: number): number =>
+  Math.max(0, Math.log(1 + (documentCount - documentFrequency + 0.5) / (documentFrequency + 0.5)))
+
+const posting = (document: IndexedDocument, field: string, term: string): FieldPosting | undefined => {
+  const stats = document.fields.get(field)
+  if (!stats) return undefined
+  const frequency = stats.tokens.get(term)
+  return frequency === undefined ? undefined : { frequency, length: stats.length }
+}
+
+/**
+ * Score every document against the query terms. Documents with no matched term are omitted, so an
+ * unrelated query returns nothing rather than a list of weak guesses.
+ */
+export const bm25Search = (index: Bm25Index, terms: readonly string[]): Bm25Hit[] => {
+  if (!terms.length || !index.documents.length) return []
+  const unique = [...new Set(terms)].sort()
+  const fieldNames = Object.keys(index.weights).sort()
+  const hits: Bm25Hit[] = []
+
+  for (const document of index.documents) {
+    let score = 0
+    const matched = new Map<string, string[]>()
+
+    for (const term of unique) {
+      const idf = bm25Idf(index.documents.length, index.documentFrequency.get(term) ?? 0)
+      if (idf <= 0) continue
+      let weightedFrequency = 0
+      for (const field of fieldNames) {
+        const found = posting(document, field, term)
+        if (!found) continue
+        const average = index.averageFieldLength.get(field) ?? 0
+        const normalization = average > 0 ? 1 - index.b + index.b * (found.length / average) : 1
+        weightedFrequency += ((index.weights[field] ?? 0) * found.frequency) / normalization
+        const list = matched.get(field)
+        if (list) list.push(term)
+        else matched.set(field, [term])
+      }
+      if (weightedFrequency <= 0) continue
+      score += (idf * weightedFrequency) / (index.k1 + weightedFrequency)
+    }
+
+    if (score <= 0) continue
+    hits.push({
+      ref: document.ref,
+      score: round(score),
+      matched: Object.fromEntries([...matched.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([field, list]) => [field, [...list].sort()])),
+    })
+  }
+
+  return hits.sort((a, b) => (b.score !== a.score ? b.score - a.score : a.ref.localeCompare(b.ref)))
+}