@agentskit/doc-bridge 1.10.0 → 1.11.0

package/dist/index.js

@@ -161,6 +161,7 @@ var GatesConfigSchema = z.object({
   include: z.array(
     z.enum([
       "index-freshness",
+      "index-reproducible",
       "human-guide-links",
       "link-rot",
       "okf-type",
@@ -173,6 +174,7 @@ var GatesConfigSchema = z.object({
   exclude: z.array(
     z.enum([
       "index-freshness",
+      "index-reproducible",
       "human-guide-links",
       "link-rot",
       "okf-type",
@@ -1331,8 +1333,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),
@@ -4393,7 +4400,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) => {
@@ -5973,7 +5980,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;
@@ -5981,6 +5988,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;
@@ -6241,7 +6254,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,
@@ -7070,6 +7083,50 @@ var buildDocBridgeIndex = (opts) => {
   };
 };
 
+// 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/retrieval/rank.ts
 var BM25_SCALE = 50;
 var EXACT_ID = 200;
@@ -11036,6 +11093,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 {
@@ -13279,6 +13368,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",
@@ -13416,7 +13515,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);
@@ -13613,7 +13717,7 @@ var evaluateQualityScorecard = (input) => {
 };
 
 // src/memory/github-pr.ts
-import { execFileSync as execFileSync2, spawnSync } from "child_process";
+import { execFileSync as execFileSync3, spawnSync } from "child_process";
 import { existsSync as existsSync21, mkdirSync as mkdirSync8, writeFileSync as writeFileSync9 } from "fs";
 import { join as join19 } from "path";
 var run = (cmd, args, cwd) => {
@@ -13740,7 +13844,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 {
@@ -17614,6 +17718,7 @@ export {
   canonicality,
   centrality,
   changeDigestView,
+  checkIndexReproducibility,
   checkPublicParity,
   checkStudyExpectations,
   chunksFromMarkdown,
@@ -17882,6 +17987,7 @@ export {
   selectTaskExecutions,
   sha256NormalizedV1,
   singularizeSearchToken,
+  snapshotObservationHash,
   startInkChat,
   startMcpStdioServer,
   studyRetrievalSuite,