flagrm 0.4.0 → 0.5.0

package/dist/core/stale.js

@@ -0,0 +1,218 @@
+/**
+ * `flagrm stale`: which flags a flag service says are ready to remove from
+ * code. Pure: it takes what the source read, the code names from `flagrm
+ * list`'s inventory, the conditions and the time to count days to, and does
+ * no I/O, so every verdict is reproducible.
+ */
+import { JSON_SCHEMA_VERSION, } from "./types.js";
+import { plural } from "./util.js";
+const DAY_MS = 86_400_000;
+/** Case and separators (`-`, `_`, `.`, spaces) don't matter: `new-checkout` and `NewCheckout` are the same name. */
+export function normalizeName(name) {
+    return name.toLowerCase().replace(/[-_.\s]/g, "");
+}
+/**
+ * The code name each LaunchDarkly key matches: a `map` entry first, then the
+ * exact name, then the normalized one. A normalized name shared by several
+ * code names, or by several keys, matches none of them: it would be a guess.
+ */
+export function matchKeys(keys, codeNames, map) {
+    const result = new Map();
+    const code = new Set(codeNames);
+    const claimed = new Set();
+    for (const key of keys) {
+        const mapped = map[key];
+        if (mapped === undefined)
+            continue;
+        if (code.has(mapped)) {
+            result.set(key, { kind: "matched", codeName: mapped });
+            claimed.add(mapped);
+        }
+        else
+            result.set(key, { kind: "none", reason: `map names "${mapped}", which the code doesn't define or use` });
+    }
+    for (const key of keys) {
+        if (!result.has(key) && code.has(key) && !claimed.has(key)) {
+            result.set(key, { kind: "matched", codeName: key });
+            claimed.add(key);
+        }
+    }
+    const group = (names) => {
+        const groups = new Map();
+        for (const n of names)
+            groups.set(normalizeName(n), [...(groups.get(normalizeName(n)) ?? []), n]);
+        return groups;
+    };
+    const restKeys = keys.filter((k) => !result.has(k));
+    const codeByName = group(codeNames.filter((n) => !claimed.has(n)));
+    const keysByName = group(restKeys);
+    const quoted = (names) => names.map((n) => `"${n}"`).join(", ");
+    for (const key of restKeys) {
+        const name = normalizeName(key);
+        const candidates = codeByName.get(name) ?? [];
+        const rivals = (keysByName.get(name) ?? []).filter((k) => k !== key);
+        if (candidates.length === 0)
+            result.set(key, { kind: "none" });
+        else if (candidates.length > 1) {
+            result.set(key, {
+                kind: "ambiguous",
+                reason: `ambiguous: code names ${quoted(candidates)} all match; add a launchdarkly.map entry`,
+            });
+        }
+        else if (rivals.length) {
+            result.set(key, {
+                kind: "ambiguous",
+                reason: `ambiguous: LaunchDarkly keys ${quoted([key, ...rivals])} all match code name "${candidates[0]}"; add a launchdarkly.map entry`,
+            });
+        }
+        else
+            result.set(key, { kind: "matched", codeName: candidates[0] });
+    }
+    return result;
+}
+export function conditionsOf(config, environments) {
+    return { environments, minDaysOn: config.minDaysOn, temporaryOnly: config.temporaryOnly, tags: config.tags };
+}
+/** Why the flag's own settings (kind, temporary, tags) rule it out, whatever its environments serve. */
+function settingReasons(flag, conditions) {
+    const reasons = [];
+    if (flag.kind !== "boolean")
+        reasons.push(`not a boolean flag (${flag.kind})`);
+    if (conditions.temporaryOnly && !flag.temporary)
+        reasons.push("permanent: not marked temporary in LaunchDarkly");
+    for (const tag of conditions.tags.include)
+        if (!flag.tags.includes(tag))
+            reasons.push(`lacks tag "${tag}"`);
+    for (const tag of conditions.tags.exclude)
+        if (flag.tags.includes(tag))
+            reasons.push(`has excluded tag "${tag}"`);
+    return reasons;
+}
+/**
+ * Whether the flag's change history can decide its verdict, so it is worth
+ * the audit-log requests: it passes every condition but the days, and a code
+ * name matches it.
+ */
+export function needsHistory(flag, config, codeNames) {
+    if (flag.unrecognized || settingReasons(flag, config).length)
+        return false;
+    // A recognized flag has every checked environment.
+    const served = Object.values(flag.environments).map((e) => e.serves);
+    if (!served.length || !served.every((s) => s.kind === "fixed" && s.value === true))
+        return false;
+    const name = normalizeName(config.map[flag.key] ?? flag.key);
+    return codeNames.some((n) => normalizeName(n) === name);
+}
+/** Each checked environment as reported, with whole days since `since`. */
+function environmentsOf(flag, environments, now) {
+    return environments.flatMap((environment) => {
+        const state = flag.environments[environment];
+        if (!state)
+            return [];
+        if (state.serves.kind === "targeted")
+            return [{ environment, serves: "targeted", detail: state.serves.detail }];
+        const days = state.since ? Math.floor((now.getTime() - Date.parse(state.since)) / DAY_MS) : undefined;
+        return [
+            {
+                environment,
+                serves: "fixed",
+                value: state.serves.value,
+                ...(state.since ? { since: state.since, sinceSource: state.sinceSource, days } : {}),
+            },
+        ];
+    });
+}
+function evaluateFlag(flag, match, conditions, now) {
+    const environments = environmentsOf(flag, conditions.environments, now);
+    const base = { key: flag.key, ...(match.kind === "matched" ? { codeName: match.codeName } : {}), environments };
+    if (flag.unrecognized)
+        return { ...base, verdict: "keep", reasons: [flag.unrecognized] };
+    if (match.kind === "none")
+        return { ...base, verdict: "unreferenced", reasons: match.reason ? [match.reason] : [] };
+    if (match.kind === "ambiguous")
+        return { ...base, verdict: "keep", reasons: [match.reason] };
+    const reasons = settingReasons(flag, conditions);
+    for (const env of environments) {
+        if (env.serves === "targeted")
+            reasons.push(`${env.environment}: targeted (${env.detail})`);
+        else if (env.value !== true)
+            reasons.push(`${env.environment}: serves ${JSON.stringify(env.value)}`);
+        else if ((env.days ?? 0) < conditions.minDaysOn) {
+            reasons.push(`${env.environment}: true for only ${plural(env.days ?? 0, "day")} (needs ${conditions.minDaysOn})`);
+        }
+    }
+    return { ...base, verdict: reasons.length ? "keep" : "remove", reasons };
+}
+/** Up to three names closest to `name` (normalized edit distance), for a "did you mean". */
+export function closestNames(name, names) {
+    const target = normalizeName(name);
+    const distance = (a, b) => {
+        let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+        for (let i = 1; i <= a.length; i++) {
+            const next = [i];
+            for (let j = 1; j <= b.length; j++) {
+                next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            }
+            row = next;
+        }
+        return row[b.length];
+    };
+    return [...new Set(names)]
+        .map((n) => ({ n, d: distance(target, normalizeName(n)) }))
+        .sort((a, b) => a.d - b.d || a.n.localeCompare(b.n))
+        .slice(0, 3)
+        .map((x) => x.n);
+}
+/** A name in `only` that neither a LaunchDarkly flag nor a code name matches: a usage error. */
+export class UnknownFlagError extends Error {
+}
+export function evaluateStale(input) {
+    const { read, codeNames, config, now } = input;
+    const conditions = conditionsOf(config, read.environments);
+    const keys = read.flags.map((f) => f.key);
+    const matches = matchKeys(keys, codeNames, config.map);
+    const byKey = new Map(read.flags.map((f) => [f.key, f]));
+    const flags = [];
+    const evaluate = (key) => {
+        if (!flags.some((f) => f.key === key)) {
+            flags.push(evaluateFlag(byKey.get(key), matches.get(key), conditions, now));
+        }
+    };
+    if (!input.only?.length)
+        keys.forEach(evaluate);
+    for (const arg of input.only ?? []) {
+        const name = normalizeName(arg);
+        const hits = keys.filter((k) => {
+            const m = matches.get(k);
+            return k === arg || (m?.kind === "matched" && m.codeName === arg);
+        });
+        const loose = hits.length ? [] : keys.filter((k) => normalizeName(k) === name);
+        if (hits.length || loose.length) {
+            [...hits, ...loose].forEach(evaluate);
+            continue;
+        }
+        const codeName = codeNames.find((n) => n === arg) ?? codeNames.find((n) => normalizeName(n) === name);
+        if (!codeName) {
+            throw new UnknownFlagError(`No LaunchDarkly flag or code name matches "${arg}". Closest: ${closestNames(arg, [...keys, ...codeNames]).join(", ") || "none"}.`);
+        }
+        if (flags.some((f) => f.codeName === codeName))
+            continue;
+        flags.push({
+            codeName,
+            verdict: "keep",
+            reasons: [
+                `no LaunchDarkly flag matches "${codeName}": if it was archived or deleted, the SDK serves the code's fallback value, which may be OFF`,
+            ],
+            environments: [],
+        });
+    }
+    const sortKey = (f) => f.key ?? f.codeName ?? "";
+    flags.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+    return {
+        schemaVersion: JSON_SCHEMA_VERSION,
+        project: input.project,
+        evaluatedAt: now.toISOString(),
+        conditions,
+        flags,
+    };
+}

package/dist/core/test-runner.js

@@ -6,7 +6,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import fg from "fast-glob";
+import { globSync } from "tinyglobby";
 import { readJson, relativePath } from "./util.js";
 /** The test target of the first `angular.json` project that has one. */
 function angularTestTarget(root) {
@@ -22,7 +22,7 @@ function dependencies(root) {
     const pkg = readJson(path.join(root, "package.json"));
     return new Set([...Object.keys(pkg?.dependencies ?? {}), ...Object.keys(pkg?.devDependencies ?? {})]);
 }
-const hasFile = (root, pattern) => fg.sync(pattern, { cwd: root, deep: 1 }).length > 0;
+const hasFile = (root, pattern) => globSync(pattern, { expandDirectories: false, cwd: root, deep: 1 }).length > 0;
 function karma(root, options) {
     const conf = path.resolve(root, typeof options.karmaConfig === "string" ? options.karmaConfig : "karma.conf.js");
     let text;

package/dist/core/types.js

@@ -21,6 +21,8 @@
  * - 8: `lint` runs (`check: "lint"`) and the `lint` and `coverage` checks;
  *   `baseline.json` gains the config's `lint` commands and `git.dirtyHashes`.
  *   Both are optional, so version 6 and 7 files are still read.
+ *
+ * `stale --json` ({@link StaleReport}) was added at 8: a new payload, so no bump.
  */
 export const JSON_SCHEMA_VERSION = 8;
 /** `baseline.json` versions this flagrm reads: 7 and 8 only added optional fields to 6. */

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

@@ -7,7 +7,7 @@
  */
 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))
@@ -200,8 +200,7 @@ export function hasTestNames(results) {
 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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flagrm",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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

@@ -25,7 +25,7 @@ Several flags (`/flagrm-remove A B C`): read [batch.md](batch.md) first; it runs
   Its doctor reports a missing SDK, `cargo` or Docker: show it. For `cargo`/Docker, offer `flagrm scope`; `--write` only on a yes.
 - `flagrm list --json`: find the flag in `flags[]`. Not there: show the closest names and ask.
 - `state` is `off`, `mixed` or `conditional`: name the environments in `config[]` that change and get a yes, or stop.
-  `unconfigured` (set in a flag service): ask if it is ON everywhere. The removal request is not that answer.
+  `unconfigured` (set in a flag service): with `launchdarkly:` in the config, `flagrm stale <flag> --json`; verdict `remove` confirms ON, another verdict: stop and show its `reasons`. No section, or `stale` exits non-zero (show its message): ask if it is ON everywhere. The removal request is not that answer.
 - Read `CLAUDE.md` or `AGENTS.md` if present, for conventions and build commands.
 
 ## 2. Baseline
@@ -80,7 +80,7 @@ Exit 2 is a usage or config error: read the message. `--skip build,tests,lint,co
 ## 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".
+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". End with: optional, for an independent review, run `/flagrm-review <flag>` in a new session.
 3. The commit message:
 
 <!-- commit-message:start -->

package/skills/flagrm-remove/batch.md

@@ -7,7 +7,7 @@ Each baseline reuses the previous flag's passing verify (seconds) only if the co
 
 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.
+   `unconfigured` flags follow SKILL.md's `flagrm stale` rule. Ask once about the rest: "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

package/skills/flagrm-review/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: flagrm-review
+description: >
+  Use when a feature flag removal needs an independent review, when the user asks
+  whether a flag removal kept the right behavior, or runs /flagrm-review <flag>,
+  in a repository with a flagrm.config.yaml.
+---
+
+# Review a flag removal
+
+`flagrm verify` decides whether the removal is done. You judge what it can't: whether
+the code still behaves as it did with the flag ON. You report; you never edit, and your
+findings never change the verify result. Run flagrm as `npx --no-install flagrm`.
+
+## 1. Fresh session only
+
+If you made this removal earlier in this conversation, don't review it: you would only
+check your own reasoning. Tell the user to run `/flagrm-review <flag>` in a new session, and stop.
+
+## 2. Verify
+
+`flagrm verify <flag> --json`
+
+- Exit 0: go to step 3.
+- Exit 1: list each check with `status: "fail"` and its findings, then stop. Don't review, don't fix.
+- Exit 2: show the message and stop. A missing baseline has to come from the code before
+  the removal: never create one on the edited code. Tell the user to start over with
+  `/flagrm-remove` from the pre-removal commit.
+
+## 3. Review the diff
+
+The removal is every file in `changedFiles`, compared with the baseline commit:
+`git diff <baseline.git.sha> -- <file>` (it may already be committed, so not `HEAD`).
+Check each change:
+
+1. **ON path kept**: where the flag was read, the code that stays is what ran with the flag ON.
+2. **Deleted tests**: each one tested only the OFF path or the flag switch, never ON behavior.
+3. **Nothing lifted**: no code from the OFF path moved into live code.
+4. **Nothing unrelated**: no edits beyond the flag and the code only the OFF path used.
+5. **No lost side effects**: unwrapping a check kept every `await`, log, return value and call.
+
+## 4. Report
+
+1. One line: `flagrm verify <flag>: pass`, with the warning count if any.
+2. **Review**: one bullet per finding: `file:line`, what is wrong, and why. No findings:
+   "No problems found."
+
+With findings, ask the user whether to fix them; edit nothing before they answer.
+When nobody can answer (a headless run), only report.

package/skills/flagrm-verify/SKILL.md

@@ -1,54 +0,0 @@
----
-name: flagrm-verify
-description: >
-  Use when a feature flag removal needs checking, when the user asks whether a
-  flag is fully removed or wants the summary or commit message for a flag
-  removal, or runs /flagrm-verify <flag>, in a repository with a flagrm.config.yaml.
----
-
-# Verify a flag removal
-
-`flagrm verify` decides whether the removal passed. You show its overview, add what the CLI
-can't know, and propose a commit message. Run it as `npx --no-install flagrm`.
-
-## 1. Verify
-
-`flagrm verify <flag> --md`
-
-- Exit 0: go to step 2.
-- Exit 1: show the failing checks. If you are in the middle of `/flagrm-remove`,
-  fix them with its rules and verify again; otherwise ask the user whether to fix them now.
-- Exit 2: read the message. A missing baseline has to come from the code before
-  the removal. Never create one on the edited code: that compares the removal
-  with itself. Tell the user to start over with `/flagrm-remove` from the
-  pre-removal commit.
-
-## 2. Hand back
-
-Output, in this order:
-
-1. The markdown from `flagrm verify` exactly as printed. Don't reword it, change
-   its numbers or drop rows.
-2. **Notes** (skip when empty), with no counts of your own:
-   - why each remaining warning is acceptable;
-   - projects whose tests didn't run because the config has no `test` command;
-   - 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. The commit message:
-
-<!-- commit-message:start -->
-**Proposed commit message**, in a code block:
-
-```
-chore: remove <flag> feature flag
-
-<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.