@agentskit/doc-bridge 1.9.0 → 1.10.1

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 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
+
+- 97851d0: Let a repository say which directories are not areas.
+  
+  An area is the unit of architecture between a package and a file, derived as the first directory
+  level under a package's source roots. In a monorepo where every package keeps `tests/` and
+  `fixtures/` beside `src/`, that derives one area per directory — and the doctor's connectivity
+  dimension then asks for a document about a folder of test data. Dogfooding on a 26-package
+  monorepo, 43 of its 81 undocumented areas were `tests/` or `fixtures/`: the metric was mostly
+  measuring directories no documentation should describe.
+  
+  `analysis.areas.exclude` takes glob patterns for directories that hold code without being a unit
+  of architecture. A matching candidate is not derived, and its modules fall to the most specific
+  area that still encloses them — or to none, which is the honest answer for a folder of fixtures.
+  An ownership record naming an excluded path still makes it an area: a person saying a directory is
+  a unit outranks a pattern saying it is not.
+  
+  On that monorepo, excluding `**/tests`, `**/fixtures`, `**/__tests__` and `**/__fixtures__` took
+  areas from 103 to 53 and the documented share from 21% to 34%, before a single document was
+  written.
+
 ## 1.9.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.9.0'
+    default: '1.10.1'
 
 runs:
   using: composite

package/dist/cli/program.js

@@ -525,11 +525,20 @@ var AnalysisConfigSchema = z.object({
   /**
    * How code areas are derived — the unit of architecture between a package and a file.
    * `roots` names directories that contain areas rather than being one (`src` holds
-   * `src/query`); `depth` is how many levels below such a root an area sits.
+   * `src/query`); `depth` is how many levels below such a root an area sits; `exclude`
+   * names directories that hold code without being a unit of architecture.
    */
   areas: z.object({
     depth: z.number().int().min(1).max(8).optional(),
-    roots: z.array(z.string().min(1).max(128)).max(32).optional()
+    roots: z.array(z.string().min(1).max(128)).max(32).optional(),
+    /**
+     * Glob patterns for directories that are not areas. A monorepo where every package
+     * keeps `tests/` and `fixtures/` beside `src/` derives one area per directory, and
+     * then connectivity asks for a document about a folder of test data. An ownership
+     * record naming an excluded path still makes it an area: a person saying a directory
+     * is a unit outranks a pattern saying it is not.
+     */
+    exclude: z.array(z.string().min(1).max(256)).max(64).optional()
   }).strict().optional()
 }).strict();
 var WorkflowConfigSchema = z.object({
@@ -2081,6 +2090,9 @@ var areaSuggestionCoverage = (snapshot, options = {}) => {
   }));
 };
 
+// src/discovery/areas.ts
+import { minimatch as minimatch2 } from "minimatch";
+
 // src/discovery/identity.ts
 var MAX_ID_LENGTH = 256;
 var ID_HASH_LENGTH = 32;
@@ -2129,10 +2141,12 @@ var deriveAreas = (options) => {
   const depth = options.depth ?? DEFAULT_AREA_DEPTH;
   const roots = options.roots ?? [...DEFAULT_AREA_ROOTS];
   const ownership = (options.ownership ?? []).map((record) => ({ ...record, path: normalize(record.path) }));
+  const excluded = options.exclude ?? [];
+  const isExcluded2 = (path) => excluded.some((pattern) => minimatch2(path, pattern, { dot: true }));
   const candidates = /* @__PURE__ */ new Map();
   for (const module of options.modules) {
     const path = conventionalAreaPath(module, depth, roots);
-    if (path && !candidates.has(path)) candidates.set(path, module.packageId);
+    if (path && !candidates.has(path) && !isExcluded2(path)) candidates.set(path, module.packageId);
   }
   for (const record of ownership) {
     if (!record.path || candidates.has(record.path)) continue;
@@ -3230,7 +3244,8 @@ var discoverRepository = (opts = {}) => {
     modules: areaModules,
     ownership: Object.entries(opts.config?.routing?.options?.ownership ?? {}).map(([id, record]) => ({ id, path: record.path })),
     ...opts.config?.analysis?.areas?.depth !== void 0 ? { depth: opts.config.analysis.areas.depth } : {},
-    ...opts.config?.analysis?.areas?.roots !== void 0 ? { roots: opts.config.analysis.areas.roots } : {}
+    ...opts.config?.analysis?.areas?.roots !== void 0 ? { roots: opts.config.analysis.areas.roots } : {},
+    ...opts.config?.analysis?.areas?.exclude !== void 0 ? { exclude: opts.config.analysis.areas.exclude } : {}
   });
   const areasById = new Map(areas.map((area) => [area.id, area]));
   const areasByPath = new Map(areas.map((area) => [area.path, area.id]));
@@ -3601,8 +3616,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),
@@ -3614,7 +3634,7 @@ var RetrievalIndexV1Schema = z5.object({
 }).strict();
 
 // src/index-builder/scan-corpus.ts
-import { minimatch as minimatch2 } from "minimatch";
+import { minimatch as minimatch3 } from "minimatch";
 
 // src/lib/markdown.ts
 var parseFrontmatter = (markdown) => {
@@ -3765,8 +3785,8 @@ var configuredPathMatches = (relPath, include, exclude) => {
   const normalize3 = (pattern) => toPosix(pattern).replace(/^\.\//, "");
   const included = include?.filter(Boolean).map(normalize3) ?? [];
   const excluded = exclude?.filter(Boolean).map(normalize3) ?? [];
-  if (excluded.some((pattern) => minimatch2(relPath, pattern, { dot: true }))) return false;
-  return included.length === 0 || included.some((pattern) => minimatch2(relPath, pattern, { dot: true }));
+  if (excluded.some((pattern) => minimatch3(relPath, pattern, { dot: true }))) return false;
+  return included.length === 0 || included.some((pattern) => minimatch3(relPath, pattern, { dot: true }));
 };
 var scanAgentCorpus = (root, config) => {
   const agentRoot = containedProjectPath(root, config.corpus.agent.root);
@@ -4040,7 +4060,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.9.0";
+var PACKAGE_VERSION = "1.10.1";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -4945,14 +4965,14 @@ var nextraAdapter = {
 };
 
 // src/index-builder/human-adapters/plain-markdown.ts
-import { minimatch as minimatch3 } from "minimatch";
+import { minimatch as minimatch4 } from "minimatch";
 var stringPatterns = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : [];
 var matchesConfiguredPath = (relPath, options) => {
   const normalize3 = (pattern) => pattern.replaceAll("\\", "/").replace(/^\.\//, "");
   const include = stringPatterns(options?.include).map(normalize3);
   const exclude = stringPatterns(options?.exclude).map(normalize3);
-  if (exclude.some((pattern) => minimatch3(relPath, pattern, { dot: true }))) return false;
-  return include.length === 0 || include.some((pattern) => minimatch3(relPath, pattern, { dot: true }));
+  if (exclude.some((pattern) => minimatch4(relPath, pattern, { dot: true }))) return false;
+  return include.length === 0 || include.some((pattern) => minimatch4(relPath, pattern, { dot: true }));
 };
 var plainMarkdownAdapter = {
   plugin: "plain-markdown",
@@ -4990,7 +5010,7 @@ var starlightAdapter = {
 };
 
 // src/index-builder/human-adapters/vitepress.ts
-import { minimatch as minimatch4 } from "minimatch";
+import { minimatch as minimatch5 } from "minimatch";
 var isVitePressPage = (relPath) => !relPath.split("/").some((part) => part === ".vitepress" || part.startsWith("."));
 var srcExcludePatterns = (value) => {
   if (value === void 0) return [];
@@ -5004,7 +5024,7 @@ var srcExcludePatterns = (value) => {
     return pattern;
   });
 };
-var isExcluded = (relPath, patterns) => patterns.some((pattern) => minimatch4(relPath, pattern, { dot: true }));
+var isExcluded = (relPath, patterns) => patterns.some((pattern) => minimatch5(relPath, pattern, { dot: true }));
 var vitepressSlug = (relPath, cleanUrls) => {
   const slug2 = routeSlug(relPath);
   if (cleanUrls || /(?:^|\/)index\.mdx?$/.test(relPath)) return slug2;
@@ -5618,7 +5638,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;
@@ -5626,6 +5646,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;
@@ -5886,7 +5912,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,
@@ -8189,7 +8215,7 @@ var resolveGateIds = (config) => {
 };
 
 // src/rules/engine.ts
-import { minimatch as minimatch5 } from "minimatch";
+import { minimatch as minimatch6 } from "minimatch";
 var diagnosticRules = {
   DOCUMENTATION_QUALITY: "documentation-quality",
   RELATION_UNDOCUMENTED: "graph-undocumented-relation",
@@ -8263,7 +8289,7 @@ var evaluateRules = (report, options = {}) => {
       findings.push(criticalFinding(finding, criticalSeverity, matchingEntity));
     }
     for (const path of resolved.criticalPaths) {
-      if (finding.evidence.some((item) => minimatch5(item.path, path, { dot: true })) && !resolved.ignore.has("critical-path-risk") && criticalSeverity !== "off") {
+      if (finding.evidence.some((item) => minimatch6(item.path, path, { dot: true })) && !resolved.ignore.has("critical-path-risk") && criticalSeverity !== "off") {
         findings.push(criticalFinding(finding, criticalSeverity, path));
       }
     }
@@ -13982,7 +14008,7 @@ var formatBenchmarkText = (result) => [
 // src/audit/documentation.ts
 import { readFileSync as readFileSync28 } from "fs";
 import { resolve as resolve25 } from "path";
-import { minimatch as minimatch6 } from "minimatch";
+import { minimatch as minimatch7 } from "minimatch";
 
 // src/render/data.ts
 var MAX_SYMBOLS2 = 12;
@@ -14313,7 +14339,7 @@ var bodyForDuplicate = (content) => {
   const start = lines[0] === "---" ? lines.findIndex((line, index) => index > 0 && line === "---") + 1 : 0;
   return lines.slice(start).join("\n").replace(/\s+/g, " ").trim().toLocaleLowerCase();
 };
-var matches = (path, patterns) => patterns.some((pattern) => minimatch6(path, pattern, { dot: true }));
+var matches = (path, patterns) => patterns.some((pattern) => minimatch7(path, pattern, { dot: true }));
 var rate2 = (count4, total) => total ? count4 / total : null;
 var metadataPresent = (content, key) => {
   const value = parseFrontmatter(content).data[key];