@intentius/chant 0.124.46 → 0.124.49

package/dist/workspace/migration-dirs.js

@@ -0,0 +1,254 @@
+/**
+ * The readers for goose, golang-migrate and clickhouse-migrations
+ * directories (#4400). Each lists the migrations in the order the tool
+ * applies them. None runs the tool or a server: the schema the migrations
+ * produce comes from a replay.
+ *
+ * File layouts, checked against the tools' own docs and source:
+ *
+ * - goose (pressly/goose 9a201bb): `<version>_<name>.sql` directly in the
+ *   directory, the version a positive integer before the first `_`
+ *   (`NumericComponent`, migration.go); ordered by that number, so a
+ *   sequential `00001` and a timestamp `20240101120000` sort together.
+ *   A file holds `-- +goose Up` and, optionally, a later `-- +goose Down`
+ *   (internal/sqlparser/parser.go); `-- +goose NO TRANSACTION` runs it
+ *   outside a transaction. `.go` migrations are listed in the version order
+ *   but are code, so each is a gap.
+ * - golang-migrate (golang-migrate/migrate 504568a): `<version>_<name>.up.<ext>`
+ *   and `.down.<ext>` directly in the directory, matched by
+ *   `^([0-9]+)_(.*)\.(down|up)\.(.*)$` (source/parse.go); ordered by the
+ *   version, a 64-bit unsigned integer. The up files are the migrations; a
+ *   version with a down file and no up file, or two files for one version
+ *   and direction, is a gap.
+ * - clickhouse-migrations, the Python tool (zifter/clickhouse-migrations) and
+ *   the Node tool (npm clickhouse-migrations): `<version>_<name>.sql` directly
+ *   in the migrations directory, the version an integer before the first `_`,
+ *   applied in ascending numeric order. The Python tool also reads an
+ *   optional `<version>_<name>.down.sql` rollback beside it. The dialect is
+ *   always ClickHouse.
+ *
+ * What the migrations produce comes from a replay (`chant sql replay`), which
+ * records the tables and columns in {@link REPLAY_FILE} beside the
+ * migrations. Each reader returns them as the member's outputs when the
+ * recorded digest still matches the files, and a gap that says to replay
+ * again when it does not (see {@link withReplay}).
+ *
+ * The member's `migrationsDir` field names the directory under the member's
+ * own, and `dialect` names the dialect for goose and golang-migrate, whose
+ * tools take it from a driver or URL the directory does not hold.
+ */
+import { createHash } from "node:crypto";
+import { joinPath } from "./tree.js";
+/** The dialects a migration directory's `dialect` field names. */
+export const MIGRATION_DIALECTS = ["postgres", "clickhouse"];
+export function fieldString(fields, name, fallback) {
+    const v = fields?.[name];
+    return typeof v === "string" && v !== "" ? v : fallback;
+}
+/** The directory a reader lists: the member's `migrationsDir` under its own directory. */
+export function migrationsDirOf(input) {
+    const sub = fieldString(input.fields, "migrationsDir", ".");
+    return joinPath(input.dir, sub.replace(/^\.\/?/, ""));
+}
+function filesIn(tree, dir) {
+    return (tree.list(dir) ?? []).filter((e) => e.type === "file").map((e) => e.name).sort();
+}
+const lineOf = (text, pred) => {
+    const i = text.split(/\r?\n/).findIndex(pred);
+    return i < 0 ? 0 : i + 1;
+};
+/** The goose annotation on `line` (`up`, `down`, `no transaction`, ...), or undefined when it holds none. Mirrors the parser's rule: a comment that contains `+goose`. */
+export function gooseAnnotation(line) {
+    const t = line.trim();
+    if (!t.startsWith("--") || !t.includes("+goose"))
+        return undefined;
+    return t.replace("+goose", "").replace(/^--\s*/, "").trim().toLowerCase();
+}
+function listGooseDir(input) {
+    const { tree } = input;
+    const dir = migrationsDirOf(input);
+    const dialect = fieldString(input.fields, "dialect", "postgres");
+    const gaps = [];
+    const result = { reader: "goose-dir", links: [], gaps, migrations: [] };
+    const found = [];
+    for (const name of filesIn(tree, dir)) {
+        const ext = name.endsWith(".sql") ? ".sql" : name.endsWith(".go") && !name.endsWith("_test.go") ? ".go" : null;
+        if (!ext)
+            continue;
+        const file = joinPath(dir, name);
+        const before = name.split("_")[0] ?? "";
+        const n = /^[0-9]+$/.test(before) && name.includes("_") ? Number(before) : NaN;
+        if (!Number.isSafeInteger(n) || n < 1) {
+            gaps.push({ file, line: 1, message: `${name} has no version goose can read: the name starts with a positive integer, then _, so goose would stop here` });
+            continue;
+        }
+        if (ext === ".go") {
+            gaps.push({ file, line: 1, message: `${name} is a Go migration; its code is not SQL, so it is not listed` });
+            found.push({ n, migration: null, file });
+            continue;
+        }
+        const text = tree.read(file);
+        const up = lineOf(text, (l) => gooseAnnotation(l) === "up");
+        if (up === 0) {
+            gaps.push({ file, line: 1, message: `${name} has no -- +goose Up annotation, so goose refuses it` });
+            continue;
+        }
+        const down = lineOf(text, (l) => gooseAnnotation(l) === "down");
+        if (down !== 0 && down < up)
+            gaps.push({ file, line: down, message: `${name}: -- +goose Down comes before -- +goose Up, which goose refuses` });
+        found.push({
+            n,
+            file,
+            migration: {
+                position: 0,
+                version: String(n),
+                name: name.slice(before.length + 1, -ext.length),
+                type: "versioned",
+                file,
+                line: up,
+                down: down !== 0,
+                dialect,
+                transaction: !text.split(/\r?\n/).some((l) => gooseAnnotation(l) === "no transaction"),
+            },
+        });
+    }
+    found.sort((a, b) => a.n - b.n || (a.file < b.file ? -1 : 1));
+    const seen = new Map();
+    for (const f of found) {
+        const prior = seen.get(f.n);
+        if (prior)
+            gaps.push({ file: f.file, line: 1, message: `version ${String(f.n)} is also ${prior}; goose refuses a duplicate version` });
+        else
+            seen.set(f.n, f.file);
+    }
+    for (const f of found)
+        if (f.migration)
+            result.migrations.push(f.migration);
+    result.migrations.forEach((m, i) => (m.position = i + 1));
+    return result;
+}
+const MIGRATE_NAME = /^([0-9]+)_(.*)\.(down|up)\.(.*)$/;
+function listGolangMigrateDir(input) {
+    const { tree } = input;
+    const dir = migrationsDirOf(input);
+    const dialect = fieldString(input.fields, "dialect", "postgres");
+    const gaps = [];
+    const result = { reader: "golang-migrate-dir", links: [], gaps, migrations: [] };
+    const ups = new Map();
+    const downs = new Map();
+    for (const name of filesIn(tree, dir)) {
+        const m = MIGRATE_NAME.exec(name);
+        if (!m)
+            continue;
+        const version = BigInt(m[1]);
+        const file = joinPath(dir, name);
+        if (version > 18446744073709551615n) {
+            gaps.push({ file, line: 1, message: `${name}: the version does not fit a 64-bit unsigned integer, which golang-migrate requires` });
+            continue;
+        }
+        const table = m[3] === "up" ? ups : downs;
+        if (table.has(version)) {
+            gaps.push({ file, line: 1, message: `${name}: another ${m[3]} file already has version ${m[1]}; golang-migrate refuses a duplicate` });
+            continue;
+        }
+        if (m[3] === "up")
+            ups.set(version, { name: m[2], file, version: m[1] });
+        else
+            downs.set(version, file);
+    }
+    for (const [v, file] of downs)
+        if (!ups.has(v))
+            gaps.push({ file, line: 1, message: `version ${String(v)} has a down file and no up file` });
+    [...ups.entries()]
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .forEach(([v, u], i) => result.migrations.push({ position: i + 1, version: u.version, name: u.name, type: "versioned", file: u.file, line: 1, down: downs.get(v) ?? false, dialect }));
+    return result;
+}
+const CLICKHOUSE_NAME = /^([0-9]+)_(.+)\.sql$/;
+function listClickHouseMigrationsDir(input) {
+    const { tree } = input;
+    const dir = migrationsDirOf(input);
+    const gaps = [];
+    const result = { reader: "clickhouse-migrations-dir", links: [], gaps, migrations: [] };
+    const names = filesIn(tree, dir).filter((n) => n.endsWith(".sql"));
+    const rollbacks = new Map(names.filter((n) => n.endsWith(".down.sql")).map((n) => [n.slice(0, -".down.sql".length), joinPath(dir, n)]));
+    const ups = [];
+    for (const name of names) {
+        if (name.endsWith(".down.sql"))
+            continue;
+        const m = CLICKHOUSE_NAME.exec(name);
+        if (!m) {
+            gaps.push({ file: joinPath(dir, name), line: 1, message: `${name} has no version before its first _, so clickhouse-migrations reports a bad file name` });
+            continue;
+        }
+        ups.push({ n: BigInt(m[1]), version: m[1], name: m[2], file: joinPath(dir, name) });
+    }
+    ups.sort((a, b) => (a.n < b.n ? -1 : a.n > b.n ? 1 : a.file < b.file ? -1 : 1));
+    const seen = new Map();
+    for (const u of ups) {
+        const prior = seen.get(u.n);
+        if (prior)
+            gaps.push({ file: u.file, line: 1, message: `version ${u.version} is also ${prior}; leading zeros are not significant, so clickhouse-migrations reports a duplicate version` });
+        else
+            seen.set(u.n, u.file);
+    }
+    ups.forEach((u, i) => result.migrations.push({ position: i + 1, version: u.version, name: u.name, type: "versioned", file: u.file, line: 1, down: rollbacks.get(u.file.split("/").pop().slice(0, -".sql".length)) ?? false, dialect: "clickhouse" }));
+    return result;
+}
+/** The file a replay writes in the member's directory: the tables and columns the migrations produced, and the digest of the files it ran (#4400). */
+export const REPLAY_FILE = "chant.replay.json";
+/** A digest of the migration files in order, so a snapshot can tell the files changed. `extra` are files beside them that change what runs, such as Flyway's configuration. */
+export function migrationDigest(read, files) {
+    const h = createHash("sha256");
+    for (const f of files) {
+        h.update(f);
+        h.update("\0");
+        h.update(read(f));
+        h.update("\0");
+    }
+    return `sha256:${h.digest("hex")}`;
+}
+/** The files a replay of `migrations` depends on, in order. */
+export function replayFiles(tree, migrations, extra = []) {
+    return [...extra.filter((f) => tree.stat(f) === "file"), ...migrations.map((m) => m.file)];
+}
+/**
+ * Add the recorded replay to a reader's result: the snapshot's names as
+ * outputs when its digest matches the files, else a gap flagged `outputs`
+ * (a link into the member is then unresolved, not missing). A snapshot
+ * that does not parse is a gap too.
+ */
+export function withReplay(result, tree, dir, extra = []) {
+    const file = joinPath(dir, REPLAY_FILE);
+    const migrations = result.migrations ?? [];
+    const gap = (message, line = 1) => result.gaps.push({ file: tree.stat(file) === "file" ? file : dir || ".", line, message, outputs: true });
+    if (tree.stat(file) !== "file") {
+        gap(`no ${REPLAY_FILE}: replay the migrations to record the tables and columns they produce (chant sql replay ${dir || "."})`);
+        return result;
+    }
+    let text;
+    let snap;
+    try {
+        text = tree.read(file);
+        snap = JSON.parse(text);
+    }
+    catch (err) {
+        gap(`${REPLAY_FILE} could not be read (${err.message}), so the tables the migrations produce are unknown`);
+        return result;
+    }
+    if (snap.schema !== 1 || typeof snap.digest !== "string" || !Array.isArray(snap.outputs) || snap.outputs.some((o) => typeof o !== "string")) {
+        gap(`${REPLAY_FILE} is not a replay snapshot (schema 1 with a digest and outputs), so the tables the migrations produce are unknown`);
+        return result;
+    }
+    const digest = migrationDigest((f) => tree.read(f), replayFiles(tree, migrations, extra));
+    if (digest !== snap.digest) {
+        gap(`the migrations changed since ${REPLAY_FILE} was recorded, so the tables they produce are unknown; replay again (chant sql replay ${dir || "."})`);
+        return result;
+    }
+    const lines = text.split("\n");
+    result.outputs = snap.outputs.map((name) => ({ name, file, line: Math.max(1, lines.findIndex((l) => l.includes(JSON.stringify(name))) + 1) }));
+    return result;
+}
+export const readGooseDir = (input) => withReplay(listGooseDir(input), input.tree, input.dir);
+export const readGolangMigrateDir = (input) => withReplay(listGolangMigrateDir(input), input.tree, input.dir);
+export const readClickHouseMigrationsDir = (input) => withReplay(listClickHouseMigrationsDir(input), input.tree, input.dir);

package/dist/workspace/new-migrations.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The migration files a pull request adds to a migration-directory workspace
+ * member (#4407), for the plan note. Reads the member's migrations at the
+ * pull request's head with the kind's own reader (`./kind-link-readers.ts`),
+ * keeps the files the base commit lacks, and asks a lexicon to classify
+ * them (`LexiconPlugin.classifyMigrations`). It reads git objects and files
+ * only: nothing is applied, no server is contacted, and no tool runs.
+ */
+import type { LexiconPlugin } from "../lexicon.js";
+import type { PrMigrationFile } from "../pr-migrations.js";
+import { type KindLinkRead, type KindReadMigration } from "./kind-link-readers.js";
+import type { WorkspaceTree } from "./tree.js";
+/** One member's new migrations. */
+export interface NewMigrationGroup {
+    member: string;
+    /** The member's directory, tree-relative; "" for the workspace root. */
+    dir: string;
+    reader: string;
+    dialect: string;
+    /** The new files, in the order the tool applies them. */
+    migrations: KindReadMigration[];
+}
+/**
+ * Per member, the migrations whose file is not in `base`. An `undo` file is
+ * not an up migration and is left out. With no `base` tree (the workspace did
+ * not exist there) every migration is new. `only` limits the answer to one
+ * member, for a member's own pipeline.
+ */
+export declare function newMigrationGroups(members: readonly {
+    name: string;
+    dir: string;
+}[], read: ReadonlyMap<string, KindLinkRead>, base: WorkspaceTree | undefined, only?: string): NewMigrationGroup[];
+/**
+ * Classify the new files with the first lexicon that answers each. A file no
+ * lexicon answers for comes back with an `error` that says which dialect, so
+ * the note shows it instead of leaving it out.
+ */
+export declare function classifyNewMigrations(groups: readonly NewMigrationGroup[], head: WorkspaceTree, plugins: readonly Pick<LexiconPlugin, "name" | "classifyMigrations">[]): Promise<PrMigrationFile[]>;
+/**
+ * The new migration files of the workspace holding `cwd`, between `base` and
+ * `head`. Empty outside a workspace or when the declaration cannot be read.
+ */
+export declare function newMigrationFilesBetween(cwd: string, base: string, head: string, options: {
+    member?: string;
+    plugins: () => Promise<readonly Pick<LexiconPlugin, "name" | "classifyMigrations">[]>;
+}): Promise<PrMigrationFile[]>;
+//# sourceMappingURL=new-migrations.d.ts.map

package/dist/workspace/new-migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-migrations.d.ts","sourceRoot":"","sources":["../../src/workspace/new-migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAA+B,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAErF,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG5C,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,EACjD,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EACvC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,IAAI,CAAC,EAAE,MAAM,GACZ,iBAAiB,EAAE,CAWrB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB,CAAC,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAoBzM;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB,CAAC,EAAE,CAAC,CAAA;CAAE,GAClH,OAAO,CAAC,eAAe,EAAE,CAAC,CAoB5B"}

package/dist/workspace/new-migrations.js

@@ -0,0 +1,91 @@
+/**
+ * The migration files a pull request adds to a migration-directory workspace
+ * member (#4407), for the plan note. Reads the member's migrations at the
+ * pull request's head with the kind's own reader (`./kind-link-readers.ts`),
+ * keeps the files the base commit lacks, and asks a lexicon to classify
+ * them (`LexiconPlugin.classifyMigrations`). It reads git objects and files
+ * only: nothing is applied, no server is contacted, and no tool runs.
+ */
+import { readDeclaration } from "./declaration.js";
+import { readKindLinks } from "./kind-link-readers.js";
+import { loadKindRegistry } from "./kinds.js";
+import { locateWorkspace } from "./which-chant.js";
+/**
+ * Per member, the migrations whose file is not in `base`. An `undo` file is
+ * not an up migration and is left out. With no `base` tree (the workspace did
+ * not exist there) every migration is new. `only` limits the answer to one
+ * member, for a member's own pipeline.
+ */
+export function newMigrationGroups(members, read, base, only) {
+    const out = [];
+    for (const m of members) {
+        if (only !== undefined && m.name !== only)
+            continue;
+        const r = read.get(m.name);
+        if (!r?.migrations)
+            continue;
+        const added = r.migrations.filter((mig) => mig.type !== "undo" && base?.stat(mig.file) !== "file");
+        if (added.length === 0)
+            continue;
+        out.push({ member: m.name, dir: m.dir === "." ? "" : m.dir, reader: r.reader, dialect: added[0].dialect, migrations: added });
+    }
+    return out;
+}
+/**
+ * Classify the new files with the first lexicon that answers each. A file no
+ * lexicon answers for comes back with an `error` that says which dialect, so
+ * the note shows it instead of leaving it out.
+ */
+export async function classifyNewMigrations(groups, head, plugins) {
+    const out = [];
+    for (const g of groups) {
+        const files = g.migrations.map((m) => m.file);
+        const answers = new Map();
+        for (const p of plugins) {
+            if (!p.classifyMigrations || answers.size === files.length)
+                continue;
+            const left = files.filter((f) => !answers.has(f));
+            try {
+                for (const a of await p.classifyMigrations({ reader: g.reader, dialect: g.dialect, tree: head, dir: g.dir, files: left }))
+                    answers.set(a.file, a);
+            }
+            catch (err) {
+                for (const f of left)
+                    answers.set(f, { file: f, statements: [], error: `the ${p.name} lexicon could not classify it: ${err instanceof Error ? err.message : String(err)}` });
+            }
+        }
+        for (const m of g.migrations) {
+            const a = answers.get(m.file) ?? { file: m.file, statements: [], error: `no installed lexicon classifies ${g.dialect} migrations` };
+            out.push({ member: g.member, reader: g.reader, version: m.version, name: m.name, type: m.type, dialect: m.dialect, ...a });
+        }
+    }
+    return out;
+}
+/**
+ * The new migration files of the workspace holding `cwd`, between `base` and
+ * `head`. Empty outside a workspace or when the declaration cannot be read.
+ */
+export async function newMigrationFilesBetween(cwd, base, head, options) {
+    let located;
+    let declaration;
+    try {
+        located = locateWorkspace(cwd, head);
+        declaration = readDeclaration(located.tree, "", { rootChant: true });
+    }
+    catch {
+        return [];
+    }
+    const { registry } = loadKindRegistry(declaration.pins, located.rootOnDisk);
+    const read = readKindLinks(declaration, located.tree, registry);
+    let baseTree;
+    try {
+        baseTree = locateWorkspace(cwd, base).tree;
+    }
+    catch {
+        baseTree = undefined;
+    }
+    const groups = newMigrationGroups(declaration.members, read, baseTree, options.member);
+    if (groups.length === 0)
+        return [];
+    return classifyNewMigrations(groups, located.tree, await options.plugins());
+}

package/dist/workspace/pr-report.schema.json

@@ -92,6 +92,39 @@
         }
       }
     },
+    "migrations": {
+      "type": "array",
+      "description": "Added within contract version 1 by #4407, written by chant 0.124.49 and newer. Plan stage: the migration files the pull request adds in a migration-directory workspace member (goose, golang-migrate, clickhouse-migrations, Flyway), each statement with the class the lexicon's classifier gives it, read offline. Absent when the pull request adds none.",
+      "items": {
+        "type": "object",
+        "required": ["member", "reader", "file", "version", "name", "type", "dialect", "statements"],
+        "properties": {
+          "member": { "type": "string" },
+          "reader": { "type": "string" },
+          "file": { "type": "string", "description": "Relative to the workspace root." },
+          "version": { "type": "string" },
+          "name": { "type": "string" },
+          "type": { "enum": ["versioned", "repeatable", "baseline", "undo"] },
+          "dialect": { "type": "string" },
+          "error": { "type": "string", "description": "Why the file could not be read; its statements are then empty." },
+          "statements": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["index", "sql", "outcome", "changes"],
+              "properties": {
+                "index": { "type": "integer", "minimum": 1 },
+                "sql": { "type": "string" },
+                "outcome": { "enum": ["classified", "undecided", "unclassified", "data"] },
+                "changes": { "type": "array", "items": { "$ref": "#/$defs/migrationChange" } },
+                "candidates": { "type": "array", "items": { "$ref": "#/$defs/migrationChange" }, "description": "With undecided: the rules that could apply." },
+                "note": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
     "plannedOutputs": {
       "type": "object",
       "description": "Added within contract version 1 by #3999, written by chant 0.124.32 and newer. Per dependency in the change that a member was planned against, the names of the outputs its plan knows, sorted. An output a member reads that is not listed is known only after apply, and the member lists it under unknownInputs. Absent when no member read one.",
@@ -258,6 +291,19 @@
     }
   },
   "$defs": {
+    "migrationChange": {
+      "type": "object",
+      "required": ["rule", "class", "label", "title"],
+      "properties": {
+        "rule": { "type": "string" },
+        "class": { "type": "string" },
+        "label": { "type": "string" },
+        "title": { "type": "string" },
+        "lock": { "type": "string" },
+        "destructive": { "type": "boolean" },
+        "note": { "type": "string" }
+      }
+    },
     "policyFinding": {
       "type": "object",
       "required": ["rule", "message"],

package/dist/workspace/promote.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `chant workspace promote <member>` (#3178): move one member one rung up the
+ * kind ladder, `other` or `terraform`, then `choudoufu`, then `chant`.
+ *
+ * The change is staged the way `workspace upgrade` stages one (#2550): in a
+ * git worktree at HEAD, so the tree is never touched until the gate passes.
+ * The gate is `workspace-promote/<member>` on the gate ledger and binds the
+ * digest of the patch the staging produced. The first run records a pending
+ * fact and exits 3. After `chant approve workspace-promote <member>`, the same
+ * command stages again, finds the approval for the same digest, applies the
+ * patch, and runs the rung's follow-up (for `choudoufu`, stamping the
+ * ownership markers with `live-import -approve`).
+ *
+ * Rungs:
+ *
+ * - `terraform` to `choudoufu`: `choudoufu live-check` in the member's
+ *   directory must pass, then `choudoufu live-import -state=<--state>
+ *   -estate=<member>` prints its ratification report (read-only: it stamps
+ *   nothing without `-approve`). The patch changes the member's kind.
+ * - `choudoufu` or `other` to `chant`: `chant import` writes TypeScript into
+ *   the member's directory. The patch holds those files and the kind change.
+ *
+ * Commands run through an injectable runner, so a test never starts a binary.
+ */
+import type { CommandContext } from "../cli/registry.js";
+import { type GateLedgerPort } from "../op/gate.js";
+export declare const PROMOTE_PLAN_KIND = "workspace-promote";
+export declare const PROMOTE_GATED_EXIT = 3;
+export declare class PromoteError extends Error {
+}
+/** The ladder, lowest rung first. `other` and `terraform` share the bottom rung. */
+export declare const LADDER: readonly ["terraform", "choudoufu", "chant"];
+export interface Rung {
+    from: string;
+    to: "choudoufu" | "chant";
+}
+/** The next rung for a member of `kind`, or undefined at the top or off the ladder. */
+export declare function nextRung(kind: string): Rung | undefined;
+export interface CommandRun {
+    label: string;
+    argv: string[];
+    /** Directory relative to the project root. */
+    cwd: string;
+}
+export type PromoteRunner = (argv: string[], cwd: string) => Promise<{
+    exitCode: number;
+    output: string;
+}>;
+export declare const spawnRunner: PromoteRunner;
+/** The commands the rung runs in the staging worktree. */
+export declare function stagingRuns(rung: Rung, member: {
+    name: string;
+    dir: string;
+}, opts: {
+    state?: string;
+    lexicon?: string;
+}): CommandRun[];
+/** After the approved patch is applied: stamping ownership markers on the live resources. */
+export declare function followUpRuns(rung: Rung, member: {
+    name: string;
+    dir: string;
+}, opts: {
+    state?: string;
+}): CommandRun[];
+export interface PromoteOptions {
+    root: string;
+    member: string;
+    state?: string;
+    lexicon?: string;
+    dryRun?: boolean;
+    output?: string;
+    json?: boolean;
+    /** For tests. */
+    runner?: PromoteRunner;
+    ledger?: GateLedgerPort;
+    now?: string;
+}
+export type PromoteOutcome = "top-of-ladder" | "checks-failed" | "dry-run" | "gated" | "applied";
+export interface PromoteResult {
+    outcome: PromoteOutcome;
+    exitCode: number;
+    member: string;
+    from?: string;
+    to?: string;
+    digest?: string;
+    patch?: string;
+    ran?: {
+        label: string;
+        exitCode: number;
+    }[];
+}
+/** Rewrite the member's `kind` in the declaration text. */
+export declare function setMemberKind(text: string, file: string, member: string, kind: string): string;
+export declare function promoteCommand(opts: PromoteOptions): Promise<PromoteResult>;
+export declare function runWorkspacePromote(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=promote.d.ts.map

package/dist/workspace/promote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promote.d.ts","sourceRoot":"","sources":["../../src/workspace/promote.ts"],"names":[],"mappings":"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"}