flagrm 0.1.0

package/dist/adapters/generic/text.js

@@ -0,0 +1,93 @@
+/**
+ * Language-agnostic text helpers for the generic adapter: config-file
+ * detection, eval-call patterns, `NAME = "flag"` declarations and paren
+ * matching, all skipping comments with a per-extension lexical mask.
+ */
+import path from "node:path";
+import { commentSyntax, computeLexicalMask, LEX_CODE, methodNamePattern } from "../../core/scan.js";
+const CONFIG_EXTENSIONS = new Set([".json", ".yaml", ".yml", ".toml", ".properties", ".ini", ".env"]);
+/** Configuration files: every mention of the flag in one is a `config` site. */
+export function isConfigFile(file) {
+    const base = path.basename(file).toLowerCase();
+    return CONFIG_EXTENSIONS.has(path.extname(base)) || base === ".env" || base.startsWith(".env.");
+}
+/** Code/comment/string classes per character, or null when the file's comment syntax is unknown (all code). */
+export function lexicalMask(file, text) {
+    const syntax = commentSyntax(file);
+    return syntax ? computeLexicalMask(text, syntax) : null;
+}
+/** `(?<![\w$])(?:IsEnabled|...)\s*\(` for the configured eval methods, or undefined when there are none. */
+export function evalCallPattern(methods) {
+    if (methods.length === 0)
+        return undefined;
+    return new RegExp(`(?<![\\w$])(?:${methods.map(methodNamePattern).join("|")})\\s*\\(`, "g");
+}
+/** Declaration keywords, modifiers and built-in string types that are never the declared name. */
+const NOT_A_NAME = new Set([
+    "const",
+    "let",
+    "var",
+    "val",
+    "final",
+    "static",
+    "public",
+    "private",
+    "protected",
+    "internal",
+    "readonly",
+    "export",
+    "pub",
+    "mut",
+    "my",
+    "our",
+    "local",
+    "string",
+    "String",
+    "str",
+]);
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/**
+ * The name a string literal starting at `quote` is assigned to, on the same
+ * line: `X = "flag"`, `X := "flag"`, `const X string = "flag"`,
+ * `static final String X = "flag"`, `X: str = "flag"`. Undefined for
+ * comparisons, keyword arguments, member assignments (`self.x = ...`) and
+ * anything else that isn't a plain declaration. Go writes the type after the
+ * name, so in `.go` files the first identifier wins, elsewhere the last.
+ */
+export function declaredName(text, quote, file) {
+    let eq = quote - 1;
+    while (eq >= 0 && (text[eq] === " " || text[eq] === "\t"))
+        eq--;
+    if (text[eq] !== "=" || /[=!<>+\-*/%&|^~]/.test(text[eq - 1] ?? ""))
+        return undefined;
+    const lineStart = text.lastIndexOf("\n", eq - 1) + 1;
+    let prefix = text.slice(lineStart, eq);
+    if (prefix.endsWith(":"))
+        prefix = prefix.slice(0, -1);
+    const count = (c) => prefix.split(c).length - 1;
+    if (count("(") > count(")") || count("[") > count("]"))
+        return undefined;
+    // A type annotation (`X: str`, `X: &'static str`).
+    prefix = prefix.replace(/:\s*[&\w$.<>[\], ']+$/, "");
+    const tokens = [...prefix.matchAll(/[^\s,;{}]+/g)];
+    if (tokens.length === 0 || !IDENTIFIER.test(tokens[tokens.length - 1][0]))
+        return undefined;
+    const names = tokens.filter((t) => !NOT_A_NAME.has(t[0]));
+    if (names.length === 0 || !names.every((t) => IDENTIFIER.test(t[0])))
+        return undefined;
+    const pick = file.endsWith(".go") ? names[0] : names[names.length - 1];
+    return { name: pick[0], start: lineStart + pick.index };
+}
+/** Index of the `)` matching the `(` at `open`, skipping strings and comments; -1 when unbalanced. */
+export function closingParen(text, mask, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+        if (mask && mask[i] !== LEX_CODE)
+            continue;
+        if (text[i] === "(")
+            depth++;
+        else if (text[i] === ")" && --depth === 0)
+            return i;
+    }
+    return -1;
+}

package/dist/cli.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import pc from "picocolors";
+import { addNames, baselinePath, discoverNames, flagDir, mergeNames, runChecks, validateAgentNames, writeBaseline, } from "./core/baseline.js";
+import { loadConfig } from "./core/config.js";
+import { runDoctor } from "./core/doctor.js";
+import { gitState } from "./core/git.js";
+import { hookRoot, parseHookInput, stopDecision } from "./core/hook.js";
+import { initProject, installRoot, updateProject } from "./core/install.js";
+import { buildInventory } from "./core/inventory.js";
+import { verifyMarkdown } from "./core/markdown.js";
+import { packageVersion } from "./core/package.js";
+import { resolveProjects } from "./core/registry.js";
+import { printBaseline, printDoctor, printInventory, printSteps, printVerifyReport } from "./core/report.js";
+import { CHECK_IDS } from "./core/types.js";
+import { relativePath } from "./core/util.js";
+import { parseSkip, verifyFlag } from "./core/verify/index.js";
+const program = new Command();
+program
+    .name("flagrm")
+    .description("Guardrails for removing feature flags with an AI coding agent: set up the skills and hook (init, update, " +
+    "doctor), find flags (list), record the state before a removal (baseline) and gate the result (verify).")
+    .version(packageVersion());
+/** Accumulate repeatable options (`--exclude a --exclude b`) into an array. */
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+function addGlobOptions(cmd) {
+    return cmd
+        .option("--exclude <glob>", "additional glob to exclude from scanning (repeatable)", collect, [])
+        .option("--include <glob>", "additional glob to include when scanning (repeatable)", collect, []);
+}
+function addCommonOptions(cmd) {
+    return addGlobOptions(cmd
+        .option("--frontend <path>", "path to an Angular project (adds or replaces the project named 'frontend')")
+        .option("--backend <path>", "path to a .NET project (adds or replaces the project named 'backend')")
+        .option("--config <path>", "path to a config file (default: the nearest flagrm.config.yaml up to the git repository root)")
+        .option("--json", "machine-readable JSON output"));
+}
+/** Print a usage or config error and end the command with exit code 2. */
+class CliError extends Error {
+}
+function fail(err) {
+    throw new CliError(err instanceof Error ? err.message : String(err));
+}
+/** Load the config and pair every project with its adapter, exiting with code 2 on any config error. */
+function loadWorkspace(opts) {
+    try {
+        const config = loadConfig(opts);
+        return { root: config.root, projects: resolveProjects(config) };
+    }
+    catch (err) {
+        fail(err);
+    }
+}
+// --- baseline ------------------------------------------------------------------
+addCommonOptions(program
+    .command("baseline <flag>")
+    .description("record the state before removing a flag: the git commit, each project's build and test results, and the " +
+    "flag's names for the leftovers check; writes .flagrm/<flag>/baseline.json for verify. With --name on an " +
+    "existing baseline, only adds names"))
+    .option("--no-checks", "record only the git state, without running build and test commands")
+    .option("--name <name>", "add a name the flag is read through (repeatable)", collect, [])
+    .option("--kind <kind>", "how --name entries are matched: alias (qualified constant) or wrapper (identifier, calls included)", "alias")
+    .option("--force", "overwrite an existing baseline")
+    .action(async (flag, opts) => {
+    const { root, projects } = loadWorkspace(opts);
+    if (opts.kind !== "alias" && opts.kind !== "wrapper") {
+        fail(new Error(`--kind must be alias or wrapper, not "${opts.kind}".`));
+    }
+    const added = opts.name.map((name) => ({
+        name,
+        kind: opts.kind,
+        source: "agent",
+    }));
+    let result;
+    try {
+        validateAgentNames(projects, added);
+        if (fs.existsSync(baselinePath(root, flag)) && !opts.force) {
+            if (added.length === 0) {
+                throw new Error(`Baseline for ${flag} already exists; pass --name to add names, or --force to start over.`);
+            }
+            result = addNames(root, flag, added);
+        }
+        else {
+            const git = gitState(root);
+            const checks = opts.checks ? await runChecks(projects, flagDir(root, flag)) : undefined;
+            result = writeBaseline(root, flag, projects, git, checks, mergeNames(await discoverNames(projects, flag), added));
+        }
+    }
+    catch (err) {
+        fail(err);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ ...result.baseline, baselineFile: result.file }, null, 2));
+    }
+    else {
+        printBaseline(result.baseline, result.file);
+    }
+});
+// --- verify ------------------------------------------------------------------
+addCommonOptions(program
+    .command("verify <flag>")
+    .description("gate a flag removal against its baseline (`flagrm baseline <flag>`): build, tests and new unused code; " +
+    "writes .flagrm/<flag>/verify.json; exit 0 pass, 1 fail, 2 usage error"))
+    .option("--skip <checks>", `comma-separated checks to skip (${CHECK_IDS.join(", ")})`)
+    .option("--strict", "treat warnings as failures")
+    .option("--md", "print a markdown overview (for the user or a PR) instead of text")
+    .action(async (flag, opts) => {
+    if (opts.md && opts.json)
+        fail(new Error("--md and --json can't be combined."));
+    const { root, projects } = loadWorkspace(opts);
+    let result;
+    try {
+        result = await verifyFlag(root, projects, flag, { skip: parseSkip(opts.skip), strict: opts.strict });
+    }
+    catch (err) {
+        fail(err);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ ...result.report, verifyFile: result.file }, null, 2));
+    }
+    else if (opts.md) {
+        process.stdout.write(verifyMarkdown(result.report, root));
+    }
+    else {
+        printVerifyReport(result.report, result.file);
+    }
+    // exitCode, not exit(): exit() can cut off stdout still being flushed to a pipe.
+    process.exitCode = result.report.status === "pass" ? 0 : 1;
+});
+// --- list ----------------------------------------------------------------
+addCommonOptions(program
+    .command("list")
+    .description("inventory the workspace's feature flags: definitions (constants, enums, flags objects), " +
+    "type and configured state per environment file (appsettings, environment.ts), " +
+    "direct reference counts and the projects involved")).action(async (opts) => {
+    const report = await buildInventory(loadWorkspace(opts).projects);
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printInventory(report);
+    }
+});
+// --- hook --------------------------------------------------------------------
+const hook = program.command("hook").description("entry points for agent hooks (installed by flagrm init)");
+hook
+    .command("stop")
+    .description("Claude Code Stop hook: block stopping while a flag removal is not verified; always exits 0")
+    .action(() => {
+    // Anything unexpected allows the stop: a broken hook must never trap the user.
+    try {
+        const input = process.stdin.isTTY ? {} : parseHookInput(fs.readFileSync(0, "utf8"));
+        const decision = stopDecision(hookRoot(input.cwd ?? process.cwd()), input);
+        if (decision.block)
+            console.log(JSON.stringify({ decision: "block", reason: decision.reason }));
+    }
+    catch {
+        // Allow the stop.
+    }
+});
+// --- init --------------------------------------------------------------------
+program
+    .command("init")
+    .description("set up flagrm in this repository: flagrm.config.yaml, the flagrm-remove and flagrm-verify skills for Claude Code, " +
+    "GitHub Copilot and Codex, the Claude Code Stop hook and the .flagrm/ gitignore entry; never overwrites")
+    .action(async () => {
+    const root = installRoot(process.cwd());
+    printInstallRoot(root);
+    printSteps(initProject(root));
+    console.log(pc.bold("\nflagrm doctor"));
+    printDoctor(await runDoctor(root));
+    console.log(pc.dim("\nNext: fill in flagrm.config.yaml, then ask your agent: /flagrm-remove <FlagName>"));
+});
+// --- update ------------------------------------------------------------------
+program
+    .command("update")
+    .description("refresh the installed skills, the AGENTS.md block and the Stop hook from this flagrm version " +
+    "(only where flagrm init installed them)")
+    .action(() => {
+    const root = installRoot(process.cwd());
+    printInstallRoot(root);
+    printSteps(updateProject(root));
+});
+/** Say where init/update install when it isn't the working directory. */
+function printInstallRoot(root) {
+    if (path.resolve(root) !== path.resolve(process.cwd())) {
+        console.log(pc.dim(`Installing in ${relativePath(process.cwd(), root)}`));
+    }
+}
+// --- doctor ------------------------------------------------------------------
+program
+    .command("doctor")
+    .description("check that this repository is ready for flag removal: config, build/test commands, git, .gitignore, " +
+    "installed skills and Stop hook, abandoned baselines; exit 0 ok, 1 problems")
+    .option("--config <path>", "path to a config file (default: the nearest flagrm.config.yaml up to the git repository root)")
+    .option("--run", "also run each build and test command")
+    .option("--json", "machine-readable JSON output")
+    .action(async (opts) => {
+    const report = await runDoctor(process.cwd(), { config: opts.config, run: opts.run });
+    if (opts.json)
+        console.log(JSON.stringify(report, null, 2));
+    else
+        printDoctor(report);
+    process.exitCode = report.status === "ok" ? 0 : 1;
+});
+// exitCode, not exit(): exit() can cut off output still being flushed to a pipe.
+program.parseAsync().catch((err) => {
+    if (!(err instanceof CliError))
+        throw err;
+    console.error(pc.red(err.message));
+    process.exitCode = 2;
+});

package/dist/core/adapter.js

@@ -0,0 +1,18 @@
+/**
+ * The diagnostics in `current` that `before` did not have. Line numbers move
+ * with the edits, so a diagnostic is matched by file, code and message (which
+ * names the member), counting repeats: a second identical message in a file
+ * (another unused `ex`) is new, not the baseline's.
+ */
+export function newDiagnostics(current, before) {
+    const key = (d) => `${d.file}\0${d.code}\0${d.message}`;
+    const remaining = new Map();
+    for (const d of before)
+        remaining.set(key(d), (remaining.get(key(d)) ?? 0) + 1);
+    return current.filter((d) => {
+        const n = remaining.get(key(d)) ?? 0;
+        if (n > 0)
+            remaining.set(key(d), n - 1);
+        return n === 0;
+    });
+}

package/dist/core/baseline.js

@@ -0,0 +1,255 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { buildInventory } from "./inventory.js";
+import { JSON_SCHEMA_VERSION } from "./types.js";
+import { collectTestResults } from "./verify/test-results.js";
+/**
+ * `.flagrm/<flag>/` under the config root. A name that isn't safe as a directory
+ * (`team/new`, `..`) is sanitized and suffixed with a hash of the original, so
+ * it stays inside `.flagrm/` and can't collide with another flag's directory.
+ */
+export function flagDir(root, flag) {
+    const safe = flag.replace(/[^\w.-]/g, "_");
+    if (flag && safe === flag && !flag.startsWith("."))
+        return path.join(root, ".flagrm", flag);
+    const hash = createHash("sha256").update(flag).digest("hex").slice(0, 8);
+    return path.join(root, ".flagrm", `${safe.replace(/^\.+/, "")}-${hash}`);
+}
+export function baselinePath(root, flag) {
+    return path.join(flagDir(root, flag), "baseline.json");
+}
+/** `.flagrm/<flag>/verify.json`: the last verify result. */
+export function verifyPath(root, flag) {
+    return path.join(flagDir(root, flag), "verify.json");
+}
+/** A problem with how flagrm was run (missing baseline, stale schema) rather than with the code under check. */
+export class UsageError extends Error {
+}
+/** Read `.flagrm/<flag>/baseline.json`, which `flagrm baseline <flag>` writes. */
+export function readBaseline(root, flag) {
+    const file = baselinePath(root, flag);
+    if (!fs.existsSync(file)) {
+        throw new UsageError(`No baseline for ${flag} at ${file}. Run \`flagrm baseline ${flag}\` before changing the code.`);
+    }
+    const baseline = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (baseline.schemaVersion !== JSON_SCHEMA_VERSION) {
+        throw new UsageError(`${file} was written by schema version ${baseline.schemaVersion}; this flagrm expects ${JSON_SCHEMA_VERSION}. ` +
+            `Re-run \`flagrm baseline ${flag} --force\` on the code as it was before the removal.`);
+    }
+    return { baseline, file };
+}
+/**
+ * Run one shell command inside a project, streaming its output to `logFile`
+ * (no buffer limit, stdout and stderr interleaved as printed). A command that
+ * can't start, is killed or outlives the project's `timeout` fails with the
+ * reason at the end of the log. A test run also reads the project's
+ * `testResults` files written during it.
+ */
+export async function runCheck(ctx, check, command, logFile) {
+    const started = Date.now();
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    fs.writeFileSync(logFile, `$ ${command}\n`, "utf8");
+    const fd = fs.openSync(logFile, "a");
+    let exit;
+    try {
+        exit = await runCommand(command, ctx.root, fd, ctx.project.timeout);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const reason = failureReason(exit, ctx.project.timeout);
+    if (reason)
+        fs.appendFileSync(logFile, `\nflagrm: error: ${reason}\n`, "utf8");
+    const run = {
+        project: ctx.name,
+        check,
+        command,
+        exitCode: exit.status ?? 1,
+        durationMs: Date.now() - started,
+        log: logFile,
+    };
+    const results = check === "test" && ctx.project.testResults ? collectTestResults(ctx.project.testResults, started) : undefined;
+    if (results)
+        run.results = results;
+    return run;
+}
+/**
+ * Run `command` in a shell with its output on `fd`. On timeout the whole
+ * process tree is killed: on Windows the shell is `cmd.exe`, and killing only
+ * it would leave the real command (`dotnet test`, `node`) running.
+ */
+function runCommand(command, cwd, fd, timeout) {
+    return new Promise((resolve) => {
+        const child = spawn(command, { cwd, shell: true, stdio: ["ignore", fd, fd], windowsHide: true });
+        let timedOut = false;
+        const timer = timeout
+            ? setTimeout(() => {
+                timedOut = true;
+                killTree(child.pid, () => child.kill("SIGKILL"));
+            }, timeout * 1000)
+            : undefined;
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            resolve({ status: null, signal: null, error });
+        });
+        child.on("close", (status, signal) => {
+            clearTimeout(timer);
+            resolve({ status, signal, timedOut });
+        });
+    });
+}
+function killTree(pid, fallback) {
+    if (pid !== undefined && process.platform === "win32") {
+        const r = spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        if (r.status === 0)
+            return;
+    }
+    fallback();
+}
+/** Why a command ended without an exit code, or undefined when it exited normally. */
+function failureReason(exit, timeout) {
+    if (exit.timedOut)
+        return `timed out after ${timeout}s (timeout in flagrm.config.yaml)`;
+    if (exit.error)
+        return `could not run the command: ${exit.error.message}`;
+    if (exit.status === null)
+        return `killed by ${exit.signal ?? "a signal"}`;
+    return undefined;
+}
+/** A project's build/test commands: the configured ones, or the adapter's defaults when it configures neither. */
+export function projectCommands(adapter, ctx) {
+    const configured = ctx.project.build !== undefined || ctx.project.test !== undefined;
+    return configured ? { build: ctx.project.build, test: ctx.project.test } : (adapter.defaultCommands?.(ctx) ?? {});
+}
+/**
+ * Why an Angular project's build can't catch template errors, if it can't:
+ * `tsc` never reads templates, so a member removed or renamed in a component
+ * but still used in its `.html` passes the build. `ngc` and `ng build` check them.
+ */
+export function templateCheckGap(adapter, build) {
+    if (adapter.id !== "angular" || !build || !/\btsc\b/.test(build))
+        return undefined;
+    if (/\bngc\b|\bng\s+build\b|\bnx\b/.test(build))
+        return undefined;
+    return "`tsc` doesn't type-check Angular templates: add `npx ngc -p <app>/tsconfig.json --noEmit` to `build` so a member removed from a component but still used in its template fails the build";
+}
+/**
+ * Why a .NET build can't feed the dead-code check, if it can't: an incremental
+ * `dotnet build` skips compiling up-to-date projects and prints none of their
+ * warnings, so a baseline taken on a built tree records no pre-existing unused
+ * code and verify reports all of it as new.
+ */
+export function incrementalBuildGap(adapter, build) {
+    if (adapter.id !== "dotnet" || !build || !/\bdotnet\s+build\b/.test(build))
+        return undefined;
+    if (/--no-incremental\b|[-/]t(arget)?:\s*Rebuild\b/i.test(build))
+        return undefined;
+    return "`dotnet build` without `--no-incremental` skips up-to-date projects and prints none of their warnings, so the dead-code check may report existing unused code as new: add `--no-incremental` to `build`";
+}
+/**
+ * Build then test every project. A project that configures `build` and/or
+ * `test` runs exactly those; one that configures neither gets the adapter's
+ * defaults (`dotnet build --no-incremental`, `npx ng test`, ...).
+ */
+export async function runChecks(projects, logDir, only = ["build", "test"]) {
+    const runs = [];
+    for (const { adapter, ctx } of projects) {
+        const commands = projectCommands(adapter, ctx);
+        for (const check of only) {
+            const command = commands[check];
+            if (command)
+                runs.push(await runCheck(ctx, check, command, path.join(logDir, `${ctx.name}.${check}.log`)));
+        }
+    }
+    return runs;
+}
+/**
+ * Write the flag's baseline: the git state and optional check runs. Take
+ * `git` before running checks, whose logs land under `.flagrm/` and would
+ * otherwise make the tree look dirty.
+ */
+export function writeBaseline(root, flag, projects, git, checks, names = []) {
+    const baseline = {
+        schemaVersion: JSON_SCHEMA_VERSION,
+        flag,
+        createdAt: new Date().toISOString(),
+        projects: projects.map(({ ctx }) => ({ name: ctx.name, adapter: ctx.project.adapter })),
+        git,
+        names,
+    };
+    if (checks)
+        baseline.checks = checks;
+    return saveBaseline(root, baseline);
+}
+function saveBaseline(root, baseline) {
+    const file = baselinePath(root, baseline.flag);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(baseline, null, 2)}\n`, "utf8");
+    return { baseline, file };
+}
+/** The flag's names from discovery: the literal, then each definition's qualified name. */
+export async function discoverNames(projects, flag) {
+    const entry = (await buildInventory(projects)).flags.find((f) => f.flag === flag);
+    return mergeNames([{ name: flag, kind: "literal", source: "discovery" }], (entry?.definitions ?? []).map((d) => ({ name: d.name, kind: "alias", source: "discovery" })));
+}
+/** `existing` followed by the names in `added` it doesn't already have. */
+export function mergeNames(existing, added) {
+    const seen = new Set(existing.map((n) => n.name));
+    const merged = [...existing];
+    for (const n of added) {
+        if (seen.has(n.name))
+            continue;
+        seen.add(n.name);
+        merged.push(n);
+    }
+    return merged;
+}
+/** Append names to an existing baseline; its git state and checks stay as they are. */
+export function addNames(root, flag, added) {
+    const { baseline } = readBaseline(root, flag);
+    return saveBaseline(root, { ...baseline, names: mergeNames(baseline.names, added) });
+}
+/**
+ * Refuse names that would match far more than this flag: a configured flag
+ * evaluation method (`isEnabled`) is called for every flag in the project.
+ */
+export function validateAgentNames(projects, names) {
+    const methods = new Set(projects.flatMap(({ ctx }) => ctx.project.methods));
+    for (const { name } of names) {
+        if (methods.has(name)) {
+            throw new UsageError(`"${name}" is a flag evaluation method (methods in flagrm.config.yaml), so it matches every flag. ` +
+                "Record the wrapper or constant specific to this flag instead.");
+        }
+    }
+}
+/**
+ * Up to `max` distinct lines of a log that look like errors, so the reader sees
+ * why a command failed without opening the log. Compiler warnings and summary
+ * lines such as `0 Error(s)` are skipped: in a large build they bury the one
+ * real error. When no line looks like an error, the last `max` lines instead.
+ */
+export function errorExcerpt(log, max = 10) {
+    if (!log)
+        return [];
+    let text;
+    try {
+        text = fs.readFileSync(log, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const all = text
+        .split(/\r?\n/)
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: strips ANSI colors (ngc colors even when piped)
+        .map((line) => line.replace(/\u001b\[[0-9;]*m/g, "").trim())
+        .filter((line) => line && !line.startsWith("$ "));
+    const lines = all
+        .filter((line) => /\berror\b|\bfailed\b|✗|×/i.test(line))
+        .filter((line) => !/:\s*warning\b/i.test(line) && !/^\d+ Error\(s\)$/i.test(line));
+    // No line says error (e.g. "A compatible .NET SDK was not found"): the end of the log usually does.
+    if (!lines.length)
+        return all.slice(-max);
+    return [...new Set(lines)].slice(0, max);
+}