Skip to content
Merged
Show file tree
Hide file tree
Changes from 16 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
22 changes: 22 additions & 0 deletions scripts/check-equivalent-mutants.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
#!/usr/bin/env -S deno run -A
/** Command line over `checkEquivalentMutants`, run by `deno task check:equivalents`. */

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

const problems = await checkEquivalentMutants({
registryDir: EQUIVALENT_MUTANTS_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);
218 changes: 218 additions & 0 deletions scripts/mutation/anchor.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,218 @@
/**
* 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. `Property` earns its place because so much of this
* codebase is config objects and dispatch maps — without it, two callbacks in
* one object share a name and can only be told apart by their order. */
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",
"Property",

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 JSX attributes before using ordinals

When JSX props supply anonymous callbacks, such as <Widget text={(x) => x ?? ""} count={(x) => x ?? ""} />, the prop name is the stable context that tells the callbacks apart, and TypeScript can contextually type x differently for each prop. Because this naming set does not include JSXAttribute or read its name, those identical mutants share the enclosing component and fingerprint and fall back to @1/@2; reordering or inserting props can make an entry audited for the string callback suppress the number callback, where 0 distinguishes ?? from ||. Carry the JSX attribute name into the anchor 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.

Fixed in 227c086. JSXAttribute now lends its prop name, so your example gives Page.text and Page.count with no ordinal. A namespaced prop (xlink:href) has no plain name, so it falls through to the same "named by how it is written" rule the computed keys use.

This one mattered most in the tree by volume: of the 59 entries the two findings moved, 37 were in ui-client.txt — the browser code is dense with callbacks handed straight to props and to properties, exactly the shape where nothing but order was telling neighbours apart. Every one kept its fingerprint.

Regression tests: your two-prop case asserting the names and that no anchor carries an ordinal, plus a single-prop one. The test helper now takes a .tsx name where it needs the source read as markup rather than as a comparison.


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 schema entries before repeated field anchors

When a typed list has repeated object entries such as { kind: "text", read: (item) => item.value ?? "" } beside { kind: "count", read: ... }, this only names the repeated read property, not the entry's own kind, so the two callbacks collapse to entries.read~...@1/@2. Reordering or inserting entries can then make an equivalent-mutant record audited for the text entry suppress the count entry where 0 distinguishes ?? from ||; include an entry label/discriminant before falling back to source order.

AGENTS.md reference: AGENTS.md:L90-L90

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 (entries.read~1u8xis1@1/@2), and declining — this one on a sharper objection than the other two in this round.

Which sibling of an object is its "kind" is a guess about meaning, not something the code writes for that member. Every rule accepted so far reads a name the source states outright: this property's key, this case's label, this prop's name, this parameter's binding. Picking kind out of { kind, read } means deciding that kind is the discriminant and read is not — and nothing in the syntax says so. The next schema calls it type, or id, or name, or has two candidates.

And it fails in the direction that matters. An anchor built on a guessed sibling moves when that sibling changes — rename kind: "text" to kind: "free_text" and the entry drifts, though the expression it was recorded against is untouched. That is drift caused by an unrelated edit, which is the exact failure this whole PR exists to remove. The ordinal at least only moves when the members themselves are reordered.

The measurement behind the decision is in the ternary thread: 3 of 540 entries carry an ordinal, none of them in a schema entry. The boundary is now written down at NAMING_TYPES, naming both excluded shapes and why.

If a real schema in this tree ever does collapse this way, the fix I would reach for is not inference — it is giving that entry a read whose text differs, or recording the mutant against the enclosing declaration instead.


Generated by Claude Code

"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

]);

type Node = Record<string, unknown>;

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

/**
* Where the fingerprint stops climbing: the statement a mutant sits in. Going
* past it would fold the mutant's neighbours into the fingerprint, so editing
* an unrelated line in the same block would move an anchor that should have
* stayed put. `Program` is a boundary too, so the search always finds one.
*/
const isBoundary = (node: Node): boolean =>
typeof node.type === "string" &&
(node.type === "Program" || /(?:Statement|Declaration)$/.test(node.type));

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 node
* whose text is fingerprinted. Follows only the child holding the span, so the
* cost is the tree's depth, not its size.
*
* The fingerprint covers the smallest node that *strictly* contains the mutant
* without leaving its statement. 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. A removed
* statement already fills its statement, so it is fingerprinted as itself —
* never as the block it shares with the statements around it.
*/
const descendTo = (program: object, mutant: Span): Descent => {
const width = mutant.end - mutant.start;
const names: string[] = [];
const path: Node[] = [];
let node: object = program;
for (;;) {
const record = node as Node;
if (typeof record.type === "string" && NAMING_TYPES.has(record.type)) {
const named = nameOf(record as NamedNode);
if (named !== null) names.push(named);
}
path.push(record);
const next = Object.values(record)
.flatMap((value) => (Array.isArray(value) ? value : [value]))
.find(
(value) =>
isSpan(value) &&
value.start <= mutant.start &&
mutant.start < value.end,
);
if (!next) break;
node = next as object;
}
// Descending follows the mutant's first character, so the deepest nodes can
// end before the mutant does. Only nodes holding all of it can name it.
const holding = path.filter(
(found): found is Node & Span =>
isSpan(found) && found.start <= mutant.start && mutant.end <= found.end,
);
const withinStatement = holding.slice(holding.findLastIndex(isBoundary));
const wider = withinStatement.findLast(
(found) => found.end - found.start > width,
);
return { context: wider ?? withinStatement.at(-1)!, names };
Comment on lines +238 to +242

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 the type context that makes equivalence valid

When equivalence depends on the operand's type, this selection stops at the logical expression and ignores its parameter or type declaration. Changing const read = (x: string | null) => x ?? "" to accept number | null leaves the anchor unchanged, so precommit passes and ?? → || remains ignored even though input 0 distinguishes it. Fresh evidence beyond the resolved whole-span finding is this unchanged-expression/type-change case; include the semantic declaration context in the anchor, or otherwise invalidate the entry, so the survivor must be re-audited.

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 are right about the hole, and I am not fixing it here — I tried, measured the cost, and reverted. Recorded in TODO.md under "An equivalence proof rests on types the anchor cannot see".

First, a correction to the severity: isIgnored is applied only to mutants that already survived (run-file.ts:96). Every mutant is still fully evaluated. So after your type change, if any test exercises read(0) the mutant dies and reports as killed — the entry cannot hide it. It hides something only when no test distinguishes the two, which is a real test gap, but a narrower one than "precommit passes and the mutant is silently ignored".

I did implement your suggestion: fingerprint the enclosing function's head (everything before its body, so parameters and their types count and the body does not). It works — and it costs more than it buys:

  • It invalidates far too much. Adding or renaming any parameter changes the head, so every entry in that function's body goes stale, including ones whose proof has nothing to do with the new parameter. My own test survives a same-kind mutant inserted above it failed immediately, because it adds a parameter.
  • It still misses most of the class. I counted: 166 of the 535 recorded reasons rest on a type that comes from a call's return, a database row, or an imported shape — getWebhookSignatureHeader → null|truthy, intent.allocations is an array or undefined, amount is bigint|undefined. A function head cannot see any of those.

So it would close a minority of cases while making the gate noisy enough that people learn to re-record stale entries without re-reading the proof — which makes the registry less trustworthy, not more.

The honest statement is that an anchor is a syntactic identity for which mutant this is, and it cannot be a validity check on a type-based proof, because the types come from all over the codebase. Re-proving needs a different mechanism, and the TODO says what I think it looks like: give mutation:audit-equivalents a way to attempt a distinguishing input, or a re-audit stamp so an entry has to be re-confirmed rather than resting on a proof nobody has re-read since it was written.


Generated by Claude Code

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.

Two more unused exports from this PR are now private as well — EquivalentCheckOptions and AnchoredMutant. Same slip as RawMutant and ANCHOR_PATTERN: I exported the types I happened to name while splitting things up, without checking anything imported them.

Replying here rather than on those threads only because they are the same point; each is fixed.


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. Nothing in the code tells those
* apart, so they fall back to source order as `@1`, `@2` — the one part of an
* anchor a reordering can move, and the reason names are collected as finely
* as they are. Anything short of that 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

};
});
};
121 changes: 121 additions & 0 deletions scripts/mutation/check-equivalents.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
/**
* 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 {
listRegistryFiles,
mutantKeyForPath,
parseRegistryText,
registryFilePath,
} from "./ignore.ts";

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