diff --git a/web/src/api/pageSizeCallSites.guard.test.ts b/web/src/api/pageSizeCallSites.guard.test.ts new file mode 100644 index 000000000..244f9217d --- /dev/null +++ b/web/src/api/pageSizeCallSites.guard.test.ts @@ -0,0 +1,448 @@ +import { describe, expect, it } from 'vitest'; +import { pageSizeSiteId, scanPageSizeSites } from './pageSizeScan'; + +/** + * #650 guard: an ENUMERATING allow-list over every `pageSize` call site in the SPA. + * + * #644 fixed every call site that requested an OVER-cap `pageSize` (e.g. `pageSize: 1000`) to + * "get everything in one call" — a pattern that silently truncates to the server's `MaxPageSize` + * (100 today) with no error and no truncation indicator. #644's own completeness check (box 4) + * was a manual grep for an inflated `pageSize`, which is why it could not see #650: two call + * sites requesting EXACTLY the cap (100) truncate exactly as much as an over-cap request, they + * just don't match a "pageSize above the cap" pattern. + * + * So this guard does NOT pattern-match on the pageSize VALUE (that repeats the #644 mistake for + * the next magic number). It enumerates every `pageSize` property inside a real object-literal + * expression via `scanPageSizeSites` (the TypeScript compiler API — see `pageSizeScan.ts`'s doc + * comment for why a hand-rolled text/regex scan was replaced) and cross-checks the discovered set + * against a hand-reviewed registry below, in BOTH directions: + * - a NEWLY discovered, unregistered site fails (a new call site was added without a documented + * classification — the exact way #650 could recur invisibly); + * - a REGISTERED site no longer discovered fails (the registry has gone stale — e.g. a site was + * removed or refactored to no longer pass a `pageSize` property, and the registry should + * shrink to match, not silently claim coverage of code that no longer exists). + * Both directions are computed and reported in a SINGLE combined failure message (not two + * sequential `expect` calls) — an early throw would otherwise hide the second direction's result + * in the same run, understating what actually needs fixing. + * + * **Identity is per-OCCURRENCE** (line + column from the real AST position, #650 follow-up F5/M-6): + * two `pageSize` properties on the same line (e.g. both branches of a ternary) get distinct + * identities because each has its own token position. Comparison is by MULTISET count, not just + * set membership, so an accidental duplicate registry entry — or, in principle, two structurally + * identical sites colliding on identity — is still caught rather than one occurrence silently + * covering both. + * + * `scanPageSizeSites` itself is verified against inline fixture source strings covering every + * input class a text-level scanner previously got wrong (comment-in-string, template + * interpolation, ternary, `??`, JSX container, same-line duplicates, parameter/nested + * destructuring, a type literal, a string containing the text `pageSize: 100`) in + * `pageSizeScan.test.ts` — that test does not depend on the real repo, so it protects the SCANNER + * itself, not just today's snapshot of call sites. + * + * Each registry entry classifies the site per `docs/spa-conventions.md` §3b / + * `docs/decisions/records/spa/list-completeness-vs-bounded-pickers.md`: + * - 'class-a' — bounded-by-construction list, paged to completeness via `loadAllPages` (or, + * for the two sites INSIDE `loadAllPages` itself, its implementation), with a + * `complete`/`incomplete` flag surfaced (never silently partial). + * - 'class-b' — media-library-scoped picker: one bounded page at (or under) the cap, with the + * real truncation (`totalCount` vs items shown) surfaced to the user. + * - 'paged-ui' — real paging UI (a page/"load more" control, or a user-adjustable page-size + * selector, keyed to a genuine `totalCount`), so a `pageSize` at or below the + * cap is correct as-is. + * + * **Known residual gap:** object SPREAD (`getFoo({ ...opts })` where `opts` was built elsewhere + * with an at-cap `pageSize`) and a `pageSize` passed as a bare POSITIONAL argument rather than an + * object-literal property (`api/search.ts`'s `getAllSearchItemIds(query, pageNum, pageSize)`, the + * api.search-allitems-paging precedent) are NOT resolvable by this scan — there is no `pageSize` + * token inside an object-literal expression to find. Written down here, not silently absent: a + * call site introduced through either path needs a human re-grep if that shape becomes common. + */ + +interface RegistryEntry { + file: string; + line: number; + column: number; + kind: 'literal' | 'shorthand'; + value: string; + classification: 'class-a' | 'class-b' | 'paged-ui'; + note: string; +} + +// Keep in file order, then position order, so a diff against the discovered set is easy to read. +const REGISTRY: RegistryEntry[] = [ + { + file: 'api/paging.ts', + line: 83, + column: 62, + kind: 'shorthand', + value: 'pageSize', + classification: 'class-a', + note: + "loadAllPages's own first-page fetch. This IS the Class A completeness helper every other " + + 'bounded list uses — not a defect, the fix itself.' + }, + { + file: 'api/paging.ts', + line: 93, + column: 60, + kind: 'shorthand', + value: 'pageSize', + classification: 'class-a', + note: "loadAllPages's subsequent-page fetch inside the completeness loop; same helper as line 83." + }, + { + file: 'builder/ChannelBuilder.tsx', + line: 427, + column: 79, + kind: 'literal', + value: '100', + classification: 'class-b', + note: + 'SeasonsDialog: TelevisionSeason browse scoped to one show (parentId). No real show has ' + + "100+ seasons, so this stays a single bounded page rather than paging to completeness — " + + "but #650 found the response's totalCount went unread; it is now surfaced as a " + + "'Showing the first N of M seasons' hint if a show somehow exceeds the cap." + }, + { + file: 'builder/libraryBrowse.ts', + line: 46, + column: 98, + kind: 'shorthand', + value: 'pageSize', + classification: 'paged-ui', + note: + "loadCollections's per-kind fan-out (#650 fix): forwards a real pageNum/pageSize from the " + + "caller and sums each kind's real totalCount, so the builder's Load more button (canLoadMore) " + + 'is meaningful — this is the paged-ui replacement for the original truncating implementation.' + }, + { + file: 'builder/libraryBrowse.ts', + line: 73, + column: 9, + kind: 'shorthand', + value: 'pageSize', + classification: 'paged-ui', + note: "loadLibraryItems's per-kind fan-out — same real pageNum/pageSize/totalCount pattern as loadCollections above." + }, + { + file: 'builder/SmartCollectionDialog.tsx', + line: 92, + column: 52, + kind: 'literal', + value: '24', + classification: 'class-b', + note: + 'Inline smart-query preview: a small bounded sample (well under the 100 cap) shown while ' + + 'authoring a query; the query itself is the narrowing mechanism, not paging.' + }, + { + file: 'screens/AutoTuneScreen.tsx', + line: 1527, + column: 105, + kind: 'literal', + value: 'MEMBER_PREVIEW_SIZE', + classification: 'class-b', + note: "Channel-member preview; renders 'showing first N' once totalCount exceeds the preview size." + }, + { + file: 'screens/AutoTuneScreen.tsx', + line: 1556, + column: 67, + kind: 'literal', + value: 'ADD_SOURCE_RESULTS', + classification: 'class-b', + note: 'Tiny (8-row) debounced add-source search preview, far under the cap; query narrows results.' + }, + { + file: 'screens/BlockPlayoutTroubleshootingScreen.tsx', + line: 161, + column: 76, + kind: 'shorthand', + value: 'pageSize', + classification: 'paged-ui', + note: + 'Playout block history: forwards a user-adjustable `pageSize` state (persisted, backed by a ' + + 'page-size ) to a real pager keyed off the response totalCount.' + }, + { + file: 'screens/MediaBrowseScreen.tsx', + line: 119, + column: 92, + kind: 'literal', + value: 'PAGE_SIZE', + classification: 'paged-ui', + note: 'Library browse grid has a real page-number pager driven off the real totalCount.' + }, + { + file: 'screens/MediaDetailScreen.tsx', + line: 267, + column: 49, + kind: 'literal', + value: 'CHILD_PAGE_SIZE', + classification: 'paged-ui', + note: 'Season/episode child list has a real page-number pager driven off the real totalCount.' + }, + { + file: 'screens/PlaylistsScreen.tsx', + line: 193, + column: 76, + kind: 'literal', + value: 'LIBRARY_BROWSE_PAGE_CAP', + classification: 'class-b', + note: 'Media-library picker pattern shared with RerunCollectionsScreen, for playlist entries.' + }, + { + file: 'screens/RerunCollectionsScreen.tsx', + line: 146, + column: 76, + kind: 'literal', + value: 'LIBRARY_BROWSE_PAGE_CAP', + classification: 'class-b', + note: + 'Media-library picker backing a rerun-collection