@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/lineage-init.ts

@@ -0,0 +1,365 @@
+/**
+ * The lineage lock at init (#2540, ws-047): `chant init --from <repo>@<ref>`
+ * and `chant init --template <name>` both leave `.chant/workspace.lock.json`
+ * with one lineage, scope `"."`, so a project made from a template can be
+ * upgraded later without first running adopt-lineage.
+ *
+ * `--from` fetches with `git`: the one network step, listed in the egress
+ * catalogue (`test/egress-catalogue.ts`). The commit and the tree of the
+ * chosen directory become the content address.
+ *
+ * Plain `chant init` without `--template` writes no lock. That keeps the
+ * output of an existing command unchanged (#2525 rule 2), and this module
+ * never loads for it.
+ */
+
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import {
+  LOCK_FILE,
+  LockError,
+  contentDigest,
+  declaredFilesAt,
+  emptyLock,
+  fileEntries,
+  readLock,
+  writeLock,
+  type Lineage,
+} from "./lineage-lock";
+import { MIGRATIONS_DIR } from "./lineage-migrations";
+import { TEMPLATE_MANIFEST, readManifest, resolveParameters, substituteParameters } from "./template-manifest";
+
+// ── The template spec ────────────────────────────────────────────────────────
+
+export interface TemplateSpec {
+  /** The repository as written. */
+  repo: string;
+  /** What `git fetch` is given: a URL, or an absolute local path. */
+  url: string;
+  ref: string;
+  /** The directory inside the repository to instantiate (`#<member>`). */
+  member?: string;
+  /** Stable identity: `<host>/<path>` for a remote, the path as written for a local repo, plus `#<member>`. */
+  id: string;
+}
+
+/**
+ * Parse `<repo>@<ref>[#<member>]`. `<repo>` is a git URL, an scp-style
+ * `git@host:path`, a local path, or `owner/name` for a GitHub repository.
+ */
+export function parseTemplateSpec(spec: string, cwd: string = process.cwd()): TemplateSpec {
+  let rest = spec.trim();
+  let member: string | undefined;
+  const hash = rest.lastIndexOf("#");
+  if (hash >= 0) {
+    member = rest.slice(hash + 1).replace(/^\/+|\/+$/g, "");
+    rest = rest.slice(0, hash);
+    if (!member || posix.normalize(member).startsWith("..")) throw new LockError(`--from ${spec}: "#${member}" is not a directory in the repository`);
+    member = posix.normalize(member);
+  }
+  const at = rest.lastIndexOf("@");
+  const lastSep = Math.max(rest.lastIndexOf("/"), rest.lastIndexOf(":"));
+  if (at <= 0 || at < lastSep || at === rest.length - 1) {
+    throw new LockError(`--from ${spec}: expected <repo>@<ref>[#<member>], e.g. acme/starter@v1.2.0`);
+  }
+  const repo = rest.slice(0, at);
+  const ref = rest.slice(at + 1);
+
+  let url: string;
+  let repoId: string;
+  const local = resolve(cwd, repo);
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(repo)) {
+    url = repo;
+    repoId = repo.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").replace(/^[^@/]*@/, "").replace(/\.git$/, "");
+  } else if (/^[^/@\s]+@[^:\s]+:/.test(repo)) {
+    url = repo;
+    repoId = repo.replace(/^[^@]+@/, "").replace(":", "/").replace(/\.git$/, "");
+  } else if (existsSync(local)) {
+    url = local;
+    repoId = repo;
+  } else if (/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+    url = `https://github.com/${repo}.git`;
+    repoId = `github.com/${repo.replace(/\.git$/, "")}`;
+  } else if (/^[\w.-]+\.[a-z]{2,}\/[\w./-]+$/i.test(repo)) {
+    url = `https://${repo}${repo.endsWith(".git") ? "" : ".git"}`;
+    repoId = repo.replace(/\.git$/, "");
+  } else {
+    throw new LockError(`--from ${spec}: "${repo}" is not a URL, a local repository or owner/name`);
+  }
+  return { repo, url, ref, member, id: member ? `${repoId}#${member}` : repoId };
+}
+
+// ── Fetch ────────────────────────────────────────────────────────────────────
+
+export interface FetchedTemplate {
+  commit: string;
+  tree: string;
+  /** Files under the chosen directory, relative to it. */
+  files: Map<string, { data: Buffer; executable: boolean }>;
+  /** Paths that were not copied, with the reason. */
+  skipped: Array<{ path: string; reason: string }>;
+}
+
+export function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    maxBuffer: 256 * 1024 * 1024,
+  }).trim();
+}
+
+/**
+ * Read the files of `member` (or the whole tree) at `commit` from a scratch
+ * repository that already holds the commit. Symbolic links, submodules and
+ * the template's own lineage lock are skipped, with the reason.
+ */
+export function readTemplateTree(
+  scratch: string,
+  commit: string,
+  member: string | undefined,
+  label: string,
+): { tree: string; files: FetchedTemplate["files"]; skipped: FetchedTemplate["skipped"] } {
+  let tree: string;
+  try {
+    tree = git(scratch, ["rev-parse", member ? `${commit}:${member}` : `${commit}^{tree}`]);
+    if (git(scratch, ["cat-file", "-t", tree]) !== "tree") throw new Error("not a tree");
+  } catch {
+    throw new LockError(`${label} has no directory ${member}`);
+  }
+
+  const files: FetchedTemplate["files"] = new Map();
+  const skipped: FetchedTemplate["skipped"] = [];
+  const listing = execFileSync("git", ["ls-tree", "-r", "-z", tree], { cwd: scratch, maxBuffer: 256 * 1024 * 1024 }).toString("utf-8");
+  for (const row of listing.split("\0")) {
+    if (!row) continue;
+    const tab = row.indexOf("\t");
+    const [mode, type, sha] = row.slice(0, tab).split(" ");
+    const path = row.slice(tab + 1);
+    if (path === LOCK_FILE) {
+      skipped.push({ path, reason: "the template's own lineage lock" });
+      continue;
+    }
+    if (type !== "blob") {
+      skipped.push({ path, reason: `a ${type === "commit" ? "submodule" : type}` });
+      continue;
+    }
+    if (mode === "120000") {
+      skipped.push({ path, reason: "a symbolic link" });
+      continue;
+    }
+    const data = execFileSync("git", ["cat-file", "blob", sha], { cwd: scratch, maxBuffer: 256 * 1024 * 1024 });
+    files.set(path, { data, executable: mode === "100755" });
+  }
+  return { tree, files, skipped };
+}
+
+/**
+ * Fetch one commit of the template repository into a scratch repository and
+ * read the files of the chosen directory from it. The template's own lock is
+ * never copied: it describes the template's lineage, not the new project's.
+ */
+export function fetchTemplate(spec: TemplateSpec): FetchedTemplate {
+  const scratch = mkdtempSync(join(tmpdir(), "chant-init-from-"));
+  try {
+    git(scratch, ["init", "-q"]);
+    try {
+      // The one network step of `chant init --from`, catalogued in test/egress-catalogue.ts.
+      git(scratch, ["fetch", "-q", "--depth", "1", spec.url, spec.ref]);
+    } catch (err) {
+      const stderr = (err as { stderr?: string }).stderr?.toString().trim();
+      throw new LockError(`could not fetch ${spec.repo}@${spec.ref}${stderr ? `: ${stderr}` : ""}`);
+    }
+    const commit = git(scratch, ["rev-parse", "FETCH_HEAD^{commit}"]);
+    return { commit, ...readTemplateTree(scratch, commit, spec.member, `${spec.repo}@${spec.ref}`) };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+// ── init --from ──────────────────────────────────────────────────────────────
+
+export interface InitFromOptions {
+  from: string;
+  /** Target directory (defaults to cwd). */
+  path?: string;
+  force?: boolean;
+  /** `--param name=value` values, parsed. Checked against the template's `chant.template.json` (#2627). */
+  params?: Record<string, string>;
+}
+
+export interface InitFromResult {
+  success: boolean;
+  createdFiles: string[];
+  warnings: string[];
+  error?: string;
+  spec?: TemplateSpec;
+  commit?: string;
+  /** The parameter values used, recorded in the lock. */
+  parameters?: Record<string, string>;
+}
+
+/** `chant init --from <repo>@<ref>[#<member>] [path]`. */
+export async function initFromCommand(options: InitFromOptions): Promise<InitFromResult> {
+  const targetDir = resolve(options.path ?? ".");
+  const warnings: string[] = [];
+  const createdFiles: string[] = [];
+
+  let spec: TemplateSpec;
+  try {
+    spec = parseTemplateSpec(options.from);
+  } catch (err) {
+    return { success: false, createdFiles, warnings, error: (err as Error).message };
+  }
+
+  if (existsSync(targetDir)) {
+    const visible = readdirSync(targetDir).filter((f) => !f.startsWith("."));
+    if (visible.length > 0 && !options.force) {
+      return { success: false, createdFiles, warnings, error: "Directory is not empty. Use --force to initialize anyway." };
+    }
+    if (visible.length > 0) warnings.push("Initializing in non-empty directory");
+  }
+  if (existsSync(join(targetDir, LOCK_FILE))) {
+    return { success: false, createdFiles, warnings, error: `${LOCK_FILE} already exists; this directory already has a lineage` };
+  }
+
+  let fetched: FetchedTemplate;
+  try {
+    fetched = fetchTemplate(spec);
+  } catch (err) {
+    return { success: false, createdFiles, warnings, error: (err as Error).message };
+  }
+  for (const s of fetched.skipped) {
+    if (s.path !== LOCK_FILE) warnings.push(`${s.path} is ${s.reason}, not copied`);
+  }
+
+  // Parameters (#2627): checked and substituted before anything is written,
+  // so a refused --param leaves the target untouched.
+  let parameters: Record<string, string>;
+  let contents: Map<string, Buffer>;
+  try {
+    const raw = new Map([...fetched.files].map(([path, f]) => [path, f.data]));
+    const manifest = readManifest(raw);
+    parameters = resolveParameters(manifest, options.params ?? {});
+    contents = substituteParameters(raw, manifest, parameters);
+  } catch (err) {
+    return { success: false, createdFiles, warnings, error: (err as Error).message };
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+  const written = new Map<string, Buffer>();
+  for (const [path, file] of [...fetched.files].sort(([a], [b]) => a.localeCompare(b))) {
+    // The template's migrations (#2550) and its manifest (#2627) are for chant, not part of a project.
+    if (path.startsWith(`${MIGRATIONS_DIR}/`) || path === TEMPLATE_MANIFEST) continue;
+    const data = contents.get(path)!;
+    const abs = join(targetDir, path);
+    if (existsSync(abs)) {
+      warnings.push(`${path} already exists, skipping`);
+      continue;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, data);
+    if (file.executable) chmodSync(abs, 0o755);
+    written.set(path, data);
+    createdFiles.push(path);
+  }
+
+  const lineage: Lineage = {
+    kind: "template",
+    template: spec.id,
+    source: { type: "git", repo: spec.repo, url: portableUrl(spec.url, targetDir), ...(spec.member ? { path: spec.member } : {}) },
+    ref: spec.ref,
+    address: { digest: contentDigest(written), commit: fetched.commit, tree: fetched.tree },
+    parameters,
+    migrations: [],
+    files: fileEntries(written, declaredFilesAt(targetDir)),
+    manualSteps: [],
+  };
+  const lock = emptyLock();
+  lock.scopes["."] = lineage;
+  writeLock(targetDir, lock);
+  createdFiles.push(LOCK_FILE);
+
+  return { success: true, createdFiles, warnings, spec, commit: fetched.commit, parameters };
+}
+
+/** A local repository is recorded relative to the project, so the lock does not name this machine's paths. */
+function portableUrl(url: string, targetDir: string): string {
+  if (!isAbsolute(url)) return url;
+  const rel = relative(targetDir, url).split(sep).join("/");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+// ── init --template ──────────────────────────────────────────────────────────
+
+/** The installed version of a lexicon package, or null when it cannot be found. */
+function lexiconPackageVersion(pkg: string, from: string): string | null {
+  for (const base of [join(from, "package.json"), import.meta.url]) {
+    try {
+      const require = createRequire(base);
+      let dir = dirname(require.resolve(pkg));
+      for (let i = 0; i < 6; i++) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate)) {
+          const json = JSON.parse(readFileSync(candidate, "utf-8")) as { name?: string; version?: string };
+          if (json.name === pkg) return json.version ?? null;
+        }
+        dir = dirname(dir);
+      }
+    } catch {
+      // Not resolvable from here; try the next base.
+    }
+  }
+  return null;
+}
+
+export interface TemplateLockInput {
+  targetDir: string;
+  lexicon: string;
+  template: string;
+  /** Files init wrote, relative to `targetDir`. */
+  createdFiles: string[];
+  chantVersion: string;
+  /** Set when the project's config declares the lexicon by path (#2520): the path, recorded instead of a package. */
+  lexiconModule?: string;
+}
+
+/**
+ * Record the lineage of a `chant init --template` project. Only files init
+ * actually wrote are listed; a file that already existed was not made from
+ * the template. `.chant/types/` is gitignored and left out (D14).
+ *
+ * Returns the lock's path relative to `targetDir`, or null when the target
+ * already has a lock (init never overwrites a lineage).
+ */
+export function writeTemplateLock(input: TemplateLockInput): string | null {
+  if (readLock(input.targetDir)) return null;
+  const files = new Map<string, Buffer>();
+  for (const rel of input.createdFiles) {
+    if (rel.startsWith(".chant/")) continue;
+    files.set(rel, readFileSync(join(input.targetDir, rel)));
+  }
+  const pkg = input.lexiconModule ?? `@intentius/chant-lexicon-${input.lexicon}`;
+  const lock = emptyLock();
+  lock.scopes["."] = {
+    kind: "template",
+    template: `lexicon:${input.lexicon}/${input.template}`,
+    source: { type: "lexicon", lexicon: input.lexicon, template: input.template },
+    address: {
+      digest: contentDigest(files),
+      package: pkg,
+      version: input.lexiconModule ? null : lexiconPackageVersion(pkg, input.targetDir),
+      chant: input.chantVersion,
+    },
+    parameters: {},
+    migrations: [],
+    files: fileEntries(files, declaredFilesAt(input.targetDir)),
+    manualSteps: [],
+  };
+  writeLock(input.targetDir, lock);
+  return LOCK_FILE;
+}

package/src/workspace/lineage-lock.test.ts

@@ -0,0 +1,224 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  LOCK_FILE,
+  LockError,
+  contentDigest,
+  emptyLock,
+  fileEntries,
+  fileHash,
+  readLock,
+  renderLock,
+  resolveManualStep,
+  scopeKey,
+  scopeStatus,
+  writeLock,
+  type Lineage,
+} from "./lineage-lock";
+import { applyUpstream } from "./lineage-update";
+import { contentHash } from "../cli/commands/vendor";
+
+let root: string;
+
+function put(rel: string, content: string): void {
+  const abs = join(root, rel);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+}
+const read = (rel: string) => readFileSync(join(root, rel), "utf-8");
+const files = (o: Record<string, string>) => new Map(Object.entries(o).map(([k, v]) => [k, Buffer.from(v)]));
+
+function vendorLineage(overrides: Partial<Lineage> = {}): Lineage {
+  return {
+    kind: "vendor",
+    name: "web",
+    template: "local:shared/web",
+    source: { type: "local", path: "shared/web" },
+    ref: "v1",
+    address: null,
+    parameters: {},
+    migrations: [],
+    files: {},
+    manualSteps: [],
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "chant-lineage-"));
+});
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("the lock file", () => {
+  test("round-trips, with scopes, files and steps in sorted order", () => {
+    const lock = emptyLock();
+    lock.scopes["vendor/web"] = vendorLineage({
+      address: { digest: contentDigest(files({ b: "2", a: "1" })) },
+      files: fileEntries(files({ "z.ts": "z", "a.ts": "a" })),
+    });
+    lock.scopes["."] = { ...vendorLineage(), kind: "template", name: undefined, template: "lexicon:aws/default" };
+    delete lock.scopes["."].name;
+    writeLock(root, lock);
+    const text = readFileSync(join(root, LOCK_FILE), "utf-8");
+    expect(Object.keys(JSON.parse(text).scopes)).toEqual([".", "vendor/web"]);
+    expect(Object.keys(JSON.parse(text).scopes["vendor/web"].files)).toEqual(["a.ts", "z.ts"]);
+    expect(readLock(root)).toEqual(JSON.parse(text));
+    expect(renderLock(readLock(root)!)).toBe(text);
+  });
+
+  test("no lock reads as null", () => {
+    expect(readLock(root)).toBeNull();
+  });
+
+  test("a newer lockVersion is refused by name", () => {
+    put(LOCK_FILE, JSON.stringify({ lockVersion: 2, scopes: {} }));
+    expect(() => readLock(root)).toThrow(/lockVersion 2; this chant reads up to 1/);
+  });
+
+  test("an invalid lock names the field", () => {
+    put(LOCK_FILE, JSON.stringify({ lockVersion: 1, scopes: { ".": { kind: "template" } } }));
+    expect(() => readLock(root)).toThrow(LockError);
+    expect(() => readLock(root)).toThrow(/scopes\.\.\.template/);
+  });
+
+  test("a scope key must be normal", () => {
+    const lock = emptyLock();
+    lock.scopes["./vendor/web/"] = vendorLineage();
+    put(LOCK_FILE, JSON.stringify(lock));
+    expect(() => readLock(root)).toThrow(/not in normal form/);
+  });
+
+  test("the digest is the vendor.json checksum", () => {
+    const set = files({ "b.ts": "b", "a/x.ts": "x" });
+    expect(contentDigest(set)).toBe(contentHash(set));
+  });
+});
+
+describe("scopeKey", () => {
+  test("normalises to posix relative form", () => {
+    expect(scopeKey("")).toBe(".");
+    expect(scopeKey("./")).toBe(".");
+    expect(scopeKey("vendor/web/")).toBe("vendor/web");
+    expect(scopeKey("./vendor//web")).toBe("vendor/web");
+  });
+  test("refuses paths outside the project", () => {
+    expect(() => scopeKey("../x")).toThrow(LockError);
+    expect(() => scopeKey("/abs")).toThrow(LockError);
+  });
+});
+
+describe("file classes", () => {
+  test("skills are generated by chant update, .mcp.json is a seed, the rest owned", () => {
+    const entries = fileEntries(files({ "skills/a/SKILL.md": "s", ".mcp.json": "{}", "src/x.ts": "x" }));
+    expect(entries["skills/a/SKILL.md"]).toMatchObject({ class: "generated", command: "chant update" });
+    expect(entries[".mcp.json"].class).toBe("seed");
+    expect(entries["src/x.ts"].class).toBe("owned");
+  });
+
+  test("status ignores generated files and reports edits and deletions", () => {
+    put("skills/a/SKILL.md", "edited");
+    put("src/x.ts", "x");
+    put("src/y.ts", "edited");
+    const lineage = vendorLineage({ files: fileEntries(files({ "skills/a/SKILL.md": "s", "src/x.ts": "x", "src/y.ts": "y", "src/z.ts": "z" })) });
+    const st = scopeStatus(root, ".", lineage);
+    expect(st.customised).toEqual(["src/y.ts"]);
+    expect(st.missing).toEqual(["src/z.ts"]);
+  });
+});
+
+describe("applyUpstream — local edits are never overwritten", () => {
+  const base = { "same.ts": "1", "edited.ts": "1", "both.ts": "1", "gone.ts": "1", "gone-edited.ts": "1", "deleted.ts": "1", "deleted-changed.ts": "1" };
+
+  function setup(): Lineage {
+    for (const [k, v] of Object.entries(base)) put(`t/${k}`, v);
+    const lineage = vendorLineage({ files: fileEntries(files(base)) });
+    put("t/edited.ts", "mine");
+    put("t/both.ts", "mine");
+    put("t/gone-edited.ts", "mine");
+    rmSync(join(root, "t/deleted.ts"));
+    rmSync(join(root, "t/deleted-changed.ts"));
+    put("t/untracked.ts", "mine");
+    put("t/collides.ts", "mine");
+    return lineage;
+  }
+
+  const upstream = files({
+    "same.ts": "2",
+    "edited.ts": "1",
+    "both.ts": "2",
+    "deleted.ts": "1",
+    "deleted-changed.ts": "2",
+    "collides.ts": "theirs",
+    "new.ts": "new",
+  });
+
+  test("each case in the table", () => {
+    const lineage = setup();
+    const result = applyUpstream(join(root, "t"), lineage, upstream);
+
+    expect(read("t/same.ts")).toBe("2");
+    expect(read("t/edited.ts")).toBe("mine");
+    expect(read("t/both.ts")).toBe("mine");
+    expect(existsSync(join(root, "t/gone.ts"))).toBe(false);
+    expect(read("t/gone-edited.ts")).toBe("mine");
+    expect(existsSync(join(root, "t/deleted.ts"))).toBe(false);
+    expect(existsSync(join(root, "t/deleted-changed.ts"))).toBe(false);
+    expect(read("t/untracked.ts")).toBe("mine");
+    expect(read("t/collides.ts")).toBe("mine");
+    expect(read("t/new.ts")).toBe("new");
+
+    expect(result.written.sort()).toEqual(["new.ts", "same.ts"]);
+    expect(result.removed).toEqual(["gone.ts"]);
+    expect(lineage.manualSteps.map((s) => [s.path, s.reason])).toEqual([
+      ["both.ts", "changed-locally"],
+      ["collides.ts", "exists-locally"],
+      ["deleted-changed.ts", "deleted-locally"],
+      ["gone-edited.ts", "removed-upstream"],
+    ]);
+    // Merge bases: advanced where the file was taken, kept where it was not.
+    expect(lineage.files["same.ts"].sha256).toBe(fileHash("2"));
+    expect(lineage.files["edited.ts"].sha256).toBe(fileHash("1"));
+    expect(lineage.files["both.ts"].sha256).toBe(fileHash("1"));
+    expect(lineage.files["gone.ts"]).toBeUndefined();
+    expect(lineage.files["untracked.ts"]).toBeUndefined();
+    expect(lineage.address?.digest).toBe(contentDigest(upstream));
+  });
+
+  test("a second pull of the same source changes nothing and keeps the steps", () => {
+    const lineage = setup();
+    applyUpstream(join(root, "t"), lineage, upstream);
+    const before = JSON.stringify(lineage);
+    const again = applyUpstream(join(root, "t"), lineage, upstream);
+    expect(again.written).toEqual([]);
+    expect(JSON.stringify(lineage)).toBe(before);
+  });
+
+  test("resolving a step moves the base to upstream, and the next pull keeps the file", () => {
+    const lineage = setup();
+    applyUpstream(join(root, "t"), lineage, upstream);
+    const lock = emptyLock();
+    lock.scopes["t"] = lineage;
+    expect(resolveManualStep(lock, "t/both.ts")?.step.reason).toBe("changed-locally");
+    expect(lineage.files["both.ts"].sha256).toBe(fileHash("2"));
+    expect(resolveManualStep(lock, "t/gone-edited.ts")?.step.upstream).toBeNull();
+    expect(lineage.files["gone-edited.ts"]).toBeUndefined();
+    expect(resolveManualStep(lock, "t/collides.ts")).not.toBeNull();
+    expect(lineage.files["collides.ts"].sha256).toBe(fileHash("theirs"));
+    expect(resolveManualStep(lock, "t/nope.ts")).toBeNull();
+
+    const again = applyUpstream(join(root, "t"), lineage, upstream);
+    expect(again.manualSteps.map((s) => s.path)).toEqual(["deleted-changed.ts"]);
+    expect(read("t/both.ts")).toBe("mine");
+  });
+
+  test("the deepest scope owns a path", () => {
+    const lock = emptyLock();
+    lock.scopes["."] = vendorLineage({ manualSteps: [{ path: "vendor/web/a.ts", reason: "changed-locally", upstream: fileHash("x") }] });
+    lock.scopes["vendor/web"] = vendorLineage({ manualSteps: [{ path: "a.ts", reason: "changed-locally", upstream: fileHash("y") }] });
+    expect(resolveManualStep(lock, "vendor/web/a.ts")?.scope).toBe("vendor/web");
+  });
+});