@agentskit/doc-bridge 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 1.11.0
+
+### Minor Changes
+
+- 25f16f3: Say when a committed index could not have come from a clean checkout.
+  
+  A scan walks what is on disk and has no reason to consult `.gitignore`, so a generated module or
+  document silently joins the corpus on a machine that has built and silently leaves it on one that
+  has not. That is harmless while the index is rebuilt on every run. It is a defect the moment the
+  index is committed so a gate can verify it — which is the setup `index-freshness` exists for: two
+  checkouts of the same commit then produce different artifacts, the gate reports staleness that
+  nothing caused, and regenerating cannot fix it because the next machine disagrees in the other
+  direction.
+  
+  Dogfooding found this the expensive way. On a 25-package monorepo the freshness gate passed locally
+  and failed in CI, twice, because `pnpm lint` had generated one `.ts` file into the corpus before the
+  index was written; CI lints a narrower scope and never had the file. Diagnosing it took reading two
+  CI logs and diffing file inventories. Git already knew the answer.
+  
+  `ak-docs index` now names those paths as it writes, and `ak-docs doctor` raises an
+  `index-not-reproducible` warning, each with the ignore rule that matched — for example
+  `apps/docs-next/lib/ask-context.ts (apps/docs-next/.gitignore:13:lib/ask-context.ts)` — so the fix
+  is one lookup away: add the path to `safety.exclude`.
+  
+  Both are unconditional and neither changes an exit code or the doctor's score. Enforcement is the
+  new `index-reproducible` gate, which is in no preset and has to be requested with
+  `gates.include: ['index-reproducible']`, because turning it on for every consumer would fail gates
+  that pass for good reasons.
+  
+  The check reports success rather than failure when the index is not committed or the project is not
+  a Git checkout, since there is nothing to reproduce in either case, and it does not flag a file that
+  is both tracked and matched by an ignore rule — being committed is the point.
+
+## 1.10.1
+
+### Patch Changes
+
+- 0926c57: Keep a committed index fresh across commits.
+  
+  The retrieval projection sealed its content hash over the discovery snapshot's hash, and a
+  snapshot's hash covers its `sourceRevision` — the commit SHA when the working tree is clean, a
+  digest of the scanned files when it is not. That is right for an artifact whose job is to say what
+  one revision looked like, and wrong as a projection input: the projection is a function of what the
+  snapshot observed, not of where it observed it.
+  
+  The consequence only appears in a repository that commits `.doc-bridge/index.json`, which is the
+  recommended setup: committing the index changes the revision that the next run hashes, so the
+  artifact was stale the moment it landed — landing it is a commit. `ak-docs gate run` reported
+  `index-freshness` failing on an index that nothing had invalidated, and no regenerate could fix it,
+  because the fix was itself a commit. Dogfooding on a 25-package monorepo, the gate could not be
+  made to pass twice in a row.
+  
+  The seal is now over what the snapshot observed: the entities, the relations and the analyzer
+  identity that produced them, alongside the overlay and configuration hashes it already covered. The
+  artifact still carries `snapshotHash`, now documented as provenance rather than a seal input, so a
+  reader can still say which snapshot a projection came from. `RETRIEVAL_PROJECTION_VERSION` goes to
+  2, so no reader compares a hash across the change, and every index's content hash changes once on
+  the next `ak-docs index`.
+
 ## 1.10.0
 
 ### Minor Changes

package/action.yml

@@ -20,7 +20,7 @@ inputs:
   package-version:
     description: Exact @agentskit/doc-bridge npm version (kept in sync with this Action release)
     required: false
-    default: '1.10.0'
+    default: '1.11.0'
 
 runs:
   using: composite

package/dist/cli/program.js

@@ -430,6 +430,7 @@ var GatesConfigSchema = z.object({
   include: z.array(
     z.enum([
       "index-freshness",
+      "index-reproducible",
       "human-guide-links",
       "link-rot",
       "okf-type",
@@ -442,6 +443,7 @@ var GatesConfigSchema = z.object({
   exclude: z.array(
     z.enum([
       "index-freshness",
+      "index-reproducible",
       "human-guide-links",
       "link-rot",
       "okf-type",
@@ -3616,8 +3618,13 @@ var RetrievalIndexV1Schema = z5.object({
   schemaVersion: z5.literal(RETRIEVAL_INDEX_SCHEMA_VERSION),
   contentHash: hash2,
   contentHashAlgo: z5.literal("sha256-normalized-v1"),
-  /** The three inputs the projection is a function of. Same three hashes, same projection. */
+  /**
+   * Which snapshot this was projected from. Provenance, not a seal input: it carries the
+   * snapshot's `sourceRevision`, and the projection is a function of what the snapshot observed
+   * rather than of the revision it was observed at.
+   */
   snapshotHash: hash2,
+  /** The inputs the projection is a function of. Same hashes, same projection. */
   overlayHash: hash2,
   configurationHash: hash2,
   lexiconVersion: z5.number().int().nonnegative().max(1e3),
@@ -4055,7 +4062,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.10.0";
+var PACKAGE_VERSION = "1.11.0";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -5633,7 +5640,7 @@ var resolveSearchParams = (configured) => ({
 });
 
 // src/retrieval/project.ts
-var RETRIEVAL_PROJECTION_VERSION = 1;
+var RETRIEVAL_PROJECTION_VERSION = 2;
 var DOCUMENT_BODY_LIMIT = 4e3;
 var MAX_EDGES = 64;
 var MAX_ALIASES = 32;
@@ -5641,6 +5648,12 @@ var MAX_TAGS = 32;
 var MAX_SYMBOLS = 256;
 var MAX_SUMMARY = 400;
 var EMPTY_OVERLAY_HASH = sha256NormalizedV1({ accepted: [] });
+var snapshotObservationHash = (snapshot) => sha256NormalizedV1({
+  pipelineVersion: snapshot.pipelineVersion,
+  analyzerVersions: snapshot.analyzerVersions,
+  entities: snapshot.entities,
+  relations: snapshot.relations
+});
 var CONFIDENCE_RANK = { observed: 0, declared: 1, fuzzy: 2, proposed: 3 };
 var weakerConfidence = (a, b) => CONFIDENCE_RANK[a] >= CONFIDENCE_RANK[b] ? a : b;
 var relationConfidence = (relation) => relation.metadata?.confidence === "fuzzy" ? "fuzzy" : relation.provenance;
@@ -5901,7 +5914,7 @@ var projectRetrievalIndex = (options) => {
   };
   const contentHash = sha256NormalizedV1({
     projectionVersion: RETRIEVAL_PROJECTION_VERSION,
-    snapshotHash: base.snapshotHash,
+    observationHash: snapshotObservationHash(snapshot),
     overlayHash: base.overlayHash,
     configurationHash: base.configurationHash,
     lexiconVersion: base.lexiconVersion,
@@ -8014,6 +8027,50 @@ var loadFreshDocBridgeIndex = (root, config) => {
   return index;
 };
 
+// src/discovery/reproducibility.ts
+import { execFileSync as execFileSync2 } from "child_process";
+var NOT_CHECKED = (skipped) => ({
+  checked: false,
+  skipped,
+  ignored: []
+});
+var git = (root, args, options = {}) => {
+  try {
+    return execFileSync2("git", args, {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+      maxBuffer: 64 * 1024 * 1024,
+      ...options.input === void 0 ? {} : { input: options.input }
+    });
+  } catch (error) {
+    const status = error.status;
+    if (options.allowExit1 && status === 1) return error.stdout ?? "";
+    return void 0;
+  }
+};
+var checkIndexReproducibility = (root, indexPath, paths) => {
+  if (git(root, ["rev-parse", "--is-inside-work-tree"]) === void 0) return NOT_CHECKED("no-git");
+  if (git(root, ["ls-files", "--error-unmatch", "--", indexPath]) === void 0) {
+    return NOT_CHECKED("index-untracked");
+  }
+  if (paths.length === 0) return { checked: true, ignored: [] };
+  const unique3 = [...new Set(paths)].sort();
+  const output = git(root, ["check-ignore", "--verbose", "-z", "--stdin"], {
+    input: `${unique3.join("\0")}\0`,
+    allowExit1: true
+  });
+  if (output === void 0) return NOT_CHECKED("no-git");
+  const fields = output.split("\0");
+  const ignored = [];
+  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) continue;
+    ignored.push({ path, rule: `${source ?? "?"}:${line ?? "?"}:${pattern ?? "?"}` });
+  }
+  return { checked: true, ignored: ignored.sort((left, right) => left.path.localeCompare(right.path)) };
+};
+
 // src/gates/run-gates.ts
 var RESERVED_GATE_IDS = /* @__PURE__ */ new Set(["link-rot", "routing-currency", "bootstrap-size"]);
 var runGate = (root, config, id) => {
@@ -8031,6 +8088,38 @@ var runGate = (root, config, id) => {
   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") {
+    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;
   try {
@@ -9061,7 +9150,7 @@ var draftMemoryPromotion = (classifications) => {
 };
 
 // src/memory/github-pr.ts
-import { execFileSync as execFileSync2, spawnSync } from "child_process";
+import { execFileSync as execFileSync3, spawnSync } from "child_process";
 import { existsSync as existsSync15, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
 import { join as join15 } from "path";
 var run = (cmd, args, cwd) => {
@@ -9188,7 +9277,7 @@ ${auth.out}`
   ];
   let prUrl = "";
   try {
-    prUrl = execFileSync2("gh", prArgs, { cwd: root, encoding: "utf8" }).trim();
+    prUrl = execFileSync3("gh", prArgs, { cwd: root, encoding: "utf8" }).trim();
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return {
@@ -10159,6 +10248,16 @@ var buildIssues = (coverage) => {
       action: "ak-docs index"
     });
   }
+  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",
@@ -10296,7 +10395,12 @@ var runDoctor = (root, config) => {
       message: freshnessMessage,
       hasIndex
     },
-    gates
+    gates,
+    reproducibility: checkIndexReproducibility(
+      root,
+      config.index?.outFile ?? ".doc-bridge/index.json",
+      index.knowledge.map((entry) => entry.path)
+    )
   };
   const issues = buildIssues(coverage);
   const score = computeScore(coverage);
@@ -16972,7 +17076,7 @@ var loadProject = (configPath) => {
   const root = projectRootFromConfigPath(path, config.project?.root);
   return { config, configPath: path, root };
 };
-var indexDiagnostics = (config, result) => {
+var indexDiagnostics = (root, config, result) => {
   const diagnostics = [];
   const onlyDoc = result.index.knowledge.length === 1 ? result.index.knowledge[0] : void 0;
   if (onlyDoc?.path === config.corpus.agent.index) {
@@ -16987,6 +17091,18 @@ var indexDiagnostics = (config, result) => {
       "No ownership handoffs yet. Add routing.options.ownership, package frontmatter (package + editRoot), or a monorepo plugin."
     );
   }
+  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;
 };
 var diagnosticNextCommands = (config, result) => {
@@ -18114,7 +18230,7 @@ var runCli2 = (argv) => {
         });
       }
       const result = buildDocBridgeIndex({ root, config });
-      const diagnostics = indexDiagnostics(config, result);
+      const diagnostics = indexDiagnostics(root, config, result);
       const handoffCount = Object.keys(result.index.handoffs ?? {}).length;
       writeJson2({
         ok: true,