From ad4ac6c7e0b33e9e4a40c7038badb7546f32ed98 Mon Sep 17 00:00:00 2001 From: Timothy Date: Sun, 26 Jul 2026 23:12:09 +0200 Subject: [PATCH 1/7] fix(650): page Trakt lists to completeness and report real totals in loadCollections Two SPA list loads requested EXACTLY the server's pageSize cap (100), truncating identically to #634/#644's over-cap defect but invisible to that fix's manual "pageSize above the cap" grep: - TraktListsScreen requested pageSize:100 and rendered BOTH the truncated page AND the real totalCount, so 101 lists showed as "101 lists" over a 100-row table. Trakt lists are bounded-by-construction (Class A), so this now pages to completeness via the shared loadAllPages helper, surfaces an "incomplete" badge if a page ever comes back short of totalCount, and passes an AbortSignal from the effect cleanup. - ChannelBuilder's loadCollections (fanning out per collection kind) reported the truncated merged.length as totalCount, so canLoadMore's `items.length < totalCount` comparison was permanently false and "load more" could never fire. It now sums the real per-kind totalCount, mirroring the existing loadLibraryItems pattern in the same file, and canLoadMore is no longer gated to the 'library' source only. Also found and fixed a third at-cap site not named in #650: ChannelBuilder's SeasonsDialog (TelevisionSeason browse scoped to one show) reads pageSize:100 but never read the response's totalCount. No real show has 100+ seasons, so this stays a single bounded page (Class B) rather than paging to completeness, but now surfaces a "Showing the first N of M seasons" hint instead of silently truncating if a show somehow exceeds the cap. Codifies the missing completeness guard as an enumerating allow-list vitest test (web/src/api/pageSizeCallSites.guard.test.ts): scans every `pageSize:` call site in the SPA and diffs it against a hand-reviewed registry in both directions (unregistered site = new defect risk, stale entry = registry rot), with anti-vacuity floors on files-scanned and sites-discovered. Verified the guard actually fails on a planted defect and a planted stale entry before finalizing it. No server-side change: the client pages, the server stays bounded (api.search-allitems-paging precedent). --- web/src/api/pageSizeCallSites.guard.test.ts | 228 ++++++++++++++++++++ web/src/builder/ChannelBuilder.test.tsx | 91 ++++++++ web/src/builder/ChannelBuilder.tsx | 76 +++++-- web/src/screens/TraktListsScreen.test.tsx | 110 ++++++++++ web/src/screens/TraktListsScreen.tsx | 42 +++- 5 files changed, 515 insertions(+), 32 deletions(-) create mode 100644 web/src/api/pageSizeCallSites.guard.test.ts create mode 100644 web/src/screens/TraktListsScreen.test.tsx diff --git a/web/src/api/pageSizeCallSites.guard.test.ts b/web/src/api/pageSizeCallSites.guard.test.ts new file mode 100644 index 000000000..1d01c7a4f --- /dev/null +++ b/web/src/api/pageSizeCallSites.guard.test.ts @@ -0,0 +1,228 @@ +import { readFileSync, readdirSync } from 'node:fs'; +import { dirname, join, relative } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { describe, expect, it } from 'vitest'; + +/** + * #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 call site that passes a literal `pageSize:` — a + * number literal or a const identifier that resolves to one — 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 literal pageSize, and the registry should shrink + * to match, not silently claim coverage of code that no longer exists). + * + * 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`, + * 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 keyed to a genuine + * `totalCount`), so a `pageSize` at or below the cap is correct as-is. + */ + +interface RegistryEntry { + file: string; + value: string; + classification: 'class-a' | 'class-b' | 'paged-ui'; + note: string; +} + +// Keep in file order, then line order, so a diff against the discovered set is easy to read. +const REGISTRY: RegistryEntry[] = [ + { + file: 'builder/ChannelBuilder.tsx', + 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/SmartCollectionDialog.tsx', + 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/CollectionsScreen.tsx', + value: '50', + classification: 'class-b', + note: + 'AddItemsDialog per-kind library search preview (well under the 100 cap): a typed query ' + + 'narrows results; capped to a slice(0, 50) preview by design, not a truncated "whole list".' + }, + { + file: 'screens/MediaDetailScreen.tsx', + 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/MediaBrowseScreen.tsx', + value: 'PAGE_SIZE', + classification: 'paged-ui', + note: 'Library browse grid has a real page-number pager driven off the real totalCount.' + }, + { + file: 'screens/TrashScreen.tsx', + value: 'PAGE_SIZE', + classification: 'paged-ui', + note: 'Per-group trash listing; "See all N" load-more gated on totalCount > items.length.' + }, + { + file: 'screens/SearchScreen.tsx', + value: 'PAGE_SIZE', + classification: 'paged-ui', + note: 'Per-group search results; hasMore gated on totalCount > items.length with a load-more.' + }, + { + file: 'screens/RerunCollectionsScreen.tsx', + value: 'LIBRARY_BROWSE_PAGE_CAP', + classification: 'class-b', + note: + 'Media-library picker backing a rerun-collection ) to a real pager keyed off the response totalCount.' + }, { file: 'screens/CollectionsScreen.tsx', + line: 234, + kind: 'literal', value: '50', classification: 'class-b', note: @@ -69,31 +164,51 @@ const REGISTRY: RegistryEntry[] = [ 'narrows results; capped to a slice(0, 50) preview by design, not a truncated "whole list".' }, { - file: 'screens/MediaDetailScreen.tsx', - value: 'CHILD_PAGE_SIZE', + file: 'screens/FillerPresetsScreen.tsx', + line: 501, + kind: 'literal', + value: 'LIBRARY_BROWSE_PAGE_CAP', + classification: 'class-b', + note: 'Media-library picker pattern shared with RerunCollectionsScreen, for filler preset content.' + }, + { + file: 'screens/LogsScreen.tsx', + line: 106, + kind: 'shorthand', + value: 'pageSize', classification: 'paged-ui', - note: 'Season/episode child list has a real page-number pager driven off the real totalCount.' + note: + 'Log listing: forwards a user-adjustable `pageSize` state (persisted, backed by a page-size ' + + '