flagrm 0.3.0 → 0.4.1

package/dist/core/config.js

@@ -48,9 +48,11 @@ const KNOWN_PROJECT_KEYS = [
     "path",
     "build",
     "test",
+    "lint",
     "testResults",
     "timeout",
     "globs",
+    "covers",
     "methods",
     "attributes",
 ];
@@ -200,14 +202,16 @@ function parseProject(raw, index, file, fileDir, quiet = false) {
         path: resolveProjectDir(fileDir, p.path, `Project "${name}"`),
         build: optionalCommand(p.build, `${where}.build`),
         test: optionalCommand(p.test, `${where}.test`),
+        lint: optionalCommand(p.lint, `${where}.lint`),
         testResults: testResults && path.resolve(fileDir, testResults),
         timeout: optionalPositiveNumber(p.timeout, `${where}.timeout`),
         globs: optionalStringList(p.globs, `${where}.globs`),
+        covers: optionalStringList(p.covers, `${where}.covers`),
         methods: optionalStringList(p.methods, `${where}.methods`) ?? defaults.methods,
         attributes: optionalStringList(p.attributes, `${where}.attributes`) ?? defaults.attributes,
     };
     // Keep the resolved shape free of absent optional keys.
-    for (const key of ["build", "test", "testResults", "timeout", "globs"]) {
+    for (const key of ["build", "test", "lint", "testResults", "timeout", "globs", "covers"]) {
         if (project[key] === undefined)
             delete project[key];
     }

package/dist/core/detect.js

@@ -5,7 +5,8 @@
  * saves the user from editing a template, and they check the result.
  */
 import path from "node:path";
-import fg from "fast-glob";
+import { globSync } from "tinyglobby";
+import { detectTestRunner } from "./test-runner.js";
 const IGNORE = ["**/node_modules/**", "**/.git/**", "**/bin/**", "**/obj/**", "**/dist/**"];
 const depth = (file) => file.split("/").length;
 /** Markers whose directory isn't inside another marker's directory, one per directory. */
@@ -31,12 +32,11 @@ function commonDir(files) {
     return common.join("/") || ".";
 }
 export function detectProjects(cwd) {
-    const find = (pattern) => fg.sync(pattern, { cwd, deep: 4, ignore: IGNORE });
+    const find = (pattern) => globSync(pattern, { expandDirectories: false, cwd, deep: 3, ignore: IGNORE });
     const found = [];
     for (const marker of topmost(find("**/angular.json"))) {
         const dir = path.posix.dirname(marker);
-        const jest = fg.sync("jest.config.{js,ts,mjs,cjs}", { cwd: path.join(cwd, dir) }).length > 0;
-        found.push({ adapter: "angular", path: dir, marker, jest });
+        found.push({ adapter: "angular", path: dir, marker, testRunner: detectTestRunner(path.join(cwd, dir)) });
     }
     const solutions = topmost(find("**/*.{sln,slnx}"));
     if (solutions.length) {

package/dist/core/doctor.js

@@ -1,6 +1,6 @@
 /**
  * `flagrm doctor`: is this repository ready for an agent to remove a flag?
- * Config, build/test commands, git, .gitignore, the installed skills and
+ * Config, build/test/lint commands, git, .gitignore, the installed skills and
  * hook, and baselines left behind by abandoned removals.
  */
 import fs from "node:fs";
@@ -15,8 +15,20 @@ import { installedSkillVersion, SKILLS, stopHookState, TOOL_SKILL_DIRS } from ".
 import { packageVersion } from "./package.js";
 import { resolveProjects } from "./registry.js";
 import { setupReport } from "./scope.js";
+import { detectTestRunner, testResultsHint } from "./test-runner.js";
 import { savedTools } from "./tools.js";
 import { onPath, readJson, relativePath } from "./util.js";
+import { hasTestNames } from "./verify/test-results.js";
+/** How to get test results for a project without `testResults`: .NET writes TRX, JavaScript runners by detection. */
+function missingResultsFix(adapterId, ctx, root) {
+    const dir = path.join(root, ".flagrm", "test-results", ctx.name);
+    const fromProject = relativePath(ctx.root, dir) || ".";
+    const fromConfig = `./${relativePath(root, dir)}`;
+    if (adapterId === "dotnet") {
+        return `add \`--logger trx --results-directory "${fromProject}"\` to the test command and set testResults: ${fromConfig}/*.trx`;
+    }
+    return testResultsHint(detectTestRunner(ctx.root), fromProject, fromConfig, adapterId === "angular", root);
+}
 /** Check the setup in `cwd`: config and commands, git, .gitignore, skills, hook and abandoned baselines. */
 export async function runDoctor(cwd, options = {}) {
     const checks = [];
@@ -93,10 +105,13 @@ async function configChecks(cwd, configFile, options, add) {
     setupChecks(projects, root, options.probes ?? realProbes((exe) => onPath(exe, root)), add);
     for (const { adapter, ctx } of projects) {
         const commands = projectCommands(adapter, ctx);
-        for (const check of ["build", "test"]) {
+        for (const check of ["build", "test", "lint"]) {
             const command = commands[check];
             if (!command) {
-                add("warn", `${ctx.name}: no ${check} command — verify can't ${check === "build" ? "check the build" : "compare tests"}`);
+                // Lint is optional: verify skips it without a command, which is no problem.
+                if (check !== "lint") {
+                    add("warn", `${ctx.name}: no ${check} command — verify can't ${check === "build" ? "check the build" : "compare tests"}`);
+                }
                 continue;
             }
             const missing = simpleCommandProgram(command);
@@ -111,7 +126,7 @@ async function configChecks(cwd, configFile, options, add) {
                 }
             }
             if (check === "test" && !commands.testResults) {
-                add("warn", `${ctx.name}: test command has no testResults — verify can't compare tests by name, so a test that fails before the removal fails verify too`);
+                add("warn", `${ctx.name}: test command has no testResults — verify reads failing tests and counts from the log only and deleted tests from the diff, so it can't compare tests by name`, [`fix: ${missingResultsFix(adapter.id, ctx, root)}`]);
             }
             if (!options.run) {
                 const source = commands.defaults.includes(check) ? " (adapter default)" : "";
@@ -121,16 +136,21 @@ async function configChecks(cwd, configFile, options, add) {
             const log = path.join(root, ".flagrm", "doctor", `${ctx.name}.${check}.log`);
             const run = await runCheck(ctx, check, command, log, undefined, commands.testResults);
             // Proven here rather than halfway through a removal: without readable results, verify can't compare tests.
-            if (check === "test" && commands.testResults && !run.results) {
+            if (check === "test" && commands.testResults && !hasTestNames(run.results)) {
                 add("fail", `${ctx.name}: \`${command}\` wrote no test results matching ${relativePath(cwd, commands.testResults)}`, run.exitCode === 0 ? undefined : errorExcerpt(run.log, 3));
                 continue;
             }
             // A suite that is already red is no setup problem: the baseline records those tests as known failures.
-            if (run.exitCode !== 0 && run.results?.failed) {
+            if (run.exitCode !== 0 && run.results?.failed && run.results.failedNames.length >= run.results.failed) {
                 const failed = run.results.failed;
                 add("warn", `${ctx.name}: \`${command}\`: ${failed === 1 ? "1 test fails already — the baseline records it as a known failure" : `${failed} tests fail already — the baseline records them as known failures`}, which verify only warns about`);
                 continue;
             }
+            // Lint debt is no setup problem: verify only warns about a lint run that already failed at the baseline.
+            if (check === "lint" && run.exitCode !== 0 && !run.failure && !run.interrupted) {
+                add("warn", `${ctx.name}: \`${command}\` fails already (exit ${run.exitCode}) — verify only warns about lint errors the baseline had`, errorExcerpt(run.log, 3));
+                continue;
+            }
             if (run.exitCode === 0) {
                 add("ok", `${ctx.name}: \`${command}\` passed`);
                 continue;

package/dist/core/environment.js

@@ -1,8 +1,8 @@
 /**
  * Tell a machine setup problem apart from broken code in a failed build or
  * test log: a missing .NET SDK, a tool a build step calls that isn't
- * installed, Docker not running for Testcontainers. Each becomes one line
- * that says what to fix.
+ * installed, Docker not running for Testcontainers, a package script or
+ * ESLint config that doesn't exist. Each becomes one line that says what to fix.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -12,7 +12,13 @@ import { relativePath } from "./util.js";
  * it shows none. `root` is the project root: paths are reported relative to it.
  */
 export function environmentProblem(log, root) {
-    const problems = [missingSdk(log, root), ...missingCommands(log, root), dockerUnavailable(log)].filter(Boolean);
+    const problems = [
+        missingSdk(log, root),
+        ...missingCommands(log, root),
+        dockerUnavailable(log),
+        missingScript(log),
+        eslintBroken(log),
+    ].filter(Boolean);
     return problems.length ? problems.join("; ") : undefined;
 }
 /**
@@ -77,3 +83,19 @@ function dockerUnavailable(log) {
         return undefined;
     return "Docker is not running (Testcontainers tests need it): start Docker or leave those tests out of `test`";
 }
+/** npm and pnpm print `Missing script: "lint"`, Yarn 1 `Command "lint" not found`, Yarn 2+ `Couldn't find a script named "lint"`. */
+function missingScript(log) {
+    const name = /\bMissing script: "?([^"\s]+)"?/.exec(log)?.[1] ??
+        /\berror Command "([^"]+)" not found/.exec(log)?.[1] ??
+        /Couldn't find a script named "([^"]+)"/.exec(log)?.[1];
+    if (!name)
+        return undefined;
+    return `package.json has no "${name}" script: add it or change the command in the config`;
+}
+/** ESLint that can't find its config or crashes exits 2 before it lints anything. */
+function eslintBroken(log) {
+    if (!/ESLint couldn't find (?:a configuration file|an eslint\.config)|Oops! Something went wrong! :\(/.test(log)) {
+        return undefined;
+    }
+    return "ESLint could not run (no config found, or it crashed): fix its setup or change the command in the config";
+}

package/dist/core/git.js

@@ -3,6 +3,7 @@
  * to the config root (`cwd`), and flagrm's own `.flagrm/` directory is ignored.
  */
 import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -12,6 +13,8 @@ function git(cwd, ...args) {
     const result = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
     return { ok: result.status === 0, stdout: result.stdout ?? "" };
 }
+/** Whether git reads `rev` as a revision: one starting with `-` (`--output=<file>`) would be an option. */
+const isRevision = (rev) => rev !== "" && !rev.startsWith("-");
 /** NUL-separated paths (`-z`), which git never quotes or escapes, whatever the file name. */
 const paths = (text) => text.split("\0").filter(Boolean);
 /** Untracked (and not ignored) files under `cwd`. */
@@ -26,11 +29,41 @@ export function gitState(cwd) {
     const dirtyFiles = changedFilesSince(cwd, "HEAD") ?? [];
     return { sha: head.stdout.trim(), dirty: dirtyFiles.length > 0, dirtyFiles };
 }
+function hashObjects(cwd, files) {
+    const result = spawnSync("git", ["hash-object", "--stdin-paths"], {
+        cwd,
+        encoding: "utf8",
+        input: `${files.join("\n")}\n`,
+    });
+    return result.status === 0 ? (result.stdout ?? "").split("\n") : undefined;
+}
+/**
+ * Each file's git blob id as it is in the working tree (null when it doesn't
+ * exist), so a later run can tell whether it changed since. A file git can't
+ * hash (a submodule directory) gets an id of its own each time, so it always
+ * counts as changed. Paths are relative to `cwd`.
+ */
+export function blobIds(cwd, files) {
+    const ids = {};
+    const existing = files.filter((rel) => fs.existsSync(path.join(cwd, rel)));
+    for (const rel of files)
+        ids[rel] = null;
+    if (existing.length === 0)
+        return ids;
+    // One git call for all files; when it fails, one per file, so a single unhashable path doesn't spoil the rest.
+    const out = hashObjects(cwd, existing);
+    existing.forEach((rel, i) => {
+        ids[rel] = (out ? out[i] : hashObjects(cwd, [rel])?.[0]) || `unhashable:${randomUUID()}`;
+    });
+    return ids;
+}
 /**
  * Files added, modified or deleted in the working tree since `sha` (tracked
  * diff plus untracked files), without the ones `ignore` names.
  */
 export function changedFilesSince(cwd, sha, ignore) {
+    if (!isRevision(sha))
+        return undefined;
     const diff = git(cwd, "diff", "-z", "--name-only", "--no-renames", "--relative", sha, ...PATHSPEC);
     if (!diff.ok)
         return undefined;
@@ -43,6 +76,8 @@ export function changedFilesSince(cwd, sha, ignore) {
  * Undefined when git can't tell.
  */
 export function trackedChangesSince(cwd, sha, ignore) {
+    if (!isRevision(sha))
+        return undefined;
     const diff = git(cwd, "diff", "-z", "--name-only", "--no-renames", "--relative", sha, ...PATHSPEC);
     if (!diff.ok)
         return undefined;
@@ -51,6 +86,8 @@ export function trackedChangesSince(cwd, sha, ignore) {
 }
 /** A file's content at `sha`, or undefined when it did not exist there. */
 export function fileAt(cwd, sha, relativePath) {
+    if (!isRevision(sha))
+        return undefined;
     const result = git(cwd, "show", `${sha}:./${relativePath.split(path.sep).join("/")}`);
     return result.ok ? result.stdout : undefined;
 }
@@ -108,17 +145,27 @@ export function treeFingerprint(cwd, ignore) {
  * doesn't have it), so the fingerprint doesn't see changes to it.
  */
 function dropIgnored(cwd, index, ignore) {
-    const listed = paths(gitWithIndex(cwd, index, ["ls-files", "-z"]).stdout).filter(ignore);
+    const head = headSha(cwd);
+    // The paths that differ from HEAD, deleted ones included: `ls-files` no longer lists a deleted file.
+    // Before the first commit there is no HEAD to compare with, so every path in the index.
+    const listing = head
+        ? gitWithIndex(cwd, index, ["diff-index", "--cached", "--name-only", "--no-renames", "--relative", "-z", "HEAD"])
+        : gitWithIndex(cwd, index, ["ls-files", "-z"]);
+    if (!listing.ok)
+        return false;
+    const listed = paths(listing.stdout).filter(ignore);
     if (listed.length === 0)
         return true;
     const input = `${listed.join("\0")}\0`;
     const fromFile = ["--pathspec-from-file=-", "--pathspec-file-nul"];
     // `reset` also drops a path HEAD doesn't have; before the first commit there is no HEAD to reset to.
-    const args = headSha(cwd) ? ["reset", "-q", "HEAD", ...fromFile] : ["rm", "-q", "--cached", ...fromFile];
+    const args = head ? ["reset", "-q", "HEAD", ...fromFile] : ["rm", "-q", "--cached", ...fromFile];
     return gitWithIndex(cwd, index, args, input).ok;
 }
 /** The tree id of `cwd` at commit `sha`. */
 export function treeAt(cwd, sha) {
+    if (!isRevision(sha))
+        return undefined;
     const prefix = repoPrefix(cwd);
     if (prefix === undefined)
         return undefined;
@@ -132,5 +179,5 @@ export function headSha(cwd) {
 }
 /** Whether `sha` is HEAD or one of its ancestors. */
 export function isAncestor(cwd, sha) {
-    return git(cwd, "merge-base", "--is-ancestor", sha, "HEAD").ok;
+    return isRevision(sha) && git(cwd, "merge-base", "--is-ancestor", sha, "HEAD").ok;
 }

package/dist/core/hook.js

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { changeFilterAt } from "./change-filter.js";
 import { findConfigRoot } from "./config.js";
+import { scanConfigChanged } from "./config-snapshot.js";
 import { headSha, trackedChangesSince, treeFingerprint } from "./git.js";
 import { readJson } from "./util.js";
 /** The hook's stdin: only a JSON object counts, and only fields of the expected type are kept. */
@@ -38,7 +39,8 @@ export function hookRoot(cwd) {
  * matches the current tree. In progress means HEAD is still the baseline
  * commit and a file git tracks changed, other than flagrm's setup files and
  * paths matching `exclude` (a removal paused on a question to the user, or a
- * stray test result file, doesn't count), or the last verify skipped checks.
+ * stray test result file, doesn't count), the config changed in what it
+ * scans or ignores, or the last verify skipped checks.
  * The fingerprint leaves out the same paths, as verify's does. Once HEAD moves (a
  * commit, a branch switch, a merge), that removal is no longer guarded.
  */
@@ -61,7 +63,7 @@ export function stopDecision(root, input) {
             return { block: false };
         const ignore = changeFilterAt(root);
         const edited = (trackedChangesSince(root, head, ignore) ?? []).length > 0;
-        const started = active.filter((flagDir) => edited || lastVerifySkipped(flagDir));
+        const started = active.filter((flagDir) => edited || lastVerifySkipped(flagDir) || configChanged(flagDir, root));
         if (started.length === 0)
             return { block: false };
         const current = treeFingerprint(root, ignore);
@@ -74,6 +76,15 @@ export function stopDecision(root, input) {
         return { block: false };
     }
 }
+/**
+ * Whether the config changed since the baseline (or `--accept config`) in what
+ * is scanned or ignored: widening `exclude` would otherwise hide the removal's
+ * edits from the hook. A verify passing on this tree shows the change and allows.
+ */
+function configChanged(flagDir, root) {
+    const baseline = readJson(path.join(flagDir, "baseline.json"));
+    return scanConfigChanged(baseline?.acceptedConfig ?? baseline?.config, root);
+}
 function lastVerifySkipped(flagDir) {
     const skipped = readJson(path.join(flagDir, "verify.json"))?.skipped;
     return Array.isArray(skipped) && skipped.length > 0;

package/dist/core/install.js

@@ -11,6 +11,7 @@ import path from "node:path";
 import { DEFAULT_BACKEND_ATTRIBUTES, DEFAULT_BACKEND_METHODS, DEFAULT_FRONTEND_METHODS, findConfigRoot, findDefaultConfigFile, repositoryRoot, TOOL_IDS, } from "./config.js";
 import { detectProjects } from "./detect.js";
 import { packageRoot, packageVersion } from "./package.js";
+import { runnerTestCommands, testResultsHint } from "./test-runner.js";
 import { saveTools } from "./tools.js";
 import { relativePath } from "./util.js";
 export const SKILLS = ["flagrm-remove", "flagrm-verify"];
@@ -27,11 +28,11 @@ export const PROMPT_FILES = {
     "flagrm-remove": [
         "---",
         "description: Remove a feature flag with flagrm's guardrails (keep the ON path, verify until it passes)",
-        "argument-hint: <flag>",
+        "argument-hint: <flag> [flag...]",
         "agent: agent",
         "---",
         "",
-        "Follow `.github/skills/flagrm-remove/SKILL.md` to remove the feature flag named after this command.",
+        "Follow `.github/skills/flagrm-remove/SKILL.md` to remove the feature flags named after this command.",
         "",
     ].join("\n"),
     "flagrm-verify": [
@@ -61,8 +62,8 @@ export const AGENTS_BLOCK = [
     AGENTS_START,
     "## Feature flag removal (flagrm)",
     "",
-    "To remove a feature flag, follow `.agents/skills/flagrm-remove/SKILL.md`. To check a removal and get its",
-    "commit message, follow `.agents/skills/flagrm-verify/SKILL.md`.",
+    "To remove one or more feature flags, follow `.agents/skills/flagrm-remove/SKILL.md`. To check a removal",
+    "later, follow `.agents/skills/flagrm-verify/SKILL.md`.",
     AGENTS_END,
 ].join("\n");
 const CONFIG_HEADER = [
@@ -89,14 +90,21 @@ const EXAMPLE_PROJECTS = [
     { name: "backend", adapter: "dotnet", path: "backend", marker: "backend/Backend.sln" },
 ];
 /** The config lines for one project, with commented-out commands that fit it. */
-function projectLines(p) {
+function projectLines(p, cwd) {
     const dir = p.path === "." ? "." : `./${p.path}`;
     const inDir = (rel) => (p.path === "." ? `./${rel}` : `${dir}/${rel}`);
     const lines = [`  - name: ${p.name}`, `    adapter: ${p.adapter}`, `    path: ${dir}`];
     if (p.adapter === "angular") {
-        lines.push("    # build: npx ng build", p.jest
-            ? "    # test: JEST_JUNIT_OUTPUT_DIR=test-results npx jest --ci --reporters=default --reporters=jest-junit"
-            : "    # test: npx ng test --watch=false", `    # testResults: ${inDir("test-results/junit.xml")}   # JUnit XML, so verify can count tests`, `    # methods: [${DEFAULT_FRONTEND_METHODS.join(", ")}]   # flag evaluation methods (defaults shown)`);
+        const results = path.join(cwd, ".flagrm", "test-results", p.name);
+        const runner = p.testRunner ?? { kind: "unknown" };
+        const tests = runnerTestCommands(runner, path.join(cwd, p.path), results);
+        lines.push("    # build: npx ng build", `    # test: ${tests?.test ?? "npx ng test --watch=false"}`, tests
+            ? `    # testResults: ./${relativePath(cwd, tests.testResults)}   # the default test command writes these`
+            : `    # testResults: ${inDir("test-results/junit.xml")}   # JUnit XML, TRX or Jest JSON, so verify can compare tests`, ...(tests
+            ? []
+            : [
+                `    # to get test results: ${testResultsHint(runner, relativePath(path.join(cwd, p.path), results) || ".", `./${relativePath(cwd, results)}`, true, cwd)}`,
+            ]), `    # methods: [${DEFAULT_FRONTEND_METHODS.join(", ")}]   # flag evaluation methods (defaults shown)`);
     }
     else {
         const solution = /\.slnx?$/.test(p.marker) ? ` ${path.posix.basename(p.marker)}` : "";
@@ -104,13 +112,20 @@ function projectLines(p) {
     }
     return lines;
 }
-export function configTemplate(projects, tools) {
+export function configTemplate(projects, tools, cwd = process.cwd()) {
     const listed = projects.length ? projects : EXAMPLE_PROJECTS;
     const [comment1, comment2, projectsKey] = CONFIG_HEADER;
     const toolLines = tools
         ? ["# The AI coding tools `flagrm init` and `flagrm update` set up.", `tools: [${tools.join(", ")}]`]
         : [];
-    return [comment1, comment2, ...toolLines, projectsKey, ...listed.flatMap(projectLines), ...CONFIG_FOOTER].join("\n");
+    return [
+        comment1,
+        comment2,
+        ...toolLines,
+        projectsKey,
+        ...listed.flatMap((p) => projectLines(p, cwd)),
+        ...CONFIG_FOOTER,
+    ].join("\n");
 }
 /** Write `flagrm.config.yaml` for the projects found in `cwd` (an example when none are) unless a config file exists. */
 export function writeConfigTemplate(cwd, tools) {
@@ -119,7 +134,7 @@ export function writeConfigTemplate(cwd, tools) {
         return { path: relativePath(cwd, existing), status: "skipped" };
     const file = path.join(cwd, "flagrm.config.yaml");
     const projects = detectProjects(cwd);
-    fs.writeFileSync(file, configTemplate(projects, tools), "utf8");
+    fs.writeFileSync(file, configTemplate(projects, tools, cwd), "utf8");
     const note = projects.length
         ? `detected ${projects.map((p) => `${p.adapter} (${p.marker})`).join(", ")}`
         : "no Angular or .NET project found: edit the example projects";

package/dist/core/inventory.js

@@ -138,7 +138,9 @@ function followFlow(projects, entries) {
                 continue;
             const words = flagWords([{ name: entry.flag }, ...entry.definitions]);
             const flagNames = [entry.flag, ...entry.definitions.map((d) => d.name.split(".").pop() ?? d.name)];
-            entry.flow.push({ ...name, record: !name.ambiguous && recordable(name, flagNames, words) });
+            // A renamed import of one of the flag's definitions is as specific as the definition.
+            const record = name.kind === "alias" || (!name.ambiguous && recordable(name, flagNames, words));
+            entry.flow.push({ ...name, record });
         }
         for (const test of tests)
             byFlag.get(test.flag)?.parameterizedTests.push(test);

package/dist/core/markdown.js

@@ -3,6 +3,7 @@
  * for the user or a PR. Every fact comes from the report; the agent adds
  * notes and the commit message around it.
  */
+import { reusedNote } from "./run-cache.js";
 import { relativePath } from "./util.js";
 import { shortTestName, shortTestNames } from "./verify/test-results.js";
 const ICON = { pass: "✅", fail: "❌", warn: "⚠️", skipped: "➖" };
@@ -30,6 +31,9 @@ export function verifyMarkdown(report, root) {
         "|---|---|---|",
         ...report.checks.map((c) => `| ${c.id} | ${ICON[c.status]} ${c.status} | ${c.summary.replace(/\|/g, "\\|")} |`),
     ];
+    const note = reusedNote(report.runs, report.createdAt);
+    if (note)
+        out.push("", `_${note}_`);
     const changed = report.changedFiles ?? [];
     if (changed.length)
         out.push("", `**Files changed since baseline (${changed.length}):** ${codeList(changed)}`);

package/dist/core/name-owner.js

@@ -0,0 +1,179 @@
+/**
+ * Which flags a name's code reads: where the name is declared or assigned
+ * (`name =`, `name:`, `name(...) {`, `Name =>`, `Name {`), and the flag
+ * literals and qualified names in what follows, up to the end of that
+ * statement or body. Lexical like the rest of discovery (comments and strings
+ * masked), so it works for TypeScript and C# alike and misses unusual shapes.
+ *
+ * `baseline --name` refuses a name that reads only other flags: once
+ * recorded, `leftovers` would make the agent delete another flag's code, and
+ * a recorded name can't be removed again.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "./baseline.js";
+import { buildInventory } from "./inventory.js";
+import { commentSyntax, computeLexicalMask, escapeRegExp, LEX_CODE, LEX_STRING } from "./scan.js";
+import { SourceText } from "./source-text.js";
+import { toLf } from "./text-utils.js";
+import { relativePath } from "./util.js";
+const MAX_LINES = 20;
+const OPEN = "([{";
+const CLOSE = ")]}";
+/** Every declaration or assignment of `name` in `files` (absolute; every project file when undefined). */
+export function nameReads(projects, name, files, flags) {
+    const only = files && new Set(files);
+    const word = new RegExp(`(?<![\\w$])${escapeRegExp(name)}(?![\\w$])`, "g");
+    const out = [];
+    const seen = new Set();
+    for (const { ctx } of projects) {
+        for (const file of ctx.files) {
+            if (seen.has(file) || (only && !only.has(file)) || commentSyntax(file) !== "slash")
+                continue;
+            seen.add(file);
+            let text;
+            try {
+                text = toLf(fs.readFileSync(file, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            if (!text.includes(name))
+                continue;
+            const mask = computeLexicalMask(text, "slash");
+            const source = new SourceText(file, text);
+            for (const m of text.matchAll(word)) {
+                if (mask[m.index] !== LEX_CODE)
+                    continue;
+                const after = m.index + name.length;
+                if (!isSite(text, mask, m.index, after))
+                    continue;
+                const body = text.slice(after, statementEnd(text, mask, after));
+                out.push({ file, line: source.position(m.index).line, flags: flagsIn(body, flags) });
+            }
+        }
+    }
+    return out;
+}
+/** A declaration or assignment of the name at `start..after`, not a read, a call, a ternary branch or a case label. */
+function isSite(text, mask, start, after) {
+    const before = text.slice(Math.max(0, start - 40), start);
+    if (/\?\s*$/.test(before) || /\bcase\s+$/.test(before))
+        return false;
+    let i = after;
+    while (i < text.length && /[ \t]/.test(text[i]))
+        i++;
+    // `x?:` / `x!:` (optional, definite) and `x ??= y` declare or assign; `x != y`, `x ? a : b` and `x!.y` don't.
+    if (text[i] === "?" || text[i] === "!") {
+        const op = text.slice(i, i + 3);
+        return op[1] === ":" || op === "??=";
+    }
+    const rest = text.slice(i, i + 3);
+    if (rest.startsWith("=>"))
+        return true;
+    if (rest.startsWith("="))
+        return !rest.startsWith("==");
+    if (rest.startsWith(":"))
+        return true;
+    if (rest.startsWith("{"))
+        return true;
+    if (!rest.startsWith("("))
+        return false;
+    // A parameter list, then (after an optional return type, which may hold `|`, `.` or `<>`) a body or
+    // `=>`: a method. Anything else is a call: `;`/`,`/`}` or a line break first, or a `)` closing an
+    // enclosing bracket (`if (isX()) {`). Arrows and braces inside the call's own brackets don't count.
+    let depth = 0;
+    for (let j = i; j < Math.min(text.length, i + 400); j++) {
+        if (mask[j] !== LEX_CODE)
+            continue;
+        const c = text[j];
+        if (c === "(")
+            depth++;
+        else if (c === ")") {
+            if (--depth < 0)
+                return false;
+        }
+        else if (depth > 0)
+            continue;
+        else if (c === "{")
+            return true;
+        else if (c === "=" && text[j + 1] === ">")
+            return true;
+        else if (c === ";" || c === "," || c === "}")
+            return false;
+        else if (c === "\n") {
+            const head = text.slice(j + 1).trimStart();
+            return head.startsWith("{") || head.startsWith("=>");
+        }
+    }
+    return false;
+}
+/** Where the statement or body starting at `from` ends: `;` or `,` at depth 0, a closing bracket below it, or a `{` body's `}`. */
+function statementEnd(text, mask, from) {
+    let depth = 0;
+    let lines = 0;
+    for (let i = from; i < text.length; i++) {
+        if (text[i] === "\n" && ++lines >= MAX_LINES)
+            return i;
+        if (mask[i] !== LEX_CODE)
+            continue;
+        const c = text[i];
+        if (OPEN.includes(c))
+            depth++;
+        else if (CLOSE.includes(c)) {
+            depth--;
+            if (depth < 0)
+                return i;
+            if (depth === 0 && c === "}")
+                return i + 1;
+        }
+        else if (depth === 0 && (c === ";" || c === ","))
+            return i;
+    }
+    return text.length;
+}
+/** The flags whose literal (quoted) or qualified name (in code) occurs in `body`. */
+function flagsIn(body, flags) {
+    const mask = computeLexicalMask(body, "slash");
+    return flags
+        .filter(({ flag, aliases }) => {
+        for (const m of body.matchAll(new RegExp(`(['"\`])${escapeRegExp(flag)}\\1`, "g"))) {
+            if (mask[m.index] === LEX_STRING)
+                return true;
+        }
+        return aliases.some((alias) => {
+            const pattern = alias.split(".").map(escapeRegExp).join("\\s*\\.\\s*");
+            for (const m of body.matchAll(new RegExp(`(?<![\\w$])${pattern}(?![\\w$])`, "g"))) {
+                if (mask[m.index] === LEX_CODE)
+                    return true;
+            }
+            return false;
+        });
+    })
+        .map((f) => f.flag);
+}
+/** Throw a {@link UsageError} for the first agent name whose code reads only flags other than `flag`. */
+export async function assertOwnNames(root, projects, flag, names) {
+    if (names.length === 0)
+        return;
+    const inventory = (await buildInventory(projects)).flags;
+    // A renamed import of the flag's registry (`AppFeatureFlags.X`) reads it as much as the definition does.
+    const refs = inventory.map((e) => ({
+        flag: e.flag,
+        aliases: [...e.definitions.map((d) => d.name), ...e.flow.filter((n) => n.kind === "alias").map((n) => n.name)],
+    }));
+    if (!refs.some((r) => r.flag === flag))
+        refs.push({ flag, aliases: [] });
+    for (const name of [...new Set(names.map((n) => n.name))]) {
+        const entries = names.filter((n) => n.name === name);
+        const files = entries.every((n) => n.file) ? entries.map((n) => path.resolve(root, n.file)) : undefined;
+        const sites = nameReads(projects, name, files, refs);
+        if (sites.some((s) => s.flags.includes(flag)))
+            continue;
+        const foreign = sites.find((s) => s.flags.length > 0);
+        if (!foreign)
+            continue;
+        throw new UsageError(`"${name}" reads ${foreign.flags.join(", ")}, not ${flag} (${relativePath(root, foreign.file)}:${foreign.line}); ` +
+            "not recorded. Record only names this flag's value goes through.");
+    }
+}