fix(650): two at-cap list truncations, and a completeness guard that keys on the defect #675

Merged
timothy merged 7 commits from fix/650-at-cap-truncation into main 2026-07-27 08:08:14 +02:00
8 changed files with 1748 additions and 158 deletions
+448
View File
@@ -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 <Select>) to a real pager keyed off the response totalCount.'
},
{
file: 'screens/CollectionsScreen.tsx',
line: 234,
column: 58,
kind: 'literal',
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/FillerPresetsScreen.tsx',
line: 501,
column: 67,
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,
column: 32,
kind: 'shorthand',
value: 'pageSize',
classification: 'paged-ui',
note:
'Log listing: forwards a user-adjustable `pageSize` state (persisted, backed by a page-size ' +
'<Select>) 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 <select>; single bounded page with a ' +
"'Showing the first N of M — use search to narrow' hint (list-completeness-vs-bounded-pickers)."
},
{
file: 'screens/SearchScreen.tsx',
line: 118,
column: 40,
kind: 'literal',
value: 'PAGE_SIZE',
classification: 'paged-ui',
note: 'Per-group search results; hasMore gated on totalCount > items.length with a load-more.'
},
{
file: 'screens/TrashScreen.tsx',
line: 82,
column: 44,
kind: 'literal',
value: 'PAGE_SIZE',
classification: 'paged-ui',
note: 'Per-group trash listing; "See all N" load-more gated on totalCount > items.length.'
},
{
file: 'screens/TrashScreen.tsx',
line: 113,
column: 79,
kind: 'literal',
value: 'PAGE_SIZE',
classification: 'paged-ui',
note: 'Same per-group trash listing as line 82, the load-more request handler.'
}
];
// Enumerates every source file under `src/` via Vite's `import.meta.glob` — eagerly, as raw text
// (`query: '?raw', import: 'default'`) — INSTEAD OF Node's `fs`/`path`/`url` (#650 follow-up).
// This is the only file under `src` that ever needed real filesystem access, and `@types/node`
// isn't wired into `tsconfig.app.json`'s project (deliberately: it covers production browser code
// too, and a file-local `/// <reference types="node" />` was tried and reverted — under `tsc -b`'s
// single-program compilation it leaked Node's ambient `setTimeout` into the whole app project,
// breaking three unrelated `window.setTimeout` mocks that expect the DOM signature). `import.meta
// .glob` needs neither `node:fs` nor a tsconfig change: it's resolved by Vite at transform time,
// natively available in the browser/app project, and is the idiomatic Vite/vitest way to enumerate
// source files. Keys are POSIX paths from the project root, e.g. `/src/api/pageSizeScan.ts`.
const rawSourceModules = import.meta.glob('/src/**/*.{ts,tsx,mts,cts}', {
query: '?raw',
import: 'default',
eager: true
}) as Record<string, string>;
function basename(path: string): string {
const idx = path.lastIndexOf('/');
return idx === -1 ? path : path.slice(idx + 1);
}
// Extracted from `listSourceFiles`'s inline condition so it's independently testable (#650
// follow-up round 4): a plant that adds a real `.mts` FILE and observes the guard notice it
// proves the behavior exists today, but pins nothing — revert the glob back to `.ts`/`.tsx` and
// both the real-source guard AND `pageSizeScan.test.ts`'s `.mts`/`.cts` PARSING tests stay green,
// because this repo has no committed `.mts`/`.cts` source and `scanPageSizeSites` parses any
// non-`.tsx` filename as plain TS regardless of extension. Testing this predicate directly, by
// filename, is what actually regression-pins the file-discovery fix rather than depending on the
// repo happening to contain (or not contain) a matching file. This predicate is still what the
// glob's results are filtered THROUGH below (`listSourceFiles`) — the extension SET moved into the
// glob literal, but discovery still runs every matched file through this same named, tested
// function, not a second copy of the logic.
export function isScannableSourceFileName(name: string): boolean {
// `.mts`/`.cts` are legal TS extensions `tsconfig.app.json`'s `include` covers alongside
// `.ts`/`.tsx` — none exist in this repo today, but the glob must not silently skip one if it
// ever does (#650 follow-up round 3 MEDIUM finding).
return (
/\.(ts|tsx|mts|cts)$/.test(name) && !/\.test\.(tsx?|mts|cts)$/.test(name) && !name.endsWith('.guard.test.ts')
);
}
interface ScannableSource {
/** Path relative to `src/`, e.g. `api/pageSizeScan.ts` — matches the REGISTRY's `file` field. */
file: string;
text: string;
}
function listSourceFiles(): ScannableSource[] {
const out: ScannableSource[] = [];
for (const [key, text] of Object.entries(rawSourceModules)) {
if (key.includes('/generated/')) {
continue;
}
if (!isScannableSourceFileName(basename(key))) {
continue;
}
out.push({ file: key.replace(/^\/src\//, ''), text });
}
return out;
}
interface DiscoveredSite {
file: string;
line: number;
column: number;
kind: 'literal' | 'shorthand';
value: string;
}
function discoverPageSizeCallSites(): DiscoveredSite[] {
const sites: DiscoveredSite[] = [];
for (const { file, text } of listSourceFiles()) {
for (const site of scanPageSizeSites(text, file)) {
sites.push({ file, ...site });
}
}
return sites;
}
function fullId(site: { file: string; line: number; column: number; kind: string; value: string }): string {
return `${site.file}:${pageSizeSiteId(site)}`;
}
// Multiset (count per identity) comparison, not plain array `.includes` membership (#650
// follow-up M-6) — so a registry that accidentally lists the same identity twice, or a future
// scanner change that could (in principle) emit a duplicate, is still caught rather than one
// occurrence silently covering both.
function toCounts(ids: string[]): Map<string, number> {
const counts = new Map<string, number>();
for (const id of ids) {
counts.set(id, (counts.get(id) ?? 0) + 1);
}
return counts;
}
// Returns entries present in `left` more times than in `right`, expanded per the excess count —
// e.g. a `left` id appearing 3 times against 1 in `right` yields that id listed twice.
function multisetExcess(left: Map<string, number>, right: Map<string, number>): string[] {
const excess: string[] = [];
for (const [id, count] of left) {
const remaining = count - (right.get(id) ?? 0);
for (let i = 0; i < remaining; i++) {
excess.push(id);
}
}
return excess.sort();
}
// These 4 tests are BASELINE assertions about the guard's steady-state behavior against the
// current repo snapshot — they all pass equally on the clean `b90f8a3b` commit (before this
// round's scanner rewrite), so none of them individually PROVE this round's fixes. What actually
// regression-pins the scanner's fixes is `pageSizeScan.test.ts` (synthetic fixtures per input
// class, verified against the prior scanner where the review asked for it) — these 4 just confirm
// the guard, wired to whichever scanner it currently uses, still holds over real source.
describe('pageSize call-site guard (#650)', () => {
it.each([
['screens/TraktListsScreen.ts', true],
['builder/ChannelBuilder.tsx', true],
['builder/libraryBrowse.mts', true],
['api/pageSizeScan.cts', true],
['screens/TraktListsScreen.test.ts', false],
['builder/ChannelBuilder.test.tsx', false],
['builder/libraryBrowse.test.mts', false],
['api/pageSizeScan.test.cts', false],
['api/pageSizeCallSites.guard.test.ts', false],
['api/generated/v1.ts', true], // the predicate itself is filename-only; the 'generated' DIRECTORY exclusion lives in listSourceFiles, tested separately below.
['components.js', false],
['data.json', false],
['README.md', false],
['noextension', false]
])(
'isScannableSourceFileName(%s) === %s — the file-discovery predicate itself, independent of ' +
'whether the repo happens to contain a matching file (#650 follow-up round 4)',
(name, expected) => {
// A prior verification planted a REAL .mts file and observed the guard notice it — that
// proved the .mts/.cts fix works today, but pinned nothing: reverting the glob back to
// `.ts`/`.tsx` leaves both the real-source guard AND pageSizeScan.test.ts's .mts/.cts
// PARSING tests green, since this repo has no committed .mts/.cts source and the scanner
// parses any non-.tsx filename as plain TS regardless of extension. Asserting on the
// predicate BY FILENAME, with no filesystem involved, is what actually regression-pins it.
expect(isScannableSourceFileName(name)).toBe(expected);
}
);
it('scans a healthy number of source files (anti-vacuity: a broken glob must not pass on zero input)', () => {
const files = listSourceFiles();
expect(files.length).toBeGreaterThan(50);
});
it('discovers a healthy number of pageSize call sites (anti-vacuity: a broken scan must not pass on zero matches)', () => {
const sites = discoverPageSizeCallSites();
expect(sites.length).toBeGreaterThan(10);
});
it('matches the discovered pageSize call sites EXACTLY against the reviewed registry (not a non-empty check)', () => {
const discoveredCounts = toCounts(discoverPageSizeCallSites().map(fullId));
const registeredCounts = toCounts(REGISTRY.map(fullId));
const unregistered = multisetExcess(discoveredCounts, registeredCounts);
const stale = multisetExcess(registeredCounts, discoveredCounts);
// Both directions are folded into ONE assertion so a failure always shows the complete
// picture in a single run (#650 follow-up, line-churn concern) — two sequential `expect`
// calls would throw on the first failing direction and never evaluate/report the second.
if (unregistered.length > 0 || stale.length > 0) {
const report = [
`UNREGISTERED (${unregistered.length}) — discovered pageSize call site(s) missing from the REGISTRY above:`,
...unregistered.map((id) => ` + ${id}`),
`STALE (${stale.length}) — REGISTRY entries no longer found as a real pageSize call site:`,
...stale.map((id) => ` - ${id}`)
].join('\n');
throw new Error(report);
}
});
it('every registry entry documents its class per docs/spa-conventions.md §3b', () => {
for (const entry of REGISTRY) {
expect(['class-a', 'class-b', 'paged-ui']).toContain(entry.classification);
expect(entry.note.length).toBeGreaterThan(20);
}
});
});
+247
View File
@@ -0,0 +1,247 @@
import { describe, expect, it } from 'vitest';
import { pageSizeSiteId, scanPageSizeSites, type PageSizeSite } from './pageSizeScan';
/**
* Fixture test for `scanPageSizeSites` itself — NOT a scan of the real repo (that's
* `pageSizeCallSites.guard.test.ts`). This is what actually protects the SCANNER going forward:
* a prior hand-rolled regex/bracket-tracking version passed the guard test against unmodified
* source at both #650 commits while still being defeated by every case below, because the guard
* only ever exercised today's snapshot of real call sites — it never proved the scanner handles
* the INPUT CLASSES that expose a text-level scanner's blind spots. Pinning the exact discovered
* set against synthetic source strings closes that gap.
*
* Not every fixture here is a REGRESSION pin against the prior (round-1, `b90f8a3b`) bracket-
* tracking scanner — a round-3 review found that round 1's simple `pageSize:\s*value` regex
* already handled a bare URL-string or a bare `??` context correctly on its own (a `//` inside a
* string, or the token immediately before `{`, only mattered to round 1's OWN heuristics, not to
* a plain regex match). Those two are labelled CONTRACT fixtures below — they pin the documented
* behavior going forward, not a fix. The fixtures that genuinely fail against round 1 (verified)
* are: the string CONTAINING the literal text `pageSize: 100`, the template-literal
* interpolation, the same-line ternary identity/multiplicity, the JSX shorthand container,
* parameter destructuring, nested destructuring, and the type-literal declaration — plus the
* combined multi-case fixture, which fails round 1 for several of those reasons at once.
*/
function ids(sites: PageSizeSite[]): string[] {
return sites.map(pageSizeSiteId);
}
describe('scanPageSizeSites', () => {
it('finds a literal pageSize: property in a plain object-literal call argument', () => {
const source = `getFoo({ pageSize: 100, query });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:10:literal:100']);
});
it('finds the ES6 shorthand pageSize property in a plain object-literal call argument', () => {
const source = `getFoo({ pageSize, query });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:10:shorthand:pageSize']);
});
it('is NOT fooled by a "//" inside a string literal — CONTRACT fixture, not a round-1 regression pin (M-3)', () => {
// NOTE: round 1's unconditional literal regex (`pageSize:\s*(\d+|identifier)`) already
// matched this exact input correctly on its own — a `//` inside a string never confused THAT
// narrower pattern. This pins the AST scanner's documented contract going forward; it is the
// COMBINED multi-case fixture below (and the M-3-shaped case buried inside it — a literal
// `//` immediately preceding a real call site on the SAME conceptual scan) that actually
// fails against round 1's comment-stripping step, not this input in isolation.
const source = [`const endpoint = 'https://example.test';`, `getFoo({ pageSize: 100 });`, ''].join('\n');
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['2:10:literal:100']);
});
it('does NOT match a string literal that merely CONTAINS the text "pageSize: 100" (L-7)', () => {
const source = `const label = "pageSize: 100";\n`;
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('finds an object literal passed inside a template-literal interpolation (M-5)', () => {
const source = 'const url = `${await getFoo({ pageSize })}`;\n';
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:31:shorthand:pageSize']);
});
it('finds an object literal in each branch of a ternary, even on the SAME line (M-4, M-6)', () => {
const source = `return ok ? getA({ pageSize }) : getB({ pageSize });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
// Two distinct occurrences on one line get distinct identities (different columns) — a
// single registry entry cannot silently cover both.
expect(ids(sites)).toEqual(['1:20:shorthand:pageSize', '1:41:shorthand:pageSize']);
expect(sites[0].column).not.toBe(sites[1].column);
});
it('finds an object literal on the right-hand side of ?? — CONTRACT fixture, not a round-1 regression pin (M-4)', () => {
// NOTE: like the URL fixture above, round 1's literal-form regex already matched this exact
// `pageSize: 50` text correctly on its own — `??` doesn't change what characters precede the
// match on the line. This pins the documented contract, not a round-1 regression.
const source = `getFoo(options ?? { pageSize: 50 });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:21:literal:50']);
});
it('finds an object literal inside a JSX expression container attribute (M-4)', () => {
const source = `const el = <Component options={{ pageSize }} />;\n`;
const sites = scanPageSizeSites(source, 'fixture.tsx');
expect(ids(sites)).toEqual(['1:34:shorthand:pageSize']);
});
it('does NOT match a parameter destructuring pattern (L-7)', () => {
const source = `function f({ pageSize }: { pageSize: number }) {}\n`;
// The destructured PARAMETER `{ pageSize }` is an ObjectBindingPattern, not an
// ObjectLiteralExpression — excluded by node kind. Its TYPE annotation `{ pageSize: number }`
// is a TypeLiteral (PropertySignature), also excluded by node kind — never an object literal.
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('does NOT match a nested destructuring pattern (L-7)', () => {
const source = `const { nested: { pageSize } } = input;\n`;
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('does NOT match a type-literal declaration (L-7)', () => {
const source = `type P = { pageSize: 100 };\n`;
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('does NOT match an interface property declaration', () => {
const source = `interface Params {\n pageSize?: number;\n}\n`;
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('does NOT match a forwarded call expression (a dynamic passthrough, not a fixed value)', () => {
const source = `getFoo({ pageSize: String(pageSize) });\n`;
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('is not confused by a pageSize reference inside a comment', () => {
const source = [`// pageSize: 999 — this is just prose, not code`, `getFoo({ query });`, ''].join('\n');
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('is not confused by a pageSize reference inside a block/JSDoc comment', () => {
const source = ['/**', ' * Uses `pageSize` under the hood — see also `{ pageSize: 100 }`.', ' */', 'getFoo({ query });', ''].join(
'\n'
);
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('does NOT match a React dependency array containing pageSize', () => {
const source = `useCallback(load, [pageNum, pageSize, sortField]);\n`;
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('finds a const-identifier literal value (not just a numeric literal)', () => {
const source = `getFoo({ pageSize: LIBRARY_BROWSE_PAGE_CAP });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:10:literal:LIBRARY_BROWSE_PAGE_CAP']);
});
it('covers every case above together in one multi-line fixture and pins the exact discovered set', () => {
const source = [
`const endpoint = 'https://example.test';`, // M-3: not a comment
`const label = "pageSize: 100";`, // L-7: string contents, not code
`// pageSize: 999 in a line comment`, // not code
`/** block comment mentioning \`pageSize\` */`, // not code
`type P = { pageSize: 100 };`, // L-7: type literal, not a value
`interface Q { pageSize?: number; }`, // not a value
`function f({ pageSize }: { pageSize: number }) {}`, // L-7: destructuring + its type
`const { nested: { pageSize } } = input;`, // L-7: nested destructuring
`useCallback(load, [pageNum, pageSize]);`, // dependency array, not an object literal
`getFoo({ pageSize: String(pageSize) });`, // forwarded call, not a fixed value
`getFoo({ pageSize: 100 });`, // REAL: literal
`getBar({ pageSize });`, // REAL: shorthand
`getBaz(options ?? { pageSize: 50 });`, // REAL: ?? context (M-4)
`const url = \`\${await getQux({ pageSize })}\`;`, // REAL: template interpolation (M-5)
`return ok ? getA({ pageSize }) : getB({ pageSize });` // REAL x2: ternary, same line (M-4/M-6)
].join('\n');
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual([
'11:10:literal:100',
'12:10:shorthand:pageSize',
'13:21:literal:50',
'14:31:shorthand:pageSize',
'15:20:shorthand:pageSize',
'15:41:shorthand:pageSize'
]);
// Anti-vacuity: the fixture packs in 10 non-matching traps ahead of the 6 real sites — a
// scanner that matched everything (or nothing) would fail this count, not just the ids above.
expect(sites.length).toBe(6);
});
it('scans .tsx source using the TSX script kind (JSX does not parse under plain .ts rules)', () => {
const source = `export function C() {\n return <div data={{ pageSize: 10 }} />;\n}\n`;
const sites = scanPageSizeSites(source, 'fixture.tsx');
expect(ids(sites)).toEqual(['2:23:literal:10']);
});
// ---- round-3 MEDIUM finding: transparent TS wrappers around the initializer -----------------
it('finds a literal wrapped in "as const" (transparent to the runtime value)', () => {
const source = `getFoo({ pageSize: 100 as const });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:10:literal:100']);
});
it('finds a literal wrapped in "satisfies number" (transparent to the runtime value)', () => {
const source = `getFoo({ pageSize: 100 satisfies number });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:10:literal:100']);
});
it('finds a parenthesized literal', () => {
const source = `getFoo({ pageSize: (100) });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:10:literal:100']);
});
it('finds a const identifier through a chain of "as"/"satisfies"/parens wrappers', () => {
const source = `getFoo({ pageSize: ((LIBRARY_BROWSE_PAGE_CAP as number) satisfies number) });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:10:literal:LIBRARY_BROWSE_PAGE_CAP']);
});
it('still rejects a forwarded call expression even when wrapped in "as"', () => {
const source = `getFoo({ pageSize: String(pageSize) as string });\n`;
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
// ---- round-3 MEDIUM finding: non-Identifier property names -----------------------------------
it('finds a quoted string property key ("pageSize": 100)', () => {
const source = `getFoo({ 'pageSize': 100 });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:10:literal:100']);
});
it('finds a statically-resolvable computed property key (["pageSize"]: 100)', () => {
const source = `getFoo({ ['pageSize']: 100 });\n`;
const sites = scanPageSizeSites(source, 'fixture.ts');
expect(ids(sites)).toEqual(['1:10:literal:100']);
});
it('does NOT match a computed property key that cannot be resolved statically', () => {
const source = `const key = getKey();\ngetFoo({ [key]: 100 });\n`;
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
it('does NOT match a quoted string key for a DIFFERENT property name', () => {
const source = `getFoo({ 'pageSizeLimit': 100 });\n`;
expect(scanPageSizeSites(source, 'fixture.ts')).toEqual([]);
});
// ---- round-3 MEDIUM finding: .mts/.cts are never silently skipped -----------------------------
it('scans .mts source (parses as plain TS, no JSX grammar)', () => {
const source = `export function loadPage() {\n return getFoo({ pageSize: 100 });\n}\n`;
const sites = scanPageSizeSites(source, 'fixture.mts');
expect(ids(sites)).toEqual(['2:19:literal:100']);
});
it('scans .cts source (parses as plain TS, no JSX grammar)', () => {
const source = `getFoo({ pageSize });\n`;
const sites = scanPageSizeSites(source, 'fixture.cts');
expect(ids(sites)).toEqual(['1:10:shorthand:pageSize']);
});
});
+131
View File
@@ -0,0 +1,131 @@
import * as ts from 'typescript';
/**
* #650 follow-up: an AST-based scanner for every `pageSize` property that appears inside a real
* object LITERAL expression. Extracted into its own module so both the enumerating guard
* (`pageSizeCallSites.guard.test.ts`, which scans the real repo) and a fixture test
* (`pageSizeScan.test.ts`, which scans synthetic source strings and does NOT touch the repo) can
* exercise the exact same scanning logic.
*
* A prior hand-rolled regex/bracket-tracking version of this scan was replaced after a review
* found it defeated by comments-in-strings, template-literal interpolations, ternary/`??`
* contexts, JSX containers, and same-line duplicates — each a DIFFERENT input class a text-level
* lexer has to special-case one at a time. The TypeScript compiler API sidesteps the whole
* category: comments and string/template CONTENTS are trivia/literal text the parser never
* revisits as code, and a real object-literal expression (`ObjectLiteralExpression`) is a
* structurally different AST node from a type literal (`type X = { pageSize: number }`,
* `PropertySignature` inside a `TypeLiteralNode`/`InterfaceDeclaration`) or a destructuring
* pattern (`ObjectBindingPattern`, e.g. `function f({ pageSize }) {}` or
* `const { pageSize } = x`) — so those are excluded by NODE KIND, not by a preceding-character
* heuristic that can be fooled by an unrelated `{`/`(`/`,`.
*
* A round-3 review found the AST version still had its own — smaller, but real — false
* negatives: an initializer wrapped in a transparent TS construct (`pageSize: 100 as const`,
* `pageSize: 100 satisfies number`, `pageSize: (100)`) was rejected outright because only a bare
* `NumericLiteral`/`Identifier` was checked; a property written as a quoted string key
* (`'pageSize': 100`) or a statically-resolvable computed key (`['pageSize']: 100`) was missed
* because only an `Identifier` name was checked. `unwrapTransparentExpression` and
* `isPageSizePropertyName` close both — see their doc comments below. Genuinely UNRESOLVABLE
* cases remain out of reach on purpose and are documented as a residual gap where this scanner is
* actually used (`pageSizeCallSites.guard.test.ts`'s module doc comment): object SPREAD
* (`getFoo({ ...opts })` built elsewhere) and a `pageSize` passed as a bare POSITIONAL argument
* rather than an object-literal property at all.
*/
export interface PageSizeSite {
/** 1-based source line of the `pageSize` property (name), matching editor line numbers. */
line: number;
/** 1-based source column of the `pageSize` property (name). */
column: number;
kind: 'literal' | 'shorthand';
/**
* For `kind: 'literal'`: the numeric-literal text or the referenced const identifier's name.
* For `kind: 'shorthand'`: always the literal string `'pageSize'` (the shorthand form only ever
* forwards whatever `pageSize` binding is in scope — there is no separate "value" to name).
*/
value: string;
}
function scriptKindFor(fileName: string): ts.ScriptKind {
// `.mts`/`.cts` parse as plain TS (no JSX support), same as `.ts` — only `.tsx` needs the JSX
// grammar. `tsconfig.app.json`'s `include` covers all of `src`, and `.mts`/`.cts` are legal
// TS extensions the guard's file-discovery glob must not silently skip even though none exist
// in this repo today (#650 follow-up round 3 MEDIUM finding).
return fileName.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
}
// Unwraps TS constructs that are transparent to the runtime VALUE but would otherwise hide a
// numeric literal / identifier from a naive node-kind check: `expr as T`, `expr satisfies T`,
// and `(expr)`. `pageSize: 100 as const` and `pageSize: 100 satisfies number` are both real
// fixed-100 call sites; only the TS type-checking wrapper differs (#650 follow-up round 3 MEDIUM).
function unwrapTransparentExpression(node: ts.Expression): ts.Expression {
let current = node;
for (;;) {
if (ts.isParenthesizedExpression(current)) {
current = current.expression;
} else if (ts.isAsExpression(current)) {
current = current.expression;
} else if (ts.isSatisfiesExpression(current)) {
current = current.expression;
} else {
return current;
}
}
}
// A property name is `pageSize` whether written as a plain identifier (`pageSize: 100`), a
// quoted string key (`'pageSize': 100`), or a computed key that's STATICALLY a `'pageSize'`
// string literal (`['pageSize']: 100`) — all three compile to the identical property, so all
// three are real call sites (#650 follow-up round 3 MEDIUM). A computed key that ISN'T a literal
// (e.g. `[dynamicKeyVar]: 100`) can't be resolved statically and is correctly left unmatched.
function isPageSizePropertyName(name: ts.PropertyName): boolean {
if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
return name.text === 'pageSize';
}
if (ts.isComputedPropertyName(name)) {
const expr = unwrapTransparentExpression(name.expression);
return ts.isStringLiteral(expr) && expr.text === 'pageSize';
}
return false;
}
export function scanPageSizeSites(sourceText: string, fileName: string): PageSizeSite[] {
const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, scriptKindFor(fileName));
const sites: PageSizeSite[] = [];
function positionOf(node: ts.Node): { line: number; column: number } {
const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
return { line: line + 1, column: character + 1 };
}
function visit(node: ts.Node): void {
if (ts.isObjectLiteralExpression(node)) {
for (const property of node.properties) {
if (ts.isPropertyAssignment(property) && isPageSizePropertyName(property.name)) {
const initializer = unwrapTransparentExpression(property.initializer);
// Only a numeric literal or a bare identifier (a const/variable reference) counts as a
// fixed value baked into THIS call site. A forwarded expression — `String(pageSize)`, a
// ternary, a template, a function call — is a dynamic passthrough of whatever the
// caller supplied, not a literal this site chose; it is deliberately not recorded here
// (see the module doc comment on `loadAllPages`/positional-argument residual gaps).
if (ts.isNumericLiteral(initializer) || ts.isIdentifier(initializer)) {
const { line, column } = positionOf(property.name);
sites.push({ line, column, kind: 'literal', value: initializer.text });
}
} else if (ts.isShorthandPropertyAssignment(property) && property.name.text === 'pageSize') {
const { line, column } = positionOf(property.name);
sites.push({ line, column, kind: 'shorthand', value: 'pageSize' });
}
}
}
ts.forEachChild(node, visit);
}
visit(sourceFile);
return sites.sort((a, b) => (a.line === b.line ? a.column - b.column : a.line - b.line));
}
export function pageSizeSiteId(site: { line: number; column: number; kind: string; value: string }): string {
return `${site.line}:${site.column}:${site.kind}:${site.value}`;
}
+506 -3
View File
@@ -1,7 +1,8 @@
import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
import { act, cleanup, fireEvent, render, renderHook, screen, waitFor, within } from '@testing-library/react';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { applyDesignSystemTheme } from '../designSystem';
import { ChannelBuilderScreen } from './ChannelBuilder';
import { useLibraryBrowse } from './libraryBrowse';
function jsonResponse(body: unknown, status = 200): Response {
return new Response(JSON.stringify(body), {
@@ -98,6 +99,7 @@ function requestBodyFor(path: string): Record<string, unknown> {
function mockBuilderApi({
artworkUploadFailure = null,
browseErrorOn = null,
browseHandler = null,
browseItems = [],
channels = [],
@@ -109,7 +111,15 @@ function mockBuilderApi({
fromLineupResponse = { channelId: 1, playlistId: null, playoutId: 3, programScheduleId: 2 }
}: {
artworkUploadFailure?: { status: number } | null;
browseHandler?: ((search: URLSearchParams) => { page: unknown[]; totalCount: number }) | null;
// Predicate over a /api/v1/library/browse request's query params: when it returns true, that
// ONE request answers with a 500 instead of a page (#650 follow-up F4 — simulates one per-kind
// fan-out request rejecting mid-Promise.all).
browseErrorOn?: ((search: URLSearchParams) => boolean) | null;
// May return the page synchronously OR a Promise of one (#650 follow-up F3 — lets a test hold a
// specific request open to simulate a superseded in-flight append).
browseHandler?:
| ((search: URLSearchParams) => { page: unknown[]; totalCount: number } | Promise<{ page: unknown[]; totalCount: number }>)
| null;
browseItems?: unknown[];
channels?: unknown[];
channelTemplates?: unknown[];
@@ -138,8 +148,13 @@ function mockBuilderApi({
if (path.startsWith('/api/v1/library/browse')) {
const search = new URL(path, window.location.origin).searchParams;
if (browseErrorOn?.(search)) {
return Promise.resolve(new Response(null, { status: 500 }));
}
if (browseHandler) {
return Promise.resolve(jsonResponse(browseHandler(search)));
return Promise.resolve(browseHandler(search)).then((body) => jsonResponse(body));
}
const mediaType = search.get('mediaType');
@@ -708,6 +723,314 @@ describe('Channel Builder (#89)', () => {
expect(screen.queryByRole('button', { name: 'Load more' })).not.toBeInTheDocument();
});
it(
'preserves already-loaded rows when a "Load more" append request fails, and lets it be retried ' +
'(#650 follow-up F4)',
async () => {
const page0 = [browseItem({ id: 1, mediaItemId: 1, title: 'Item A' })];
// Loaded once via `Load more`, then again on retry after the first attempt fails.
const page1 = [browseItem({ id: 2, mediaItemId: 2, title: 'Item B' })];
let page1Attempts = 0;
mockBuilderApi({
...builderDefaults(),
browseHandler: (search) => {
if (search.get('mediaType') !== 'TelevisionShow') {
return { page: [], totalCount: 0 };
}
const pageNum = Number(search.get('pageNum') ?? '0');
if (pageNum === 0) {
return { page: page0, totalCount: 3 };
}
page1Attempts += 1;
if (page1Attempts === 1) {
return Promise.reject(new Error('network blip'));
}
return { page: page1, totalCount: 3 };
}
});
await renderBuilder();
expect(await screen.findByText('Item A')).toBeInTheDocument();
const loadMoreButton = screen.getByRole('button', { name: 'Load more' });
fireEvent.click(loadMoreButton);
// The rejected append must NOT wipe Item A — only report the failure inline.
expect(await screen.findByText('network blip')).toBeInTheDocument();
expect(screen.getByText('Item A')).toBeInTheDocument();
expect(screen.queryByText('No titles match.')).not.toBeInTheDocument();
// The button survives the failure so the SAME page can be retried (the page cursor rolls
// back rather than skipping ahead to a page that was never fetched).
const retryButton = screen.getByRole('button', { name: 'Load more' });
fireEvent.click(retryButton);
expect(await screen.findByText('Item B')).toBeInTheDocument();
expect(screen.getByText('Item A')).toBeInTheDocument();
expect(page1Attempts).toBe(2);
}
);
it(
'clears the "Load more" spinner instead of stranding it when the query changes while an ' +
'append request is still in flight (#650 follow-up F3)',
async () => {
const page0ForA = [browseItem({ id: 1, mediaItemId: 1, title: 'Item A' })];
const page0ForZ = [browseItem({ id: 9, mediaItemId: 9, title: 'Item Z' })];
// No-op initializer (not `null`) matching the established gate-helper pattern elsewhere in
// this repo (see `api/libraries.test.ts`'s `releasePost`) — avoids a `tsc -b` project-mode
// control-flow quirk where a `let x: (() => void) | null = null` reassigned only inside a
// Promise executor narrows a later `x?.()` call to `never` (not caught by a bare
// `tsc --noEmit`, only by the real `npm run typecheck` gate).
let releaseStrandedAppend = () => {};
const strandedAppendGate = new Promise<void>((resolve) => {
releaseStrandedAppend = resolve;
});
mockBuilderApi({
...builderDefaults(),
browseHandler: async (search) => {
if (search.get('mediaType') !== 'TelevisionShow') {
return { page: [], totalCount: 0 };
}
const query = search.get('query') ?? '';
const pageNum = Number(search.get('pageNum') ?? '0');
if (pageNum === 0) {
return { page: query === 'zzz' ? page0ForZ : page0ForA, totalCount: 3 };
}
// The one append (page 1) request never resolves until the test releases it — long
// after the query change below has superseded it.
await strandedAppendGate;
return { page: [browseItem({ id: 2, mediaItemId: 2, title: 'Item B' })], totalCount: 3 };
}
});
await renderBuilder();
expect(await screen.findByText('Item A')).toBeInTheDocument();
const loadMoreButton = screen.getByRole('button', { name: 'Load more' });
fireEvent.click(loadMoreButton);
expect((loadMoreButton as HTMLButtonElement).disabled).toBe(true);
// Change the query while the append is still in flight — this supersedes it with a fresh
// (non-append) page-0 fetch.
fireEvent.change(screen.getByPlaceholderText('Search shows & movies…'), { target: { value: 'zzz' } });
// Without the F3 fix, the superseded append's `finally` never fires its `setLoadingMore(false)`
// (its own request id no longer matches) AND the new fetch's `finally` only clears it when
// `append` is true — so the button would stay disabled/loading forever.
expect(await screen.findByText('Item Z')).toBeInTheDocument();
await waitFor(() => {
expect((screen.getByRole('button', { name: 'Load more' }) as HTMLButtonElement).disabled).toBe(false);
});
// Let the stranded append resolve too, after the fact — it must not resurrect stale rows.
releaseStrandedAppend();
await waitFor(() => expect(screen.getByText('Item Z')).toBeInTheDocument());
expect(screen.queryByText('Item A')).not.toBeInTheDocument();
}
);
it(
'single-flight: a "Load more" click while a page-0 refresh is in flight is IGNORED (not ' +
'queued), so a naive inverse settlement order (page 1 resolving before page 0) is no ' +
'longer reachable — page 1 is only ever requested AFTER page 0 settles, and both end up ' +
'present with the cursor correctly at page 2 for the next click (#650 follow-up round 3)',
async () => {
// Round 1 fixed "page 0 settles first, wrongly clears the append spinner". Round 3's
// review found the MIRROR image reachable through the exact same click sequence: if the
// click were still allowed to start B/page-1 while B/page-0 was in flight, page 1 could
// resolve FIRST, append onto stale query-A rows, and then page 0's later resolution would
// silently replace/erase it without resetting the cursor — permanently losing page 1. Round
// 3's fix removes the click's ability to start a second fetch AT ALL while any fetch (page-0
// refresh or append) is outstanding, so this ordering can't arise irrespective of which
// network response happens to land first.
const pageA0 = [browseItem({ id: 1, mediaItemId: 1, title: 'Item A1' })];
const pageB0 = [browseItem({ id: 2, mediaItemId: 2, title: 'Item B1' })];
const pageB1 = [browseItem({ id: 3, mediaItemId: 3, title: 'Item B2' })];
const pageB2 = [browseItem({ id: 4, mediaItemId: 4, title: 'Item B3' })];
// No-op initializer (not `null`) — see the note on `releaseStrandedAppend` above for why.
let releaseB0 = () => {};
const gateB0 = new Promise<void>((resolve) => {
releaseB0 = resolve;
});
const televisionShowPageNumsForB: number[] = [];
const fetchMock = mockBuilderApi({
...builderDefaults(),
browseHandler: async (search) => {
if (search.get('mediaType') !== 'TelevisionShow') {
return { page: [], totalCount: 0 };
}
const query = search.get('query') ?? '';
const pageNum = Number(search.get('pageNum') ?? '0');
if (query === '') {
// Query A: resolves immediately, canLoadMore true (1 of 4).
return { page: pageA0, totalCount: 4 };
}
televisionShowPageNumsForB.push(pageNum);
if (pageNum === 0) {
await gateB0;
return { page: pageB0, totalCount: 4 };
}
if (pageNum === 1) {
return { page: pageB1, totalCount: 4 };
}
return { page: pageB2, totalCount: 4 };
}
});
await renderBuilder();
expect(await screen.findByText('Item A1')).toBeInTheDocument();
const loadMoreButton = screen.getByRole('button', { name: 'Load more' });
expect((loadMoreButton as HTMLButtonElement).disabled).toBe(false);
// Change the query — the search box debounces (280ms) before `query` state (and the reqId
// bump) actually happens, so wait for B/page-0's request to genuinely be ISSUED before
// clicking — otherwise the click below would still target query A's generation.
fireEvent.change(screen.getByPlaceholderText('Search shows & movies…'), { target: { value: 'B' } });
await waitFor(() => {
const b0Calls = fetchMock.mock.calls.filter(([input]) => {
const url = new URL(input.toString(), 'http://localhost');
return (
url.pathname === '/api/v1/library/browse' &&
url.searchParams.get('mediaType') === 'TelevisionShow' &&
url.searchParams.get('query') === 'B' &&
(url.searchParams.get('pageNum') ?? '0') === '0'
);
});
expect(b0Calls.length).toBeGreaterThan(0);
});
// Click "Load more" WHILE B/page-0 is still in flight. Single-flight must IGNORE this —
// no B/page-1 request may be issued yet.
fireEvent.click(loadMoreButton);
expect(televisionShowPageNumsForB).toEqual([0]);
// Release B/page-0 — items replace the stale A rows.
releaseB0();
await screen.findByText('Item B1');
await waitFor(() => {
expect((screen.getByRole('button', { name: 'Load more' }) as HTMLButtonElement).disabled).toBe(false);
});
// NOW a click is genuinely free to fetch page 1 — click again (the earlier click while busy
// was a no-op, not a queued request).
fireEvent.click(screen.getByRole('button', { name: 'Load more' }));
await screen.findByText('Item B2');
expect(screen.getByText('Item B1')).toBeInTheDocument();
expect(televisionShowPageNumsForB).toEqual([0, 1]);
// The cursor is correctly at page 2 for the next click — not skipped, not repeated.
fireEvent.click(screen.getByRole('button', { name: 'Load more' }));
await screen.findByText('Item B3');
expect(televisionShowPageNumsForB).toEqual([0, 1, 2]);
}
);
it(
'fires "Load more" in Collections mode once merged items reach the 100-row server cap, using ' +
'the REAL summed totalCount rather than the truncated page length (#650)',
async () => {
// Boundary: 100 vs 101 Collection-kind rows. #650's bug reported `merged.length` as
// `totalCount`, so `items.length < totalCount` was always `100 < 100` (false) — this pins
// that canLoadMore now reads the real totalCount (101) and DOES fire past the cap.
const page0 = Array.from({ length: 100 }, (_, i) =>
browseItem({
id: i + 1,
mediaItemId: undefined,
collectionId: i + 1,
collectionType: 'Collection',
mediaType: 'Collection',
title: `Coll ${String(i + 1).padStart(3, '0')}`
})
);
const page1 = [
browseItem({
id: 101,
mediaItemId: undefined,
collectionId: 101,
collectionType: 'Collection',
mediaType: 'Collection',
title: 'Coll 101'
})
];
mockBuilderApi({
...builderDefaults(),
browseHandler: (search) => {
if (search.get('mediaType') !== 'Collection') {
return { page: [], totalCount: 0 };
}
const pageNum = Number(search.get('pageNum') ?? '0');
return { page: pageNum === 0 ? page0 : page1, totalCount: 101 };
}
});
await renderBuilder();
fireEvent.click(screen.getByRole('button', { name: 'Collections' }));
expect(await screen.findByText('Coll 001')).toBeInTheDocument();
expect(screen.getByText('Coll 100')).toBeInTheDocument();
expect(screen.queryByText('Coll 101')).not.toBeInTheDocument();
const loadMoreButton = screen.getByRole('button', { name: 'Load more' });
fireEvent.click(loadMoreButton);
expect(await screen.findByText('Coll 101')).toBeInTheDocument();
expect(screen.getByText('Coll 001')).toBeInTheDocument();
expect(screen.queryByRole('button', { name: 'Load more' })).not.toBeInTheDocument();
}
);
it('surfaces a truncation hint in the Seasons drill-in when a show has more than 100 seasons (#650)', async () => {
// TelevisionSeason browse is scoped to one show (parentId) and requests a single page at the
// cap (Class B, spa-conventions §3b) — no real show has 100+ seasons, but the response's
// totalCount must still be read and surfaced rather than silently truncating if it somehow did.
const seasons = Array.from({ length: 100 }, (_, i) =>
browseItem({
id: 200 + i,
mediaItemId: 200 + i,
mediaType: 'TelevisionSeason',
title: `Season ${i + 1}`
})
);
mockBuilderApi({
...builderDefaults(),
browseItems: [browseItem()],
browseHandler: (search) => {
if (search.get('mediaType') === 'TelevisionSeason') {
return { page: seasons, totalCount: 140 };
}
if (search.get('mediaType') === 'TelevisionShow') {
return { page: [browseItem()], totalCount: 1 };
}
return { page: [], totalCount: 0 };
}
});
await renderBuilder();
expect(await screen.findByText('Looney Tunes')).toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: 'Seasons' }));
expect(await screen.findByText('Season 1')).toBeInTheDocument();
expect(screen.getByText('Showing the first 100 of 140 seasons.')).toBeInTheDocument();
});
it('saves the current settings as a new template and selects it', async () => {
const created = channelTemplate({
id: 55,
@@ -891,4 +1214,184 @@ describe('Channel Builder (#89)', () => {
expect(document.documentElement).toHaveAttribute('data-theme', 'dual');
expect(screen.getByPlaceholderText('Search shows & movies…')).toBeInTheDocument();
});
it(
'single-flight: calling loadMore() twice back-to-back issues only ONE fetch — the second ' +
'call is ignored, not queued as a second overlapping request (#650 follow-up round 3)',
async () => {
// Drives the hook directly via `renderHook` (bypassing the DOM/disabled-button layer
// entirely) to prove the guard lives in the HOOK, not just the presentation: even a
// synchronous double-call cannot start two fetches.
const page0 = [browseItem({ id: 1, mediaItemId: 1, mediaType: 'TelevisionShow', title: 'Item A' })];
const page1Items = [browseItem({ id: 2, mediaItemId: 2, mediaType: 'TelevisionShow', title: 'Item B' })];
const televisionShowPageNumsRequested: number[] = [];
vi.spyOn(window, 'fetch').mockImplementation((input: RequestInfo | URL) => {
const url = new URL(input.toString(), 'http://localhost');
if (url.pathname !== '/api/v1/library/browse') {
return Promise.resolve(new Response(null, { status: 204 }));
}
const mediaType = url.searchParams.get('mediaType');
if (mediaType !== 'TelevisionShow') {
return Promise.resolve(jsonResponse({ page: [], totalCount: 0 }));
}
const pageNum = Number(url.searchParams.get('pageNum') ?? '0');
televisionShowPageNumsRequested.push(pageNum);
if (pageNum === 0) {
return Promise.resolve(jsonResponse({ page: page0, totalCount: 5 }));
}
return Promise.resolve(jsonResponse({ page: page1Items, totalCount: 5 }));
});
const { result } = renderHook(() => useLibraryBrowse('library', '', null));
await waitFor(() => expect(result.current.state.status).toBe('success'));
act(() => {
result.current.loadMore();
result.current.loadMore();
});
await waitFor(() => expect(result.current.state.items.map((item) => item.title)).toContain('Item B'));
// Only ONE page-1 request was ever issued — the second synchronous call was a no-op.
expect(televisionShowPageNumsRequested).toEqual([0, 1]);
expect(result.current.state.items.map((item) => item.title)).toEqual(['Item A', 'Item B']);
}
);
it(
'single-flight: calling loadMore() directly while a page-0 refresh is still in flight is ' +
'IGNORED — no page-1 request is ever issued (#650 follow-up round 4)',
async () => {
// ChannelBuilder.test.tsx's component-level single-flight test asserts on the DISABLED
// BUTTON — during a page-0 refresh, `loadingMore` disables the native button, so
// `fireEvent.click` never even reaches `loadMore`. That test would stay green if the
// generation-change effect's `busyRef.current = true` (libraryBrowse.ts) were deleted,
// because the presentation layer's own disabling would still mask the missing guard. This
// test drives `loadMore()` directly via `renderHook`, bypassing the button entirely, so it
// exercises the HOOK's own guard rather than something adjacent to it.
const pageA0 = [browseItem({ id: 1, mediaItemId: 1, mediaType: 'TelevisionShow', title: 'Item A' })];
const pageB0 = [browseItem({ id: 2, mediaItemId: 2, mediaType: 'TelevisionShow', title: 'Item B0' })];
const pageB1 = [browseItem({ id: 3, mediaItemId: 3, mediaType: 'TelevisionShow', title: 'Item B1' })];
// No-op initializer (not `null`) — see the note on `releaseStrandedAppend` above for why.
let releaseB0 = () => {};
const gateB0 = new Promise<void>((resolve) => {
releaseB0 = resolve;
});
const televisionShowPageNumsForB: number[] = [];
vi.spyOn(window, 'fetch').mockImplementation((input: RequestInfo | URL) => {
const url = new URL(input.toString(), 'http://localhost');
if (url.pathname !== '/api/v1/library/browse') {
return Promise.resolve(new Response(null, { status: 204 }));
}
const mediaType = url.searchParams.get('mediaType');
if (mediaType !== 'TelevisionShow') {
return Promise.resolve(jsonResponse({ page: [], totalCount: 0 }));
}
const query = url.searchParams.get('query') ?? '';
const pageNum = Number(url.searchParams.get('pageNum') ?? '0');
if (query === '') {
return Promise.resolve(jsonResponse({ page: pageA0, totalCount: 4 }));
}
televisionShowPageNumsForB.push(pageNum);
if (pageNum === 0) {
return gateB0.then(() => jsonResponse({ page: pageB0, totalCount: 4 }));
}
return Promise.resolve(jsonResponse({ page: pageB1, totalCount: 4 }));
});
const { result, rerender } = renderHook(({ query }) => useLibraryBrowse('library', query, null), {
initialProps: { query: '' }
});
await waitFor(() => expect(result.current.state.status).toBe('success'));
expect(result.current.state.items.map((item) => item.title)).toEqual(['Item A']);
// Change the query — the generation-change effect fires immediately (no debounce at the
// hook level; that's a ChannelBuilderScreen-only concern) and issues B/page-0, held open by
// gateB0.
rerender({ query: 'B' });
await waitFor(() => expect(televisionShowPageNumsForB).toEqual([0]));
// Call loadMore() DIRECTLY while B/page-0 is still in flight — single-flight must ignore
// this outright, not queue a page-1 request behind it.
act(() => {
result.current.loadMore();
});
expect(televisionShowPageNumsForB).toEqual([0]);
// Let B/page-0 resolve; still no page-1 request should have appeared (the ignored call
// above must not have been queued for later, either).
releaseB0();
await waitFor(() => expect(result.current.state.items.map((item) => item.title)).toContain('Item B0'));
expect(televisionShowPageNumsForB).toEqual([0]);
// Now that the single-flight slot is free, a genuine call correctly fetches page 1.
act(() => {
result.current.loadMore();
});
await waitFor(() => expect(result.current.state.items.map((item) => item.title)).toContain('Item B1'));
expect(televisionShowPageNumsForB).toEqual([0, 1]);
}
);
it(
'a failed "Load more" page is retried as the SAME page number, not skipped or duplicated ' +
'(#650 follow-up round 3)',
async () => {
const page0 = [browseItem({ id: 1, mediaItemId: 1, mediaType: 'TelevisionShow', title: 'Item A' })];
const page1Items = [browseItem({ id: 2, mediaItemId: 2, mediaType: 'TelevisionShow', title: 'Item B' })];
const televisionShowPageNumsRequested: number[] = [];
let page1Attempts = 0;
vi.spyOn(window, 'fetch').mockImplementation((input: RequestInfo | URL) => {
const url = new URL(input.toString(), 'http://localhost');
if (url.pathname !== '/api/v1/library/browse') {
return Promise.resolve(new Response(null, { status: 204 }));
}
const mediaType = url.searchParams.get('mediaType');
if (mediaType !== 'TelevisionShow') {
return Promise.resolve(jsonResponse({ page: [], totalCount: 0 }));
}
const pageNum = Number(url.searchParams.get('pageNum') ?? '0');
televisionShowPageNumsRequested.push(pageNum);
if (pageNum === 0) {
return Promise.resolve(jsonResponse({ page: page0, totalCount: 5 }));
}
if (pageNum === 1) {
page1Attempts += 1;
if (page1Attempts === 1) {
return Promise.resolve(new Response(null, { status: 500 }));
}
return Promise.resolve(jsonResponse({ page: page1Items, totalCount: 5 }));
}
return Promise.resolve(jsonResponse({ page: [], totalCount: 0 }));
});
const { result } = renderHook(() => useLibraryBrowse('library', '', null));
await waitFor(() => expect(result.current.state.status).toBe('success'));
act(() => {
result.current.loadMore();
});
await waitFor(() => expect(result.current.loadMoreError).not.toBeNull());
// The failed page must not be silently skipped: items stay at just page 0's row, and the
// NEXT "Load more" call must re-request page 1 — never page 2 — or that row is permanently
// lost. (An earlier compare-and-set rollback attempt made this assertion fail: it left the
// cursor at page 1 only when nothing else had raced ahead, but a genuinely single-flight
// hook has no "else" case left to distinguish — the unconditional rollback below is what
// that guarantee simplifies down to.)
expect(result.current.state.items.map((item) => item.title)).toEqual(['Item A']);
expect(televisionShowPageNumsRequested).toEqual([0, 1]);
act(() => {
result.current.loadMore();
});
await waitFor(() => expect(result.current.state.items.map((item) => item.title)).toContain('Item B'));
expect(televisionShowPageNumsRequested).toEqual([0, 1, 1]);
expect(result.current.loadMoreError).toBeNull();
}
);
});
+38 -146
View File
@@ -59,7 +59,6 @@ import {
type FFmpegProfile,
type FillerPreset,
type LibraryBrowseItem,
type LibraryBrowseMediaType,
type MediaSource,
type Watermark
} from '../api';
@@ -107,6 +106,7 @@ import {
type SubtitleMode,
type TranscodeMode
} from './advancedOptions';
import { useLibraryBrowse } from './libraryBrowse';
import { SmartCollectionDialog } from './SmartCollectionDialog';
// Advanced-options model (enum unions, INHERIT/omit semantics, the override hook)
@@ -115,26 +115,6 @@ import { SmartCollectionDialog } from './SmartCollectionDialog';
// TYPE_ICON / TYPE_LABEL / hueOf are shared with the media browse/search/trash screens
// (see ../media/mediaKinds) so the per-kind icon+label map has a single source of truth.
const COLLECTION_MEDIA_TYPES: LibraryBrowseMediaType[] = [
'Collection',
'SmartCollection',
'MultiCollection',
'RerunCollection',
'Playlist'
];
// Browsing a library shows the "pickable" top-level kinds only, not every
// episode/song/etc. nested underneath them. Kept explicit here since
// `GET /api/v1/library/browse` now spans all 10 media kinds when `mediaType` is
// omitted. TelevisionSeason is intentionally excluded so a multi-season show
// renders as a single tile instead of flooding the grid with per-season tiles
// (issue #180); seasons are reachable via the show tile's Seasons drill-in.
const LIBRARY_MEDIA_TYPES: LibraryBrowseMediaType[] = [
'Movie',
'TelevisionShow',
'Artist'
];
// ---- Small pure helpers ----------------------------------------------------
const mono: CSSProperties = { fontFamily: 'var(--font-mono)', fontVariantNumeric: 'tabular-nums' };
@@ -433,15 +413,22 @@ function SeasonsDialog({
onClose: () => void;
}) {
const [seasons, setSeasons] = useState<LibraryBrowseItem[]>([]);
const [totalCount, setTotalCount] = useState(0);
const [status, setStatus] = useState<'loading' | 'error' | 'success'>('loading');
const [error, setError] = useState<string | null>(null);
useEffect(() => {
let active = true;
// Class B (media-library-scoped, spa-conventions §3b): a single bounded page at the
// server cap is intentional here — no real show has anywhere near 100 seasons, so this
// isn't paged to completeness — but #650 found the response's real `totalCount` went
// unread, so a show that somehow did exceed the cap would truncate silently. Read it and
// surface it below instead, same as the other Class B pickers.
getLibraryBrowseItems({ mediaType: 'TelevisionSeason', parentId: show.id, pageSize: 100 })
.then((result) => {
if (active) {
setSeasons(result.page ?? []);
setTotalCount(result.totalCount ?? (result.page ?? []).length);
setStatus('success');
}
})
@@ -479,136 +466,36 @@ function SeasonsDialog({
) : seasons.length === 0 ? (
<div className="ctv-builder-empty">This show has no seasons.</div>
) : (
<div className="ctv-builder-seasons-list">
{seasons.map((season) => {
const added = addedKeys.has(lineupKey(season));
return (
<div key={lineupKey(season)} className="ctv-builder-seasons-row">
<Poster item={season} width={40} height={54} mini />
<div className="ctv-builder-seasons-row-title">{season.title}</div>
<IconButton size="sm" title={added ? 'Added' : 'Add to lineup'} onClick={() => onAdd(season)}>
{added ? (
<Check size={15} color="var(--action-primary)" aria-hidden="true" />
) : (
<Plus size={15} aria-hidden="true" />
)}
</IconButton>
</div>
);
})}
</div>
<>
{seasons.length < totalCount && (
<span className="ctv-field-help">
Showing the first {seasons.length} of {totalCount} seasons.
</span>
)}
<div className="ctv-builder-seasons-list">
{seasons.map((season) => {
const added = addedKeys.has(lineupKey(season));
return (
<div key={lineupKey(season)} className="ctv-builder-seasons-row">
<Poster item={season} width={40} height={54} mini />
<div className="ctv-builder-seasons-row-title">{season.title}</div>
<IconButton size="sm" title={added ? 'Added' : 'Add to lineup'} onClick={() => onAdd(season)}>
{added ? (
<Check size={15} color="var(--action-primary)" aria-hidden="true" />
) : (
<Plus size={15} aria-hidden="true" />
)}
</IconButton>
</div>
);
})}
</div>
</>
)}
</Dialog>
);
}
// ---- Library browse data hook ---------------------------------------------
interface BrowseState {
status: 'loading' | 'error' | 'success';
items: LibraryBrowseItem[];
totalCount: number;
error: string | null;
}
async function loadCollections(query: string): Promise<{ page: LibraryBrowseItem[]; totalCount: number }> {
const results = await Promise.all(
COLLECTION_MEDIA_TYPES.map((mediaType) => getLibraryBrowseItems({ query, mediaType, pageSize: 100 }))
);
const merged = results
.flatMap((result) => result.page)
.sort((left, right) => left.title.localeCompare(right.title, undefined, { sensitivity: 'base' }));
return { page: merged, totalCount: merged.length };
}
// Fan out across the pickable top-level library kinds (movies/shows/artists)
// instead of the unscoped browse, which now also returns episodes/songs/etc.
// Mirrors loadCollections's per-kind Promise.all pattern, but preserves real
// paging (each kind keeps its own pageNum/totalCount, summed across kinds) so
// canLoadMore stays meaningful for large libraries.
async function loadLibraryItems(
query: string,
libraryId: number | null,
pageNum: number,
pageSize: number
): Promise<{ page: LibraryBrowseItem[]; totalCount: number }> {
const results = await Promise.all(
LIBRARY_MEDIA_TYPES.map((mediaType) =>
getLibraryBrowseItems({
query: query || undefined,
libraryId: libraryId ?? undefined,
mediaType,
pageNum,
pageSize
})
)
);
const merged = results
.flatMap((result) => result.page)
.sort((left, right) => left.title.localeCompare(right.title, undefined, { sensitivity: 'base' }));
const totalCount = results.reduce((sum, result) => sum + result.totalCount, 0);
return { page: merged, totalCount };
}
function useLibraryBrowse(source: 'library' | 'collections', query: string, libraryId: number | null) {
const [state, setState] = useState<BrowseState>({ status: 'loading', items: [], totalCount: 0, error: null });
const [loadingMore, setLoadingMore] = useState(false);
const reqRef = useRef(0);
const pageRef = useRef(0);
const runFetch = useCallback(
(pageNum: number, reqId: number, append: boolean) => {
const promise =
source === 'collections' ? loadCollections(query) : loadLibraryItems(query, libraryId, pageNum, 100);
promise
.then((result) => {
if (reqRef.current !== reqId) {
return;
}
setState((prev) => ({
status: 'success',
error: null,
items: append ? [...prev.items, ...result.page] : result.page,
totalCount: result.totalCount
}));
})
.catch((error: unknown) => {
if (reqRef.current !== reqId) {
return;
}
setState({ status: 'error', items: [], totalCount: 0, error: messageFromError(error) });
})
.finally(() => {
if (reqRef.current === reqId && append) {
setLoadingMore(false);
}
});
},
[source, query, libraryId]
);
// Refetch when inputs change. Following the guide-hook pattern, setState only
// runs inside runFetch's async callbacks - the previous results stay visible
// until the new page resolves (initial 'loading' shows the first-load spinner).
useEffect(() => {
const reqId = reqRef.current + 1;
reqRef.current = reqId;
pageRef.current = 0;
runFetch(0, reqId, false);
}, [runFetch]);
const loadMore = useCallback(() => {
const nextPage = pageRef.current + 1;
pageRef.current = nextPage;
setLoadingMore(true);
runFetch(nextPage, reqRef.current, true);
}, [runFetch]);
const canLoadMore = source === 'library' && state.status === 'success' && state.items.length < state.totalCount;
return { state, loadingMore, loadMore, canLoadMore };
}
// ---- Builder support data (templates, pickers, channels) -------------------
interface BuilderData {
channels: ChannelSummary[];
@@ -1276,6 +1163,11 @@ function ChannelBuilder({
<Button variant="secondary" size="sm" loading={browse.loadingMore} onClick={browse.loadMore}>
Load more
</Button>
{browse.loadMoreError && (
<span className="ctv-field-error" role="alert">
{browse.loadMoreError}
</span>
)}
</div>
)}
</>
+204
View File
@@ -0,0 +1,204 @@
import { useCallback, useEffect, useRef, useState } from 'react';
import { getLibraryBrowseItems, messageFromError, type LibraryBrowseItem, type LibraryBrowseMediaType } from '../api';
// Extracted from ChannelBuilder.tsx into its own non-JSX module (#650 follow-up) so
// `useLibraryBrowse` — a plain hook, no component — can be exported without tripping
// `react-refresh/only-export-components` (that lint rule wants a file that exports React
// Fast-Refresh components to export ONLY components). It also lets `ChannelBuilder.test.tsx`
// unit-test the hook's single-flight guard directly via `renderHook`.
export const COLLECTION_MEDIA_TYPES: LibraryBrowseMediaType[] = [
'Collection',
'SmartCollection',
'MultiCollection',
'RerunCollection',
'Playlist'
];
// Browsing a library shows the "pickable" top-level kinds only, not every
// episode/song/etc. nested underneath them. Kept explicit here since
// `GET /api/v1/library/browse` now spans all 10 media kinds when `mediaType` is
// omitted. TelevisionSeason is intentionally excluded so a multi-season show
// renders as a single tile instead of flooding the grid with per-season tiles
// (issue #180); seasons are reachable via the show tile's Seasons drill-in.
export const LIBRARY_MEDIA_TYPES: LibraryBrowseMediaType[] = ['Movie', 'TelevisionShow', 'Artist'];
// ---- Library browse data hook ---------------------------------------------
export interface BrowseState {
status: 'loading' | 'error' | 'success';
items: LibraryBrowseItem[];
totalCount: number;
error: string | null;
}
// Fan out across the "pickable" collection-ish kinds (Collection, SmartCollection,
// MultiCollection, RerunCollection, Playlist). Reports the REAL summed per-kind `totalCount`
// (not `merged.length`, i.e. the truncated page) — #650: returning the page length as the total
// made `canLoadMore`'s `items.length < totalCount` comparison permanently `merged.length >=
// merged.length`, so "load more" could never fire once any one kind hit the 100-row server cap.
// Mirrors loadLibraryItems's per-kind pageNum/totalCount pattern below.
async function loadCollections(
query: string,
pageNum: number,
pageSize: number
): Promise<{ page: LibraryBrowseItem[]; totalCount: number }> {
const results = await Promise.all(
COLLECTION_MEDIA_TYPES.map((mediaType) => getLibraryBrowseItems({ query, mediaType, pageNum, pageSize }))
);
const merged = results
.flatMap((result) => result.page)
.sort((left, right) => left.title.localeCompare(right.title, undefined, { sensitivity: 'base' }));
const totalCount = results.reduce((sum, result) => sum + result.totalCount, 0);
return { page: merged, totalCount };
}
// Fan out across the pickable top-level library kinds (movies/shows/artists)
// instead of the unscoped browse, which now also returns episodes/songs/etc.
// Mirrors loadCollections's per-kind Promise.all pattern, but preserves real
// paging (each kind keeps its own pageNum/totalCount, summed across kinds) so
// canLoadMore stays meaningful for large libraries.
async function loadLibraryItems(
query: string,
libraryId: number | null,
pageNum: number,
pageSize: number
): Promise<{ page: LibraryBrowseItem[]; totalCount: number }> {
const results = await Promise.all(
LIBRARY_MEDIA_TYPES.map((mediaType) =>
getLibraryBrowseItems({
query: query || undefined,
libraryId: libraryId ?? undefined,
mediaType,
pageNum,
pageSize
})
)
);
const merged = results
.flatMap((result) => result.page)
.sort((left, right) => left.title.localeCompare(right.title, undefined, { sensitivity: 'base' }));
const totalCount = results.reduce((sum, result) => sum + result.totalCount, 0);
return { page: merged, totalCount };
}
/**
* #650 follow-up (review round 3): rounds 1-2 kept fixing one overlapping page-0-refresh/append
* interleaving only to have the reviewer find its mirror image (page-0-settles-first, then
* page-1-settles-first; a compare-and-set rollback that traded duplication for a permanently
* skipped page). The hook still PERMITTED a page-0 refresh and an append to be in flight
* together, so every ordering of "which one wins" was a distinct bug to enumerate.
*
* This version enforces SINGLE-FLIGHT instead: at most one fetch (a page-0 refresh OR an append)
* is ever outstanding for the current query generation. `busyRef` is the guard — `loadMore` reads
* it SYNCHRONOUSLY and, if a fetch is already in flight, the call is IGNORED outright (not
* queued, not superseded — simply a no-op), so a second click can never start a second
* request. The generation-change effect also claims the single-flight slot for its own page-0
* fetch, so `loadMore` is a no-op while a query/library change is still resolving too — not only
* while a previous append is pending. With overlapping fetches structurally impossible, the
* append-failure rollback no longer needs a compare-and-set: single-flight guarantees nothing
* else could have moved `pageRef` since this fetch started, so it always retries the exact page
* that failed.
*/
export function useLibraryBrowse(source: 'library' | 'collections', query: string, libraryId: number | null) {
const [state, setState] = useState<BrowseState>({ status: 'loading', items: [], totalCount: 0, error: null });
const [loadingMore, setLoadingMore] = useState(false);
// Append-only error, kept separate from `state.error` (#650 follow-up F4): a rejected "load
// more" must NOT flip `state.status` to 'error' — that branch renders instead of the item grid
// and would destroy every already-loaded row with no way back. This renders inline next to the
// (still-present) Load more button so the fetch can simply be retried.
const [loadMoreError, setLoadMoreError] = useState<string | null>(null);
// Query GENERATION (bumped on query/library/source change) — invalidates every fetch from an
// earlier generation, whether it was a page-0 refresh or an append.
const reqRef = useRef(0);
const pageRef = useRef(0);
// Single-flight guard: true from the moment ANY fetch (page-0 refresh or append) for the
// CURRENT generation is issued, until it settles. `loadMore` bails out synchronously while this
// is true. A plain ref (not state) is deliberate — it must be readable/writable synchronously
// inside the generation-change effect without tripping `react-hooks/set-state-in-effect`
// (setState calls belong in async callbacks only, per that rule; a ref mutation isn't one).
const busyRef = useRef(false);
const runFetch = useCallback(
(pageNum: number, reqId: number, append: boolean) => {
const promise =
source === 'collections'
? loadCollections(query, pageNum, 100)
: loadLibraryItems(query, libraryId, pageNum, 100);
promise
.then((result) => {
if (reqRef.current !== reqId) {
return;
}
setLoadMoreError(null);
setState((prev) => ({
status: 'success',
error: null,
items: append ? [...prev.items, ...result.page] : result.page,
totalCount: result.totalCount
}));
})
.catch((error: unknown) => {
if (reqRef.current !== reqId) {
return;
}
if (append) {
// Single-flight (see the hook's doc comment above) guarantees NOTHING else could
// have advanced `pageRef` since this exact fetch started — no compare-and-set needed,
// just always roll back to retry the SAME page that failed.
pageRef.current = pageNum - 1;
setLoadMoreError(messageFromError(error));
} else {
setState({ status: 'error', items: [], totalCount: 0, error: messageFromError(error) });
}
})
.finally(() => {
if (reqRef.current !== reqId) {
// An abandoned generation's fetch settling late: a newer generation's own fetch
// already owns (or has already released) the single-flight slot — do not touch it.
return;
}
busyRef.current = false;
setLoadingMore(false);
});
},
[source, query, libraryId]
);
// Refetch when inputs change. Following the guide-hook pattern, setState only
// runs inside runFetch's async callbacks - the previous results stay visible
// until the new page resolves (initial 'loading' shows the first-load spinner).
useEffect(() => {
const reqId = reqRef.current + 1;
reqRef.current = reqId;
pageRef.current = 0;
// Claims the single-flight slot for this generation's own page-0 fetch — `loadMore` is a
// no-op until it settles, closing the exact window earlier rounds kept losing: a "Load more"
// click that lands while a fresh query's page-0 refresh is still in flight.
busyRef.current = true;
queueMicrotask(() => setLoadingMore(true));
runFetch(0, reqId, false);
}, [runFetch]);
const loadMore = useCallback(() => {
if (busyRef.current) {
// Single-flight: ignored outright rather than queued. Queuing (or racing) a second fetch
// against whichever one is already in flight is exactly what produced every
// page-ordering defect earlier rounds kept chasing one interleaving at a time.
return;
}
busyRef.current = true;
const nextPage = pageRef.current + 1;
pageRef.current = nextPage;
setLoadingMore(true);
setLoadMoreError(null);
runFetch(nextPage, reqRef.current, true);
}, [runFetch]);
// #650: `totalCount` is now the real summed per-kind total for both sources (loadCollections
// no longer reports the truncated page length as the total), so this comparison is meaningful
// for 'collections' too — no need to gate it to 'library' only.
const canLoadMore = state.status === 'success' && state.items.length < state.totalCount;
return { state, loadingMore, loadMore, canLoadMore, loadMoreError };
}
+136
View File
@@ -0,0 +1,136 @@
import { cleanup, render, screen } from '@testing-library/react';
import { afterEach, describe, expect, it, vi } from 'vitest';
import { TraktListsScreen } from './TraktListsScreen';
function jsonResponse(body: unknown, status = 200): Response {
return new Response(JSON.stringify(body), {
headers: { 'Content-Type': 'application/json' },
status
});
}
describe('TraktListsScreen', () => {
afterEach(() => {
cleanup();
vi.restoreAllMocks();
});
it(
'pages to completeness: a 101-item list (one over the 100 server cap) issues a SECOND request and ' +
'renders every row, with the footer count agreeing with the row count (#650)',
async () => {
// Trakt lists are bounded-by-construction (admin-added), so this pins the exact boundary named
// in #650: a request for EXACTLY the cap (100) truncates just as much as an over-cap request,
// so 101 rows (one over the cap) must still page to completeness rather than showing "101
// lists" over a 100-row table (the self-contradictory symptom #650 described).
const total = 101;
const cap = 100;
const all = Array.from({ length: total }, (_, i) => ({
autoRefresh: false,
generatePlaylist: false,
id: i + 1,
itemCount: 10,
matchCount: 5,
name: `List ${i + 1}`,
slug: `list-${i + 1}`,
traktId: 1000 + i
}));
const fetchMock = vi.spyOn(window, 'fetch').mockImplementation((input: RequestInfo | URL) => {
const url = new URL(input.toString(), 'http://localhost');
if (url.pathname === '/api/v1/trakt/lists') {
const pageNum = Number(url.searchParams.get('pageNum') ?? '0');
const pageSize = Number(url.searchParams.get('pageSize') ?? String(cap));
const start = pageNum * pageSize;
return Promise.resolve(jsonResponse({ page: all.slice(start, start + pageSize), totalCount: total }));
}
if (url.pathname === '/api/v1/trakt/status') {
return Promise.resolve(jsonResponse({ busy: false }));
}
return Promise.resolve(new Response(null, { status: 204 }));
});
render(<TraktListsScreen />);
expect(await screen.findByText('List 101')).toBeInTheDocument();
expect(screen.getByText('List 1')).toBeInTheDocument();
// Row count and footer count must AGREE at the boundary — the #650 defect was rendering
// "101 lists" above a table truncated to 100 rows.
expect(screen.getAllByRole('row')).toHaveLength(total + 1); // +1 header row
expect(screen.getByText(`${total} lists`)).toBeInTheDocument();
expect(screen.queryByText('List may be incomplete — retry to reload')).not.toBeInTheDocument();
const listCalls = fetchMock.mock.calls.filter(
([u]) => new URL(u.toString(), 'http://localhost').pathname === '/api/v1/trakt/lists'
);
expect(listCalls).toHaveLength(2);
}
);
it('surfaces an incomplete-load warning when a page comes back short of totalCount (#650)', async () => {
// Defensive break in loadAllPages: an empty (or short) page before totalCount converges must
// render the same "may be incomplete" state used by the other Class A screens, not silently
// show a partial list as if it were the whole one.
vi.spyOn(window, 'fetch').mockImplementation((input: RequestInfo | URL) => {
const url = new URL(input.toString(), 'http://localhost');
if (url.pathname === '/api/v1/trakt/lists') {
const pageNum = Number(url.searchParams.get('pageNum') ?? '0');
// Page 0 returns one row; every subsequent page comes back empty even though
// totalCount (50) never converges — the defensive break loadAllPages relies on.
const page =
pageNum === 0
? [
{
autoRefresh: false,
generatePlaylist: false,
id: 1,
itemCount: 1,
matchCount: 1,
name: 'Only List',
slug: 'only-list',
traktId: 1
}
]
: [];
return Promise.resolve(jsonResponse({ page, totalCount: 50 }));
}
if (url.pathname === '/api/v1/trakt/status') {
return Promise.resolve(jsonResponse({ busy: false }));
}
return Promise.resolve(new Response(null, { status: 204 }));
});
render(<TraktListsScreen />);
expect(await screen.findByText('Only List')).toBeInTheDocument();
expect(screen.getByText('List may be incomplete — retry to reload')).toBeInTheDocument();
expect(screen.getByText('1 list')).toBeInTheDocument();
});
it(
'does NOT claim "No Trakt lists yet" when zero rows accumulated from an incomplete load ' +
'(#650 follow-up F2)',
async () => {
// Every page comes back empty even though totalCount (50) never converges, so
// loadAllPages resolves { items: [], complete: false } — zero rows AND incomplete at the
// same time. The empty-state text is an unsupported positive claim ("there are zero lists")
// when the load never actually finished; only the incomplete badge/message should show.
vi.spyOn(window, 'fetch').mockImplementation((input: RequestInfo | URL) => {
const url = new URL(input.toString(), 'http://localhost');
if (url.pathname === '/api/v1/trakt/lists') {
return Promise.resolve(jsonResponse({ page: [], totalCount: 50 }));
}
if (url.pathname === '/api/v1/trakt/status') {
return Promise.resolve(jsonResponse({ busy: false }));
}
return Promise.resolve(new Response(null, { status: 204 }));
});
render(<TraktListsScreen />);
expect(await screen.findByText('List may be incomplete — retry to reload')).toBeInTheDocument();
expect(screen.queryByText('No Trakt lists yet.')).not.toBeInTheDocument();
}
);
});
+38 -9
View File
@@ -9,6 +9,7 @@ import {
getTraktListById,
getTraktLists,
getTraktStatus,
loadAllPages,
matchTraktList,
messageFromTraktError,
updateTraktList,
@@ -265,7 +266,7 @@ export function TraktListsScreen() {
const editingId = traktListIdFromPathname(window.location.pathname);
const [lists, setLists] = useState<TraktList[]>([]);
const [totalCount, setTotalCount] = useState(0);
const [incomplete, setIncomplete] = useState(false);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [addOpen, setAddOpen] = useState(false);
@@ -276,6 +277,12 @@ export function TraktListsScreen() {
const [deleteError, setDeleteError] = useState<string | null>(null);
const [rowError, setRowError] = useState<string | null>(null);
const activeRef = useRef(true);
// Monotonic request id (spa-conventions §3): `refresh()`/the busy->idle transition can
// re-trigger `load()`, and now that a load is a multi-request `loadAllPages` loop, an older
// loop can resolve after a newer one — guarding on `activeRef` (still mounted) alone isn't
// enough (#644 follow-up F3).
const seqRef = useRef(0);
const abortRef = useRef<AbortController | null>(null);
// TopBar "Add Trakt List" primary action. On the list, open the add dialog. On the
// detail sub-route (/app/trakt-lists/{id}) the add dialog isn't mounted and this component
@@ -294,21 +301,36 @@ export function TraktListsScreen() {
// shows the spinner; later quiet reloads (e.g. after a busy -> idle transition) never
// touch `loading`, so the table stays visible instead of flashing back to a spinner.
const load = useCallback(() => {
getTraktLists({ pageSize: 100 })
.then((paged) => {
if (activeRef.current) {
setLists(paged.page ?? []);
setTotalCount(paged.totalCount ?? 0);
abortRef.current?.abort();
const controller = new AbortController();
abortRef.current = controller;
const seq = (seqRef.current += 1);
// Trakt lists are admin-created (bounded by construction), so this pages to completeness
// rather than requesting a single at-cap page (#650 — the same defect class as #644/#634:
// treating one page as the whole list, just triggered by an exact-cap request instead of
// an over-cap one).
loadAllPages(getTraktLists, undefined, undefined, controller.signal)
.then(({ complete, items }) => {
if (activeRef.current && seqRef.current === seq) {
if (!complete && !controller.signal.aborted) {
// #644 follow-up F4: a partial result is otherwise indistinguishable from a complete
// one. Surfaced via `incomplete` below; also logged so it shows up outside the UI.
console.warn('TraktListsScreen: trakt-lists load did not complete; some lists may be missing');
}
setLists(items);
setIncomplete(!complete);
setError(null);
}
})
.catch((loadError: unknown) => {
if (activeRef.current) {
if (activeRef.current && seqRef.current === seq) {
setError(messageFromTraktError(loadError));
}
})
.finally(() => {
if (activeRef.current) {
if (activeRef.current && seqRef.current === seq) {
setLoading(false);
}
});
@@ -325,6 +347,7 @@ export function TraktListsScreen() {
return () => {
activeRef.current = false;
abortRef.current?.abort();
};
}, [load]);
@@ -394,6 +417,7 @@ export function TraktListsScreen() {
<Spinner size={12} /> Busy
</Badge>
)}
{incomplete && <Badge tone="warn">List may be incomplete — retry to reload</Badge>}
<span className="ctv-channels-spacer" />
<Button
disabled={busy}
@@ -432,6 +456,11 @@ export function TraktListsScreen() {
<Spinner size={18} />
<span>Loading Trakt lists…</span>
</div>
) : lists.length === 0 && incomplete ? (
// #650 follow-up F2: an incomplete load with zero accumulated rows must not also claim
// "No Trakt lists yet." — that's an unsupported positive claim when the load never
// finished. The "may be incomplete" badge above already carries the real state.
<div className="ctv-collections-empty">Unable to load Trakt lists — retry to reload.</div>
) : lists.length === 0 ? (
<div className="ctv-collections-empty">No Trakt lists yet.</div>
) : (
@@ -497,7 +526,7 @@ export function TraktListsScreen() {
</div>
<div className="ctv-channels-footer">
<span>
{totalCount} list{totalCount === 1 ? '' : 's'}
{lists.length} list{lists.length === 1 ? '' : 's'}
</span>
</div>
</div>