@agentskit/doc-bridge 1.4.3 → 1.5.1

package/src/reconciliation/reconcile.ts

@@ -0,0 +1,227 @@
+import { contentHashForArtifactV1, sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import {
+  ReconciliationReportV1Schema,
+  type DiscoverySnapshotV1,
+  type Evidence,
+  type KnowledgeEntity,
+  type KnowledgeRelation,
+  type ReconciliationReportV1,
+} from '../schemas/knowledge.js'
+
+type EntityResolver = (reference: string) => string
+
+const ignoredDocumentationRelations = new Set(['covers'])
+
+const metadataDetection = (relation: KnowledgeRelation): string | undefined => {
+  const detection = relation.metadata?.detection
+  return typeof detection === 'string' ? detection : undefined
+}
+
+const relationDetection = (relation: KnowledgeRelation): string =>
+  relation.discriminator ?? metadataDetection(relation) ?? 'static'
+
+const entityResolver = (snapshots: readonly DiscoverySnapshotV1[]): EntityResolver => {
+  const references = new Map<string, string>()
+  const entities = snapshots.flatMap((snapshot) => snapshot.entities).sort((a, b) => a.id.localeCompare(b.id))
+  for (const entity of entities) {
+    references.set(entity.id, entity.id)
+    for (const alias of entity.aliases ?? []) {
+      if (!references.has(alias)) references.set(alias, entity.id)
+    }
+  }
+  return (reference) => references.get(reference) ?? reference
+}
+
+const relationBase = (relation: KnowledgeRelation, resolveEntity: EntityResolver): string =>
+  `${resolveEntity(relation.from)}\u0000${resolveEntity(relation.to)}\u0000${relation.kind}`
+
+const evidenceKey = (item: Evidence): string =>
+  `${item.source}:${item.path}:${item.lineStart ?? ''}:${item.lineEnd ?? ''}:${item.context ?? ''}`
+
+const mergeEvidence = (...relations: readonly KnowledgeRelation[]): Evidence[] => {
+  const merged = new Map<string, Evidence>()
+  for (const relation of relations) {
+    for (const item of relation.evidence) merged.set(evidenceKey(item), item)
+  }
+  return [...merged.values()].sort((a, b) => evidenceKey(a).localeCompare(evidenceKey(b)))
+}
+
+const diagnosticId = (code: string, value: unknown): string =>
+  `reconciliation:${code}:${sha256NormalizedV1(value).slice(0, 32)}`
+
+const coverageAvailable = (snapshot: DiscoverySnapshotV1, relation: KnowledgeRelation): boolean => {
+  const status = snapshot.coverage.find((entry) =>
+    entry.scope === 'static-imports-and-exports' && (relation.kind === 'imports' || relation.kind === 're-exports'),
+  )?.status
+  return status === undefined || status === 'complete'
+}
+
+const entityById = (snapshots: readonly DiscoverySnapshotV1[]): ReadonlyMap<string, KnowledgeEntity> => {
+  const entities = new Map<string, KnowledgeEntity>()
+  for (const snapshot of snapshots) {
+    for (const entity of snapshot.entities) if (!entities.has(entity.id)) entities.set(entity.id, entity)
+  }
+  return entities
+}
+
+const isUnresolved = (id: string, entities: ReadonlyMap<string, KnowledgeEntity>): boolean =>
+  id.startsWith('unresolved:') || entities.get(id)?.kind === 'unresolved-reference'
+
+const relationMatches = (observed: KnowledgeRelation, declared: KnowledgeRelation, resolveEntity: EntityResolver): boolean => {
+  if (relationBase(observed, resolveEntity) !== relationBase(declared, resolveEntity)) return false
+  return relationDetection(declared) === relationDetection(observed)
+}
+
+const reportDiagnostic = (
+  code: string,
+  status: ReconciliationReportV1['diagnostics'][number]['status'],
+  severity: ReconciliationReportV1['diagnostics'][number]['severity'],
+  message: string,
+  evidence: readonly Evidence[],
+  value: unknown,
+  entityIds?: readonly string[],
+  relationIds?: readonly string[],
+  remediation?: string,
+): ReconciliationReportV1['diagnostics'][number] => ({
+  id: diagnosticId(code, value),
+  code,
+  status,
+  severity,
+  message,
+  evidence: [...evidence],
+  ...(entityIds?.length ? { entityIds: [...entityIds] } : {}),
+  ...(relationIds?.length ? { relationIds: [...relationIds] } : {}),
+  ...(remediation ? { remediation } : {}),
+})
+
+export const reconcileKnowledge = (
+  observed: DiscoverySnapshotV1,
+  declared: DiscoverySnapshotV1,
+): ReconciliationReportV1 => {
+  const resolveEntity = entityResolver([observed, declared])
+  const entities = entityById([observed, declared])
+  const observedRelations = observed.relations.filter((relation) => relation.provenance === 'observed' && !ignoredDocumentationRelations.has(relation.kind))
+  const declaredRelations = declared.relations.filter((relation) => relation.provenance === 'declared' && !ignoredDocumentationRelations.has(relation.kind))
+  const diagnostics: ReconciliationReportV1['diagnostics'][number][] = []
+
+  for (const entity of declared.entities.filter((item) => isUnresolved(item.id, entities)).sort((a, b) => a.id.localeCompare(b.id))) {
+    diagnostics.push(reportDiagnostic(
+      'UNRESOLVED_ENTITY_REFERENCE',
+      'unresolved',
+      'error',
+      `Declared reference could not be resolved: ${entity.name}.`,
+      entity.evidence,
+      entity.id,
+      [entity.id],
+      undefined,
+      'Resolve the reference to an observed entity ID or configured alias.',
+    ))
+  }
+
+  const declaredByBase = new Map<string, KnowledgeRelation[]>()
+  for (const relation of declaredRelations) {
+    const base = relationBase(relation, resolveEntity)
+    const group = declaredByBase.get(base) ?? []
+    group.push(relation)
+    declaredByBase.set(base, group)
+  }
+
+  for (const group of declaredByBase.values()) {
+    const detections = new Set(group.map(relationDetection))
+    if (detections.size < 2) continue
+    diagnostics.push(reportDiagnostic(
+      'CONFLICTING_DECLARATIONS',
+      'conflict',
+      'error',
+      'Declarations for the same semantic relation disagree on detection.',
+      mergeEvidence(...group),
+      [relationBase(group[0] as KnowledgeRelation, resolveEntity), [...detections].sort()],
+      undefined,
+      group.map((relation) => relation.id),
+      'Keep one detection value for this relation or document the intended distinction with a different relation kind.',
+    ))
+  }
+
+  for (const relation of observedRelations) {
+    const candidates = declaredByBase.get(relationBase(relation, resolveEntity)) ?? []
+    const match = candidates.find((candidate) => relationMatches(relation, candidate, resolveEntity))
+    if (match) {
+      diagnostics.push(reportDiagnostic(
+        'RELATION_CONFIRMED',
+        'confirmed',
+        'info',
+        'Observed relation is covered by a matching declaration.',
+        mergeEvidence(relation, match),
+        relation.id,
+        undefined,
+        [relation.id, match.id],
+      ))
+    } else if (coverageAvailable(observed, relation)) {
+      diagnostics.push(reportDiagnostic(
+        'RELATION_UNDOCUMENTED',
+        'undocumented',
+        'warn',
+        'Observed relation has no matching documentation declaration.',
+        relation.evidence,
+        relation.id,
+        undefined,
+        [relation.id],
+        'Add a matching relation declaration or configure this relation kind as intentionally undocumented.',
+      ))
+    }
+  }
+
+  for (const relation of declaredRelations) {
+    const candidates = observedRelations.filter((candidate) => relationBase(candidate, resolveEntity) === relationBase(relation, resolveEntity))
+    const detection = relationDetection(relation)
+    if (candidates.some((candidate) => relationMatches(candidate, relation, resolveEntity))) continue
+    if (isUnresolved(resolveEntity(relation.from), entities) || isUnresolved(resolveEntity(relation.to), entities)) continue
+    if (detection === 'dynamic' || detection === 'external') {
+      diagnostics.push(reportDiagnostic(
+        'RELATION_NOT_ANALYZED',
+        'not-analyzed',
+        'info',
+        `Declared ${detection} relation cannot be verified by the current static analyzer.`,
+        relation.evidence,
+        relation.id,
+        undefined,
+        [relation.id],
+        'Enable a compatible analyzer or provide explicit observed evidence before treating this relation as confirmed.',
+      ))
+    } else if (coverageAvailable(observed, relation)) {
+      diagnostics.push(reportDiagnostic(
+        'DECLARED_RELATION_STALE',
+        'stale-or-unverified',
+        'warn',
+        candidates.length ? 'Declared relation has incompatible observed evidence.' : 'Declared static relation was not observed.',
+        candidates.length ? mergeEvidence(relation, ...candidates) : relation.evidence,
+        relation.id,
+        undefined,
+        [relation.id, ...candidates.map((candidate) => candidate.id)],
+        'Update the declaration or the implementation so both graphs describe the same relation.',
+      ))
+    }
+  }
+
+  const sortedDiagnostics = [...diagnostics].sort((a, b) => a.id.localeCompare(b.id))
+  const base = {
+    type: 'reconciliation-report' as const,
+    schemaVersion: 1 as const,
+    contentHash: '0'.repeat(64),
+    contentHashAlgo: observed.contentHashAlgo,
+    project: observed.project,
+    sourceRevision: observed.sourceRevision,
+    sourceRevisionKind: observed.sourceRevisionKind,
+    configurationHash: observed.configurationHash,
+    pipelineVersion: observed.pipelineVersion,
+    analyzerVersions: observed.analyzerVersions,
+    snapshotHash: observed.contentHash,
+    diagnostics: sortedDiagnostics,
+    summary: {
+      entityCount: observed.entities.length,
+      relationCount: observedRelations.length,
+      diagnosticCount: sortedDiagnostics.length,
+    },
+  }
+  return ReconciliationReportV1Schema.parse({ ...base, contentHash: contentHashForArtifactV1(base) })
+}

package/src/report/html.ts

@@ -0,0 +1,74 @@
+import { DiscoverySnapshotV1Schema, ReconciliationReportV1Schema, type DiscoverySnapshotV1, type ReconciliationReportV1 } from '../schemas/knowledge.js'
+import { redactSecrets } from '../safety/repository.js'
+
+export type OfflineReportInput = {
+  readonly snapshot: DiscoverySnapshotV1
+  readonly report: ReconciliationReportV1
+}
+
+export type OfflineReportOptions = {
+  readonly includeSnippets?: boolean
+}
+
+const escapeHtml = (value: unknown): string => String(value)
+  .replaceAll('&', '&')
+  .replaceAll('<', '&lt;')
+  .replaceAll('>', '&gt;')
+  .replaceAll('"', '&quot;')
+  .replaceAll("'", '&#39;')
+
+const anchor = (prefix: string, value: string): string => `${prefix}-${value.replace(/[^A-Za-z0-9_-]+/g, '-')}`
+
+const evidenceText = (evidence: ReconciliationReportV1['diagnostics'][number]['evidence'][number], includeSnippets: boolean): string => {
+  const location = `${evidence.path}${evidence.lineStart ? `:${evidence.lineStart}${evidence.lineEnd && evidence.lineEnd !== evidence.lineStart ? `-${evidence.lineEnd}` : ''}` : ''}`
+  return `${location}${includeSnippets && evidence.context ? ` — ${redactSecrets(evidence.context)}` : ''}`
+}
+
+const errorPage = (message: string): string => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Doc Bridge report error</title><style>body{font:16px system-ui;margin:3rem;color:#311}main{max-width:60rem;margin:auto;border:1px solid #d99;padding:2rem;border-radius:8px;background:#fff8f8}code{white-space:pre-wrap}</style></head><body><main><h1>Doc Bridge report unavailable</h1><p>The saved snapshot/report could not be rendered.</p><code>${escapeHtml(message)}</code><p>Run <code>ak-docs check</code> to regenerate valid artifacts.</p></main></body></html>`
+
+const embeddedJson = (value: unknown): string => JSON.stringify(value).replaceAll('<', '\\u003c')
+
+const controls = (statusOptions: string[]): string => `<section id="controls"><label>Search <input id="search" type="search" placeholder="entity, relation, diagnostic"></label><label>Severity <select id="severity"><option value="">Any</option><option>error</option><option>warn</option><option>info</option></select></label><label>Provenance <select id="provenance"><option value="">Any</option><option>observed</option><option>declared</option><option>proposed</option></select></label><label>Status <select id="status"><option value="">Any</option>${statusOptions.map((value) => `<option>${value}</option>`).join('')}</select></label><label>Analyzer <input id="analyzer" type="search" placeholder="js-ts, report"></label><label>Entity <input id="entity" type="search" placeholder="entity id"></label><label>Relation <input id="relation" type="search" placeholder="relation id"></label><button id="reset">Reset filters</button></section>`
+
+const renderCompact = (snapshot: DiscoverySnapshotV1, report: ReconciliationReportV1, entityAnchors: ReadonlyMap<string, string>, includeSnippets: boolean): string => {
+  const entities = snapshot.entities.map((entity) => ({ id: entity.id, name: entity.name, kind: entity.kind, anchor: entityAnchors.get(entity.id) ?? anchor('entity', entity.id) }))
+  const entityIndexes = new Map(entities.map((entity, index) => [entity.id, index]))
+  const relations = snapshot.relations.map((relation) => ({ id: relation.id, from: entityIndexes.get(relation.from), to: entityIndexes.get(relation.to), kind: relation.kind, provenance: relation.provenance }))
+  const diagnostics = report.diagnostics.map((diagnostic) => ({
+    ...diagnostic,
+    evidence: diagnostic.evidence.map(({ context, ...evidence }) => includeSnippets && context ? { ...evidence, context: redactSecrets(context) } : evidence),
+  }))
+  const data = embeddedJson({ entities, relations, diagnostics, coverage: snapshot.coverage })
+  const script = `const data=${data};const esc=(v)=>String(v).replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;').replaceAll('"','&quot;').replaceAll("'",'&#39;');const entityById=new Map(data.entities.map((e)=>[e.id,e]));const entityLink=(id)=>{const e=entityById.get(id);return '<a href="#'+esc(e?.anchor??'entity-'+id)+'">'+esc(e?.name??id)+'</a>'};const evidenceText=(e)=>esc(e.path+(e.lineStart?':'+e.lineStart+(e.lineEnd&&e.lineEnd!==e.lineStart?'-'+e.lineEnd:''):'')+(e.context?' — '+e.context:''));const render=()=>{document.querySelector('#map').innerHTML=data.entities.map((e)=>'<div class="node" id="'+esc(e.anchor)+'" data-node="'+esc(e.anchor)+'" data-search="'+esc([e.id,e.name,e.kind].join(' '))+'"><a href="#'+esc(e.anchor)+'">'+esc(e.name)+'</a><br><span class="muted">'+esc(e.kind)+'</span></div>').join('');document.querySelector('#relations').innerHTML=data.relations.map((r)=>{const from=data.entities[r.from],to=data.entities[r.to];return '<tr id="relation-'+esc(r.id)+'" data-relation="'+esc(r.id)+'" data-from="'+esc(from?.anchor??'')+'" data-to="'+esc(to?.anchor??'')+'" data-kind="'+esc(r.kind)+'" data-provenance="'+esc(r.provenance)+'" data-analyzer="snapshot" data-search="'+esc([r.id,from?.id,to?.id,r.kind,r.provenance].join(' '))+'"><td>'+esc(r.kind)+'</td><td>'+entityLink(from?.id??'')+'</td><td>'+entityLink(to?.id??'')+'</td><td>'+esc(r.provenance)+'</td></tr>'}).join('');document.querySelector('#diagnostics').innerHTML=data.diagnostics.length?data.diagnostics.map((d)=>'<article id="diagnostic-'+esc(d.id)+'" class="diagnostic" data-status="'+esc(d.status)+'" data-severity="'+esc(d.severity)+'" data-analyzer="report" data-entity="'+esc((d.entityIds??[]).join(' '))+'" data-relation="'+esc((d.relationIds??[]).join(' '))+'" data-search="'+esc([d.id,d.code,d.message,...(d.entityIds??[]),...(d.relationIds??[])].join(' '))+'"><h3><a href="#diagnostic-'+esc(d.id)+'">'+esc(d.code)+'</a> <span class="badge '+esc(d.severity)+'">'+esc(d.severity)+'</span></h3><p>'+esc(d.message)+'</p><p>Status: <b>'+esc(d.status)+'</b></p><ul>'+d.evidence.map((e)=>'<li>'+evidenceText(e)+'</li>').join('')+'</ul>'+(d.entityIds?.length?'<p>Entities: '+d.entityIds.map(entityLink).join(', ')+'</p>':'')+'</article>').join(''):'<p class="muted">No diagnostics.</p>';document.querySelector('#coverage').innerHTML=data.coverage.length?data.coverage.map((c)=>'<li data-status="'+esc(c.status)+'" data-analyzer="'+esc(c.analyzer)+'" data-search="'+esc([c.analyzer,c.scope,c.status,c.reason??''].join(' '))+'"><b>'+esc(c.analyzer)+'</b> / '+esc(c.scope)+': '+esc(c.status)+(c.reason?' — '+esc(c.reason):'')+'</li>').join(''):'<li class="muted">No coverage metadata.</li>';document.querySelectorAll('[data-node]').forEach((node)=>node.onclick=()=>{const id=node.dataset.node;document.querySelectorAll('[data-from],[data-to]').forEach((edge)=>edge.classList.toggle('hidden',edge.dataset.from!==id&&edge.dataset.to!==id))});};const apply=()=>{const q=document.querySelector('#search').value.toLowerCase(),severity=document.querySelector('#severity').value,provenance=document.querySelector('#provenance').value,status=document.querySelector('#status').value,analyzer=document.querySelector('#analyzer').value.toLowerCase(),entity=document.querySelector('#entity').value.toLowerCase(),relation=document.querySelector('#relation').value.toLowerCase();document.querySelectorAll('[data-search]').forEach((el)=>el.classList.toggle('hidden',Boolean(q&&!el.dataset.search.toLowerCase().includes(q)||severity&&el.dataset.severity!==severity||provenance&&el.dataset.provenance!==provenance||status&&el.dataset.status!==status||analyzer&&!el.dataset.analyzer?.toLowerCase().includes(analyzer)||entity&&!el.dataset.entity?.toLowerCase().includes(entity)||relation&&!el.dataset.relation?.toLowerCase().includes(relation))));};render();for(const id of ['search','analyzer','entity','relation'])document.querySelector('#'+id).oninput=apply;for(const id of ['severity','provenance','status'])document.querySelector('#'+id).onchange=apply;document.querySelector('#reset').onclick=()=>{for(const id of ['search','analyzer','entity','relation'])document.querySelector('#'+id).value='';for(const id of ['severity','provenance','status'])document.querySelector('#'+id).value='';apply()};`
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Doc Bridge — ${escapeHtml(snapshot.project.name)}</title><style>body{font:14px system-ui;margin:0;color:#18202a;background:#f5f7fa}header,main{max-width:1200px;margin:auto;padding:1.25rem}header{background:#18202a;color:white;max-width:none;padding-left:calc((100% - 1200px)/2);padding-right:calc((100% - 1200px)/2)}main{background:white}section{margin:1.5rem 0;border-top:1px solid #d7dde5;padding-top:1rem}table{border-collapse:collapse;width:100%;margin-top:.75rem}td,th{border-bottom:1px solid #e5e9ef;text-align:left;padding:.45rem;vertical-align:top}input,select,button{padding:.45rem;margin:.15rem;border:1px solid #b9c3d0;border-radius:4px;background:white}.badge{border-radius:1rem;padding:.15rem .5rem;background:#dce4ee}.error{background:#ffd9d9}.warn{background:#fff0c2}.info{background:#dcecff}.diagnostic{border:1px solid #d7dde5;border-left:4px solid #9aa7b5;padding:.75rem;margin:.75rem 0}.diagnostic:target,tr:target{background:#fff8cf}.muted{color:#5d6a78}a{color:#0b5cad}#map{display:flex;gap:1rem;flex-wrap:wrap}.node{border:1px solid #9aa7b5;padding:.5rem;border-radius:4px}.hidden{display:none}</style></head><body><header><h1>Doc Bridge: ${escapeHtml(snapshot.project.name)}</h1><p>Offline architecture and documentation reconciliation report</p><p class="muted">Snapshot ${escapeHtml(snapshot.contentHash)} · Report ${escapeHtml(report.contentHash)} · Revision ${escapeHtml(snapshot.sourceRevision)}</p></header><main>${controls(['confirmed', 'undocumented', 'stale-or-unverified', 'conflict', 'unresolved', 'not-analyzed'])}<section id="architecture"><h2>Architecture map</h2><p>Large snapshots are rendered from compact canonical data after load to keep the offline report bounded.</p><div id="map"></div><h3>Relations</h3><table><thead><tr><th>Kind</th><th>From</th><th>To</th><th>Provenance</th></tr></thead><tbody id="relations"></tbody></table></section><section id="diagnostic-lens"><h2>Diagnostic lens</h2><p>Findings: ${report.diagnostics.length}</p><div id="diagnostics"></div></section><section id="coverage"><h2>Coverage and unsupported areas</h2><ul></ul></section><section id="metadata"><h2>Run metadata</h2><dl><dt>Source revision</dt><dd>${escapeHtml(snapshot.sourceRevision)} (${escapeHtml(snapshot.sourceRevisionKind)})</dd><dt>Configuration hash</dt><dd>${escapeHtml(snapshot.configurationHash)}</dd><dt>Pipeline</dt><dd>${escapeHtml(snapshot.pipelineVersion)}</dd></dl></section></main><script>${script}</script></body></html>`
+}
+
+const render = (input: OfflineReportInput, options: OfflineReportOptions): string => {
+  const { snapshot, report } = input
+  const includeSnippets = options.includeSnippets === true
+  const entityAnchors = new Map(snapshot.entities.map((entity, index) => [entity.id, entity.id.length > 64 ? `entity-n${index}` : anchor('entity', entity.id)]))
+  if (snapshot.entities.length > 500 || report.diagnostics.length > 1_000) return renderCompact(snapshot, report, entityAnchors, includeSnippets)
+  const entityNames = new Map(snapshot.entities.map((entity) => [entity.id, entity.name]))
+  const entityAnchor = (id: string): string => entityAnchors.get(id) ?? anchor('entity', id)
+  const entityLabel = (id: string): string => entityNames.get(id) ?? id
+  const entityLink = (id: string): string => `<a href="#${entityAnchor(id)}">${escapeHtml(entityLabel(id))}</a>`
+  const relations = snapshot.relations.map((relation) => `<tr id="${anchor('relation', relation.id)}" data-relation="${escapeHtml(relation.id)}" data-from="${entityAnchor(relation.from)}" data-to="${entityAnchor(relation.to)}" data-kind="${escapeHtml(relation.kind)}" data-provenance="${escapeHtml(relation.provenance)}" data-analyzer="snapshot" data-search="${escapeHtml(`${relation.id} ${relation.from} ${relation.to} ${relation.kind} ${relation.provenance}`)}"><td>${escapeHtml(relation.kind)}</td><td>${entityLink(relation.from)}</td><td>${entityLink(relation.to)}</td><td>${escapeHtml(relation.provenance)}</td></tr>`).join('')
+  const diagnostics = report.diagnostics.map((diagnostic) => `<article id="${anchor('diagnostic', diagnostic.id)}" class="diagnostic" data-status="${escapeHtml(diagnostic.status)}" data-severity="${escapeHtml(diagnostic.severity)}" data-analyzer="report" data-entity="${escapeHtml(diagnostic.entityIds?.join(' ') ?? '')}" data-relation="${escapeHtml(diagnostic.relationIds?.join(' ') ?? '')}" data-search="${escapeHtml(`${diagnostic.id} ${diagnostic.code} ${diagnostic.message} ${diagnostic.entityIds?.join(' ') ?? ''} ${diagnostic.relationIds?.join(' ') ?? ''}`)}"><h3><a href="#${anchor('diagnostic', diagnostic.id)}">${escapeHtml(diagnostic.code)}</a> <span class="badge ${escapeHtml(diagnostic.severity)}">${escapeHtml(diagnostic.severity)}</span></h3><p>${escapeHtml(diagnostic.message)}</p><p>Status: <b>${escapeHtml(diagnostic.status)}</b></p><ul>${diagnostic.evidence.map((item) => `<li>${escapeHtml(evidenceText(item, includeSnippets))}</li>`).join('')}</ul>${diagnostic.entityIds?.length ? `<p>Entities: ${diagnostic.entityIds.map((id) => entityLink(id)).join(', ')}</p>` : ''}</article>`).join('')
+  const coverage = snapshot.coverage.map((entry) => `<li data-status="${escapeHtml(entry.status)}" data-analyzer="${escapeHtml(entry.analyzer)}" data-search="${escapeHtml(`${entry.analyzer} ${entry.scope} ${entry.status} ${entry.reason ?? ''}`)}"><b>${escapeHtml(entry.analyzer)}</b> / ${escapeHtml(entry.scope)}: ${escapeHtml(entry.status)}${entry.reason ? ` — ${escapeHtml(entry.reason)}` : ''}</li>`).join('')
+  const nodes = snapshot.entities.map((entity) => `<div class="node" id="${entityAnchor(entity.id)}" data-node="${entityAnchor(entity.id)}"><a href="#${entityAnchor(entity.id)}">${escapeHtml(entity.name)}</a><br><span class="muted">${escapeHtml(entity.kind)}</span></div>`).join('')
+  const script = `const q=document.querySelector('#search'),severity=document.querySelector('#severity'),provenance=document.querySelector('#provenance'),status=document.querySelector('#status'),analyzer=document.querySelector('#analyzer'),entity=document.querySelector('#entity'),relation=document.querySelector('#relation');function apply(){const term=q.value.toLowerCase(),entityTerm=entity.value.toLowerCase(),relationTerm=relation.value.toLowerCase();document.querySelectorAll('[data-search]').forEach((el)=>{const match=(!term||el.dataset.search.toLowerCase().includes(term))&&(!severity.value||el.dataset.severity===severity.value)&&(!provenance.value||el.dataset.provenance===provenance.value)&&(!status.value||el.dataset.status===status.value)&&(!analyzer.value||el.dataset.analyzer?.toLowerCase().includes(analyzer.value.toLowerCase()))&&(!entityTerm||el.dataset.entity?.toLowerCase().includes(entityTerm))&&(!relationTerm||el.dataset.relation?.toLowerCase().includes(relationTerm));el.classList.toggle('hidden',!match)});}q.oninput=apply;severity.onchange=apply;provenance.onchange=apply;status.onchange=apply;analyzer.oninput=apply;entity.oninput=apply;relation.oninput=apply;document.querySelector('#reset').onclick=()=>{q.value='';severity.value='';provenance.value='';status.value='';analyzer.value='';entity.value='';relation.value='';apply()};document.querySelectorAll('[data-node]').forEach((node)=>node.onclick=()=>{const id=node.dataset.node;document.querySelectorAll('[data-from],[data-to]').forEach((edge)=>edge.classList.toggle('hidden',edge.dataset.from!==id&&edge.dataset.to!==id));});`
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Doc Bridge — ${escapeHtml(snapshot.project.name)}</title><style>body{font:14px system-ui;margin:0;color:#18202a;background:#f5f7fa}header,main{max-width:1200px;margin:auto;padding:1.25rem}header{background:#18202a;color:white;max-width:none;padding-left:calc((100% - 1200px)/2);padding-right:calc((100% - 1200px)/2)}main{background:white}section{margin:1.5rem 0;border-top:1px solid #d7dde5;padding-top:1rem}table{border-collapse:collapse;width:100%;margin-top:.75rem}td,th{border-bottom:1px solid #e5e9ef;text-align:left;padding:.45rem;vertical-align:top}input,select,button{padding:.45rem;margin:.15rem;border:1px solid #b9c3d0;border-radius:4px;background:white}.badge{border-radius:1rem;padding:.15rem .5rem;background:#dce4ee}.error{background:#ffd9d9}.warn{background:#fff0c2}.info{background:#dcecff}.diagnostic{border:1px solid #d7dde5;border-left:4px solid #9aa7b5;padding:.75rem;margin:.75rem 0}.diagnostic:target,tr:target{background:#fff8cf}.muted{color:#5d6a78}a{color:#0b5cad}#map{display:flex;gap:1rem;flex-wrap:wrap}.node{border:1px solid #9aa7b5;padding:.5rem;border-radius:4px}.hidden{display:none}</style></head><body><header><h1>Doc Bridge: ${escapeHtml(snapshot.project.name)}</h1><p>Offline architecture and documentation reconciliation report</p><p class="muted">Snapshot ${escapeHtml(snapshot.contentHash)} · Report ${escapeHtml(report.contentHash)} · Revision ${escapeHtml(snapshot.sourceRevision)}</p></header><main><section id="controls"><label>Search <input id="search" type="search" placeholder="entity, relation, diagnostic"></label><label>Severity <select id="severity"><option value="">Any</option><option>error</option><option>warn</option><option>info</option></select></label><label>Provenance <select id="provenance"><option value="">Any</option><option>observed</option><option>declared</option><option>proposed</option></select></label><label>Status <select id="status"><option value="">Any</option>${['confirmed', 'undocumented', 'stale-or-unverified', 'conflict', 'unresolved', 'not-analyzed'].map((value) => `<option>${value}</option>`).join('')}</select></label><label>Analyzer <input id="analyzer" type="search" placeholder="js-ts, report"></label><label>Entity <input id="entity" type="search" placeholder="entity id"></label><label>Relation <input id="relation" type="search" placeholder="relation id"></label><button id="reset">Reset filters</button></section><section id="architecture"><h2>Architecture map</h2><p>Observed and declared relations are rendered from the canonical snapshot; browser code does not infer edges.</p><div id="map">${nodes}</div><h3>Relations</h3><table><thead><tr><th>Kind</th><th>From</th><th>To</th><th>Provenance</th></tr></thead><tbody id="relations">${relations}</tbody></table></section><section id="diagnostic-lens"><h2>Diagnostic lens</h2><p>Findings: ${report.diagnostics.length}</p><div id="diagnostics">${diagnostics || '<p class="muted">No diagnostics.</p>'}</div></section><section id="coverage"><h2>Coverage and unsupported areas</h2><ul>${coverage || '<li>No coverage metadata.</li>'}</ul></section><section id="metadata"><h2>Run metadata</h2><dl><dt>Source revision</dt><dd>${escapeHtml(snapshot.sourceRevision)} (${escapeHtml(snapshot.sourceRevisionKind)})</dd><dt>Configuration hash</dt><dd>${escapeHtml(snapshot.configurationHash)}</dd><dt>Pipeline</dt><dd>${escapeHtml(snapshot.pipelineVersion)}</dd></dl></section></main><script>${script}</script></body></html>`
+}
+
+export const renderOfflineReport = (input: unknown, options: OfflineReportOptions = {}): string => {
+  try {
+    if (!input || typeof input !== 'object') throw new Error('Input must contain snapshot and report artifacts.')
+    const value = input as Partial<OfflineReportInput>
+    const snapshot = DiscoverySnapshotV1Schema.parse(value.snapshot)
+    const report = ReconciliationReportV1Schema.parse(value.report)
+    if (report.snapshotHash !== snapshot.contentHash) throw new Error('Report snapshotHash does not match snapshot contentHash.')
+    return render({ snapshot, report }, options)
+  } catch (error) {
+    return errorPage(error instanceof Error ? error.message : String(error))
+  }
+}

package/src/rules/engine.ts

@@ -0,0 +1,180 @@
+import { minimatch } from 'minimatch'
+
+import {
+  RuleIdSchema,
+  RuleSeveritySchema,
+  RulesConfigSchema,
+  type RuleId,
+  type RuleSeverity,
+  type RulesConfig,
+} from '../config/schema.js'
+import type { ReconciliationReportV1 } from '../schemas/knowledge.js'
+
+export type RuleMode = 'default' | 'recommended' | 'strict'
+
+export type RuleEngineOptions = {
+  readonly config?: RulesConfig
+  readonly preset?: RuleMode
+  readonly severity?: Partial<Record<RuleId, RuleSeverity>>
+  readonly ignore?: readonly RuleId[]
+  readonly criticalEntities?: readonly string[]
+  readonly criticalPaths?: readonly string[]
+  readonly warningThresholds?: Partial<Record<RuleId, number>>
+}
+
+export type RuleFinding = {
+  readonly id: string
+  readonly ruleId: RuleId
+  readonly code: string
+  readonly status: ReconciliationReportV1['diagnostics'][number]['status']
+  readonly severity: RuleSeverity
+  readonly message: string
+  readonly evidence: ReconciliationReportV1['diagnostics'][number]['evidence']
+  readonly entityIds?: readonly string[]
+  readonly relationIds?: readonly string[]
+  readonly remediation?: string
+  readonly sourceDiagnosticCode?: string
+}
+
+export type RuleEvaluationResult = {
+  readonly mode: RuleMode
+  readonly findings: readonly RuleFinding[]
+  readonly exitCode: 0 | 1
+}
+
+const diagnosticRules: Readonly<Record<string, RuleId>> = {
+  DOCUMENTATION_QUALITY: 'documentation-quality',
+  RELATION_UNDOCUMENTED: 'graph-undocumented-relation',
+  DECLARED_RELATION_STALE: 'declared-unobserved-relation',
+  UNRESOLVED_ENTITY_REFERENCE: 'unresolved-reference',
+  CONFLICTING_DECLARATIONS: 'conflicting-declaration',
+  RELATION_NOT_ANALYZED: 'not-analyzed-coverage',
+  STALE_DOCUMENTATION: 'stale-documentation',
+  FRESHNESS_FAILURE: 'freshness',
+  OWNERSHIP_GAP: 'ownership',
+  CENTRALITY_RISK: 'centrality-risk',
+  CRITICAL_PATH_RISK: 'critical-path-risk',
+}
+
+const defaultSeverity = (mode: RuleMode, ruleId: RuleId): RuleSeverity => {
+  if (mode === 'default') return 'info'
+  if (mode === 'strict') return ruleId === 'not-analyzed-coverage' ? 'warn' : 'error'
+  return ruleId === 'not-analyzed-coverage' ? 'info' : 'warn'
+}
+
+const resolvedOptions = (options: RuleEngineOptions): {
+  readonly mode: RuleMode
+  readonly severity: Partial<Record<RuleId, RuleSeverity>>
+  readonly ignore: ReadonlySet<RuleId>
+  readonly criticalEntities: readonly string[]
+  readonly criticalPaths: readonly string[]
+  readonly warningThresholds: Partial<Record<RuleId, number>>
+} => {
+  const config = RulesConfigSchema.parse(options.config ?? {})
+  const mode = options.preset ?? config.mode ?? 'default'
+  const severity = { ...config.severity, ...options.severity }
+  const ignore = new Set<RuleId>([...(config.ignore ?? []), ...(options.ignore ?? [])])
+  return {
+    mode,
+    severity,
+    ignore,
+    criticalEntities: options.criticalEntities ?? config.criticalEntities ?? [],
+    criticalPaths: options.criticalPaths ?? config.criticalPaths ?? [],
+    warningThresholds: { ...config.warningThresholds, ...options.warningThresholds },
+  }
+}
+
+const severityFor = (
+  ruleId: RuleId,
+  mode: RuleMode,
+  overrides: Partial<Record<RuleId, RuleSeverity>>,
+): RuleSeverity => overrides[ruleId] ?? defaultSeverity(mode, ruleId)
+
+const findingFromDiagnostic = (
+  diagnostic: ReconciliationReportV1['diagnostics'][number],
+  ruleId: RuleId,
+  severity: RuleSeverity,
+): RuleFinding => ({
+  id: `${diagnostic.id}:${ruleId}`,
+  ruleId,
+  code: ruleId,
+  status: diagnostic.status,
+  severity,
+  message: diagnostic.message,
+  evidence: diagnostic.evidence,
+  ...(diagnostic.entityIds ? { entityIds: diagnostic.entityIds } : {}),
+  ...(diagnostic.relationIds ? { relationIds: diagnostic.relationIds } : {}),
+  ...(diagnostic.remediation ? { remediation: diagnostic.remediation } : {}),
+  sourceDiagnosticCode: diagnostic.code,
+})
+
+const criticalFinding = (
+  finding: RuleFinding,
+  severity: RuleSeverity,
+  target: string,
+): RuleFinding => ({
+  ...finding,
+  id: `${finding.id}:critical:${target}`,
+  ruleId: 'critical-path-risk',
+  code: 'critical-path-risk',
+  severity,
+  message: `Critical path or entity is affected: ${target}. ${finding.message}`,
+})
+
+export const evaluateRules = (
+  report: ReconciliationReportV1,
+  options: RuleEngineOptions = {},
+): RuleEvaluationResult => {
+  const resolved = resolvedOptions(options)
+  const findings: RuleFinding[] = []
+
+  for (const diagnostic of [...report.diagnostics].sort((a, b) => a.id.localeCompare(b.id))) {
+    const ruleId = diagnosticRules[diagnostic.code]
+    if (!ruleId || resolved.ignore.has(ruleId)) continue
+    const severity = severityFor(ruleId, resolved.mode, resolved.severity)
+    if (severity !== 'off') findings.push(findingFromDiagnostic(diagnostic, ruleId, severity))
+  }
+
+  const criticalSeverity = severityFor('critical-path-risk', resolved.mode, resolved.severity)
+  const criticalEntitySet = new Set(resolved.criticalEntities)
+  for (const finding of [...findings]) {
+    const matchingEntity = (finding.entityIds ?? []).find((id) => criticalEntitySet.has(id))
+    if (matchingEntity && !resolved.ignore.has('critical-path-risk') && criticalSeverity !== 'off') {
+      findings.push(criticalFinding(finding, criticalSeverity, matchingEntity))
+    }
+    for (const path of resolved.criticalPaths) {
+      if (finding.evidence.some((item) => minimatch(item.path, path, { dot: true })) && !resolved.ignore.has('critical-path-risk') && criticalSeverity !== 'off') {
+        findings.push(criticalFinding(finding, criticalSeverity, path))
+      }
+    }
+  }
+
+  const centralityThreshold = resolved.warningThresholds['centrality-risk'] ?? 3
+  const centralitySeverity = severityFor('centrality-risk', resolved.mode, resolved.severity)
+  if (!resolved.ignore.has('centrality-risk') && centralitySeverity !== 'off') {
+    const counts = new Map<string, number>()
+    for (const finding of findings.filter((item) => item.ruleId === 'graph-undocumented-relation')) {
+      for (const entityId of finding.entityIds ?? []) counts.set(entityId, (counts.get(entityId) ?? 0) + 1)
+    }
+    for (const [entityId, count] of [...counts.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      if (count < centralityThreshold || !criticalEntitySet.has(entityId)) continue
+      findings.push({
+        id: `centrality-risk:${entityId}`,
+        ruleId: 'centrality-risk',
+        code: 'centrality-risk',
+        status: 'unresolved',
+        severity: centralitySeverity,
+        message: `Critical entity has ${count} undocumented relation finding(s); static centrality is a review signal, not a runtime availability claim.`,
+        evidence: findings.filter((item) => item.ruleId === 'graph-undocumented-relation' && item.entityIds?.includes(entityId)).flatMap((item) => item.evidence),
+        entityIds: [entityId],
+        remediation: 'Review ownership, dependency boundaries, and runtime availability before declaring an SPOF.',
+      })
+    }
+  }
+
+  const sortedFindings = [...findings].sort((a, b) => a.id.localeCompare(b.id))
+  return { mode: resolved.mode, findings: sortedFindings, exitCode: sortedFindings.some((finding) => finding.severity === 'error') ? 1 : 0 }
+}
+
+export const parseRuleId = (value: string): RuleId => RuleIdSchema.parse(value)
+export const parseRuleSeverity = (value: string): RuleSeverity => RuleSeveritySchema.parse(value)

package/src/safety/repository.ts

@@ -0,0 +1,84 @@
+import { lstatSync, readdirSync, realpathSync, statSync } from 'node:fs'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+
+import { minimatch } from 'minimatch'
+
+export const DEFAULT_SAFETY_EXCLUDES = ['**/.git/**', '**/node_modules/**', '**/dist/**', '**/build/**', '**/coverage/**', '**/.doc-bridge/**', '**/.env', '**/.env.*', '**/*secret*', '**/*credential*', '**/*.pem', '**/*.key'] as const
+
+export type SafeWalkOptions = {
+  readonly extensions?: readonly string[]
+  readonly exclude?: readonly string[]
+  readonly maxFiles?: number
+  readonly maxBytes?: number
+  readonly maxTimeMs?: number
+  readonly maxMemoryMb?: number
+}
+
+export type SafeWalkResult = {
+  readonly files: readonly string[]
+  readonly incomplete: boolean
+  readonly reason?: string
+}
+
+export const containedPath = (root: string, candidate: string): string | undefined => {
+  const projectRoot = realpathSync.native(resolve(root))
+  const unresolved = resolve(projectRoot, candidate)
+  const unresolvedRelative = relative(projectRoot, unresolved)
+  if (isAbsolute(unresolvedRelative) || unresolvedRelative === '..' || unresolvedRelative.startsWith(`..${sep}`)) return undefined
+  try {
+    const canonical = realpathSync.native(unresolved)
+    const canonicalRelative = relative(projectRoot, canonical)
+    return isAbsolute(canonicalRelative) || canonicalRelative === '..' || canonicalRelative.startsWith(`..${sep}`) ? undefined : canonical
+  } catch {
+    return unresolved
+  }
+}
+
+export const safeWalkFiles = (root: string, options: SafeWalkOptions = {}): SafeWalkResult => {
+  const projectRoot = resolve(root)
+  const extensions = options.extensions ?? []
+  const excludes = options.exclude ?? DEFAULT_SAFETY_EXCLUDES
+  const files: string[] = []
+  let bytes = 0
+  let reason: string | undefined
+  const started = Date.now()
+  const matchesExclude = (path: string): boolean => excludes.some((pattern) => minimatch(path, pattern, { dot: true }))
+  const visit = (directory: string): void => {
+    if (reason) return
+    if (options.maxTimeMs !== undefined && Date.now() - started >= options.maxTimeMs) { reason = `Repository scan exceeded the ${options.maxTimeMs} ms time limit.`; return }
+    if (options.maxMemoryMb !== undefined && process.memoryUsage().heapUsed > options.maxMemoryMb * 1024 * 1024) { reason = `Repository scan exceeded the ${options.maxMemoryMb} MiB memory limit.`; return }
+    let entries: string[]
+    try { entries = readdirSync(directory) } catch { return }
+    for (const name of entries.sort()) {
+      const absolute = resolve(directory, name)
+      const relativePath = relative(projectRoot, absolute).split(sep).join('/')
+      if (matchesExclude(relativePath) || name === '.git') continue
+      let stats
+      try { stats = lstatSync(absolute) } catch { continue }
+      if (stats.isSymbolicLink()) continue
+      if (stats.isDirectory()) { visit(absolute); if (reason) return; continue }
+      if (!stats.isFile() || (extensions.length > 0 && !extensions.some((extension) => name.endsWith(extension)))) continue
+      if (files.length >= (options.maxFiles ?? 10_000)) { reason = `Repository scan exceeded the ${options.maxFiles ?? 10_000} file limit.`; return }
+      bytes += statSync(absolute).size
+      if (options.maxBytes !== undefined && bytes > options.maxBytes) { reason = `Repository scan exceeded the ${options.maxBytes} byte limit.`; return }
+      files.push(absolute)
+    }
+  }
+  visit(projectRoot)
+  return { files: files.sort(), incomplete: reason !== undefined, ...(reason ? { reason } : {}) }
+}
+
+const SECRET_PATTERNS = [
+  /\b(?:sk|pk)[_-](?:live|test)[_-][A-Za-z0-9_-]{12,}\b/g,
+  /\b(?:ghp|github_pat|xox[baprs])_[A-Za-z0-9_-]{12,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /(?:password|passwd|secret|token|api[_-]?key)\s*[:=]\s*["']?[^\s,"']+/gi,
+]
+
+export const redactSecrets = (value: string): string => SECRET_PATTERNS.reduce((result, pattern) => result.replace(pattern, '[REDACTED]'), value)
+
+export const redactValue = (value: unknown): unknown => Array.isArray(value)
+  ? value.map(redactValue)
+  : value && typeof value === 'object'
+    ? Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, item]) => [key, redactValue(item)]))
+    : typeof value === 'string' ? redactSecrets(value) : value