@intentius/chant 0.124.13 → 0.124.15

package/dist/cli/commands/onboard.js

@@ -0,0 +1,403 @@
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { formatSuccess, formatError, formatWarning } from "../format.js";
+import { lexiconModulePath, lexiconSourceLabel } from "../../lexicon-module.js";
+/** Resolve the monorepo root (5 dirs up from packages/core/src/cli/commands/). */
+function findRepoRoot() {
+    const here = dirname(fileURLToPath(import.meta.url)); // commands/
+    return dirname(dirname(dirname(dirname(dirname(here))))); // -> root
+}
+/**
+ * A real prepack invocation line: a Dockerfile `RUN`, a workflow `- run:`,
+ * or a bare line inside a `run: |` block. Comments, `echo` messages and
+ * `$lex` / `<lex>` placeholders do not match. Matching those placeholder
+ * substrings was how onboard appended duplicates to Dockerfile.smoke on
+ * every run (#1678).
+ */
+const PREPACK_LINE = /^\s*(?:RUN\s+|-\s*run:\s*)?npm run --prefix lexicons\/[a-z0-9-]+ prepack\s*$/i;
+function isPrepackLine(line) {
+    return PREPACK_LINE.test(line);
+}
+/** A YAML comment line, e.g. the cedar note sitting mid-list in chant.yml. */
+const COMMENT_LINE = /^\s*#/;
+function isCommentLine(line) {
+    return COMMENT_LINE.test(line);
+}
+function hasPrepackLine(lines, name) {
+    return lines.some((l) => isPrepackLine(l) && l.includes(`lexicons/${name} prepack`));
+}
+/** Shell loop header over lexicon names: `for lex in aws gcp k8s; do \`. */
+const LEX_LOOP = /^(\s*(?:RUN\s+)?for lex in )([a-z0-9][a-z0-9 -]*?)(\s*;\s*do\b.*)$/i;
+function loopCoversLexicon(lines, name) {
+    return lines.some((l) => {
+        const m = l.match(LEX_LOOP);
+        return m !== null && m[2].split(/\s+/).includes(name);
+    });
+}
+/**
+ * Append the lexicon to every `for lex in ...` loop list that does not
+ * already contain it. Returns true when at least one list changed.
+ */
+function addToLexiconLoops(lines, name) {
+    let changed = false;
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(LEX_LOOP);
+        if (!m)
+            continue;
+        const names = m[2].split(/\s+/).filter(Boolean);
+        if (names.includes(name))
+            continue;
+        names.push(name);
+        lines[i] = `${m[1]}${names.join(" ")}${m[3]}`;
+        changed = true;
+    }
+    return changed;
+}
+/**
+ * Patch root package.json to add a workspace dependency for the lexicon.
+ */
+function patchRootPackageJson(root, name) {
+    const pkgPath = join(root, "package.json");
+    if (!existsSync(pkgPath))
+        return { patched: false, reason: "root package.json not found" };
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const depKey = `@intentius/chant-lexicon-${name}`;
+    if (pkg.dependencies?.[depKey]) {
+        return { patched: false, reason: `${depKey} already in dependencies` };
+    }
+    pkg.dependencies = pkg.dependencies ?? {};
+    pkg.dependencies[depKey] = "workspace:*";
+    // Sort dependencies for consistency
+    const sorted = {};
+    for (const k of Object.keys(pkg.dependencies).sort()) {
+        sorted[k] = pkg.dependencies[k];
+    }
+    pkg.dependencies = sorted;
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    return { patched: true };
+}
+/**
+ * Patch the root tsconfig.json `paths` map (#1614).
+ *
+ * The whole-repo typecheck runs with `moduleResolution: node`, which never
+ * reads package exports maps, so every lexicon needs a bare + subpath
+ * mapping here or an example importing the package fails to resolve.
+ *
+ * Entries are `./`-prefixed like every other entry (#3227): with no `baseUrl`
+ * (removed in #3205) a bare `lexicons/...` path is invalid and tsx's tsconfig
+ * loader throws on it for every run in the repo.
+ */
+export function patchRootTsconfigPaths(root, name) {
+    const tsconfigPath = join(root, "tsconfig.json");
+    if (!existsSync(tsconfigPath))
+        return { patched: false, reason: "root tsconfig.json not found" };
+    const cfg = JSON.parse(readFileSync(tsconfigPath, "utf-8"));
+    cfg.compilerOptions = cfg.compilerOptions ?? {};
+    const paths = (cfg.compilerOptions.paths = cfg.compilerOptions.paths ?? {});
+    const bare = `@intentius/chant-lexicon-${name}`;
+    const wanted = {
+        [bare]: [`./lexicons/${name}/src/index.ts`],
+        [`${bare}/*`]: [`./lexicons/${name}/src/*`],
+    };
+    let changed = false;
+    for (const [key, value] of Object.entries(wanted)) {
+        if (Array.isArray(paths[key]) && paths[key].length > 0)
+            continue;
+        paths[key] = value;
+        changed = true;
+    }
+    if (!changed)
+        return { patched: false, reason: `${bare} already in paths` };
+    writeFileSync(tsconfigPath, JSON.stringify(cfg, null, 2) + "\n");
+    return { patched: true };
+}
+/**
+ * Insert a new prepack line after the last prepack line in each contiguous group
+ * of 2+ prepack lines. Single standalone lines (like YAML `run:` values) are
+ * ignored. Used for multi-line `run: |` blocks in workflows.
+ *
+ * A comment line between two prepack lines (the cedar note in chant.yml's
+ * check and test jobs) does not end the group: it is skipped when scanning,
+ * so the block still gets exactly one insertion, anchored after its last
+ * real prepack line rather than after the comment (#2098).
+ */
+function insertPrepackInContiguousGroups(lines, name) {
+    if (hasPrepackLine(lines, name))
+        return false;
+    // Identify contiguous groups of prepack lines, treating comment lines
+    // inside a group as pass-through rather than a boundary.
+    const groups = [];
+    let groupStart = -1;
+    let lastPrepackIdx = -1;
+    let count = 0;
+    const closeGroup = () => {
+        if (groupStart !== -1)
+            groups.push({ lastPrepackIdx, count });
+        groupStart = -1;
+        count = 0;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        if (isPrepackLine(lines[i])) {
+            if (groupStart === -1)
+                groupStart = i;
+            lastPrepackIdx = i;
+            count++;
+        }
+        else if (isCommentLine(lines[i])) {
+            // Skip: does not extend a group on its own, and does not close one.
+            continue;
+        }
+        else {
+            closeGroup();
+        }
+    }
+    closeGroup();
+    // Only insert into groups of 2+ prepack lines (multi-line blocks, not standalone steps)
+    const insertAfter = groups.filter((g) => g.count > 1).map((g) => g.lastPrepackIdx);
+    if (insertAfter.length === 0)
+        return false;
+    for (const idx of insertAfter.reverse()) {
+        const newLine = lines[idx].replace(/lexicons\/[a-z0-9-]+/i, `lexicons/${name}`);
+        lines.splice(idx + 1, 0, newLine);
+    }
+    return true;
+}
+/**
+ * Insert a new prepack line after every last-in-group prepack line (groups of 1+).
+ * Used for publish.yml and Dockerfiles that list one RUN per lexicon.
+ */
+export function insertPrepackAfterEach(lines, name) {
+    if (hasPrepackLine(lines, name))
+        return false;
+    const insertAfter = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!isPrepackLine(lines[i]))
+            continue;
+        const nextIsAlsoPrepack = i + 1 < lines.length && isPrepackLine(lines[i + 1]);
+        if (!nextIsAlsoPrepack) {
+            insertAfter.push(i);
+        }
+    }
+    if (insertAfter.length === 0)
+        return false;
+    for (const idx of insertAfter.reverse()) {
+        const newLine = lines[idx].replace(/lexicons\/[a-z0-9-]+/i, `lexicons/${name}`);
+        lines.splice(idx + 1, 0, newLine);
+    }
+    return true;
+}
+/**
+ * Patch chant.yml: add prepack lines in check/test multi-line `run: |` blocks,
+ * and add a new validate step.
+ *
+ * The file has two patterns:
+ * 1. Multi-line blocks (check + test jobs): `run: |\n  npm run --prefix lexicons/aws prepack\n  ...`
+ * 2. Standalone steps (validate job): `- name: Generate and validate ...\n  run: npm run --prefix ...`
+ *
+ * We only insert into pattern 1 (contiguous groups) and separately add a new pattern 2 step.
+ */
+function patchCiWorkflow(root, name) {
+    const filePath = join(root, ".github/workflows/chant.yml");
+    if (!existsSync(filePath))
+        return { patched: false, reason: "chant.yml not found" };
+    const content = readFileSync(filePath, "utf-8");
+    const lines = content.split("\n");
+    if (hasPrepackLine(lines, name)) {
+        return { patched: false, reason: `${name} already in chant.yml` };
+    }
+    // 1. Insert into multi-line `run: |` blocks only (contiguous prepack groups of 2+).
+    //    The validate job has standalone steps that are NOT contiguous, so they won't match.
+    let changed = insertPrepackInContiguousGroups(lines, name);
+    // 2. Add a named validate step after the last "Generate and validate" step
+    const displayName = name.charAt(0).toUpperCase() + name.slice(1);
+    const validateStepName = `Generate and validate ${displayName} lexicon`;
+    if (!lines.some((l) => l.includes(validateStepName))) {
+        let lastValidateRunIdx = -1;
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].includes("Generate and validate")) {
+                if (i + 1 < lines.length && lines[i + 1].trimStart().startsWith("run:")) {
+                    lastValidateRunIdx = i + 1;
+                }
+            }
+        }
+        if (lastValidateRunIdx > 0) {
+            const block = [
+                "",
+                `      - name: ${validateStepName}`,
+                `        run: npm run --prefix lexicons/${name} prepack`,
+            ];
+            lines.splice(lastValidateRunIdx + 1, 0, ...block);
+            changed = true;
+        }
+    }
+    if (!changed)
+        return { patched: false, reason: "no prepack block found to anchor on" };
+    writeFileSync(filePath, lines.join("\n"));
+    return { patched: true };
+}
+/**
+ * Patch publish.yml: add the prepack line to the test job.
+ *
+ * No publish step is added. scripts/publish-packages.sh enumerates every
+ * non-private workspace package at run time, so a new lexicon is published
+ * the moment it exists — that is deliberate. Hand-maintained publish steps
+ * were how k8s-client (#1177) and fountain (#1253) each shipped a package
+ * the release pipeline could not publish.
+ */
+function patchPublishWorkflow(root, name) {
+    const filePath = join(root, ".github/workflows/publish.yml");
+    if (!existsSync(filePath))
+        return { patched: false, reason: "publish.yml not found" };
+    const lines = readFileSync(filePath, "utf-8").split("\n");
+    if (hasPrepackLine(lines, name)) {
+        return { patched: false, reason: `prepack for ${name} already present` };
+    }
+    if (!insertPrepackAfterEach(lines, name)) {
+        // #3227 — not a failure and not "covered by a prepack line": publish.yml
+        // carries no per-lexicon lines. The run builds every lexicon through
+        // scripts/ci-lexicon-artifacts.sh and publishes through
+        // scripts/publish-packages.sh, both of which enumerate the workspace.
+        return {
+            patched: false,
+            reason: "nothing to patch: it has no per-lexicon prepack lines; scripts/ci-lexicon-artifacts.sh and scripts/publish-packages.sh enumerate the workspace",
+        };
+    }
+    writeFileSync(filePath, lines.join("\n"));
+    return { patched: true };
+}
+/**
+ * Patch a smoke Dockerfile so it covers the lexicon.
+ *
+ * Two layouts exist. Loop-based files (`for lex in aws gcp ...; do`) get the
+ * name appended to every loop list. Per-lexicon files (`RUN npm run --prefix
+ * lexicons/<x> prepack` lines) get one more RUN line. A file that already
+ * covers the lexicon either way is reported as such and left untouched.
+ */
+export function patchDockerfile(filePath, name) {
+    if (!existsSync(filePath))
+        return { patched: false, reason: `${filePath} not found` };
+    const lines = readFileSync(filePath, "utf-8").split("\n");
+    if (loopCoversLexicon(lines, name) || hasPrepackLine(lines, name)) {
+        return { patched: false, reason: `already covers ${name}` };
+    }
+    const changed = addToLexiconLoops(lines, name) || insertPrepackAfterEach(lines, name);
+    if (!changed) {
+        // #3227 — the smoke-npm and smoke-e2e images read their lexicon list from
+        // a file. Point at it instead of reporting a missing anchor.
+        const listFile = lines.join("\n").match(/test\/(smoke-[\w-]+-lexicons\.txt)/)?.[1];
+        if (listFile) {
+            return { patched: false, reason: `reads its lexicon list from test/${listFile}, not from the Dockerfile` };
+        }
+        return { patched: false, reason: "no lexicon loop or prepack line found to anchor on" };
+    }
+    writeFileSync(filePath, lines.join("\n"));
+    return { patched: true };
+}
+/**
+ * Append a lexicon to a one-name-per-line list file (test/smoke-npm-lexicons.txt).
+ * Idempotent; keeps the file's trailing newline.
+ */
+export function patchLexiconList(filePath, name) {
+    const rel = filePath.split("/").slice(-2).join("/");
+    if (!existsSync(filePath))
+        return { patched: false, reason: `${rel} not found` };
+    const content = readFileSync(filePath, "utf-8");
+    if (content.split("\n").some((l) => l.trim() === name)) {
+        return { patched: false, reason: `${name} already in ${rel}` };
+    }
+    const sep = content === "" || content.endsWith("\n") ? "" : "\n";
+    writeFileSync(filePath, `${content}${sep}${name}\n`);
+    return { patched: true };
+}
+/**
+ * Execute the onboard command — patches monorepo infrastructure for a new lexicon.
+ */
+export function onboardCommand(options) {
+    // chant#2578 — onboard wires a lexicon package into the chant monorepo. A
+    // lexicon declared by path has no package, so there is nothing to wire and
+    // no install step to print; say where it loads from instead.
+    if (lexiconModulePath(options.name) !== undefined) {
+        return {
+            success: false,
+            patched: [],
+            skipped: [],
+            error: `lexicon "${options.name}" is declared by path in chant.config.ts and loads from ${lexiconSourceLabel(options.name)}. ` +
+                "onboard adds a lexicon package to the chant monorepo, and a lexicon loaded by path has no package to add.",
+        };
+    }
+    const root = options.root ?? findRepoRoot();
+    const patched = [];
+    const skipped = [];
+    const record = (label, summary, result) => {
+        if (result.patched)
+            patched.push(`${label} (${summary})`);
+        else
+            skipped.push(`${label}: ${result.reason}`);
+    };
+    // 1. Root package.json
+    record("package.json", "root dependency", patchRootPackageJson(root, options.name));
+    // 2. Root tsconfig.json paths (#1614)
+    record("tsconfig.json", "paths mapping", patchRootTsconfigPaths(root, options.name));
+    // 3. CI workflow
+    record("chant.yml", "prepack + validate", patchCiWorkflow(root, options.name));
+    // 4. Publish workflow
+    record("publish.yml", "prepack", patchPublishWorkflow(root, options.name));
+    // 5. Dockerfiles
+    record("Dockerfile.smoke", "lexicon list", patchDockerfile(join(root, "test/Dockerfile.smoke"), options.name));
+    record("Dockerfile.smoke-npm", "lexicon list", patchDockerfile(join(root, "test/Dockerfile.smoke-npm"), options.name));
+    // 6. Smoke image lexicon lists (#3227). The npm smoke packs every lexicon.
+    //    The e2e list is opt-in: it names the lexicons an example uses plus
+    //    their dependencies, so onboard leaves it alone and says so.
+    record("smoke-npm-lexicons.txt", "lexicon list", patchLexiconList(join(root, "test/smoke-npm-lexicons.txt"), options.name));
+    if (existsSync(join(root, "test/smoke-e2e-lexicons.txt"))) {
+        skipped.push(`smoke-e2e-lexicons.txt: not patched; it lists only lexicons an e2e example uses (and their dependencies). Add ${options.name} to test/smoke-e2e-lexicons.txt when an example needs it`);
+    }
+    return { success: true, patched, skipped, verbose: options.verbose };
+}
+/**
+ * Print onboard results and remaining manual steps.
+ */
+export async function printOnboardResult(result, name) {
+    if (!result.success) {
+        console.error(formatError({ message: result.error ?? "onboard failed" }));
+        return;
+    }
+    if (result.patched.length > 0) {
+        console.log(formatSuccess("Patched:"));
+        for (const f of result.patched) {
+            console.log(`  ${f}`);
+        }
+    }
+    if (result.skipped.length > 0) {
+        console.log("");
+        console.log("Not patched (already covered, or nothing to patch):");
+        for (const s of result.skipped) {
+            console.log(`  ${s}`);
+        }
+    }
+    console.log("");
+    console.log("Remaining manual steps:");
+    console.log(`  1. Create an example: lexicons/${name}/examples/<example-name>/`);
+    console.log(`     (must depend on @intentius/chant-lexicon-${name} for workspace resolution)`);
+    console.log(`  2. Add smoke tests to test/integration.sh`);
+    console.log(`  3. Run: npm install (to update workspace links)`);
+    console.log(`  4. First release: just release-lexicon ${name} patch`);
+    console.log(`  5. Run: chant dev check-lexicon lexicons/${name} (to see completeness status)`);
+    console.log(formatWarning({
+        message: "First-time scoped packages may publish as private despite --access public",
+    }));
+    console.log(`     Check https://www.npmjs.com/org/intentius and toggle visibility if needed`);
+    // Under --verbose, run check-lexicon now instead of leaving step 5 to the
+    // author, printing the full tier 1/2/3 detail rather than just the summary above.
+    if (result.verbose) {
+        const lexiconDir = join(findRepoRoot(), "lexicons", name);
+        if (existsSync(lexiconDir)) {
+            console.log("");
+            console.log("Lexicon completeness:");
+            const { checkLexicon, printCheckResult } = await import("./check-lexicon.js");
+            const checkResult = await checkLexicon(lexiconDir);
+            printCheckResult(checkResult, false);
+        }
+    }
+}

package/dist/cli/commands/pinned-upgrade.js

@@ -0,0 +1,191 @@
+/**
+ * `chant dev pinned-upgrade <lexicon-dir>` command implementation.
+ *
+ * Detects whether a lexicon that declares `upstreamPin` has a
+ * newer stable upstream release. When it does, it dry-run bumps the pinned
+ * version constant, regenerates + surface-diffs (via #524's regenLexicon), then
+ * reverts the bump — leaving the working tree unchanged.
+ *
+ * This command only REPORTS. Branch/PR automation lives in #527.
+ */
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { checkPinnedUpgrades, lexiconNameOf, } from "../../codegen/pinned-upgrade.js";
+/**
+ * Infer the lexicon id from a directory: its package name
+ * (`@intentius/chant-lexicon-<name>`), else the directory name. Whether the
+ * lexicon is pinned is the plugin's `upstreamPin`, checked by
+ * `checkPinnedUpgrade`, not a list here.
+ */
+export function inferLexicon(lexiconDir) {
+    return lexiconNameOf(lexiconDir);
+}
+/**
+ * Map a regen severity to a semver review label.
+ * additive → "minor"; breaking → "major"; none → "none".
+ */
+export function semverLabel(result) {
+    const sev = result.validation?.severity;
+    if (sev === "breaking")
+        return "major";
+    if (sev === "additive")
+        return "minor";
+    return "none";
+}
+/**
+ * Run the pinned-upgrade check and return the structured result.
+ * Never throws — a missing dir or a lexicon with no `upstreamPin` becomes a fetchError.
+ */
+export async function runPinnedUpgrade(opts) {
+    return (await runPinnedUpgrades(opts))[0];
+}
+/**
+ * Run the check for every pin the plugin declares (or the one in `opts.pin`),
+ * one result each. A lexicon with one pin gives one result.
+ */
+export async function runPinnedUpgrades(opts) {
+    const dir = resolve(opts.lexiconDir);
+    const lexicon = opts.lexicon ?? inferLexicon(dir);
+    if (!existsSync(dir)) {
+        return [
+            {
+                lexicon,
+                hasUpgrade: false,
+                from: "(unknown)",
+                to: null,
+                validation: null,
+                fetchError: `Lexicon directory not found: ${dir}`,
+            },
+        ];
+    }
+    return checkPinnedUpgrades({
+        lexiconDir: dir,
+        lexicon,
+        pin: opts.pin,
+        force: opts.force,
+        verbose: opts.verbose,
+    });
+}
+// ── Human-readable output ─────────────────────────────────────────────
+const COLORS = {
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    gray: "\x1b[90m",
+    bold: "\x1b[1m",
+    reset: "\x1b[0m",
+};
+function useColors() {
+    return !process.env.NO_COLOR && process.stdout.isTTY !== false;
+}
+function c(text, code) {
+    return useColors() ? `${code}${text}${COLORS.reset}` : text;
+}
+/**
+ * Print the pinned-upgrade result. `json` emits a machine-readable object.
+ */
+export function printPinnedUpgradeResult(result, json) {
+    const label = semverLabel(result);
+    const name = result.pin ? `${result.lexicon}/${result.pin}` : result.lexicon;
+    if (json) {
+        console.log(JSON.stringify({
+            lexicon: result.lexicon,
+            ...(result.pin ? { pin: result.pin } : {}),
+            hasUpgrade: result.hasUpgrade,
+            from: result.from,
+            to: result.to,
+            semver: label,
+            severity: result.validation?.severity ?? "none",
+            changed: result.validation?.changed ?? false,
+            delta: result.validation?.delta ?? null,
+            validationOk: result.validation?.ok ?? null,
+            failures: result.validation?.failures ?? [],
+            fetchError: result.fetchError,
+            manualPin: result.manualPin ?? null,
+        }, null, 2));
+        return;
+    }
+    if (result.fetchError) {
+        console.log(c(`[${name}] error: ${result.fetchError}`, COLORS.red));
+        return;
+    }
+    if (!result.hasUpgrade) {
+        console.log(c(`[${name}] up to date`, COLORS.green) +
+            `  pinned=${result.from}` +
+            (result.to ? ` latest=${result.to}` : ""));
+        return;
+    }
+    if (result.manualPin) {
+        console.log(c(`[${name}] upgrade available`, COLORS.bold) + `  ${result.from} -> ${result.to}`);
+        console.log(`  The pin in ${result.manualPin.file} cannot be rewritten generically, so nothing was edited or regenerated.`);
+        console.log(`  ${result.manualPin.instructions}`);
+        return;
+    }
+    // Upgrade available
+    console.log(c(`[${name}] upgrade available`, COLORS.bold) +
+        `  ${result.from} -> ${result.to}`);
+    const v = result.validation;
+    if (v) {
+        // Surface delta
+        if (v.deltaText) {
+            console.log("");
+            console.log(v.deltaText);
+        }
+        else if (v.changed) {
+            console.log("  Surface changed (no baseline to diff against).");
+        }
+        else {
+            console.log("  No surface changes.");
+        }
+        // Failures
+        if (v.failures.length > 0) {
+            console.log("");
+            console.log(c(`  ${v.failures.length} validation step(s) failed:`, COLORS.bold));
+            for (const f of v.failures) {
+                console.log(c(`    FAIL [${f.step}]${f.exitCode !== undefined ? ` (exit ${f.exitCode})` : ""}`, COLORS.red));
+                if (f.output) {
+                    const indented = f.output
+                        .split("\n")
+                        .map((l) => `         ${l}`)
+                        .join("\n");
+                    console.log(c(indented, COLORS.gray));
+                }
+            }
+        }
+    }
+    console.log("");
+    const labelColor = label === "major" ? COLORS.red : label === "minor" ? COLORS.yellow : COLORS.green;
+    const validationLabel = v
+        ? v.ok
+            ? c("ok", COLORS.green)
+            : c("FAILED", COLORS.red)
+        : c("skipped", COLORS.gray);
+    console.log(`Validation: ${validationLabel}  Semver: ${c(label, labelColor)}  ${result.from} -> ${result.to}`);
+}
+/**
+ * Print one result per pin. One result prints exactly as `printPinnedUpgradeResult`;
+ * several print in turn, and `json` emits an array of the same objects.
+ */
+export function printPinnedUpgradeResults(results, json) {
+    if (results.length === 1) {
+        printPinnedUpgradeResult(results[0], json);
+        return;
+    }
+    if (json) {
+        // Each result prints as its own JSON object; collect them into one array.
+        const lines = [];
+        const log = console.log;
+        console.log = (...a) => void lines.push(a.join(" "));
+        try {
+            for (const r of results)
+                printPinnedUpgradeResult(r, true);
+        }
+        finally {
+            console.log = log;
+        }
+        console.log(`[${lines.join(",\n")}]`);
+        return;
+    }
+    for (const r of results)
+        printPinnedUpgradeResult(r, false);
+}