flagrm 0.4.1 → 0.5.0

package/dist/core/sources/launchdarkly.js

@@ -0,0 +1,331 @@
+/**
+ * Reads a LaunchDarkly project through the REST API (GET only): its
+ * environments, every non-archived flag with full targeting, and, for the
+ * flags that could be removed, the audit log to date the last targeting change.
+ * `fetch` and `sleep` are injectable so tests never touch the network or wait.
+ */
+import { SourceError } from "./types.js";
+export const LD_API_VERSION = "20240415";
+const TIMEOUT_MS = 30_000;
+const MAX_RETRIES = 5;
+const MAX_WAIT_MS = 60_000;
+const PAGE_SIZE = 100;
+/** Environments requested per flags listing: kept small, since each adds full targeting to every flag. */
+const ENVIRONMENTS_PER_LISTING = 3;
+/** The audit log returns at most 20 entries per page. */
+const AUDIT_PAGE_SIZE = 20;
+const AUDIT_PAGES = 5;
+/**
+ * Audit-log actions that don't change what an environment serves. Any other
+ * action, including one LaunchDarkly adds later, resets `since`: an unknown
+ * action can then only shorten the time a flag counts as ON, never lengthen it.
+ */
+export const NON_TARGETING_ACTIONS = new Set([
+    "updateName",
+    "updateDescription",
+    "updateTags",
+    "updateTemporary",
+    "updateMaintainer",
+    "updateDeprecated",
+    "updateIncludeInSnippet",
+    "updateClientSideFlagAvailability",
+    "updateFlagCustomProperties",
+    "updateFlagLinks",
+    "updateTrackEvents",
+    "updateTrackEventsFallthrough",
+    "updateFlagSalt",
+    "createApprovalRequest",
+    "reviewApprovalRequest",
+    "deleteApprovalRequest",
+    "updateApprovalRequest",
+    "createTriggers",
+    "updateTriggers",
+    "deleteTriggers",
+]);
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const iso = (ms) => new Date(ms).toISOString();
+export class LaunchDarklySource {
+    config;
+    options;
+    fetch;
+    sleep;
+    now;
+    constructor(config, options) {
+        this.config = config;
+        this.options = options;
+        this.fetch = options.fetch ?? globalThis.fetch;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.now = options.now ?? Date.now;
+    }
+    async read(wantsHistory) {
+        const environments = await this.environments();
+        const flags = await this.flags(environments);
+        for (const { flag, raw } of flags) {
+            if (flag.unrecognized)
+                continue;
+            const history = wantsHistory(flag);
+            for (const [env, state] of Object.entries(flag.environments)) {
+                if (state.serves.kind !== "fixed")
+                    continue;
+                const lastModified = raw[env].lastModified;
+                const audit = history ? await this.lastTargetingChange(flag.key, env) : undefined;
+                state.since = iso(audit ?? lastModified);
+                state.sinceSource = audit === undefined ? "lastModified" : "audit";
+            }
+        }
+        return { environments, flags: flags.map((f) => f.flag) };
+    }
+    /** The checked environments: the configured ones, which must exist, or all of the project's. */
+    async environments() {
+        const project = encodeURIComponent(this.config.project);
+        const keys = [];
+        const environmentsUrl = `/api/v2/projects/${project}/environments?limit=${PAGE_SIZE}`;
+        for await (const item of this.pages(environmentsUrl, this.projectNotFound())) {
+            if (typeof item.key === "string")
+                keys.push(item.key);
+        }
+        const wanted = this.config.environments;
+        if (!wanted)
+            return keys;
+        const unknown = wanted.filter((e) => !keys.includes(e));
+        if (unknown.length) {
+            throw new Error(`launchdarkly.environments: ${unknown.map((e) => `"${e}"`).join(", ")} not in LaunchDarkly project ` +
+                `"${this.config.project}". Its environments: ${keys.join(", ") || "none"}.`);
+        }
+        return wanted;
+    }
+    /**
+     * Every non-archived flag with what each environment serves; `raw` keeps each environment's JSON.
+     * The listing leaves archived flags out unless asked for them (`filter=state:archived`), so no filter is sent.
+     */
+    async flags(environments) {
+        const project = encodeURIComponent(this.config.project);
+        const byKey = new Map();
+        for (let i = 0; i < environments.length; i += ENVIRONMENTS_PER_LISTING) {
+            const batch = environments.slice(i, i + ENVIRONMENTS_PER_LISTING);
+            const envParams = batch.map((e) => `&env=${encodeURIComponent(e)}`).join("");
+            const flagsUrl = `/api/v2/flags/${project}?summary=0&limit=${PAGE_SIZE}${envParams}`;
+            for await (const item of this.pages(flagsUrl, this.projectNotFound())) {
+                const key = typeof item.key === "string" ? item.key : undefined;
+                if (!key)
+                    continue;
+                const entry = byKey.get(key) ?? { item, envs: {} };
+                if (isObject(item.environments))
+                    Object.assign(entry.envs, item.environments);
+                byKey.set(key, entry);
+            }
+        }
+        return [...byKey.values()].map(({ item, envs }) => ({ flag: parseFlag(item, envs, environments), raw: envs }));
+    }
+    /** Epoch ms of the latest audit entry for the flag in `env` that may have changed targeting; undefined when none. */
+    async lastTargetingChange(flagKey, env) {
+        const spec = `proj/${this.config.project}:env/${env}:flag/${flagKey}`;
+        let before;
+        for (let page = 0; page < AUDIT_PAGES; page++) {
+            const query = `spec=${encodeURIComponent(spec)}&limit=${AUDIT_PAGE_SIZE}${before ? `&before=${before}` : ""}`;
+            const body = await this.get(`/api/v2/auditlog?${query}`);
+            const items = Array.isArray(body.items) ? body.items.filter(isObject) : [];
+            const dated = items.filter((i) => typeof i.date === "number");
+            // The log lists newest first, but take the latest targeting entry of the page rather than rely on it.
+            const changes = dated.filter(changesTargeting).map((i) => i.date);
+            if (changes.length)
+                return Math.max(...changes);
+            if (dated.length < AUDIT_PAGE_SIZE)
+                return undefined;
+            before = Math.min(...dated.map((i) => i.date));
+        }
+        return undefined;
+    }
+    /** Each item of a paginated listing, following `_links.next`. */
+    async *pages(first, notFound) {
+        for (let next = first; next;) {
+            const body = await this.get(next, notFound);
+            if (!Array.isArray(body.items))
+                throw new SourceError(`LaunchDarkly returned no items list for GET ${next}`);
+            yield* body.items.filter(isObject);
+            const links = isObject(body._links) && isObject(body._links.next) ? body._links.next : undefined;
+            next = typeof links?.href === "string" ? links.href : undefined;
+        }
+    }
+    /**
+     * GET `target` as JSON, retrying rate limits; every failure is a {@link SourceError}, a 404 with `notFound`
+     * as its message when given. `target` is a path rooted at `baseUrl`, or a `_links` URL on the same origin.
+     */
+    async get(target, notFound) {
+        const url = this.resolve(target);
+        const endpoint = new URL(url).pathname;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetch(url, {
+                    method: "GET",
+                    headers: { Authorization: this.options.token, "LD-API-Version": LD_API_VERSION, Accept: "application/json" },
+                    signal: AbortSignal.timeout(TIMEOUT_MS),
+                });
+            }
+            catch (err) {
+                throw new SourceError(this.redact(networkMessage(err, endpoint)));
+            }
+            if (res.status === 429 && attempt < MAX_RETRIES) {
+                await this.sleep(this.retryWait(res.headers));
+                continue;
+            }
+            if (res.ok) {
+                try {
+                    const body = await res.json();
+                    if (isObject(body))
+                        return body;
+                }
+                catch {
+                    // reported below
+                }
+                throw new SourceError(`LaunchDarkly returned a response that isn't a JSON object for GET ${endpoint}`);
+            }
+            const message = res.status === 404 && notFound ? `${notFound} (404) at GET ${endpoint}` : undefined;
+            throw new SourceError(this.redact(message ?? this.statusMessage(res.status, endpoint)));
+        }
+    }
+    /**
+     * The URL for a path (`/api/v2/...`, appended to `baseUrl`) or an absolute `_links` URL. An absolute URL
+     * must be on `baseUrl`'s origin: the token is sent with the request, so it never goes to another host.
+     */
+    resolve(target) {
+        if (target.startsWith("/"))
+            return `${this.config.baseUrl}${target}`;
+        let url;
+        try {
+            url = new URL(target);
+        }
+        catch {
+            throw new SourceError(`LaunchDarkly returned a link flagrm can't follow: ${target}`);
+        }
+        if (url.origin !== new URL(this.config.baseUrl).origin) {
+            throw new SourceError(`LaunchDarkly returned a link to another host (${url.origin}); not following it`);
+        }
+        return url.href;
+    }
+    projectNotFound() {
+        return `LaunchDarkly project "${this.config.project}" not found`;
+    }
+    statusMessage(status, endpoint) {
+        const { project, tokenEnv } = this.config;
+        if (status === 401)
+            return `LaunchDarkly rejected the token in ${tokenEnv} (401) for GET ${endpoint}`;
+        if (status === 403) {
+            return `The token in ${tokenEnv} may not read LaunchDarkly project "${project}" (403) for GET ${endpoint}`;
+        }
+        if (status === 404)
+            return `LaunchDarkly found nothing (404) at GET ${endpoint}`;
+        if (status === 429)
+            return `LaunchDarkly kept rate-limiting (429) after ${MAX_RETRIES} retries for GET ${endpoint}`;
+        return `LaunchDarkly answered ${status} for GET ${endpoint}`;
+    }
+    /** Milliseconds to wait before retrying a 429: the longest the headers ask for, at most a minute. */
+    retryWait(headers) {
+        const waits = [];
+        for (const name of ["X-Ratelimit-Reset", "X-Ratelimit-Auth-Token-Reset"]) {
+            const reset = Number(headers.get(name));
+            if (headers.get(name) && Number.isFinite(reset))
+                waits.push(reset - this.now());
+        }
+        const retryAfter = Number(headers.get("Retry-After"));
+        if (headers.get("Retry-After") && Number.isFinite(retryAfter))
+            waits.push(retryAfter * 1000);
+        const wait = waits.length ? Math.max(...waits) : 1000;
+        return Math.min(MAX_WAIT_MS, Math.max(0, wait));
+    }
+    /** Belt and braces: no message may carry the token, whatever an error echoes back. */
+    redact(message) {
+        const { token } = this.options;
+        return token ? message.split(token).join("***") : message;
+    }
+}
+function networkMessage(err, endpoint) {
+    const e = err;
+    if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+        return `LaunchDarkly didn't answer within ${TIMEOUT_MS / 1000} s for GET ${endpoint}`;
+    }
+    const cause = e?.cause?.code ?? e?.cause?.message ?? e?.message ?? String(err);
+    return `Couldn't reach LaunchDarkly (${cause}) for GET ${endpoint}`;
+}
+/** Whether an audit entry may have changed what the environment serves. */
+function changesTargeting(entry) {
+    const accesses = Array.isArray(entry.accesses) ? entry.accesses.filter(isObject) : [];
+    // An entry without readable actions counts as a change: unknown can only shorten the ON time.
+    if (accesses.length === 0)
+        return true;
+    return accesses.some((a) => typeof a.action !== "string" || !NON_TARGETING_ACTIONS.has(a.action));
+}
+const nonEmpty = (v) => Array.isArray(v) && v.length > 0;
+/**
+ * What one environment serves, from its targeting: `fixed` only when every
+ * context gets one variation. Undefined when the data isn't what flagrm expects.
+ */
+export function servedValue(env, variations) {
+    const variation = (index) => typeof index === "number" && Number.isInteger(index) && index >= 0 && index < variations.length
+        ? { kind: "fixed", value: variations[index].value }
+        : undefined;
+    for (const field of ["targets", "contextTargets", "rules", "prerequisites"]) {
+        if (env[field] !== undefined && env[field] !== null && !Array.isArray(env[field]))
+            return undefined;
+    }
+    if (typeof env.on !== "boolean")
+        return undefined;
+    if (!env.on) {
+        if (env.offVariation === undefined || env.offVariation === null) {
+            return { kind: "targeted", detail: "targeting off without an off variation (the code's fallback is served)" };
+        }
+        return variation(env.offVariation);
+    }
+    const count = (field) => (Array.isArray(env[field]) ? env[field].length : 0);
+    if (nonEmpty(env.prerequisites))
+        return { kind: "targeted", detail: `${count("prerequisites")} prerequisite(s)` };
+    if (nonEmpty(env.rules))
+        return { kind: "targeted", detail: `${count("rules")} rule(s)` };
+    if (nonEmpty(env.targets) || nonEmpty(env.contextTargets))
+        return { kind: "targeted", detail: "individual targets" };
+    if (!isObject(env.fallthrough))
+        return undefined;
+    if (env.fallthrough.rollout !== undefined && env.fallthrough.rollout !== null) {
+        return { kind: "targeted", detail: "a percentage rollout" };
+    }
+    return variation(env.fallthrough.variation);
+}
+/** A {@link SourceFlag} from one flags-listing item; `unrecognized` says what didn't parse. */
+export function parseFlag(item, envs, environments) {
+    const key = String(item.key);
+    const flag = {
+        key,
+        name: typeof item.name === "string" ? item.name : key,
+        kind: typeof item.kind === "string" ? item.kind : "unknown",
+        temporary: item.temporary === true,
+        tags: Array.isArray(item.tags) ? item.tags.filter((t) => typeof t === "string") : [],
+        creationDate: typeof item.creationDate === "number" ? iso(item.creationDate) : "",
+        environments: {},
+    };
+    const problems = [];
+    if (typeof item.kind !== "string")
+        problems.push("no kind");
+    if (typeof item.temporary !== "boolean")
+        problems.push("no temporary marker");
+    if (!Array.isArray(item.variations) || !item.variations.every(isObject))
+        problems.push("no variations");
+    for (const env of environments) {
+        const raw = envs[env];
+        if (!isObject(raw)) {
+            problems.push(`no targeting for environment "${env}"`);
+            continue;
+        }
+        const serves = Array.isArray(item.variations) ? servedValue(raw, item.variations) : undefined;
+        if (!serves)
+            problems.push(`unreadable targeting in "${env}"`);
+        else if (serves.kind === "fixed" && typeof raw.lastModified !== "number") {
+            problems.push(`no lastModified in "${env}"`);
+        }
+        else
+            flag.environments[env] = { serves };
+    }
+    if (problems.length)
+        flag.unrecognized = `unrecognized LaunchDarkly data: ${problems.join(", ")}`;
+    return flag;
+}

package/dist/core/sources/types.js

@@ -0,0 +1,13 @@
+/**
+ * A flag service flagrm reads flags from, for `flagrm stale`. Read-only: a
+ * source never writes to the service. LaunchDarkly is the only one today;
+ * another service is a new file implementing {@link FlagSource}.
+ */
+/**
+ * The service couldn't be asked: unreachable, timed out, rejected the token,
+ * unknown project, rate limit retries used up. `flagrm stale` exits 3 on it.
+ * Messages name the endpoint, never the token.
+ */
+export class SourceError extends Error {
+    name = "SourceError";
+}

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/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/package.json

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

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.