agent-doc-system 1.2.0 → 1.4.0

package/core/fsx.mjs

@@ -5,11 +5,21 @@
 // is what the graph's inputHash is computed over, so freshness detection can
 // never miss an input. This is the single most important property of the
 // original system and is preserved verbatim.
+//
+// The input set is the checkout as git sees it: paths git ignores are not part
+// of the repository (issue #45). A local build writing into an ignored
+// directory — `astro build` filling `.astro/`, a `build/` tree, a `*.log` —
+// must not move the inputHash, or a graph compiled after that build can never
+// be reproduced by a clean checkout or by CI. Git itself is the oracle (see
+// `ignoredPaths`); nothing here re-implements gitignore matching. Every read,
+// probe and listing below consults the same oracle, and `check` recomputes the
+// hash by running the same compile, so compile and check cannot disagree.
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { AgentDocError, CODES } from "./codes.mjs";
+import { canonicalPath, ownsPath, REPO_ROOT } from "./paths.mjs";
 
 export function sha256Hex(buf) {
   return createHash("sha256").update(buf).digest("hex");
@@ -39,6 +49,9 @@ export function assertRepoPath(p, ctx) {
 
 // Build/tooling output is never repository authority. Configurable per install
 // so a project with e.g. "target" or "vendor" trees keeps them out too.
+// This list applies everywhere, and is the *only* exclusion when there is no
+// git oracle (no repository, no git binary, or `noGit`). Inside a git
+// checkout, git-ignored paths are excluded in addition — see `ignoredPaths`.
 // Build and tooling output. Tooling caches and dependency directories only: a
 // name like `build`, `out` or `tmp` is far more likely to be a real unit in some
 // repository than a generated directory, and a repository with a deployable
@@ -62,6 +75,11 @@ export class Repo {
     this.nestedUnitRoots = new Map();
     this.generatedDirs = new Set(opts.generatedDirs || DEFAULT_GENERATED_DIRS);
     this.noGit = Boolean(opts.noGit);
+    // Per-Repo git caches. undefined = not asked yet; null = no answer.
+    this._hasGit = undefined;
+    this._prefix = undefined;
+    this._status = undefined;
+    this._ignored = undefined;
   }
   abs(rel) {
     const a = path.resolve(this.root, rel);
@@ -70,14 +88,71 @@ export class Repo {
     }
     return a;
   }
+  // The paths git ignores under this.root, asked once per Repo and cached, so
+  // every read, probe and listing in a run sees the same snapshot.
+  //
+  // `git status --ignored=matching` is the oracle (git-status(1)): it reports
+  // exactly the untracked paths that match an ignore pattern, and an ignored
+  // directory as one `dir/` entry without its contents. That gives git's own
+  // semantics for free:
+  //   - tracked files are never reported, so a tracked file that matches a
+  //     pattern stays an input ("tracked always wins", gitignore(5));
+  //   - nested .gitignore files, $GIT_DIR/info/exclude and core.excludesFile
+  //     apply with gitignore(5) precedence, negations included, and a file
+  //     whose parent directory is excluded cannot be re-included;
+  //   - a directory that is not itself ignored is never collapsed, only its
+  //     ignored contents are listed. (`git ls-files -o -i --directory` gets
+  //     this wrong: it also prints a non-ignored parent whose only content is
+  //     ignored, and aborts when run from inside an ignored directory.)
+  //
+  // The user's global core.excludesFile deliberately counts. An ignored
+  // untracked file is, by definition, absent from every clean checkout, so
+  // whichever ignore source matched it, dropping it moves this machine's input
+  // set *towards* what CI sees, never away from it — no ignore rule can hide a
+  // tracked file. Ignoring core.excludesFile would bring back issue #45 for
+  // anything a developer ignores globally (editor swap files, `.envrc`): the
+  // file would enter the hash while `git status`, and therefore the graph's
+  // `dirty` flag, stays silent about it.
+  //
+  // The snapshot comes from `statusRecords`, the same single `git status`
+  // call the compile's dirty check reads, so the input set and the `dirty`
+  // flag describe the same moment. Paths come back relative to the git
+  // toplevel and are re-keyed by `toRepoPaths`; an ignored *ancestor* of
+  // this.root is dropped there, so a project the user pointed the compiler at
+  // is never blanked out by an outer .gitignore.
+  //
+  // null when there is no oracle — `noGit`, not a git checkout, git missing
+  // or failing. The input set is then the filesystem minus generatedDirs,
+  // exactly as before #45.
+  ignoredPaths() {
+    if (this._ignored !== undefined) return this._ignored;
+    const recs = this.statusRecords();
+    const prefix = recs ? this.gitPrefix() : null;
+    this._ignored = recs && prefix !== null
+      ? new Set(this.toRepoPaths(recs.filter((r) => r.xy === "!!").map((r) => r.path), prefix))
+      : null;
+    return this._ignored;
+  }
+  // True when git ignores `rel` or one of its parent directories. Directory
+  // entries carry a trailing "/" in git's output.
+  isIgnored(rel) {
+    const set = this.ignoredPaths();
+    if (!set || set.size === 0 || !rel || rel === ".") return false;
+    if (set.has(rel) || set.has(rel + "/")) return true;
+    for (let i = rel.indexOf("/"); i >= 0; i = rel.indexOf("/", i + 1)) {
+      if (set.has(rel.slice(0, i + 1))) return true;
+    }
+    return false;
+  }
+  // An ignored path is probed as absent: that is what a clean checkout sees.
   exists(rel) {
-    const r = fs.existsSync(this.abs(rel));
+    const r = !this.isIgnored(rel) && fs.existsSync(this.abs(rel));
     this.probes.set(rel, r);
     return r;
   }
   isDir(rel) {
     try {
-      const r = fs.statSync(this.abs(rel)).isDirectory();
+      const r = !this.isIgnored(rel) && fs.statSync(this.abs(rel)).isDirectory();
       this.probes.set(rel, r);
       return r;
     } catch {
@@ -87,6 +162,16 @@ export class Repo {
   }
   readBytes(rel, { track = true } = {}) {
     const a = this.abs(rel);
+    // A tracked (input) read of an ignored path fails exactly as a read of a
+    // missing file does, so a descriptor that points into build output breaks
+    // locally the same way it breaks in CI. Untracked reads are not inputs.
+    if (track && this.isIgnored(rel)) {
+      throw new AgentDocError(
+        CODES.PATH_UNRESOLVED,
+        "path is ignored by git, so it is not a repository input: " + rel,
+        { path: rel }
+      );
+    }
     let buf;
     try {
       buf = fs.readFileSync(a);
@@ -114,10 +199,13 @@ export class Repo {
     return JSON.parse(this.readText(rel, { track: false }));
   }
   // Recursive listing, byte-sorted, never following symlinks out of the repo.
+  // Ignored directories are pruned, not descended: an ignored `node_modules`
+  // or `.astro` costs one Set lookup.
   walk(relDir, { exclude = () => false } = {}) {
     const base = relDir ? this.abs(relDir) : this.root;
     const out = [];
-    const stack = [base];
+    const ignored = this.ignoredPaths();
+    const stack = relDir && this.isIgnored(relDir) ? [] : [base];
     while (stack.length) {
       const dir = stack.pop();
       let entries;
@@ -132,6 +220,9 @@ export class Repo {
         const full = path.join(dir, ent.name);
         const rel = path.relative(this.root, full).split(path.sep).join("/");
         if (ent.isSymbolicLink()) continue;
+        // Parents are already known not to be ignored, so the entry itself is
+        // the only lookup needed.
+        if (ignored && ignored.has(ent.isDirectory() ? rel + "/" : rel)) continue;
         if (exclude(rel, ent)) continue;
         if (ent.isDirectory()) stack.push(full);
         else if (ent.isFile()) out.push(rel);
@@ -144,12 +235,11 @@ export class Repo {
   // Per-unit scans use the discovery result, never filesystem heuristics.
   // Keep walk() repository-wide for discovery, contracts and authored inputs.
   ownsUnitPath(unitRoot, rel) {
-    const normalize = (p) => path.posix.normalize(p || ".").replace(/^\.$/, "");
-    const root = normalize(unitRoot);
-    const target = normalize(rel);
-    if (root && target !== root && !target.startsWith(root + "/")) return false;
-    for (const child of this.nestedUnitRoots.get(root) || []) {
-      if (target === child || target.startsWith(child + "/")) return false;
+    if (!ownsPath(unitRoot, rel)) return false;
+    // nestedUnitRoots is keyed with the root spelled "" (see discoverUnits).
+    const root = canonicalPath(unitRoot);
+    for (const child of this.nestedUnitRoots.get(root === REPO_ROOT ? "" : root) || []) {
+      if (ownsPath(child, rel)) return false;
     }
     return true;
   }
@@ -179,12 +269,17 @@ export class Repo {
   // A directory listing is a compiler input like any other, and is recorded so
   // the input hash covers it. An untracked listing would let a change to a
   // directory's contents escape freshness detection.
+  // Ignored entries are left out, as if absent.
   listDir(relDir) {
     let names;
     try {
-      names = fs.readdirSync(this.abs(relDir), { withFileTypes: true })
-        .map((e) => (e.isDirectory() ? e.name + "/" : e.name))
-        .sort();
+      const prefix = relDir && relDir !== "." ? relDir + "/" : "";
+      names = this.isIgnored(relDir)
+        ? []
+        : fs.readdirSync(this.abs(relDir), { withFileTypes: true })
+          .map((e) => (e.isDirectory() ? e.name + "/" : e.name))
+          .filter((n) => !this.isIgnored(prefix + n.replace(/\/$/, "")))
+          .sort();
     } catch {
       names = [];
     }
@@ -204,17 +299,21 @@ export class Repo {
     });
     return trim ? out.trim() : out;
   }
+  // Cached per Repo, like gitPrefix: whether this.root is a git checkout does
+  // not change during a run, and each probe is a process spawn.
   hasGit() {
     if (this.noGit) return false;
+    if (this._hasGit !== undefined) return this._hasGit;
     try {
       const probe = execFileSync("git", ["rev-parse", "--git-dir"], {
         cwd: this.root,
         stdio: ["ignore", "pipe", "ignore"],
       });
-      return probe.toString().trim().length > 0;
+      this._hasGit = probe.toString().trim().length > 0;
     } catch {
-      return false;
+      this._hasGit = false;
     }
+    return this._hasGit;
   }
   // A checkout without git — a source tarball, a vendored copy, a CI runner with
   // no VCS — still compiles. Freshness then rests on the input hash alone, and
@@ -236,14 +335,15 @@ export class Repo {
   // tracker uses.
   gitPrefix() {
     if (this.noGit || !this.hasGit()) return null;
+    if (this._prefix !== undefined) return this._prefix;
     try {
-      return this.git(["rev-parse", "--show-prefix"]);
+      this._prefix = this.git(["rev-parse", "--show-prefix"]);
     } catch {
-      return null;
+      this._prefix = null;
     }
+    return this._prefix;
   }
-  toRepoPaths(gitPaths) {
-    const prefix = this.gitPrefix();
+  toRepoPaths(gitPaths, prefix = this.gitPrefix()) {
     if (prefix === null) return [];
     const out = [];
     for (const p of gitPaths) {
@@ -253,31 +353,46 @@ export class Repo {
     }
     return out;
   }
-  dirtyPaths() {
-    if (this.noGit || !this.hasGit()) return [];
-    let raw;
-    try {
-      // Untrimmed: a porcelain record is `XY <path>` with fixed columns, and an
-      // unstaged change has X = " ". Trimming would eat that space from the
-      // first record, so `.slice(3)` would drop the path's first character —
-      // ` M .agentdoc/graph.json` became `agentdoc/graph.json`, slipped past
-      // the output exclusion and counted as a dirty input (issue #11).
-      raw = this.git(["status", "--porcelain", "-z", "--untracked-files=all"], { trim: false });
-    } catch {
-      return [];
-    }
-    const paths = [];
-    let skipNext = false;
-    for (const rec of raw.split("\0")) {
-      if (!rec) continue;
-      // In -z format a rename/copy is two records: `XY <to>` then a bare
-      // `<from>` with no status. The bare record must be consumed, not parsed
-      // as a status line.
-      if (skipNext) { skipNext = false; continue; }
-      if (rec[0] === "R" || rec[0] === "C" || rec[1] === "R" || rec[1] === "C") skipNext = true;
-      paths.push(rec.slice(3));
+  // One `git status` for both questions a compile asks git about the
+  // working tree: what is dirty (`XY` records) and what is ignored (`!!`).
+  // `--untracked-files=all` lists untracked files individually, so they can
+  // be matched against the read tracker; `--ignored=matching` adds the
+  // ignored paths without descending into ignored directories.
+  // `--no-optional-locks` keeps it read-only: no refreshed index is written
+  // back, so it never contends with a git command the user is running.
+  // `-- .` scopes the scan to this.root, which may sit inside a larger
+  // checkout. Cached unless `fresh`: the ignore oracle must answer from one
+  // snapshot for the whole run.
+  statusRecords({ fresh = false } = {}) {
+    if (!fresh && this._status !== undefined) return this._status;
+    let recs = null;
+    if (!this.noGit && this.hasGit()) {
+      try {
+        // Untrimmed: a porcelain record is `XY <path>` with fixed columns, and
+        // an unstaged change has X = " ". Trimming would eat that space from
+        // the first record, so `.slice(3)` would drop the path's first
+        // character — ` M .agentdoc/graph.json` became `agentdoc/graph.json`,
+        // slipped past the output exclusion and counted as a dirty input
+        // (issue #11).
+        recs = parseStatusZ(this.git(
+          ["--no-optional-locks", "status", "--porcelain", "-z",
+            "--untracked-files=all", "--ignored=matching", "--", "."],
+          { trim: false }
+        ));
+      } catch {
+        recs = null;
+      }
     }
-    return this.toRepoPaths(paths);
+    if (!fresh) this._status = recs;
+    return recs;
+  }
+  // Fresh by default, so a caller holding a Repo sees the current tree. The
+  // compile passes `snapshot: true` to read the same status the ignore oracle
+  // used — one git call, and a dirty flag consistent with the input set.
+  dirtyPaths({ snapshot = false } = {}) {
+    const recs = this.statusRecords({ fresh: !snapshot });
+    if (!recs) return [];
+    return this.toRepoPaths(recs.filter((r) => r.xy !== "!!").map((r) => r.path));
   }
   // null on failure (bad ref, missing object store) so callers can tell
   // "the diff failed" apart from "the diff is empty".
@@ -291,6 +406,23 @@ export class Repo {
   }
 }
 
+// `git status --porcelain -z` records (git-status(1), "Porcelain Format
+// Version 1"): `XY <path>`, NUL-terminated, never quoted.
+function parseStatusZ(raw) {
+  const out = [];
+  let skipNext = false;
+  for (const rec of raw.split("\0")) {
+    if (!rec) continue;
+    // In -z format a rename/copy is two records: `XY <to>` then a bare
+    // `<from>` with no status. The bare record must be consumed, not parsed
+    // as a status line.
+    if (skipNext) { skipNext = false; continue; }
+    if (rec[0] === "R" || rec[0] === "C" || rec[1] === "R" || rec[1] === "C") skipNext = true;
+    out.push({ xy: rec.slice(0, 2), path: rec.slice(3) });
+  }
+  return out;
+}
+
 // Minimal glob: '*' matches within one segment, '**' matches any depth.
 export function globToRegExp(glob) {
   const segs = glob.split("/");

package/core/graph.mjs

@@ -9,7 +9,7 @@ import { assertDeterministic, structuralProjection } from "./determinism.mjs";
 import { sha256Hex } from "./fsx.mjs";
 
 export const COMPILER_NAME = "agentdoc-compiler";
-export const COMPILER_VERSION = "1.2.0";
+export const COMPILER_VERSION = "1.4.0";
 export const GRAPH_SCHEMA_VERSION = "agentdoc.dev/graph/v1";
 
 // Resolve symbolic provenance subjects to RFC 6901 pointers into the graph.

package/core/impact.mjs

@@ -5,6 +5,12 @@
 // from the graph alone, so the answer is available before any exploration.
 import { ContextIndex } from "./query.mjs";
 import { dependentScope, verificationForChange } from "./dependents.mjs";
+import { canonicalPath, ownsPath, longestOwner } 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
@@ -17,7 +23,10 @@ import { dependentScope, verificationForChange } from "./dependents.mjs";
 //   - every extractor identity, which names the technology        -> dependency /
 //                                                                    verification
 //   - every documentation and constraint path on an entity         -> documentation
-function classify(graph, p, idx) {
+//   - every migration directory: declared on a logical-database    -> resource
+//     Resource (`spec.migrationPaths`), or detected per component
+//     by the database adapter (`derived.migrationDirs`)
+function classify(graph, p, idx, migrations) {
   for (const c of graph.contracts) if (c.ref === p) return "contract";
   for (const e of graph.entities) {
     const d = e.derived || {};
@@ -26,6 +35,13 @@ 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 (migrationHit(migrations, p)) return "resource";
+  // Kept as a fallback, and the one name-based rule left: before the graph
+  // recorded migration directories this regex was the whole classification,
+  // and it still has to answer where nothing is recorded — a repository that
+  // does not enable the database adapter, a migration directory deeper than
+  // the adapter's bounded walk, a graph built by hand. Dropping it would change
+  // the answer for those repositories; what the graph records only adds to it.
   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
@@ -40,8 +56,43 @@ function classify(graph, p, idx) {
   return null;
 }
 
+// Migration directories recorded in the graph, with what made them one.
+function migrationDirs(graph) {
+  const declared = new Map(); // path -> Resource ref
+  const detected = new Map(); // path -> { componentRef, via }
+  for (const e of graph.entities) {
+    if (e.kind === "Resource") {
+      for (const p of e.entity?.spec?.migrationPaths || []) declared.set(p, e.ref);
+    }
+    if (e.kind === "Component") {
+      for (const d of e.derived?.migrationDirs || []) detected.set(d.path, { componentRef: e.ref, via: d.via || [] });
+    }
+  }
+  return { declared, detected };
+}
+
+// The migration directory a path is under, by whole path segments, the most
+// specific first. An authored declaration beats a detected directory: it names
+// the database, where detection only names the component whose bindings say
+// which database it is.
+function migrationHit(migrations, p) {
+  if (!migrations) return null;
+  const d = longestOwner(migrations.declared.keys(), p);
+  if (d) return { dir: d, resourceRef: migrations.declared.get(d), how: "declared on " + migrations.declared.get(d) };
+  const x = longestOwner(migrations.detected.keys(), p);
+  if (!x) return null;
+  const { componentRef, via } = migrations.detected.get(x);
+  // A directory found by its conventional name is exactly what the fallback
+  // regex already classified; only a directory nothing but the graph knows
+  // about is worth a reason of its own.
+  const conventional = via.every((v) => v === "directory-name" || v === "alembic-versions");
+  return { dir: x, componentRef, conventional, how: "detected from " + via.join(", ") + " in " + componentRef };
+}
+
 export function impact(graph, changedPaths) {
   const idx = new ContextIndex(graph);
+  const migrations = migrationDirs(graph);
+  const migrationReasons = new Map(); // Resource ref -> Set(reason)
   const affectedComponents = new Map(); // ref -> Set(reason)
   const add = (ref, reason) => {
     if (idx.byRef.get(ref)?.kind !== "Component") return;
@@ -59,31 +110,48 @@ export function impact(graph, changedPaths) {
   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",
     // while the components actually bound to it went unmentioned.
     if (entity && entity.kind === "Component") add(entity.ref, "direct file change inside " + entity.ref);
     else unmatched.push(p);
-    const kind = classify(graph, p, idx);
+    const kind = classify(graph, p, idx, migrations);
     if (kind === "contract") contracts.add(p);
     if (kind === "documentation") docs.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);
+      const hit = migrationHit(migrations, p);
+      const because = (ref) => {
+        if (!hit || hit.conventional) return;
+        if (!migrationReasons.has(ref)) migrationReasons.set(ref, new Set());
+        migrationReasons.get(ref).add("migration " + p + " changes " + ref + " (migration directory " + hit.dir + ", " + hit.how + ")");
+      };
+      if (hit?.resourceRef) {
+        // Authored: the declaration names the database, whichever component
+        // owns the file and whatever that component is bound to.
+        resources.add(hit.resourceRef);
+        because(hit.resourceRef);
+      } else {
+        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.
+        const owner = hit?.componentRef ?? (entity?.kind === "Component" ? entity.ref : null);
+        if (owner) {
+          for (const rel of graph.relations) {
+            const bound = rel.type === "usesResource" && rel.sourceRef === owner ? rel.targetRef
+              : rel.type === "resourceUsedBy" && rel.targetRef === owner ? rel.sourceRef : null;
+            if (idx.byRef.get(bound)?.entity.spec.type === "logical-database") {
+              resources.add(bound);
+              because(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
@@ -129,6 +197,7 @@ export function impact(graph, changedPaths) {
       const user = rel.type === "usesResource" ? rel.sourceRef : rel.targetRef;
       if (r === bound) {
         add(user, "resource change touches " + bound);
+        for (const reason of migrationReasons.get(bound) || []) add(user, reason);
       }
     }
   }
@@ -180,7 +249,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;
+}