@agentskit/doc-bridge 1.4.1 → 1.5.0

package/src/mcp/server.ts

@@ -1,5 +1,5 @@
-import { readFileSync, realpathSync } from 'node:fs'
-import { relative, resolve } from 'node:path'
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
 
 import { z, ZodError } from 'zod'
 
@@ -13,6 +13,14 @@ import { runQuery } from '../query/query.js'
 import { searchIndex } from '../query/search.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
 import { PACKAGE_VERSION } from '../version.js'
+import { loadWorkflowManifest, loadWorkflowStepOutput } from '../workflow/engine.js'
+import { parseDiscoverySnapshot, parseReconciliationReport } from '../validate.js'
+import { applyFixProposal, approveFixProposal, createArtifactNormalizationProposal, createMarkdownLinkFixProposal } from '../fixes/proposals.js'
+import { createRegistryAgentAdapter, loadRegistryAgentRunner, persistRegistryAgentProposal } from '../agents/registry-adapter.js'
+import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import { discoverRepository } from '../discovery/repository.js'
+import { FixProposalV1Schema, type DiscoverySnapshotV1, type ReconciliationReportV1, type FixProposalV1 } from '../schemas/knowledge.js'
+import { redactValue } from '../safety/repository.js'
 
 type JsonRpcRequest = {
   readonly jsonrpc?: '2.0'
@@ -99,6 +107,47 @@ export const MCP_TOOLS = [
     annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
+  {
+    name: 'docbridge.snapshot',
+    title: 'Read the latest discovery snapshot',
+    description: 'Read the bounded canonical repository snapshot from the latest workflow run.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' } } },
+  },
+  {
+    name: 'docbridge.report',
+    title: 'Read the latest reconciliation report',
+    description: 'Read the canonical reconciliation report from the latest workflow run.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' } } },
+  },
+  {
+    name: 'docbridge.diagnostics',
+    title: 'Read reconciliation diagnostics',
+    description: 'Read bounded diagnostics from the latest canonical reconciliation report.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: { status: { type: 'string' }, severity: { type: 'string' } } },
+  },
+  {
+    name: 'docbridge.relations',
+    title: 'Read architecture relations',
+    description: 'Read bounded observed and declared relations from the latest canonical snapshot.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: { kind: { type: 'string' }, limit: { type: 'number' } } },
+  },
+  {
+    name: 'docbridge.run',
+    title: 'Read workflow state',
+    description: 'Read the latest resumable workflow state and artifact references.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'docbridge.proposals',
+    title: 'Read or approve proposals',
+    description: 'Create, inspect, approve and apply deterministic proposals through the shared human-gated workflow.',
+    inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['list', 'propose-links', 'propose-normalize', 'suggest', 'approve', 'apply'] }, proposalHash: { type: 'string' }, artifactPath: { type: 'string' }, approvedBy: { type: 'string' }, proposal: { type: 'object' } } },
+  },
 ] as const
 
 const asRecord = (value: unknown): Record<string, unknown> =>
@@ -126,6 +175,11 @@ const DocGetArgsSchema = z
   })
   .refine((args) => args.id || args.path, 'doc.get requires id or path')
 
+const WorkflowRunArgsSchema = z.object({ runId: z.string().min(1).optional() })
+const DiagnosticsArgsSchema = z.object({ status: z.string().min(1).optional(), severity: z.string().min(1).optional() })
+const RelationsArgsSchema = z.object({ kind: z.string().min(1).optional(), limit: z.number().int().positive().max(500).optional() })
+const ProposalsArgsSchema = z.object({ action: z.enum(['list', 'propose-links', 'propose-normalize', 'suggest', 'approve', 'apply']).optional(), proposalHash: z.string().min(1).optional(), artifactPath: z.string().min(1).optional(), approvedBy: z.string().min(1).optional(), proposal: z.unknown().optional() })
+
 const parseToolArgs = <T>(tool: string, schema: z.ZodType<T>, value: unknown): T => {
   try {
     return schema.parse(value)
@@ -169,6 +223,45 @@ const resolveDocPath = (root: string, relPath: string): string => {
   return abs
 }
 
+const workflowStateDir = (ctx: McpContext): string => resolve(ctx.root, ctx.config.workflow?.stateDir ?? '.doc-bridge/workflow')
+
+const workflowRun = (ctx: McpContext) => loadWorkflowManifest(workflowStateDir(ctx))
+
+const ensureLatestRun = (ctx: McpContext, runId?: string) => {
+  const run = workflowRun(ctx)
+  if (runId && run.runId !== runId) throw new Error(`Unknown workflow run "${runId}"`)
+  if (run.state === 'stale' || run.state === 'failed') throw new Error(`Workflow run is ${run.state}; resume or create a valid run before reading artifacts.`)
+  return run
+}
+
+const workflowSnapshot = (ctx: McpContext, runId?: string): DiscoverySnapshotV1 => {
+  ensureLatestRun(ctx, runId)
+  return parseDiscoverySnapshot(loadWorkflowStepOutput(workflowStateDir(ctx), 'normalize'))
+}
+
+const workflowReport = (ctx: McpContext, runId?: string): ReconciliationReportV1 => {
+  ensureLatestRun(ctx, runId)
+  return parseReconciliationReport(loadWorkflowStepOutput(workflowStateDir(ctx), 'reconcile'))
+}
+
+const proposalPath = (ctx: McpContext): string => join(ctx.root, '.doc-bridge', 'proposal.json')
+const readSavedProposal = (ctx: McpContext, input: unknown): FixProposalV1 => {
+  if (input !== undefined) return FixProposalV1Schema.parse(input)
+  try { return FixProposalV1Schema.parse(JSON.parse(readFileSync(proposalPath(ctx), 'utf8')) as unknown) } catch { throw new Error(`No saved fix proposal at ${proposalPath(ctx)}.`) }
+}
+const saveProposal = (ctx: McpContext, proposal: FixProposalV1): void => { mkdirSync(join(ctx.root, '.doc-bridge'), { recursive: true }); writeFileSync(proposalPath(ctx), `${JSON.stringify(proposal, null, 2)}\n`, 'utf8') }
+
+const enabledMcpTools = (ctx: McpContext) => {
+  const configured = ctx.config.surfaces?.mcp?.tools
+  if (!configured || configured.length === MCP_TOOLS.length && MCP_TOOLS.every((tool) => configured.includes(tool.name as typeof configured[number]))) return MCP_TOOLS
+  return MCP_TOOLS.filter((tool) => configured.includes(tool.name as typeof configured[number]))
+}
+
+const assertMcpToolEnabled = (ctx: McpContext, name: string): void => {
+  if (!MCP_TOOLS.some((tool) => tool.name === name)) throw new Error(`Unknown tool "${name}"`)
+  if (!enabledMcpTools(ctx).some((tool) => tool.name === name)) throw new Error(`MCP tool "${name}" is disabled by configuration.`)
+}
+
 export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unknown => {
   if (request.method === 'initialize') {
     return {
@@ -178,12 +271,14 @@ export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unkn
     }
   }
 
-  if (request.method === 'tools/list') return { tools: MCP_TOOLS }
+  if (request.method === 'tools/list') return { tools: enabledMcpTools(ctx) }
 
   if (request.method === 'tools/call') {
     const params = asRecord(request.params)
     const name = params.name
     const args = asRecord(params.arguments)
+    if (typeof name !== 'string') throw new Error('MCP tools/call requires a tool name.')
+    assertMcpToolEnabled(ctx, name)
     const index = () => ctx.loadIndex?.() ?? loadDocBridgeIndex(ctx.root, ctx.config)
 
     if (name === 'handoff.resolve') {
@@ -232,6 +327,77 @@ export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unkn
       })
     }
 
+    if (name === 'docbridge.snapshot') {
+      const parsed = parseToolArgs('docbridge.snapshot', WorkflowRunArgsSchema, args)
+      return textResult(redactValue(workflowSnapshot(ctx, parsed.runId)))
+    }
+
+    if (name === 'docbridge.report') {
+      const parsed = parseToolArgs('docbridge.report', WorkflowRunArgsSchema, args)
+      return textResult(redactValue(workflowReport(ctx, parsed.runId)))
+    }
+
+    if (name === 'docbridge.diagnostics') {
+      const parsed = parseToolArgs('docbridge.diagnostics', DiagnosticsArgsSchema, args)
+      const diagnostics = workflowReport(ctx).diagnostics.filter((diagnostic) =>
+        (!parsed.status || diagnostic.status === parsed.status) && (!parsed.severity || diagnostic.severity === parsed.severity),
+      )
+      return textResult(redactValue({ reportHash: workflowReport(ctx).contentHash, diagnostics }))
+    }
+
+    if (name === 'docbridge.relations') {
+      const parsed = parseToolArgs('docbridge.relations', RelationsArgsSchema, args)
+      const snapshot = workflowSnapshot(ctx)
+      return textResult({ snapshotHash: snapshot.contentHash, relations: snapshot.relations.filter((relation) => !parsed.kind || relation.kind === parsed.kind).slice(0, parsed.limit ?? 100) })
+    }
+
+    if (name === 'docbridge.run') {
+      parseToolArgs('docbridge.run', z.object({}), args)
+      return textResult(workflowRun(ctx))
+    }
+
+    if (name === 'docbridge.proposals') {
+      const parsed = parseToolArgs('docbridge.proposals', ProposalsArgsSchema, args)
+      const run = (() => { try { return workflowRun(ctx) } catch { return undefined } })()
+      if (!parsed.action || parsed.action === 'list') {
+        let proposal: FixProposalV1 | undefined
+        try { proposal = readSavedProposal(ctx, undefined) } catch { proposal = undefined }
+        return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposals: proposal ? [proposal] : [] }))
+      }
+      if (parsed.action === 'suggest') {
+        return loadRegistryAgentRunner(ctx.root, ctx.config).then(async (runner) => {
+          const snapshot = workflowSnapshot(ctx)
+          const report = workflowReport(ctx)
+          const adapter = createRegistryAgentAdapter(ctx.root, ctx.config, runner)
+          const proposal = await adapter.run(snapshot, report)
+          const savedPath = persistRegistryAgentProposal(workflowStateDir(ctx), proposal)
+          return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal, proposalPath: savedPath }))
+        })
+      }
+      const discovered = discoverRepository({ root: ctx.root, config: ctx.config })
+      const options = { baseRevision: discovered.sourceRevision, configurationHash: sha256NormalizedV1(ctx.config), ...(ctx.config.project?.name ? { projectName: ctx.config.project.name } : {}) }
+      if (parsed.action === 'propose-links') {
+        const proposal = createMarkdownLinkFixProposal(ctx.root, options)
+        if (proposal) saveProposal(ctx, proposal)
+        return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal: proposal ?? null }))
+      }
+      if (parsed.action === 'propose-normalize') {
+        if (!parsed.artifactPath) throw new Error('docbridge.proposals propose-normalize requires artifactPath')
+        const proposal = createArtifactNormalizationProposal(ctx.root, parsed.artifactPath, options)
+        if (proposal) saveProposal(ctx, proposal)
+        return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal: proposal ?? null }))
+      }
+      if (parsed.action === 'approve') {
+        const proposal = approveFixProposal(readSavedProposal(ctx, parsed.proposal), parsed.approvedBy ?? 'human')
+        if (parsed.proposalHash && proposal.approval?.proposalHash !== parsed.proposalHash) throw new Error('proposalHash does not match the saved proposal')
+        saveProposal(ctx, proposal)
+        return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal }))
+      }
+      const proposal = applyFixProposal(ctx.root, readSavedProposal(ctx, parsed.proposal), { currentRevision: discovered.sourceRevision })
+      saveProposal(ctx, proposal)
+      return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal }))
+    }
+
     throw new Error(`Unknown tool "${String(name)}"`)
   }
 
@@ -246,10 +412,10 @@ const writeFrame = (payload: unknown, framing: StdioFraming): void => {
   process.stdout.write(framing === 'json-line' ? `${body}\n` : `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
 }
 
-const respond = (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming): void => {
+export const respondMcpRequest = async (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming): Promise<void> => {
   if (request.id === undefined) {
     try {
-      handleMcpRequest(ctx, request)
+      await handleMcpRequest(ctx, request)
     } catch {
       // Notifications do not get responses.
     }
@@ -257,7 +423,7 @@ const respond = (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming
   }
 
   try {
-    const result = handleMcpRequest(ctx, request)
+    const result = await handleMcpRequest(ctx, request)
     writeFrame({ jsonrpc: '2.0', id: request.id, result: result ?? {} }, framing)
   } catch (error) {
     writeFrame({
@@ -270,6 +436,10 @@ const respond = (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming
 
 export const startMcpStdioServer = (ctx: McpContext): void => {
   let buffer = Buffer.alloc(0)
+  let responseChain = Promise.resolve()
+  const enqueueResponse = (request: JsonRpcRequest, framing: StdioFraming): void => {
+    responseChain = responseChain.then(() => respondMcpRequest(ctx, request, framing))
+  }
   process.stdin.on('data', (chunk: Buffer) => {
     buffer = Buffer.concat([buffer, chunk])
     while (true) {
@@ -288,7 +458,7 @@ export const startMcpStdioServer = (ctx: McpContext): void => {
         if (buffer.length < bodyEnd) return
         const raw = buffer.subarray(bodyStart, bodyEnd).toString('utf8')
         buffer = buffer.subarray(bodyEnd)
-        respond(ctx, JSON.parse(raw) as JsonRpcRequest, 'content-length')
+        enqueueResponse(JSON.parse(raw) as JsonRpcRequest, 'content-length')
         continue
       }
 
@@ -298,7 +468,7 @@ export const startMcpStdioServer = (ctx: McpContext): void => {
       buffer = buffer.subarray(lineEnd + 1)
       if (!raw) continue
       try {
-        respond(ctx, JSON.parse(raw) as JsonRpcRequest, 'json-line')
+        enqueueResponse(JSON.parse(raw) as JsonRpcRequest, 'json-line')
       } catch {
         writeFrame({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }, 'json-line')
       }

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))
+  }
+}