@agentskit/doc-bridge 1.10.1 → 1.11.1

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.11.1
+
+### Patch Changes
+
+- faf29f5: Stop reporting a path an ignore rule rescues as unreproducible.
+  
+  `git check-ignore --verbose` emits a record for every path that *matched* a rule, including the path
+  a `!` negation rescues — and such a path is precisely one Git does not ignore. The reproducibility
+  check read the record without reading the pattern, so `dist/*` plus `!dist/keep.js` reported
+  `dist/keep.js` as a reason the index could not be rebuilt from a clean checkout. The opposite of
+  what the rule says, stated confidently.
+  
+  The window is narrow: `check-ignore` stops reporting a path once it is committed, and a path rescued
+  by a negation is usually committed, which is the point of rescuing it. It shows up while such a path
+  is still untracked — a file added but not yet committed.
+  
+  Found by turning the new `index-reproducible` gate on in this repository, which had to add
+  `!.doc-bridge/index.json` to its own `.gitignore` to commit the index the gate verifies.
+
+## 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

package/README.md

@@ -297,19 +297,23 @@ gates without silently rebuilding them. It rejects non-exact package versions.
 See the [Marketplace guide](docs/MARKETPLACE.md).
 
 The guide is pinned to the published stable Action release `v1.7.45`; the
-checked-in package version is `1.8.0`.
+checked-in package version is `1.11.1`.
 
 Coverage is repository-specific. Run `ak-docs doctor --badge` locally to emit
 current handoff and human-bridge badges, or `pnpm coverage:badge` in CI; this
 README intentionally avoids publishing a stale static percentage.
 
-Or locally:
+Or locally, as two steps rather than one, because they answer different questions:
 
 ```bash
-ak-docs index && ak-docs gate run
+ak-docs index     # after changing docs or config — then review and commit the result
+ak-docs gate run  # verifies the committed index, which is what CI verifies
 ```
 
-Gate fails with `Index is stale. Run: ak-docs index` — same check in CI annotations.
+Chaining them (`index && gate run`) cannot report a stale index: it gates an artifact written a
+second earlier against a rebuild of the same tree. The gate's value is that the committed index
+and the repository agree, so run it the way CI does, against what is committed. It fails with
+`Index is stale. Run: ak-docs index` — the same check, and the same annotation, as in CI.
 
 ## Product surface
 

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.1'
+    default: '1.11.1'
 
 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",
@@ -4060,7 +4062,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.10.1";
+var PACKAGE_VERSION = "1.11.1";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -8025,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 || pattern?.startsWith("!")) 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) => {
@@ -8042,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 {
@@ -9072,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) => {
@@ -9199,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 {
@@ -10170,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",
@@ -10307,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);
@@ -16983,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) {
@@ -16998,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) => {
@@ -18125,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,