flagrm 0.2.1 → 0.4.0

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";
@@ -26,32 +27,70 @@ export function gitState(cwd) {
     const dirtyFiles = changedFilesSince(cwd, "HEAD") ?? [];
     return { sha: head.stdout.trim(), dirty: dirtyFiles.length > 0, dirtyFiles };
 }
-/** Files added, modified or deleted in the working tree since `sha` (tracked diff plus untracked files). */
-export function changedFilesSince(cwd, sha) {
+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) {
     const diff = git(cwd, "diff", "-z", "--name-only", "--no-renames", "--relative", sha, ...PATHSPEC);
     if (!diff.ok)
         return undefined;
-    return [...new Set([...paths(diff.stdout), ...untracked(cwd)])].sort();
+    const all = [...new Set([...paths(diff.stdout), ...untracked(cwd)])].sort();
+    return ignore ? all.filter((rel) => !ignore(rel)) : all;
 }
 /**
  * Tracked files modified or deleted in the working tree since `sha` (staged
- * or not); untracked files don't count. Undefined when git can't tell.
+ * or not), without the ones `ignore` names; untracked files don't count.
+ * Undefined when git can't tell.
  */
-export function trackedChangesSince(cwd, sha) {
+export function trackedChangesSince(cwd, sha, ignore) {
     const diff = git(cwd, "diff", "-z", "--name-only", "--no-renames", "--relative", sha, ...PATHSPEC);
-    return diff.ok ? paths(diff.stdout).sort() : undefined;
+    if (!diff.ok)
+        return undefined;
+    const all = paths(diff.stdout).sort();
+    return ignore ? all.filter((rel) => !ignore(rel)) : all;
 }
 /** A file's content at `sha`, or undefined when it did not exist there. */
 export function fileAt(cwd, sha, relativePath) {
     const result = git(cwd, "show", `${sha}:./${relativePath.split(path.sep).join("/")}`);
     return result.ok ? result.stdout : undefined;
 }
-function gitWithIndex(cwd, index, ...args) {
+function gitWithIndex(cwd, index, args, input) {
     const result = spawnSync("git", args, {
         cwd,
         encoding: "utf8",
         maxBuffer: 256 * 1024 * 1024,
-        env: { ...process.env, GIT_INDEX_FILE: index },
+        input,
+        // Literal: a file named `[ab].txt` must not match `a.txt` when its path is passed back to git.
+        env: { ...process.env, GIT_INDEX_FILE: index, GIT_LITERAL_PATHSPECS: input === undefined ? undefined : "1" },
     });
     return { ok: result.status === 0, stdout: result.stdout ?? "" };
 }
@@ -62,12 +101,13 @@ function repoPrefix(cwd) {
 }
 /**
  * The git tree id of the working tree under `cwd` as it would be committed:
- * tracked and untracked files, not ignored ones, without `.flagrm/`. Built in a
- * temporary copy of the index, so the user's index is untouched. Committing
- * the tree doesn't change it; any edit does. Before any edit it equals
- * {@link treeAt} of HEAD.
+ * tracked and untracked files, not ignored ones, without `.flagrm/` and the
+ * paths `ignore` names. Built in a temporary copy of the index, so the user's
+ * index is untouched. Committing the tree doesn't change it; any edit does.
+ * Before any edit it equals {@link treeAt} of HEAD, as long as the ignored
+ * paths are unchanged since.
  */
-export function treeFingerprint(cwd) {
+export function treeFingerprint(cwd, ignore) {
     const prefix = repoPrefix(cwd);
     if (prefix === undefined)
         return undefined;
@@ -79,17 +119,41 @@ export function treeFingerprint(cwd) {
         if (realIndex && fs.existsSync(realIndex))
             fs.cpSync(realIndex, index, { preserveTimestamps: true });
         // Not PATHSPEC: `git add` exits 1 when an exclude pathspec names an ignored path (`.flagrm/` usually is).
-        if (!gitWithIndex(cwd, index, "add", "-A", "--", ".").ok)
+        if (!gitWithIndex(cwd, index, ["add", "-A", "--", "."]).ok)
             return undefined;
-        if (!gitWithIndex(cwd, index, "rm", "-r", "-q", "--cached", "--ignore-unmatch", "--", ".flagrm").ok)
+        if (!gitWithIndex(cwd, index, ["rm", "-r", "-q", "--cached", "--ignore-unmatch", "--", ".flagrm"]).ok)
             return undefined;
-        const tree = gitWithIndex(cwd, index, "write-tree", ...(prefix ? [`--prefix=${prefix}`] : []));
+        if (ignore && !dropIgnored(cwd, index, ignore))
+            return undefined;
+        const tree = gitWithIndex(cwd, index, ["write-tree", ...(prefix ? [`--prefix=${prefix}`] : [])]);
         return tree.ok ? tree.stdout.trim() : undefined;
     }
     finally {
         fs.rmSync(dir, { recursive: true, force: true });
     }
 }
+/**
+ * Put back each path `ignore` names as it is at HEAD (or drop it, if HEAD
+ * doesn't have it), so the fingerprint doesn't see changes to it.
+ */
+function dropIgnored(cwd, index, 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 = 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) {
     const prefix = repoPrefix(cwd);

package/dist/core/hook.js

@@ -6,7 +6,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { CONFIG_FILENAMES, findConfigRoot } from "./config.js";
+import { changeFilterAt } from "./change-filter.js";
+import { findConfigRoot } from "./config.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. */
@@ -35,9 +36,10 @@ export function hookRoot(cwd) {
 /**
  * Whether to block the stop: a removal is in progress and no passing verify
  * matches the current tree. In progress means HEAD is still the baseline
- * commit and a file git tracks changed, other than the flagrm config (a
- * removal paused on a question to the user, or a stray test result file,
- * doesn't count), or the last verify skipped checks. Once HEAD moves (a
+ * 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.
+ * 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.
  */
 export function stopDecision(root, input) {
@@ -57,11 +59,12 @@ export function stopDecision(root, input) {
             .filter((flagDir) => readJson(path.join(flagDir, "baseline.json"))?.git?.sha === head);
         if (active.length === 0)
             return { block: false };
-        const edited = (trackedChangesSince(root, head) ?? []).some((rel) => !CONFIG_FILENAMES.includes(rel));
+        const ignore = changeFilterAt(root);
+        const edited = (trackedChangesSince(root, head, ignore) ?? []).length > 0;
         const started = active.filter((flagDir) => edited || lastVerifySkipped(flagDir));
         if (started.length === 0)
             return { block: false };
-        const current = treeFingerprint(root);
+        const current = treeFingerprint(root, ignore);
         if (!current)
             return { block: false };
         const reasons = started.map((flagDir) => unverified(flagDir, current)).filter((r) => r !== undefined);

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.");
+    }
+}

package/dist/core/report.js

@@ -1,4 +1,5 @@
 import pc from "picocolors";
+import { reusedNote } from "./run-cache.js";
 import { plural, relativePath } from "./util.js";
 /** A path relative to the working directory, with `/` separators on every platform. */
 function rel(file) {
@@ -70,10 +71,19 @@ export function printBaseline(baseline, file) {
         if (c.failure)
             console.log(`    ${pc.yellow("setup problem:")} ${c.failure.message}`);
     }
+    const note = reusedNote(checks ?? [], baseline.createdAt);
+    if (note)
+        console.log(`  ${pc.dim(note)}`);
     if (baseline.names.length) {
         const names = baseline.names.map((n) => n.kind === "literal" ? n.name : `${n.name} (${n.kind}${n.file ? ` in ${n.file}` : ""})`);
         console.log(`  names: ${pc.dim(names.join(", "))}`);
     }
+    const accepted = [
+        baseline.acceptedConfig && "the config as of now",
+        baseline.acceptedFailures && "the baseline's failing tests",
+    ].filter(Boolean);
+    if (accepted.length)
+        console.log(`  accepted: ${pc.dim(accepted.join(", "))}`);
     for (const n of baseline.suggestedNames ?? []) {
         console.log(`  ${pc.yellow("suggested")} ${n.name} ${pc.dim(`(${n.kind})`)} ${pc.cyan(`${rel(n.file)}:${n.line}`)} ` +
             pc.dim(`if it only carries this flag: --name ${n.name} --kind wrapper` +
@@ -116,6 +126,9 @@ export function printVerifyReport(report, file) {
     }
     if (report.strict && warned)
         console.log(pc.dim("\n  --strict: warnings count as failures."));
+    const note = reusedNote(report.runs, report.createdAt);
+    if (note)
+        console.log(pc.dim(`\n  ${note}`));
     console.log(pc.dim(`\nResult written to ${rel(file)}.`));
 }
 const STEP_STYLE = {