@agentskit/doc-bridge 1.10.1 → 1.11.1

package/src/cli/program.ts

@@ -99,6 +99,7 @@ import { independentlyAdjudicateStudyLedger, persistIndependentlyAdjudicatedLedg
 import { formatStudyProviderCliText, parseStudyProviderCliConfig } from '../study/provider-cli.js'
 import { calculateStudyMetrics, formatStudyMetricsText } from '../study/metrics.js'
 import { formatStudyVerificationText, parseStudyVerificationBinding } from '../study/verification.js'
+import { checkIndexReproducibility } from '../discovery/reproducibility.js'
 
 type Command =
   | 'help'
@@ -469,7 +470,11 @@ const loadProject = (configPath?: string) => {
   return { config, configPath: path, root }
 }
 
-const indexDiagnostics = (config: DocBridgeConfigV1, result: ReturnType<typeof buildDocBridgeIndex>): string[] => {
+const indexDiagnostics = (
+  root: string,
+  config: DocBridgeConfigV1,
+  result: ReturnType<typeof buildDocBridgeIndex>,
+): string[] => {
   const diagnostics: string[] = []
   const onlyDoc = result.index.knowledge.length === 1 ? result.index.knowledge[0] : undefined
   if (onlyDoc?.path === config.corpus.agent.index) {
@@ -484,6 +489,22 @@ const indexDiagnostics = (config: DocBridgeConfigV1, result: ReturnType<typeof b
       'No ownership handoffs yet. Add routing.options.ownership, package frontmatter (package + editRoot), or a monorepo plugin.',
     )
   }
+  /*
+   * Said at write time, because this is the moment the unreproducible artifact is created and the
+   * only moment the operator can see what their machine had that another will not.
+   */
+  const reproducibility = checkIndexReproducibility(
+    root,
+    config.index?.outFile ?? '.doc-bridge/index.json',
+    result.index.knowledge.map((entry) => entry.path),
+  )
+  if (reproducibility.ignored.length > 0) {
+    const sample = reproducibility.ignored.slice(0, 5).map((entry) => `${entry.path} (${entry.rule})`)
+    diagnostics.push(
+      `${reproducibility.ignored.length} indexed path(s) are ignored by Git: ${sample.join(', ')}${reproducibility.ignored.length > sample.length ? `, and ${reproducibility.ignored.length - sample.length} more` : ''}.`,
+      'A clean checkout will not have them, so it builds a different index. Add them to safety.exclude in doc-bridge.config.json.',
+    )
+  }
   return diagnostics
 }
 
@@ -1749,7 +1770,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
         })
       }
       const result = buildDocBridgeIndex({ root, config })
-      const diagnostics = indexDiagnostics(config, result)
+      const diagnostics = indexDiagnostics(root, config, result)
       const handoffCount = Object.keys(result.index.handoffs ?? {}).length
       writeJson({
         ok: true,

package/src/config/schema.ts

@@ -122,6 +122,7 @@ export const GatesConfigSchema = z
       .array(
         z.enum([
           'index-freshness',
+          'index-reproducible',
           'human-guide-links',
           'link-rot',
           'okf-type',
@@ -137,6 +138,7 @@ export const GatesConfigSchema = z
       .array(
         z.enum([
           'index-freshness',
+          'index-reproducible',
           'human-guide-links',
           'link-rot',
           'okf-type',

package/src/discovery/reproducibility.ts

@@ -0,0 +1,118 @@
+/**
+ * Whether a committed index could have been produced by a clean checkout.
+ *
+ * The recommended setup commits `.doc-bridge/index.json` so a gate can verify it, and that only
+ * works while the index is a function of committed content. A scan has no reason to know about
+ * `.gitignore` — it walks what is on disk — so a generated module or document silently joins the
+ * corpus on any machine that has built, and silently leaves it on one that has not. The index then
+ * disagrees with itself between two checkouts of the same commit, `index-freshness` reports an
+ * artifact that nothing invalidated, and regenerating cannot fix it because the next machine
+ * disagrees in the other direction.
+ *
+ * Dogfooding found this the expensive way: a 25-package monorepo whose gate passed locally and
+ * failed in CI because `pnpm lint` had generated one `.ts` file into the corpus before the index
+ * was written. The scan cannot guess which files are generated, but Git already knows, so the
+ * check is: of the paths this index carries, which ones does Git ignore?
+ *
+ * It only applies when the index is itself tracked. A consumer who regenerates on every run has
+ * nothing to reproduce, and reporting generated files to them would be noise.
+ */
+
+import { execFileSync } from 'node:child_process'
+
+export type IgnoredIndexEntry = {
+  readonly path: string
+  /** The ignore rule that matched, as `.gitignore:12:pattern`, so the fix is one lookup away. */
+  readonly rule: string
+}
+
+export type IndexReproducibility = {
+  /**
+   * Whether the question was answerable. False outside a Git checkout, when Git is unavailable, or
+   * when the index is not tracked — in all three cases `ignored` is empty and means nothing.
+   */
+  readonly checked: boolean
+  /** Why the check did not run, for a caller that wants to say so. */
+  readonly skipped?: 'no-git' | 'index-untracked'
+  /** Indexed paths that Git ignores, in path order. */
+  readonly ignored: readonly IgnoredIndexEntry[]
+}
+
+const NOT_CHECKED = (skipped: 'no-git' | 'index-untracked'): IndexReproducibility => ({
+  checked: false,
+  skipped,
+  ignored: [],
+})
+
+/**
+ * `undefined` means the command did not answer.
+ *
+ * `allowExit1` is for `check-ignore` alone, which exits 1 when nothing matched — the common answer
+ * rather than a failure, and it still writes whatever did match to stdout. The probes must not
+ * share that tolerance: `ls-files --error-unmatch` exits 1 precisely to say "not tracked", and
+ * reading that as success made the untracked case look checked.
+ */
+const git = (
+  root: string,
+  args: readonly string[],
+  options: { readonly input?: string; readonly allowExit1?: boolean } = {},
+): string | undefined => {
+  try {
+    return execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+      ...(options.input === undefined ? {} : { input: options.input }),
+    })
+  } catch (error) {
+    const status = (error as { status?: number }).status
+    if (options.allowExit1 && status === 1) return (error as { stdout?: string }).stdout ?? ''
+    return undefined
+  }
+}
+
+/**
+ * The paths a committed index carries that Git ignores.
+ *
+ * `git check-ignore` consults the index by default, so a tracked file that also matches an ignore
+ * pattern is correctly reported as not ignored — being committed is the whole point. A test pins
+ * that behaviour rather than trusting it.
+ */
+export const checkIndexReproducibility = (
+  root: string,
+  indexPath: string,
+  paths: readonly string[],
+): IndexReproducibility => {
+  if (git(root, ['rev-parse', '--is-inside-work-tree']) === undefined) return NOT_CHECKED('no-git')
+  if (git(root, ['ls-files', '--error-unmatch', '--', indexPath]) === undefined) {
+    return NOT_CHECKED('index-untracked')
+  }
+  if (paths.length === 0) return { checked: true, ignored: [] }
+
+  const unique = [...new Set(paths)].sort()
+  const output = git(root, ['check-ignore', '--verbose', '-z', '--stdin'], {
+    input: `${unique.join('\0')}\0`,
+    allowExit1: true,
+  })
+  if (output === undefined) return NOT_CHECKED('no-git')
+
+  /*
+   * `-z --verbose` emits four NUL-terminated fields per match: source, line, pattern, path.
+   *
+   * A record is not the same as an answer. `--verbose` also emits the path a `!` rule rescues,
+   * with that negation as the pattern — and such a path is precisely one Git does *not* ignore.
+   * Reading the record without reading the pattern reported it as unreproducible, which is the
+   * opposite of what the rule says. It only shows up while the rescued path is untracked, since
+   * `check-ignore` stops reporting it once it is committed, so the window is narrow and the wrong
+   * answer inside it was confident.
+   */
+  const fields = output.split('\0')
+  const ignored: IgnoredIndexEntry[] = []
+  for (let index = 0; index + 3 < fields.length; index += 4) {
+    const [source, line, pattern, path] = [fields[index], fields[index + 1], fields[index + 2], fields[index + 3]]
+    if (!path || pattern?.startsWith('!')) continue
+    ignored.push({ path, rule: `${source ?? '?'}:${line ?? '?'}:${pattern ?? '?'}` })
+  }
+  return { checked: true, ignored: ignored.sort((left, right) => left.path.localeCompare(right.path)) }
+}

package/src/doctor/run-doctor.ts

@@ -8,6 +8,7 @@ import { buildDocBridgeIndex } from '../index-builder/build-index.js'
 import { scanAgentCorpus } from '../index-builder/scan-corpus.js'
 import { runGates, type GateRunResult } from '../gates/run-gates.js'
 import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
+import { checkIndexReproducibility, type IndexReproducibility } from '../discovery/reproducibility.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
 import type { DiscoverySnapshotV1 } from '../schemas/knowledge.js'
 import { doctorBadgeMetrics, type DoctorBadgeMetrics } from './badge.js'
@@ -104,6 +105,8 @@ export type DoctorCoverage = {
     readonly hasIndex: boolean
   }
   readonly gates: GateRunResult
+  /** Whether a clean checkout would rebuild this index, or whether generated files leak into it. */
+  readonly reproducibility: IndexReproducibility
 }
 
 export type DoctorReport = {
@@ -265,6 +268,22 @@ const buildIssues = (coverage: DoctorCoverage): DoctorIssue[] => {
     })
   }
 
+  /*
+   * A warning, not an error: the index is not wrong, it is unreproducible, and every reader of it
+   * on another machine is the one who finds out. The fix belongs to the repository's
+   * `safety.exclude`, so the message names the rule that matched and lets the operator decide.
+   */
+  const { ignored } = coverage.reproducibility
+  if (ignored.length > 0) {
+    const sample = ignored.slice(0, 5).map((entry) => `${entry.path} (${entry.rule})`)
+    issues.push({
+      severity: 'warn',
+      code: 'index-not-reproducible',
+      message: `${ignored.length} indexed path(s) are ignored by Git, so a clean checkout builds a different index: ${sample.join(', ')}${ignored.length > sample.length ? `, and ${ignored.length - sample.length} more` : ''}.`,
+      action: 'edit doc-bridge.config.json  # add the generated paths to safety.exclude',
+    })
+  }
+
   for (const id of coverage.packages.missingAgentDoc) {
     issues.push({
       severity: 'warn',
@@ -423,6 +442,11 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
       hasIndex,
     },
     gates,
+    reproducibility: checkIndexReproducibility(
+      root,
+      config.index?.outFile ?? '.doc-bridge/index.json',
+      index.knowledge.map((entry) => entry.path),
+    ),
   }
 
   const issues = buildIssues(coverage)

package/src/gates/run-gates.ts

@@ -9,9 +9,11 @@ import { buildDocBridgeIndex } from '../index-builder/build-index.js'
 import { scanAgentCorpus } from '../index-builder/scan-corpus.js'
 import { scanHumanDocRecords } from '../index-builder/human-adapters/index.js'
 import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
+import { checkIndexReproducibility } from '../discovery/reproducibility.js'
 
 export type GateId =
   | 'index-freshness'
+  | 'index-reproducible'
   | 'human-guide-links'
   | 'okf-type'
   | 'docs-style'
@@ -54,6 +56,48 @@ export const runGate = (
   if (id === 'human-guide-links') return runHumanGuideLinksGate(root, config)
   if (id === 'okf-type') return runOkfTypeGate(root, config)
   if (id === 'docs-style') return runDocsStyleGate(root, config)
+  if (id === 'index-reproducible') {
+    /*
+     * Opt-in, and in no preset: a repository that regenerates the index on every run has nothing
+     * to enforce, and turning this on for everyone would fail gates that were passing for good
+     * reasons. `gates.include: ['index-reproducible']` is how a repository that commits the index
+     * says it wants the guarantee enforced rather than merely reported.
+     */
+    let index
+    try {
+      index = loadDocBridgeIndex(root, config)
+    } catch (error) {
+      if (error instanceof IndexNotFoundError) return { id, ok: false, message: error.message }
+      throw error
+    }
+    const result = checkIndexReproducibility(
+      root,
+      config.index?.outFile ?? '.doc-bridge/index.json',
+      index.knowledge.map((entry) => entry.path),
+    )
+    if (!result.checked) {
+      return {
+        id,
+        ok: true,
+        message:
+          result.skipped === 'index-untracked'
+            ? 'Index is not committed, so nothing has to reproduce it'
+            : 'Not a Git checkout; reproducibility was not checked',
+      }
+    }
+    if (result.ignored.length === 0) {
+      return { id, ok: true, message: 'Every indexed path is committed' }
+    }
+    const sample = result.ignored.slice(0, 5).map((entry) => `${entry.path} (${entry.rule})`)
+    return {
+      id,
+      ok: false,
+      message: `${result.ignored.length} indexed path(s) are ignored by Git, so a clean checkout builds a different index. Add them to safety.exclude.`,
+      expected: 'every indexed path is committed',
+      actual: sample.join(', '),
+    }
+  }
+
   if (id !== 'index-freshness') throw new Error(`Unsupported gate "${id}"`)
 
   let current: string

package/src/index.ts

@@ -98,6 +98,11 @@ export {
   repositoryInputs,
   type RepositoryInputsV1,
 } from './index-builder/project-corpus.js'
+export {
+  checkIndexReproducibility,
+  type IgnoredIndexEntry,
+  type IndexReproducibility,
+} from './discovery/reproducibility.js'
 export {
   DOCUMENT_BODY_LIMIT,
   EMPTY_OVERLAY_HASH,

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.10.1'
+export const PACKAGE_VERSION = '1.11.1'