@agentskit/doc-bridge 1.6.4 → 1.7.45

package/src/reconciliation/reconcile.ts

@@ -11,19 +11,29 @@ import {
 type EntityResolver = (reference: string) => string
 
 export type ReconciliationOptions = {
+  /** Compare declarations at a semantic level while retaining raw discovery evidence. */
+  readonly scope?: 'file' | 'module' | 'package'
   /** Omit for backwards-compatible all-relation checking; [] disables missing-declaration findings. */
   readonly requiredRelationKinds?: readonly string[]
+  /** Limit missing-declaration findings to relations between internal project entities. */
+  readonly requiredRelationTargets?: 'all' | 'internal'
+  /** Emit one bounded finding for each observed Markdown document without declarations. */
+  readonly includeOrphanedDocuments?: boolean
 }
 
 const ignoredDocumentationRelations = new Set(['covers'])
 
+const isInternalEntity = (id: string): boolean => !id.startsWith('external:') && !id.startsWith('unresolved:')
+
 const metadataDetection = (relation: KnowledgeRelation): string | undefined => {
   const detection = relation.metadata?.detection
   return typeof detection === 'string' ? detection : undefined
 }
 
+const normalizeDetection = (value: string): string => value === 'dynamic-literal' ? 'dynamic' : value
+
 const relationDetection = (relation: KnowledgeRelation): string =>
-  relation.discriminator ?? metadataDetection(relation) ?? 'static'
+  normalizeDetection(relation.discriminator ?? metadataDetection(relation) ?? 'static')
 
 const entityResolver = (snapshots: readonly DiscoverySnapshotV1[]): EntityResolver => {
   const references = new Map<string, string>()
@@ -51,6 +61,32 @@ const mergeEvidence = (...relations: readonly KnowledgeRelation[]): Evidence[] =
   return [...merged.values()].sort((a, b) => evidenceKey(a).localeCompare(evidenceKey(b)))
 }
 
+const boundedEvidence = (evidence: readonly Evidence[]): Evidence[] => [...evidence].slice(0, 64)
+
+const diagnosticCounts = (values: readonly string[]): Record<string, number> => {
+  const counts = new Map<string, number>()
+  for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1)
+  return Object.fromEntries([...counts.entries()].sort(([a], [b]) => a.localeCompare(b)))
+}
+
+const documentClass = (entity: KnowledgeEntity): string => {
+  const classification = entity.metadata?.classification
+  return typeof classification === 'string' && classification.length > 0 ? classification : 'unclassified'
+}
+
+const countDocumentClasses = (
+  documents: readonly KnowledgeEntity[],
+  selectedIds?: ReadonlySet<string>,
+): Record<string, number> => {
+  const counts = new Map<string, number>()
+  for (const document of documents) {
+    if (selectedIds && !selectedIds.has(document.id)) continue
+    const classification = documentClass(document)
+    counts.set(classification, (counts.get(classification) ?? 0) + 1)
+  }
+  return Object.fromEntries([...counts.entries()].sort(([a], [b]) => a.localeCompare(b)))
+}
+
 const diagnosticId = (code: string, value: unknown): string =>
   `reconciliation:${code}:${sha256NormalizedV1(value).slice(0, 32)}`
 
@@ -72,6 +108,79 @@ const entityById = (snapshots: readonly DiscoverySnapshotV1[]): ReadonlyMap<stri
 const isUnresolved = (id: string, entities: ReadonlyMap<string, KnowledgeEntity>): boolean =>
   id.startsWith('unresolved:') || entities.get(id)?.kind === 'unresolved-reference'
 
+const normalizedPath = (path: string): string => path.replaceAll('\\', '/').replace(/^\.\//, '')
+
+const semanticEntityId = (
+  id: string,
+  scope: NonNullable<ReconciliationOptions['scope']>,
+  entities: ReadonlyMap<string, KnowledgeEntity>,
+  packageByModule: ReadonlyMap<string, string>,
+): string => {
+  if (scope === 'file' || id.startsWith('external:') || id.startsWith('unresolved:')) return id
+  const entity = entities.get(id)
+  if (!entity || entity.kind !== 'module' || !entity.path) return id
+  if (scope === 'module') return id
+  return packageByModule.get(id) ?? id
+}
+
+const packageLookup = (scope: NonNullable<ReconciliationOptions['scope']>, entities: ReadonlyMap<string, KnowledgeEntity>): Map<string, string> => {
+  if (scope !== 'package') return new Map()
+  const packages = [...entities.values()]
+    .filter((entity) => entity.kind === 'package' && entity.path)
+    .map((entity) => ({ id: entity.id, path: normalizedPath(entity.path as string) }))
+    .sort((a, b) => b.path.length - a.path.length || a.id.localeCompare(b.id))
+  const result = new Map<string, string>()
+  for (const entity of entities.values()) {
+    if (entity.kind !== 'module' || !entity.path) continue
+    const modulePath = normalizedPath(entity.path)
+    const packageEntity = packages.find(({ path }) => path === '.' || modulePath === path || modulePath.startsWith(`${path}/`))
+    if (packageEntity) result.set(entity.id, packageEntity.id)
+  }
+  return result
+}
+
+const aggregatedRelations = (
+  relations: readonly KnowledgeRelation[],
+  scope: NonNullable<ReconciliationOptions['scope']>,
+  entities: ReadonlyMap<string, KnowledgeEntity>,
+  packageByModule: ReadonlyMap<string, string>,
+): KnowledgeRelation[] => {
+  if (scope === 'file') return [...relations]
+  const groups = new Map<string, KnowledgeRelation[]>()
+  for (const relation of relations) {
+    const from = semanticEntityId(relation.from, scope, entities, packageByModule)
+    const to = semanticEntityId(relation.to, scope, entities, packageByModule)
+    const detection = relationDetection(relation)
+    const key = `${from}\u0000${to}\u0000${relation.kind}\u0000${detection}`
+    const group = groups.get(key) ?? []
+    group.push(relation)
+    groups.set(key, group)
+  }
+  return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, group]) => {
+    const first = group[0] as KnowledgeRelation
+    const parts = key.split('\u0000')
+    const from = parts[0] ?? first.from
+    const to = parts[1] ?? first.to
+    const detection = parts[3] ?? relationDetection(first)
+    const mergedEvidence = mergeEvidence(...group)
+    return {
+      ...first,
+      id: `relation:aggregated:${scope}:${sha256NormalizedV1(key).slice(0, 32)}`,
+      from,
+      to,
+      ...(detection === 'static' && !first.discriminator ? {} : { discriminator: detection }),
+      evidence: boundedEvidence(mergedEvidence),
+      metadata: {
+        ...(first.metadata ?? {}),
+        aggregationScope: scope,
+        aggregatedRelationCount: group.length,
+        aggregatedEvidenceCount: mergedEvidence.length,
+        ...(mergedEvidence.length > 64 ? { evidenceTruncated: true } : {}),
+      },
+    }
+  })
+}
+
 const relationMatches = (observed: KnowledgeRelation, declared: KnowledgeRelation, resolveEntity: EntityResolver): boolean => {
   if (relationBase(observed, resolveEntity) !== relationBase(declared, resolveEntity)) return false
   return relationDetection(declared) === relationDetection(observed)
@@ -93,7 +202,7 @@ const reportDiagnostic = (
   status,
   severity,
   message,
-  evidence: [...evidence],
+  evidence: boundedEvidence(evidence),
   ...(entityIds?.length ? { entityIds: [...entityIds] } : {}),
   ...(relationIds?.length ? { relationIds: [...relationIds] } : {}),
   ...(remediation ? { remediation } : {}),
@@ -106,11 +215,32 @@ export const reconcileKnowledge = (
 ): 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 scope = options.scope ?? 'file'
+  const packageByModule = packageLookup(scope, entities)
+  const allDeclaredRelations = declared.relations.filter((relation) => relation.provenance === 'declared')
+  const observedRelations = aggregatedRelations(observed.relations.filter((relation) => relation.provenance === 'observed' && !ignoredDocumentationRelations.has(relation.kind)), scope, entities, packageByModule)
+  const declaredRelations = aggregatedRelations(declared.relations.filter((relation) => relation.provenance === 'declared' && !ignoredDocumentationRelations.has(relation.kind)), scope, entities, packageByModule)
   const requiredRelationKinds = options.requiredRelationKinds === undefined ? undefined : new Set(options.requiredRelationKinds)
   const diagnostics: ReconciliationReportV1['diagnostics'][number][] = []
 
+  if (options.includeOrphanedDocuments) {
+    const declaredDocumentIds = new Set(allDeclaredRelations.map((relation) => relation.from).filter((id) => id.startsWith('document:')))
+    for (const document of observed.entities.filter((entity) => entity.kind === 'document').sort((a, b) => a.id.localeCompare(b.id))) {
+      if (declaredDocumentIds.has(document.id)) continue
+      diagnostics.push(reportDiagnostic(
+        'DOCUMENTATION_ORPHANED',
+        'undocumented',
+        'info',
+        'Markdown document has no Doc Bridge declaration linking it to observed knowledge.',
+        document.evidence,
+        document.id,
+        [document.id],
+        undefined,
+        'Add a docbridge declaration or exclude this document from the documentation comparison scope.',
+      ))
+    }
+  }
+
   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',
@@ -133,9 +263,19 @@ export const reconcileKnowledge = (
     declaredByBase.set(base, group)
   }
 
+  const observedDetectionsByBase = new Map<string, Set<string>>()
+  for (const relation of observedRelations) {
+    const base = relationBase(relation, resolveEntity)
+    const detections = observedDetectionsByBase.get(base) ?? new Set<string>()
+    detections.add(relationDetection(relation))
+    observedDetectionsByBase.set(base, detections)
+  }
+
   for (const group of declaredByBase.values()) {
     const detections = new Set(group.map(relationDetection))
     if (detections.size < 2) continue
+    const observedDetections = observedDetectionsByBase.get(relationBase(group[0] as KnowledgeRelation, resolveEntity))
+    if (observedDetections && [...detections].every((detection) => observedDetections.has(detection))) continue
     diagnostics.push(reportDiagnostic(
       'CONFLICTING_DECLARATIONS',
       'conflict',
@@ -163,7 +303,11 @@ export const reconcileKnowledge = (
         undefined,
         [relation.id, match.id],
       ))
-    } else if (coverageAvailable(observed, relation) && (requiredRelationKinds === undefined || requiredRelationKinds.has(relation.kind))) {
+    } else if (
+      coverageAvailable(observed, relation) &&
+      (requiredRelationKinds === undefined || requiredRelationKinds.has(relation.kind)) &&
+      (options.requiredRelationTargets !== 'internal' || (relation.from !== relation.to && isInternalEntity(relation.from) && isInternalEntity(relation.to)))
+    ) {
       diagnostics.push(reportDiagnostic(
         'RELATION_UNDOCUMENTED',
         'undocumented',
@@ -211,6 +355,33 @@ export const reconcileKnowledge = (
   }
 
   const sortedDiagnostics = [...diagnostics].sort((a, b) => a.id.localeCompare(b.id))
+  const packageEntities = observed.entities.filter((entity) => entity.kind === 'package')
+  const packageStatus = { fresh: 0, stale: 0, missing: 0, unverified: 0 }
+  const diagnosticStatusByEntity = new Map<string, Set<ReconciliationReportV1['diagnostics'][number]['status']>>()
+  const relationEndpoints = new Map([...observedRelations, ...declaredRelations].map((relation) => [relation.id, [relation.from, relation.to]]))
+  for (const diagnostic of sortedDiagnostics) for (const id of [...(diagnostic.entityIds ?? []), ...(diagnostic.relationIds ?? []).flatMap((relationId) => relationEndpoints.get(relationId) ?? [])]) {
+    const statuses = diagnosticStatusByEntity.get(id) ?? new Set()
+    statuses.add(diagnostic.status)
+    diagnosticStatusByEntity.set(id, statuses)
+  }
+  for (const packageEntity of packageEntities) {
+    const docs = allDeclaredRelations.filter((relation) => relation.from.startsWith('document:') && relation.to === packageEntity.id)
+    const statuses = diagnosticStatusByEntity.get(packageEntity.id) ?? new Set()
+    if (!docs.length) packageStatus.missing += 1
+    else if (statuses.has('conflict') || statuses.has('stale-or-unverified')) packageStatus.stale += 1
+    else if (statuses.has('undocumented') || statuses.has('unresolved') || statuses.has('not-analyzed')) packageStatus.unverified += 1
+    else packageStatus.fresh += 1
+  }
+  const documents = observed.entities.filter((entity) => entity.kind === 'document')
+  const documentedDocumentIds = new Set(allDeclaredRelations.filter((relation) => relation.from.startsWith('document:')).map((relation) => relation.from))
+  const documentation = {
+    documentCount: documents.length,
+    documentedDocumentCount: documentedDocumentIds.size,
+    documentClassificationCounts: countDocumentClasses(documents),
+    documentedDocumentClassificationCounts: countDocumentClasses(documents, documentedDocumentIds),
+    packageCount: packageEntities.length,
+    packageStatus,
+  }
   const base = {
     type: 'reconciliation-report' as const,
     schemaVersion: 1 as const,
@@ -228,7 +399,12 @@ export const reconcileKnowledge = (
       entityCount: observed.entities.length,
       relationCount: observedRelations.length,
       diagnosticCount: sortedDiagnostics.length,
+      ...(options.scope === undefined ? {} : { scope: options.scope }),
       ...(options.requiredRelationKinds === undefined ? {} : { requiredRelationKinds: [...new Set(options.requiredRelationKinds)].sort() }),
+      ...(options.requiredRelationTargets === undefined ? {} : { requiredRelationTargets: options.requiredRelationTargets }),
+      diagnosticsByCode: diagnosticCounts(sortedDiagnostics.map((diagnostic) => diagnostic.code)),
+      diagnosticsByStatus: diagnosticCounts(sortedDiagnostics.map((diagnostic) => diagnostic.status)),
+      documentation,
     },
   }
   return ReconciliationReportV1Schema.parse({ ...base, contentHash: contentHashForArtifactV1(base) })