flagrm 0.3.0 → 0.4.1

package/dist/core/verify/removed-tests.js

@@ -2,19 +2,23 @@
  * Why each baseline test no longer runs. Deleting the OFF path's tests and
  * dropping the flag from test names is part of a removal, and a narrower test
  * command leaves tests out on purpose; only the rest needs explaining.
+ * Without result files, the changed test files' declarations stand in for the
+ * names (`declaredTestDiff`).
  */
 import fs from "node:fs";
 import path from "node:path";
 import { flagWords, words } from "../flag-words.js";
 import { fileAt } from "../git.js";
-import { escapeRegExp, isTestPath } from "../scan.js";
+import { computeCodeMask, escapeRegExp, isTestPath } from "../scan.js";
 import { JUNIT_SEPARATOR, testKey } from "./test-results.js";
-/** Sort the tests that no longer run (`removed`) using the new ones (`added`) and the diff. */
-export function classifyRemovedTests(removed, added, afterNames, ctx) {
+/**
+ * Sort the tests that no longer run (`removed`) using the new ones (`added`)
+ * and the diff. `files`: the changed test files when the caller already read them.
+ */
+export function classifyRemovedTests(removed, added, afterNames, ctx, files = changedTestFiles(ctx)) {
     const out = { deleted: [], renamed: [], excludedByConfig: [], unexplained: [] };
     const renamedTo = matchRenames(removed, added, flagWords(ctx.names));
     const stillRuns = new Set(afterNames.map(testKey));
-    const files = changedTestFiles(ctx);
     for (const name of removed) {
         const to = renamedTo.get(testKey(name));
         if (to)
@@ -83,7 +87,7 @@ function matchRenames(removed, added, flag) {
     }
     return out;
 }
-function changedTestFiles(ctx) {
+function changedTestFiles(ctx, includeNew = false) {
     if (!ctx.sha)
         return [];
     const out = [];
@@ -91,7 +95,7 @@ function changedTestFiles(ctx) {
         if (!isTestPath(rel))
             continue;
         const before = fileAt(ctx.root, ctx.sha, rel);
-        if (before === undefined)
+        if (before === undefined && !includeNew)
             continue;
         let now;
         try {
@@ -100,7 +104,7 @@ function changedTestFiles(ctx) {
         catch {
             now = undefined;
         }
-        out.push({ before, now });
+        out.push({ rel, before: before ?? "", now });
     }
     return out;
 }
@@ -123,6 +127,10 @@ function isDeleted(name, keyStillRuns, files) {
 }
 /** xUnit (`InlineData`, `[Bit]AutoData(...)` with values), NUnit and MSTest attributes that each add a data row. */
 const DATA_ROW = /\b(?:\w*InlineData|\w*AutoData|TestCase|DataRow)\s*\(/g;
+/** Whether a test file has data-row attributes or `.each` cases. */
+function hasDataRows(text) {
+    return new RegExp(DATA_ROW.source).test(text) || /\.each\s*[(`]/.test(text);
+}
 /**
  * How many data rows `own` has in `text`: the row attributes between the end
  * of the previous member and its declaration. For JUnit names (`it.each`
@@ -139,3 +147,78 @@ function dataRows(text, own, junit) {
     }
     return rows;
 }
+// --- declarations ----------------------------------------------------------------
+const JS_TEST = /(?<![\w$.])(describe|fdescribe|xdescribe|context|suite|it|fit|xit|test)(?:\.(?:only|skip|todo))?(?:\.each\s*(?:\([\s\S]*?\)|`[\s\S]*?`))?\s*\(\s*(['"`])((?:\\.|(?!\2)[^\\])*)\2/g;
+/** `it`/`test` titles prefixed with the titles of the `describe` blocks around them (by brace depth over code). */
+function jsTests(text) {
+    const code = computeCodeMask(text);
+    const out = [];
+    const open = [];
+    let depth = 0;
+    let pos = 0;
+    for (const m of text.matchAll(JS_TEST)) {
+        if (!code[m.index])
+            continue;
+        for (; pos < m.index; pos++)
+            if (code[pos])
+                depth += text[pos] === "{" ? 1 : text[pos] === "}" ? -1 : 0;
+        while (open.length && open[open.length - 1].depth >= depth)
+            open.pop();
+        if (/describe|context|suite/.test(m[1]))
+            open.push({ title: m[3], depth });
+        else
+            out.push([...open.map((d) => d.title), m[3]].join(JUNIT_SEPARATOR));
+    }
+    return out;
+}
+const CS_TEST = /\[(?:Fact|Theory|Test|TestCase|TestMethod)\b[^\]]*\][\s\S]*?\b(?:void|Task|ValueTask)(?:<[^>]*>)?\s+(\w+)\s*\(/g;
+/** Test methods as TRX names them without data-row arguments: `Namespace.Class.Method`. */
+function csTests(text) {
+    const ns = /^\s*namespace\s+([\w.]+)/m.exec(text)?.[1];
+    return [...text.matchAll(CS_TEST)].map((m) => {
+        const cls = [...text.slice(0, m.index).matchAll(/\bclass\s+(\w+)/g)].pop()?.[1];
+        return [ns, cls, m[1]].filter(Boolean).join(".");
+    });
+}
+/** The tests a test file declares, named as result files name them where the syntax allows. */
+export function declaredTests(text, file) {
+    if (/\.[cm]?[jt]sx?$/.test(file))
+        return jsTests(text);
+    if (file.endsWith(".cs"))
+        return csTests(text);
+    if (file.endsWith(".go"))
+        return [...text.matchAll(/\bfunc (Test\w+)\s*\(/g)].map((m) => m[1]);
+    if (file.endsWith(".py"))
+        return [...text.matchAll(/^\s*def (test_\w+)\s*\(/gm)].map((m) => m[1]);
+    return [];
+}
+/** `from` without the names in `other`, counting duplicates. */
+function minus(from, other) {
+    const left = new Map();
+    for (const name of other)
+        left.set(name, (left.get(name) ?? 0) + 1);
+    return from.filter((name) => {
+        const n = left.get(name) ?? 0;
+        left.set(name, n - 1);
+        return n <= 0;
+    });
+}
+/**
+ * What the changed test files declared at the baseline and don't now, the
+ * new declarations, and all declared now: the stand-in for result files'
+ * names when there are none.
+ */
+export function declaredTestDiff(ctx) {
+    const before = [];
+    const now = [];
+    let rows = false;
+    // A file new since the baseline declared nothing then, so a moved spec's tests cancel out.
+    const files = changedTestFiles(ctx, true);
+    for (const file of files) {
+        rows ||= hasDataRows(file.before) || (file.now !== undefined && hasDataRows(file.now));
+        before.push(...declaredTests(file.before, file.rel));
+        if (file.now !== undefined)
+            now.push(...declaredTests(file.now, file.rel));
+    }
+    return { removed: minus(before, now), added: minus(now, before), now, rows, files };
+}

package/dist/core/verify/test-results.js

@@ -1,12 +1,13 @@
 /**
  * Read test counts and names from the result files a test command writes:
- * TRX (`dotnet test --logger trx`) and JUnit XML (Karma, Jest, Vitest, NUnit
- * and most CI reporters). Both are parsed with regexes over tags and
- * attributes, which is enough for these machine-written formats.
+ * TRX (`dotnet test --logger trx`), JUnit XML (Karma, Jest, Vitest, NUnit
+ * and most CI reporters) and Jest JSON (`jest --json`, Vitest's `json`
+ * reporter). They are parsed with regexes over tags and attributes, or
+ * JSON.parse, which is enough for these machine-written formats.
  */
 import fs from "node:fs";
 import path from "node:path";
-import fg from "fast-glob";
+import { globAbsolute } from "../scan.js";
 function attributes(tag) {
     const out = {};
     for (const m of tag.matchAll(/([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g))
@@ -142,19 +143,64 @@ export function parseJUnit(xml) {
     }
     return results;
 }
+/**
+ * Jest's `--json` output (Vitest's `json` reporter writes the same shape): a
+ * test is named by its `describe` titles and its own, joined like JUnit names;
+ * a test outside any `describe` by its file name. Undefined when the text isn't that.
+ */
+export function parseJestJson(text) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(json?.testResults))
+        return undefined;
+    const results = empty();
+    for (const file of json.testResults) {
+        if (!file || typeof file !== "object" || !Array.isArray(file.assertionResults ?? []))
+            return undefined;
+        for (const test of file.assertionResults ?? []) {
+            if (!test || typeof test !== "object")
+                return undefined;
+            const owners = test.ancestorTitles?.length ? test.ancestorTitles : file.name ? [path.basename(file.name)] : [];
+            const status = test.status ?? "";
+            record(results, [...owners, test.title ?? ""].join(JUNIT_SEPARATOR), status === "passed" ? "passed" : status === "failed" ? "failed" : "skipped");
+        }
+    }
+    return results;
+}
+/**
+ * One result file by its content: TRX, Jest JSON or JUnit XML. Undefined when
+ * it can't be read as any, or the XML document isn't complete (still being written).
+ */
+function parseResultFile(text) {
+    if (/^\s*\{/.test(text))
+        return parseJestJson(text);
+    if (/<TestRun\b/.test(text))
+        return /<\/TestRun>\s*$/.test(text) ? parseTrx(text) : undefined;
+    return /<testsuites?\b/.test(text) && /(?:<\/testsuites?>|<testsuites?\b[^>]*\/>)\s*$/.test(text)
+        ? parseJUnit(text)
+        : undefined;
+}
+/** Whether results name every test that ran (read from result files), not only the failing ones a log names. */
+export function hasTestNames(results) {
+    return results !== undefined && results.source !== "log";
+}
 /**
  * Merge every result file matching `pattern` (an absolute path or glob)
  * modified at or after `since` — test runners keep older result files around.
  * Files in `claimed` that haven't changed since are skipped: another
  * project's run just wrote them, and an overlapping pattern
  * (`./**\/TestResults/*.trx`) would count them twice. The files read are
- * added to `claimed`. Undefined when no such file exists.
+ * added to `claimed`. Undefined when no such file exists or none can be read.
  */
 export function collectTestResults(pattern, since, claimed = new Map()) {
     // Filesystem timestamps can be coarser than Date.now().
     const cutoff = since - 2000;
-    const files = fg
-        .sync(path.sep === "\\" ? pattern.replace(/\\/g, "/") : pattern, { absolute: true, dot: true })
+    const files = globAbsolute(pattern)
         .map((file) => ({ file, mtime: fs.statSync(file).mtimeMs }))
         .filter(({ file, mtime }) => mtime >= cutoff && claimed.get(file) !== mtime)
         .sort((a, b) => a.file.localeCompare(b.file));
@@ -164,8 +210,10 @@ export function collectTestResults(pattern, since, claimed = new Map()) {
         return undefined;
     const merged = empty();
     for (const { file } of files) {
-        const xml = fs.readFileSync(file, "utf8");
-        const parsed = /<TestRun\b/.test(xml) ? parseTrx(xml) : parseJUnit(xml);
+        // A file that is still being written, or isn't a result file, is skipped rather than failing the run.
+        const parsed = parseResultFile(fs.readFileSync(file, "utf8"));
+        if (!parsed)
+            continue;
         merged.total += parsed.total;
         merged.passed += parsed.passed;
         merged.failed += parsed.failed;
@@ -174,5 +222,5 @@ export function collectTestResults(pattern, since, claimed = new Map()) {
         merged.failedNames.push(...parsed.failedNames);
         merged.files.push(file);
     }
-    return merged;
+    return merged.files.length ? merged : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flagrm",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Guardrails for removing feature flags with AI coding agents (Claude Code, Copilot, Codex): skills, a baseline, a verify gate and a Stop hook.",
   "type": "module",
   "license": "Apache-2.0",
@@ -53,17 +53,17 @@
   ],
   "dependencies": {
     "commander": "^13.1.0",
-    "fast-glob": "^3.3.3",
     "picocolors": "^1.1.1",
     "picomatch": "^4.0.7",
+    "tinyglobby": "^0.2.17",
     "typescript": "^5.7.0",
     "yaml": "^2.7.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.10",
+    "@biomejs/biome": "2.5.15",
     "@types/node": "^22.13.0",
     "@types/picomatch": "^4.0.3",
     "tsx": "^4.19.0",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.11"
   }
 }

package/skills/flagrm-remove/SKILL.md

@@ -16,6 +16,8 @@ You find and edit the code. `flagrm` records the state before you start and
 decides when you are done: **done means `flagrm verify <flag> --json` exited 0.**
 Run it as `npx --no-install flagrm`, one command per call, no `||` (plain `npx flagrm` is another package).
 
+Several flags (`/flagrm-remove A B C`): read [batch.md](batch.md) first; it runs this workflow once per flag.
+
 ## 1. Preconditions
 
 - `flagrm doctor` must not warn about uncommitted files (flagrm's own setup files and `exclude`d paths don't count). Otherwise ask the user to commit or stash.
@@ -35,7 +37,7 @@ Without `failure`: a build, stop. Tests: stop if the failures (`results.failedTe
 ## 3. Find every usage
 
 - Grep for each name in `names[]`: code, templates, config and tests. `parameterizedTests[]` are test calls passing ON/OFF.
-- `suggestedNames[]`: values of the flag with generic names. Record each that carries only this flag, a local, parameter or field with `--file <its file>`.
+- `suggestedNames[]`: values of the flag with generic names. Record each that carries only this flag, a local, parameter or field with `--file <its file>` (repeat `--file` for each file; a component's template is added for you).
 - Follow the value further: a method or property returning it, a field or local holding it, a parameter
   it's passed as, a DI-registered bool. Record each so `verify` checks it, then grep for it:
   `flagrm baseline <flag> --name IsNewCheckoutEnabledAsync --kind wrapper` (`--kind alias` for a constant like `Flags.NewCheckout`).
@@ -70,19 +72,37 @@ Read `patterns.md` in this skill's directory when a case is unclear.
 | `dead-code` | Delete what the removal left unused. A declaration "referenced only where it is declared" (warning): delete it if only the OFF path used it; else say why it stays |
 | `build` | Fix the error your edit caused; don't touch unrelated code. `tsc` skips templates: grep `.html` for each member you removed or renamed |
 | `tests` | A new failure means ON behavior changed: fix the edit, not the test. Known failures (failed at the baseline) only warn. A test listed as no longer running (`unexplained`) must be one you removed on purpose: say why. A changed test file whose tests didn't run: run them yourself and report it |
+| `lint` | Fix what your edit caused. An already-failing lint fails only on new error lines: fix those; other new lines it lists only warn |
+| `coverage` | Tell the user which changed files no command checks; don't add or change commands yourself |
+
+Exit 2 is a usage or config error: read the message. `--skip build,tests,lint,coverage` is fine for a quick check in between; only a full run counts, and the Stop hook won't let you finish on one with `--skip`. After three failed attempts on one check, show the user the findings. Don't run code generators or formatters after the passing verify; if you must, verify again.
+
+## 6. Hand back
+
+1. `flagrm verify <flag> --md` on the final tree (it reuses the passing build, test and lint runs; edit nothing after it): show its output exactly as printed; don't reword it or change its numbers. It must pass: the Stop hook checks it.
+2. **Notes**, 3–5 lines: what you kept on purpose, each remaining warning with its reason, follow-ups in the flag service. If `state` wasn't `on` and nobody confirmed ON, start with "Assumed ON everywhere".
+3. The commit message:
+
+<!-- commit-message:start -->
+**Proposed commit message**, in a code block:
+
+```
+chore: remove <flag> feature flag
 
-Exit 2 is a usage or config error: read the message. `--skip build,tests` is fine for a quick check
-in between; only a full run counts, and the Stop hook won't let you finish on one with `--skip`. After three failed attempts on one check, show the user the findings.
+<one or two sentences: which path stays and what was deleted>
+```
 
-## 6. Report
+- Follow the repository's convention instead when `git log --oneline -10` shows a different one.
+- A ticket in the branch name (`feature/feat-24586`): add it the way the log does (`#24586`, `FEAT-24586`), else `(#24586)` after the subject.
+- Wrap the body at 72 columns.
+<!-- commit-message:end -->
 
-In 3–5 lines: what was removed, what you kept on purpose, and each remaining warning with its
-reason. If `state` wasn't `on` and nobody confirmed ON, start with "Assumed ON everywhere".
-Suggest `/flagrm-verify <flag>` for the overview and commit message. Don't commit.
+Commit only when the user asked (in a batch: their answer at the start).
 
 ## Rules
 
 - Never lift code out of the OFF path into live code.
 - Match the file's formatting; don't refactor unrelated code.
 - Never edit `.flagrm/`. Rerun `flagrm baseline <flag>` only with `--name`, or with `--force` before your first edit (it refuses after).
-- Never `--skip` a failing check, and never change a test's expected value or the build/test commands to pass. If the user changes the config mid-removal (say, to leave out tests that need services), run `flagrm baseline <flag> --accept config` once they confirm.
+- Never `--skip` a failing check, and never change a test's expected value or the build, test or lint commands or `covers` to pass. If the user changes the config mid-removal (say, to leave out tests that need services), run `flagrm baseline <flag> --accept config` once they confirm.
+- `baseline` and `verify` reuse a passing verify's build, test and lint results on the same tree and commands. If the user changed the machine (SDK, Docker, services) since, add `--no-reuse`.

package/skills/flagrm-remove/batch.md

@@ -0,0 +1,38 @@
+# Remove several flags
+
+Run SKILL.md's workflow once per flag, in the order given, one commit per flag.
+Each baseline reuses the previous flag's passing verify (seconds) only if the commit leaves the tree as verified.
+
+## Once, before the first flag
+
+1. SKILL.md step 1 preconditions. Find every flag in `flagrm list --json`; for one that's missing, show the closest names and ask.
+2. One table: flag, `state`, and for any not `on` the environments in `config[]` that change.
+   Ask once: "Remove all of these as ON everywhere?" On a no, drop the flags the user names.
+3. Ask once: "Commit each flag once its verify passes?"
+
+## Per flag
+
+Copy this checklist for each flag and tick it as you go:
+
+```
+<flag>:
+- [ ] baseline (step 2)
+- [ ] every usage found (step 3)
+- [ ] removed (step 4)
+- [ ] verify passes (step 5)
+- [ ] handed back (step 6)
+- [ ] committed
+```
+
+- The ON answer above is step 1's state answer: don't ask again.
+- Commit answer yes: commit with the proposed message, then start the next flag. No: show the message,
+  stop, and continue once the user says it's committed. The next baseline needs the previous removal committed.
+- A flag that needs the user (three failed attempts on one check, an unclear case) pauses the batch.
+  Never start a flag while the previous one is uncommitted.
+- Optional: if you can start subagents, run each flag in its own, one at a time. A subagent sees no
+  conversation history: give it the flag, that it is confirmed ON everywhere, the commit answer, and
+  "follow flagrm-remove's SKILL.md steps 2–6".
+
+## At the end
+
+One table: flag, commit, remaining warnings, kept on purpose.

package/skills/flagrm-verify/SKILL.md

@@ -35,14 +35,20 @@ Output, in this order:
    - follow-ups outside the repo: archive the flag in the flag service
      (LaunchDarkly, Azure App Configuration, ...), remove keys from deployment
      settings and secret stores.
-3. **Proposed commit message**, in a code block:
+3. The commit message:
 
-   ```
-   chore: remove <flag> feature flag
+<!-- commit-message:start -->
+**Proposed commit message**, in a code block:
 
-   <one or two sentences: which path stays and what was deleted>
-   ```
+```
+chore: remove <flag> feature flag
 
-   Follow the repository's convention instead when `git log --oneline -10` shows a different one.
+<one or two sentences: which path stays and what was deleted>
+```
+
+- Follow the repository's convention instead when `git log --oneline -10` shows a different one.
+- A ticket in the branch name (`feature/feat-24586`): add it the way the log does (`#24586`, `FEAT-24586`), else `(#24586)` after the subject.
+- Wrap the body at 72 columns.
+<!-- commit-message:end -->
 
 Never commit, push or open a PR unless asked. Write a PR description only on request, from the same output.