@agentskit/doc-bridge 1.6.3 → 1.7.44

package/src/config/schema.ts

@@ -181,8 +181,48 @@ export const RulesConfigSchema = z
 
 export const ReconciliationConfigSchema = z
   .object({
+    /** Semantic comparison level. Raw discovery always keeps file-level relations. */
+    scope: z.enum(['file', 'module', 'package']).optional(),
     /** Relation kinds that must have documentation declarations. Omit to require all observed kinds; [] disables this signal. */
     requiredRelationKinds: z.array(z.string().min(1).max(128)).max(128).optional(),
+    includeOrphanedDocuments: z.boolean().optional(),
+  })
+  .strict()
+
+export const AnalysisConfigSchema = z
+  .object({
+    plugins: z
+      .array(
+        z
+          .object({
+            id: z.string().regex(/^[a-z][a-z0-9-]*$/).max(128),
+            enabled: z.boolean().optional(),
+            order: z.number().int().nonnegative().optional(),
+            options: z.record(z.string(), z.unknown()).optional(),
+            reason: z.string().min(1).max(1_024).optional(),
+          })
+          .strict(),
+      )
+      .max(128)
+      .optional(),
+    jsTs: z
+      .object({
+        runtimeWiringMethods: z.array(z.string().regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/).max(64)).max(64).optional(),
+        runtimeWiringAdapters: z
+          .array(
+            z
+              .object({
+                id: z.string().min(1).max(128),
+                methods: z.array(z.string().regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/).max(64)).min(1).max(64),
+              })
+              .strict(),
+          )
+          .max(32)
+          .optional(),
+        includeTestRuntimeWiring: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
   })
   .strict()
 
@@ -203,6 +243,13 @@ export const RepositorySafetyConfigSchema = z
   })
   .strict()
 
+export const ReportConfigSchema = z
+  .object({
+    /** Public report privacy mode. Private is the default; anonymized preserves topology without project identity. */
+    privacy: z.enum(['private', 'anonymized']).optional(),
+  })
+  .strict()
+
 export const SurfacesConfigSchema = z
   .object({
     cli: z
@@ -310,6 +357,11 @@ export const IntelligenceConfigSchema = z
         agentId: z.string().min(1).max(256).optional(),
         agentRoot: z.string().min(1).max(512).optional(),
         runnerModule: z.string().min(1).max(512).optional(),
+        deterministic: z.boolean().optional(),
+        timeoutMs: z.number().int().positive().max(600_000).optional(),
+        maxTokens: z.number().int().positive().max(1_000_000).optional(),
+        maxResponseBytes: z.number().int().positive().max(10_000_000).optional(),
+        maxConcurrency: z.number().int().positive().max(64).optional(),
       })
       .strict()
       .optional(),
@@ -442,9 +494,11 @@ export const DocBridgeConfigV1Schema = z
     routing: RoutingConfigSchema.optional(),
     gates: GatesConfigSchema.optional(),
     reconciliation: ReconciliationConfigSchema.optional(),
+    analysis: AnalysisConfigSchema.optional(),
     rules: RulesConfigSchema.optional(),
     workflow: WorkflowConfigSchema.optional(),
     safety: RepositorySafetyConfigSchema.optional(),
+    report: ReportConfigSchema.optional(),
     surfaces: SurfacesConfigSchema.optional(),
     intelligence: IntelligenceConfigSchema.optional(),
     federation: FederationConfigSchema.optional(),
@@ -458,8 +512,10 @@ export type HumanCorpusConfig = z.infer<typeof HumanCorpusConfigSchema>
 export type DocumentationStandardV1Config = z.infer<typeof DocumentationStandardV1ConfigSchema>
 export type DocumentationStandardRuleId = z.infer<typeof DocumentationStandardRuleIdSchema>
 export type ReconciliationConfig = z.infer<typeof ReconciliationConfigSchema>
+export type AnalysisConfig = z.infer<typeof AnalysisConfigSchema>
 export type RuleId = z.infer<typeof RuleIdSchema>
 export type RuleSeverity = z.infer<typeof RuleSeveritySchema>
 export type RulesConfig = z.infer<typeof RulesConfigSchema>
 export type WorkflowConfig = z.infer<typeof WorkflowConfigSchema>
 export type RepositorySafetyConfig = z.infer<typeof RepositorySafetyConfigSchema>
+export type ReportConfig = z.infer<typeof ReportConfigSchema>

package/src/discovery/documentation.ts

@@ -22,6 +22,8 @@ export type DocumentationDeclarationInput = {
 export type DocumentationDeclarationOptions = {
   readonly snapshot: Pick<DiscoverySnapshotV1, 'entities'>
   readonly documentId?: string
+  /** Agent corpus root used for conservative package/app path inference. */
+  readonly agentRoot?: string
 }
 
 export type DocumentationDeclarationResult = {
@@ -71,6 +73,15 @@ const scalar = (value: string): string => {
   return trimmed
 }
 
+const conventionalPackageReference = (path: string, agentRoot: string): string | undefined => {
+  const prefix = `${agentRoot.replace(/\/$/, '')}/`
+  if (!path.startsWith(prefix)) return undefined
+  const relative = path.slice(prefix.length)
+  const [scope, file] = relative.split('/')
+  if ((scope !== 'packages' && scope !== 'apps') || !file) return undefined
+  return file.replace(/\.mdx?$/, '')
+}
+
 const list = (value: string): string[] | undefined => {
   const trimmed = value.trim()
   if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) return undefined
@@ -103,7 +114,15 @@ const resolveEntity = (
   lineStart: number,
   unresolved: Map<string, KnowledgeEntity>,
 ): KnowledgeEntity => {
-  const resolved = entities.find((entity) => entity.id === reference || entity.aliases?.includes(reference))
+  const direct = entities.find((entity) => entity.id === reference || entity.aliases?.includes(reference))
+  if (direct) return direct
+  const packageReference = reference.replace(/^package:/, '')
+  const packageCandidates = entities.filter((entity) => {
+    if (entity.kind !== 'package') return false
+    const pathName = entity.path?.split('/').pop()
+    return entity.name === reference || entity.path === reference || pathName === packageReference || entity.name.endsWith(`/${packageReference}`)
+  })
+  const resolved = packageCandidates.length === 1 ? packageCandidates[0] : undefined
   if (resolved) return resolved
   const id = `unresolved:${reference}`
   const existing = unresolved.get(id)
@@ -123,9 +142,14 @@ const relationKey = (from: string, to: string, kind: string): string => `${from}
 
 const parseBlock = (
   input: DocumentationDeclarationInput,
+  options: Pick<DocumentationDeclarationOptions, 'agentRoot'> = {},
 ): { readonly covers: readonly { value: string; line: number }[]; readonly relations: readonly RelationFields[]; readonly diagnostics: readonly DocumentationDiagnostic[]; readonly hasDocbridge: boolean } => {
+  const conventionalPath = conventionalPackageReference(input.path, options.agentRoot ?? 'docs/for-agents')
   const frontmatter = findFrontmatter(input.content)
   if (!frontmatter) {
+    if (conventionalPath && !input.content.replace(/^\uFEFF/, '').startsWith('---')) {
+      return { covers: [{ value: conventionalPath, line: 1 }], relations: [], diagnostics: [], hasDocbridge: true }
+    }
     if (input.content.replace(/^\uFEFF/, '').startsWith('---')) {
       return {
         covers: [],
@@ -138,8 +162,24 @@ const parseBlock = (
   }
 
   const { lines, end } = frontmatter
-  const docbridgeLine = lines.findIndex((line, index) => index > 0 && index < end && /^docbridge\s*:/.test(line))
-  if (docbridgeLine < 0) return { covers: [], relations: [], diagnostics: [], hasDocbridge: false }
+  let docbridgeLine = -1
+  let typeLine = -1
+  let packageLine = -1
+  let humanDocLine = -1
+  for (let index = 1; index < end; index += 1) {
+    const line = lines[index] ?? ''
+    if (docbridgeLine < 0 && /^docbridge\s*:/.test(line)) docbridgeLine = index
+    if (typeLine < 0 && /^type\s*:/.test(line)) typeLine = index
+    if (packageLine < 0 && /^package\s*:/.test(line)) packageLine = index
+    if (humanDocLine < 0 && /^humanDoc\s*:/.test(line)) humanDocLine = index
+  }
+  if (docbridgeLine < 0) {
+    const type = typeLine >= 0 ? scalar(lines[typeLine]?.slice('type:'.length) ?? '') : ''
+    const packageReference = packageLine >= 0 ? scalar(lines[packageLine]?.slice('package:'.length) ?? '') : conventionalPath ?? ''
+    if (type === 'package' && packageReference) return { covers: [{ value: packageReference, line: packageLine >= 0 ? packageLine + 1 : typeLine + 1 }], relations: [], diagnostics: [], hasDocbridge: true }
+    if (conventionalPath) return { covers: [{ value: packageReference, line: humanDocLine >= 0 ? humanDocLine + 1 : 1 }], relations: [], diagnostics: [], hasDocbridge: true }
+    return { covers: [], relations: [], diagnostics: [], hasDocbridge: false }
+  }
 
   const diagnostics: DocumentationDiagnostic[] = []
   const covers: { value: string; line: number }[] = []
@@ -231,7 +271,7 @@ export const parseDocumentationDeclarations = (
   input: DocumentationDeclarationInput,
   options: DocumentationDeclarationOptions,
 ): DocumentationDeclarationResult => {
-  const parsed = parseBlock(input)
+  const parsed = parseBlock(input, options)
   if (!parsed.hasDocbridge) return { hasDocbridge: false, entities: [], relations: [], diagnostics: [] }
   const diagnostics = [...parsed.diagnostics]
   const unresolved = new Map<string, KnowledgeEntity>()
@@ -300,13 +340,14 @@ export const parseDocumentationDeclarations = (
 export const applyDocumentationDeclarations = (
   snapshot: DiscoverySnapshotV1,
   documents: readonly DocumentationDeclarationInput[],
+  options: Pick<DocumentationDeclarationOptions, 'agentRoot'> = {},
 ): DocumentationAnalysisResult => {
   const entities = new Map(snapshot.entities.map((entity) => [entity.id, entity]))
   const relations = new Map(snapshot.relations.map((relation) => [relation.id, relation]))
   const diagnostics: DocumentationDiagnostic[] = []
 
   for (const document of documents) {
-    const result = parseDocumentationDeclarations(document, { snapshot })
+    const result = parseDocumentationDeclarations(document, { snapshot, ...options })
     diagnostics.push(...result.diagnostics)
     for (const entity of result.entities) entities.set(entity.id, entity)
     for (const relation of result.relations) relations.set(relation.id, relation)

package/src/discovery/repository.ts

@@ -21,6 +21,8 @@ const SOURCE_EXTENSIONS = ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts',
 const DOCUMENT_EXTENSIONS = ['.md', '.mdx'] as const
 const DEFAULT_MAX_FILES = 10_000
 const EMPTY_HASH = '0'.repeat(64)
+const DEFAULT_RUNTIME_WIRING_METHODS = ['register', 'use', 'mount', 'attach'] as const
+const TEST_MODULE_PATTERN = /(?:\.test|\.spec|__tests__)/
 
 type JsonRecord = Record<string, unknown>
 
@@ -42,8 +44,9 @@ type ModuleInfo = {
 
 type ImportReference = {
   readonly specifier: string
-  readonly kind: 'imports' | 're-exports'
+  readonly kind: 'imports' | 're-exports' | 'runtime-wiring'
   readonly evidence: Evidence
+  readonly detection?: 'dynamic-literal' | 'runtime-wiring-static'
 }
 
 type DiscoveryOptions = {
@@ -97,6 +100,13 @@ const firstLineContaining = (text: string, pattern: string): number | undefined
   return line >= 0 ? line + 1 : undefined
 }
 
+const documentClassification = (path: string): string => {
+  if (/(^|\/)docs\/for-agents(?:\/|$)/.test(path)) return 'agent'
+  if (/(^|\/)docs(?:\/|$)/.test(path)) return 'human'
+  if (/(^|\/)(README|CONTRIBUTING|SECURITY|CHANGELOG)(?:\.|$)/i.test(path)) return 'project'
+  return 'unclassified'
+}
+
 const packageName = (manifest: JsonRecord, fallback: string): string | undefined =>
   typeof manifest.name === 'string' && manifest.name.length > 0 ? manifest.name : fallback || undefined
 
@@ -262,30 +272,69 @@ const moduleReferences = (
   root: string,
   path: string,
   sourceFile: ts.SourceFile,
-): { readonly references: readonly ImportReference[]; readonly exports: readonly string[]; readonly hasDynamic: boolean; readonly hasRuntimeWiring: boolean } => {
+  runtimeWiringMethods: ReadonlySet<string>,
+): { readonly references: readonly ImportReference[]; readonly exports: readonly string[]; readonly hasDynamic: boolean; readonly hasLiteralDynamic: boolean; readonly hasRuntimeWiring: boolean; readonly hasUnresolvedRuntimeWiring: boolean } => {
   const references: ImportReference[] = []
   let hasDynamic = false
+  let hasLiteralDynamic = false
   let hasRuntimeWiring = false
-  const addReference = (specifier: ts.StringLiteralLike, kind: ImportReference['kind'], node: ts.Node): void => {
-    references.push({ specifier: specifier.text, kind, evidence: nodeEvidence(root, path, sourceFile, node) })
+  let hasUnresolvedRuntimeWiring = false
+  const importedBindings = new Map<string, string>()
+  const staticStringBindings = new Map<string, string | undefined>()
+  const collectStaticStringBindings = (node: ts.Node): void => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isStringLiteralLike(node.initializer) && ts.isVariableDeclarationList(node.parent) && (node.parent.flags & ts.NodeFlags.Const) !== 0) {
+      const previous = staticStringBindings.get(node.name.text)
+      staticStringBindings.set(node.name.text, !staticStringBindings.has(node.name.text) || previous === node.initializer.text ? node.initializer.text : undefined)
+    }
+    ts.forEachChild(node, collectStaticStringBindings)
+  }
+  collectStaticStringBindings(sourceFile)
+  const addReference = (specifier: ts.StringLiteralLike, kind: ImportReference['kind'], node: ts.Node, detection?: ImportReference['detection']): void => {
+    references.push({ specifier: specifier.text, kind, evidence: nodeEvidence(root, path, sourceFile, node), ...(detection ? { detection } : {}) })
   }
 
   const visit = (node: ts.Node): void => {
     if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
       addReference(node.moduleSpecifier, 'imports', node)
+      const clause = node.importClause
+      if (clause?.name) importedBindings.set(clause.name.text, node.moduleSpecifier.text)
+      if (clause?.namedBindings && ts.isNamespaceImport(clause.namedBindings)) importedBindings.set(clause.namedBindings.name.text, node.moduleSpecifier.text)
+      if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+        for (const element of clause.namedBindings.elements) importedBindings.set((element.name ?? element.propertyName)?.text ?? '', node.moduleSpecifier.text)
+      }
     } else if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
       addReference(node.moduleSpecifier, 're-exports', node)
     } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) && ts.isStringLiteral(node.moduleReference.expression)) {
       addReference(node.moduleReference.expression, 'imports', node)
+      importedBindings.set(node.name.text, node.moduleReference.expression.text)
     } else if (ts.isCallExpression(node)) {
       if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
-        if (!node.arguments[0] || !ts.isStringLiteralLike(node.arguments[0])) hasDynamic = true
+        if (node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])) {
+          hasLiteralDynamic = true
+          addReference(node.arguments[0], 'imports', node, 'dynamic-literal')
+        } else if (node.arguments[0] && ts.isIdentifier(node.arguments[0]) && staticStringBindings.get(node.arguments[0].text)) {
+          hasLiteralDynamic = true
+          addReference({ text: staticStringBindings.get(node.arguments[0].text)! } as ts.StringLiteralLike, 'imports', node, 'dynamic-literal')
+        } else hasDynamic = true
       } else if (ts.isIdentifier(node.expression) && node.expression.text === 'require') {
         const argument = node.arguments[0]
         if (argument && ts.isStringLiteralLike(argument)) addReference(argument, 'imports', node)
+        else if (argument && ts.isIdentifier(argument) && staticStringBindings.get(argument.text)) addReference({ text: staticStringBindings.get(argument.text)! } as ts.StringLiteralLike, 'imports', node)
         else hasDynamic = true
-      } else if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register') {
+      } else if (ts.isPropertyAccessExpression(node.expression) && runtimeWiringMethods.has(node.expression.name.text)) {
         hasRuntimeWiring = true
+        const before = references.length
+        let hasPotentialTargetArgument = false
+        for (const argument of node.arguments) {
+          if (ts.isIdentifier(argument)) {
+            hasPotentialTargetArgument = true
+            const specifier = importedBindings.get(argument.text)
+            if (specifier) addReference({ text: specifier } as ts.StringLiteralLike, 'runtime-wiring', node, 'runtime-wiring-static')
+          } else if (ts.isPropertyAccessExpression(argument) || ts.isCallExpression(argument)) {
+            hasPotentialTargetArgument = true
+          }
+        }
+        if (hasPotentialTargetArgument && references.length === before) hasUnresolvedRuntimeWiring = true
       }
     }
     ts.forEachChild(node, visit)
@@ -295,7 +344,9 @@ const moduleReferences = (
     references,
     exports: exportedNames(sourceFile),
     hasDynamic,
+    hasLiteralDynamic,
     hasRuntimeWiring,
+    hasUnresolvedRuntimeWiring,
   }
 }
 
@@ -395,10 +446,10 @@ const artifact = (root: string, config: DocBridgeConfigV1 | undefined, files: re
     sourceRevisionKind: revision.kind,
     configurationHash: sha256NormalizedV1(config ?? {}),
     pipelineVersion: '1.0.0',
-    analyzerVersions: { repository: '1.0.0', 'js-ts': '1.0.0' },
+    analyzerVersions: { repository: '1.0.0', 'js-ts': '1.3.0' },
     entities: [...entities].sort((a, b) => a.id.localeCompare(b.id)),
     relations: [...relations].sort((a, b) => a.id.localeCompare(b.id)),
-    coverage: [...coverage],
+    coverage: coverage.map((entry) => ({ ...entry, analyzerVersion: entry.analyzerVersion ?? ({ repository: '1.0.0', 'js-ts': '1.3.0' }[entry.analyzer] ?? '1.0.0') })),
   }
   return DiscoverySnapshotV1Schema.parse({ ...base, contentHash: contentHashForArtifactV1(base) })
 }
@@ -463,13 +514,13 @@ export const discoverRepository = (opts: DiscoveryOptions = {}): DiscoverySnapsh
     const sourceFile = ts.createSourceFile(absPath, text, ts.ScriptTarget.Latest, true, scriptKind(absPath))
     const exports = exportedNames(sourceFile)
     modules.set(resolve(absPath), { absPath, path, entityId: id, ...(pkg ? { packageId: pkg.id } : {}) })
-    addEntity({ id, kind: 'module', name: basename(absPath), path, provenance: 'observed', evidence: [lineEvidence('code', root, absPath, 1, sourceFile.getLineAndCharacterOfPosition(sourceFile.getEnd()).line + 1)], ...(exports.length ? { metadata: { exports, test: /(?:\.test|\.spec|__tests__)/.test(path) } } : {}) })
+    addEntity({ id, kind: 'module', name: basename(absPath), path, provenance: 'observed', evidence: [lineEvidence('code', root, absPath, 1, sourceFile.getLineAndCharacterOfPosition(sourceFile.getEnd()).line + 1)], ...(exports.length ? { metadata: { exports, test: TEST_MODULE_PATTERN.test(path) } } : {}) })
     if (pkg) addRelation({ id: entityId('relation', `${pkg.id}:contains:${id}`), kind: 'contains', from: pkg.id, to: id, provenance: 'observed', evidence: [lineEvidence('code', root, absPath, 1)] })
   }
 
   for (const absPath of documentPaths) {
     const path = relativePath(root, absPath)
-    addEntity({ id: entityId('document', path), kind: 'document', name: basename(absPath), path, provenance: 'observed', evidence: [lineEvidence('documentation', root, absPath, 1)] })
+    addEntity({ id: entityId('document', path), kind: 'document', name: basename(absPath), path, provenance: 'observed', evidence: [lineEvidence('documentation', root, absPath, 1)], metadata: { classification: documentClassification(path) } })
   }
 
   const compiler = readCompilerOptions(root)
@@ -478,8 +529,8 @@ export const discoverRepository = (opts: DiscoveryOptions = {}): DiscoverySnapsh
     { analyzer: 'repository', scope: 'package-manager', status: hasPackageManagerMetadata(root, rootManifest) ? 'complete' : 'partial', ...(!hasPackageManagerMetadata(root, rootManifest) ? { reason: `No package manager metadata found; default helper would fall back to ${detectPackageManager(root)}.` } : {}) },
     { analyzer: 'repository', scope: 'workspace-packages', status: packageResult.coverage.some((item) => item.status === 'partial') ? 'partial' : 'complete', ...(packageResult.coverage.find((item) => item.reason)?.reason ? { reason: packageResult.coverage.find((item) => item.reason)?.reason } : {}) },
     { analyzer: 'js-ts', scope: 'static-imports-and-exports', status: compiler.error ? 'partial' : 'complete', ...(compiler.error ? { reason: compiler.error } : {}) },
-    { analyzer: 'js-ts', scope: 'dynamic-imports', status: 'not-analyzed', reason: 'Dynamic import expressions and non-literal require calls are not resolved.' },
-    { analyzer: 'js-ts', scope: 'runtime-wiring', status: 'not-analyzed', reason: 'Reflection, dependency injection and runtime wiring are not inferred.' },
+    { analyzer: 'js-ts', scope: 'dynamic-imports', status: 'not-applicable', reason: 'No dynamic loading expression was observed.' },
+    { analyzer: 'js-ts', scope: 'runtime-wiring', status: 'not-applicable', reason: 'No configured runtime-wiring call was observed.' },
     { analyzer: 'js-ts', scope: 'generated-code', status: 'not-analyzed', reason: 'Generated code is not interpreted as source architecture.' },
   ]
 
@@ -492,10 +543,26 @@ export const discoverRepository = (opts: DiscoveryOptions = {}): DiscoverySnapsh
     }
   }
 
+  const dynamicCoverageIndex = coverage.findIndex((entry) => entry.scope === 'dynamic-imports')
+  const configuredRuntimeWiringMethods = new Set([
+    ...(opts.config?.analysis?.jsTs?.runtimeWiringMethods ?? []),
+    ...(opts.config?.analysis?.jsTs?.runtimeWiringAdapters?.flatMap((adapter) => adapter.methods) ?? []),
+  ])
+  if (!configuredRuntimeWiringMethods.size) for (const method of DEFAULT_RUNTIME_WIRING_METHODS) configuredRuntimeWiringMethods.add(method)
+  const includeTestRuntimeWiring = opts.config?.analysis?.jsTs?.includeTestRuntimeWiring ?? false
+  let observedLiteralDynamic = false
+  let observedUnresolvedDynamic = false
+  let observedRuntimeWiring = false
+  let observedUnresolvedRuntimeWiring = false
   for (const module of modules.values()) {
     const text = readFileSync(module.absPath, 'utf8')
     const sourceFile = ts.createSourceFile(module.absPath, text, ts.ScriptTarget.Latest, true, scriptKind(module.absPath))
-    const references = moduleReferences(root, module.absPath, sourceFile)
+    const runtimeWiringMethods = includeTestRuntimeWiring || !TEST_MODULE_PATTERN.test(module.path) ? configuredRuntimeWiringMethods : new Set<string>()
+    const references = moduleReferences(root, module.absPath, sourceFile, runtimeWiringMethods)
+    observedLiteralDynamic ||= references.hasLiteralDynamic
+    observedUnresolvedDynamic ||= references.hasDynamic
+    observedRuntimeWiring ||= references.hasRuntimeWiring
+    observedUnresolvedRuntimeWiring ||= references.hasUnresolvedRuntimeWiring
     for (const reference of references.references) {
       const target = resolveReference(reference, module.absPath, modules, packageResult.packages, compiler.options)
       if (!target) continue
@@ -503,12 +570,24 @@ export const discoverRepository = (opts: DiscoveryOptions = {}): DiscoverySnapsh
         const externalName = target.targetId.replace(/^external:/, '')
         addEntity({ id: target.targetId, kind: 'external', name: externalName, provenance: 'observed', evidence: [reference.evidence] })
       }
-      addRelation({ id: entityId('relation', `${module.entityId}:${reference.kind}:${target.targetId}`), kind: reference.kind, from: module.entityId, to: target.targetId, provenance: 'observed', evidence: [reference.evidence] })
+      addRelation({ id: entityId('relation', `${module.entityId}:${reference.kind}:${target.targetId}`), kind: reference.kind, from: module.entityId, to: target.targetId, provenance: 'observed', evidence: [reference.evidence], ...(reference.detection ? { metadata: { detection: reference.detection } } : {}) })
     }
-    if (references.hasDynamic) coverage.push({ analyzer: 'js-ts', scope: `dynamic-imports:${module.path}`, status: 'not-analyzed', reason: 'A dynamic import or non-literal require was found.', evidence: [lineEvidence('code', root, module.absPath)] })
-    if (references.hasRuntimeWiring) coverage.push({ analyzer: 'js-ts', scope: `runtime-wiring:${module.path}`, status: 'not-analyzed', reason: 'A possible runtime registration/wiring call was found.', evidence: [lineEvidence('code', root, module.absPath)] })
+    if (references.hasLiteralDynamic || references.hasDynamic) coverage.push({ analyzer: 'js-ts', scope: `dynamic-imports:${module.path}`, status: references.hasDynamic ? 'not-analyzed' : 'complete', reason: references.hasDynamic ? 'A non-literal dynamic import was found; the target is unresolved.' : 'Literal dynamic imports were resolved.', evidence: [lineEvidence('code', root, module.absPath)] })
+    if (references.hasUnresolvedRuntimeWiring) coverage.push({ analyzer: 'js-ts', scope: `runtime-wiring:${module.path}`, status: 'not-analyzed', reason: 'A runtime registration/wiring call was found without a statically imported target.', evidence: [lineEvidence('code', root, module.absPath)] })
   }
 
+  if (dynamicCoverageIndex >= 0) coverage[dynamicCoverageIndex] = observedUnresolvedDynamic
+    ? { analyzer: 'js-ts', scope: 'dynamic-imports', status: 'partial', reason: 'Literal dynamic imports are resolved; non-literal import expressions and require calls remain unresolved.' }
+    : observedLiteralDynamic
+      ? { analyzer: 'js-ts', scope: 'dynamic-imports', status: 'complete', reason: 'All observed dynamic imports used literal targets and were resolved.' }
+      : { analyzer: 'js-ts', scope: 'dynamic-imports', status: 'not-applicable', reason: 'No dynamic loading expression was observed.' }
+  const runtimeCoverageIndex = coverage.findIndex((entry) => entry.scope === 'runtime-wiring')
+  if (runtimeCoverageIndex >= 0) coverage[runtimeCoverageIndex] = observedUnresolvedRuntimeWiring
+    ? { analyzer: 'js-ts', scope: 'runtime-wiring', status: 'partial', reason: 'Some configured runtime-wiring calls remain unresolved after static binding analysis.' }
+    : observedRuntimeWiring
+      ? { analyzer: 'js-ts', scope: 'runtime-wiring', status: 'complete', reason: 'All observed configured runtime-wiring calls resolved to static bindings.' }
+      : { analyzer: 'js-ts', scope: 'runtime-wiring', status: 'not-applicable', reason: 'No configured runtime-wiring call was observed.' }
+
   return artifact(root, opts.config, allFiles, [...entities.values()], [...relations.values()], coverage)
 }
 

package/src/index.ts

@@ -20,11 +20,13 @@ export {
   RulesConfigSchema,
   WorkflowConfigSchema,
   RepositorySafetyConfigSchema,
+  ReportConfigSchema,
   type RuleId,
   type RuleSeverity,
   type RulesConfig,
   type WorkflowConfig,
   type RepositorySafetyConfig,
+  type ReportConfig,
 } from './config/schema.js'
 
 export {
@@ -180,6 +182,33 @@ export {
   type GithubPrResult,
 } from './memory/github-pr.js'
 export { canonicalJsonV1, contentHashForArtifactV1, sha256NormalizedV1 } from './index-builder/content-hash.js'
+export {
+  ANALYZER_PLUGIN_CONTRACT_VERSION,
+  AnalyzerPluginManifestSchema,
+  AnalyzerPluginOutputSchema,
+  createAnalyzerRegistry,
+  type AnalyzerPlugin,
+  type AnalyzerPluginInput,
+  type AnalyzerPluginManifest,
+  type AnalyzerPluginOutput,
+  type AnalyzerRegistry,
+} from './plugins/contract.js'
+export {
+  BENCHMARK_SCHEMA_VERSION,
+  BenchmarkFixtureV1Schema,
+  benchmarkFixture,
+  compareBenchmarkSnapshots,
+  formatBenchmarkText,
+  measureAgentEfficiency,
+  measureBenchmark,
+  type AgentEfficiencyObservation,
+  type BenchmarkFixtureV1,
+  type BenchmarkObservation,
+  type BenchmarkResult,
+  type BenchmarkSetMetrics,
+  type BenchmarkSnapshot,
+  type BenchmarkSnapshotDiff,
+} from './metrics/benchmark.js'
 export {
   AgentProposalV1Schema,
   AffectedFileSchema,

package/src/metrics/benchmark.ts

@@ -0,0 +1,176 @@
+import { z } from 'zod'
+
+export const BENCHMARK_SCHEMA_VERSION = 1 as const
+
+const stringList = z.array(z.string().min(1).max(512)).max(100_000)
+const benchmarkSets = z.object({
+  entities: stringList.default([]),
+  relations: stringList.default([]),
+  findings: stringList.default([]),
+}).strict()
+
+export const BenchmarkFixtureV1Schema = z.object({
+  schemaVersion: z.literal(BENCHMARK_SCHEMA_VERSION),
+  supported: benchmarkSets,
+  excluded: benchmarkSets.optional(),
+}).strict()
+
+export type BenchmarkFixtureV1 = z.infer<typeof BenchmarkFixtureV1Schema>
+
+export type BenchmarkObservation = {
+  readonly entities: readonly string[]
+  readonly relations: readonly string[]
+  readonly findings: readonly string[]
+  readonly evidenced?: readonly string[]
+  readonly findingCategories?: Readonly<Record<string, number>>
+}
+
+export type BenchmarkSetMetrics = {
+  readonly truePositives: number
+  readonly falsePositives: number
+  readonly falseNegatives: number
+  readonly precision: number
+  readonly recall: number
+  readonly duplicateCount: number
+}
+
+export type BenchmarkResult = {
+  readonly schemaVersion: typeof BENCHMARK_SCHEMA_VERSION
+  readonly quality: {
+    readonly entities: BenchmarkSetMetrics
+    readonly relations: BenchmarkSetMetrics
+    readonly findings: BenchmarkSetMetrics
+  }
+  readonly evidenceRatio: number
+  readonly findingDensity: number
+  readonly findingCategoryDistribution: Readonly<Record<string, number>>
+  readonly excludedCaseCount: number
+  readonly excludedCaseIds: Readonly<{ entities: number; relations: number; findings: number }>
+  readonly thresholds: { readonly precision: number; readonly recall: number }
+  readonly regressions: readonly string[]
+}
+
+const unique = (values: readonly string[]): Set<string> => new Set(values)
+const ratio = (numerator: number, denominator: number): number => denominator === 0 ? 1 : numerator / denominator
+
+const setMetrics = (
+  actualValues: readonly string[],
+  expectedValues: readonly string[],
+  excludedValues: readonly string[],
+): BenchmarkSetMetrics => {
+  const excluded = unique(excludedValues)
+  const activeActualValues = actualValues.filter((value) => !excluded.has(value))
+  const actual = unique(activeActualValues)
+  const expected = unique(expectedValues.filter((value) => !excluded.has(value)))
+  const truePositives = [...actual].filter((value) => expected.has(value)).length
+  const falsePositives = actual.size - truePositives
+  const falseNegatives = expected.size - truePositives
+  return {
+    truePositives,
+    falsePositives,
+    falseNegatives,
+    precision: ratio(truePositives, actual.size),
+    recall: ratio(truePositives, expected.size),
+    duplicateCount: activeActualValues.length - actual.size,
+  }
+}
+
+export const benchmarkFixture = (fixture: unknown): BenchmarkFixtureV1 => BenchmarkFixtureV1Schema.parse(fixture)
+
+export const measureBenchmark = (
+  observation: BenchmarkObservation,
+  fixture: BenchmarkFixtureV1,
+  thresholds: { readonly precision?: number; readonly recall?: number } = {},
+): BenchmarkResult => {
+  const excluded = fixture.excluded ?? { entities: [], relations: [], findings: [] }
+  const quality = {
+    entities: setMetrics(observation.entities, fixture.supported.entities, excluded.entities),
+    relations: setMetrics(observation.relations, fixture.supported.relations, excluded.relations),
+    findings: setMetrics(observation.findings, fixture.supported.findings, excluded.findings),
+  }
+  const actualEntities = unique(observation.entities)
+  const evidenced = unique(observation.evidenced ?? [])
+  const evidenceRatio = ratio([...actualEntities].filter((id) => evidenced.has(id)).length, actualEntities.size)
+  const findingDensity = ratio(unique(observation.findings).size, actualEntities.size)
+  const precisionThreshold = thresholds.precision ?? 0.95
+  const recallThreshold = thresholds.recall ?? 1
+  const regressions: string[] = []
+  for (const [name, metrics] of Object.entries(quality)) {
+    if (metrics.precision < precisionThreshold) regressions.push(`${name}.precision below ${precisionThreshold}`)
+    if (metrics.recall < recallThreshold) regressions.push(`${name}.recall below ${recallThreshold}`)
+  }
+  return {
+    schemaVersion: BENCHMARK_SCHEMA_VERSION,
+    quality,
+    evidenceRatio,
+    findingDensity,
+    findingCategoryDistribution: Object.fromEntries(Object.entries(observation.findingCategories ?? {}).sort(([a], [b]) => a.localeCompare(b))),
+    excludedCaseCount: excluded.entities.length + excluded.relations.length + excluded.findings.length,
+    excludedCaseIds: { entities: excluded.entities.length, relations: excluded.relations.length, findings: excluded.findings.length },
+    thresholds: { precision: precisionThreshold, recall: recallThreshold },
+    regressions,
+  }
+}
+
+export type BenchmarkSnapshot = Readonly<Record<string, string>>
+
+export type BenchmarkSnapshotDiff = {
+  readonly added: number
+  readonly removed: number
+  readonly unchanged: number
+  readonly reclassified: number
+  readonly unchangedEvidence: number
+}
+
+export const compareBenchmarkSnapshots = (
+  previous: BenchmarkSnapshot,
+  current: BenchmarkSnapshot,
+): BenchmarkSnapshotDiff => {
+  const ids = new Set([...Object.keys(previous), ...Object.keys(current)])
+  let added = 0
+  let removed = 0
+  let unchanged = 0
+  let reclassified = 0
+  let unchangedEvidence = 0
+  for (const id of ids) {
+    if (!(id in previous)) { added += 1; continue }
+    if (!(id in current)) { removed += 1; continue }
+    if (previous[id] === current[id]) unchanged += 1
+    else reclassified += 1
+    if (previous[id] === current[id]) unchangedEvidence += 1
+  }
+  return { added, removed, unchanged, reclassified, unchangedEvidence }
+}
+
+export type AgentEfficiencyObservation = {
+  readonly hits: number
+  readonly queries: number
+  readonly latencyMs: readonly number[]
+  readonly responseBytes: readonly number[]
+  readonly estimatedTokens: readonly number[]
+  readonly corpusBytes: number
+}
+
+const percentile95 = (values: readonly number[]): number => {
+  if (!values.length) return 0
+  const sorted = [...values].sort((a, b) => a - b)
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)] ?? 0
+}
+
+export const measureAgentEfficiency = (observation: AgentEfficiencyObservation) => ({
+  hitRate: ratio(observation.hits, observation.queries),
+  latencyP95Ms: percentile95(observation.latencyMs),
+  responseBytesP95: percentile95(observation.responseBytes),
+  estimatedTokensP95: percentile95(observation.estimatedTokens),
+  corpusBytes: observation.corpusBytes,
+  contextReduction: observation.corpusBytes > 0 ? 1 - (percentile95(observation.responseBytes) / observation.corpusBytes) : 0,
+})
+
+export const formatBenchmarkText = (result: BenchmarkResult): string => [
+  `Precision: entities ${result.quality.entities.precision.toFixed(3)}, relations ${result.quality.relations.precision.toFixed(3)}, findings ${result.quality.findings.precision.toFixed(3)}`,
+  `Recall: entities ${result.quality.entities.recall.toFixed(3)}, relations ${result.quality.relations.recall.toFixed(3)}, findings ${result.quality.findings.recall.toFixed(3)}`,
+  `Evidence ratio: ${result.evidenceRatio.toFixed(3)}`,
+  `Finding density: ${result.findingDensity.toFixed(3)}`,
+  `Excluded cases: ${result.excludedCaseCount}`,
+  `Regressions: ${result.regressions.length ? result.regressions.join('; ') : 'none'}`,
+].join('\n')