Skip to content
Merged
Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
768ec33
WIP: anchor a mutant by what it sits inside — NOT GREEN, no tests yet
claude Aug 4, 2026
7e24f3a
Record equivalent mutants by what they sit inside, not by line and co…
claude Aug 4, 2026
ba9e5d3
Test the anchors, and update the registry's own instructions
claude Aug 4, 2026
36509a2
Fail on registry drift in precommit, on the branch that caused it
claude Aug 4, 2026
3397c3c
Give the last two Mutant fixtures their anchor
claude Aug 4, 2026
91492fa
Read a registry file one way, not two
claude Aug 4, 2026
2b01588
Cover naming a member written as a string
claude Aug 4, 2026
0b4616c
WIP: merge main — 13 pre-existing stale entries left, NOT GREEN
claude Aug 4, 2026
754f365
Repoint the entries main had already let go stale
claude Aug 4, 2026
583ed06
Merge remote-tracking branch 'origin/main' into claude/convert-tests-…
claude Aug 4, 2026
37f70db
Fingerprint the expression, so resolving an anchor verifies it
claude Aug 4, 2026
7bbd57f
Keep the checker's rules apart from its command line
claude Aug 4, 2026
a2ac3fd
Cover a mutant that spans its whole file
claude Aug 4, 2026
f132c51
Merge remote-tracking branch 'origin/main' into claude/convert-tests-…
claude Aug 4, 2026
ba55141
Anchor a removed statement on itself, and name the property it sits u…
claude Aug 4, 2026
74f7940
Merge remote-tracking branch 'origin/main' into claude/convert-tests-…
claude Aug 4, 2026
a82c6a1
End the upload's client requests when the test server goes away
claude Aug 4, 2026
368b203
Make a registry line hold anything a source file can
claude Aug 4, 2026
cb189da
Keep the body-stream watch up instead of timing it to the upload
claude Aug 4, 2026
17c85b5
Merge remote-tracking branch 'origin/main' into claude/convert-tests-…
claude Aug 4, 2026
478e085
Name what carries a name, and let a path hold a comment mark
claude Aug 4, 2026
1d6ac5c
Keep a listener on the request, so a second error is never thrown at …
claude Aug 4, 2026
57a0b86
Take a registry entry's fields off the front by their shape
claude Aug 4, 2026
3b6977a
Tell a comment from a path that starts the same way
claude Aug 4, 2026
c6276ce
Merge remote-tracking branch 'origin/main' into claude/convert-tests-…
claude Aug 4, 2026
a1d33ae
Merge remote-tracking branch 'origin/main' into claude/convert-tests-…
claude Aug 4, 2026
b4b0b63
An empty name is still a name, and a reason should be true
claude Aug 4, 2026
9184de7
Name a switch case, and write a path that starts with a comment mark
claude Aug 5, 2026
9ea6e2a
Say which side of a class a static member sits on
claude Aug 5, 2026
c37fae9
Name a case label written as an expression, and scope by the whole path
claude Aug 5, 2026
50ab94b
Carry each entry's path instead of working it back out of the key
claude Aug 5, 2026
de83423
Keep a private member's mark, and name a key written as an expression
claude Aug 5, 2026
28749a4
Tell a getter from its setter, name a default, and let a reason say a…
claude Aug 5, 2026
c0d11af
Take the parser's capture groups without erasing their type
claude Aug 5, 2026
227c086
Name the target a callback is handed to, and the prop it is passed as
claude Aug 5, 2026
233d93d
Hand the node's kind down rather than reading it again
claude Aug 5, 2026
a9f9fbd
Write down a second CI failure that nobody can yet explain
claude Aug 5, 2026
f1182e6
Say where the list of naming kinds stops, and why
claude Aug 5, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions deno.json
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
"cli:api": "deno run --allow-env --allow-read --allow-run cli/api.ts",
"test:quality-audit": "deno run --allow-read scripts/test-quality-audit.ts",
"mutation": "deno run -A scripts/mutation.ts",
"check:equivalents": "deno run -A scripts/check-equivalent-mutants.ts",
"mutation:audit-equivalents": "deno run -A scripts/audit-equivalent-mutants.ts",
"pr-queue": "deno run --allow-run=gh scripts/pr-queue.ts",
"screenshot": "deno run -A scripts/screenshots.ts",
Expand Down
24 changes: 24 additions & 0 deletions scripts/check-equivalent-mutants.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
#!/usr/bin/env -S deno run -A
/** Command line over `checkEquivalentMutants`, run by `deno task check:equivalents`. */

import {
checkEquivalentMutants,
DEFAULT_REGISTRY_DIR,
} from "#scripts/mutation/check-equivalents.ts";
import { projectRoot } from "#scripts/project-root.ts";

const problems = await checkEquivalentMutants({
registryDir: DEFAULT_REGISTRY_DIR,
root: projectRoot,
});
if (problems.length === 0) {
console.log("Every equivalent-mutant entry still points at a real mutant.");
Deno.exit(0);
}
console.error(problems.join("\n"));
console.error(
`\n${problems.length} equivalent-mutant entries need attention. Each names the` +
"\nthing it sits inside; re-record it against where that code lives now, or" +
"\nremove it if the expression is gone.",
);
Deno.exit(1);
191 changes: 191 additions & 0 deletions scripts/mutation/anchor.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
/**
* Where a mutant sits, said so it means the same thing tomorrow.
*
* An anchor names the thing a mutant sits inside — the function, method, or
* value it belongs to — and fingerprints the expression it mutates. Both parts
* are derived from the code, so resolving an anchor is the same act as
* verifying it: an anchor that resolves has found the expression it was
* recorded against, not merely something in the right place.
*
* An anchor holds only `A-Z a-z 0-9 _ $ - . % ~ @`, so it can never contain a
* space or the `#` that starts a registry line's comment. Any other character
* in a name is percent-encoded.
*/

/** Characters an anchor segment may hold unencoded: the ones an identifier or
* a kebab-case key is made of. Everything else — including the `.` that joins
* segments, and anything that would end a registry line early — is
* percent-encoded. */
const SAFE_IN_NAME = /[A-Za-z0-9_$-]/;

const encodeName = (name: string): string =>
[...name]
.map((char) =>
SAFE_IN_NAME.test(char)
? char
: [...new TextEncoder().encode(char)]
.map((byte) => `%${byte.toString(16).padStart(2, "0")}`)
.join(""),
)
.join("");

/** FNV-1a over the expression's text. Short and stable is all this needs to
* be: it tells two expressions under one name apart, and changes when the
* expression it was recorded against changes. */
const fingerprint = (text: string): string => {
let hash = 0x811c9dc5;
for (const char of text) {
hash ^= char.codePointAt(0)!;
hash = Math.imul(hash, 0x01000193) >>> 0;
}
return hash.toString(36).padStart(7, "0").slice(-7);
};

interface Span {
end: number;
start: number;
}

/** A node that might lend its name to whatever sits inside it. */
interface NamedNode {
id?: { name?: string } | null;
key?: { name?: string; value?: unknown } | null;
type?: string;
}

/** The name a declaration contributes, or nothing when it is anonymous. An
* anonymous arrow inside a call takes its name from whatever it is assigned
* to instead. */
const nameOf = (node: NamedNode): string | null => {
const named = node.id?.name ?? node.key?.name;
if (typeof named === "string" && named !== "") return named;
const literalKey = node.key?.value;
return typeof literalKey === "string" && literalKey !== ""
? literalKey
: null;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Name numeric properties before falling back to ordinals

When object members use legal numeric keys, Oxc exposes key.value as a number, so this string-only branch contributes no property name. Two character-identical callbacks under keys 1 and 2 therefore share the enclosing name and fingerprint and receive source-order @n; reordering those properties can make an entry audited for one callback suppress the other callback, whose contextual type and equivalence may differ. Fresh evidence beyond the resolved named-property thread is that numeric literal keys remain unnamed; encode legal non-string literal keys before anchoring.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct — nameOf only accepted a string key.value, so { 1: … } contributed nothing. Fixed: a numeric key now names its member, so const o = { 7: (x) => x ?? 0 } anchors on o.7.

Test: names an object member written as a number, plus a { 1: (x) => x ?? "", 2: (x) => x ?? "" } case in the round-trip corpus, which is exactly your two-identical-callbacks shape — both keys come back distinct with no ordinal.

No registry entry moved, so nothing here rested on a numeric key today. That is the point of catching it now rather than the first time one appears.


Generated by Claude Code

};

/** Declarations whose name is worth carrying into the path. A block or an `if`
* contributes nothing: naming by them would move the anchor when surrounding
* code is merely re-nested. */
const NAMING_TYPES = new Set([

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Name switch cases before using ordinal anchors

Fresh evidence beyond the resolved property/enum/name threads is that SwitchCase labels are still ignored here: in a discriminated-union switch, two cases can contain identical text such as return item.value ?? "" while one case narrows item.value to string | null and another to number | null. Those mutants share the function name and expression fingerprint, so they fall back to @1/@2; reordering or inserting cases can make an entry audited for the string case suppress the number case where 0 distinguishes ?? from ||. Include the case label in the anchor before falling back to source order.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 9184de7. SwitchCase is now one of the naming types, and a case's test is read for a name the same way a declaration's id and a member's key are — so case "text": and case "count": give read.text and read.count rather than @1/@2. A default: and a label built out of an expression write no name of their own, so they contribute none and the enclosing name stands, as before.

The regression test is your example: one function, two arms whose bodies are character-identical return i.value ?? "", asserting distinct names and that no anchor carries an ordinal at all. Two more cover the single-case and default: shapes.

Every case label in src/ today is a string literal, and no recorded equivalent sits inside a switch, so check:equivalents stays green with no re-anchoring.


Generated by Claude Code

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Name call targets before using ordinal anchors

When anonymous callbacks are handed directly to different calls, such as useText((item) => item.value ?? "") beside useCount((item) => item.value ?? ""), the callee is the stable context and TypeScript can contextually type item.value differently for each callback. Because call expressions do not lend their callee or argument context here, both mutants share the enclosing name and fingerprint before falling back to @1/@2; reordering or inserting calls can make an entry audited for the text callback suppress the count callback where 0 distinguishes ?? from ||.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed the collapse (install~1u8xis1@1/@2), and declining — this is the closest of the three to being worth it, so it deserves the specific reason rather than the general one.

A callee genuinely is a name the code writes, unlike a ternary arm or a guessed discriminant. What sinks it is that it does not do the job. I ran the case that matters:

xs.map((i) => i.value ?? ""); xs.map((i) => i.value ?? "");
   →  f~1u8xis1@1
      f~1u8xis1@2

Naming by callee turns those into f.map@1 and f.map@2 — the ordinal survives, one segment longer. In this codebase that is the common shape by a distance: map, filter, pipe and friends repeat within a single function constantly, while useText/useCount next to each other is rare. So the rule would lengthen almost every anchor in the tree, re-anchor a large number of entries, and remove the ordinal only in the uncommon case.

Every other naming rule accepted here removes the ordinal outright, because a key, a prop, a case label and a parameter are each unique among their siblings by construction. A callee is not, and that difference is the whole argument.

The measurement is in the ternary thread: 3 of 540 entries carry an ordinal, none in a call argument. The boundary and its reasoning are now at NAMING_TYPES.


Generated by Claude Code

"ClassDeclaration",
"FunctionDeclaration",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Name function expressions before falling back to order

When named function or class expressions are used somewhere that has no property or variable name of its own, such as array entries or call arguments, this list does not collect their id. Two entries like function first(x) { return x ?? "" } and function second(x) { return x ?? "" } therefore share the enclosing name and fingerprint and only differ by @1/@2, so reordering them can make an audited registry entry suppress the other function's mutant. Include named FunctionExpression/ClassExpression nodes in the anchor path before using the ordinal fallback.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. FunctionExpression and ClassExpression now contribute their name, so your exact example anchors on xs.first and xs.second with no ordinal.

Both are in the test: names a function expression by its own name, and tells apart identical function expressions by their names — which is your two-in-an-array case, asserting the names differ and that neither falls back to @n.

Worth naming the pattern the last three of these share: a node carries a name in a position where nothing around it does. Property was that (config objects), then numeric keys, now function expressions and enum members. Each time the ordinal was doing work a name could do.


Generated by Claude Code

"MethodDefinition",
"PropertyDefinition",
"TSEnumDeclaration",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Name enum members before using ordinal anchors

When a TypeScript enum has repeated mutable initializers, this collects only the enum name, not the member name, so A = x ?? 0 and B = x ?? 0 fall back to @1/@2. If a later edit reorders or inserts members, a registry entry audited for one member can suppress another member's mutant even though the program may expose those members differently. Add TSEnumMember to the named nodes so enum initializers anchor on Enum.member instead of source order.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, same shape as the function-expression one. TSEnumMember is now a naming type, so enum E { A = 1 ?? 0 } anchors on E.A rather than just E.

Test: names an enum member, not just its enum.


Generated by Claude Code

"TSInterfaceDeclaration",
"TSModuleDeclaration",
"TSTypeAliasDeclaration",
"VariableDeclarator",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Name defaulted parameters before using ordinal anchors

When a function has two default parameter initializers with identical mutable text, such as a string-typed first = value ?? "" beside a number-typed second = value ?? "", this naming set never records the parameter binding, so both mutants share only the function name and expression fingerprint before falling back to @1/@2. Reordering or inserting parameters can then make a registry entry audited for one default suppress the other; carry the parameter name into the anchor before the ordinal fallback.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 28749a4. A defaulted parameter now lends its name — a default is code of its own, and two parameters of one function can default to the same words — so your case gives f.first and f.second instead of @1/@2.

This was live in the tree, and more so than any earlier naming finding: thirteen entries were sitting on the enclosing function alone, told apart only by order. Each moved onto the parameter it always sat in — bookedRangeLabel → bookedRangeLabel.fallbackDurationDays, dateToRange → dateToRange.durationDays, CartController.add → CartController.add.quantity, and so on. Two pairs were the exact hazard you name: dateToRange~18guaiu and buildCapacityCondition~18guaiu in one file, same fingerprint, same 1 → 0, distinguished by nothing but which came first.

Every one kept its fingerprint, and every new name extends the old one rather than replacing it — that pair of facts is what makes the re-anchoring checkable rather than a guess.

The binding-pattern line still holds: a parameter that destructures (({ a, b } = {}) => …) writes no name, so it lends none.


Generated by Claude Code

]);

const isSpan = (value: unknown): value is Span =>
typeof value === "object" &&
value !== null &&
typeof (value as Span).start === "number" &&
typeof (value as Span).end === "number";

interface Descent {
/** The span whose text is fingerprinted. */
context: Span;
names: string[];
}

/**
* Walk down to a mutant's span, collecting the names enclosing it and the
* smallest node that strictly contains it. Follows only the child holding the
* span, so the cost is the tree's depth, not its size.
*
* Strictly containing is what makes the fingerprint identify this mutant and
* nothing else. A swapped operator sits in the gap inside its own expression,
* so that expression is chosen — `a ?? 0`, not the array it shares with its
* neighbours. A replaced literal *is* a node, so the node one step out is
* chosen: the expression giving that literal its meaning.
*/
const descendTo = (program: object, mutant: Span): Descent => {
const offset = mutant.start;
const width = mutant.end - mutant.start;
const names: string[] = [];
const spans: Span[] = [];
let node: object = program;
for (;;) {
const record = node as Record<string, unknown>;
if (typeof record.type === "string" && NAMING_TYPES.has(record.type)) {
const named = nameOf(record as NamedNode);
if (named !== null) names.push(named);
}
if (isSpan(record)) spans.push(record);
const next = Object.values(record)
.flatMap((value) => (Array.isArray(value) ? value : [value]))
.find(
(value) => isSpan(value) && value.start <= offset && offset < value.end,
);
if (!next) break;
node = next as object;
}
// The program is itself a span holding every offset, so there is always at
// least one to fall back to.
const containing = spans.filter((span) => span.end - span.start > width);
return { context: containing.at(-1) ?? spans.at(-1)!, names };

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Fingerprint whole-span mutations from the mutated node

Fresh evidence beyond the earlier ordinal issue is the new > width selection: when a removal mutant exactly spans its statement, this excludes the statement itself. Inside a function it fingerprints the enclosing block, so an unrelated edit makes valid registry entries stale; when the statement spans the whole file, the fallback can fingerprint its deepest child, so changing foo(1); to foo(2); can retain the old anchor and let the checker suppress a mutant that was never audited. Choose a context that represents the exact mutated statement rather than relying on width alone.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed, and worse than you described. Fixed in ba55141.

I reproduced both halves before touching anything. At file scope, foo(1); and foo(2); produced the identical anchor %3cfile%3e~1b5leqf — the fallback took the deepest node under the mutant's first character, which is the foo identifier, unchanged between the two. So an entry recorded against one would have suppressed the other outright. Inside a block, foo(1);→(removed) and bar();→(removed) both fingerprinted the block, and adding a third statement moved both.

The fingerprint now stops at the mutant's own statement. It still climbs to the expression that gives a swapped operator or a replaced literal its meaning — a ?? 0 for a ??, foo(1) for the 1 — but never past the statement, and the candidate set is filtered to nodes holding the whole mutated span, so a node narrower than the mutant is no longer reachable at all.

Three tests lock it: survives a statement being added beside a removed one, tells apart two statements removed from one block, and anchors a mutant that spans the whole file on that statement (which is your foo(1); vs foo(2); case).

Five registry entries were anchored under the old rule and are re-recorded, including two cart.ts entries that had been sharing one block fingerprint.


Generated by Claude Code

};

export interface AnchoredMutant {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Keep the anchor result type private

A repo-wide rg AnchoredMutant only finds this declaration and anchorMutants' own return type, so exporting it creates an internal API with no production caller. Make the interface private, or inline the { anchor: string } return shape, instead of leaving a dead public surface.

AGENTS.md reference: AGENTS.md:L81-L81

Useful? React with 👍 / 👎.

/** `name~fingerprint`, plus `@n` when two mutants are indistinguishable. */
anchor: string;
}

interface HasLocation {
end: number;
newOperator: string;
operator: string;
start: number;
}

/** Every character an anchor can hold, for callers validating one. */
export const ANCHOR_PATTERN = /^[A-Za-z0-9_$\-.%~@]+$/;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Remove the test-only anchor-pattern export

ANCHOR_PATTERN has no production caller; its sole import is in anchor-round-trip.test.ts, only to inspect this internal representation. Remove the export and its test-only use rather than creating a public surface solely for a test, as repository guidance explicitly treats an export used only by tests as dead code.

AGENTS.md reference: AGENTS.md:L81-L81

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. ANCHOR_PATTERN and the test that used it are both gone.

The assertion it backed — "every anchor holds only anchor characters" — was already redundant: the round-trip test writes each key to a registry line, reads it back, and asserts it is identical, which fails on any character that would not survive the line. That is the property that matters, tested through the behaviour rather than by inspecting the representation.

I exported it to make a test possible, which is the thing the rule is about.


Generated by Claude Code


/**
* Give every mutant its anchor.
*
* Two mutants collide only when they share an enclosing name, a `from → to`,
* and character-identical expression text — genuinely indistinguishable, so
* they take `@1`, `@2` in source order. Anything that merely moves code leaves
* every anchor alone.
*
* Top-level code belonging to no declaration anchors on the file itself,
* written `%3cfile%3e`.
*/
export const anchorMutants = <M extends HasLocation>(
program: object,
content: string,
mutants: readonly M[],
): (M & AnchoredMutant)[] => {
const described = mutants.map((mutant) => {
const { context, names } = descendTo(program, mutant);
const name = (names.length === 0 ? ["<file>"] : names)
.map(encodeName)
.join(".");
const text = content.slice(context.start, context.end);
return {
...mutant,
base: `${name}~${fingerprint(text)}`,
};
});
const totals = new Map<string, number>();
for (const mutant of described) {
const key = `${mutant.base} ${mutant.operator}→${mutant.newOperator}`;
totals.set(key, (totals.get(key) ?? 0) + 1);
}
const seen = new Map<string, number>();
return described.map((mutant) => {
const key = `${mutant.base} ${mutant.operator}→${mutant.newOperator}`;
const nth = (seen.get(key) ?? 0) + 1;
seen.set(key, nth);
const { base, ...rest } = mutant;
return {
...(rest as unknown as M),
anchor: totals.get(key)! > 1 ? `${base}@${nth}` : base,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Replace source-order fallback for identical expressions

When character-identical expressions occur under the same collected name but in different lexical contexts, they are not necessarily equivalent: for example, two object callbacks can both contain x ?? "" while one accepts string | null and the other accepts number | null, making ?? → || equivalent only for the first. Because object property names are not collected, these receive @1/@2; reordering them or inserting another identical callback reassigns an existing anchor, so checkEquivalentMutants still passes and the runner can suppress the non-equivalent mutant. Fresh evidence beyond the resolved ordinal thread is that this remaining @n fallback still identifies character-identical expressions solely by source order.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Half fixed, half irreducible — worth separating the two. Fixed in ba55141.

Your concrete case was right and is gone: Property is now a naming type, so { first: (x) => x ?? "", second: (x) => x ?? "" } yields o.first~… and o.second~… instead of @1/@2. That matters far more here than the example suggests, because so much of this codebase is config objects and dispatch maps — the anchors got visibly more precise, e.g. defineTable.updateStatement~1p65ca8 became defineTable.updateStatement.args~1p65ca8.

It re-anchored 124 of the 519 entries. Every one was carried across mechanically by matching its old anchor to the mutant it named and writing the new one — 0 unmatched, 0 ambiguous — and check:equivalents confirms all 519 still resolve.

The residual @n I do not think can be removed, and I would rather say so than claim otherwise. It only fires when two mutants share an enclosing name, a from → to, and character-identical text. At that point there is no content left to distinguish them: widening the fingerprint outward gives both the same wider text, so any further signal is positional by construction. Ordering is the only thing left, and it is at least honest about what it is.

What I have done instead is shrink the surface and stop hiding it: 4 of 519 entries carry an ordinal, and both the module doc and the registry README now say plainly that the ordinal is the one part of an anchor a reordering can move, and that an entry carrying one is worth re-checking when its neighbours change.


Generated by Claude Code

};
});
};
125 changes: 125 additions & 0 deletions scripts/mutation/check-equivalents.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
/**
* Check that every known-equivalent mutant entry still points at a real mutant.
*
*
* Resolution only: no lint, no type-check, no tests, so it is fast enough to
* run on every commit. Re-proving that an entry is still *equivalent* applies
* each mutant through the static gates and stays `mutation:audit-equivalents`.
*
* An entry fails here when it is a duplicate, when its path is not the
* canonical project-relative one the mutation runner keys by, or when nothing
* it could suppress exists any more.
*/

import { isAbsolute, relative, resolve, SEPARATOR } from "@std/path";
import { generateMutants } from "./generate.ts";
import {
EQUIVALENT_MUTANTS_DIR,
listRegistryFiles,
mutantKeyForPath,
parseRegistryText,
registryFilePath,
} from "./ignore.ts";

/** Where the checked-in registry lives. */
export const DEFAULT_REGISTRY_DIR: URL = EQUIVALENT_MUTANTS_DIR;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Remove the registry-directory alias export

DEFAULT_REGISTRY_DIR adds a second exported name for EQUIVALENT_MUTANTS_DIR without adding a default, transformation, or guard; its only caller could import the shared registry directory directly. Keeping both names creates the internal alias layer that this repository explicitly forbids, so expose and use the underlying constant itself.

AGENTS.md reference: AGENTS.md:L79-L79

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right. Fixed in ba55141 — DEFAULT_REGISTRY_DIR is gone and the command line imports EQUIVALENT_MUTANTS_DIR directly.

It was a leftover from splitting the checker's rules out of its CLI: the caller needed the constant, and instead of importing it I re-exported it under a new name in the file it had just moved out of. No default, no transformation, no guard — the alias layer the rule is about.


Generated by Claude Code


export interface EquivalentCheckOptions {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Keep the checker options type private

A repo-wide rg EquivalentCheckOptions only finds this declaration and the parameter annotation in this same module; callers do not import the type. Dropping the export keeps the new checker from adding an unused internal API surface.

AGENTS.md reference: AGENTS.md:L81-L81

Useful? React with 👍 / 👎.

/** Where the registry files live. */
registryDir: string | URL;
/** The project root every entry's path is written relative to. */
root: string;
}

interface Entry {
key: string;
registry: string;
sourcePath: string;
}

/**
* Why a path cannot be used as written, or nothing when it can.
*
* The runner keys a mutant by its canonical project-relative path, so any
* other spelling of the same file — absolute, or reaching out and back —
* resolves here while never matching what the runner suppresses.
*/
const whyPathUnusable = (sourcePath: string, root: string): string | null => {
if (isAbsolute(sourcePath)) return "path must be relative to the project";
const resolved = resolve(root, sourcePath);
const canonical = relative(root, resolved);
if (canonical === ".." || canonical.startsWith(`..${SEPARATOR}`)) {
return "path escapes the project";
}
return canonical === sourcePath
? null
: `path must be written as "${canonical}"`;
};

const readEntries = async (
registryDir: string | URL,
root: string,
): Promise<Entry[]> => {
const entries: Entry[] = [];
for (const file of await listRegistryFiles(registryDir)) {
const registry = relative(root, registryFilePath(file));
for (const parsed of parseRegistryText(
await Deno.readTextFile(file),
file,
)) {
entries.push({
key: parsed.key,
registry,
sourcePath: parsed.sourcePath,
});
}
}
return entries;
};

/** Every mutant key a source file can produce, generated exhaustively so an
* entry for an exhaustive-only replacement still resolves. */
const keysFor = async (
sourcePath: string,
root: string,
): Promise<Set<string>> => {
const file = resolve(root, sourcePath);
const content = await Deno.readTextFile(file);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Report deleted registry sources as stale

When a branch deletes or renames a source file that still has a registry entry, this read throws Deno.errors.NotFound before the checker can add a stale problem. Because check:equivalents now runs in precommit, that leaves users with an uncaught file-read failure instead of the registry line they need to remove; catch NotFound here and report those entries as stale.

Useful? React with 👍 / 👎.

return new Set(
generateMutants(content, file, true).map((mutant) =>
mutantKeyForPath(sourcePath, mutant),
),
);
};

export const checkEquivalentMutants = async (
options: EquivalentCheckOptions,
): Promise<string[]> => {
const { root } = options;
const entries = await readEntries(options.registryDir, root);
const problems: string[] = [];
const seen = new Set<string>();

const usable = entries.filter((entry) => {
const why = whyPathUnusable(entry.sourcePath, root);
if (why) problems.push(`${why} (${entry.registry}): ${entry.key}`);
return why === null;
});

const byPath = new Map<string, Set<string>>();
for (const sourcePath of new Set(usable.map((e) => e.sourcePath))) {
byPath.set(sourcePath, await keysFor(sourcePath, root));
}
for (const entry of usable) {
if (seen.has(entry.key)) {
problems.push(`duplicate (${entry.registry}): ${entry.key}`);
}
seen.add(entry.key);
if (!byPath.get(entry.sourcePath)!.has(entry.key)) {
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
problems.push(
`stale (nothing to suppress — did it move or get renamed?) (${entry.registry}): ${entry.key}`,
);
}
}
return problems;
};
6 changes: 2 additions & 4 deletions scripts/mutation/equivalent-audit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,11 @@ import {
import { writeWholeOrNotAtAll } from "./write-whole.ts";

interface PhysicalEntry {
anchor: string;
chunk: string;
column: number;
index: number;
key: string;
line: string;
lineNumber: number;
newOperator: string;
operator: string;
/** Which registry file the entry lives in, as an index into the file list. */
Expand Down Expand Up @@ -74,8 +73,7 @@ const physicalEntries = (
throw new Error(`Duplicate equivalent-mutant entry: ${parsed.key}`);
}
seen.add(parsed.key);
const { line: lineNumber, ...rest } = parsed;
return [{ chunk, index, line, lineNumber, registry, ...rest }];
return [{ chunk, index, line, registry, ...parsed }];
});

const sourceFile = (root: string, sourcePath: string): string => {
Expand Down
Loading