@intentius/chant 0.79.0 → 0.81.0

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

@@ -0,0 +1,126 @@
+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 { MANIFEST_FILE, loadManifest, vendorPull } from "../cli/commands/vendor";
+import { LOCK_FILE, readLock, resolveManualStep, writeLock } from "./lineage-lock";
+import { checkLockedScopes, migrateVendorManifest, pullLockedScopes } from "./lineage-vendor";
+
+let root: string;
+
+function put(rel: string, content: string): void {
+  mkdirSync(dirname(join(root, rel)), { recursive: true });
+  writeFileSync(join(root, rel), content);
+}
+const read = (rel: string) => readFileSync(join(root, rel), "utf-8");
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "chant-lineage-vendor-"));
+  put("shared/web/index.ts", "export const v = 1;\n");
+  put("shared/web/README.md", "# web\n");
+  put(
+    MANIFEST_FILE,
+    JSON.stringify({
+      vendored: [
+        { name: "web", source: { type: "local", path: "shared/web" }, target: "vendor/web", ref: "v1" },
+        { name: "later", source: { type: "local", path: "shared/web" }, target: "vendor/later" },
+      ],
+    }),
+  );
+});
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("chant vendor migrate", () => {
+  test("moves every entry into the lock as a vendor scope and removes vendor.json", async () => {
+    await vendorPull(root, "web");
+    const checksum = loadManifest(root).manifest.vendored[0].checksum;
+    const result = await migrateVendorManifest(root);
+    expect(result).toEqual({
+      migrated: [
+        { name: "web", target: "vendor/web", files: 2, pinned: true },
+        { name: "later", target: "vendor/later", files: 0, pinned: false },
+      ],
+      lockCreated: true,
+    });
+    expect(existsSync(join(root, MANIFEST_FILE))).toBe(false);
+    const lock = readLock(root)!;
+    expect(lock.scopes["vendor/web"]).toMatchObject({
+      kind: "vendor",
+      name: "web",
+      template: "local:shared/web",
+      source: { type: "local", path: "shared/web" },
+      ref: "v1",
+      address: { digest: checksum },
+      parameters: {},
+      migrations: [],
+    });
+    expect(Object.keys(lock.scopes["vendor/web"].files)).toEqual(["README.md", "index.ts"]);
+    expect(lock.scopes["vendor/later"].address).toBeNull();
+  });
+
+  test("an edited target takes its merge bases from the source when the source still matches", async () => {
+    await vendorPull(root, "web");
+    put("vendor/web/index.ts", "mine\n");
+    await migrateVendorManifest(root);
+    expect(checkLockedScopes(root).find((c) => c.name === "web")).toMatchObject({ status: "customised", customised: ["index.ts"] });
+  });
+
+  test("refuses, writing nothing, when the pinned content cannot be recovered", async () => {
+    await vendorPull(root, "web");
+    put("vendor/web/index.ts", "mine\n");
+    put("shared/web/index.ts", "moved on\n");
+    await expect(migrateVendorManifest(root)).rejects.toThrow(/cannot be recovered/);
+    expect(existsSync(join(root, MANIFEST_FILE))).toBe(true);
+    expect(existsSync(join(root, LOCK_FILE))).toBe(false);
+  });
+
+  test("keeps scopes already in the lock and refuses a clash", async () => {
+    await migrateVendorManifest(root);
+    put(MANIFEST_FILE, JSON.stringify({ vendored: [{ name: "web", source: { type: "local", path: "shared/web" }, target: "vendor/other" }] }));
+    await expect(migrateVendorManifest(root)).rejects.toThrow(/already has a vendor scope with that name/);
+    put(MANIFEST_FILE, JSON.stringify({ vendored: [{ name: "x", source: { type: "local", path: "shared/web" }, target: "vendor/web/" }] }));
+    await expect(migrateVendorManifest(root)).rejects.toThrow(/already has a scope at vendor\/web/);
+  });
+});
+
+describe("chant vendor pull through the lock", () => {
+  test("keeps local edits, applies clean updates and records conflicts as manual steps", async () => {
+    await vendorPull(root);
+    await migrateVendorManifest(root);
+    put("vendor/web/index.ts", "mine\n");
+    put("vendor/web/local-only.ts", "mine\n");
+    put("shared/web/index.ts", "export const v = 2;\n");
+    put("shared/web/README.md", "# web v2\n");
+
+    const [web] = await pullLockedScopes(root, "web");
+    expect(web).toMatchObject({ name: "web", target: "vendor/web", written: 1, kept: 1 });
+    expect(web.manualSteps.map((s) => [s.path, s.reason])).toEqual([["index.ts", "changed-locally"]]);
+    expect(read("vendor/web/index.ts")).toBe("mine\n");
+    expect(read("vendor/web/README.md")).toBe("# web v2\n");
+    expect(read("vendor/web/local-only.ts")).toBe("mine\n");
+
+    expect(checkLockedScopes(root).find((c) => c.name === "web")?.status).toBe("manual");
+
+    const lock = readLock(root)!;
+    resolveManualStep(lock, "vendor/web/index.ts");
+    writeLock(root, lock);
+    expect(checkLockedScopes(root).find((c) => c.name === "web")).toMatchObject({ status: "customised", customised: ["index.ts"] });
+  });
+
+  test("an unpinned scope is populated by its first pull", async () => {
+    await migrateVendorManifest(root);
+    expect(checkLockedScopes(root).find((c) => c.name === "later")?.status).toBe("unpinned");
+    await pullLockedScopes(root, "later");
+    expect(read("vendor/later/index.ts")).toBe("export const v = 1;\n");
+    expect(checkLockedScopes(root).find((c) => c.name === "later")?.status).toBe("ok");
+  });
+
+  test("a deleted target is missing", async () => {
+    await vendorPull(root, "web");
+    await migrateVendorManifest(root);
+    rmSync(join(root, "vendor/web"), { recursive: true });
+    expect(checkLockedScopes(root).find((c) => c.name === "web")?.status).toBe("missing");
+  });
+});

package/src/workspace/lineage-vendor.ts

@@ -0,0 +1,215 @@
+/**
+ * `chant vendor` over the lineage lock (#2540, ws-038).
+ *
+ * A vendored target is one lineage scope of kind `vendor`: copied, with no
+ * parameters. `pull` updates it file by file through {@link applyUpstream}, so
+ * local edits survive and a file both sides changed becomes a manual step.
+ * `check` reports edits and fails on open manual steps.
+ *
+ * `vendor.json` is still read. A project whose lock has no vendor scopes and
+ * which never ran `chant vendor migrate` keeps today's `vendor.json` behaviour
+ * byte for byte (#2525 rule 2): this module loads only when a lock exists or
+ * `migrate` runs.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  MANIFEST_FILE,
+  contentHash,
+  loadManifest,
+  readTarget,
+  resolveVendorSource,
+  type VendorEntry,
+} from "../cli/commands/vendor";
+import { LOCK_FILE, LockError, declaredFilesAt, emptyLock, fileEntries, readLock, scopeKey, scopeStatus, writeLock, type Lineage, type LineageLock, type ManualStep } from "./lineage-lock";
+import { applyUpstream } from "./lineage-update";
+
+/** The template id a vendor source is known by. */
+function vendorTemplateId(source: VendorEntry["source"]): string {
+  if (source.type === "local") return `local:${source.path}`;
+  return source.subpath ? `${source.url}#${source.subpath}` : source.url;
+}
+
+/** Vendor scopes in the lock, by scope key. */
+export function vendorScopes(lock: LineageLock): Array<[string, Lineage]> {
+  return Object.entries(lock.scopes).filter(([, l]) => l.kind === "vendor");
+}
+
+function vendorSource(lineage: Lineage): VendorEntry["source"] {
+  const s = lineage.source;
+  if (s.type === "local" || s.type === "archive") return s;
+  throw new LockError(`vendor scope "${lineage.name}" has a ${s.type} source; vendor scopes take local or archive sources`);
+}
+
+// ── pull ─────────────────────────────────────────────────────────────────────
+
+export interface LockedPull {
+  name: string;
+  target: string;
+  digest: string;
+  fileCount: number;
+  written: number;
+  kept: number;
+  removed: number;
+  manualSteps: ManualStep[];
+}
+
+/** Pull the lock's vendor scopes (or just `only`). Writes the lock. */
+export async function pullLockedScopes(root: string, only?: string): Promise<LockedPull[]> {
+  const lock = readLock(root) ?? emptyLock();
+  const pulled: LockedPull[] = [];
+  for (const [scope, lineage] of vendorScopes(lock)) {
+    if (only && lineage.name !== only) continue;
+    const files = await resolveVendorSource(vendorSource(lineage), root);
+    const result = applyUpstream(resolve(root, scope), lineage, files);
+    pulled.push({
+      name: lineage.name ?? scope,
+      target: scope,
+      digest: lineage.address!.digest,
+      fileCount: files.size,
+      written: result.written.length,
+      kept: result.kept.length,
+      removed: result.removed.length,
+      manualSteps: result.manualSteps,
+    });
+  }
+  if (pulled.length > 0) writeLock(root, lock);
+  return pulled;
+}
+
+export function formatLockedPull(p: LockedPull): string {
+  const lines = [`  ${p.name} → ${p.target} (${p.fileCount} file(s), ${p.digest.slice(0, 19)}…)`];
+  if (p.kept > 0) lines.push(`    kept ${p.kept} locally edited file(s)`);
+  for (const s of p.manualSteps) lines.push(`    manual step: ${s.path} (${s.reason})`);
+  return lines.join("\n");
+}
+
+// ── check ────────────────────────────────────────────────────────────────────
+
+export type LockedCheckStatus = "ok" | "customised" | "manual" | "unpinned" | "missing";
+
+export interface LockedCheck {
+  name: string;
+  status: LockedCheckStatus;
+  customised: string[];
+  manualSteps: ManualStep[];
+}
+
+/** Check each vendor scope in the lock against the tree. */
+export function checkLockedScopes(root: string): LockedCheck[] {
+  const lock = readLock(root);
+  if (!lock) return [];
+  const out: LockedCheck[] = [];
+  for (const [scope, lineage] of vendorScopes(lock)) {
+    const name = lineage.name ?? scope;
+    if (!lineage.address) {
+      out.push({ name, status: "unpinned", customised: [], manualSteps: [] });
+      continue;
+    }
+    if (!existsSync(resolve(root, scope))) {
+      out.push({ name, status: "missing", customised: [], manualSteps: [] });
+      continue;
+    }
+    const st = scopeStatus(root, scope, lineage);
+    const customised = [...st.customised, ...st.missing].sort();
+    const status: LockedCheckStatus = lineage.manualSteps.length > 0 ? "manual" : customised.length > 0 ? "customised" : "ok";
+    out.push({ name, status, customised, manualSteps: lineage.manualSteps });
+  }
+  return out;
+}
+
+export function formatLockedCheck(c: LockedCheck): string {
+  switch (c.status) {
+    case "ok":
+      return `  ${c.name}: ok`;
+    case "customised":
+      return `  ${c.name}: ok, ${c.customised.length} file(s) edited locally`;
+    case "manual":
+      return [
+        `  ${c.name}: ${c.manualSteps.length} manual step(s) open`,
+        ...c.manualSteps.map((s) => `    ${s.path} (${s.reason})`),
+      ].join("\n");
+    case "unpinned":
+      return `  ${c.name}: unpinned — run \`chant vendor pull\` to record it`;
+    case "missing":
+      return `  ${c.name}: MISSING — target not found; run \`chant vendor pull\``;
+  }
+}
+
+/** Whether a check result fails the check the way drift does for `vendor.json`. */
+export function lockedCheckFails(c: LockedCheck): boolean {
+  return c.status === "manual" || c.status === "missing";
+}
+
+// ── migrate ──────────────────────────────────────────────────────────────────
+
+export interface MigrateResult {
+  migrated: Array<{ name: string; target: string; files: number; pinned: boolean }>;
+  lockCreated: boolean;
+}
+
+/**
+ * Move every `vendor.json` entry into the lock as a vendor scope, then delete
+ * `vendor.json`. An entry's checksum becomes the scope's digest.
+ *
+ * Per-file merge bases come from the target when it still matches the
+ * checksum. When it has been edited, they come from the source instead, which
+ * must still hash to the checksum; otherwise the pinned content is gone and the
+ * entry is refused. Nothing is written unless every entry migrates.
+ */
+export async function migrateVendorManifest(root: string): Promise<MigrateResult> {
+  const { manifest, path: manifestPath } = loadManifest(root);
+  const existing = readLock(root);
+  const lock = existing ?? emptyLock();
+  const migrated: MigrateResult["migrated"] = [];
+  const names = new Set(vendorScopes(lock).map(([, l]) => l.name));
+
+  for (const entry of manifest.vendored) {
+    const scope = scopeKey(entry.target);
+    if (scope === ".") throw new LockError(`vendor entry "${entry.name}" targets the project root; a vendor scope must be a subdirectory`);
+    if (lock.scopes[scope]) throw new LockError(`vendor entry "${entry.name}": ${LOCK_FILE} already has a scope at ${scope}`);
+    if (names.has(entry.name)) throw new LockError(`vendor entry "${entry.name}": ${LOCK_FILE} already has a vendor scope with that name`);
+    names.add(entry.name);
+
+    let files: Lineage["files"] = {};
+    if (entry.checksum) {
+      const targetAbs = resolve(root, entry.target);
+      const local = readTarget(targetAbs);
+      if (local.size > 0 && contentHash(local) === entry.checksum) {
+        files = fileEntries(local, declaredFilesAt(targetAbs));
+      } else {
+        const source = await resolveVendorSource(entry.source, root);
+        if (contentHash(source) !== entry.checksum) {
+          throw new LockError(
+            `vendor entry "${entry.name}": ${entry.target} has been edited and its source no longer matches the recorded checksum, so the pinned files cannot be recovered. Run \`chant vendor pull ${entry.name}\` first (it overwrites ${entry.target}), or restore the pinned content.`,
+          );
+        }
+        files = fileEntries(source, declaredFilesAt(targetAbs));
+      }
+    }
+
+    lock.scopes[scope] = {
+      kind: "vendor",
+      name: entry.name,
+      template: vendorTemplateId(entry.source),
+      source: entry.source,
+      ...(entry.ref !== undefined ? { ref: entry.ref } : {}),
+      address: entry.checksum ? { digest: entry.checksum } : null,
+      parameters: {},
+      migrations: [],
+      files,
+      manualSteps: [],
+    };
+    migrated.push({ name: entry.name, target: scope, files: Object.keys(files).length, pinned: !!entry.checksum });
+  }
+
+  writeLock(root, lock);
+  rmSync(manifestPath);
+  return { migrated, lockCreated: existing === null };
+}
+
+/** Whether `vendor.json` sits next to the lock. */
+export function manifestPresent(root: string): boolean {
+  return existsSync(join(root, MANIFEST_FILE));
+}

package/src/workspace/lineage-version.ts

@@ -0,0 +1,127 @@
+/**
+ * Template versions and version ranges, for migration chains (#2550, D9).
+ *
+ * A template's version is read from the ref it was pinned at: `v1.4.0`,
+ * `1.4`, or a prefixed release tag such as `chant-v0.80.0`. Missing minor and
+ * patch numbers read as 0. A ref that is not a version (a branch, a commit)
+ * has none, and a chain of migrations cannot be planned from it.
+ *
+ * Ranges use the familiar npm subset: comparators (`>=1.0.0 <2.0.0`), `^`,
+ * `~`, `x` wildcards, a bare version for an exact match, `*` for any, and
+ * `||` between alternatives. Pre-release tags compare below their release,
+ * and a range matches a pre-release only through an exact comparator.
+ */
+
+export interface Version {
+  major: number;
+  minor: number;
+  patch: number;
+  /** The pre-release label after `-`, or empty for a release. */
+  pre: string;
+}
+
+const VERSION_TAIL = /(?:^|[-_/@])v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** The version a ref names, or null when it names none. */
+export function parseVersion(ref: string | undefined | null): Version | null {
+  if (!ref) return null;
+  const m = VERSION_TAIL.exec(ref.trim());
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2] ?? 0), patch: Number(m[3] ?? 0), pre: m[4] ?? "" };
+}
+
+export function formatVersion(v: Version): string {
+  return `${v.major}.${v.minor}.${v.patch}${v.pre ? `-${v.pre}` : ""}`;
+}
+
+export function compareVersions(a: Version, b: Version): number {
+  for (const k of ["major", "minor", "patch"] as const) {
+    if (a[k] !== b[k]) return a[k] < b[k] ? -1 : 1;
+  }
+  if (a.pre === b.pre) return 0;
+  if (!a.pre) return 1;
+  if (!b.pre) return -1;
+  return a.pre < b.pre ? -1 : 1;
+}
+
+export class VersionRangeError extends Error {
+  override name = "VersionRangeError";
+}
+
+type Comparator = { op: "<" | "<=" | ">" | ">=" | "="; v: Version };
+
+function partial(text: string, range: string): { v: Version; parts: number } {
+  const m = /^v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z.-]+))?$/.exec(text);
+  if (!m) throw new VersionRangeError(`"${range}" is not a version range: cannot read "${text}"`);
+  const nums = [m[1], m[2], m[3]];
+  let parts = 0;
+  for (const n of nums) {
+    if (n === undefined || /^[xX*]$/.test(n)) break;
+    parts++;
+  }
+  const at = (i: number) => (i < parts ? Number(nums[i]) : 0);
+  return { v: { major: at(0), minor: at(1), patch: at(2), pre: parts === 3 ? (m[4] ?? "") : "" }, parts };
+}
+
+function bump(v: Version, part: number): Version {
+  if (part === 0) return { major: v.major + 1, minor: 0, patch: 0, pre: "" };
+  if (part === 1) return { major: v.major, minor: v.minor + 1, patch: 0, pre: "" };
+  return { major: v.major, minor: v.minor, patch: v.patch + 1, pre: "" };
+}
+
+/** The comparators of one `||` alternative. */
+function comparators(alt: string, range: string): Comparator[] {
+  const out: Comparator[] = [];
+  const tokens = alt.trim().replace(/(>=|<=|>|<|=|\^|~)\s+/g, "$1").split(/\s+/).filter(Boolean);
+  for (const token of tokens) {
+    if (token === "*" || /^[xX]$/.test(token)) continue;
+    const m = /^(>=|<=|>|<|=|\^|~)?(.*)$/.exec(token)!;
+    const op = m[1] ?? "";
+    const { v, parts } = partial(m[2], range);
+    if (op === "^") {
+      const upper = v.major > 0 || parts === 1 ? bump(v, 0) : v.minor > 0 || parts === 2 ? bump(v, 1) : bump(v, 2);
+      out.push({ op: ">=", v }, { op: "<", v: upper });
+    } else if (op === "~") {
+      out.push({ op: ">=", v }, { op: "<", v: bump(v, parts >= 2 ? 1 : 0) });
+    } else if (op === "" || op === "=") {
+      if (parts === 3) out.push({ op: "=", v });
+      else if (parts > 0) out.push({ op: ">=", v }, { op: "<", v: bump(v, parts - 1) });
+    } else if (parts < 3 && (op === ">" || op === "<=")) {
+      // `>1.2` means past every 1.2.x; `<=1.2` includes every 1.2.x.
+      out.push({ op: op === ">" ? ">=" : "<", v: bump(v, parts - 1) });
+    } else {
+      out.push({ op: op as Comparator["op"], v });
+    }
+  }
+  return out;
+}
+
+function test(v: Version, c: Comparator): boolean {
+  const d = compareVersions(v, c.v);
+  switch (c.op) {
+    case "<":
+      return d < 0;
+    case "<=":
+      return d <= 0;
+    case ">":
+      return d > 0;
+    case ">=":
+      return d >= 0;
+    case "=":
+      return d === 0;
+  }
+}
+
+/** Check a range's syntax, throwing {@link VersionRangeError} when it cannot be read. */
+export function validateRange(range: string): void {
+  for (const alt of range.split("||")) comparators(alt, range);
+}
+
+/** Whether `version` falls in `range`. */
+export function satisfies(version: Version, range: string): boolean {
+  return range.split("||").some((alt) => {
+    const cs = comparators(alt, range);
+    if (version.pre && !cs.some((c) => c.op === "=" && compareVersions(c.v, version) === 0)) return false;
+    return cs.every((c) => test(version, c));
+  });
+}