flagrm 0.1.0

package/dist/core/verify/leftovers.js

@@ -0,0 +1,74 @@
+/**
+ * The `leftovers` check: no recorded name of the flag (`baseline.names`) is
+ * left anywhere in the projects. Code and config fail; comments warn.
+ */
+import { FEATURE_MANAGEMENT_SECTION } from "../discover.js";
+import { discoverCandidates } from "../inventory.js";
+import { findIdentifiers, findMentions } from "../mentions.js";
+import { checkResult, plural } from "./context.js";
+const STILL = {
+    config: "still configured",
+    attribute: "still gated by attribute",
+    eval: "still evaluated",
+    constant: "still defined",
+    "object-key": "still defined",
+};
+export async function leftoversCheck(v) {
+    const byKind = (kind) => v.baseline.names.filter((n) => n.kind === kind).map((n) => n.name);
+    const literals = byKind("literal");
+    const contexts = v.projects.map((p) => p.ctx);
+    const findings = [];
+    const seen = new Set();
+    const add = (f) => {
+        const key = `${f.file}:${f.line}:${f.severity}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        findings.push(f);
+    };
+    for (const m of findMentions(contexts, literals, byKind("alias"), { comments: true })) {
+        add({
+            severity: m.inComment ? "warn" : "fail",
+            project: m.project,
+            file: m.file,
+            line: m.line,
+            message: `${m.inComment ? "comment mentions" : "still references"} ${m.token}`,
+        });
+    }
+    const hits = findIdentifiers(contexts, [...byKind("wrapper"), ...literals], 
+    // `FeatureManagement__Flag=true` configures the flag through an environment variable (.env, docker-compose);
+    // `GetValue<bool>("FeatureManagement:Flag")` reads it by its section-qualified key.
+    literals.flatMap((name) => [`${FEATURE_MANAGEMENT_SECTION}__${name}`, `${FEATURE_MANAGEMENT_SECTION}:${name}`]));
+    for (const hit of hits) {
+        const isLiteral = literals.includes(hit.token);
+        // A bare literal name in code is an identifier that merely shares the name; only its comments and
+        // config keys (`new-checkout: true`) count.
+        if (isLiteral && !hit.inComment && !hit.isConfigKey)
+            continue;
+        add({
+            severity: hit.inComment ? "warn" : "fail",
+            project: hit.project,
+            file: hit.file,
+            line: hit.line,
+            message: `${hit.inComment ? "comment mentions" : "still references"} ${hit.token}`,
+        });
+    }
+    // Discovery only: the inventory's reference counts would scan every file again for every flag.
+    for (const c of (await discoverCandidates(v.projects)).filter((c) => c.flag === v.flag)) {
+        add({
+            severity: "fail",
+            project: c.project,
+            file: c.file,
+            line: c.line,
+            message: `${STILL[c.source]} ${c.symbol ?? c.flag}`,
+        });
+    }
+    const fails = findings.filter((f) => f.severity === "fail").length;
+    const warns = findings.length - fails;
+    const summary = findings.length === 0
+        ? "no recorded name left in code or config"
+        : [fails && `${plural(fails, "reference")} left`, warns && `${plural(warns, "comment")} naming the flag`]
+            .filter(Boolean)
+            .join(", ");
+    return checkResult("leftovers", summary, findings);
+}

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

@@ -0,0 +1,153 @@
+/**
+ * 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.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import fg from "fast-glob";
+function attributes(tag) {
+    const out = {};
+    for (const m of tag.matchAll(/([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g))
+        out[m[1]] = decode(m[2] ?? m[3]);
+    return out;
+}
+function decode(text) {
+    return text
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+        .replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCodePoint(Number.parseInt(n, 16)))
+        .replace(/&amp;/g, "&");
+}
+function empty() {
+    return { total: 0, passed: 0, failed: 0, skipped: 0, names: [], failedNames: [], files: [] };
+}
+function record(results, name, outcome) {
+    results.total++;
+    results[outcome]++;
+    results.names.push(name);
+    if (outcome === "failed")
+        results.failedNames.push(name);
+}
+/** One `<UnitTestResult>` per executed test or data row. */
+export function parseTrx(xml) {
+    const results = empty();
+    for (const m of xml.matchAll(/<UnitTestResult\b[^>]*>/g)) {
+        const attrs = attributes(m[0]);
+        const outcome = (attrs.outcome ?? "").toLowerCase();
+        const kind = outcome === "passed" ? "passed" : outcome === "failed" || outcome === "error" ? "failed" : "skipped";
+        record(results, attrs.testName ?? "", kind);
+    }
+    return results;
+}
+/** Joins a JUnit `classname` and test `name` (Jest's separator; test titles may contain dots). */
+export const JUNIT_SEPARATOR = " › ";
+/**
+ * A test name short enough to read in an overview. TRX names lose their
+ * namespace and data-row arguments (`Ns.JobTests.Run(sutProvider: …)` becomes
+ * `JobTests.Run(…)`); a JUnit name whose class repeats the title (Jest's
+ * default) is shown once. Names are only shortened for display, never compared.
+ */
+export function shortTestName(name) {
+    const sep = name.indexOf(JUNIT_SEPARATOR);
+    if (sep >= 0) {
+        const cls = name.slice(0, sep);
+        const title = name.slice(sep + JUNIT_SEPARATOR.length);
+        if (cls.endsWith(title))
+            return cls;
+        if (title.startsWith(cls))
+            return title;
+        return name;
+    }
+    const paren = name.indexOf("(");
+    const qualified = paren >= 0 ? name.slice(0, paren) : name;
+    return qualified.split(".").slice(-2).join(".") + (paren >= 0 ? "(…)" : "");
+}
+/** Short names, each once, with a count when data rows collapse into one (`Run(…) ×3`). */
+export function shortTestNames(names) {
+    const counts = new Map();
+    for (const name of names) {
+        const short = shortTestName(name);
+        counts.set(short, (counts.get(short) ?? 0) + 1);
+    }
+    return [...counts].map(([short, n]) => (n > 1 ? `${short} ×${n}` : short));
+}
+/**
+ * The name a test is compared by: a TRX data row without its arguments, since
+ * AutoFixture-style attributes put random values in them on every run. JUnit
+ * names are kept whole (a test title may contain parentheses).
+ */
+function testKey(name) {
+    if (name.includes(JUNIT_SEPARATOR))
+        return name;
+    const m = /^([\w.`+<>,[\]]+)\(.*\)$/s.exec(name);
+    return m ? m[1] : name;
+}
+/**
+ * The tests in `before` that no longer run and the ones in `after` that are new.
+ * Data rows are counted per test, so dropping the OFF row of a theory still
+ * shows up; among a test's rows, the ones whose exact name is gone are reported.
+ */
+export function diffTestNames(before, after) {
+    const onlyIn = (from, other) => {
+        const exact = new Set(other);
+        const left = new Map();
+        for (const name of exact)
+            left.set(testKey(name), (left.get(testKey(name)) ?? 0) + 1);
+        const rows = new Map();
+        for (const name of new Set(from))
+            rows.set(testKey(name), [...(rows.get(testKey(name)) ?? []), name]);
+        const out = [];
+        for (const [key, names] of rows) {
+            const extra = names.length - (left.get(key) ?? 0);
+            if (extra > 0)
+                out.push(...[...names].sort((a, b) => Number(exact.has(a)) - Number(exact.has(b))).slice(0, extra));
+        }
+        return out;
+    };
+    return { removed: onlyIn(before, after), added: onlyIn(after, before) };
+}
+/** One `<testcase>` per test; a `<failure>`/`<error>` child fails it, `<skipped>` skips it. */
+export function parseJUnit(xml) {
+    const results = empty();
+    for (const m of xml.matchAll(/<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g)) {
+        const attrs = attributes(m[1]);
+        const name = [attrs.classname, attrs.name].filter(Boolean).join(JUNIT_SEPARATOR);
+        const body = m[2] ?? "";
+        const kind = /<(?:failure|error)\b/.test(body) ? "failed" : /<skipped\b/.test(body) ? "skipped" : "passed";
+        record(results, name, kind);
+    }
+    return results;
+}
+/**
+ * Merge every result file matching `pattern` (an absolute path or glob)
+ * modified at or after `since` — test runners keep older result files around.
+ * Undefined when no such file exists.
+ */
+export function collectTestResults(pattern, since) {
+    // 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 })
+        .filter((file) => fs.statSync(file).mtimeMs >= cutoff)
+        .sort();
+    if (files.length === 0)
+        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);
+        merged.total += parsed.total;
+        merged.passed += parsed.passed;
+        merged.failed += parsed.failed;
+        merged.skipped += parsed.skipped;
+        merged.names.push(...parsed.names);
+        merged.failedNames.push(...parsed.failedNames);
+        merged.files.push(file);
+    }
+    return merged;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "flagrm",
+  "version": "0.1.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": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dino-cosic/flagrm.git"
+  },
+  "homepage": "https://github.com/dino-cosic/flagrm#readme",
+  "bugs": {
+    "url": "https://github.com/dino-cosic/flagrm/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "flagrm": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "ci": "npm run typecheck && npm run lint && npm run build && npm test",
+    "prepublishOnly": "npm run ci"
+  },
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "flag-removal",
+    "ai-agent",
+    "claude-code",
+    "copilot",
+    "codex",
+    "agent-skills",
+    "angular",
+    "dotnet",
+    "cli"
+  ],
+  "dependencies": {
+    "commander": "^13.1.0",
+    "fast-glob": "^3.3.3",
+    "picocolors": "^1.1.1",
+    "typescript": "^5.7.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.10",
+    "@types/node": "^22.13.0",
+    "tsx": "^4.19.0",
+    "vitest": "^3.0.0"
+  }
+}

package/skills/flagrm-remove/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: flagrm-remove
+description: >
+  Use when the user asks to remove, retire, deprecate or clean up a feature flag
+  or feature toggle, says a flag is fully rolled out, or runs /flagrm-remove <flag>,
+  in a repository with a flagrm.config.yaml. Works for Angular, .NET and other
+  stacks: IFeatureManager, [FeatureGate], appsettings FeatureManagement,
+  LaunchDarkly-style calls, flags objects, enums, signals, *ngIf/@if templates.
+---
+
+# Remove a feature flag
+
+**The flag is permanently ON.** Keep the ON path, delete the OFF path and
+everything only it used. Behavior with the flag ON must not change.
+
+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).
+
+## 1. Preconditions
+
+- `git status --porcelain` must print nothing. Otherwise ask the user to commit or stash.
+- No `flagrm.config.yaml`: run `flagrm init` and fill in project paths and build/test commands with the user.
+- `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.
+- Read `CLAUDE.md` or `AGENTS.md` if present, for conventions and build commands.
+
+## 2. Baseline
+
+`flagrm baseline <flag> --json` records the git commit, build and test results and the flag's
+`names[]`. A `checks[]` entry with a non-zero `exitCode` means the code is already broken: stop.
+
+## 3. Find every usage
+
+- Grep for each name in `names[]`: code, templates, config and tests.
+- Follow how the value travels: a method or property returning the flag, a field
+  or local holding it, a parameter it's passed as, a DI-registered bool. Record
+  each so `verify` checks it too, then grep for it:
+  `flagrm baseline <flag> --name IsNewCheckoutEnabledAsync --kind wrapper`
+  (`--kind alias` for a qualified constant like `Flags.NewCheckout`).
+
+## 4. Remove
+
+Read `patterns.md` in this skill's directory when a case is unclear.
+
+- Condition: keep the ON branch, delete the OFF branch, drop the check.
+  `a && flag` → `a`, `a || !flag` → `a`. Never touch other flags.
+- Wrapper: replace each call with `true` and simplify, then delete the wrapper, its interface member and DI registration.
+- Passed as a parameter: pass `true` and simplify the callee. Once no caller
+  passes anything else, remove the parameter and the argument at every caller.
+- Code only the OFF path used (methods, classes, fields, constructor parameters,
+  DI registrations, imports/usings, files): delete it. Keep what anything else uses.
+- Definition and config: remove the constant, enum member or flags-object key,
+  and the key in every environment's config file. Remove a section left empty.
+  Keep a key the service sends to other apps (a known-flags list behind a config endpoint): they'd read OFF.
+- Tests: delete tests of the OFF path. In the others, remove the flag setup
+  (mocks, spies, overrides) and drop the flag from the test name. A test
+  parameterized over ON/OFF keeps only the ON case.
+- Keep the flag system itself (the flag service or client and its generic methods), public API
+  of a library package, and anything that also defines other flags. Mention them in your report.
+
+## 5. Verify until it passes
+
+`flagrm verify <flag> --json`. Fix every check with `status: "fail"`, run it again.
+
+| Check | Fix |
+|---|---|
+| `leftovers` | Remove each reference listed. A comment is a warning: reword or delete it |
+| `dead-code` | Delete what the removal left unused |
+| `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 failure means ON behavior changed: fix the edit, not the test. Tests that no longer run must be ones you deleted on purpose. A changed test file whose tests didn't run: run them yourself and report it |
+
+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.
+
+## 6. Report
+
+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.
+
+## 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/`. Never run `flagrm baseline <flag>` again without `--name`.
+- Never `--skip` a failing check, and never change a test's expected value to pass.

package/skills/flagrm-remove/patterns.md

@@ -0,0 +1,96 @@
+# Flag removal patterns
+
+The flag is always ON: keep the ON path, delete the OFF path.
+
+## C# / .NET
+
+**Fall-through return.** The code after an `if` that returns is the OFF path.
+
+```csharp
+// before
+if (await _featureManager.IsEnabledAsync(FeatureFlags.NewCheckout))
+    return await PlaceOrderAsync(cart);
+return PlaceOrderLegacy(cart);
+// after
+return await PlaceOrderAsync(cart);
+```
+
+**Negated guard.** The block only runs when OFF: delete it.
+
+```csharp
+if (!await checkoutFeatures.IsNewCheckoutEnabledAsync()) { return Legacy(); }  // delete
+```
+
+**Wrapper.** `Task<bool> IsNewCheckoutEnabledAsync()` is the flag under another
+name: record it with `--kind wrapper`, replace each call with `true`, then
+delete the member, its interface member, the interface and class when nothing
+is left, and their DI registration. Test mocks of it (`Setup(x => x.IsNewCheckoutEnabledAsync())`) go too.
+
+**DI toggle.** Keep the ON registration.
+
+```csharp
+// before
+if (config.GetValue<bool>("FeatureManagement:NewPayments"))
+    services.AddScoped<IPaymentService, NewPaymentService>();
+else
+    services.AddScoped<IPaymentService, LegacyPaymentService>();
+// after
+services.AddScoped<IPaymentService, NewPaymentService>();
+```
+
+**Switch.** `flag switch { true => A(), false => B() }` → `A()`.
+
+**Middleware.** `app.UseWhen(ctx => flag, b => b.UseMiddleware<M>())` →
+`app.UseMiddleware<M>()` at the same position in the pipeline.
+
+**`[FeatureGate]`.** Remove the attribute. If another action only served the
+disabled case (404, redirect), delete it too.
+
+**Config.** Remove the key from `appsettings*.json` in every environment, and a
+`FeatureManagement` section left empty. Keys outside the repo (Key Vault, App
+Service settings, Helm values) go in your report as follow-ups.
+
+## Angular / TypeScript
+
+**Templates.** `@if (newCheckout()) { A } @else { B }` → `A`. An element with
+`*ngIf="!newCheckout()"` is deleted; `*ngIf="newCheckout()"` loses the directive
+(an `<ng-container>` left with no directive is unwrapped). A binding such as
+`[disabled]="!newCheckout()"` is `false` when ON: remove it.
+
+**Signals and Observables.** `newCheckout = this.flags.watch(FLAGS.newCheckout)`
+is a wrapper: remove the field and every read. `flag$ | async` and
+`toSignal(getFlag$())` are the same: remove the stream, `AsyncPipe` and `NgIf`
+when the template no longer needs them.
+
+**Standalone imports.** Remove `imports: [...]` entries (components, `NgIf`,
+`AsyncPipe`) the template no longer uses.
+
+**Routes.** A route guarded with `canMatch: [() => !isEnabled(...)]` only
+served the OFF case: delete it. A positive guard loses the guard.
+
+**Tests.** `spyOn(flags, 'isEnabled').withArgs(FLAGS.newCheckout).and.returnValue(true)`
+is setup: delete it and keep the test. A test returning `false`, or calling
+`flags.override(FLAGS.newCheckout, false)`, tests the OFF path: delete it.
+`TestBed` providers only the OFF path needed go too.
+
+## Any stack
+
+**Flag passed as a parameter.**
+
+```ts
+// before
+function price(cart: Cart, useEngine: boolean) { return useEngine ? engine(cart) : legacy(cart); }
+price(cart, flags.isEnabled('NewCheckout'));
+// after
+function price(cart: Cart) { return engine(cart); }
+price(cart);
+```
+
+Pass `true` first, simplify, then remove the parameter only when every caller
+passes `true`. A caller that passes something else keeps it.
+
+**Stored in a field or local.** `const useNew = isEnabled(...)` is a wrapper:
+record it, replace each read with `true`, then delete it.
+
+**Two flags.** `if (flagA && flagB)` → `if (flagB)` when removing `flagA`.
+Never remove or change the other flag.

package/skills/flagrm-verify/SKILL.md

@@ -0,0 +1,48 @@
+---
+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. **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.
+
+Never commit, push or open a PR unless asked. Write a PR description only on request, from the same output.