agent-doc-system 1.1.0 → 1.3.0

package/core/impact.mjs

@@ -3,8 +3,14 @@
 // When an agent edits a file, the question is not "what does this file do" but
 // "what must I keep consistent, and which gate proves it". This answers that
 // from the graph alone, so the answer is available before any exploration.
-import path from "node:path";
 import { ContextIndex } from "./query.mjs";
+import { dependentScope, verificationForChange } from "./dependents.mjs";
+import { canonicalPath, ownsPath } from "./paths.mjs";
+
+// Changed paths are compared in the graph's canonical form (git's: no "./").
+// A path that is not repository-relative is kept verbatim so it is reported
+// as unmatched rather than silently rewritten.
+const canonical = (p) => canonicalPath(p) ?? p;
 
 // The affected-file classification is derived from the compiled graph, not from
 // a hand-written list of technology filenames. A list would go stale for every
@@ -26,7 +32,7 @@ function classify(graph, p, idx) {
     for (const x of d.runbooks || []) if (x === p) return "documentation";
   }
   if (/\.(md|mdx|adoc|rst|txt)$/.test(p)) return "documentation";
-  if (/(^|\/)migrations?\//.test(p)) return "resource";
+  if (/(^|\/)(migrations?|alembic\/versions)\//.test(p)) return "resource";
   // A Resource named directly — by ref, or by the descriptor file that declares
   // it — is a resource change. Without this, `impact resource:default/x` reported
   // nothing at all, and a change to a dataset's owner was invisible. The loop
@@ -44,7 +50,7 @@ export function impact(graph, changedPaths) {
   const idx = new ContextIndex(graph);
   const affectedComponents = new Map(); // ref -> Set(reason)
   const add = (ref, reason) => {
-    if (!idx.byRef.has(ref)) return;
+    if (idx.byRef.get(ref)?.kind !== "Component") return;
     if (!affectedComponents.has(ref)) affectedComponents.set(ref, new Set());
     affectedComponents.get(ref).add(reason);
   };
@@ -56,9 +62,10 @@ export function impact(graph, changedPaths) {
   const dependencyPaths = new Set();
   const catalogPaths = new Set();
   const unmatched = [];
+  const matchedVerification = new Set();
 
   for (const raw of changedPaths) {
-    const p = raw.replace(/^\.\//, "");
+    const p = canonical(raw);
     const entity = idx.resolve(p);
     // A Resource is not a component. Adding it to `affectedComponents` put a
     // `resource:` ref in a list an agent reads as "components you must check",
@@ -68,11 +75,35 @@ export function impact(graph, changedPaths) {
     const kind = classify(graph, p, idx);
     if (kind === "contract") contracts.add(p);
     if (kind === "documentation") docs.add(p);
-    if (kind === "resource") resources.add(p);
+    if (kind === "resource") {
+      resources.add(entity?.kind === "Resource" ? entity.ref : p);
+      // Migration authority is not ownership. Only follow an existing binding
+      // from the component containing this migration to a logical database.
+      if (entity?.kind === "Component") {
+        for (const rel of graph.relations) {
+          const bound = rel.type === "usesResource" && rel.sourceRef === entity.ref ? rel.targetRef
+            : rel.type === "resourceUsedBy" && rel.targetRef === entity.ref ? rel.sourceRef : null;
+          if (idx.byRef.get(bound)?.entity.spec.type === "logical-database") resources.add(bound);
+        }
+      }
+    }
     if (kind === "verification") verificationPaths.add(p);
     if (kind === "input") dependencyPaths.add(p);
-    if (p.startsWith("agentdoc/")) catalogPaths.add(p);
+    if (ownsPath("agentdoc", p)) catalogPaths.add(p);
+  }
+
+  // A check's configuration is evidence of the components it covers, even
+  // when the file lives outside every component root (for example CI). Add
+  // these before taking the seeds so their dependents' checks follow too.
+  for (const v of graph.verification) {
+    for (const p of verificationPaths) {
+      if (!v.configPaths?.includes(p)) continue;
+      matchedVerification.add(p);
+      for (const ref of v.componentRefs) add(ref, "verification configuration " + p + " changed");
+    }
   }
+  const gates = graph.gates.filter((g) => g.configPaths?.some((p) => verificationPaths.has(p)));
+  for (const g of gates) for (const p of g.configPaths) if (verificationPaths.has(p)) matchedVerification.add(p);
 
   // A contract change reaches its provider and every consumer.
   for (const c of contracts) {
@@ -84,36 +115,6 @@ export function impact(graph, changedPaths) {
     }
   }
 
-  // Changing a component reaches the components that depend on it, and the
-  // components it schedules or is scheduled by. Two hops: a direct dependent
-  // and a dependent-of-a-dependent is the practical blast radius; beyond that
-  // the graph stops being a routing aid and becomes a dump.
-  for (const start of [...affectedComponents.keys()]) {
-    for (let hop = 0; hop < 2; hop++) {
-      for (const r of graph.relations) {
-        if (r.type === "buildDependencyOf" || r.type === "testDependencyOf" || r.type === "buildDependsOn" || r.type === "testDependsOn") {
-          if (r.targetRef === start) add(r.sourceRef, "depends on a changed component");
-          if (r.sourceRef === start) add(r.targetRef, "a dependent of a changed component");
-        }
-        if (r.type === "schedules" || r.type === "scheduledBy" || r.type === "runtimeCalls" || r.type === "runtimeCalledBy") {
-          if (r.sourceRef === start) add(r.targetRef, "connected to a changed component by " + r.type);
-          if (r.targetRef === start) add(r.sourceRef, "connected to a changed component by " + r.type);
-        }
-      }
-    }
-  }
-
-  // A dependency manifest change reaches both directions of the edge.
-  for (const d of dependencyPaths) {
-    for (const r of graph.relations) {
-      if (r.type !== "buildDependsOn" && r.type !== "testDependsOn") continue;
-      if (r.attributes?.package === path.basename(d)) {
-        add(r.sourceRef, "dependency manifest " + d + " changed");
-        add(r.targetRef, "depended on by a component whose manifest changed");
-      }
-    }
-  }
-
   // A documentation change reaches the component that owns it.
   for (const d of docs) {
     for (const e of graph.entities) {
@@ -125,43 +126,59 @@ export function impact(graph, changedPaths) {
     }
   }
 
-  // A resource change reaches every component bound to it. Matched on the full
-  // ref or on a path that lies under the Resource's own source root, so a
-  // Resource ref and its migration directory both reach the same components.
+  // A resource change reaches every component bound to that exact Resource.
+  // Never match a name as a substring of a migration path.
   for (const r of resources) {
-    const refMatch = r.match(/^[a-z]+:[^/]+\/(.+)$/);
-    const refName = refMatch ? refMatch[1] : null;
     for (const rel of graph.relations) {
       if (rel.type !== "usesResource" && rel.type !== "resourceUsedBy") continue;
       const bound = rel.type === "usesResource" ? rel.targetRef : rel.sourceRef;
       const user = rel.type === "usesResource" ? rel.sourceRef : rel.targetRef;
-      const name = bound.split("/").slice(1).join("/");
-      if ((refName && name === refName) || r.includes(name)) {
+      if (r === bound) {
         add(user, "resource change touches " + bound);
       }
     }
   }
 
+  // Preserve the existing direct runtime/schedule context, then follow only
+  // reverse build/test edges. Dependencies remain context in query's explicitly
+  // typed relations; they are never affected components just for being inputs.
+  const directlyAffected = [...affectedComponents.keys()];
+  for (const start of directlyAffected) {
+    for (const r of graph.relations) {
+      if (r.type === "schedules" || r.type === "scheduledBy" || r.type === "runtimeCalls" || r.type === "runtimeCalledBy") {
+        if (r.sourceRef === start) add(r.targetRef, "connected to a changed component by " + r.type);
+        if (r.targetRef === start) add(r.sourceRef, "connected to a changed component by " + r.type);
+      }
+    }
+  }
+  const seeds = [...affectedComponents.keys()];
+  for (const ref of dependentScope(graph, seeds).keys()) {
+    if (!affectedComponents.has(ref)) add(ref, "depends on a changed component");
+  }
+
   const refs = [...affectedComponents.keys()].sort();
-  const verification = graph.verification.filter((v) => v.componentRefs.some((r) => refs.includes(r)));
+  const verification = verificationForChange(graph, seeds, directlyAffected);
   const conflicts = graph.conflicts.filter((c) => refs.includes(c.subject));
   const journeys = graph.journeys.filter((j) => j.components.some((r) => refs.includes(r)));
 
   return {
     changedFiles: changedPaths.slice().sort(),
-    unmatchedFiles: unmatched.sort(),
+    unmatchedFiles: unmatched.filter((p) => !matchedVerification.has(p)).sort(),
     affectedComponents: refs.map((ref) => ({ ref, reasons: [...affectedComponents.get(ref)].sort() })),
     affectedContracts: [...contracts].sort(),
     affectedDocs: [...docs].sort(),
     affectedResources: [...resources].sort(),
     affectedInputs: [...dependencyPaths].sort(),
     affectedVerification: [...verificationPaths].sort(),
+    affectedGates: gates.map((v) => ({ id: v.id, tier: v.tier, command: v.command })),
     affectedCatalog: [...catalogPaths].sort(),
     catalogSourceChanged: catalogPaths.size > 0,
     // Any file the compiler read is a graph input: changing it invalidates the
     // committed graph even when no descriptor changed.
     graphWillBeStale: graphAffected(graph, changedPaths),
-    recommendedVerification: verification.map((v) => ({ id: v.id, tier: v.tier, command: v.command })).slice(0, 25),
+    recommendedVerification: [...verification, ...gates].map((v) => ({ id: v.id, tier: v.tier, command: v.command })).slice(0, 25),
+    recommendedVerificationTotal: verification.length + gates.length,
+    recommendedVerificationTruncated: verification.length + gates.length > 25,
     openConflicts: conflicts.map((c) => ({ id: c.id, subject: c.subject, key: c.key, status: c.status, kind: c.kind })),
     relatedJourneys: journeys.map((j) => ({ id: j.id, description: j.description })),
   };
@@ -169,7 +186,8 @@ export function impact(graph, changedPaths) {
 
 function graphAffected(graph, changedPaths) {
   const inputs = new Set(graph.provenance.map((p) => p.path));
-  for (const p of changedPaths) if (inputs.has(p)) return true;
+  const paths = changedPaths.map(canonical);
+  for (const p of paths) if (inputs.has(p)) return true;
   const idx = new ContextIndex(graph);
-  return changedPaths.some((p) => idx.resolve(p));
+  return paths.some((p) => idx.resolve(p));
 }

package/core/paths.mjs

@@ -0,0 +1,71 @@
+// Repository-relative path semantics, in one place.
+//
+// Every path the catalog stores or matches is in one canonical form, the one
+// git uses for pathspecs and `ls-files` output: relative to the repository
+// root, '/'-separated, with no "./", no empty or "." segments and no trailing
+// slash. The repository root itself is the single value REPO_ROOT (".", which
+// is what a root unit's `sourcePath` has always recorded).
+//
+// Ownership is decided on whole path segments, never on raw string prefixes:
+// `src` owns `src` and `src/x.ts`, never `src2/x.ts`. The root owns every
+// repository path, which makes it the lowest-precedence owner: when several
+// owners match, the longest one wins, as in a routing table or CODEOWNERS.
+
+export const REPO_ROOT = ".";
+
+// Canonical form of a repository-relative path, or null for a path that is
+// not one: absolute, drive-qualified, backslash-separated or escaping the
+// repository through "..". Those are rejected here rather than resolved, the
+// same rule `isRepoPath` applies to authored paths.
+export function canonicalPath(p) {
+  if (typeof p !== "string") return null;
+  if (p.startsWith("/") || /^[A-Za-z]:/.test(p) || p.includes("\\")) return null;
+  const segs = [];
+  for (const seg of p.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") return null;
+    segs.push(seg);
+  }
+  return segs.length ? segs.join("/") : REPO_ROOT;
+}
+
+export function isRepoRoot(p) {
+  return canonicalPath(p) === REPO_ROOT;
+}
+
+// True when `owner` (a directory such as a unit root or a component's
+// sourcePath) contains `file`, segment by segment.
+export function ownsPath(owner, file) {
+  const o = canonicalPath(owner);
+  const f = canonicalPath(file);
+  if (o === null || f === null) return false;
+  if (o === REPO_ROOT) return true;
+  return f === o || f.startsWith(o + "/");
+}
+
+// The most specific owner of `file` among `owners`, or null. Specificity is
+// segment depth, so the root (depth 0) only wins when nothing else matches —
+// a one-character sibling such as `a` must not tie with ".".
+export function longestOwner(owners, file) {
+  let best = null;
+  let bestDepth = -1;
+  for (const o of owners) {
+    if (!ownsPath(o, file)) continue;
+    const c = canonicalPath(o);
+    const depth = c === REPO_ROOT ? 0 : c.split("/").length;
+    if (depth > bestDepth) {
+      best = o;
+      bestDepth = depth;
+    }
+  }
+  return best;
+}
+
+// Join a unit root and a path below it without ever producing "./x": a root
+// unit's manifest is `package.json`, exactly as git and every other path in
+// the graph spell it.
+export function joinPath(root, rel) {
+  const r = canonicalPath(root);
+  const base = r === null ? String(root).replace(/\/+$/, "") : r;
+  return base === REPO_ROOT || base === "" ? rel : base + "/" + rel;
+}

package/core/query.mjs

@@ -9,6 +9,8 @@
 // than silently dropped, so an agent can see that it is seeing a slice.
 import { AgentDocError, CODES } from "./codes.mjs";
 import { assertNoSecretsInText } from "./secrets.mjs";
+import { verificationForChange } from "./dependents.mjs";
+import { canonicalPath, longestOwner, ownsPath, REPO_ROOT } from "./paths.mjs";
 
 const DEFAULT_BUDGET = {
   relations: 40,
@@ -27,13 +29,13 @@ export class ContextIndex {
   constructor(graph) {
     this.graph = graph;
     this.byRef = new Map(graph.entities.map((e) => [e.ref, e]));
+    // Keyed by canonical source path, so a root unit's "." and any other
+    // spelling of the same directory land on one key.
     this.byPath = new Map();
     for (const e of graph.entities) {
-      const sp = e.derived && e.derived.sourcePath;
-      if (!sp) continue;
+      const sp = e.derived && canonicalPath(e.derived.sourcePath);
+      if (sp === null || sp === undefined) continue;
       this.byPath.set(sp, e);
-      // Longest path first so a nested path resolves to its own component
-      // rather than to a parent.
     }
     // Documentation and constraint files a descriptor links resolve to their
     // component, even when they live outside the source root. Following a
@@ -48,9 +50,12 @@ export class ContextIndex {
         ...(e.derived || {}).constraints || [],
         ...(e.derived || {}).runbooks || [],
       ];
-      for (const p of ctxPaths) if (!this.byDoc.has(p)) this.byDoc.set(p, e);
+      for (const raw of ctxPaths) {
+        const p = canonicalPath(raw) ?? raw;
+        if (!this.byDoc.has(p)) this.byDoc.set(p, e);
+      }
     }
-    this.paths = [...this.byPath.keys()].sort((a, b) => b.length - a.length);
+    this.paths = [...this.byPath.keys()];
     this.relationsByRef = new Map();
     for (const r of graph.relations) {
       if (!this.relationsByRef.has(r.sourceRef)) this.relationsByRef.set(r.sourceRef, []);
@@ -61,34 +66,64 @@ export class ContextIndex {
   }
 
   // A contract file resolves to the API entity that claims it, so "change this
-  // endpoint" routes to the boundary rather than to nothing.
+  // endpoint" routes to the boundary rather than to nothing. A contract ref
+  // names a file, a directory or a module prefix (`events` covering
+  // `events.go`, `events.proto`), the same coverage `Repo.filesWithPrefix`
+  // gives it — never a raw string prefix such as `events2/x`.
   contractFor(needle) {
-    const norm = needle.replace(/^\.\//, "").replace(/\/+$/, "");
+    const norm = canonicalPath(needle);
+    if (norm === null) return null;
     let best = null;
     for (const c of (this.graph.contracts || [])) {
-      if (norm === c.ref || norm.startsWith(c.ref)) {
+      if (contractCovers(c.ref, norm)) {
         if (!best || c.ref.length > best.ref.length) best = c;
       }
     }
     return best;
   }
+  // The component whose source root most specifically owns a repository path:
+  // the longest owning sourcePath, with a root component (".") as the
+  // lowest-precedence fallback. Null when no component owns the path.
+  ownerOf(file) {
+    const p = longestOwner(this.paths, file);
+    return p === null ? null : this.byPath.get(p);
+  }
   resolve(needle) {
     if (this.byRef.has(needle)) return this.byRef.get(needle);
-    const norm = needle.replace(/^\.\//, "").replace(/\/+$/, "");
+    if (looksLikeRef(needle)) return null;
+    // One canonical spelling for every path: `./a/b`, `a//b` and `a/b/` are
+    // all `a/b`. A path escaping the repository resolves to nothing.
+    const norm = canonicalPath(needle);
+    if (norm === null) return null;
     if (this.byDoc.has(norm)) return this.byDoc.get(norm);
-    if (this.byPath.has(norm)) return this.byPath.get(norm);
-    for (const p of this.paths) {
-      if (norm === p || norm.startsWith(p + "/")) return this.byPath.get(p);
-    }
-    for (const p of this.paths) {
-      if (needle.startsWith(p + "/")) return this.byPath.get(p);
-    }
-    if (this.byDoc.has(needle)) return this.byDoc.get(needle);
-    const c = this.contractFor(needle);
-    return c ? this.byRef.get(c.apiRef) || null : null;
+    // Precedence, most specific first: a linked document, a component source
+    // root, a contract's API, and only then a root component. The root owns
+    // every path, so it is the fallback for files nothing else claims; it
+    // must not take a contract file away from the API that declares it.
+    const owner = this.ownerOf(norm);
+    if (owner && canonicalPath(owner.derived.sourcePath) !== REPO_ROOT) return owner;
+    const c = this.contractFor(norm);
+    const api = c ? this.byRef.get(c.apiRef) || null : null;
+    return api || owner || null;
   }
 }
 
+export function contractCovers(ref, file) {
+  const r = canonicalPath(ref);
+  const f = canonicalPath(file);
+  if (r === null || f === null) return false;
+  if (ownsPath(r, f)) return true;
+  const cut = r.lastIndexOf("/");
+  const dir = r.slice(0, cut + 1);
+  return f.startsWith(dir) && f.slice(dir.length).startsWith(r.slice(cut + 1) + ".");
+}
+
+// An entity ref is `kind:namespace/name`. A needle shaped like one that names
+// no entity is an unresolved ref, not a repository path a root component owns.
+function looksLikeRef(needle) {
+  return /^[A-Za-z][\w-]*:/.test(needle);
+}
+
 function contractsOf(graph) {
   return graph.contracts || [];
 }
@@ -135,14 +170,15 @@ export function queryContext(graph, needle, opts = {}) {
   const apiProvider = entity.kind === "API" ? providerOf(ref) : null;
 
   const apiRefs = new Set([...providedApis, ...consumedApis]);
-  const srcPath = (entity.derived && entity.derived.sourcePath) || null;
   const events = g.interfaces.events.filter(
     (e) =>
       e.producers.includes(ref) ||
       e.consumers.includes(ref) ||
       // A contract library that ships the subject catalog owns those subjects,
-      // even when another component is the one that subscribes to them.
-      (srcPath && e.contract && e.contract.ref.startsWith(srcPath + "/"))
+      // even when another component is the one that subscribes to them. The
+      // owner is the component that most specifically owns the contract file,
+      // so a root component does not claim a nested library's catalog.
+      (e.contract && e.contract.ref && idx.ownerOf(e.contract.ref) === entity)
   );
   const externals = g.externalDependencies.filter((e) => e.componentRef === ref);
   const capabilities = g.capabilities.filter((e) => e.componentRef === ref);
@@ -151,7 +187,7 @@ export function queryContext(graph, needle, opts = {}) {
   const verificationScope = entity.kind === "API"
     ? [ref, ...apiConsumers, ...(apiProvider ? [apiProvider] : [])]
     : [ref];
-  const verification = g.verification.filter((e) => e.componentRefs.some((r) => verificationScope.includes(r)));
+  const verification = verificationForChange(g, verificationScope);
   const journeys = g.journeys.filter((j) => j.components.includes(ref));
   const contracts = g.contracts.filter((c) => c.apiRef && apiRefs.has(c.apiRef));
   const conflicts = g.conflicts.filter((c) => c.subject === ref);
@@ -231,9 +267,11 @@ export function queryContext(graph, needle, opts = {}) {
     ),
     capabilities: take(capabilities.map((c) => ({ name: c.name, evidenceClass: c.evidenceClass })), budget.capabilities),
     constraints: {
-      docs: (entity.derived && entity.derived.docs) || [],
-      constraints: (entity.derived && entity.derived.constraints) || [],
-      runbooks: (entity.derived && entity.derived.runbooks) || [],
+      // Components derive these lists (including conventional files); central
+      // entities such as Resources and Systems carry them only in their spec.
+      docs: entity.derived?.docs || entity.entity.spec?.context?.docs || [],
+      constraints: entity.derived?.constraints || entity.entity.spec?.context?.constraints || [],
+      runbooks: entity.derived?.runbooks || entity.entity.spec?.context?.runbooks || [],
     },
     verification: take(
       verification.map((v) => ({ id: v.id, tier: v.tier, command: v.command, configPaths: v.configPaths })),
@@ -329,7 +367,7 @@ function contractRef(graph, apiRef) {
 }
 
 // Compact markdown rendering for a prompt or a human. Same routing, less tokens.
-export function renderContext(ctx) {
+export function renderContext(ctx, opts = {}) {
   const L = [];
   const e = ctx.entity;
   L.push("# " + e.ref + " (" + e.kind + ")");
@@ -345,9 +383,16 @@ export function renderContext(ctx) {
   if (ctx.events.items.length) L.push("- events: " + ctx.events.items.map((x) => x.pattern + " [" + x.resolution + "]").join(", "));
   if (ctx.externalDependencies.items.length) L.push("- external: " + ctx.externalDependencies.items.map((x) => x.name + " (" + x.role + ")").join(", "));
   if (ctx.capabilities.items.length) L.push("- capabilities: " + ctx.capabilities.items.map((x) => x.name).join(", "));
-  if (ctx.constraints.constraints.length) L.push("- CONSTRAINTS: " + ctx.constraints.constraints.join(", "));
-  if (ctx.constraints.docs.length) L.push("- docs: " + ctx.constraints.docs.join(", "));
-  if (ctx.constraints.runbooks.length) L.push("- runbooks: " + ctx.constraints.runbooks.join(", "));
+  for (const key of ["constraints", "docs", "runbooks"]) {
+    const paths = ctx.constraints[key];
+    if (!paths.length) continue;
+    // Constraints are critical routing context; cap them only on request.
+    const limit = opts.budget?.[key] ?? (key === "constraints" ? paths.length : 12);
+    const shown = paths.slice(0, limit);
+    const label = key === "constraints" ? "CONSTRAINTS" : key;
+    L.push("- " + label + ": " + shown.join(", ") +
+      (shown.length < paths.length ? " [truncated: " + shown.length + " of " + paths.length + "]" : ""));
+  }
   if (ctx.verification.items.length) {
     L.push("- verify:");
     for (const v of ctx.verification.items) L.push("  - [" + v.tier + "] " + v.command);