@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/lineage-check.js

@@ -0,0 +1,282 @@
+/**
+ * `chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>]`:
+ * 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. `--kind`
+ * reads a record kind's records and reports the files they pin by hash that
+ * have changed since (#2549). `--live --env <env>` resolves each declared
+ * member link against the live graph of `<env>` (`./checks/live.ts`, #2549):
+ * it is the one option that reaches a network, through each member's own
+ * `chant graph --live`, and is catalogued as egress.
+ *
+ * `chant workspace upgrade` runs the same checks in its staging worktree
+ * before it reaches its gate.
+ *
+ * `--changes <base>..<head>` runs the forward coverage check instead
+ * (`changes-cli.ts`, #2773), which prints a document of its own.
+ */
+import { realpathSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { formatError, formatSuccess } from "../cli/format.js";
+import { findWorkspaceRoot } from "../project-root.js";
+import { LOCK_FILE, LockError, parseLock, readLock } from "./lineage-lock.js";
+/** Closed: a reader may switch on it. */
+export const CHECK_CODES = ["lock-invalid", "manual-step-open"];
+/**
+ * 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, lockText) {
+    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 = [];
+    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) {
+    return `${f.code}\0${f.scope ?? ""}\0${f.path ?? ""}`;
+}
+const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>]\n       chant workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]";
+const FORMATS = ["stylish", "json", "sarif"];
+/** A lock finding as a lint diagnostic, for `--format json` and `--format sarif`. */
+function lockDiagnostic(f) {
+    return { file: f.path ?? LOCK_FILE, line: 1, column: 1, ruleId: f.code, severity: "error", message: f.message };
+}
+const LOCK_RULES = [
+    { 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) {
+    const doc = JSON.parse(sarif);
+    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, to) {
+    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"];
+/**
+ * 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, at, options = {}) {
+    // 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.js"),
+        import("./tree.js"),
+    ]);
+    const head = { $schema: CHECK_OUTPUT_SCHEMA_ID, contract: CHECK_CONTRACT_VERSION, chant: readerVersion() };
+    let report;
+    /** The declaration's directory on disk, its root relative to the git root, and the files to check. */
+    let found;
+    let commit = 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;
+    let workspace = null;
+    if (found) {
+        const { runDeclarationChecks } = await import("./checks.js");
+        const { dir, tree } = found;
+        const records = options.kind !== undefined ? await readRecordFacts(options.kind, cwd, commit) : undefined;
+        declaration = await runDeclarationChecks(dir, (file) => relative(cwd, join(dir, file)).split(sep).join("/"), {
+            runGenerators: options.runGenerators === true,
+            ...(commit !== null ? { tree } : {}),
+            ...(records ? { records } : {}),
+            ...(options.live ? { live: options.live } : {}),
+        });
+        let name = 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 } : {}) };
+}
+/** The records of the kind file `kind` for the record checks (#2549), at `commit` or in the working tree. */
+async function readRecordFacts(kind, cwd, commit) {
+    const [{ readRecordsFor }, { RecordReadError }] = await Promise.all([import("./records-cli.js"), import("./records.js")]);
+    try {
+        const read = await readRecordsFor({ kind, cwd, ...(commit !== null ? { at: commit } : {}) });
+        return { kind, records: read.result.records.map((r) => ({ ...r, file: join(read.root, ...r.path.split("/")) })) };
+    }
+    catch (err) {
+        if (!(err instanceof RecordReadError))
+            throw err;
+        return { kind, error: { code: err.code, message: err.message } };
+    }
+}
+export async function runWorkspaceCheck(ctx) {
+    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;
+    }
+    // The forward coverage check (#2773) is its own document.
+    if (ctx.args.changes !== undefined) {
+        if (ctx.args.at !== undefined) {
+            console.error(formatError({ message: "--changes reads the records at the range's head, so it takes no --at", hint: USAGE }));
+            return 1;
+        }
+        const { handToRootChant } = await import("./which-chant.js");
+        const handed = await handToRootChant(root, undefined);
+        if (handed !== undefined)
+            return handed;
+        return (await import("./changes-cli.js")).runWorkspaceChanges(ctx, root);
+    }
+    if (ctx.args.live) {
+        // A live read is of the account now, and it needs the environment each member's `chant graph --live` reads.
+        const problem = ctx.args.at !== undefined
+            ? "--live reads the account as it stands now, and --at reads the source at a revision; chant workspace check takes one of them"
+            : !ctx.args.env
+                ? "--live needs an environment, as each member's chant graph --live does: --live --env <env>"
+                : undefined;
+        if (problem) {
+            console.error(formatError({ message: problem, hint: USAGE }));
+            return 1;
+        }
+    }
+    const format = (ctx.args.format || "stylish");
+    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.js");
+        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, ...(ctx.args.kind !== undefined ? { kind: ctx.args.kind } : {}), ...(ctx.args.live && ctx.args.env ? { live: { env: ctx.args.env, onStderr: (text) => process.stderr.write(text) } } : {}) });
+    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;
+    }
+    if (ctx.args.live && !doc.declaration) {
+        console.error(formatError({ message: "--live resolves a workspace's member links, and there is no chant.workspace.json between here and the git root", 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.js");
+        const diagnostics = [...report.findings.map(lockDiagnostic), ...(declaration?.diagnostics ?? [])];
+        const suppressed = declaration?.suppressed ?? [];
+        const { workspaceCheckRules } = await import("./checks.js");
+        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.js");
+        console.log(formatStylish(declaration.diagnostics, declaration.suppressed));
+    }
+    return ok ? 0 : 1;
+}

package/dist/workspace/lineage-cli.js

@@ -0,0 +1,121 @@
+/**
+ * `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.js";
+import { LOCK_FILE, LockError, readLock, resolveManualStep, scopeStatus, writeLock } from "./lineage-lock.js";
+import { lineageProvenance } from "./lineage-provenance.js";
+const USAGE = "chant workspace lineage [--json] | chant workspace lineage resolve <path>";
+/** One line naming a scope's source kind and where it points (#2647). */
+export function describeSource(source) {
+    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) {
+    const lock = readLock(root);
+    if (!lock)
+        return null;
+    const scopes = Object.entries(lock.scopes).map(([scope, lineage]) => {
+        const st = scopeStatus(root, scope, lineage);
+        const view = {
+            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,
+            ...(lineage.adoption ? { adoption: lineage.adoption } : {}),
+        };
+        const provenance = lineageProvenance(root, lineage);
+        return provenance ? { ...view, provenance } : view;
+    });
+    return { lock: LOCK_FILE, scopes };
+}
+export async function runWorkspaceLineage(ctx) {
+    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 = [];
+        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)}`);
+            if (s.adoption?.by === "lineage" && s.adoption.previous)
+                lines.push(`  moved from ${describeSource(s.adoption.previous.source)} by adopt-lineage`);
+            if (s.adoption?.by === "files")
+                lines.push(`  adopted up to ${s.adoption.commits.to.slice(0, 12)}: ${s.provenance?.level ?? "unattested"}, ${s.provenance?.reason ?? ""}`.replace(/, $/, ""));
+            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, path) {
+    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;
+}