@intentius/chant 0.80.0 → 0.82.0

package/src/workspace/lineage-check.ts

@@ -0,0 +1,264 @@
+/**
+ * `chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]`:
+ * the lineage checks (#2550, D9), and the declaration checks (#2535, D16)
+ * when a declaration sits between the current directory and the git root.
+ *
+ * D9 says open manual steps fail `check`. So far, `check` checks the
+ * lineage lock only: the lock must be readable, and no scope may have an open
+ * manual step. It needs no `chant.workspace.json`, the way `chant workspace
+ * lineage` needs none, and a directory without a lock passes with nothing to
+ * check. The declaration checks report `WSP` findings through lint's
+ * reporters (`./checks.ts`), and cover member ledgers (#2538), recorded
+ * pipelines (#2542) and generated files (#2541) as well as the declaration
+ * itself (#2641). `--generated` runs each declared generator too.
+ *
+ * `chant workspace upgrade` runs the same checks in its staging worktree
+ * before it reaches its gate.
+ */
+
+import { realpathSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { formatError, formatSuccess } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import type { LintDiagnostic, LintRule } from "../lint/rule";
+import { findWorkspaceRoot } from "../project-root";
+import type { DeclarationCheckReport } from "./checks";
+import { LOCK_FILE, LockError, parseLock, readLock } from "./lineage-lock";
+import type { ReasonCode } from "./reason-codes";
+import type { WorkspaceTree } from "./tree";
+
+/** Closed: a reader may switch on it. */
+export const CHECK_CODES = ["lock-invalid", "manual-step-open"] as const satisfies readonly ReasonCode[];
+export type CheckCode = (typeof CHECK_CODES)[number];
+
+export interface CheckFinding {
+  code: CheckCode;
+  /** The scope the finding is in, or null for the lock as a whole. */
+  scope: string | null;
+  /** The file, relative to the lock's directory, when the finding is about one. */
+  path?: string;
+  message: string;
+}
+
+export interface CheckReport {
+  lock: string | null;
+  ok: boolean;
+  findings: CheckFinding[];
+}
+
+/**
+ * Run the lineage checks over the lock at `root`. Never throws a
+ * {@link LockError}. `lockText` is the lock's text when it comes from
+ * somewhere other than the disk, such as a revision (`--at`), with null
+ * for no lock.
+ */
+export function checkLineage(root: string, lockText?: string | null): CheckReport {
+  let lock;
+  try {
+    lock = lockText === undefined ? readLock(root) : lockText === null ? null : parseLock(lockText);
+  } catch (err) {
+    if (!(err instanceof LockError)) throw err;
+    return { lock: LOCK_FILE, ok: false, findings: [{ code: "lock-invalid", scope: null, path: LOCK_FILE, message: err.message }] };
+  }
+  if (!lock) return { lock: null, ok: true, findings: [] };
+  const findings: CheckFinding[] = [];
+  for (const [scope, lineage] of Object.entries(lock.scopes)) {
+    for (const step of lineage.manualSteps) {
+      const path = scope === "." ? step.path : `${scope}/${step.path}`;
+      findings.push({
+        code: "manual-step-open",
+        scope,
+        path,
+        message: `manual step open (${step.reason}): merge by hand, then \`chant workspace lineage resolve ${path}\``,
+      });
+    }
+  }
+  return { lock: LOCK_FILE, ok: findings.length === 0, findings };
+}
+
+/** A finding's identity, for comparing two reports. */
+export function findingKey(f: CheckFinding): string {
+  return `${f.code}\0${f.scope ?? ""}\0${f.path ?? ""}`;
+}
+
+const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]";
+const FORMATS = ["stylish", "json", "sarif"] as const;
+
+/** A lock finding as a lint diagnostic, for `--format json` and `--format sarif`. */
+function lockDiagnostic(f: CheckFinding): LintDiagnostic {
+  return { file: f.path ?? LOCK_FILE, line: 1, column: 1, ruleId: f.code, severity: "error", message: f.message };
+}
+
+const LOCK_RULES: LintRule[] = [
+  { id: "lock-invalid", severity: "error", category: "correctness", description: "The lineage lock can be read.", helpUri: "https://intentius.io/chant/cli/workspace-check/", check: () => [] },
+  {
+    id: "manual-step-open",
+    severity: "error",
+    category: "correctness",
+    description: "No scope in the lineage lock has an open manual step.",
+    helpUri: "https://intentius.io/chant/cli/workspace-check/",
+    check: () => [],
+  },
+];
+
+/** SARIF says `inSource` for a comment in the code; a declaration's `suppress` is `external`. */
+function markExternalSuppressions(sarif: string): string {
+  const doc = JSON.parse(sarif) as { runs: { results: { suppressions?: { kind: string }[] }[] }[] };
+  for (const run of doc.runs) for (const r of run.results) for (const s of r.suppressions ?? []) s.kind = "external";
+  return JSON.stringify(doc, null, 2);
+}
+
+/** The path from tree directory `from` to tree directory `to`, both relative to the git root. */
+function posixRelative(from: string, to: string): string {
+  return relative(`/${from}`, `/${to}`) || ".";
+}
+
+/** The version of the `check` document this chant writes. */
+export const CHECK_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the `--format json` output, shipped beside this file. */
+export const CHECK_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json";
+
+/** Why `check` could not run at all: only the `--at` codes. A declaration that can't be read is a WSP001 finding instead. */
+export const CHECK_ERROR_CODES = ["not-a-git-repository", "revision-unknown"] as const satisfies readonly ReasonCode[];
+export type CheckErrorCode = (typeof CHECK_ERROR_CODES)[number];
+
+/** What `check --format json` prints (#2536). `check.schema.json` describes it. */
+export type CheckDocument =
+  | (CheckReport & {
+      $schema: string;
+      contract: number;
+      chant: string;
+      at: string | null;
+      /** The declaration's workspace, or null when there is none; `name` is null when it can't be read. */
+      workspace: { name: string | null; root: string } | null;
+      declaration?: DeclarationCheckReport;
+    })
+  | { $schema: string; contract: number; chant: string; error: { code: CheckErrorCode; message: string; location: null } };
+
+/**
+ * Run every check from `cwd`, in the working tree or at revision `at`, and
+ * build the document the JSON formats print. Paths in findings are relative
+ * to `cwd`. `runGenerators` is `--generated`; with `at` it does nothing,
+ * since the member facts describe the working tree, not the revision.
+ */
+export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean } = {}): Promise<CheckDocument> {
+  // Loaded here, not at the top: `workspace upgrade` imports this module for checkLineage alone.
+  const [{ findDeclarationDir, readDeclaration, readerVersion }, { gitTop, gitTree, resolveCommit, workingTree }] = await Promise.all([
+    import("./declaration"),
+    import("./tree"),
+  ]);
+  const head = { $schema: CHECK_OUTPUT_SCHEMA_ID, contract: CHECK_CONTRACT_VERSION, chant: readerVersion() };
+  let report: CheckReport;
+  /** The declaration's directory on disk, its root relative to the git root, and the files to check. */
+  let found: { dir: string; root: string; tree: WorkspaceTree } | undefined;
+  let commit: string | null = null;
+  if (at === undefined) {
+    report = checkLineage(cwd);
+    // Declaration checks run when a declaration sits between here and the git
+    // root (#2535). Without one the command stays a lock check.
+    const f = findWorkspaceRoot(cwd);
+    if (f) {
+      const top = gitTop(f.dir);
+      const rel = top ? relative(top, realpathSync(f.dir)).split(sep).join("/") : f.dir;
+      found = { dir: f.dir, root: rel === "" ? "." : rel, tree: workingTree(f.dir) };
+    }
+  } else {
+    const top = gitTop(cwd);
+    if (!top) return { ...head, error: { code: "not-a-git-repository", message: "--at reads git objects, and this directory is not in a git repository", location: null } };
+    const c = resolveCommit(top, at);
+    if (!c) return { ...head, error: { code: "revision-unknown", message: `--at ${at} names no commit in this repository`, location: null } };
+    commit = c;
+    const rel = relative(top, realpathSync(resolve(cwd))).split(sep).join("/");
+    const start = rel.startsWith("..") ? "" : rel;
+    const whole = gitTree(top, c);
+    const lockAt = start ? `${start}/${LOCK_FILE}` : LOCK_FILE;
+    report = checkLineage(cwd, whole.stat(lockAt) === "file" ? whole.read(lockAt) : null);
+    const dir = findDeclarationDir(whole, start);
+    // The root on disk is reached from cwd, so paths print relative to cwd as it was given.
+    if (dir !== undefined) found = { dir: resolve(cwd, posixRelative(start, dir)), root: dir === "" ? "." : dir, tree: dir === "" ? whole : gitTree(top, c, dir) };
+  }
+
+  let declaration: DeclarationCheckReport | undefined;
+  let workspace: { name: string | null; root: string } | null = null;
+  if (found) {
+    const { runDeclarationChecks } = await import("./checks");
+    const { dir, tree } = found;
+    declaration = await runDeclarationChecks(dir, (file) => relative(cwd, join(dir, file)).split(sep).join("/"), {
+      runGenerators: options.runGenerators === true,
+      ...(commit !== null ? { tree } : {}),
+    });
+    let name: string | null = null;
+    try {
+      name = readDeclaration(tree, "", { rootChant: true }).name;
+    } catch {
+      // The WSP001 finding already says why.
+    }
+    workspace = { name, root: found.root };
+  }
+  const ok = report.ok && (declaration?.ok ?? true);
+  return { ...head, at: commit, workspace, ...report, ok, ...(declaration ? { declaration } : {}) };
+}
+
+export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
+  const root = process.cwd();
+  if (ctx.args.extraPositional) {
+    console.error(formatError({ message: `chant workspace check takes no argument (got ${ctx.args.extraPositional})`, hint: USAGE }));
+    return 1;
+  }
+  const format = (ctx.args.format || "stylish") as (typeof FORMATS)[number];
+  if (!FORMATS.includes(format)) {
+    console.error(formatError({ message: `--format ${format} is not a check format; use stylish, json or sarif`, hint: USAGE }));
+    return 1;
+  }
+  // The root's chant reads the declaration (ws-021). Only a workspace with a
+  // declaration loads this.
+  if (ctx.args.at !== undefined || findWorkspaceRoot(root)) {
+    const { handToRootChant } = await import("./which-chant");
+    const handed = await handToRootChant(root, ctx.args.at);
+    if (handed !== undefined) return handed;
+  }
+  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true });
+  if ("error" in doc) {
+    if (ctx.args.json || format === "json") console.log(JSON.stringify(doc, null, 2));
+    else console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  const { declaration, ok } = doc;
+  const report = { lock: doc.lock, findings: doc.findings };
+
+  // --format json is the read contract's document. --json keeps the shape it
+  // had before the contract, the lineage report with `declaration` beside it.
+  if (format === "json") {
+    console.log(JSON.stringify(doc, null, 2));
+    return ok ? 0 : 1;
+  }
+  if (ctx.args.json) {
+    console.log(JSON.stringify({ lock: doc.lock, ok, findings: doc.findings, ...(declaration ? { declaration } : {}) }, null, 2));
+    return ok ? 0 : 1;
+  }
+  // The reporters load only when there is something to report through them,
+  // so a plain lock check loads what it did before.
+  if (format === "sarif") {
+    const { formatSarif } = await import("../cli/reporters/stylish");
+    const diagnostics = [...report.findings.map(lockDiagnostic), ...(declaration?.diagnostics ?? [])];
+    const suppressed = declaration?.suppressed ?? [];
+    const { workspaceCheckRules } = await import("./checks");
+    console.log(markExternalSuppressions(formatSarif(diagnostics, [...LOCK_RULES, ...workspaceCheckRules()], suppressed, doc.chant)));
+    return ok ? 0 : 1;
+  }
+
+  if (!report.lock) {
+    if (!declaration) console.error(formatSuccess(`no ${LOCK_FILE}: nothing to check`));
+  } else if (report.findings.length === 0) {
+    console.error(formatSuccess(`${LOCK_FILE}: no open manual steps`));
+  } else {
+    for (const f of report.findings) console.error(`  ${f.path ?? f.scope ?? ""}: ${f.message}`);
+    console.error(formatError({ message: `${report.findings.length} check(s) failed` }));
+  }
+  if (declaration) {
+    const { formatStylish } = await import("../cli/reporters/stylish");
+    console.log(formatStylish(declaration.diagnostics, declaration.suppressed));
+  }
+  return ok ? 0 : 1;
+}

package/src/workspace/lineage-cli.ts

@@ -0,0 +1,134 @@
+/**
+ * `chant workspace lineage [--json]` and
+ * `chant workspace lineage resolve <path>` (#2540).
+ *
+ * The first shows each scope in `.chant/workspace.lock.json`: where it came
+ * from, which files the project has edited since, and which manual steps are
+ * open. The second closes a manual step once the file has been merged by
+ * hand. Neither needs a `chant.workspace.json`: lineage works for a plain
+ * project (#2525 rule 4).
+ */
+
+import { formatError, formatSuccess } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { LOCK_FILE, LockError, readLock, resolveManualStep, scopeStatus, writeLock, type LineageSource, type ManualStep } from "./lineage-lock";
+
+const USAGE = "chant workspace lineage [--json] | chant workspace lineage resolve <path>";
+
+export interface LineageScopeView {
+  scope: string;
+  kind: "template" | "vendor";
+  name?: string;
+  template: string;
+  /** Where the files came from, as the lock records it: its `type` and the repository, directory, lexicon or URL. */
+  source: LineageSource;
+  ref?: string;
+  address: Record<string, unknown> | null;
+  files: number;
+  edited: string[];
+  missing: string[];
+  manualSteps: ManualStep[];
+}
+
+/** One line naming a scope's source kind and where it points (#2647). */
+export function describeSource(source: LineageSource): string {
+  switch (source.type) {
+    case "git":
+      return `git ${source.repo}${source.path ? `#${source.path}` : ""}`;
+    case "dir":
+      return `dir ${source.path}${source.member ? `#${source.member}` : ""}`;
+    case "lexicon":
+      return `lexicon ${source.lexicon}/${source.template}`;
+    case "local":
+      return `local ${source.path}`;
+    case "archive":
+      return `archive ${source.url}${source.subpath ? `#${source.subpath}` : ""}`;
+  }
+}
+
+/** The lock as `--json` prints it: one view per scope, with its state in the tree. */
+export function lineageView(root: string): { lock: string; scopes: LineageScopeView[] } | null {
+  const lock = readLock(root);
+  if (!lock) return null;
+  const scopes = Object.entries(lock.scopes).map(([scope, lineage]) => {
+    const st = scopeStatus(root, scope, lineage);
+    return {
+      scope,
+      kind: lineage.kind,
+      ...(lineage.name !== undefined ? { name: lineage.name } : {}),
+      template: lineage.template,
+      source: lineage.source,
+      ...(lineage.ref !== undefined ? { ref: lineage.ref } : {}),
+      address: lineage.address,
+      files: Object.keys(lineage.files).length,
+      edited: st.customised,
+      missing: st.missing,
+      manualSteps: lineage.manualSteps,
+    };
+  });
+  return { lock: LOCK_FILE, scopes };
+}
+
+export async function runWorkspaceLineage(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const root = process.cwd();
+  try {
+    if (args.extraPositional === "resolve") return resolve(root, args.extraPositional2);
+    if (args.extraPositional) {
+      console.error(formatError({ message: `Unknown lineage subcommand: ${args.extraPositional}`, hint: USAGE }));
+      return 1;
+    }
+    const view = lineageView(root);
+    if (!view) {
+      console.error(formatError({ message: `no ${LOCK_FILE} in ${root}`, hint: "chant init --from or --template writes one; so does chant vendor migrate" }));
+      return 1;
+    }
+    if (args.json) {
+      console.log(JSON.stringify(view, null, 2));
+      return 0;
+    }
+    const lines: string[] = [];
+    for (const s of view.scopes) {
+      const pin = s.ref ? `@${s.ref}` : "";
+      const at = typeof s.address?.commit === "string" ? ` (${s.address.commit.slice(0, 12)})` : "";
+      lines.push(`${s.scope}  ${s.kind}${s.name ? ` ${s.name}` : ""}  ${s.template}${pin}${at}`);
+      lines.push(`  source: ${describeSource(s.source)}`);
+      lines.push(`  ${s.files} file(s), ${s.edited.length} edited, ${s.missing.length} deleted`);
+      for (const m of s.manualSteps) lines.push(`  manual step: ${s.scope === "." ? "" : `${s.scope}/`}${m.path} (${m.reason})`);
+    }
+    const open = view.scopes.reduce((n, s) => n + s.manualSteps.length, 0);
+    lines.push(`${view.scopes.length} scope(s), ${open} manual step(s) open`);
+    console.log(lines.join("\n"));
+    return 0;
+  } catch (err) {
+    if (!(err instanceof LockError)) throw err;
+    console.error(formatError({ message: err.message }));
+    return 1;
+  }
+}
+
+function resolve(root: string, path: string | undefined): number {
+  if (!path) {
+    console.error(formatError({ message: "resolve needs the path of a file with an open manual step", hint: USAGE }));
+    return 1;
+  }
+  const lock = readLock(root);
+  if (!lock) {
+    console.error(formatError({ message: `no ${LOCK_FILE} in ${root}` }));
+    return 1;
+  }
+  const closed = resolveManualStep(lock, path);
+  if (!closed) {
+    console.error(formatError({ message: `no open manual step for ${path}`, hint: "chant workspace lineage lists them" }));
+    return 1;
+  }
+  writeLock(root, lock);
+  console.error(
+    formatSuccess(
+      closed.step.upstream === null
+        ? `${path}: the source removed this file; it is now the project's own`
+        : `${path}: resolved; the file as it stands is kept, and the source's version is its new merge base`,
+    ),
+  );
+  return 0;
+}

package/src/workspace/lineage-init-dir.test.ts

@@ -0,0 +1,243 @@
+/**
+ * chant #2647: `chant init --from <dir>[#<member>]`, a template directory on
+ * disk. The same files and parameters as the git form for the same tree, a
+ * lock whose address is the digest alone, and `chant workspace upgrade`
+ * from a directory, which rebuilds its merge base only while the recorded
+ * directory still holds what the scope was made from.
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { initFromCommand, parseDirSpec, recordedDirPath } from "./lineage-init";
+import { LOCK_FILE, readLock } from "./lineage-lock";
+import { describeSource, lineageView } from "./lineage-cli";
+import { stageUpgrade, type ChantRunner } from "./lineage-upgrade";
+
+const ENV = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" };
+
+let root: string;
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", env: ENV, stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function put(base: string, rel: string, content: string): void {
+  mkdirSync(dirname(join(base, rel)), { recursive: true });
+  writeFileSync(join(base, rel), content);
+}
+function read(base: string, rel: string): string {
+  return readFileSync(join(base, rel), "utf-8");
+}
+/** Every file under `dir` except the lock, with its content and executable bit. */
+function tree(dir: string, prefix = ""): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const e of readdirSync(join(dir, prefix), { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (e.isDirectory()) Object.assign(out, tree(dir, rel));
+    else if (rel !== LOCK_FILE) out[rel] = `${statSync(join(dir, rel)).mode & 0o100 ? "x " : ""}${readFileSync(join(dir, rel), "utf-8")}`;
+  }
+  return out;
+}
+
+/** A template directory with a manifest, an executable, a seed and a lock of its own. */
+function writeTemplate(dir: string, version = "1"): void {
+  put(dir, "svc/README.md", `template v${version}\n`);
+  put(dir, "svc/src/main.ts", 'export const name = "{{chant:name}}";\n');
+  put(dir, "svc/run.sh", "#!/bin/sh\n");
+  execFileSync("chmod", ["+x", join(dir, "svc/run.sh")]);
+  put(dir, "svc/.mcp.json", "{}\n");
+  put(dir, `svc/${LOCK_FILE}`, JSON.stringify({ lockVersion: 1, scopes: {} }));
+  put(
+    dir,
+    "svc/chant.template.json",
+    JSON.stringify({ parameters: { name: { type: "string", default: "app" }, owner: { type: "string", default: "ops" } }, files: ["src/main.ts"] }),
+  );
+}
+
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), "chant-init-dir-test-")));
+  vi.spyOn(console, "log").mockImplementation(() => undefined);
+  vi.spyOn(console, "error").mockImplementation(() => undefined);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("parseDirSpec", () => {
+  test("an existing directory is the directory form, with or without #<member>", () => {
+    mkdirSync(join(root, "tpl", "svc"), { recursive: true });
+    expect(parseDirSpec("tpl#svc", root)).toEqual({ kind: "dir", path: "tpl", abs: join(root, "tpl"), member: "svc" });
+    expect(parseDirSpec(join(root, "tpl"), root)).toEqual({ kind: "dir", path: join(root, "tpl"), abs: join(root, "tpl") });
+  });
+  test("a directory whose name parses as <repo>@<ref> is still a directory", () => {
+    mkdirSync(join(root, "starter@v1"));
+    expect(parseDirSpec("starter@v1", root)).toMatchObject({ kind: "dir", abs: join(root, "starter@v1") });
+  });
+  test("<repo>@<ref> with no such directory is the git form", () => {
+    expect(parseDirSpec("acme/starter@v1.2.0#service", root)).toBeNull();
+  });
+  test("a path with no @ that is not a directory is refused", () => {
+    expect(() => parseDirSpec("missing", root)).toThrow(/no directory missing, and not <repo>@<ref>/);
+    put(root, "file", "x");
+    expect(() => parseDirSpec("file", root)).toThrow(/file is not a directory/);
+    mkdirSync(join(root, "tpl"));
+    expect(() => parseDirSpec("tpl#../x", root)).toThrow(/not a directory in the directory/);
+  });
+  test("a relative directory is recorded from the project, an absolute one as given", () => {
+    expect(recordedDirPath("../tpl", join(root, "tpl"), join(root, "proj"))).toBe("../tpl");
+    expect(recordedDirPath("tpl", join(root, "tpl"), root)).toBe("./tpl");
+    expect(recordedDirPath(join(root, "tpl"), join(root, "tpl"), join(root, "proj"))).toBe(join(root, "tpl"));
+  });
+});
+
+describe("chant init --from <dir>", () => {
+  test("copies the same files, with the same parameters and digest, as the git form of the same tree", async () => {
+    const tpl = join(root, "tpl");
+    writeTemplate(tpl);
+    git(tpl, ["init", "-q", "-b", "main"]);
+    git(tpl, ["add", "-A"]);
+    git(tpl, ["commit", "-q", "-m", "v1"]);
+
+    const fromGit = await initFromCommand({ from: `${tpl}@main#svc`, path: join(root, "a"), params: { name: "billing" } });
+    const fromDir = await initFromCommand({ from: `${tpl}#svc`, path: join(root, "b"), params: { name: "billing" } });
+    expect(fromGit.error).toBeUndefined();
+    expect(fromDir.error).toBeUndefined();
+    expect(fromDir.createdFiles).toEqual(fromGit.createdFiles);
+    expect(tree(join(root, "b"))).toEqual(tree(join(root, "a")));
+    expect(read(join(root, "b"), "src/main.ts")).toBe('export const name = "billing";\n');
+    expect(statSync(join(root, "b", "run.sh")).mode & 0o111).not.toBe(0);
+    expect(existsSync(join(root, "b", "chant.template.json"))).toBe(false);
+
+    const a = readLock(join(root, "a"))!.scopes["."];
+    const b = readLock(join(root, "b"))!.scopes["."];
+    expect(b.parameters).toEqual({ name: "billing", owner: "ops" });
+    expect(b.parameters).toEqual(a.parameters);
+    expect(b.files).toEqual(a.files);
+    expect(b.address).toEqual({ digest: a.address!.digest });
+    // The lock shape: the digest alone, a dir source, no ref.
+    expect(b.source).toEqual({ type: "dir", path: tpl, member: "svc" });
+    expect(b.template).toBe(`dir:${tpl}#svc`);
+    expect(b.ref).toBeUndefined();
+    expect(fromDir.template).toBe(`dir:${tpl}#svc`);
+    expect(fromDir.commit).toBeUndefined();
+    expect(a.source).toMatchObject({ type: "git", path: "svc" });
+  });
+
+  test("inside a git checkout, .gitignore is respected and untracked files are copied", async () => {
+    const tpl = join(root, "tpl");
+    git(root, ["init", "-q", "-b", "main"]);
+    put(tpl, "keep.ts", "keep\n");
+    put(tpl, ".gitignore", "out/\n*.log\n");
+    put(tpl, "out/built.js", "built\n");
+    put(tpl, "debug.log", "noise\n");
+    git(root, ["add", "tpl/keep.ts", "tpl/.gitignore"]);
+    git(root, ["commit", "-q", "-m", "t"]);
+    put(tpl, "untracked.ts", "new\n");
+
+    const result = await initFromCommand({ from: tpl, path: join(root, "proj") });
+    expect(result.error).toBeUndefined();
+    expect(result.createdFiles.sort()).toEqual([".gitignore", LOCK_FILE, "keep.ts", "untracked.ts"].sort());
+  });
+
+  test("outside git every file is copied, except node_modules, symbolic links and the template's own lock", async () => {
+    const tpl = join(root, "tpl");
+    writeTemplate(tpl);
+    put(tpl, "svc/.gitignore", "*.log\n");
+    put(tpl, "svc/debug.log", "copied: no git to read .gitignore\n");
+    put(tpl, "svc/node_modules/dep/index.js", "x\n");
+    symlinkSync("README.md", join(tpl, "svc", "link.md"));
+
+    const result = await initFromCommand({ from: `${tpl}#svc`, path: join(root, "proj") });
+    expect(result.error).toBeUndefined();
+    expect(result.createdFiles.sort()).toEqual([".gitignore", ".mcp.json", LOCK_FILE, "README.md", "debug.log", "run.sh", "src/main.ts"].sort());
+    expect(result.warnings).toEqual(["link.md is a symbolic link, not copied", "node_modules is node_modules, not copied"]);
+    expect(readLock(join(root, "proj"))!.scopes["."].files).not.toHaveProperty(LOCK_FILE);
+  });
+
+  test("refuses a missing member, a missing directory and an undeclared --param, writing nothing", async () => {
+    const tpl = join(root, "tpl");
+    writeTemplate(tpl);
+    const target = join(root, "proj");
+    expect((await initFromCommand({ from: `${tpl}#nope`, path: target })).error).toBe(`${tpl} has no directory nope`);
+    expect((await initFromCommand({ from: join(root, "missing"), path: target })).error).toMatch(/no directory .*missing, and not <repo>@<ref>/);
+    expect((await initFromCommand({ from: `${tpl}#svc`, path: target, params: { title: "x" } })).error).toBe("unknown parameter title (declared: name, owner)");
+    expect(existsSync(target)).toBe(false);
+  });
+
+  test("chant workspace lineage names the source kind and path", async () => {
+    const tpl = join(root, "tpl");
+    writeTemplate(tpl);
+    await initFromCommand({ from: `${tpl}#svc`, path: join(root, "proj") });
+    const view = lineageView(join(root, "proj"))!;
+    expect(view.scopes[0].source).toEqual({ type: "dir", path: tpl, member: "svc" });
+    expect(describeSource(view.scopes[0].source)).toBe(`dir ${tpl}#svc`);
+    expect(describeSource({ type: "git", repo: "acme/starter", url: "https://github.com/acme/starter.git", path: "svc" })).toBe("git acme/starter#svc");
+  });
+});
+
+describe("chant workspace upgrade on a directory scope", () => {
+  const passing: ChantRunner = async () => ({ exitCode: 0, output: "" });
+  let v1: string;
+  let v2: string;
+  let proj: string;
+
+  beforeEach(async () => {
+    v1 = join(root, "bundle-v1");
+    v2 = join(root, "bundle-v2");
+    proj = join(root, "proj");
+    writeTemplate(v1);
+    put(v1, "svc/src/lib.ts", "one\ntwo\nthree\nfour\nfive\nsix\nseven\n");
+    const made = await initFromCommand({ from: `${v1}#svc`, path: proj, params: { name: "billing" } });
+    expect(made.error).toBeUndefined();
+    git(proj, ["init", "-q", "-b", "main"]);
+    put(proj, "src/lib.ts", "ONE (ours)\ntwo\nthree\nfour\nfive\nsix\nseven\n");
+    git(proj, ["add", "-A"]);
+    git(proj, ["commit", "-q", "-m", "init and edit"]);
+
+    cpSync(v1, v2, { recursive: true });
+    put(v2, "svc/README.md", "template v2\n");
+    put(v2, "svc/src/lib.ts", "one\ntwo\nthree\nfour\nfive\nsix\nSEVEN (theirs)\n");
+    put(v2, "svc/src/new.ts", "new\n");
+  });
+
+  test("without --to it refuses, naming adopt-lineage", async () => {
+    await expect(stageUpgrade({ root: proj, runChant: passing })).rejects.toThrow(/no --to directory\. .*has no git history.*chant workspace adopt-lineage/);
+  });
+
+  test("with --to a directory, the recorded directory is the merge base while it holds the same digest", async () => {
+    const staged = await stageUpgrade({ root: proj, to: v2, runChant: passing });
+    try {
+      expect(staged.merged).toEqual(["src/lib.ts"]);
+      expect(staged.written.sort()).toEqual(["README.md", "src/new.ts"]);
+      expect(staged.manualSteps).toEqual([]);
+      expect(staged.from).toBe(`${v1}#svc`);
+      expect(staged.to).toBe(`${v2}#svc`);
+      expect(read(staged.worktreeProject, "src/lib.ts")).toBe("ONE (ours)\ntwo\nthree\nfour\nfive\nsix\nSEVEN (theirs)\n");
+      // The parameter carried into the new version's files.
+      expect(read(staged.worktreeProject, "src/main.ts")).toBe('export const name = "billing";\n');
+      const lock = readLock(staged.worktreeProject)!.scopes["."];
+      expect(lock.source).toEqual({ type: "dir", path: v2, member: "svc" });
+      expect(Object.keys(lock.address!)).toEqual(["digest"]);
+      expect(lock.ref).toBeUndefined();
+      expect(lock.parameters).toEqual({ name: "billing", owner: "ops" });
+    } finally {
+      staged.dispose();
+    }
+  });
+
+  test("refuses when the recorded directory changed or is gone, naming adopt-lineage", async () => {
+    put(v1, "svc/README.md", "replaced in place\n");
+    await expect(stageUpgrade({ root: proj, to: v2, runChant: passing })).rejects.toThrow(
+      /no longer holds the files the scope was made from.*chant workspace adopt-lineage/,
+    );
+    rmSync(v1, { recursive: true, force: true });
+    await expect(stageUpgrade({ root: proj, to: v2, runChant: passing })).rejects.toThrow(/is gone\. .*chant workspace adopt-lineage/);
+  });
+
+  test("--to must be a directory", async () => {
+    await expect(stageUpgrade({ root: proj, to: "v2.0.0", runChant: passing })).rejects.toThrow(/--to v2\.0\.0: a scope made from a directory upgrades from a directory/);
+  });
+});