@agentskit/doc-bridge 1.7.44 → 1.7.45

package/src/cli/program.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 
@@ -25,7 +25,7 @@ import { ingestMemoryCandidates } from '../memory/ingest.js'
 import { classifyMemoryCandidates, draftMemoryPromotion } from '../memory/pipeline.js'
 import { promoteMemoryToGithubPr } from '../memory/github-pr.js'
 import { watchDocBridgeIndex } from '../index-builder/watch-index.js'
-import { loadWorkflowManifest, loadWorkflowStepOutput, runWorkflow, type WorkflowExecutionResult } from '../workflow/engine.js'
+import { loadWorkflowStepOutput, runWorkflow, type WorkflowExecutionResult } from '../workflow/engine.js'
 import {
   formatDoctorBadgeJson,
   formatDoctorBadgeMarkdown,
@@ -500,6 +500,7 @@ const reconcileWorkflow = (root: string, config: DocBridgeConfigV1): WorkflowExe
   const report = reconcileKnowledge(snapshot, declared, {
     ...(config.reconciliation?.scope === undefined ? {} : { scope: config.reconciliation.scope }),
     ...(config.reconciliation?.requiredRelationKinds === undefined ? {} : { requiredRelationKinds: config.reconciliation.requiredRelationKinds }),
+    ...(config.reconciliation?.requiredRelationTargets === undefined ? {} : { requiredRelationTargets: config.reconciliation.requiredRelationTargets }),
     ...(config.reconciliation?.includeOrphanedDocuments === undefined ? {} : { includeOrphanedDocuments: config.reconciliation.includeOrphanedDocuments }),
   })
   return runWorkflow(workflowOptions(root, config, snapshot.sourceRevision, 'reconcile', { reconcile: () => report }, { pipelineVersion: snapshot.pipelineVersion, analyzerVersions: snapshot.analyzerVersions }))
@@ -720,10 +721,19 @@ const runSuggestCommand = async (flags: ReadonlySet<string>, configPath: string
 }
 
 const writeIfMissing = (path: string, contents: string): boolean => {
-  if (existsSync(path)) return false
   mkdirSync(dirname(path), { recursive: true })
-  writeFileSync(path, contents, 'utf8')
-  return true
+  try {
+    const fd = openSync(path, 'wx')
+    try {
+      writeFileSync(fd, contents, 'utf8')
+      return true
+    } finally {
+      closeSync(fd)
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false
+    throw error
+  }
 }
 
 const demoOwnership = {

package/src/config/load-config.ts

@@ -79,7 +79,13 @@ const parseConfig = (input: unknown): DocBridgeConfigV1 => {
   if (result.success) return result.data
   throw new Error(
     `Invalid doc-bridge config:\n${result.error.issues.map((issue) =>
-      `  - ${issue.path.join('.') || '(root)'}: ${issue.message}`,
+      `  - ${issue.path.join('.') || '(root)'}: ${
+        issue.code === 'invalid_type' && issue.message.endsWith('received undefined')
+          ? 'Required'
+          : issue.code === 'invalid_value' && 'values' in issue
+            ? 'Invalid enum value'
+            : issue.message
+      }`,
     ).join('\n')}`,
   )
 }

package/src/config/schema.ts

@@ -171,11 +171,11 @@ export const RuleSeveritySchema = z.enum(['off', 'info', 'warn', 'error'])
 export const RulesConfigSchema = z
   .object({
     mode: z.enum(['default', 'recommended', 'strict']).optional(),
-    severity: z.record(RuleIdSchema, RuleSeveritySchema).optional(),
+    severity: z.partialRecord(RuleIdSchema, RuleSeveritySchema).optional(),
     ignore: z.array(RuleIdSchema).max(128).optional(),
     criticalEntities: z.array(z.string().min(1).max(256)).max(128).optional(),
     criticalPaths: z.array(z.string().min(1).max(512)).max(128).optional(),
-    warningThresholds: z.record(RuleIdSchema, z.number().int().min(1).max(100_000)).optional(),
+    warningThresholds: z.partialRecord(RuleIdSchema, z.number().int().min(1).max(100_000)).optional(),
   })
   .strict()
 
@@ -185,6 +185,8 @@ export const ReconciliationConfigSchema = z
     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(),
+    /** Limit missing-declaration findings to relations whose endpoints are internal project entities. */
+    requiredRelationTargets: z.enum(['all', 'internal']).optional(),
     includeOrphanedDocuments: z.boolean().optional(),
   })
   .strict()

package/src/conformance/documentation-standard-v1.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, realpathSync } from 'node:fs'
 import { isAbsolute, relative, resolve, sep } from 'node:path'
 
 import type {
@@ -95,11 +95,10 @@ const fileEvidence = (
       evidence: { path, detail: 'Path escapes the project root.' },
     }
   }
-  if (!existsSync(abs)) {
-    return { exists: false, content: '', evidence: { path, detail: 'File does not exist.' } }
-  }
+  let fd: number | undefined
   try {
-    const stat = statSync(abs)
+    fd = openSync(abs, 'r')
+    const stat = fstatSync(fd)
     if (!stat.isFile()) {
       return { exists: false, content: '', evidence: { path, detail: 'Path is not a regular file.' } }
     }
@@ -120,7 +119,7 @@ const fileEvidence = (
         evidence: { path, detail: `Text evidence exceeds ${MAX_TEXT_EVIDENCE_BYTES} bytes.` },
       }
     }
-    const content = readFileSync(abs, 'utf8')
+    const content = readFileSync(fd, 'utf8')
     return {
       exists: content.trim().length > 0,
       content,
@@ -129,8 +128,15 @@ const fileEvidence = (
         detail: content.trim().length > 0 ? 'File exists and is non-empty.' : 'File is empty.',
       },
     }
-  } catch {
-    return { exists: false, content: '', evidence: { path, detail: 'File is not readable text.' } }
+  } catch (error) {
+    const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined
+    return {
+      exists: false,
+      content: '',
+      evidence: { path, detail: code === 'ENOENT' ? 'File does not exist.' : 'File is not readable text.' },
+    }
+  } finally {
+    if (fd !== undefined) closeSync(fd)
   }
 }
 

package/src/discovery/documentation.ts

@@ -73,6 +73,32 @@ const scalar = (value: string): string => {
   return trimmed
 }
 
+const isFieldName = (value: string): boolean => {
+  if (!/^[A-Za-z]/.test(value)) return false
+  for (const character of value.slice(1)) {
+    if (!/[A-Za-z0-9_-]/.test(character)) return false
+  }
+  return true
+}
+
+const parseIndentedField = (raw: string, indentation: number): { readonly key: string; readonly value: string } | undefined => {
+  const prefix = ' '.repeat(indentation)
+  if (!raw.startsWith(prefix) || raw[indentation] === ' ') return undefined
+  const body = raw.slice(indentation)
+  const separator = body.indexOf(':')
+  if (separator <= 0) return undefined
+  const key = body.slice(0, separator).trim()
+  return isFieldName(key) ? { key, value: body.slice(separator + 1).trim() } : undefined
+}
+
+const parseListItem = (raw: string, indentation: number): string | undefined => {
+  const prefix = `${' '.repeat(indentation)}-`
+  if (!raw.startsWith(prefix)) return undefined
+  const rest = raw.slice(prefix.length)
+  if (rest && !/\s/.test(rest[0] ?? '')) return undefined
+  return rest.trim()
+}
+
 const conventionalPackageReference = (path: string, agentRoot: string): string | undefined => {
   const prefix = `${agentRoot.replace(/\/$/, '')}/`
   if (!path.startsWith(prefix)) return undefined
@@ -208,11 +234,10 @@ const parseBlock = (
       section = undefined
       continue
     }
-    if (/^ {2}[A-Za-z][A-Za-z0-9_-]*\s*:/.test(raw)) {
+    const sectionField = parseIndentedField(raw, 2)
+    if (sectionField) {
       finishRelation()
-      const match = /^ {2}([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(raw)
-      const key = match?.[1]
-      const value = match?.[2] ?? ''
+      const { key, value } = sectionField
       if (key !== 'covers' && key !== 'relations') {
         addDiagnostic(diagnostics, input, 'DOCBRIDGE_FIELD_UNKNOWN', `Unknown docbridge field: ${key ?? '(missing)'}.`, line)
         section = undefined
@@ -229,35 +254,36 @@ const parseBlock = (
       }
       continue
     }
-    if (section === 'covers' && /^ {4}-\s*/.test(raw)) {
-      const value = scalar(raw.replace(/^ {4}-\s*/, ''))
+    const listValue = parseListItem(raw, 4)
+    if (section === 'covers' && listValue !== undefined) {
+      const value = scalar(listValue)
       if (!value) addDiagnostic(diagnostics, input, 'DOCBRIDGE_REFERENCE_MISSING', 'covers entries must not be empty.', line)
       else covers.push({ value, line })
       continue
     }
-    if (section === 'relations' && /^ {4}-\s*/.test(raw)) {
+    if (section === 'relations' && listValue !== undefined) {
       finishRelation()
-      const firstField = /^ {4}-\s*([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(raw)
+      const firstField = parseIndentedField(`    ${listValue}`, 4)
       current = { startLine: line, endLine: line, fields: new Set() }
-      if (firstField?.[1]) {
-        current.fields.add(firstField[1])
-        current[firstField[1] as 'from' | 'to' | 'kind' | 'detection'] = scalar(firstField[2] ?? '')
-      } else if (raw.replace(/^ {4}-\s*/, '').trim()) {
+      if (firstField?.key) {
+        current.fields.add(firstField.key)
+        current[firstField.key as 'from' | 'to' | 'kind' | 'detection'] = scalar(firstField.value)
+      } else if (listValue) {
         addDiagnostic(diagnostics, input, 'DOCBRIDGE_RELATION_INVALID', 'Relation entries must be field mappings.', line)
       }
       continue
     }
-    if (section === 'relations' && current && /^ {6}[A-Za-z][A-Za-z0-9_-]*\s*:/.test(raw)) {
-      const field = /^ {6}([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(raw)
-      const key = field?.[1]
+    const field = parseIndentedField(raw, 6)
+    if (section === 'relations' && current && field) {
+      const { key, value } = field
       current.endLine = line
-      if (!key || !['from', 'to', 'kind', 'detection'].includes(key)) {
-        addDiagnostic(diagnostics, input, 'DOCBRIDGE_FIELD_UNKNOWN', `Unknown relation field: ${key ?? '(missing)'}.`, line)
+      if (!['from', 'to', 'kind', 'detection'].includes(key)) {
+        addDiagnostic(diagnostics, input, 'DOCBRIDGE_FIELD_UNKNOWN', `Unknown relation field: ${key}.`, line)
       } else if (current.fields.has(key)) {
         addDiagnostic(diagnostics, input, 'DOCBRIDGE_FIELD_DUPLICATE', `Duplicate relation field: ${key}.`, line)
       } else {
         current.fields.add(key)
-        current[key as 'from' | 'to' | 'kind' | 'detection'] = scalar(field?.[2] ?? '')
+        current[key as 'from' | 'to' | 'kind' | 'detection'] = scalar(value)
       }
       continue
     }

package/src/discovery/repository.ts

@@ -102,6 +102,7 @@ const firstLineContaining = (text: string, pattern: string): number | undefined
 
 const documentClassification = (path: string): string => {
   if (/(^|\/)docs\/for-agents(?:\/|$)/.test(path)) return 'agent'
+  if (/(^|\/)docs-archive(?:\/|$)/.test(path)) return 'archive'
   if (/(^|\/)docs(?:\/|$)/.test(path)) return 'human'
   if (/(^|\/)(README|CONTRIBUTING|SECURITY|CHANGELOG)(?:\.|$)/i.test(path)) return 'project'
   return 'unclassified'
@@ -273,22 +274,64 @@ const moduleReferences = (
   path: string,
   sourceFile: ts.SourceFile,
   runtimeWiringMethods: ReadonlySet<string>,
-): { readonly references: readonly ImportReference[]; readonly exports: readonly string[]; readonly hasDynamic: boolean; readonly hasLiteralDynamic: boolean; readonly hasRuntimeWiring: boolean; readonly hasUnresolvedRuntimeWiring: boolean } => {
+): { readonly references: readonly ImportReference[]; readonly exports: readonly string[]; readonly dynamicEvidence: readonly Evidence[]; readonly hasDynamic: boolean; readonly hasLiteralDynamic: boolean; readonly hasRuntimeWiring: boolean; readonly hasUnresolvedRuntimeWiring: boolean } => {
   const references: ImportReference[] = []
+  const dynamicEvidence: Evidence[] = []
   let hasDynamic = false
   let hasLiteralDynamic = false
   let hasRuntimeWiring = false
   let hasUnresolvedRuntimeWiring = false
   const importedBindings = new Map<string, string>()
   const staticStringBindings = new Map<string, string | undefined>()
+  const localBindings = new Set<string>()
+  const resolveStaticString = (expression: ts.Expression): string | undefined => {
+    if (ts.isStringLiteralLike(expression)) return expression.text
+    if (ts.isIdentifier(expression)) return staticStringBindings.get(expression.text)
+    if (ts.isParenthesizedExpression(expression)) return resolveStaticString(expression.expression)
+    if (ts.isBinaryExpression(expression) && expression.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+      const left = resolveStaticString(expression.left)
+      const right = resolveStaticString(expression.right)
+      return left !== undefined && right !== undefined ? left + right : undefined
+    }
+    return 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) {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isVariableDeclarationList(node.parent) && (node.parent.flags & ts.NodeFlags.Const) !== 0) {
+      const value = resolveStaticString(node.initializer)
       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)
+      staticStringBindings.set(node.name.text, !staticStringBindings.has(node.name.text) || previous === value ? value : undefined)
     }
+    if (
+      (ts.isVariableDeclaration(node) || ts.isParameter(node) || ts.isBindingElement(node)) &&
+      ts.isIdentifier(node.name)
+    ) localBindings.add(node.name.text)
+    if (
+      (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isEnumDeclaration(node)) &&
+      node.name
+    ) localBindings.add(node.name.text)
     ts.forEachChild(node, collectStaticStringBindings)
   }
   collectStaticStringBindings(sourceFile)
+  const addImportedBindingReference = (expression: ts.Expression, node: ts.Node): boolean => {
+    if (ts.isIdentifier(expression)) {
+      const specifier = importedBindings.get(expression.text)
+      if (specifier) {
+        addReference({ text: specifier } as ts.StringLiteralLike, 'runtime-wiring', node, 'runtime-wiring-static')
+        return true
+      }
+      return false
+    }
+    if (ts.isPropertyAccessExpression(expression)) return addImportedBindingReference(expression.expression, node)
+    if (ts.isCallExpression(expression)) return addImportedBindingReference(expression.expression, node)
+    return false
+  }
+  const isKnownLocal = (expression: ts.Expression): boolean => {
+    if (ts.isIdentifier(expression)) return localBindings.has(expression.text) || importedBindings.has(expression.text)
+    if (expression.kind === ts.SyntaxKind.ThisKeyword) return true
+    if (ts.isPropertyAccessExpression(expression)) return isKnownLocal(expression.expression)
+    if (ts.isCallExpression(expression)) return isKnownLocal(expression.expression)
+    return ts.isStringLiteralLike(expression)
+  }
   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 } : {}) })
   }
@@ -309,32 +352,35 @@ const moduleReferences = (
       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])) {
-          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)) {
+        const specifier = node.arguments[0] ? resolveStaticString(node.arguments[0]) : undefined
+        if (specifier !== undefined) {
           hasLiteralDynamic = true
-          addReference({ text: staticStringBindings.get(node.arguments[0].text)! } as ts.StringLiteralLike, 'imports', node, 'dynamic-literal')
-        } else hasDynamic = true
+          dynamicEvidence.push(nodeEvidence(root, path, sourceFile, node))
+          addReference({ text: specifier } as ts.StringLiteralLike, 'imports', node, 'dynamic-literal')
+        } else {
+          hasDynamic = true
+          dynamicEvidence.push(nodeEvidence(root, path, sourceFile, node))
+        }
       } 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
+        const specifier = argument ? resolveStaticString(argument) : undefined
+        if (specifier !== undefined) {
+          dynamicEvidence.push(nodeEvidence(root, path, sourceFile, node))
+          addReference({ text: specifier } as ts.StringLiteralLike, 'imports', node)
+        } else {
+          hasDynamic = true
+          dynamicEvidence.push(nodeEvidence(root, path, sourceFile, node))
+        }
       } else if (ts.isPropertyAccessExpression(node.expression) && runtimeWiringMethods.has(node.expression.name.text)) {
         hasRuntimeWiring = true
-        const before = references.length
-        let hasPotentialTargetArgument = false
+        let hasUnresolvedTarget = 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 (ts.isStringLiteralLike(argument)) continue
+          if (addImportedBindingReference(argument, node)) continue
+          if (!isKnownLocal(argument)) hasUnresolvedTarget = true
         }
-        if (hasPotentialTargetArgument && references.length === before) hasUnresolvedRuntimeWiring = true
+        const receiver = node.expression.expression
+        if (hasUnresolvedTarget && !isKnownLocal(receiver)) hasUnresolvedRuntimeWiring = true
       }
     }
     ts.forEachChild(node, visit)
@@ -343,6 +389,7 @@ const moduleReferences = (
   return {
     references,
     exports: exportedNames(sourceFile),
+    dynamicEvidence,
     hasDynamic,
     hasLiteralDynamic,
     hasRuntimeWiring,
@@ -445,11 +492,11 @@ const artifact = (root: string, config: DocBridgeConfigV1 | undefined, files: re
     sourceRevision: revision.value,
     sourceRevisionKind: revision.kind,
     configurationHash: sha256NormalizedV1(config ?? {}),
-    pipelineVersion: '1.0.0',
-    analyzerVersions: { repository: '1.0.0', 'js-ts': '1.3.0' },
+    pipelineVersion: '1.1.8',
+    analyzerVersions: { repository: '1.1.1', 'js-ts': '1.3.4' },
     entities: [...entities].sort((a, b) => a.id.localeCompare(b.id)),
     relations: [...relations].sort((a, b) => a.id.localeCompare(b.id)),
-    coverage: coverage.map((entry) => ({ ...entry, analyzerVersion: entry.analyzerVersion ?? ({ repository: '1.0.0', 'js-ts': '1.3.0' }[entry.analyzer] ?? '1.0.0') })),
+    coverage: coverage.map((entry) => ({ ...entry, analyzerVersion: entry.analyzerVersion ?? ({ repository: '1.1.1', 'js-ts': '1.3.4' }[entry.analyzer] ?? '1.0.0') })),
   }
   return DiscoverySnapshotV1Schema.parse({ ...base, contentHash: contentHashForArtifactV1(base) })
 }
@@ -552,6 +599,7 @@ export const discoverRepository = (opts: DiscoveryOptions = {}): DiscoverySnapsh
   const includeTestRuntimeWiring = opts.config?.analysis?.jsTs?.includeTestRuntimeWiring ?? false
   let observedLiteralDynamic = false
   let observedUnresolvedDynamic = false
+  const observedDynamicEvidence: Evidence[] = []
   let observedRuntimeWiring = false
   let observedUnresolvedRuntimeWiring = false
   for (const module of modules.values()) {
@@ -561,6 +609,7 @@ export const discoverRepository = (opts: DiscoveryOptions = {}): DiscoverySnapsh
     const references = moduleReferences(root, module.absPath, sourceFile, runtimeWiringMethods)
     observedLiteralDynamic ||= references.hasLiteralDynamic
     observedUnresolvedDynamic ||= references.hasDynamic
+    observedDynamicEvidence.push(...references.dynamicEvidence)
     observedRuntimeWiring ||= references.hasRuntimeWiring
     observedUnresolvedRuntimeWiring ||= references.hasUnresolvedRuntimeWiring
     for (const reference of references.references) {
@@ -572,14 +621,14 @@ export const discoverRepository = (opts: DiscoveryOptions = {}): DiscoverySnapsh
       }
       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.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.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: [...references.dynamicEvidence.slice(0, 32)] })
     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.' }
+    ? { analyzer: 'js-ts', scope: 'dynamic-imports', status: 'partial', reason: 'Literal dynamic imports are resolved; non-literal import expressions and require calls remain unresolved. Evidence lists representative dynamic loading sites.', evidence: [...observedDynamicEvidence.slice(0, 32)] }
     : 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: 'complete', reason: 'All observed dynamic imports used literal targets and were resolved.', evidence: [...observedDynamicEvidence.slice(0, 32)] }
       : { 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

package/src/doctor/run-doctor.ts

@@ -52,17 +52,6 @@ const gradeForScore = (score: number): DoctorReport['grade'] => {
   return 'F'
 }
 
-const agentDocPaths = (index: DocBridgeIndexV1): Set<string> => {
-  const paths = new Set<string>()
-  for (const owner of Object.values(index.lookup?.ownership ?? {})) {
-    if (owner.agentDoc) paths.add(owner.agentDoc)
-  }
-  for (const handoff of Object.values(index.handoffs ?? {})) {
-    if (handoff.startHere) paths.add(handoff.startHere)
-  }
-  return paths
-}
-
 const computeScore = (coverage: DoctorCoverage): number => {
   let score = 0
 
@@ -166,7 +155,7 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
   let index: DocBridgeIndexV1 | undefined
   let hasIndex = true
   let freshnessOk = false
-  let freshnessMessage = 'Index is fresh'
+  let freshnessMessage: string
 
   try {
     index = loadDocBridgeIndex(root, config)
@@ -191,8 +180,6 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
   const missingHumanDoc = ownership.filter(([, owner]) => !owner.humanDoc).map(([id]) => id)
 
   const indexedPaths = new Set(index.knowledge.map((entry) => entry.path))
-  const expectedAgentDocs = agentDocPaths(index)
-  const unindexed = [...expectedAgentDocs].filter((path) => !indexedPaths.has(path))
 
   const corpusDocs = scanAgentCorpus(root, config).filter(
     (doc) => doc.path !== config.corpus.agent.index,
@@ -283,4 +270,4 @@ export const formatDoctorText = (report: DoctorReport): string[] => {
 
   lines.push('', 'Next actions', ...report.nextActions.map((action) => `  → ${action}`))
   return lines
-}
+}

package/src/federation/llms.ts

@@ -31,13 +31,25 @@ const defaultFetchText: FetchText = async (url) => {
   return res.text()
 }
 
+const httpUrl = (value: string): string | undefined => {
+  try {
+    const parsed = new URL(value)
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return undefined
+    if (parsed.username || parsed.password) return undefined
+    return parsed.href
+  } catch {
+    return undefined
+  }
+}
+
 const sourceText = async (
   root: string,
   source: string,
   fetchText: FetchText,
 ): Promise<string | null> => {
   try {
-    if (/^https?:\/\//.test(source)) return await fetchText(source)
+    const remote = httpUrl(source)
+    if (remote) return await fetchText(remote)
     const path = resolve(root, source)
     if (!existsSync(path)) return null
     return readFileSync(path, 'utf8')
@@ -52,34 +64,72 @@ const sameOrigin = (base: string, target: string): boolean => {
 }
 
 export const parseLlmsTxtLinks = (raw: string): { title: string; url: string; description?: string }[] => {
-  const links = [...raw.matchAll(/\[([^\]]+)\]\(([^)]+)\)(?::\s*([^\n]+))?/g)].map((match) => ({
-    title: match[1] ?? match[2] ?? 'link',
-    url: match[2] ?? '',
-    ...(match[3]?.trim() ? { description: match[3].trim() } : {}),
-  })).filter((link) => link.url)
-
-  for (const match of raw.matchAll(/(?:^|\s)(?:Raw|llms\.txt|Full bundle|ZIP bundle)?:?\s*(https?:\/\/\S+)/gi)) {
-    const url = match[1]?.replace(/[),.;]+$/, '')
-    if (url && !links.some((link) => link.url === url)) links.push({ title: slugFromPath(url), url })
+  const links: { title: string; url: string; description?: string }[] = []
+  for (const line of raw.split(/\r?\n/)) {
+    let cursor = 0
+    while (cursor < line.length) {
+      const open = line.indexOf('[', cursor)
+      if (open < 0) break
+      const titleEnd = line.indexOf(']', open + 1)
+      const urlStart = titleEnd < 0 ? -1 : line.indexOf('(', titleEnd + 1)
+      const urlEnd = urlStart < 0 ? -1 : line.indexOf(')', urlStart + 1)
+      if (titleEnd < 0 || urlStart !== titleEnd + 1 || urlEnd < 0) {
+        cursor = open + 1
+        continue
+      }
+      const title = line.slice(open + 1, titleEnd).trim()
+      const url = line.slice(urlStart + 1, urlEnd).trim()
+      const description = line.slice(urlEnd + 1).trim().replace(/^:\s*/, '')
+      if (url) links.push({ title: title || url, url, ...(description ? { description } : {}) })
+      cursor = urlEnd + 1
+    }
+
+    for (const token of line.split(/\s+/)) {
+      let end = token.length
+      while (end > 0 && '),.;:'.includes(token[end - 1] ?? '')) end -= 1
+      const url = token.slice(0, end)
+      if (!/^https?:\/\//i.test(url) || links.some((link) => link.url === url)) continue
+      links.push({ title: slugFromPath(url), url })
+    }
   }
   return links
 }
 
+const firstMatchingLine = (section: string, predicate: (line: string) => boolean): string | undefined =>
+  section.split(/\r?\n/).find((line) => predicate(line.trim()))?.trim()
+
+const sectionTitle = (section: string, sourceUrl: string): string => {
+  const titleLine = firstMatchingLine(section, (line) => line.startsWith('title:'))
+  if (titleLine) return titleLine.slice('title:'.length).trim()
+  const urlLine = firstMatchingLine(section, (line) => /^https?:\/\//i.test(line))
+  if (urlLine) {
+    try {
+      return new URL(urlLine).pathname.split('/').filter(Boolean).at(-1) ?? slugFromPath(sourceUrl)
+    } catch {
+      return slugFromPath(sourceUrl)
+    }
+  }
+  const heading = firstMatchingLine(section, (line) => line.startsWith('#'))
+  if (heading) return heading.replace(/^#+\s*/, '').trim()
+  return slugFromPath(sourceUrl)
+}
+
 export const chunksFromMarkdown = (
   property: string,
   raw: string,
   sourceUrl: string,
 ): DocBridgeRetrievedChunk[] => {
-  const searchable = raw.includes('\n==== ') ? raw : raw.replace(/^---\n[\s\S]*?\n---\n?/, '')
+  const frontmatterEnd = raw.startsWith('---\n') ? raw.indexOf('\n---', 4) : -1
+  const searchable = raw.includes('\n==== ')
+    ? raw
+    : frontmatterEnd >= 0
+      ? raw.slice(frontmatterEnd + '\n---'.length).replace(/^\n/, '')
+      : raw
   const sections = searchable.includes('\n==== ')
     ? searchable.split(/\n====\s+/).filter((section) => section.trim())
     : searchable.split(/\n(?=##?\s+)/)
   return sections.map((section, index) => {
-    const title =
-      /^title:\s*(.+)$/m.exec(section)?.[1]?.trim() ??
-      /^https?:\/\/\S+\/([^/\s]+)$/m.exec(section)?.[1]?.trim() ??
-      /^#+\s+(.+)$/m.exec(section)?.[1]?.trim() ??
-      slugFromPath(sourceUrl)
+    const title = sectionTitle(section, sourceUrl)
     const id = slugFromPath(title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')) || `${index}`
     return {
       chunkKey: `${property}:federated:${id}`,
@@ -112,10 +162,12 @@ export const loadFederatedChunks = async (
     chunks.push(...chunksFromMarkdown(source.id, llms, source.llmsTxt))
     const links = parseLlmsTxtLinks(llms)
     for (const link of links) {
-      const url = !/^https?:\/\//.test(link.url) && source.rawBaseUrl
-        ? `${source.rawBaseUrl.replace(/\/$/, '')}/${link.url.replace(/^\//, '')}`
-        : link.url
-      if (!/\.(md|txt)(?:$|\?)/.test(url)) continue
+      const linkUrl = httpUrl(link.url)
+      const baseUrl = source.rawBaseUrl ? httpUrl(source.rawBaseUrl) : undefined
+      const url = linkUrl ?? (baseUrl ? new URL(link.url, baseUrl).href : link.url)
+      let pathname = url
+      try { pathname = new URL(url).pathname } catch { /* local source */ }
+      if (!/\.(md|txt)$/i.test(pathname)) continue
       if (!sameOrigin(source.llmsTxt, url)) continue
       const raw = await sourceText(root, url, fetchText)
       if (raw) chunks.push(...chunksFromMarkdown(source.id, raw, url))

package/src/fixes/proposals.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path'
 
 import { contentHashForArtifactV1, sha256NormalizedV1 } from '../index-builder/content-hash.js'
@@ -99,8 +99,9 @@ export const createArtifactNormalizationProposal = (root: string, artifactPath:
   const projectRoot = realpathSync.native(resolve(root))
   const path = artifactPath.split(sep).join('/')
   const absolute = containedPath(projectRoot, path)
-  if (!absolute || !existsSync(absolute) || !statSync(absolute).isFile()) return undefined
-  const before = readFileSync(absolute, 'utf8')
+  if (!absolute) return undefined
+  let before: string
+  try { before = readFileSync(absolute, 'utf8') } catch { return undefined }
   let after: string
   try { after = `${JSON.stringify(sortJson(JSON.parse(before) as unknown), null, 2)}\n` } catch { return undefined }
   return after === before ? undefined : makeProposal(projectRoot, options, [{ path: relative(projectRoot, absolute).split(sep).join('/'), before, after }], ['The artifact contains valid JSON.'], ['The artifact is valid canonical JSON with one trailing newline.'])

package/src/index-builder/human-adapters/fumadocs.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { join } from 'node:path'
 
 import { optionString, scanMarkdownDocs, type HumanAdapter } from './core.js'
 

package/src/index-builder/watch-index.ts

@@ -1,5 +1,5 @@
 import { existsSync, watch } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { dirname, resolve } from 'node:path'
 
 import type { DocBridgeConfigV1 } from '../config/schema.js'
 import { buildDocBridgeIndex } from './build-index.js'