agent-doc-system 1.2.0 → 1.4.0

package/adapters/typescript.mjs

@@ -6,6 +6,7 @@
 import path from "node:path";
 import { Adapter } from "./registry.mjs";
 import { parseYamlDocuments } from "../core/yaml.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 export class TypeScriptAdapter extends Adapter {
   static adapterName = "typescript";
@@ -13,13 +14,13 @@ export class TypeScriptAdapter extends Adapter {
     super({ name: "typescript", version: "1.0.0", kind: "unit-marker" });
   }
   detect(ctx, root) {
-    const p = root + "/tsconfig.json";
+    const p = joinPath(root, "tsconfig.json");
     if (!ctx.repo.exists(p)) return null;
     return { path: p, shape: "importable" };
   }
   extract(ctx, unit) {
     const { repo, prov, compRef } = ctx;
-    const p = unit.root + "/tsconfig.json";
+    const p = joinPath(unit.root, "tsconfig.json");
     if (!repo.exists(p)) return {};
     const derived = { languages: new Set(["typescript"]), runtimes: new Set(["node"]) };
     let ts;
@@ -43,8 +44,9 @@ export class TypeScriptAdapter extends Adapter {
     // real HTTP surface and must be visible to the query surface.
     const routes = [];
     for (const base of ["src/app", "app", "src/pages", "pages"]) {
-      if (!repo.isDir(unit.root + "/" + base)) continue;
-      for (const f of repo.walkUnit(unit.root, unit.root + "/" + base)) {
+      const dir = joinPath(unit.root, base);
+      if (!repo.isDir(dir)) continue;
+      for (const f of repo.walkUnit(unit.root, dir)) {
         const routePath = routeFor(unit.root, base, f);
         if (!routePath) continue;
         const rpr = prov.add("observed", f, "route-extractor", ["der:" + compRef + ":/routes"]);
@@ -63,7 +65,7 @@ export class TypeScriptAdapter extends Adapter {
 }
 
 function routeFor(root, base, file) {
-  const rel = file.slice((root + "/" + base).length + 1);
+  const rel = file.slice(joinPath(root, base).length + 1);
   if (base.endsWith("app")) {
     if (!rel.endsWith("/route.ts") && !rel.endsWith("/route.tsx") && !rel.endsWith("/route.js")) return null;
     const segs = rel.split("/").slice(0, -1);

package/adapters/wrangler.mjs

@@ -11,6 +11,7 @@
 import { Adapter } from "./registry.mjs";
 import { parse as parseToml } from "../core/toml.mjs";
 import { sourceFiles } from "../core/sourcescan.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 const MANIFESTS = ["wrangler.toml", "wrangler.json", "wrangler.jsonc"];
 
@@ -21,13 +22,13 @@ export class WranglerAdapter extends Adapter {
   }
   detect(ctx, root) {
     for (const n of MANIFESTS) {
-      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+      if (ctx.repo.exists(joinPath(root, n))) return { path: joinPath(root, n), shape: "deployable" };
     }
     return null;
   }
   extract(ctx, unit) {
     const { repo, prov, compRef } = ctx;
-    const file = MANIFESTS.map((n) => unit.root + "/" + n).find((p) => repo.exists(p));
+    const file = MANIFESTS.map((n) => joinPath(unit.root, n)).find((p) => repo.exists(p));
     if (!file) return {};
     let toml;
     try {

package/bin/agentdoc.mjs

@@ -19,7 +19,7 @@ import { observationFreshness, stalenessDiagnostics } from "../core/observations
 import { assertNoSecretsInText } from "../core/secrets.mjs";
 import { installTemplates } from "../core/scaffold.mjs";
 import { COMMANDS, flagsOf, parseArgs, commandHelp, UsageError } from "./commands.mjs";
-import { loadSchemaBundle, loadConfig } from "../core/descriptors.mjs";
+import { loadSchemaBundle, loadConfig, CONFIG_PATH } from "../core/descriptors.mjs";
 import { execFileSync } from "node:child_process";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -353,7 +353,14 @@ try {
         : {}),
     }, true);
   } else if (cmd === "init") {
-    const result = installTemplates(null, null, { write: true, root: ROOT, force: opt("force") });
+    // An existing configuration is the authority on where documentation lives
+    // (issue #49). Load it through the compiler's own loader, so init, scaffold,
+    // audit and compile cannot disagree, and so an invalid or escaping docs path
+    // is rejected before anything is written.
+    const docsConfig = fs.existsSync(path.join(ROOT, CONFIG_PATH))
+      ? loadConfig(new Repo(ROOT, { noGit: true }), loadSchemaBundle().bundle)
+      : null;
+    const result = installTemplates(null, null, { write: true, root: ROOT, force: opt("force"), docsConfig });
     out(result, true);
   } else if (cmd === "eval") {
     const which = positional[0] || "routing";

package/bin/usage.txt

@@ -5,6 +5,8 @@ agentdoc — portable documentation & software-catalog system
   agentdoc <command> --help          every flag one command accepts (also: agentdoc help <command>)
 
   agentdoc init [--force]            write a configuration and documentation skeleton
+                                     (docs skeleton goes to the configured docs.* paths;
+                                     agentdoc/docs/ when there is no configuration yet)
   agentdoc audit                     inventory the repository, classify every fact
   agentdoc scaffold [--write]        generate a CREATE-mode skeleton from the audit
   agentdoc validate                  sources + schemas + semantic checks

package/core/audit.mjs

@@ -19,6 +19,7 @@ import { classifyContractFile } from "./contracts.mjs";
 import { ContextIndex } from "./query.mjs";
 import { expandGlob, isRepoPath } from "./fsx.mjs";
 import { isNormative, NORMATIVE_SEMANTICS_PREFIX } from "./normative.mjs";
+import { isRepoRoot, longestOwner } from "./paths.mjs";
 
 const DOC_EXT = /\.(md|mdx|adoc|rst|txt)$/;
 
@@ -143,11 +144,12 @@ export function audit(repo, cfg, res) {
       configured.push({ role, path: dir, configured: false });
     }
   }
-  const unitRoots = new Set(res.discovery.units.map((u) => u.root));
-  const insideComponent = (p) => {
-    for (const r of unitRoots) if (p === r || p.startsWith(r + "/")) return r;
-    return null;
-  };
+  // The most specific unit root containing the path. A root unit is left out
+  // on purpose: it contains the whole repository, so counting it would make
+  // every repository-wide hierarchy document "component-scoped" and the
+  // distinction this check draws would disappear.
+  const unitRoots = [...new Set(res.discovery.units.map((u) => u.root))].filter((r) => !isRepoRoot(r));
+  const insideComponent = (p) => longestOwner(unitRoots, p);
 
   // The audit reports; it does not gate. These are therefore collected as audit
   // findings on the report rather than pushed into the compile-time diagnostics,

package/core/codes.mjs

@@ -23,6 +23,7 @@ export const CODES = {
   GLOB: "AGENTDOC_GLOB",
   PATH_ESCAPE: "AGENTDOC_PATH_ESCAPE",
   PATH_UNRESOLVED: "AGENTDOC_PATH_UNRESOLVED",
+  MIGRATION_PATH: "AGENTDOC_MIGRATION_PATH",
   SECRET: "AGENTDOC_SECRET",
 
   // identity & references
@@ -98,6 +99,7 @@ export const ACCEPTABLE_WARNING_CODES = Object.freeze([
   "AGENTDOC_NORMATIVE_UNCOVERED",
   "AGENTDOC_REQUIREMENT_UNVERIFIED",
   "AGENTDOC_PYTHON_SPECIFIER",
+  "AGENTDOC_MIGRATION_DIR_UNRESOLVED",
 ]);
 
 export class AgentDocError extends Error {

package/core/compile.mjs

@@ -24,6 +24,7 @@ import {
 } from "./normative.mjs";
 import { loadAdapters } from "../adapters/index.mjs";
 import { loadCargoUnit, analyzeCargoDeps, rustIdentsInSource } from "../adapters/rust.mjs";
+import { joinPath, ownsPath } from "./paths.mjs";
 import {
   COMPILER_NAME, COMPILER_VERSION, GRAPH_SCHEMA_VERSION,
   assembleGraph, serializeGraph, finalizeSerialization, subjectResolver,
@@ -300,7 +301,7 @@ export function compile(root, opts = {}) {
   // every graph that does not enable python.
   const pythonOn = adapters.some((a) => a.name === "python");
   for (const unit of discovery.eligible) {
-    const pkgPath = unit.root + "/package.json";
+    const pkgPath = joinPath(unit.root, "package.json");
     if (repo.exists(pkgPath)) {
       try {
         const pkg = repo.readJson(pkgPath);
@@ -310,7 +311,7 @@ export function compile(root, opts = {}) {
         res.errors.push(new AgentDocError(CODES.SCHEMA, "package.json is not valid JSON: " + pkgPath, { path: pkgPath }));
       }
     }
-    const gomodPath = unit.root + "/go.mod";
+    const gomodPath = joinPath(unit.root, "go.mod");
     if (repo.exists(gomodPath)) {
       const m = /^module\s+(\S+)/m.exec(repo.readText(gomodPath));
       unit.goModule = m ? m[1] : null;
@@ -398,7 +399,7 @@ export function compile(root, opts = {}) {
       if (t && t.component && t.component.ref !== unit.component.ref) deps.add(t.component.ref);
     }
     if (unit.goModule) {
-      const gomod = repo.exists(unit.root + "/go.mod") ? repo.readText(unit.root + "/go.mod") : "";
+      const gomod = repo.exists(joinPath(unit.root, "go.mod")) ? repo.readText(joinPath(unit.root, "go.mod")) : "";
       const goReqs = [...gomod.matchAll(/^\s*(?:require\s+)?([a-z0-9.]+\.[a-z0-9./-]+)\s+v[0-9]/gm)].map((m) => m[1]);
       productionDependencies.set(unit.component.ref, [...(productionDependencies.get(unit.component.ref) || []), ...goReqs]);
       for (const m of gomod.matchAll(/^\s*(?:require\s+)?([a-z0-9.]+\.[a-z0-9./-]+)\s+v[0-9]/gm)) {
@@ -497,6 +498,10 @@ export function compile(root, opts = {}) {
       "entf:" + e.ref + ":/metadata/description",
     ];
     if (e.doc.spec !== undefined) subjects.push("entf:" + e.ref + ":/spec");
+    // A declared migration path is the one authored path whose meaning reaches
+    // past the descriptor (impact routes every change below it to this
+    // Resource), so it is pointed at directly rather than through `/spec`.
+    if (e.doc.spec?.migrationPaths) subjects.push("entf:" + e.ref + ":/spec/migrationPaths");
     prov.add("declared", e.file, "descriptor-reader", subjects);
   }
 
@@ -776,7 +781,7 @@ export function compile(root, opts = {}) {
     return earlyOut(res, { entities: sources.entities.length, units: discovery.eligible.length });
   }
   for (const d of derivedMap.values()) {
-    for (const list of [d.bindings || [], d.healthContracts || []]) {
+    for (const list of [d.bindings || [], d.healthContracts || [], d.migrationDirs || []]) {
       for (const b of list) {
         b.provenanceIds = [...(b._provs || [])].map((p) => provFinal.idOf.get(p)).filter(Boolean).sort();
         delete b._provs;
@@ -796,14 +801,15 @@ export function compile(root, opts = {}) {
     ...schemaInputs,
     ...adapters.map((a) => ADAPTER_VERSION_INPUT_PREFIX + a.name + "@" + a.version),
   ]);
-  const dirtySet = new Set(repo.dirtyPaths().filter((p) => p !== graphPath));
+  // The same git status snapshot the ignore oracle answered from (fsx.mjs).
+  const dirtySet = new Set(repo.dirtyPaths({ snapshot: true }).filter((p) => p !== graphPath));
   const walkedDirs = [...repo.walks.keys()];
   const dirty = [...dirtySet].some(
     (p) =>
       repo.readPaths.has(p) ||
       repo.probes.has(p) ||
       repo.listings.has(p) ||
-      walkedDirs.some((d) => (d === "." ? true : p === d || p.startsWith(d + "/")))
+      walkedDirs.some((d) => ownsPath(d, p))
   );
   graph.source = { commit, dirty, inputHash };
 

package/core/derive.mjs

@@ -7,6 +7,7 @@
 import path from "node:path";
 import { assertRepoPath } from "./fsx.mjs";
 import { CODES } from "./codes.mjs";
+import { joinPath } from "./paths.mjs";
 
 const DEFAULT_DOC_CANDIDATES = ["README.md", "ARCHITECTURE.md", "AGENTS.md", "CONTRIBUTING.md", "DESIGN.md", "OVERVIEW.md"];
 const DEFAULT_CONSTRAINT_CANDIDATES = ["CONSTRAINTS.md", "INVARIANTS.md"];
@@ -33,15 +34,15 @@ export function genericFacts(ctx, unit) {
   const constraints = [];
   const runbooks = [];
   for (const n of docNames) {
-    const p = root + "/" + n;
+    const p = joinPath(root, n);
     if (repo.exists(p)) { docs.push(p); prov.add("observed", p, "docs-extractor", ["der:" + compRef + ":/docs"]); }
   }
   for (const n of constraintNames) {
-    const p = root + "/" + n;
+    const p = joinPath(root, n);
     if (repo.exists(p)) { constraints.push(p); prov.add("observed", p, "docs-extractor", ["der:" + compRef + ":/constraints"]); }
   }
   for (const n of runbookNames) {
-    const p = root + "/" + n;
+    const p = joinPath(root, n);
     if (repo.exists(p)) { runbooks.push(p); prov.add("observed", p, "docs-extractor", ["der:" + compRef + ":/runbooks"]); }
   }
   const spec = ctx.componentEntity().doc.spec || {};

package/core/descriptors.mjs

@@ -20,6 +20,7 @@ import { parseYamlDocuments } from "./yaml.mjs";
 import { scanForSecrets } from "./secrets.mjs";
 import { formatErrors } from "./jsonschema.mjs";
 import { SchemaBundle } from "./jsonschema.mjs";
+import { joinPath, ownsPath } from "./paths.mjs";
 
 export const KINDS = Object.freeze(["Domain", "System", "Component", "API", "Resource"]);
 const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -177,7 +178,7 @@ function descriptorGlobs(repo, cfg) {
   // glob — its descriptor lives at a fixed path and must be loaded even when
   // no componentDescriptors glob happens to cover that directory.
   for (const r of cfg.discovery.supplementalRoots || []) {
-    const f = String(r).replace(/\/+$/, "") + "/" + cfg.discovery.componentDescriptorName;
+    const f = joinPath(String(r), cfg.discovery.componentDescriptorName);
     if (repo.exists(f)) componentFiles.add(f);
   }
   const centralFiles = new Set();
@@ -296,6 +297,7 @@ export function loadDescriptors(repo, cfg, bundle, refs) {
           throw new AgentDocError(CODES.PATH_UNRESOLVED, "context link does not resolve: " + p, { path: e.file, ref: e.ref });
         }
       }
+      if (e.kind === "Resource" && spec.migrationPaths) checkMigrationPaths(repo, e);
       if (e.kind === "API") {
         const prov = spec.provider;
         if (!refs.isValidRef(prov) || refs.kindOfRef(prov) !== "Component") {
@@ -334,9 +336,57 @@ export function loadDescriptors(repo, cfg, bundle, refs) {
     }, errors);
   }
 
+  // One directory migrates one database. Two Resources declaring the same path
+  // would make every migration under it ambiguous, and impact must not pick.
+  // Nested declarations are fine: the longest prefix wins, as for ownership.
+  const declaredBy = new Map();
+  for (const e of entities) {
+    if (e.kind !== "Resource") continue;
+    for (const p of e.doc.spec?.migrationPaths || []) {
+      if (!declaredBy.has(p)) declaredBy.set(p, []);
+      declaredBy.get(p).push(e);
+    }
+  }
+  for (const [p, owners] of [...declaredBy.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    if (owners.length < 2) continue;
+    const names = owners.map((o) => o.ref).sort();
+    errors.push(new AgentDocError(
+      CODES.MIGRATION_PATH,
+      "migration path " + JSON.stringify(p) + " is declared by several Resources (" + names.join(", ") + "); a migration directory migrates one logical database",
+      { path: owners[0].file, ref: names[0] }
+    ));
+  }
+
   return { entities, byRef, byKindName, componentFiles: new Set(componentFiles), errors, componentSet, centralSet };
 }
 
+// `spec.migrationPaths` on a Resource: repository directories (or files) whose
+// changes are changes to this database. They are whole-segment prefixes with
+// the semantics of `core/paths.mjs`, never globs: a glob would need an engine
+// this system does not ship, and `drizzle/**` means nothing a prefix does not.
+function checkMigrationPaths(repo, e) {
+  if (e.doc.spec.type !== "logical-database") {
+    throw new AgentDocError(
+      CODES.MIGRATION_PATH,
+      "spec.migrationPaths is only meaningful on a logical-database Resource, not on type '" + e.doc.spec.type + "'",
+      { path: e.file, ref: e.ref }
+    );
+  }
+  for (const p of e.doc.spec.migrationPaths) {
+    assertRepoPath(p, e.file);
+    if (/[*?[\]{}!]/.test(p)) {
+      throw new AgentDocError(
+        CODES.MIGRATION_PATH,
+        "migration path " + JSON.stringify(p) + " is a glob; declare the directory itself (e.g. \"" + p.replace(/\/?[^/]*[*?[\]{}!].*$/, "") + "\"), which covers everything below it",
+        { path: e.file, ref: e.ref }
+      );
+    }
+    if (!repo.exists(p)) {
+      throw new AgentDocError(CODES.PATH_UNRESOLVED, "migration path does not resolve: " + p, { path: e.file, ref: e.ref });
+    }
+  }
+}
+
 export function loadJourneys(repo, cfg, bundle, byRef) {
   const errors = [];
   const jPath = cfg.discovery.journeyDefinitions;
@@ -473,7 +523,7 @@ export function loadReviewedOverrides(repo, cfg, refs, byRef) {
         : null;
       for (const ev of o.evidence) {
         const p = ev.path;
-        const scoped = p === o.contractRef || p.startsWith(subjectRoot + "/") || (targetRoot && p.startsWith(targetRoot + "/"));
+        const scoped = p === o.contractRef || ownsPath(subjectRoot, p) || (targetRoot !== null && ownsPath(targetRoot, p));
         if (!scoped) {
           throw new AgentDocError(
             CODES.RELATION_KIND,

package/core/discover.mjs

@@ -7,6 +7,7 @@
 import path from "node:path";
 import { AgentDocError, CODES } from "./codes.mjs";
 import { expandGlob, globToRegExp, assertGlob } from "../core/fsx.mjs";
+import { joinPath, ownsPath } from "./paths.mjs";
 
 // Roots excluded from inference and scaffolding. Authored descriptors strictly
 // below them can still claim units; descriptors at these exact roots cannot.
@@ -20,7 +21,7 @@ function notUnitRoots(cfg) {
 // mode shares this policy even for units with an existing authored descriptor.
 export function isNotUnitRoot(root, cfg) {
   return notUnitRoots(cfg)
-    .some((excluded) => root === excluded || root.startsWith(excluded + "/"));
+    .some((excluded) => ownsPath(excluded, root));
 }
 
 export function discoverUnits(repo, cfg, adapters) {
@@ -54,7 +55,7 @@ export function discoverUnits(repo, cfg, adapters) {
   for (const r of cfg.discovery.supplementalRoots || []) {
     candidates.add(r);
     // The descriptor loader also reads these fixed paths outside the globs.
-    if (repo.exists(r + "/" + cfg.discovery.componentDescriptorName)) descriptorRoots.add(r);
+    if (repo.exists(joinPath(r, cfg.discovery.componentDescriptorName))) descriptorRoots.add(r);
   }
 
   // Adapters may contribute roots the descriptor globs cannot know about: a