diff --git a/AGENTS.md b/AGENTS.md index 8722af971e..11581b706e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,7 +79,7 @@ as-is and skips the download, so `deno task test`, `deno task test:files`, and - **No alias exports — expose the shared mechanism itself**: Never export a name that is just another name for an existing method (`export const getChildIds = byParent.getIds`). Expose the underlying helper/object directly and let callers use it (`listingChildren.getIds(parentId)`). Exposing our internals is a feature: it encourages us to make them universal, understandable, and neat, while an alias layer hides the one shared mechanism behind per-module vocabulary and gives the same behavior two names. A thin wrapper that *adds* something — a default, a transformation, a guard — is not an alias and is fine. - **No internal compatibility layers**: We own every internal caller. When replacing an internal API, migrate every caller in the same change and delete the old surface instead of keeping wrappers, aliases, re-exports, or "compatibility" shims. Keep adapters only at true external boundaries (provider APIs, serialized data/import formats, browser/platform contracts) or for an explicitly staged data migration with a named removal path. - **Remove dead code — always the answer**: When code has no production caller — an unused export, an unreferenced helper, a guard/page whose only consumer is itself unused, an unreachable branch — delete it. Removal is *always* the right call; never keep it "for symmetry" or "for future use" (add it back when the future arrives, from git history), and never paper over it with a test-only import or a lint/usage-check exemption. If a check surfaces an export that's used only by tests, that's a signal the export is dead, not a reason to allow-list it: remove the export (and its now-pointless test). A symmetric-but-unused API is still dead code. The reference: `agentPage`/`requireAgentOr` were an agent-only page+guard pair with no route wiring (agents are gated via `deliveryPage`/`requireDeliveryOr`), so both were deleted rather than exempted. -- **Keep files under ~400 lines**: When refactoring a file, aim to keep it under 400 lines — and if hitting that target means splitting one file into several, so be it: a new file is cheaper than an overloaded one. When you end up with a handful of files all about the same thing, group them in a folder and give them shorter names that don't repeat the folder's name (`ledger/project.ts`, not `ledger/ledger-project.ts` — see the `src/shared/ledger/` and `src/shared/db/attendees/` examples in [Modularised](#modularised)). While you're at it, use the split as a chance to separate pure from non-pure code — push the data-in/data-out logic into its own file and keep the IO in a thin shell (see [Pure, functional](#pure-functional)). **The same 400-line limit applies to test files**, and matters just as much: smaller, more specific test files let us run mutation tests far faster, because a source file's mutants only need to run against the narrow test file that covers it, not one giant suite. Biome enforces a hard 1,000-line ceiling as a lint error (`nursery.noExcessiveLinesPerFile` in `biome.json`); files that predate the rule are grandfathered in a `biome.json` override list — when you split one, delete its entry, and never add a new entry. (Expect a known side effect when splitting: jscpd cannot fully scan very large files, so a split routinely *surfaces* duplication that was silently passing inside the monolith — budget for extracting helpers, not just moving tests.) +- **Keep files under ~400 lines**: When refactoring a file, aim to keep it under 400 lines — and if hitting that target means splitting one file into several, so be it: a new file is cheaper than an overloaded one. When you end up with a handful of files all about the same thing, group them in a folder and give them shorter names that don't repeat the folder's name (`ledger/project.ts`, not `ledger/ledger-project.ts` — see the `src/shared/ledger/` and `src/shared/db/attendees/` examples in [Modularised](#modularised)). While you're at it, use the split as a chance to separate pure from non-pure code — push the data-in/data-out logic into its own file and keep the IO in a thin shell (see [Pure, functional](#pure-functional)). **The same 400-line limit applies to test files**, and matters just as much: smaller, more specific test files let us run mutation tests far faster, because a source file's mutants only need to run against the narrow test file that covers it, not one giant suite. Biome enforces a hard 1,000-line ceiling as a lint error (`nursery.noExcessiveLinesPerFile` in `biome.json`); it applies to every file, with no exceptions — never add an override to let one file past it. (Expect a known side effect when splitting: jscpd cannot fully scan very large files, so a split routinely *surfaces* duplication that was silently passing inside the monolith — budget for extracting helpers, not just moving tests.) - **Good citizen — fix what you spot**: If you notice a bug, a coverage gap, or a flaky/fragile test while working — even in code you were not asked to touch and did not write — fix it in passing rather than stepping around it. A green build you helped produce is your responsibility too. - **Every bug fix ships with a regression test**: Never fix a bug without also adding a test that fails before the fix and passes after it. The test must exercise the real bug — reproduce the exact condition that was broken so it would have caught the original defect — not merely touch the changed lines for coverage. Write the failing test first, confirm it fails for the right reason, then apply the fix and watch it go green. This locks the bug out for good and proves the fix actually addresses it. - **Offensive, not defensive, programming**: Fail loudly and immediately instead of tolerating bad states — never suppress, default away, or paper over an error. See [Offensive Programming](#offensive-programming--never-suppress-errors) for the full rules. diff --git a/TODO.md b/TODO.md index 4090338d58..9a75e44a31 100644 --- a/TODO.md +++ b/TODO.md @@ -806,10 +806,10 @@ and profile the top entry. *Origin: review of PR #1796 (the `[object Object]` error-box fix). Flagged by CodeRabbit while that PR hardened the questions template's mutation coverage.* -`test/ui/templates/admin/questions.test.ts` is ~876 lines — over the ~400-line +`test/ui/templates/admin/questions.test.ts` is ~862 lines — over the ~400-line target for test files (it was already ~795 before #1796 added the hardening -assertions; it stays under Biome's 1,000-line hard limit, so it is not -grandfathered and CI passes). Smaller, focused test files also let mutation +assertions; it stays under Biome's 1,000-line hard limit, so CI passes). +Smaller, focused test files also let mutation runs map `questions.tsx` to a narrower suite. Split it into focused sibling suites sharing one fixtures helper, roughly: @@ -1407,7 +1407,7 @@ requires mirror-located direct tests). Two of the moved files are over the `deno task test:files test/features/admin/auth/*.ts` after the split to confirm coverage stays at 100%. -- **`test/ui/templates/checkin.test.ts` (533 lines).** Was +- **`test/ui/templates/checkin.test.ts` (523 lines).** Was `test/lib/server-checkin.test.ts` (499 lines on `main`) — the move grew it slightly via the row-scoped assertion rewrite in `64475d4f`. Covers GET/POST `/checkin/:tokens` rendering, column visibility, check-in/out flows, @@ -1419,7 +1419,7 @@ requires mirror-located direct tests). Two of the moved files are over the duplicating it across the split files. Both files are well under the Biome hard 1,000-line ceiling -(`noExcessiveLinesPerFile`), so neither is in the `biome.json` override list. +(`noExcessiveLinesPerFile`), so CI passes on both today. Splitting them now was deliberately deferred because doing it inside the cold-start PR would balloon the diff with unrelated mechanical test moves and re-conflict with the import-only changes that are the actual subject of the diff --git a/scripts/mutation/equivalent-mutants.txt b/scripts/mutation/equivalent-mutants.txt index 6c4020dc8f..d26e7cd2e6 100644 --- a/scripts/mutation/equivalent-mutants.txt +++ b/scripts/mutation/equivalent-mutants.txt @@ -114,9 +114,9 @@ src/fp.ts:455:49 ?? → || # items?.length is undefined or a non-negative int # undefined, paired null checks already reject both nullish values, optional # conditions/dependencies are objects or arrays, and non-generated primary keys # are overwritten from the input-column fold in either initial-row branch. -src/shared/db/table.ts:508:24 ?: → consequent only # generated keys use the consequent; non-generated keys are overwritten by their input-column value -src/shared/db/table.ts:548:28 ?? → || # condition?.args is an array or undefined, and every array is truthy -src/shared/db/table.ts:720:32 ?? → || # dependsOn is a readonly array or undefined, and every array is truthy +src/shared/db/table.ts:521:24 ?: → consequent only # generated keys use the consequent; non-generated keys are overwritten by their input-column value +src/shared/db/table.ts:561:28 ?? → || # condition?.args is an array or undefined, and every array is truthy +src/shared/db/table.ts:733:32 ?? → || # dependsOn is a readonly array or undefined, and every array is truthy # Login attempt rows store an integer count. For undefined, null, zero, or any # non-zero integer, `(attempts ?? 0) + 1` and `(attempts || 0) + 1` agree. @@ -245,8 +245,8 @@ test/test-utils/test-browser.ts:80:73 ?? → || # find(): LinkMatch|undefined test/test-utils/test-browser.ts:100:26 ?? → || # missing input type defaults to text; empty/invalid type follows the same successful-input path as text test/test-utils/test-browser.ts:150:19 ?? → || # submitted option tags are non-empty strings when present, otherwise undefined test/test-utils/test-browser.ts:256:49 ?? → || # button value fallback is "", so empty value and absent value agree -test/test-utils/test-browser.ts:351:58 ?? → || # RequestInit.method is omitted or a non-empty method string in every caller -test/test-utils/test-browser.ts:414:28 ?? → || # forms[0] is a FormInfo object when present, otherwise undefined +test/test-utils/test-browser.ts:357:58 ?? → || # RequestInit.method is omitted or a non-empty method string in every caller +test/test-utils/test-browser.ts:422:28 ?? → || # forms[0] is a FormInfo object when present, otherwise undefined, so both operators reach throwNoForm() on the same input src/ui/templates/admin/listing-defaults.tsx:105:17 ?? → || # UrlControl value: string|undefined; the only falsy-non-null string is "" which equals the "" fallback, so ?? and || coincide src/ui/templates/admin/listing-defaults.tsx:128:38 ?? → || # value?.includes(day): boolean|undefined; for boolean b, b ?? false === b || false, and undefined ?? false === undefined || false src/shared/booking/build-tree.ts:130:48 ?? → || # childrenByParentId?.get(): readonly TicketListing[]|undefined — an array is always truthy, so ?? and || coincide @@ -267,8 +267,8 @@ src/shared/booking/capacity-tree.ts:38:45 ?? → || # groupIdsByListingId.ge # Attendee group-capacity lookups: Map values are arrays (always truthy), and # duration normalization clamps both a default of 0 and 1 to one day. -src/shared/db/attendees/capacity/groups.ts:134:50 ?? → || # rowsByGroup.get(): GroupRow[]|undefined — an array is always truthy -src/shared/db/attendees/capacity/groups.ts:145:14 1 → 0 # expandDailyRange normalizes both 0 and 1 to a one-day span +src/shared/db/attendees/capacity/groups.ts:135:50 ?? → || # rowsByGroup.get(): GroupRow[]|undefined — an array is always truthy +src/shared/db/attendees/capacity/groups.ts:146:14 1 → 0 # expandDailyRange normalizes both 0 and 1 to a one-day span # v2 signed metadata (Phase 2d). src/shared/payment-helpers.ts:196:24 ?? → || # toBookingItems intent.allocations: ChildAllocation[]|undefined — an array is always truthy, undefined→[] either way @@ -447,8 +447,8 @@ src/features/admin/questions.ts:146:7 answerText → "" # answerTextForm con # operand exists to coerce. # The generated WASM modules terminate every statement with punctuation, so # joining their source lines with "" or ";" parses and behaves identically. -scripts/inline-jsquash-wasm.ts:54:21 ; → "" # inline module remains semicolon/brace delimited -scripts/inline-jsquash-wasm.ts:76:38 ; → "" # remote module remains semicolon/brace delimited +scripts/inline-jsquash-wasm.ts:53:21 ; → "" # inline module remains semicolon/brace delimited +scripts/inline-jsquash-wasm.ts:75:38 ; → "" # remote module remains semicolon/brace delimited # sort-listings.ts's tier constants (0/1/2 for no-date-standard/dated- # standard/daily) and the "date === ''" empty-date sentinel: Array.sort only @@ -881,7 +881,7 @@ src/shared/runtime.ts:68:18 ?? → || # os is string|undefined and falls back src/shared/runtime.ts:70:43 ?? → || # typescriptVersion is string|undefined and falls back to "", so both operators agree src/shared/runtime.ts:71:38 ?? → || # userAgent is string|undefined and falls back to "", so both operators agree src/shared/square.ts:312:21 ?: → consequent only # the buyer_phone_number ternary spreads {} when the phone is absent; the consequent-only mutant always spreads { buyer_phone_number: undefined }, but JSON.stringify omits undefined values, so the serialized request body is identical in both cases -src/shared/square.ts:783:37 ?? → || # locations is an array or undefined; arrays are truthy and undefined takes [] under both operators +src/shared/square.ts:795:37 ?? → || # locations is an array or undefined; arrays are truthy and undefined takes [] under both operators src/ui/client/dom.ts:13:19 = → += # createElement returns a new button with className "", so both assignments produce the supplied class string # Paid-payment processing: private defaults are always supplied by their only @@ -969,14 +969,14 @@ scripts/mutation/summary.ts:65:69 ?? → || # Object.groupBy gives each statu scripts/mutation/summary.ts:92:33 ?? → || # the survivors group is an array when present, so ?? [] and || [] pick the same list # Lock file: the handle exists only to carry the advisory lock. -scripts/lock-file.ts:4:41 true → false # nothing ever reads or writes through this handle, so opening it write-only still takes and releases the same lock +scripts/lock-file.ts:16:41 true → false # nothing ever reads or writes through this handle, so opening it write-only still takes and releases the same lock # Process helpers: the timer handle before the timer exists. scripts/process.ts:60:17 0 → 1 # the promise body runs straight away and overwrites this handle, so its starting value is never the one cleared scripts/process.ts:62:12 = → += # the handle starts at 0, so adding to it and replacing it store the same timer id # Isolated mutation runs: the exit code before any path has set one. -scripts/mutation/isolation.ts:197:18 1 → 0 # every path overwrites this before it is returned: the lock always runs its callback, which either sets 130 on an interrupt or hands back a child whose status sets the code, and any throw is caught and sets it there +scripts/mutation/isolation.ts:127:18 1 → 0 # every path overwrites this before it is returned: the lock always runs its callback, which either sets 130 on an interrupt or hands back a child whose status sets the code, and any throw is caught and sets it there src/shared/db/migrations.ts:254:49 ?? → || # opts.allowMissingSettings is boolean | undefined, and false ?? false and false || false both yield false # Cucumber runs: telling Cucumber to be strict, when we already reject the diff --git a/test/shared/request-batch-cache.test.ts b/test/shared/request-cache/batch.test.ts similarity index 100% rename from test/shared/request-batch-cache.test.ts rename to test/shared/request-cache/batch.test.ts