Skip to content
Merged
Show file tree
Hide file tree
Changes from 7 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
96 changes: 96 additions & 0 deletions scripts/check-equivalent-mutants.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
/**
* Check that every known-equivalent mutant entry still points at a real mutant.
*
* This is the cheap half of `mutation:audit-equivalents`: it only resolves
* entries against freshly generated mutants, running no lint, no type-check and
* no tests, so it is fast enough for `precommit`. Re-proving that each entry is
* still *equivalent* is the expensive half and stays an on-demand tool.
*
* It exists because drift used to be found in review. An entry that no longer
* resolves stops suppressing its mutant, and the next mutation run fails
* somewhere else entirely — on a branch that may not be the one that moved it.
*/

import { relative, resolve } from "@std/path";
import { generateMutants } from "#scripts/mutation/generate.ts";
import {
listRegistryFiles,
mutantKeyForPath,
parseRegistryText,
} from "#scripts/mutation/ignore.ts";
import { projectRoot } from "#scripts/project-root.ts";

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

/** Every entry across the registry, with the file it was read from. */
const readEntries = async (): Promise<Entry[]> => {
const entries: Entry[] = [];
for (const file of await listRegistryFiles()) {
const path = typeof file === "string" ? file : file.pathname;
const registry = relative(projectRoot, path);
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, under exhaustive generation so
* an entry for an exhaustive-only replacement still resolves. */
const keysFor = async (sourcePath: string): Promise<Set<string>> => {
const file = resolve(projectRoot, 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 Reject non-canonical registry source paths

When an entry uses an absolute path or an in-project alias such as ../tickets/src/foo.ts, resolve reads the intended file and generated keys retain that exact spelling, so this precommit check reports success. The mutation runner, however, keys the same file through its canonical project-relative path (src/foo.ts), meaning the accepted entry never suppresses its mutant and is skipped by per-file registry validation. Reject absolute paths and require sourcePath to equal the canonical relative path, matching the audit's path checks.

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.

Agreed. Fixed in 37f70db.

whyPathUnusable now rejects three spellings: an absolute path, one escaping the project, and one that resolves to a file inside the project but is not written as the canonical relative path. The last is the case you named — the error says path must be written as "src/foo.ts" rather than just refusing.

Three of the nine checker tests cover them, including ../<root>/src/read.ts reaching out and back.


Generated by Claude Code

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

export const checkEquivalentMutants = async (): Promise<string[]> => {

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 Add direct tests for the precommit equivalent check

No test in this commit imports checkEquivalentMutants; its only caller is the new precommit subprocess, so its success, duplicate, and stale-entry branches have no direct in-process coverage. Add unit tests with controllable registry/source inputs rather than relying on incidental CLI execution, as the repository explicitly requires deterministic direct coverage for subprocess code.

AGENTS.md reference: AGENTS.md:L74-L74

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.

Fair. Fixed in 37f70db and 7bbd57f.

Adding the tests immediately proved the second half of your point: importing the module in-process pulled its import.meta.main block into the coverage gate, where no test can reach it. So the rules moved to scripts/mutation/check-equivalents.ts and the command line stayed a thin shell nothing imports — the split AGENTS.md prescribes for exactly this.

Nine cases in test/scripts/mutation/check-equivalents.test.ts, each with its own registry and source under a temp root: a clean pass, comments and blanks skipped, a stale entry, a duplicate, three rejected path spellings, and a malformed line raising.

Making it testable also removed two branches worth losing — the registry directory and project root are named by the caller now instead of defaulted, and the "which spelling is this path" branch went away because registryFilePath already answered it.


Generated by Claude Code

const entries = await readEntries();
const problems: string[] = [];
const seen = new Set<string>();
const byPath = new Map<string, Set<string>>();
for (const sourcePath of new Set(entries.map((e) => e.sourcePath))) {
byPath.set(sourcePath, await keysFor(sourcePath));
}
for (const entry of entries) {
if (seen.has(entry.key)) {
problems.push(`duplicate (${entry.registry}): ${entry.key}`);
}
seen.add(entry.key);
if (!byPath.get(entry.sourcePath)!.has(entry.key)) {
problems.push(
`stale (nothing to suppress — did it move or get renamed?) (${entry.registry}): ${entry.key}`,
);
}
}
return problems;
};

if (import.meta.main) {
const problems = await checkEquivalentMutants();
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);
}
146 changes: 146 additions & 0 deletions scripts/mutation/anchor.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
/**
* Where a mutant sits, said in a way that survives an edit somewhere else.
*
* The equivalent-mutant registry used to record `path:line:column`, so any edit
* *above* a recorded expression silently invalidated its entry — the mutant
* stopped being suppressed and the audit failed, without the recorded
* expression having changed at all. That happened repeatedly, and was always
* found by a reviewer rather than by a check.

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 historical implementation narratives from comments

This module header describes the former line-and-column implementation, past review failures, and what the new code replaced rather than documenting only the current anchor contract; similar historical narratives were also added to the checker and ignore-list comments. Move that history to the commit message and keep only the present constraint, as the repository explicitly forbids old-implementation comparisons in source comments and requires comments to stay short.

AGENTS.md reference: AGENTS.md:L71-L72

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.

You're right, and I wrote those deliberately, which makes it worse. Fixed in 37f70db.

anchor.ts, ignore.ts and the checker now describe the contract only: what an anchor is made of, which characters it may hold, and when it moves. The history — the line-and-column format, the reviews that caught it, the entries it lost — is in the commit messages, where git keeps it for whoever needs it.

I kept one sentence that reads like history but is not: the note on descendTo explaining why the fingerprint comes from the strictly-containing node rather than the deepest one. That is a constraint on the current code — pick the wrong node and neighbouring expressions collide — not a comparison with what came before.


Generated by Claude Code

*
* An anchor is the name of the thing the mutant sits inside — the function,
* method, or top-level value it belongs to — plus `@n` when several mutants of
* the same kind sit inside that same thing. The ordinal is written with `@`
* rather than `#` because a registry line ends with a `#` comment, and a `#`
* in the anchor would be read as the start of one. Adding a comment, an import, or a
* whole unrelated function moves no anchor. Renaming the function, or adding
* another mutant of that kind inside it, does — and both are real changes to
* the thing being recorded.
*/

/** Names of the declarations a mutant can sit inside, outermost first. */
type NamePath = readonly string[];

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. Kept
* to the shapes that really carry a reader-recognisable name: an anonymous
* arrow inside a call gets 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 make the anchor move when
* the 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";

/**
* The names enclosing byte offset `offset`, outermost first. Walks down the
* tree following whichever child actually contains the offset, so the cost is
* the depth of the tree rather than its size.
*/
const namePathAt = (program: object, offset: number): NamePath => {
const names: string[] = [];
let node: object = program;
for (;;) {
const record = node as Record<string, unknown>;
if (
typeof record.type === "string" &&
NAMING_TYPES.has(record.type as string)
) {
const named = nameOf(record as NamedNode);
if (named !== null) names.push(named);
}
const next = Object.values(record)
.flatMap((value) => (Array.isArray(value) ? value : [value]))
.find(
(value) => isSpan(value) && value.start <= offset && offset < value.end,
);
if (!next) return names;
node = next as object;
}
};

/** The anchor for a mutant at `offset`, without its ordinal. Top-level code
* belonging to no declaration anchors on the file itself, written `<file>`. */
export const anchorNameAt = (program: object, offset: number): string => {
const names = namePathAt(program, offset);
return names.length === 0 ? "<file>" : names.join(".");
};

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` plus `@n` when more than one of this kind shares the name. */
anchor: string;
}

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

/**
* Give every mutant its anchor, numbering the ones that would otherwise
* collide. The ordinal counts only mutants sharing both the same enclosing
* name and the same `from → to`, so adding a different kind of mutant beside a
* recorded one leaves its number alone.
*
* Mutants are numbered in source order, which is the order `generateMutants`
* produces them in for a single file.
*/
export const anchorMutants = <M extends HasLocation>(
program: object,
mutants: readonly M[],
): (M & AnchoredMutant)[] => {
const seen = new Map<string, number>();
const named = mutants.map((mutant) => ({
...mutant,
name: anchorNameAt(program, mutant.start),
}));
const totals = new Map<string, number>();
for (const mutant of named) {
const key = `${mutant.name} ${mutant.operator}→${mutant.newOperator}`;
totals.set(key, (totals.get(key) ?? 0) + 1);
}
return named.map((mutant) => {
const key = `${mutant.name} ${mutant.operator}→${mutant.newOperator}`;
const nth = (seen.get(key) ?? 0) + 1;
seen.set(key, nth);
const { name, ...rest } = mutant;
return {
...(rest as unknown as M),
anchor: totals.get(key)! > 1 ? `${name}@${nth}` : name,

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 Preserve mutation identity when ordinal neighbors move

When an enclosing name has several identical from → to mutants, the anchor identifies them only by their current ordinal. If an earlier same-kind expression is inserted, deleted, or reordered while the recorded ordinal still exists, the registry entry silently points to a different mutant; checkEquivalentMutants then passes and isIgnored can suppress a non-equivalent survivor that was never audited. Include stable local expression context in the anchor rather than relying only on @n.

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, and this was the important one. Fixed in 37f70db.

An anchor now carries a fingerprint of the expression it mutates, taken from the smallest node that strictly contains the mutated span. For a swapped operator that is the expression itself (a ?? 0), not the array it shares with its neighbours; for a replaced literal it is the node one step out, which is what gives that literal its meaning. So resolving an anchor and verifying it became the same act — pointing at a neighbour is no longer expressible.

Ordinals survive only for mutants sharing a name, a from → to, and character-identical text, which nothing can tell apart anyway.

Your exact scenario is now a test — survives a same-kind mutant inserted above it — inserting c ?? 9 ahead of a ?? 0, b ?? 1 and asserting both original anchors are unchanged. Under the old scheme they shifted by one.

Worth saying plainly: this was a shortcut, not an oversight. The TODO this PR implements asked for "the expression text plus its enclosing function name", and I substituted an ordinal to keep the registry line easy to parse. My own repointing commit on this branch then hit the failure in the wild — three entries needed their ordinals corrected because main had added mutants above them inside the same function — and I wrote that up as the system working correctly rather than as the bug you found.


Generated by Claude Code

};
});
};
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
18 changes: 16 additions & 2 deletions scripts/mutation/equivalent-mutants/README.txt
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,22 @@
# new record to the file whose name covers the source path (splitting a
# file that outgrows ~400 lines).
#
# Format — copy a survivor line from the report and add a reason:
# <path>:<line>:<col> <from> → <to> # why it is equivalent
# Format — one entry per line, plus a reason:
# <path>::<anchor> <from> → <to> # why it is equivalent
#
# The anchor names the thing the mutant sits inside — a function, a method, a
# value — with nested names joined by dots:
#
# src/fp.ts::collectionCache.generation 0 → 1 # ...
#
# Where several mutants of the SAME kind sit inside one name they are numbered
# in source order, `@1`, `@2`. The ordinal uses `@` and not `#`, because a line
# ends with a `#` comment and a `#` in the anchor would start one early.
#
# Entries used to record <path>:<line>:<col>, which meant any edit ABOVE a
# recorded expression silently invalidated it. An anchor moves only when the
# thing it names does: renaming its function, or adding another mutant of the
# same kind inside that function. Both are real changes to what was recorded.
#
# Do NOT list a mutant whose output the linter or type checker rejects. Biome's
# noDoubleEquals rule rejects every `=== → ==` and `!== → !=` mutant. The runner
Expand Down
Loading