@agentskit/doc-bridge 1.6.4 → 1.7.44

package/src/plugins/contract.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod'
+
+import { CoverageSchema, DiagnosticSchema, EntitySchema, RelationSchema, type Coverage, type KnowledgeDiagnostic, type KnowledgeEntity, type KnowledgeRelation } from '../schemas/knowledge.js'
+
+export const ANALYZER_PLUGIN_CONTRACT_VERSION = 1 as const
+
+export const AnalyzerPluginManifestSchema = z.object({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/).max(128),
+  version: z.string().min(1).max(64),
+  languages: z.array(z.string().min(1).max(64)).min(1).max(32),
+  frameworks: z.array(z.string().min(1).max(128)).max(32).default([]),
+  capabilities: z.array(z.string().min(1).max(128)).min(1).max(32),
+  knowledgeSchemaVersion: z.literal(1),
+  compatibility: z.object({ pipelineMajor: z.number().int().nonnegative() }).strict(),
+  unsupportedConstructs: z.array(z.string().min(1).max(256)).max(128).default([]),
+  resourceLimits: z.object({ maxFiles: z.number().int().positive().optional(), maxBytes: z.number().int().positive().optional() }).strict().default({}),
+}).strict()
+
+export type AnalyzerPluginManifest = z.infer<typeof AnalyzerPluginManifestSchema>
+
+export const AnalyzerPluginOutputSchema = z.object({
+  entities: z.array(EntitySchema).max(50_000).default([]),
+  relations: z.array(RelationSchema).max(100_000).default([]),
+  coverage: z.array(CoverageSchema).max(1_000).default([]),
+  diagnostics: z.array(DiagnosticSchema).max(100_000).default([]),
+}).strict()
+
+export type AnalyzerPluginOutput = z.infer<typeof AnalyzerPluginOutputSchema>
+
+export type AnalyzerPluginInput = {
+  readonly language: string
+  readonly framework?: string
+  readonly files: readonly { readonly path: string; readonly bytes: number }[]
+  readonly value?: unknown
+}
+
+export type AnalyzerPlugin = {
+  readonly manifest: AnalyzerPluginManifest
+  readonly analyze: (input: AnalyzerPluginInput) => Promise<unknown> | unknown
+}
+
+export type AnalyzerRegistry = {
+  readonly register: (plugin: AnalyzerPlugin) => void
+  readonly list: () => readonly AnalyzerPluginManifest[]
+  readonly analyze: (id: string, input: AnalyzerPluginInput) => Promise<AnalyzerPluginOutput>
+}
+
+const pipelineMajor = (version: string): number => Number.parseInt(version.split('.')[0] ?? '', 10)
+
+export const createAnalyzerRegistry = (options: { readonly pipelineVersion?: string; readonly maxPlugins?: number } = {}): AnalyzerRegistry => {
+  const plugins = new Map<string, AnalyzerPlugin>()
+  const pipeline = pipelineMajor(options.pipelineVersion ?? '1.0.0')
+  return {
+    register(plugin) {
+      const manifest = AnalyzerPluginManifestSchema.parse(plugin.manifest)
+      if (manifest.compatibility.pipelineMajor !== pipeline) throw new Error(`Analyzer plugin "${manifest.id}" requires pipeline major ${manifest.compatibility.pipelineMajor}; current pipeline is ${pipeline}.`)
+      if (plugins.has(manifest.id)) throw new Error(`Analyzer plugin "${manifest.id}" is already registered.`)
+      if (options.maxPlugins !== undefined && plugins.size >= options.maxPlugins) throw new Error(`Analyzer plugin limit ${options.maxPlugins} exceeded.`)
+      plugins.set(manifest.id, { ...plugin, manifest })
+    },
+    list() {
+      return [...plugins.values()].map((plugin) => plugin.manifest).sort((a, b) => a.id.localeCompare(b.id))
+    },
+    async analyze(id, input) {
+      const plugin = plugins.get(id)
+      if (!plugin) throw new Error(`Analyzer plugin "${id}" is not registered.`)
+      const { maxFiles, maxBytes } = plugin.manifest.resourceLimits
+      const bytes = input.files.reduce((total, file) => total + file.bytes, 0)
+      if (maxFiles !== undefined && input.files.length > maxFiles) throw new Error(`Analyzer plugin "${id}" file limit ${maxFiles} exceeded.`)
+      if (maxBytes !== undefined && bytes > maxBytes) throw new Error(`Analyzer plugin "${id}" byte limit ${maxBytes} exceeded.`)
+      try {
+        const output = AnalyzerPluginOutputSchema.parse(await plugin.analyze(input))
+        return {
+          ...output,
+          coverage: output.coverage.map((entry) => ({ ...entry, analyzer: plugin.manifest.id, analyzerVersion: plugin.manifest.version })),
+        }
+      } catch (error) {
+        return {
+          entities: [],
+          relations: [],
+          diagnostics: [],
+          coverage: [{ analyzer: plugin.manifest.id, analyzerVersion: plugin.manifest.version, scope: 'plugin', status: 'not-analyzed', reason: `Plugin failed safely: ${error instanceof Error ? error.message : String(error)}` }],
+        }
+      }
+    },
+  }
+}
+
+export type { Coverage, KnowledgeDiagnostic, KnowledgeEntity, KnowledgeRelation }

package/src/reconciliation/reconcile.ts

@@ -11,8 +11,12 @@ 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[]
+  /** Emit one bounded finding for each observed Markdown document without declarations. */
+  readonly includeOrphanedDocuments?: boolean
 }
 
 const ignoredDocumentationRelations = new Set(['covers'])
@@ -51,6 +55,14 @@ 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 diagnosticId = (code: string, value: unknown): string =>
   `reconciliation:${code}:${sha256NormalizedV1(value).slice(0, 32)}`
 
@@ -72,6 +84,80 @@ 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 kind = parts[2] ?? first.kind
+    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 +179,7 @@ const reportDiagnostic = (
   status,
   severity,
   message,
-  evidence: [...evidence],
+  evidence: boundedEvidence(evidence),
   ...(entityIds?.length ? { entityIds: [...entityIds] } : {}),
   ...(relationIds?.length ? { relationIds: [...relationIds] } : {}),
   ...(remediation ? { remediation } : {}),
@@ -106,11 +192,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',
@@ -211,6 +318,29 @@ 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 documentation = {
+    documentCount: observed.entities.filter((entity) => entity.kind === 'document').length,
+    documentedDocumentCount: new Set(allDeclaredRelations.filter((relation) => relation.from.startsWith('document:')).map((relation) => relation.from)).size,
+    packageCount: packageEntities.length,
+    packageStatus,
+  }
   const base = {
     type: 'reconciliation-report' as const,
     schemaVersion: 1 as const,
@@ -228,7 +358,11 @@ 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() }),
+      diagnosticsByCode: diagnosticCounts(sortedDiagnostics.map((diagnostic) => diagnostic.code)),
+      diagnosticsByStatus: diagnosticCounts(sortedDiagnostics.map((diagnostic) => diagnostic.status)),
+      documentation,
     },
   }
   return ReconciliationReportV1Schema.parse({ ...base, contentHash: contentHashForArtifactV1(base) })