flagrm 0.1.0 → 0.2.0

package/dist/cli.js

@@ -3,8 +3,9 @@ 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 { realProbes } from "./adapters/dotnet/setup.js";
+import { addNames, assertNoEditsSinceBaseline, baselinePath, baselineSummary, discoverFlag, flagDir, mergeNames, runChecks, validateAgentNames, writeBaseline, } from "./core/baseline.js";
+import { loadConfig, parseTools, TOOL_IDS } from "./core/config.js";
 import { runDoctor } from "./core/doctor.js";
 import { gitState } from "./core/git.js";
 import { hookRoot, parseHookInput, stopDecision } from "./core/hook.js";
@@ -13,9 +14,11 @@ 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 { printBaseline, printDoctor, printInventory, printScope, printSteps, printVerifyReport, } from "./core/report.js";
+import { setupReport, writeScope } from "./core/scope.js";
+import { askTools, detectTools, savedTools, TOOL_LABELS } from "./core/tools.js";
 import { CHECK_IDS } from "./core/types.js";
-import { relativePath } from "./core/util.js";
+import { onPath, relativePath } from "./core/util.js";
 import { parseSkip, verifyFlag } from "./core/verify/index.js";
 const program = new Command();
 program
@@ -63,22 +66,38 @@ addCommonOptions(program
     "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")
+    .option("--kind <kind>", "how --name entries are matched: alias (qualified constant) or wrapper (identifier, calls included); default alias, wrapper with --file")
+    .option("--file <path>", "check the --name entries only in this file (a local, parameter or field; implies --kind wrapper)")
+    .option("--force", "start over: replace the baseline, only while the code is unedited since it")
     .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}".`));
+    // Only wrappers are matched per file: a name scoped with --file is a local, parameter or field.
+    const kind = opts.kind ?? (opts.file ? "wrapper" : "alias");
+    if (kind !== "alias" && kind !== "wrapper") {
+        fail(new Error(`--kind must be alias or wrapper, not "${kind}".`));
     }
+    if (opts.file && opts.name.length === 0)
+        fail(new Error("--file scopes --name entries; pass --name too."));
+    if (opts.file && kind !== "wrapper")
+        fail(new Error("--file scopes wrapper names; drop --kind alias."));
+    const scope = opts.file && relativePath(root, path.resolve(opts.file));
+    if (scope?.startsWith(".."))
+        fail(new Error(`--file ${opts.file} is outside ${root}.`));
     const added = opts.name.map((name) => ({
         name,
-        kind: opts.kind,
+        kind: kind,
         source: "agent",
+        ...(scope ? { file: scope } : {}),
     }));
     let result;
     try {
         validateAgentNames(projects, added);
-        if (fs.existsSync(baselinePath(root, flag)) && !opts.force) {
+        const exists = fs.existsSync(baselinePath(root, flag));
+        if (exists && opts.force) {
+            const testResults = projects.flatMap(({ ctx }) => (ctx.project.testResults ? [ctx.project.testResults] : []));
+            assertNoEditsSinceBaseline(root, flag, testResults);
+        }
+        if (exists && !opts.force) {
             if (added.length === 0) {
                 throw new Error(`Baseline for ${flag} already exists; pass --name to add names, or --force to start over.`);
             }
@@ -87,14 +106,15 @@ addCommonOptions(program
         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));
+            const { names, ...flow } = await discoverFlag(projects, flag);
+            result = writeBaseline(root, flag, projects, git, checks, mergeNames(names, added), flow);
         }
     }
     catch (err) {
         fail(err);
     }
     if (opts.json) {
-        console.log(JSON.stringify({ ...result.baseline, baselineFile: result.file }, null, 2));
+        console.log(JSON.stringify(baselineSummary(result.baseline, result.file), null, 2));
     }
     else {
         printBaseline(result.baseline, result.file);
@@ -165,25 +185,63 @@ hook
 // --- 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 () => {
+    .description("set up flagrm in this repository: flagrm.config.yaml, the .flagrm/ gitignore entry, and for each AI coding " +
+    "tool its files (Claude Code: skills and Stop hook; GitHub Copilot: skills and prompt files; Codex: skills " +
+    "and the AGENTS.md block); asks which tools on a terminal and saves the choice as `tools:`; never overwrites")
+    .option("--tool <tools>", `comma-separated tools to set up, without asking: ${TOOL_IDS.join(", ")}`)
+    .action(async (opts) => {
     const root = installRoot(process.cwd());
     printInstallRoot(root);
-    printSteps(initProject(root));
+    let tools;
+    try {
+        tools = await chooseTools(root, opts.tool);
+    }
+    catch (err) {
+        fail(err);
+    }
+    printSteps(initProject(root, tools));
     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>"));
 });
+/**
+ * The tools `init` sets up: `--tool`, else the config's saved `tools:`, else
+ * the user's answer with the tools the repository already uses pre-selected.
+ * Without a terminal to ask on: those detected tools, or all when there are none.
+ */
+async function chooseTools(root, flag) {
+    if (flag !== undefined) {
+        const tools = parseTools(flag, "--tool") ?? [];
+        if (tools.length === 0)
+            throw new Error(`--tool needs at least one of ${TOOL_IDS.join(", ")}.`);
+        return tools;
+    }
+    const saved = savedTools(root);
+    if (saved?.length) {
+        console.log(pc.dim(`Tools: ${saved.map((t) => TOOL_LABELS[t]).join(", ")} (from tools: in the config; --tool changes it)`));
+        return saved;
+    }
+    const detected = detectTools(root);
+    if (process.stdin.isTTY && process.stdout.isTTY)
+        return askTools(detected);
+    return detected.length ? detected : [...TOOL_IDS];
+}
 // --- 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)")
+    .description("refresh the installed skills, prompt files, AGENTS.md block and Stop hook from this flagrm version " +
+    "(only where flagrm init installed them, and only for the config's tools: when it lists them)")
     .action(() => {
     const root = installRoot(process.cwd());
     printInstallRoot(root);
-    printSteps(updateProject(root));
+    let tools;
+    try {
+        tools = savedTools(root);
+    }
+    catch (err) {
+        fail(err);
+    }
+    printSteps(updateProject(root, tools));
 });
 /** Say where init/update install when it isn't the working directory. */
 function printInstallRoot(root) {
@@ -207,6 +265,26 @@ program
         printDoctor(report);
     process.exitCode = report.status === "ok" ? 0 : 1;
 });
+// --- scope -------------------------------------------------------------------
+addCommonOptions(program
+    .command("scope")
+    .description("check that this machine can build and test each .NET project (the SDK global.json asks for, `cargo`, " +
+    "Docker for Testcontainers) and show which projects a solution filter (flagrm.slnf) would leave out; " +
+    "exit 0 nothing missing, 1 something missing"))
+    .option("--write", "create flagrm.slnf, keep it out of git and point the config's build and test at it")
+    .action((opts) => {
+    const { root, projects } = loadWorkspace(opts);
+    const setups = setupReport(projects, root, realProbes((exe) => onPath(exe, root)));
+    const steps = opts.write ? writeScope(setups, projects, root, projects[0]?.ctx.config.file) : [];
+    if (opts.json)
+        console.log(JSON.stringify({ projects: setups, ...(opts.write ? { steps } : {}) }, null, 2));
+    else {
+        printScope(setups, root, Boolean(opts.write));
+        printSteps(steps);
+    }
+    const missing = setups.some((s) => s.sdk || s.setup?.problems.length);
+    process.exitCode = missing ? 1 : 0;
+});
 // exitCode, not exit(): exit() can cut off output still being flushed to a pipe.
 program.parseAsync().catch((err) => {
     if (!(err instanceof CliError))

package/dist/core/baseline.js

@@ -2,9 +2,15 @@ import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import fg from "fast-glob";
+import { CONFIG_FILENAMES } from "./config.js";
+import { configSnapshot, projectCommands } from "./config-snapshot.js";
+import { environmentProblem } from "./environment.js";
+import { changedFilesSince } from "./git.js";
 import { buildInventory } from "./inventory.js";
-import { JSON_SCHEMA_VERSION } from "./types.js";
-import { collectTestResults } from "./verify/test-results.js";
+import { JSON_SCHEMA_VERSION, READABLE_BASELINE_VERSIONS, } from "./types.js";
+import { readJson, relativePath } from "./util.js";
+import { collectTestResults, shortTestNames } 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
@@ -24,6 +30,40 @@ export function baselinePath(root, flag) {
 export function verifyPath(root, flag) {
     return path.join(flagDir(root, flag), "verify.json");
 }
+/** At most this many failed test names in `baseline --json`. */
+const MAX_FAILED_NAMES = 20;
+/**
+ * What `baseline --json` prints: the baseline without the per-test name lists
+ * (every test of a large suite, with its data-row arguments: megabytes) and
+ * the config snapshot. Failed tests are listed by short name, at most 20;
+ * `baseline.json` keeps everything.
+ */
+export function baselineSummary(baseline, file) {
+    const { config: _config, checks, ...rest } = baseline;
+    return {
+        ...rest,
+        ...(checks
+            ? {
+                checks: checks.map(({ results, ...run }) => {
+                    if (!results)
+                        return run;
+                    const { names: _names, failedNames, files, ...counts } = results;
+                    const failed = shortTestNames(failedNames);
+                    return {
+                        ...run,
+                        results: {
+                            ...counts,
+                            files: files.length,
+                            failedTests: failed.slice(0, MAX_FAILED_NAMES),
+                            ...(failed.length > MAX_FAILED_NAMES ? { moreFailedTests: failed.length - MAX_FAILED_NAMES } : {}),
+                        },
+                    };
+                }),
+            }
+            : {}),
+        baselineFile: file,
+    };
+}
 /** A problem with how flagrm was run (missing baseline, stale schema) rather than with the code under check. */
 export class UsageError extends Error {
 }
@@ -34,7 +74,7 @@ export function readBaseline(root, flag) {
         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) {
+    if (!READABLE_BASELINE_VERSIONS.includes(baseline.schemaVersion)) {
         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.`);
     }
@@ -47,7 +87,7 @@ export function readBaseline(root, flag) {
  * 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) {
+export async function runCheck(ctx, check, command, logFile, claimed) {
     const started = Date.now();
     fs.mkdirSync(path.dirname(logFile), { recursive: true });
     fs.writeFileSync(logFile, `$ ${command}\n`, "utf8");
@@ -70,7 +110,14 @@ export async function runCheck(ctx, check, command, logFile) {
         durationMs: Date.now() - started,
         log: logFile,
     };
-    const results = check === "test" && ctx.project.testResults ? collectTestResults(ctx.project.testResults, started) : undefined;
+    if (run.exitCode !== 0) {
+        const problem = environmentProblem(fs.readFileSync(logFile, "utf8"), ctx.root);
+        if (problem)
+            run.failure = { kind: "environment", message: problem };
+    }
+    const results = check === "test" && ctx.project.testResults
+        ? collectTestResults(ctx.project.testResults, started, claimed)
+        : undefined;
     if (results)
         run.results = results;
     return run;
@@ -118,11 +165,6 @@ function failureReason(exit, timeout) {
         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
@@ -155,12 +197,15 @@ export function incrementalBuildGap(adapter, build) {
  */
 export async function runChecks(projects, logDir, only = ["build", "test"]) {
     const runs = [];
+    // Projects whose `testResults` patterns overlap must not count each other's result files.
+    const claimed = new Map();
     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`)));
+            if (!command)
+                continue;
+            runs.push(await runCheck(ctx, check, command, path.join(logDir, `${ctx.name}.${check}.log`), claimed));
         }
     }
     return runs;
@@ -170,7 +215,7 @@ export async function runChecks(projects, logDir, only = ["build", "test"]) {
  * `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 = []) {
+export function writeBaseline(root, flag, projects, git, checks, names = [], flow) {
     const baseline = {
         schemaVersion: JSON_SCHEMA_VERSION,
         flag,
@@ -178,9 +223,14 @@ export function writeBaseline(root, flag, projects, git, checks, names = []) {
         projects: projects.map(({ ctx }) => ({ name: ctx.name, adapter: ctx.project.adapter })),
         git,
         names,
+        config: configSnapshot(projects),
     };
     if (checks)
         baseline.checks = checks;
+    if (flow?.suggestedNames.length)
+        baseline.suggestedNames = flow.suggestedNames;
+    if (flow?.parameterizedTests.length)
+        baseline.parameterizedTests = flow.parameterizedTests;
     return saveBaseline(root, baseline);
 }
 function saveBaseline(root, baseline) {
@@ -189,23 +239,93 @@ function saveBaseline(root, baseline) {
     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) {
+/**
+ * The flag's names from discovery: the literal, then each definition's
+ * qualified name, then the names its value travels through that contain one
+ * of the flag's words, as wrappers.
+ */
+export async function discoverFlag(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" })));
+    const flow = entry?.flow ?? [];
+    const names = mergeNames([{ name: flag, kind: "literal", source: "discovery" }], [
+        ...(entry?.definitions ?? []).map((d) => ({ name: d.name, kind: "alias", source: "discovery" })),
+        ...flow.filter((n) => n.record).map((n) => flowName(projects, n)),
+    ]);
+    const key = (n) => `${n.name}\0${n.file ?? ""}`;
+    const recorded = new Set(names.map(key));
+    const suggestedNames = flow
+        .filter((n) => !n.record && !recorded.has(key(flowName(projects, n))))
+        .map(({ record: _record, ...name }) => name)
+        .filter((n, i, all) => all.findIndex((m) => m.name === n.name && m.file === n.file) === i);
+    return { names, suggestedNames, parameterizedTests: entry?.parameterizedTests ?? [] };
+}
+/** A flow name as a wrapper; a local, parameter or field only in its own file. */
+function flowName(projects, n) {
+    const name = { name: n.name, kind: "wrapper", source: "discovery" };
+    const root = projects[0]?.ctx.config.root;
+    if (root && (n.kind === "local" || n.kind === "parameter" || n.kind === "field"))
+        name.file = relativePath(root, n.file);
+    return name;
 }
-/** `existing` followed by the names in `added` it doesn't already have. */
+/** The names {@link discoverFlag} records. */
+export async function discoverNames(projects, flag) {
+    return (await discoverFlag(projects, flag)).names;
+}
+/** `existing` followed by the names in `added` it doesn't already cover. */
 export function mergeNames(existing, added) {
-    const seen = new Set(existing.map((n) => n.name));
+    // A name recorded for every file already covers the same name in one file.
+    const key = (n) => `${n.name}\0${n.file ?? ""}`;
+    const seen = new Set(existing.map(key));
+    const everywhere = new Set(existing.filter((n) => !n.file).map((n) => n.name));
     const merged = [...existing];
     for (const n of added) {
-        if (seen.has(n.name))
+        if (seen.has(key(n)) || everywhere.has(n.name))
             continue;
-        seen.add(n.name);
+        seen.add(key(n));
+        if (!n.file)
+            everywhere.add(n.name);
         merged.push(n);
     }
     return merged;
 }
+/**
+ * Files changed since `sha` that count as edits to the code: everything but
+ * `.flagrm/`, the flagrm config, which may change to fix the setup, and the
+ * files matching `testResults` patterns (absolute), which the baseline's own
+ * test run writes. Undefined when git can't tell (not a repository, or `sha`
+ * isn't in it).
+ */
+export function editsSince(root, sha, testResults = []) {
+    const results = new Set(testResults.flatMap((pattern) => fg
+        .sync(path.sep === "\\" ? pattern.replace(/\\/g, "/") : pattern, { absolute: true, dot: true })
+        .map((file) => relativePath(root, file))));
+    return changedFilesSince(root, sha)?.filter((rel) => !CONFIG_FILENAMES.includes(rel) && !results.has(rel));
+}
+/**
+ * `baseline --force` starts over only before the removal began: the working
+ * tree must still match the baseline commit. Otherwise the new baseline would
+ * record half-removed code, and verify would no longer see those edits.
+ * Without git there is nothing to compare, so it is allowed. Files matching
+ * `testResults` (absolute patterns) are not edits.
+ */
+export function assertNoEditsSinceBaseline(root, flag, testResults = []) {
+    const sha = readJson(baselinePath(root, flag))?.git?.sha;
+    if (!sha)
+        return;
+    const edits = editsSince(root, sha, testResults);
+    if (edits === undefined) {
+        throw new UsageError(`The baseline commit ${sha.slice(0, 7)} of ${flag} is not in this repository, so flagrm can't tell whether the ` +
+            `code was edited since. If it wasn't, delete ${relativePath(root, flagDir(root, flag))}/ and take a new baseline.`);
+    }
+    if (edits.length === 0)
+        return;
+    const shown = edits.slice(0, 5).join(", ") + (edits.length > 5 ? `, and ${edits.length - 5} more` : "");
+    const uncommitted = new Set(changedFilesSince(root, "HEAD") ?? []);
+    const fix = edits.every((rel) => uncommitted.has(rel))
+        ? `Set the edits aside with \`git stash -u\`, run \`flagrm baseline ${flag} --force\` again, then \`git stash pop\`.`
+        : `Some are committed since the baseline commit ${sha.slice(0, 7)}: check out code without the removal first.`;
+    throw new UsageError(`The code changed since the baseline of ${flag} (${shown}), so --force would record a half-done removal. ${fix}`);
+}
 /** 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);

package/dist/core/config-snapshot.js

@@ -0,0 +1,183 @@
+/**
+ * The configuration a baseline was taken with, so `verify` can tell when it
+ * changed since: a narrower test command or filter runs fewer tests, and the
+ * comparison against the baseline no longer means what it did.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { relativePath } from "./util.js";
+/** 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) ?? {});
+}
+/** Solution and project files: a removal may edit them, so they don't count as a command's configuration. */
+const PROJECT_FILE = /\.(sln|slnx|\w*proj)$/i;
+/** The resolved build/test commands of every project, the files they name, and the config file's text. */
+export function configSnapshot(projects) {
+    const configFile = projects[0]?.ctx.config.file;
+    const root = projects[0]?.ctx.config.root ?? process.cwd();
+    const snapshot = { projects: [] };
+    if (configFile) {
+        try {
+            snapshot.file = { path: relativePath(root, configFile), text: fs.readFileSync(configFile, "utf8") };
+        }
+        catch {
+            // Unreadable: nothing to compare later.
+        }
+    }
+    for (const { adapter, ctx } of projects) {
+        const commands = projectCommands(adapter, ctx);
+        const command = (text) => ({ command: text, files: namedFiles(text, ctx.root, root) });
+        const entry = { name: ctx.name };
+        if (commands.build)
+            entry.build = command(commands.build);
+        if (commands.test)
+            entry.test = command(commands.test);
+        if (ctx.project.testResults)
+            entry.testResults = relativePath(root, ctx.project.testResults);
+        snapshot.projects.push(entry);
+    }
+    return snapshot;
+}
+/**
+ * Files a command names (`flagrm.slnf`, `--settings ci.runsettings`,
+ * `--filter-file=filters.txt`), with a hash of their content. Words are
+ * resolved against the directory the command runs in.
+ */
+function namedFiles(command, cwd, root) {
+    const words = command
+        .split(/\s+/)
+        .flatMap((word) => [word, word.slice(word.indexOf("=") + 1), word.slice(word.indexOf(":") + 1)])
+        .map((word) => word.replace(/^["']|["']$/g, ""))
+        .filter((word) => word && !word.startsWith("-") && !PROJECT_FILE.test(word));
+    const files = new Map();
+    for (const word of new Set(words)) {
+        const file = path.resolve(cwd, word);
+        try {
+            if (!fs.statSync(file).isFile())
+                continue;
+            files.set(relativePath(root, file), createHash("sha256").update(fs.readFileSync(file)).digest("hex"));
+        }
+        catch {
+            // Not a file.
+        }
+    }
+    return [...files].sort(([a], [b]) => a.localeCompare(b)).map(([p, sha256]) => ({ path: p, sha256 }));
+}
+/** What changed between the configuration at the baseline and now. None when the baseline predates snapshots. */
+export function configChanges(before, now) {
+    if (!before)
+        return [];
+    const changes = [];
+    const names = [...new Set([...before.projects, ...now.projects].map((p) => p.name))];
+    for (const name of names) {
+        const was = before.projects.find((p) => p.name === name);
+        const is = now.projects.find((p) => p.name === name);
+        for (const [kind, check] of [
+            ["build", "build"],
+            ["test", "tests"],
+        ]) {
+            const a = was?.[kind];
+            const b = is?.[kind];
+            if (a?.command !== b?.command) {
+                changes.push({
+                    check,
+                    project: name,
+                    message: `${kind} command changed since the baseline: ${quote(a?.command)} → ${quote(b?.command)}`,
+                });
+            }
+            const changed = changedFiles(a?.files ?? [], b?.files ?? []);
+            if (changed.length) {
+                changes.push({
+                    check,
+                    project: name,
+                    message: `${changed.join(", ")}, named by the ${kind} command, changed since the baseline`,
+                });
+            }
+        }
+        if (was?.testResults !== is?.testResults) {
+            changes.push({
+                check: "tests",
+                project: name,
+                message: `testResults changed since the baseline: ${quote(was?.testResults)} → ${quote(is?.testResults)}`,
+            });
+        }
+    }
+    if (before.file && now.file && withoutCommands(before.file.text) !== withoutCommands(now.file.text)) {
+        changes.push({
+            check: "leftovers",
+            message: `${now.file.path} changed since the baseline, which changes what is scanned`,
+            details: lineDiff(before.file.text, now.file.text),
+        });
+    }
+    return changes;
+}
+const quote = (text) => (text === undefined ? "(none)" : `\`${text}\``);
+function changedFiles(a, b) {
+    const hashes = new Map(a.map((f) => [f.path, f.sha256]));
+    const out = new Set();
+    for (const f of b)
+        if (hashes.get(f.path) !== f.sha256)
+            out.add(f.path);
+    for (const f of a)
+        if (!b.some((g) => g.path === f.path))
+            out.add(f.path);
+    return [...out].sort();
+}
+/** The config without what the command comparison already covers, normalized for comparison. */
+function withoutCommands(text) {
+    let parsed;
+    try {
+        parsed = YAML.parse(text);
+    }
+    catch {
+        return text;
+    }
+    const strip = (project) => {
+        if (!project || typeof project !== "object")
+            return project;
+        const { build: _b, test: _t, testResults: _r, timeout: _o, ...rest } = project;
+        return rest;
+    };
+    if (parsed && typeof parsed === "object") {
+        const config = { ...parsed };
+        if (Array.isArray(config.projects))
+            config.projects = config.projects.map(strip);
+        for (const legacy of ["frontend", "backend"]) {
+            if (config[legacy] && typeof config[legacy] === "object")
+                config[legacy] = strip(config[legacy]);
+        }
+        return JSON.stringify(config);
+    }
+    return JSON.stringify(parsed);
+}
+/** Lines removed (`- `) and added (`+ `) from `a` to `b`, by longest common subsequence; at most 20. */
+export function lineDiff(a, b, max = 20) {
+    const x = a.split(/\r?\n/);
+    const y = b.split(/\r?\n/);
+    const lcs = Array.from({ length: x.length + 1 }, () => new Array(y.length + 1).fill(0));
+    for (let i = x.length - 1; i >= 0; i--) {
+        for (let j = y.length - 1; j >= 0; j--) {
+            lcs[i][j] = x[i] === y[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < x.length || j < y.length) {
+        if (i < x.length && j < y.length && x[i] === y[j]) {
+            i++;
+            j++;
+        }
+        else if (i < x.length && (j === y.length || lcs[i + 1][j] >= lcs[i][j + 1])) {
+            out.push(`- ${x[i++]}`);
+        }
+        else {
+            out.push(`+ ${y[j++]}`);
+        }
+    }
+    return out.length > max ? [...out.slice(0, max), `… ${out.length - max} more changed lines`] : out;
+}

package/dist/core/config.js

@@ -2,6 +2,23 @@ import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
 export const ADAPTER_IDS = ["angular", "dotnet", "generic"];
+/** The AI coding tools `init` can set up: Claude Code, GitHub Copilot, Codex. */
+export const TOOL_IDS = ["claude-code", "copilot", "codex"];
+/** `tools:` as configured, checked; undefined when the key is absent. */
+export function parseTools(value, where = "tools") {
+    if (value === undefined || value === null)
+        return undefined;
+    const list = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : undefined;
+    if (!list)
+        throw new Error(`${where} must be a list of ${TOOL_IDS.join(", ")}.`);
+    const tools = list.map((t) => String(t).trim()).filter(Boolean);
+    for (const t of tools) {
+        if (!TOOL_IDS.includes(t)) {
+            throw new Error(`${where}: "${t}" is not one of ${TOOL_IDS.join(", ")}.`);
+        }
+    }
+    return TOOL_IDS.filter((t) => tools.includes(t));
+}
 export const DEFAULT_FRONTEND_METHODS = ["isEnabled", "isFeatureEnabled", "hasFeature", "getFlag", "isOn"];
 export const DEFAULT_BACKEND_METHODS = [
     "IsEnabledAsync",
@@ -12,10 +29,11 @@ export const DEFAULT_BACKEND_METHODS = [
     "GetValue<bool>",
 ];
 export const DEFAULT_BACKEND_ATTRIBUTES = ["FeatureGate", "Feature"];
-const CONFIG_FILENAMES = ["flagrm.config.yaml", "flagrm.config.yml", "flagrm.config.json"];
+export const CONFIG_FILENAMES = ["flagrm.config.yaml", "flagrm.config.yml", "flagrm.config.json"];
 /** Known top-level `flagrm.config.yaml` keys — anything else is likely a typo. */
 const KNOWN_CONFIG_KEYS = [
     "projects",
+    "tools",
     "frontend",
     "backend",
     "frontendMethods",
@@ -245,8 +263,11 @@ export function loadConfig(cli, cwd = process.cwd()) {
     if (projects.length === 0) {
         throw new Error("No projects configured. Add a `projects:` list to flagrm.config.yaml, or pass --frontend and/or --backend.");
     }
+    const tools = parseTools(file.tools);
     return {
         root: fileDir,
+        file: configPath && fs.existsSync(configPath) ? configPath : undefined,
+        ...(tools ? { tools } : {}),
         projects,
         exclude: [...(file.exclude ?? []), ...(cli.exclude ?? [])],
         include: [...(file.include ?? []), ...(cli.include ?? [])],