flagrm 0.1.0

package/dist/core/inventory.js

@@ -0,0 +1,118 @@
+/**
+ * `flagrm list`: turn each adapter's discovery candidates into one inventory
+ * entry per flag — its definitions, configured state per environment file,
+ * type, direct reference counts and the projects involved.
+ */
+import path from "node:path";
+import { findMentions } from "./mentions.js";
+import { isTestPath } from "./scan.js";
+import { JSON_SCHEMA_VERSION, } from "./types.js";
+/** Every adapter's discovery candidates, without the ones only tests evaluate. */
+export async function discoverCandidates(projects) {
+    const candidates = [];
+    for (const { adapter, ctx } of projects) {
+        // A literal that only a test passes to an eval method (`isEnabled('DoesNotExist')`) is not a flag.
+        const found = await adapter.discover(ctx);
+        candidates.push(...found.filter((c) => (c.source !== "eval" && c.source !== "attribute") || !isTestPath(path.relative(ctx.root, c.file))));
+    }
+    return candidates;
+}
+/** Discover every flag across the workspace and build the inventory. */
+export async function buildInventory(projects) {
+    const candidates = await discoverCandidates(projects);
+    const entries = new Map();
+    const involved = new Map();
+    for (const c of candidates) {
+        let entry = entries.get(c.flag);
+        if (!entry) {
+            entry = {
+                flag: c.flag,
+                type: "unknown",
+                state: "unconfigured",
+                projects: [],
+                definitions: [],
+                config: [],
+                references: { total: 0, files: 0, tests: 0, byProject: {} },
+            };
+            entries.set(c.flag, entry);
+            involved.set(entry, new Set());
+        }
+        involved.get(entry)?.add(c.project);
+        const location = { project: c.project, file: c.file, line: c.line };
+        if (c.source === "config") {
+            entry.config.push({
+                ...location,
+                environment: c.environment ?? "default",
+                state: c.state ?? "unknown",
+                ...(c.filters ? { filters: c.filters } : {}),
+            });
+        }
+        else if (c.symbol && c.symbolKind) {
+            entry.definitions.push({ kind: c.symbolKind, name: c.symbol, ...location });
+        }
+    }
+    countReferences(projects, [...entries.values()]);
+    const order = projects.map(({ ctx }) => ctx.name);
+    const byLocation = (a, b) => order.indexOf(a.project) - order.indexOf(b.project) || a.file.localeCompare(b.file) || a.line - b.line;
+    for (const entry of entries.values()) {
+        entry.definitions.sort(byLocation);
+        entry.config.sort(byLocation);
+        const names = involved.get(entry) ?? new Set();
+        for (const name of Object.keys(entry.references.byProject))
+            names.add(name);
+        entry.projects = order.filter((name) => names.has(name));
+        Object.assign(entry, summarizeConfig(entry));
+    }
+    return {
+        schemaVersion: JSON_SCHEMA_VERSION,
+        projects: projects.map(({ ctx }) => ({ name: ctx.name, adapter: ctx.project.adapter })),
+        flags: [...entries.values()].sort((a, b) => a.flag.localeCompare(b.flag)),
+        candidates,
+    };
+}
+function summarizeConfig(entry) {
+    const states = new Set(entry.config.map((c) => c.state));
+    if (states.size === 0)
+        return { type: "unknown", state: "unconfigured" };
+    if (states.has("conditional"))
+        return { type: "conditional", state: "conditional" };
+    const type = states.has("unknown") ? "unknown" : "boolean";
+    const state = states.size === 1 && !states.has("unknown") ? entry.config[0].state : "mixed";
+    return { type, state };
+}
+/**
+ * Count each flag's direct references: the flag name as a string literal, or
+ * a definition's qualified name (`FLAGS.newCheckout`). Mentions on
+ * definition and config lines are the declarations themselves, not uses.
+ */
+function countReferences(projects, entries) {
+    const byLiteral = new Map();
+    const byAlias = new Map();
+    const declared = new Set();
+    for (const entry of entries) {
+        byLiteral.set(entry.flag, entry);
+        for (const d of entry.definitions) {
+            byAlias.set(d.name, entry);
+            declared.add(`${d.file}:${d.line}`);
+        }
+        for (const c of entry.config)
+            declared.add(`${c.file}:${c.line}`);
+    }
+    const mentions = findMentions(projects.map(({ ctx }) => ctx), [...byLiteral.keys()], [...byAlias.keys()]);
+    const files = new Map();
+    for (const m of mentions) {
+        const entry = m.kind === "literal" ? byLiteral.get(m.token) : byAlias.get(m.token);
+        if (!entry || declared.has(`${m.file}:${m.line}`))
+            continue;
+        const refs = entry.references;
+        refs.total++;
+        if (m.isTest)
+            refs.tests++;
+        refs.byProject[m.project] = (refs.byProject[m.project] ?? 0) + 1;
+        const seen = files.get(entry) ?? new Set();
+        seen.add(m.file);
+        files.set(entry, seen);
+    }
+    for (const [entry, seen] of files)
+        entry.references.files = seen.size;
+}

package/dist/core/markdown.js

@@ -0,0 +1,55 @@
+/**
+ * `flagrm verify <flag> --md`: a compact markdown overview of a verify result
+ * for the user or a PR. Every fact comes from the report; the agent adds
+ * notes and the commit message around it.
+ */
+import { relativePath } from "./util.js";
+import { shortTestNames } from "./verify/test-results.js";
+const ICON = { pass: "✅", fail: "❌", warn: "⚠️", skipped: "➖" };
+/** How many entries a list shows before summarizing the rest. */
+const MAX_ITEMS = 20;
+function codeList(items) {
+    const shown = items
+        .slice(0, MAX_ITEMS)
+        .map((i) => `\`${i}\``)
+        .join(", ");
+    return items.length > MAX_ITEMS ? `${shown} and ${items.length - MAX_ITEMS} more` : shown;
+}
+function findingLine(root, f) {
+    if (!f.file)
+        return `- ${f.message}`;
+    const rel = relativePath(root, f.file);
+    return `- \`${rel}${f.line ? `:${f.line}` : ""}\` ${f.message}`;
+}
+/** Render a verify report as markdown: status, checks table, changed files, removed and new tests, failures and warnings. */
+export function verifyMarkdown(report, root) {
+    const out = [
+        `### flagrm verify: ${report.flag} ${report.status === "pass" ? "✅ pass" : "❌ fail"}`,
+        "",
+        "| Check | Status | Summary |",
+        "|---|---|---|",
+        ...report.checks.map((c) => `| ${c.id} | ${ICON[c.status]} ${c.status} | ${c.summary.replace(/\|/g, "\\|")} |`),
+    ];
+    const changed = report.changedFiles ?? [];
+    if (changed.length)
+        out.push("", `**Files changed since baseline (${changed.length}):** ${codeList(changed)}`);
+    const removed = report.tests.flatMap((t) => t.removed);
+    if (removed.length) {
+        out.push("", `**Tests that no longer run (${removed.length}):** ${codeList(shortTestNames(removed))}`);
+    }
+    const added = report.tests.flatMap((t) => t.added);
+    if (added.length)
+        out.push("", `**New tests (${added.length}):** ${codeList(shortTestNames(added))}`);
+    for (const [severity, title] of [
+        ["fail", "Failures"],
+        ["warn", "Warnings"],
+    ]) {
+        const items = report.checks.flatMap((c) => c.findings.filter((f) => f.severity === severity));
+        if (items.length === 0)
+            continue;
+        out.push("", `**${title}:**`, ...items.slice(0, MAX_ITEMS).map((f) => findingLine(root, f)));
+        if (items.length > MAX_ITEMS)
+            out.push(`- and ${items.length - MAX_ITEMS} more (see --json)`);
+    }
+    return `${out.join("\n")}\n`;
+}

package/dist/core/mentions.js

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import path from "node:path";
+import { commentMaskFor, commentSyntax, computeLexicalMask, escapeRegExp, isKeyValueConfig, isTestPath, LEX_COMMENT, LEX_STRING, } from "./scan.js";
+import { SourceText } from "./source-text.js";
+import { toLf } from "./text-utils.js";
+/**
+ * Find, in one pass per file, every string literal equal to one of
+ * `literals` and every qualified name in `aliases` (`FLAGS.newCheckout`,
+ * also inside `nameof(...)` or a longer chain). An alias followed by `(` is a
+ * call of something else with the same name, never a use of a constant.
+ * Comments and config (`.json`) files are skipped; with `comments: true`,
+ * aliases inside comments (`<see cref="FeatureFlags.NewCheckout"/>`) are
+ * returned too, marked `inComment`. A file shared by two projects is reported
+ * once, for the first.
+ */
+export function findMentions(projects, literals, aliases, options = {}) {
+    const alternation = (keys, toPattern) => [...new Set(keys)]
+        .sort((a, b) => b.length - a.length)
+        .map(toPattern)
+        .join("|");
+    const parts = [];
+    if (literals.length)
+        parts.push(`(['"\`])(${alternation(literals, escapeRegExp)})\\1`);
+    if (aliases.length) {
+        const alias = alternation(aliases, (name) => name.split(".").map(escapeRegExp).join("\\s*\\.\\s*"));
+        parts.push(`(?<![\\w$])(${alias})(?![\\w$])(?!\\s*\\()`);
+    }
+    if (parts.length === 0)
+        return [];
+    const pattern = new RegExp(parts.join("|"), "g");
+    // Group numbers: literal quote/content are 1/2 when present; the alias group comes last.
+    const literalGroup = literals.length ? 2 : -1;
+    const aliasGroup = literals.length ? 3 : 1;
+    const mentions = [];
+    const seen = new Set();
+    for (const ctx of projects) {
+        for (const file of ctx.files) {
+            if (seen.has(file) || file.endsWith(".json"))
+                continue;
+            seen.add(file);
+            let text;
+            try {
+                text = toLf(fs.readFileSync(file, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            pattern.lastIndex = 0;
+            if (!pattern.test(text))
+                continue;
+            pattern.lastIndex = 0; // matchAll starts from the regex's lastIndex
+            const source = new SourceText(file, text);
+            const mask = commentMaskFor(file, text);
+            const isTest = isTestPath(path.relative(ctx.root, file));
+            for (const m of text.matchAll(pattern)) {
+                const literal = literalGroup > 0 ? m[literalGroup] : undefined;
+                const inComment = mask !== null && mask[m.index] === 0;
+                if (inComment && (!options.comments || literal !== undefined))
+                    continue;
+                mentions.push({
+                    project: ctx.name,
+                    file,
+                    line: source.position(m.index).line,
+                    token: literal ?? m[aliasGroup].replace(/\s+/g, ""),
+                    kind: literal !== undefined ? "literal" : "alias",
+                    isTest,
+                    inComment,
+                    snippet: source.snippet(m.index),
+                });
+            }
+        }
+    }
+    return mentions;
+}
+/** What may come before a key on its line: indentation, a YAML list `- `, `export `, dotted parents (`features.`). */
+const CONFIG_KEY_HEAD = /^[ \t]*(?:-[ \t]+)?(?:export[ \t]+)?(?:[\w-]+\.)*$/;
+/** What follows a key in a key/value file: `:` and whitespace (YAML), or `=` but not `==`. */
+const CONFIG_KEY_TAIL = /^[ \t]*(?::(?=\s|$)|=(?!=))/;
+/**
+ * Find every whole-word use of `names` (calls included, unlike aliases in
+ * {@link findMentions}), skipping string literals. Uses in comments are
+ * returned marked `inComment`. Config (`.json`) files are skipped. A file
+ * shared by two projects is reported once, for the first.
+ *
+ * `configPaths` are .NET configuration paths (`FeatureManagement__NewCheckout`
+ * environment variables, `FeatureManagement:NewCheckout` keys), matched in the
+ * same pass: ignoring case, as .NET configuration does, inside strings and
+ * `launchSettings.json` too, and before a deeper `__Section`. Other `.json`
+ * files are never read.
+ */
+export function findIdentifiers(projects, names, configPaths = []) {
+    const alternation = (list, toPattern) => [...new Set(list)]
+        .sort((a, b) => b.length - a.length)
+        .map(toPattern)
+        .join("|");
+    const branches = [
+        names.length ? `(?<name>${alternation(names, escapeRegExp)})(?![\\w$])` : "",
+        configPaths.length ? `(?<path>${alternation(configPaths, caseInsensitivePattern)})(?!(?!__)[\\w$])` : "",
+    ].filter(Boolean);
+    if (branches.length === 0)
+        return [];
+    const pattern = new RegExp(`(?<![\\w$])(?:${branches.join("|")})`, "g");
+    const hits = [];
+    const seen = new Set();
+    for (const ctx of projects) {
+        for (const file of ctx.files) {
+            const json = file.endsWith(".json");
+            // Of the `.json` files, only launchSettings.json sets environment variables.
+            if (seen.has(file) || (json && (configPaths.length === 0 || path.basename(file) !== "launchSettings.json")))
+                continue;
+            seen.add(file);
+            let text;
+            try {
+                text = toLf(fs.readFileSync(file, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            pattern.lastIndex = 0;
+            if (!pattern.test(text))
+                continue;
+            pattern.lastIndex = 0;
+            const keyValue = isKeyValueConfig(file);
+            const syntax = commentSyntax(file);
+            const mask = syntax ? computeLexicalMask(text, syntax) : null;
+            const source = new SourceText(file, text);
+            for (const m of text.matchAll(pattern)) {
+                const isPath = m.groups?.path !== undefined;
+                const cls = mask ? mask[m.index] : 0;
+                if (!isPath && (json || cls === LEX_STRING))
+                    continue;
+                const end = m.index + m[0].length;
+                hits.push({
+                    project: ctx.name,
+                    file,
+                    line: source.position(m.index).line,
+                    token: m[0],
+                    inComment: cls === LEX_COMMENT,
+                    isConfigKey: keyValue &&
+                        CONFIG_KEY_HEAD.test(text.slice(text.lastIndexOf("\n", m.index - 1) + 1, m.index)) &&
+                        CONFIG_KEY_TAIL.test(text.slice(end, end + 80)),
+                });
+            }
+        }
+    }
+    return hits;
+}
+/** `name` as a regex source that matches it in any letter case (`[fF][eE]...`). */
+function caseInsensitivePattern(name) {
+    return [...name]
+        .map((c) => (c.toLowerCase() === c.toUpperCase() ? escapeRegExp(c) : `[${c.toLowerCase()}${c.toUpperCase()}]`))
+        .join("");
+}

package/dist/core/package.js

@@ -0,0 +1,17 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Root of the installed flagrm package (holds package.json and skills/); this file is src/core or dist/core. */
+export function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+/** The flagrm version from package.json, or `0.0.0` when it can't be read. */
+export function packageVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot(), "package.json"), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}

package/dist/core/registry.js

@@ -0,0 +1,29 @@
+import { angularAdapter } from "../adapters/angular/index.js";
+import { dotnetAdapter } from "../adapters/dotnet/index.js";
+import { genericAdapter } from "../adapters/generic/index.js";
+import { listProjectFiles } from "./scan.js";
+const ADAPTERS = {
+    angular: angularAdapter,
+    dotnet: dotnetAdapter,
+    generic: genericAdapter,
+};
+export function getAdapter(id) {
+    return ADAPTERS[id];
+}
+export function createProjectContext(project, config) {
+    const adapter = getAdapter(project.adapter);
+    return {
+        name: project.name,
+        root: project.path,
+        project,
+        config,
+        files: listProjectFiles(project.path, project.globs ?? adapter.defaultGlobs, config),
+    };
+}
+/** Every configured project paired with its adapter, in config order. Throws on an unavailable adapter. */
+export function resolveProjects(config) {
+    return config.projects.map((project) => ({
+        adapter: getAdapter(project.adapter),
+        ctx: createProjectContext(project, config),
+    }));
+}

package/dist/core/report.js

@@ -0,0 +1,135 @@
+import pc from "picocolors";
+import { plural, relativePath } from "./util.js";
+import { shortTestNames } from "./verify/test-results.js";
+/** A path relative to the working directory, with `/` separators on every platform. */
+function rel(file) {
+    return relativePath(process.cwd(), file) || file;
+}
+export function printInventory(report) {
+    const { flags, projects } = report;
+    if (flags.length === 0) {
+        console.log(pc.dim("No feature flags found."));
+        return;
+    }
+    console.log(pc.bold(`${plural(flags.length, "flag")} in ${plural(projects.length, "project")}`) +
+        pc.dim(` (${projects.map((p) => p.name).join(", ")})\n`));
+    const pad = (values) => {
+        const width = Math.max(0, ...values.map((v) => v.length));
+        return (v) => v.padEnd(width);
+    };
+    for (const entry of flags) {
+        const { references: refs } = entry;
+        const byProject = Object.entries(refs.byProject)
+            .map(([name, n]) => `${name} ${n}`)
+            .join(", ");
+        const usage = refs.total === 0
+            ? pc.yellow("no references")
+            : `${plural(refs.total, "ref")} in ${plural(refs.files, "file")}` +
+                (refs.tests ? ` (${refs.tests} in tests)` : "") +
+                pc.dim(` · ${byProject}`);
+        console.log(`${pc.bold(entry.flag)}  ${pc.dim(`${entry.type} · ${stateLabel(entry.state)} ·`)} ${usage}`);
+        const project = pad([...entry.definitions, ...entry.config].map((x) => x.project));
+        const kind = pad(entry.definitions.map((d) => d.kind));
+        const name = pad(entry.definitions.map((d) => d.name));
+        for (const d of entry.definitions) {
+            console.log(`  ${pc.dim("defined")}  ${pc.dim(project(d.project))}  ${pc.dim(kind(d.kind))}  ${name(d.name)}  ${pc.cyan(`${rel(d.file)}:${d.line}`)}`);
+        }
+        const env = pad(entry.config.map((c) => c.environment));
+        const state = pad(entry.config.map((c) => configLabel(c.state, c.filters)));
+        for (const c of entry.config) {
+            console.log(`  ${pc.dim("config ")}  ${pc.dim(project(c.project))}  ${pc.dim(env(c.environment))}  ${state(configLabel(c.state, c.filters))}  ${pc.cyan(`${rel(c.file)}:${c.line}`)}`);
+        }
+        console.log("");
+    }
+    console.log(pc.dim("Reference counts are direct uses of the flag's literal and definitions, not reads through wrappers."));
+}
+function stateLabel(state) {
+    return state === "unconfigured" ? "not configured" : state;
+}
+function configLabel(state, filters) {
+    return filters?.length ? `${state} (${filters.join(", ")})` : state;
+}
+export function printBaseline(baseline, file) {
+    const { git, checks } = baseline;
+    const state = git.sha
+        ? `git ${git.sha.slice(0, 7)}${git.dirty ? ", uncommitted changes" : ""}`
+        : "not a git repository";
+    console.log(`${pc.green(`Baseline for ${baseline.flag} written to ${rel(file)}`)} ${pc.dim(`(${state})`)}`);
+    for (const c of checks ?? []) {
+        const status = c.exitCode === 0 ? pc.green("pass") : pc.red(`fail (exit ${c.exitCode})`);
+        console.log(`  ${c.project} ${c.check}: ${status} ${pc.dim(`${c.command} — ${Math.round(c.durationMs / 100) / 10}s`)}`);
+    }
+    if (baseline.names.length) {
+        const names = baseline.names.map((n) => (n.kind === "literal" ? n.name : `${n.name} (${n.kind})`));
+        console.log(`  names: ${pc.dim(names.join(", "))}`);
+    }
+}
+const CHECK_STYLE = {
+    pass: { icon: "✓", color: pc.green },
+    fail: { icon: "✗", color: pc.red },
+    warn: { icon: "!", color: pc.yellow },
+    skipped: { icon: "–", color: pc.dim },
+};
+/** How many findings to print per check before summarizing the rest. */
+const MAX_FINDINGS = 15;
+export function printVerifyReport(report, file) {
+    const failed = report.checks.filter((c) => c.status === "fail").length;
+    const warned = report.checks.filter((c) => c.status === "warn").length;
+    const verdict = report.status === "pass" ? pc.green(pc.bold("PASS")) : pc.red(pc.bold("FAIL"));
+    const tally = [failed && `${failed} failed`, warned && `${warned} with warnings`].filter(Boolean).join(", ");
+    console.log(`\n${pc.bold(`flagrm verify ${report.flag}`)} — ${verdict}${tally ? pc.dim(` (${tally})`) : ""}\n`);
+    const width = Math.max(...report.checks.map((c) => c.id.length));
+    for (const check of report.checks) {
+        const { icon, color } = CHECK_STYLE[check.status];
+        console.log(`  ${color(icon)} ${check.id.padEnd(width)}  ${check.status === "pass" ? pc.dim(check.summary) : check.summary}`);
+        if (check.status === "pass" || check.status === "skipped")
+            continue;
+        const shown = check.findings.slice(0, MAX_FINDINGS);
+        for (const f of shown) {
+            const where = f.file ? `${pc.cyan(`${rel(f.file)}${f.line ? `:${f.line}` : ""}`)} ` : "";
+            const project = f.project ? pc.dim(`[${f.project}] `) : "";
+            const text = f.severity === "info" ? pc.dim(f.message) : f.message;
+            console.log(`      ${project}${where}${text}`);
+        }
+        if (check.findings.length > shown.length) {
+            console.log(pc.dim(`      … ${check.findings.length - shown.length} more (see --json)`));
+        }
+        if (check.id === "tests") {
+            const removed = shortTestNames(report.tests.flatMap((t) => t.removed));
+            for (const name of removed.slice(0, MAX_FINDINGS))
+                console.log(pc.dim(`      no longer runs: ${name}`));
+            if (removed.length > MAX_FINDINGS)
+                console.log(pc.dim(`      … ${removed.length - MAX_FINDINGS} more (see --md)`));
+        }
+    }
+    if (report.strict && warned)
+        console.log(pc.dim("\n  --strict: warnings count as failures."));
+    console.log(pc.dim(`\nResult written to ${rel(file)}.`));
+}
+const STEP_STYLE = {
+    created: pc.green,
+    updated: pc.green,
+    unchanged: pc.dim,
+    skipped: pc.dim,
+};
+/** One line per `init`/`update` step: `created   .claude/skills/flagrm-remove`. */
+export function printSteps(steps) {
+    for (const s of steps) {
+        console.log(STEP_STYLE[s.status](`${s.status.padEnd(9)} ${s.path}${s.note ? ` — ${s.note}` : ""}`));
+    }
+}
+const DOCTOR_STYLE = {
+    ok: { icon: "✓", color: pc.green },
+    warn: { icon: "!", color: pc.yellow },
+    fail: { icon: "✗", color: pc.red },
+};
+/** One line per doctor check, then the overall result. */
+export function printDoctor(report) {
+    for (const c of report.checks) {
+        const { icon, color } = DOCTOR_STYLE[c.status];
+        console.log(`  ${color(icon)} ${c.status === "ok" ? pc.dim(c.message) : c.message}`);
+        for (const line of c.details ?? [])
+            console.log(pc.dim(`      ${line}`));
+    }
+    console.log(report.status === "ok" ? pc.green("\nflagrm doctor: ok") : pc.red("\nflagrm doctor: problems found"));
+}