urtext 0.1.0

package/dist/analyze/effects.d.ts

@@ -0,0 +1,15 @@
+import type { Analyzer, EffectKind } from "../types.js";
+export interface EffectSite {
+    kind: EffectKind;
+    line: number;
+    excerpt: string;
+}
+/** Effect sites in a file, in source order. Syntactic — no type checker. */
+export declare function detectEffects(path: string, text: string): EffectSite[];
+/**
+ * Reports effect kinds that appear in a file's after-state but not its
+ * before-state, and vice versa. A file that already made network calls and
+ * makes different ones now is not a finding; a file that never did and now
+ * does, is.
+ */
+export declare const effectsAnalyzer: Analyzer;

package/dist/analyze/effects.js

@@ -0,0 +1,255 @@
+import ts from "typescript";
+import { isTypeScriptFile } from "../extract/symbols.js";
+import { makeFact, MAX_EVIDENCE } from "./fact.js";
+/**
+ * Detection below is syntactic and keyed on identifier names, plus a pass
+ * that resolves import bindings against `MODULE_EFFECTS` by specifier. The
+ * identifier tables alone remain scope-blind: a shadowing local (`const db =
+ * new Map()`) still produces a false-positive `database` effect, because
+ * that is a name coincidence no amount of import resolution can rule out.
+ * But imports from a module in `MODULE_EFFECTS` are now resolved by
+ * specifier regardless of the local name they bind to — aliased
+ * (`readFile as rf`), namespace (`* as fsp`), and default imports all
+ * resolve correctly. What is still unresolved: an import from a module not
+ * listed in `MODULE_EFFECTS`, and a binding introduced by re-export
+ * (`export { readFile } from ...`) or dynamic `import()` rather than a
+ * static import declaration.
+ *
+ * This binding lookup is itself name-based and scope-blind, the same way
+ * the identifier tables are: it is a single flat map consulted against
+ * every identifier in the file, with no tracking of scope or redeclaration.
+ * A local declaration that reuses an imported binding's name — a function
+ * parameter named `rf` in a file that also imports `readFile as rf` — is
+ * misattributed as a filesystem effect in exactly the same way `db` is
+ * misattributed above. Resolving imports by specifier closes the
+ * false-negative gap (an aliased import used to be invisible); it does not
+ * close the false-positive gap (a shadowing name is still indistinguishable
+ * from the binding it shadows).
+ */
+/** Bare global calls that are effectful. */
+const GLOBAL_CALLS = {
+    fetch: "network",
+};
+/** `object.member` patterns, matched on the object name. */
+const OBJECT_EFFECTS = {
+    fs: "filesystem",
+    fsPromises: "filesystem",
+    axios: "network",
+    http: "network",
+    https: "network",
+    child_process: "process",
+    db: "database",
+    prisma: "database",
+    knex: "database",
+    pool: "database",
+};
+/** Fully-qualified `object.member` patterns that beat the object-name table. */
+const QUALIFIED_EFFECTS = {
+    "process.env": "env",
+    "process.exit": "process",
+    "Date.now": "timing",
+    "Math.random": "timing",
+};
+function qualifiedName(node) {
+    const left = node.expression;
+    if (!ts.isIdentifier(left))
+        return null;
+    return `${left.text}.${node.name.text}`;
+}
+/**
+ * Module specifiers whose imports carry an effect. Matched after stripping a
+ * `node:` prefix, so "node:fs/promises" and "fs/promises" are one entry.
+ * This is specifier-based and purely syntactic: it needs no type checker,
+ * and it closes the aliased-import blind spot the identifier tables have.
+ *
+ * The lookup is exact-match after stripping `node:`, not prefix-match —
+ * `fs/promises` needs its own entry precisely because `fs` would not
+ * cover it.
+ */
+const MODULE_EFFECTS = {
+    fs: "filesystem",
+    "fs/promises": "filesystem",
+    http: "network",
+    https: "network",
+    http2: "network",
+    net: "network",
+    dns: "network",
+    undici: "network",
+    axios: "network",
+    "node-fetch": "network",
+    child_process: "process",
+    cluster: "process",
+    worker_threads: "process",
+    pg: "database",
+    mysql: "database",
+    mysql2: "database",
+    sqlite3: "database",
+    "better-sqlite3": "database",
+    mongodb: "database",
+    ioredis: "database",
+    redis: "database",
+};
+function moduleEffect(specifier) {
+    const s = specifier.replace(/^node:/, "");
+    return MODULE_EFFECTS[s];
+}
+/** Local identifier → effect, from this file's import declarations. */
+function importBindings(sf) {
+    const out = new Map();
+    for (const stmt of sf.statements) {
+        if (!ts.isImportDeclaration(stmt))
+            continue;
+        if (!ts.isStringLiteral(stmt.moduleSpecifier))
+            continue;
+        const effect = moduleEffect(stmt.moduleSpecifier.text);
+        if (!effect)
+            continue;
+        const clause = stmt.importClause;
+        if (!clause || clause.isTypeOnly)
+            continue;
+        // `import http from "node:http"`
+        if (clause.name)
+            out.set(clause.name.text, effect);
+        const bindings = clause.namedBindings;
+        if (!bindings)
+            continue;
+        if (ts.isNamespaceImport(bindings)) {
+            // `import * as fsp from "node:fs/promises"`
+            out.set(bindings.name.text, effect);
+        }
+        else {
+            // `import { readFile as rf } from "fs/promises"` — the local name is
+            // `bindings.elements[i].name`, which is what appears at call sites.
+            // `import { type readFile } from ...` is inert in valid code (a
+            // type-only binding cannot appear in value position), so skip it too.
+            for (const el of bindings.elements) {
+                if (el.isTypeOnly)
+                    continue;
+                out.set(el.name.text, effect);
+            }
+        }
+    }
+    return out;
+}
+/** Effect sites in a file, in source order. Syntactic — no type checker. */
+export function detectEffects(path, text) {
+    if (!isTypeScriptFile(path))
+        return [];
+    const sf = ts.createSourceFile(path, text, ts.ScriptTarget.ES2022, true, path.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const lines = text.split("\n");
+    const sites = [];
+    const bindings = importBindings(sf);
+    const push = (node, kind) => {
+        const line = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+        sites.push({ kind, line, excerpt: (lines[line - 1] ?? "").trim() });
+    };
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node)) {
+            const q = qualifiedName(node);
+            if (q && QUALIFIED_EFFECTS[q]) {
+                push(node, QUALIFIED_EFFECTS[q]);
+            }
+            else if (ts.isIdentifier(node.expression)) {
+                const bound = bindings.get(node.expression.text);
+                if (bound) {
+                    push(node, bound);
+                }
+                else if (OBJECT_EFFECTS[node.expression.text]) {
+                    push(node, OBJECT_EFFECTS[node.expression.text]);
+                }
+            }
+        }
+        else if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+            const bound = bindings.get(node.expression.text);
+            if (bound) {
+                push(node, bound);
+            }
+            else if (GLOBAL_CALLS[node.expression.text]) {
+                push(node, GLOBAL_CALLS[node.expression.text]);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sf, visit);
+    return sites;
+}
+function kindsOf(sites) {
+    return new Set(sites.map((s) => s.kind));
+}
+function toEvidence(path, sites, kind, side) {
+    return sites
+        .filter((s) => s.kind === kind)
+        .slice(0, MAX_EVIDENCE)
+        .map((s) => ({ file: path, line: s.line, excerpt: s.excerpt, side }));
+}
+/**
+ * Builds one Fact for a single (path, kind) pair, or null if there is
+ * nothing to show. `path` is the file the sites and evidence both come
+ * from — the after-path for additions, the before-path for removals — and
+ * `side` says which revision those line numbers count in. `Fact.file`/
+ * `Fact.line` are derived from `evidence[0]` by `makeFact`, so they agree
+ * with the evidence even for a renamed file.
+ */
+function buildFact(factKind, path, effectKind, sites) {
+    const side = factKind === "effect_removed" ? "before" : "after";
+    const matching = sites.filter((s) => s.kind === effectKind);
+    const evidence = toEvidence(path, matching, effectKind, side);
+    // A fact that cannot show its evidence must not ship. Unreachable today
+    // because `evidence` is derived from the same non-empty `matching` list,
+    // but returning null rather than calling makeFact (which throws on empty
+    // evidence) keeps a future refactor's mistake a silent no-op here rather
+    // than a crashed review.
+    if (evidence.length === 0)
+        return null;
+    return makeFact({
+        id: `${factKind}:${path}:${effectKind}`,
+        kind: factKind,
+        // True total, not the (possibly capped) evidence count — this number is
+        // shown to users, so it must not understate how many sites there are.
+        detail: { effect: effectKind, sites: matching.length },
+        evidence,
+    });
+}
+/**
+ * Reports effect kinds that appear in a file's after-state but not its
+ * before-state, and vice versa. A file that already made network calls and
+ * makes different ones now is not a finding; a file that never did and now
+ * does, is.
+ */
+export const effectsAnalyzer = async (changeset, ctx) => {
+    const facts = [];
+    for (const file of changeset.files) {
+        if (!isTypeScriptFile(file.path))
+            continue;
+        const beforePath = file.previousPath ?? file.path;
+        const beforeText = file.status === "added" ? null : await ctx.readAt(ctx.range.from, beforePath);
+        const afterText = file.status === "deleted" ? null : await ctx.readAt(ctx.range.to, file.path);
+        // A file that still exists but whose after-state could not be read tells
+        // us nothing: the content is missing, not the effects. Treating that as
+        // "the effects are gone" is how a wrong range or a wrong working
+        // directory turns into a confident `verified` claim that a guard was
+        // removed. Say nothing instead — silence is recoverable, a false
+        // verified finding is not.
+        if (afterText === null && file.status !== "deleted")
+            continue;
+        const beforeSites = beforeText ? detectEffects(beforePath, beforeText) : [];
+        const afterSites = afterText ? detectEffects(file.path, afterText) : [];
+        const before = kindsOf(beforeSites);
+        const after = kindsOf(afterSites);
+        for (const kind of after) {
+            if (before.has(kind))
+                continue;
+            const fact = buildFact("effect_added", file.path, kind, afterSites);
+            if (fact)
+                facts.push(fact);
+        }
+        for (const kind of before) {
+            if (after.has(kind))
+                continue;
+            const fact = buildFact("effect_removed", beforePath, kind, beforeSites);
+            if (fact)
+                facts.push(fact);
+        }
+    }
+    return facts;
+};

package/dist/analyze/fact.d.ts

@@ -0,0 +1,42 @@
+import type { EvidenceRef, Fact, FactKind } from "../types.js";
+/**
+ * How many EvidenceRefs a fact carries at most. Only the excerpted evidence
+ * list is capped — counted quantities (`detail.sites`,
+ * `detail.references`) stay exact, so the prose never understates a change.
+ * Shared by the analyzers that sample evidence (effects, blast-radius) so
+ * the cap cannot drift between them; `test/comment-contract.test.ts`
+ * derives part of its forbidden set from it, so comments name it rather
+ * than restating its value.
+ */
+export declare const MAX_EVIDENCE = 5;
+/**
+ * Everything a Fact needs that is not derivable from its evidence. `file`
+ * and `line` are deliberately absent: they are not inputs.
+ */
+export interface FactInput {
+    id: string;
+    kind: FactKind;
+    qualifiedSymbol?: string;
+    detail: Record<string, unknown>;
+    evidence: EvidenceRef[];
+}
+/**
+ * The only way an *emitted* Fact is built: every analyzer constructs its
+ * facts through this function. (`minPossibleAnalyzerScore` in
+ * `../score/index.ts` builds throwaway synthetic Facts directly, but those
+ * are scored and discarded, never emitted.)
+ *
+ * Two rules the spec treats as load-bearing — every fact carries evidence,
+ * and `Fact.file`/`Fact.line` name the same place as `evidence[0]` — were
+ * previously defended by convention and per-analyzer review. They were
+ * broken three times anyway, each time producing a `verified` finding that
+ * pointed somewhere the reader could not check. Deriving the location from
+ * the evidence instead of accepting it as a parameter makes the broken
+ * version unrepresentable: there is no argument to get wrong.
+ *
+ * Empty evidence throws rather than returning null. An analyzer that
+ * reaches this point with nothing to show has a bug in the caller, and a
+ * silent drop would hide it; analyzers that legitimately have nothing to
+ * report must not call this at all.
+ */
+export declare function makeFact(input: FactInput): Fact;

package/dist/analyze/fact.js

@@ -0,0 +1,46 @@
+/**
+ * How many EvidenceRefs a fact carries at most. Only the excerpted evidence
+ * list is capped — counted quantities (`detail.sites`,
+ * `detail.references`) stay exact, so the prose never understates a change.
+ * Shared by the analyzers that sample evidence (effects, blast-radius) so
+ * the cap cannot drift between them; `test/comment-contract.test.ts`
+ * derives part of its forbidden set from it, so comments name it rather
+ * than restating its value.
+ */
+export const MAX_EVIDENCE = 5;
+/**
+ * The only way an *emitted* Fact is built: every analyzer constructs its
+ * facts through this function. (`minPossibleAnalyzerScore` in
+ * `../score/index.ts` builds throwaway synthetic Facts directly, but those
+ * are scored and discarded, never emitted.)
+ *
+ * Two rules the spec treats as load-bearing — every fact carries evidence,
+ * and `Fact.file`/`Fact.line` name the same place as `evidence[0]` — were
+ * previously defended by convention and per-analyzer review. They were
+ * broken three times anyway, each time producing a `verified` finding that
+ * pointed somewhere the reader could not check. Deriving the location from
+ * the evidence instead of accepting it as a parameter makes the broken
+ * version unrepresentable: there is no argument to get wrong.
+ *
+ * Empty evidence throws rather than returning null. An analyzer that
+ * reaches this point with nothing to show has a bug in the caller, and a
+ * silent drop would hide it; analyzers that legitimately have nothing to
+ * report must not call this at all.
+ */
+export function makeFact(input) {
+    const anchor = input.evidence[0];
+    if (!anchor) {
+        throw new Error(`makeFact(${input.kind}, id=${input.id}): a fact must carry at least one EvidenceRef`);
+    }
+    return {
+        id: input.id,
+        kind: input.kind,
+        file: anchor.file,
+        line: anchor.line,
+        ...(input.qualifiedSymbol === undefined
+            ? {}
+            : { qualifiedSymbol: input.qualifiedSymbol }),
+        detail: input.detail,
+        evidence: input.evidence,
+    };
+}

package/dist/analyze/guards.d.ts

@@ -0,0 +1,70 @@
+import type { Analyzer } from "../types.js";
+export interface GuardSite {
+    /**
+     * Dotted path to the scope the guard runs in — `Worker.run`, `handlers.run`,
+     * `N.check`, or a class for a guard in its static initializer block — or
+     * `MODULE_OWNER` for top-level code. Built by pushing `framesFor`, which is
+     * also how `mapSymbols` builds `ChangedSymbol.qualifiedName`: the same
+     * declaration has to come out with the same path from both, because
+     * `foldReach` matches facts across analyzers on it. When it did not — this
+     * side framed no object literal and rooted no unnamed scope — a guard removed
+     * from `handlers.run` was reported against an untouched top-level `run`, and
+     * a guard genuinely removed from that export was cancelled out by one added
+     * to the method and never reported at all. `test/extract/scope.test.ts` asks
+     * both sides about the same declaration and compares.
+     *
+     * Also not the innermost name alone: the whole file's guards are matched
+     * before against after on this string, and two classes in one file may each
+     * declare `render`. See `Fact.qualifiedSymbol`, which this becomes.
+     */
+    qualifiedOwner: string;
+    /** Kind plus normalised condition text — the identity used for matching. */
+    signature: string;
+    line: number;
+    excerpt: string;
+}
+/**
+ * Guard-shaped constructs, attributed to the symbol containing them.
+ * Matching is by (qualifiedOwner, signature), so moving a guard within a
+ * function is not a removal; what makes a removal reportable is decided by
+ * `guardsAnalyzer` below, which requires the *count* of that guard kind in
+ * that symbol to have gone down.
+ */
+export declare function collectGuards(path: string, text: string): GuardSite[];
+/**
+ * Reports guards that a symbol has genuinely lost.
+ *
+ * Two conditions, both required. First, the exact guard — kind plus
+ * normalised condition text — must be unmatched on the after side, matched
+ * as a multiset so that deleting one of two identical guards still leaves
+ * one unmatched. Second, the *count* of that guard kind in that symbol must
+ * have gone down.
+ *
+ * The count condition is what separates a removal from an edit. Guard
+ * identity includes the condition text, so rewording a condition, renaming
+ * a variable it reads, or narrowing an `else if` all make the old signature
+ * absent — and on identity alone each presented as a pure removal, with no
+ * compensating "added" fact and the highest weight in the report. Three of
+ * three guard findings on this branch's own diff were exactly that. A
+ * symbol that still runs as many `if` guards as it did before has not lost
+ * one, whatever the conditions now say.
+ *
+ * The cost is a real removal that coincides with a new guard of the same kind
+ * under the same owner path: the counts balance and nothing is reported. "The
+ * same symbol" understated it — an owner path is not always one declaration.
+ * Two anonymous functions in one scope share `<anonymous>`, and two bindings in
+ * different unnamed scopes share a `<local>` root (see `byQualifiedName` in
+ * `../extract/symbols.ts`, which records the same trade from the other end), so
+ * a guard *moved* between two sibling callbacks in one function cancels out and
+ * this analyzer says nothing. Common enough to matter: this codebase's own
+ * `runAnalyzers` and `parseClaims` each hold more than one guard under a
+ * single `<anonymous>` path.
+ *
+ * That is still the intended trade — silence is recoverable, a confident wrong
+ * `verified` finding is not — but it is paid more often than "the same symbol"
+ * suggests.
+ *
+ * A symbol that disappeared entirely is not reported either — its deletion
+ * is the finding, and the guards analyzer would only add noise.
+ */
+export declare const guardsAnalyzer: Analyzer;

package/dist/analyze/guards.js

@@ -0,0 +1,211 @@
+import ts from "typescript";
+import { framesFor, MODULE_OWNER, qualifyOwner } from "../extract/scope.js";
+import { isTypeScriptFile } from "../extract/symbols.js";
+import { makeFact } from "./fact.js";
+function normalise(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * Guard-shaped constructs, attributed to the symbol containing them.
+ * Matching is by (qualifiedOwner, signature), so moving a guard within a
+ * function is not a removal; what makes a removal reportable is decided by
+ * `guardsAnalyzer` below, which requires the *count* of that guard kind in
+ * that symbol to have gone down.
+ */
+export function collectGuards(path, text) {
+    if (!isTypeScriptFile(path))
+        return [];
+    const sf = ts.createSourceFile(path, text, ts.ScriptTarget.ES2022, true, path.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const lines = text.split("\n");
+    const out = [];
+    const owner = [];
+    const push = (node, signature) => {
+        const line = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+        out.push({
+            qualifiedOwner: qualifyOwner(owner),
+            signature,
+            line,
+            excerpt: (lines[line - 1] ?? "").trim(),
+        });
+    };
+    const visit = (node) => {
+        const pushed = framesFor(node);
+        owner.push(...pushed);
+        if (ts.isIfStatement(node)) {
+            push(node, `if:${normalise(node.expression.getText(sf))}`);
+        }
+        else if (ts.isThrowStatement(node)) {
+            push(node, `throw:${normalise(node.expression.getText(sf))}`);
+        }
+        else if (ts.isReturnStatement(node) &&
+            node.parent &&
+            ts.isBlock(node.parent) &&
+            node.parent.parent &&
+            ts.isIfStatement(node.parent.parent)) {
+            // An early return inside a conditional — the classic guard clause.
+            push(node, `return:${normalise(node.getText(sf))}`);
+        }
+        ts.forEachChild(node, visit);
+        owner.length -= pushed.length;
+    };
+    ts.forEachChild(sf, visit);
+    return out;
+}
+/** Exact identity: this guard, with this condition text, in this symbol. */
+function key(g) {
+    return `${g.qualifiedOwner}|${g.signature}`;
+}
+/** Coarse identity: an if / throw / return guard in this symbol, any text. */
+function kindKey(g) {
+    return `${g.qualifiedOwner}|${g.signature.split(":")[0]}`;
+}
+function countBy(guards, of) {
+    const counts = new Map();
+    for (const g of guards)
+        counts.set(of(g), (counts.get(of(g)) ?? 0) + 1);
+    return counts;
+}
+/**
+ * Reports guards that a symbol has genuinely lost.
+ *
+ * Two conditions, both required. First, the exact guard — kind plus
+ * normalised condition text — must be unmatched on the after side, matched
+ * as a multiset so that deleting one of two identical guards still leaves
+ * one unmatched. Second, the *count* of that guard kind in that symbol must
+ * have gone down.
+ *
+ * The count condition is what separates a removal from an edit. Guard
+ * identity includes the condition text, so rewording a condition, renaming
+ * a variable it reads, or narrowing an `else if` all make the old signature
+ * absent — and on identity alone each presented as a pure removal, with no
+ * compensating "added" fact and the highest weight in the report. Three of
+ * three guard findings on this branch's own diff were exactly that. A
+ * symbol that still runs as many `if` guards as it did before has not lost
+ * one, whatever the conditions now say.
+ *
+ * The cost is a real removal that coincides with a new guard of the same kind
+ * under the same owner path: the counts balance and nothing is reported. "The
+ * same symbol" understated it — an owner path is not always one declaration.
+ * Two anonymous functions in one scope share `<anonymous>`, and two bindings in
+ * different unnamed scopes share a `<local>` root (see `byQualifiedName` in
+ * `../extract/symbols.ts`, which records the same trade from the other end), so
+ * a guard *moved* between two sibling callbacks in one function cancels out and
+ * this analyzer says nothing. Common enough to matter: this codebase's own
+ * `runAnalyzers` and `parseClaims` each hold more than one guard under a
+ * single `<anonymous>` path.
+ *
+ * That is still the intended trade — silence is recoverable, a confident wrong
+ * `verified` finding is not — but it is paid more often than "the same symbol"
+ * suggests.
+ *
+ * A symbol that disappeared entirely is not reported either — its deletion
+ * is the finding, and the guards analyzer would only add noise.
+ */
+export const guardsAnalyzer = async (changeset, ctx) => {
+    const facts = [];
+    for (const file of changeset.files) {
+        if (!isTypeScriptFile(file.path))
+            continue;
+        if (file.status === "added" || file.status === "deleted")
+            continue;
+        const beforePath = file.previousPath ?? file.path;
+        const beforeText = await ctx.readAt(ctx.range.from, beforePath);
+        const afterText = await ctx.readAt(ctx.range.to, file.path);
+        // An unreadable side is an error, never evidence that a guard vanished.
+        if (beforeText === null || afterText === null)
+            continue;
+        const before = collectGuards(beforePath, beforeText);
+        const after = collectGuards(file.path, afterText);
+        // Consumed as the before-side guards are matched against it, so two
+        // identical before-guards cannot both be "matched" by a single
+        // surviving one.
+        const unmatched = countBy(after, key);
+        // How many removals of each (symbol, kind) the counts can justify.
+        const beforeKinds = countBy(before, kindKey);
+        const afterKinds = countBy(after, kindKey);
+        const budget = new Map();
+        for (const [k, n] of beforeKinds) {
+            budget.set(k, n - (afterKinds.get(k) ?? 0));
+        }
+        const survivingSymbols = new Set(after.map((g) => g.qualifiedOwner));
+        // Symbols with no guards at all after the change still count as
+        // surviving if they still exist in the file. This must recognise every
+        // owner path `frameNameOf` can ever attribute a guard to (including arrow
+        // functions and function expressions bound to a name), qualified exactly
+        // as `collectGuards` qualifies it — otherwise a symbol whose *last* guard
+        // was just removed looks, from here, like a symbol that was deleted
+        // outright, and the removal is wrongly suppressed as "vanished symbol"
+        // noise instead of reported.
+        for (const s of collectDeclaredOwners(file.path, afterText)) {
+            survivingSymbols.add(s);
+        }
+        // "<module>" is not a declaration that can be deleted — it stands for
+        // top-level code, which survives as long as the file itself does (both
+        // sides having been readable is already established above). Without
+        // this, a removed top-level guard would be wrongly treated as belonging
+        // to a vanished symbol and silently dropped.
+        survivingSymbols.add(MODULE_OWNER);
+        for (const g of before) {
+            // Matched against a surviving guard with the same condition text:
+            // consume it and move on. Multiset, not set — see `unmatched`.
+            const survivor = unmatched.get(key(g)) ?? 0;
+            if (survivor > 0) {
+                unmatched.set(key(g), survivor - 1);
+                continue;
+            }
+            if (!survivingSymbols.has(g.qualifiedOwner))
+                continue;
+            // Unmatched text, but the symbol runs as many guards of this kind as
+            // it did before: this is an edited condition, not a removed guard.
+            const left = budget.get(kindKey(g)) ?? 0;
+            if (left <= 0)
+                continue;
+            budget.set(kindKey(g), left - 1);
+            const evidence = [
+                // beforePath and the before-side line: the guard existed in the
+                // before-side content, and that line number counts in the before
+                // revision — `side` says so, so the renderer does not send a reader
+                // to whatever occupies that line now. Fact.file/Fact.line follow
+                // from this ref via makeFact, so they agree even for a renamed file.
+                { file: beforePath, line: g.line, excerpt: g.excerpt, side: "before" },
+            ];
+            facts.push(makeFact({
+                // The line is part of the id: with two identical guards in one
+                // symbol and only one deleted, symbol+signature alone would not
+                // distinguish the fact from a second one.
+                id: `guard_removed:${beforePath}:${g.line}:${g.qualifiedOwner}:${g.signature}`,
+                kind: "guard_removed",
+                qualifiedSymbol: g.qualifiedOwner,
+                detail: { guard: g.signature.split(":")[0], symbol: g.qualifiedOwner },
+                evidence,
+            }));
+        }
+    }
+    return facts;
+};
+/**
+ * Every owner path `frameNameOf` could attribute a guard to in this file — the
+ * same predicate *and the same owner stack* `collectGuards` uses. The stack
+ * is not optional here even though survival is a question about presence
+ * rather than nesting: these strings are compared against `GuardSite`'s
+ * qualified owners, so `Worker.run` present in the file must not read as
+ * `run` absent from it.
+ */
+function collectDeclaredOwners(path, text) {
+    if (!isTypeScriptFile(path))
+        return [];
+    const sf = ts.createSourceFile(path, text, ts.ScriptTarget.ES2022, true, path.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const owners = [];
+    const stack = [];
+    const visit = (node) => {
+        const pushed = framesFor(node);
+        if (pushed.length > 0) {
+            stack.push(...pushed);
+            owners.push(qualifyOwner(stack));
+        }
+        ts.forEachChild(node, visit);
+        stack.length -= pushed.length;
+    };
+    ts.forEachChild(sf, visit);
+    return owners;
+}

package/dist/analyze/index.d.ts

@@ -0,0 +1,26 @@
+import type { AnalysisContext, Analyzer, Changeset, Fact } from "../types.js";
+export { detectEffects, effectsAnalyzer } from "./effects.js";
+export { collectGuards, guardsAnalyzer } from "./guards.js";
+export { exportedSignatures, surfaceAnalyzer } from "./surface.js";
+export { countReferences, blastRadiusAnalyzer } from "./blast-radius.js";
+export { citationsAnalyzer, makeCitationsAnalyzer } from "./citations.js";
+export { createProgramAt, listTypeScriptFilesAt } from "./program.js";
+export { makeFact } from "./fact.js";
+export declare const ANALYZERS: Analyzer[];
+/** One analyzer that threw, named so the user knows what is missing. */
+export interface AnalyzerFailure {
+    analyzer: string;
+    message: string;
+}
+/**
+ * Runs every analyzer and returns the facts from the ones that succeeded.
+ *
+ * `Promise.allSettled`, not `Promise.all`: one compiler-API or git failure
+ * used to discard every analyzer's facts and exit non-zero, so a single
+ * unreadable revision turned a review with three real findings into no
+ * review at all. A degraded review beats no review — but only if the
+ * degradation is visible, which is what `onFailure` is for. Callers that
+ * pass no handler get the facts and no indication anything was lost, so
+ * anything user-facing should pass one.
+ */
+export declare function runAnalyzers(changeset: Changeset, ctx: AnalysisContext, analyzers?: Analyzer[], onFailure?: (failure: AnalyzerFailure) => void): Promise<Fact[]>;