@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/member-commands.js

@@ -0,0 +1,508 @@
+/**
+ * `chant workspace build|lint|audit|graph [dir]` (#2537, #2524 D3, D8, D12,
+ * D16): run a level-0 command in every member, each under the member's own
+ * chant, and put the answers together.
+ *
+ * What runs:
+ *
+ * - Members of kind `chant`, the root member `.` included when it is one.
+ *   Members of kind `other` are never read, and a nested `workspace` member
+ *   runs its own workspace commands, so both are listed as skipped with the
+ *   reason code `kind-not-run`.
+ * - For `graph` only, members of a pinned package's kind whose kinds file
+ *   says how to read them (#2874, a `graph` block): each runs `chant graph`
+ *   in a reader project chant writes for it (`kind-readers.ts`). Other
+ *   package kinds are `kind-not-run`, as before.
+ * - For `build` and `lint` only, every project an example group matches
+ *   (ws-051): groups are built and linted, and have no ledger, audit or place
+ *   in the graph. On a large repository this is most of the run, so
+ *   `--member <name>` narrows it to the named members and groups.
+ *
+ * Which chant runs a member (its toolchain): the `node_modules/.bin/chant`
+ * found by walking up from the member's directory to the workspace root,
+ * followed to its real path. A member with none uses the root's, and when
+ * the root has none either, the chant running this command. Members are
+ * grouped by that real path, and each group gets one process: the chant's
+ * `workspace member-run`, handed every member's command line on stdin (see
+ * `member-run.ts`). A chant too old to have `member-run` gets one level-0
+ * process per member instead, from inside the member's directory.
+ *
+ * Member `.` is the root project minus every other member, so its run leaves
+ * the member directories and group matches out of discovery, as
+ * `chant build --root-only` does.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { formatError } from "../cli/format.js";
+import { findWorkspaceRoot } from "../project-root.js";
+import { mergeAudit, mergeSarif } from "./compose-reports.js";
+import { readDeclaration, resolveGroups, rootExclusions, WorkspaceReadError } from "./declaration.js";
+import { builtinKindRegistry } from "./kinds.js";
+import { memberReason } from "./ls.js";
+import { MEMBER_RUN_PROTOCOL, PROTOCOL_PREFIX } from "./member-run.js";
+import { workingTree } from "./tree.js";
+/** The `bin/chant` of the chant this module belongs to. */
+export function readerBin() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "bin", "chant");
+}
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * How to start the chant running this command. When this process is chant's
+ * own CLI, it is started again the same way (node, its loader flags and
+ * `main.ts`), which works from any directory. `bin/chant` looks for tsx
+ * relative to an installed package, and from a source checkout it can only
+ * fall back to `npx tsx` in the current directory.
+ */
+export function readerToolchain() {
+    const main = process.argv[1] ?? "";
+    const command = /[\\/]cli[\\/]main\.(ts|js|mjs)$/.test(main) ? [process.execPath, ...process.execArgv, main] : [readerBin()];
+    return { command, identity: real(readerBin()), source: "reader" };
+}
+/**
+ * The chant a directory resolves: the first `node_modules/.bin/chant` from
+ * `dir` up to `root` (both absolute, `dir` inside `root`), else `reader`.
+ * A bin that is the reader's own chant is started the way the reader is.
+ */
+export function resolveToolchain(dir, root, reader = readerToolchain()) {
+    for (let at = dir;; at = dirname(at)) {
+        const bin = join(at, "node_modules", ".bin", "chant");
+        if (existsSync(bin)) {
+            const identity = real(bin);
+            const source = at === root ? "root" : "member";
+            return identity === reader.identity ? { ...reader, source } : { command: [bin], identity, source };
+        }
+        if (at === root || dirname(at) === at)
+            break;
+    }
+    return reader;
+}
+/** Work out which projects run and under which chant. Throws a {@link WorkspaceReadError} for an unreadable declaration or an unknown `--member` name. */
+export function planMembers(verb, root, options = {}) {
+    const tree = options.tree ?? workingTree(root);
+    const declaration = readDeclaration(tree);
+    const resolvedGroups = resolveGroups(declaration, tree);
+    const kinds = options.kinds ?? builtinKindRegistry();
+    const only = options.only?.length ? new Set(options.only) : undefined;
+    if (only) {
+        const known = new Set(declaration.entries.map((e) => e.name));
+        const unknown = [...only].filter((n) => !known.has(n));
+        if (unknown.length > 0) {
+            throw new WorkspaceReadError("declaration-invalid", `--member names ${unknown.join(", ")}, which the declaration does not declare; it declares ${[...known].join(", ")}`);
+        }
+    }
+    const units = [];
+    const skipped = [];
+    const unreadable = [];
+    const groupsRun = verb === "build" || verb === "lint";
+    for (const entry of declaration.entries) {
+        if (only && !only.has(entry.name))
+            continue;
+        if (entry.type === "group") {
+            const g = resolvedGroups.find((r) => r.group === entry);
+            if (!groupsRun) {
+                skipped.push({
+                    name: entry.name,
+                    dir: null,
+                    kind: entry.kind,
+                    reason: { code: "kind-not-run", message: `example groups are built and linted only; chant workspace ${verb} leaves them out` },
+                });
+                continue;
+            }
+            for (const dir of g.matches) {
+                units.push({ id: `${entry.name}:${dir}`, member: entry.name, kind: entry.kind, group: true, dir, abs: join(root, dir), exclude: [] });
+            }
+            continue;
+        }
+        const byKind = verb === "graph" && entry.kind !== "chant" ? kinds.get(entry.kind) : undefined;
+        if (byKind?.graph && byKind.packageDir) {
+            const reason = memberReason(entry, tree, kinds);
+            if (reason) {
+                unreadable.push({ name: entry.name, dir: entry.dir, kind: entry.kind, reason });
+                continue;
+            }
+            units.push({
+                id: entry.name,
+                member: entry.name,
+                kind: entry.kind,
+                group: false,
+                dir: entry.dir,
+                abs: entry.dir === "." ? root : join(root, entry.dir),
+                exclude: [],
+                reader: { ...byKind.graph, packageDir: byKind.packageDir },
+            });
+            continue;
+        }
+        if (entry.kind !== "chant") {
+            const why = entry.kind === "workspace"
+                ? "a nested workspace runs its own chant workspace commands"
+                : entry.kind === "design"
+                    ? "a design member is data: chant reads its files for record pins and builds nothing"
+                    : `chant workspace ${verb} runs members of kind chant, and this one is kind ${entry.kind}`;
+            skipped.push({ name: entry.name, dir: entry.dir, kind: entry.kind, reason: { code: "kind-not-run", message: why } });
+            continue;
+        }
+        const reason = memberReason(entry, tree, kinds);
+        if (reason) {
+            unreadable.push({ name: entry.name, dir: entry.dir, kind: entry.kind, reason });
+            continue;
+        }
+        units.push({
+            id: entry.name,
+            member: entry.name,
+            kind: entry.kind,
+            group: false,
+            dir: entry.dir,
+            abs: entry.dir === "." ? root : join(root, entry.dir),
+            exclude: entry.dir === "." ? rootExclusions(declaration, resolvedGroups).map((e) => e.dir) : [],
+        });
+    }
+    const reader = options.reader ?? readerToolchain();
+    const byIdentity = new Map();
+    for (const unit of units) {
+        // The walk reaches the root's chant before it gives up, so a member with
+        // none of its own runs under the root's, and under this chant only when
+        // the root has none either.
+        const tc = resolveToolchain(unit.abs, root, reader);
+        const group = byIdentity.get(tc.identity) ?? { toolchain: tc, units: [] };
+        group.units.push(unit);
+        byIdentity.set(tc.identity, group);
+    }
+    return {
+        verb,
+        workspace: { name: declaration.name, root, file: declaration.file },
+        groups: [...byIdentity.values()],
+        unreadable,
+        skipped,
+    };
+}
+// ── Command lines ────────────────────────────────────────────────────────────
+/** What each member's run prints, for the verb and the workspace command's own flags. */
+export function memberFormat(verb, args) {
+    if (verb === "graph")
+        return "ir";
+    // Audit always reads JSON, so member `.` can leave other members' findings to them.
+    if (verb === "audit")
+        return "json";
+    if (verb === "lint")
+        return args.format === "sarif" || args.format === "json" ? args.format : "stylish";
+    return args.format === "yaml" ? "yaml" : "json";
+}
+/** The level-0 command line one member runs. */
+export function memberArgv(verb, unit, args) {
+    // A build keeps its own default format unless one was asked for.
+    const argv = verb === "build" && !args.format ? [verb, "."] : [verb, ".", "--format", memberFormat(verb, args)];
+    const params = () => {
+        for (const p of args.param ?? [])
+            argv.push("--param", p);
+        if (args.paramsFile)
+            argv.push("--params-file", resolve(args.paramsFile));
+    };
+    if (verb === "build") {
+        if (args.env)
+            argv.push("--env", args.env);
+        params();
+        if (args.lexicon)
+            argv.push("--lexicon", args.lexicon);
+        if (args.output)
+            argv.push("--output", buildOutputPath(args.output, unit, memberFormat(verb, args)));
+    }
+    else if (verb === "lint") {
+        params();
+        if (args.fix)
+            argv.push("--fix");
+    }
+    else if (verb === "audit") {
+        if (args.tier)
+            argv.push("--tier", args.tier);
+        if (args.failOn)
+            argv.push("--fail-on", args.failOn);
+        if (args.maxFiles !== undefined)
+            argv.push("--max-files", String(args.maxFiles));
+    }
+    else {
+        // graph. A reader project declares no environments, so a source read
+        // leaves --env to the chant members. A live read needs one, and a reader
+        // project with none declared takes any name, so --live carries it (#2875).
+        if (args.env && (!unit.reader || args.live))
+            argv.push("--env", args.env);
+        // The live read's flags go to every member as they are (#2875).
+        if (args.live)
+            argv.push("--live");
+        if (args.overlay)
+            argv.push("--overlay");
+        if (args.traffic)
+            argv.push("--traffic", args.traffic);
+    }
+    return argv;
+}
+/** `workspace build -o <dir>` writes `<dir>/<member>.<ext>`, and `<dir>/<group>/<match dir>.<ext>` for a group match. */
+export function buildOutputPath(outDir, unit, format) {
+    const ext = format === "yaml" ? "yaml" : "json";
+    return `${resolve(outDir, unit.group ? join(unit.member, unit.dir) : unit.member)}.${ext}`;
+}
+function run(command, argv, cwd, input) {
+    const [bin, ...pre] = command;
+    return new Promise((done) => {
+        const child = spawn(bin, [...pre, ...argv], { cwd, stdio: ["pipe", "pipe", "pipe"], env: process.env });
+        const out = [];
+        const err = [];
+        child.stdout.on("data", (b) => out.push(b));
+        child.stderr.on("data", (b) => err.push(b));
+        child.on("error", (e) => done({ exitCode: 127, stdout: "", stderr: `could not start ${bin}: ${e.message}\n` }));
+        child.on("close", (code) => done({ exitCode: code ?? 1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8") }));
+        child.stdin.on("error", () => {
+            // A chant that never reads stdin closes it early; its answer says why.
+        });
+        child.stdin.end(input ?? "");
+    });
+}
+/** Parse a member-run answer. `undefined` when there is no header: the chant has no member-run. */
+export function parseMemberRunOutput(stdout) {
+    let header;
+    const results = new Map();
+    const stray = [];
+    for (const line of stdout.split("\n")) {
+        if (!line.startsWith(PROTOCOL_PREFIX)) {
+            if (line.trim())
+                stray.push(line);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line.slice(PROTOCOL_PREFIX.length));
+        }
+        catch {
+            continue;
+        }
+        if (parsed.type === "header" && !header)
+            header = parsed;
+        else if (parsed.type === "result" && header)
+            results.set(parsed.id, parsed);
+    }
+    return header ? { chant: header.chant, results, stray: stray.join("\n") } : undefined;
+}
+async function runGroup(verb, group, root, args, argvFor) {
+    const { toolchain, units } = group;
+    const argvs = new Map(units.map((u) => [u.id, argvFor ? argvFor(u) : memberArgv(verb, u, args)]));
+    for (const u of units) {
+        const o = argvs.get(u.id);
+        const i = o.indexOf("--output");
+        if (i >= 0)
+            mkdirSync(dirname(o[i + 1]), { recursive: true });
+    }
+    const request = {
+        protocol: MEMBER_RUN_PROTOCOL,
+        units: units.map((u) => ({ id: u.id, dir: u.abs, argv: argvs.get(u.id), ...(u.exclude.length ? { exclude: u.exclude } : {}) })),
+    };
+    const answer = await run(toolchain.command, ["workspace", "member-run"], root, JSON.stringify(request));
+    const ended = new Date().toISOString();
+    const parsed = parseMemberRunOutput(answer.stdout);
+    if (parsed) {
+        if (parsed.stray)
+            process.stderr.write(`${parsed.stray}\n`);
+        return units.map((unit) => {
+            const r = parsed.results.get(unit.id);
+            const base = { unit, toolchain, chant: parsed.chant, mode: "member-run", id: unit.id, member: unit.member, dir: unit.dir, exclude: unit.exclude };
+            // A member-run from before #2875 names no time; the group's end is the closest one.
+            if (r)
+                return { ...base, exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr, finishedAt: r.finishedAt ?? ended };
+            return { ...base, exitCode: answer.exitCode || 1, stdout: "", stderr: `the member-run process for ${toolchain.identity} ended before running this member\n${answer.stderr}` };
+        });
+    }
+    // No header: a chant older than member-run. One level-0 process per member.
+    const out = [];
+    for (const unit of units) {
+        const r = await run(toolchain.command, argvs.get(unit.id), unit.abs);
+        out.push({ unit, toolchain, chant: null, mode: "per-member", id: unit.id, member: unit.member, dir: unit.dir, exclude: unit.exclude, ...r, finishedAt: new Date().toISOString() });
+    }
+    return out;
+}
+/**
+ * Run every group of the plan, one process per toolchain at a time each, and
+ * return the results in plan order. `argvFor` replaces the verb's command line.
+ */
+export async function executePlan(plan, args, argvFor) {
+    const perGroup = await Promise.all(plan.groups.map((g) => runGroup(plan.verb, g, plan.workspace.root, args, argvFor)));
+    const byId = new Map(perGroup.flat().map((r) => [r.id, r]));
+    const order = plan.groups.flatMap((g) => g.units);
+    return order.map((u) => byId.get(u.id));
+}
+// ── The command ──────────────────────────────────────────────────────────────
+const USAGE = {
+    build: "chant workspace build [dir] [--member <name>] [-o <dir>] [--format json|yaml] [--env <env>] [--param k=v] [--dry-run]",
+    lint: "chant workspace lint [dir] [--member <name>] [--format stylish|json|sarif] [-o <file>] [--fix] [--dry-run]",
+    audit: "chant workspace audit [dir] [--member <name>] [--format stylish|json] [-o <file>] [--tier <tier>] [--fail-on <level>] [--dry-run]",
+    graph: "chant workspace graph [dir] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run]",
+};
+export function describePlan(plan) {
+    const lines = [`chant workspace ${plan.verb} in ${plan.workspace.name} (${plan.workspace.root})`];
+    for (const g of plan.groups) {
+        lines.push("", `${g.toolchain.identity}  (${g.toolchain.source}, ${g.units.length} project${g.units.length === 1 ? "" : "s"}, one process)`);
+        for (const u of g.units)
+            lines.push(`  ${u.id}${u.group ? "" : `  ${u.dir}`}`);
+    }
+    for (const s of plan.unreadable)
+        lines.push("", `unreadable ${s.name}: ${s.reason.code}: ${s.reason.message}`);
+    if (plan.skipped.length) {
+        lines.push("", "skipped:");
+        for (const s of plan.skipped)
+            lines.push(`  ${s.name}  ${s.reason.code}: ${s.reason.message}`);
+    }
+    return lines.join("\n");
+}
+export function planJson(plan) {
+    return {
+        verb: plan.verb,
+        workspace: plan.workspace,
+        toolchains: plan.groups.map((g) => ({ ...g.toolchain, units: g.units.map((u) => ({ id: u.id, member: u.member, dir: u.dir, group: u.group })) })),
+        unreadable: plan.unreadable,
+        skipped: plan.skipped,
+    };
+}
+export function emitDocument(doc, output) {
+    const text = JSON.stringify(doc, null, 2);
+    if (output) {
+        mkdirSync(dirname(resolve(output)), { recursive: true });
+        writeFileSync(resolve(output), `${text}\n`);
+    }
+    else {
+        console.log(text);
+    }
+}
+function summaryLine(plan, results) {
+    const failed = results.filter((r) => r.exitCode !== 0).length + plan.unreadable.length;
+    const n = results.length + plan.unreadable.length;
+    const processes = plan.groups.length;
+    return (`chant workspace ${plan.verb}: ${n} project${n === 1 ? "" : "s"}, ${n - failed} passed, ${failed} failed; ` +
+        `${plan.skipped.length} skipped; ${processes} toolchain${processes === 1 ? "" : "s"}`);
+}
+function printSections(plan, results, showStdout) {
+    for (const r of results) {
+        const via = r.chant ? `chant ${r.chant}` : r.toolchain.identity;
+        console.log(`── ${r.id}  ${r.dir}  (${via}, exit ${r.exitCode})`);
+        if (showStdout && r.stdout.trim())
+            console.log(r.stdout.replace(/\n$/, ""));
+        if (r.stderr.trim())
+            process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+    }
+    for (const s of plan.unreadable)
+        console.log(`── ${s.name}  ${s.dir}  (${s.reason.code}: ${s.reason.message})`);
+    console.error(summaryLine(plan, results));
+}
+/** The text form of `workspace audit`: each member's findings under a heading, one line each. */
+function formatAuditText(doc, plan) {
+    const lines = [];
+    for (const m of doc.members) {
+        const own = doc.findings.filter((f) => f.member === m.member);
+        lines.push(`── ${m.member}  ${m.dir}  (${m.status === "failed" ? `failed: ${m.error}` : m.note ?? `${own.length} finding${own.length === 1 ? "" : "s"}`})`);
+        for (const f of own) {
+            const at = `${String(f.file)}${f.line !== undefined ? `:${String(f.line)}` : ""}`;
+            lines.push(`  ${at}  ${String(f.severity)}  ${String(f.checkId)}  ${String(f.message)}`);
+        }
+    }
+    for (const s of plan.unreadable)
+        lines.push(`── ${s.name}  ${s.dir}  (${s.reason.code}: ${s.reason.message})`);
+    const errors = doc.findings.filter((f) => f.severity === "error").length;
+    lines.push("", `${doc.findings.length} finding${doc.findings.length === 1 ? "" : "s"}, ${errors} error${errors === 1 ? "" : "s"}`);
+    return lines.join("\n");
+}
+export function memberStatus(name, dir, kind, status, reason, chant) {
+    return { name, dir, kind, status, reason, chant, irVersion: null, live: false };
+}
+export async function runWorkspaceMembers(ctx, verb) {
+    // graph is part of the read contract, with --at and its own document (#2536).
+    if (verb === "graph")
+        return (await import("./graph-cli.js")).runWorkspaceGraph(ctx);
+    const { args } = ctx;
+    const start = resolve(args.extraPositional ?? ".");
+    const found = existsSync(start) ? findWorkspaceRoot(start) : undefined;
+    if (!found) {
+        console.error(formatError({ message: `declaration-missing: no chant.workspace.json or .jsonc between ${start} and the git root; chant workspace init proposes one`, hint: USAGE[verb] }));
+        return 1;
+    }
+    let plan;
+    try {
+        plan = planMembers(verb, found.dir, { only: args.members });
+    }
+    catch (err) {
+        if (!(err instanceof WorkspaceReadError))
+            throw err;
+        console.error(formatError({ message: `${err.code}: ${err.describe()}`, hint: USAGE[verb] }));
+        return 1;
+    }
+    if (args.dryRun) {
+        if (args.json)
+            console.log(JSON.stringify(planJson(plan), null, 2));
+        else
+            console.log(describePlan(plan));
+        return 0;
+    }
+    const results = await executePlan(plan, args);
+    const anyFailed = results.some((r) => r.exitCode !== 0) || plan.unreadable.length > 0;
+    const workspace = { name: plan.workspace.name, root: plan.workspace.root };
+    if (verb === "lint" && args.format === "sarif") {
+        for (const r of results)
+            if (r.stderr.trim())
+                process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+        const unreadable = plan.unreadable.map((s) => ({ id: s.name, member: s.name, dir: s.dir ?? ".", exitCode: 1, stdout: "", stderr: `${s.reason.code}: ${s.reason.message}` }));
+        emitDocument(mergeSarif([...results, ...unreadable], plan.workspace.root), args.output);
+        console.error(summaryLine(plan, results));
+        return anyFailed ? 1 : 0;
+    }
+    if (verb === "audit" && !(args.json || args.format === "json")) {
+        for (const r of results)
+            if (r.stderr.trim())
+                process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+        const merged = mergeAudit(results, workspace);
+        console.log(formatAuditText(merged, plan));
+        console.error(summaryLine(plan, results));
+        return anyFailed ? 1 : 0;
+    }
+    if ((verb === "lint" && args.format === "json") || verb === "audit") {
+        for (const r of results)
+            if (r.stderr.trim())
+                process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+        let doc;
+        if (verb === "audit") {
+            const merged = mergeAudit(results, workspace);
+            for (const s of plan.unreadable)
+                merged.members.push({ member: s.name, dir: s.dir ?? ".", exitCode: 1, status: "failed", summary: null, error: `${s.reason.code}: ${s.reason.message}` });
+            doc = { ...merged, skipped: plan.skipped };
+        }
+        else {
+            doc = {
+                workspace,
+                members: [
+                    ...results.map((r) => {
+                        let diagnostics = null;
+                        try {
+                            diagnostics = JSON.parse(r.stdout);
+                        }
+                        catch {
+                            // A member whose lint printed no JSON keeps null, with its exit code saying why.
+                        }
+                        return { member: r.id, dir: r.dir, exitCode: r.exitCode, diagnostics };
+                    }),
+                    ...plan.unreadable.map((s) => ({ member: s.name, dir: s.dir, exitCode: 1, diagnostics: null, reason: s.reason })),
+                ],
+                skipped: plan.skipped,
+            };
+        }
+        emitDocument(doc, args.output);
+        console.error(summaryLine(plan, results));
+        return anyFailed ? 1 : 0;
+    }
+    // Text: each member's own output under a heading. A build without -o prints
+    // no templates, since several members' templates can't share one stdout.
+    printSections(plan, results, verb !== "build" || args.output !== undefined);
+    return anyFailed ? 1 : 0;
+}