chore(comments): drop epic, sprint and review-round ids from the code

The code cited its plan instead of saying why: `E28 review J4`, `(R6 S3b)`, `S1 justified…`,
`deep-review round 5`. That plan lives in the private ops repo, so for every reader of this one the
citation was noise, and a sentence whose subject was the plan step ("round 2 showed…") hid its
lesson behind an id. Each one is gone and the "why" kept: a bare citation is deleted, a sentence
carrying a lesson is reworded around it ("a later attempt showed…").

Measured (`scripts/audit_metrics.py`, product code): 652 lines in 270 files carried an epic code by
the definition the next commit holds (507 / 241 by the old, two-digit-only one) -> 0. Across all
code, tests, scripts and configs: ~1100 epic-code lines plus ~320 sprint/round ids.

Behaviour unchanged, checked mechanically: every changed .py file has the same AST once docstrings
are blanked; css/sh/toml/yml/json files are identical once comments are stripped; the only
non-comment changes in TS/JS are test titles, one description string in a contract table, and five
ESLint messages, whose text is all the gates snapshot diff holds. Not touched: Markdown (docs and
the changelog keep their history), Alembic migrations, TV episode notation (`S2 · E5`), DESIGN.md
ids (`C1`, `B4`, `S3h`), tracker ids (`SEC-16`, `DX-17`).

One stale claim fixed on the way: test_hls_reaper's docstring said the player checkpoints "every
10 s whether or not it is playing", which plex/stream.py calls wrong; it now says what the code does.
This commit is contained in:
2026-10-05 00:19:39 +02:00
parent c73d8be094
commit 4aaaaa7860
669 changed files with 1831 additions and 1904 deletions
+42 -42
View File
@@ -10,21 +10,21 @@ import playwright from "eslint-plugin-playwright";
// Flat config (ESLint 9). Deliberately NARROW: the high-value rules here are react-hooks' (the
// hook rules and the React Compiler's diagnostics). The 33 inline `exhaustive-deps` suppressions this
// config first met are all gone (0 left, E32 review); what is still suppressed is suppressed inline,
// config first met are all gone (0 left); what is still suppressed is suppressed inline,
// one site at a time, each naming its invariant. tsc already owns unused vars, undefined names
// and types (noUnusedLocals/Parameters + strict), so typescript-eslint's non-type-checked
// `recommended` is layered on but its overlap with tsc is turned off below to avoid double-reporting
// and a churny diff. `eslint-config-prettier` is LAST so formatting rules never fight Prettier.
//
// reportUnusedDisableDirectives: a `// eslint-disable` that no longer suppresses anything is itself
// an error — that is what keeps inert disable comments from re-accumulating (the S1b mandate).
// an error — that is what keeps inert disable comments from re-accumulating.
//
// E32 (gate integrity): every switched-off or narrowed rule here is listed, with its reason and its
// Gate integrity: every switched-off or narrowed rule here is listed, with its reason and its
// measured count, in docs/gates.md, and lib/gates.contract.test.ts fails when one is not. A rule
// with a single real hit is never switched off — its sites are fixed, or each suppressed inline with
// a `-- <the invariant>` description (eslint-comments/require-description makes that mandatory).
// E22 S4: every way out of the browser goes through the one module that LOGS it — a request line
// Every way out of the browser goes through the one module that LOGS it — a request line
// with a request id (lib/http.ts), the upload XHR (lib/api/core.ts). A bare `fetch` elsewhere is a
// request the client log never sees, which is exactly how the baseline survey found four. Each owner
// is exempt from its OWN global only; a global with no owner (null) has no exempt file at all.
@@ -40,16 +40,16 @@ const networkGlobals = (exempt) =>
.map(([name, owner]) => ({
name,
message: owner
? `Use the logged request layer: \`${name}\` belongs to ${owner} only (E22 S4 — a request outside it never reaches the client log).`
: `No \`${name}\` without a logged owner module (E22 S4).`,
? `Use the logged request layer: \`${name}\` belongs to ${owner} only — a request outside it never reaches the client log.`
: `No \`${name}\` without a logged owner module.`,
}));
const networkProperties = [
{ object: "window", property: "fetch", message: "Use lib/http.ts `send` (E22 S4)." },
{ object: "globalThis", property: "fetch", message: "Use lib/http.ts `send` (E22 S4)." },
{ object: "window", property: "fetch", message: "Use lib/http.ts `send`." },
{ object: "globalThis", property: "fetch", message: "Use lib/http.ts `send`." },
{
object: "navigator",
property: "sendBeacon",
message: "Use lib/api/core.ts `beacon` (E22 S4).",
message: "Use lib/api/core.ts `beacon`.",
},
];
@@ -70,7 +70,7 @@ const jsxCommentText = {
};
},
};
// E28 S3g + E30 S3 (docs/DESIGN.md "Copy"): a date, a number and an alphabetical order are all in the
// docs/DESIGN.md "Copy": a date, a number and an alphabetical order are all in the
// UI language — dates and numbers built in lib/format.ts, text compared in lib/collate.ts. A bare
// `toLocaleString()` formats in the BROWSER's locale (seven date sites had drifted into five shapes), a
// bare `toFixed` writes the English decimal point, a bare `localeCompare` sorts in the browser's
@@ -134,7 +134,7 @@ const localeFormat = {
};
},
};
// E28 S3b: one primitive per button family (docs/DESIGN.md). 268 hand-rolled buttons in 79 files had
// One primitive per button family (docs/DESIGN.md). 268 hand-rolled buttons in 79 files had
// drifted into as many looks, heights and hover styles; they were swept onto ui/Button, IconButton,
// Pressable, Chip and DragHandle, and this keeps the next one out. The raw element lives only in the
// files that ARE a control primitive — not in the rest of components/ui/, whose composites (a pager, a
@@ -144,7 +144,7 @@ const localeFormat = {
// native disabled drops a focused keyboard user to <body> the moment the button turns disabled (a
// mutation pending, a list at its end, a form gone clean) — measured in Chrome, and ~60 buttons in this
// app are disabled by their own click. ui/FocusSafeButton (and ui/Button on top of it) keeps the
// focus. (It was its own rule, `focus-safe-disabled`, until E35.)
// focus. (It used to be its own rule, `focus-safe-disabled`.)
const BUTTON_PRIMITIVES = new Set([
"FocusSafeButton.tsx", // the focus-keeping <button> everything stands on
"Button.tsx",
@@ -196,8 +196,8 @@ const buttonPrimitive = {
else if (exempt) return;
else if (name === "button" || name === "FocusSafeButton")
context.report({ node, messageId: "raw", data: { name } });
// S3g: the same button spelled as a div with a role slipped past the rule above (my own
// S3h Plex picture). A component (capitalised) may take a role for its own reasons.
// The same button spelled as a div with a role slipped past the rule above (one Plex
// picture did it). A component (capitalised) may take a role for its own reasons.
else if (
/^[a-z]/.test(name) &&
node.attributes.some(
@@ -213,8 +213,8 @@ const buttonPrimitive = {
};
},
};
// The same for a text field and the native checkbox / slider / colour well (docs/DESIGN.md A4, A6;
// E28 S3c): ~100 hand-styled boxes carried six edges, four radii and two focus looks between them. A
// The same for a text field and the native checkbox / slider / colour well (docs/DESIGN.md A4, A6):
// ~100 hand-styled boxes carried six edges, four radii and two focus looks between them. A
// file picker has no look (it is hidden behind a Button), so it passes.
const INPUT_PRIMITIVES = new Set([
"Input.tsx",
@@ -247,7 +247,7 @@ const inputPrimitive = {
};
},
};
// B5 (docs/DESIGN.md; E28 S3d): a glass surface is a ROLE from ui/surfaces.ts, which brings its radius.
// B5 (docs/DESIGN.md): a glass surface is a ROLE from ui/surfaces.ts, which brings its radius.
// ~140 sites had paired the three glass tiers with five radii and three menu paddings. A class string
// (two or more tokens, so `variant="glass"` passes) holding a bare glass tier is refused outside the
// role table and the control primitives that paint a glass BUTTON face.
@@ -389,7 +389,7 @@ const sortableA11y = {
},
};
// An <a> whose content is only a glyph is a link that looks like a button (DESIGN.md): `IconLink`, with
// a name, a 24+ box and the icon button's layer. The E28 audit found five bare 14px ones. Text or an
// a name, a 24+ box and the icon button's layer. An audit found five bare 14px ones. Text or an
// expression anywhere in its CHILDREN (not its attributes: every link has an `href={…}`) is a text
// link or a card, and passes; a self-closing <a> is a `Trans` slot that i18n fills with text.
const glyphLink = {
@@ -434,7 +434,7 @@ const localRules = {
// A px-frozen BOX (the no-restricted-syntax block below): an esquery regex, as a string. A box utility
// (`w-[150px]`) or a grid's auto-fill column MINIMUM (`minmax(150px,1fr)`): the text inside grows with
// the slider while the box or the column floor stays, so it re-wraps, clips or cramps at a large text
// size (E30 review for the grid). `[\d.]+`, not `\d+`: a fractional `text-[9.5px]` slipped past the
// size (seen in the grid). `[\d.]+`, not `\d+`: a fractional `text-[9.5px]` slipped past the
// integer-only pattern. A fixed track (`grid-cols-[1fr_240px]`) is left alone, as is VirtualGrid's
// measured `minCol` (a number).
const BOX_PX =
@@ -459,14 +459,14 @@ const PALETTE_MESSAGE =
"a palette colour: use a semantic token (text-rating, bg-live, bg-media-chrome, text-danger, …; DESIGN.md Tokens), not text-amber-500.";
// A class name split by an interpolation: the text right after `${…}` starts with a variant (`hover:`),
// or the interpolation IS the variant and the text goes on with its class (`${NARROW}:w-24`, E28 S3f3).
// or the interpolation IS the variant and the text goes on with its class (`${NARROW}:w-24`).
// A clock (`${m}:00`) and a URL (`${u}://`) are not classes.
const SPLIT_CLASS = "/^([a-z][\\w-]*:[\\w\\[!-]|:[a-z\\[!])/";
const SPLIT_CLASS_MESSAGE =
"a class split by an interpolation (`${x}hover:…`): Tailwind never sees it whole and emits no CSS; write the class literally (a shared guard is the `act:` variant).";
// Applies to EVERY linted file: a suppression says which rule and why. A bare
// `eslint-disable-next-line rule` named nothing in four places the E32 audit found, against the
// `eslint-disable-next-line rule` named nothing in four places an audit found, against the
// CLAUDE.md rule that each one names its invariant; a blanket `eslint-disable` names no rule at all.
const suppressionRules = {
plugins: { "@eslint-community/eslint-comments": eslintComments },
@@ -477,7 +477,7 @@ const suppressionRules = {
},
};
// The two type-aware rules (E32 D3: a curated pair, not strictTypeChecked — ~2000 hits there, none
// The two type-aware rules (a curated pair, not strictTypeChecked — ~2000 hits there, none
// real in the sample). A floating promise is a rejection nobody handles: the audit found two real
// ones (the chat dock's device key store, since removed, and VideoEditor's play()). `void` marks a deliberate fire-and-forget
// whose callee reports its own failure. React Query's invalidate/refetch family never rejects
@@ -524,12 +524,12 @@ export default tseslint.config(
rules: {
...reactHooks.configs.recommended.rules,
...typedRules,
// The React Compiler's own diagnostics that `recommended` leaves out (E32). Each is a function
// The React Compiler's own diagnostics that `recommended` leaves out. Each is a function
// the compiler SKIPS, silently — `panicThreshold` is "none" and there is no logger, so a lint
// error is the only place the skip is said out loud. `todo` is the compiler's "cannot lower
// this shape yet" (E32 S4 rewrote all 31 try statements it found); the rest had 0 hits when
// this shape yet" (all 31 try statements it found were rewritten); the rest had 0 hits when
// switched on, and are tripwires. Three more exist but cannot report anything under
// eslint-plugin-react-hooks 7.1.1 (E32 review, read in its source and probed), so they are not
// eslint-plugin-react-hooks 7.1.1 (read in its source and probed), so they are not
// listed: `exhaustive-effect-dependencies` (its validation is compiled off — the classic
// `exhaustive-deps` reports a missing effect dependency), `memoized-effect-dependencies` (nothing
// emits its category) and `rule-suppression` (lint mode hands it no suppression rules). A
@@ -547,14 +547,14 @@ export default tseslint.config(
"react-hooks/hooks": "error",
"react-hooks/no-deriving-state-in-effects": "error",
// eslint-plugin-react-hooks 7's `recommended` is no longer two rules — it carries the whole
// React Compiler rule set (E27 S1). On this codebase that landed 283 findings. 66 were fixed or
// React Compiler rule set. On this codebase that landed 283 findings. 66 were fixed or
// suppressed inline, each naming its invariant; there is DELIBERATELY no suppressions file — a
// bulk `--suppress-all` would hide the next violation instead of answering it.
//
// `refs` (the other 217) was switched OFF in E27 as mostly false positives, and that triage was
// `refs` (the other 217) was once switched OFF as mostly false positives, and that triage was
// wrong: the rule and the React Compiler share one analysis, so every hit was a function the
// compiler SKIPS — 21 popover components among them, and Channels' 0.9 s row menu was the bill
// (E32). E32 S3–S4 fixed every site (245 measured) instead of narrowing the rule: the popover
// compiler SKIPS — 21 popover components among them, and Channels' 0.9 s row menu was the bill.
// Every site was fixed (245 measured) instead of narrowing the rule: the popover
// engine is read through destructuring, render-phase ref writes became `useEffectEvent` /
// `useLatest`. It is on, at error, with no exception.
"react-hooks/refs": "error",
@@ -571,12 +571,12 @@ export default tseslint.config(
// finding is reported once, by one tool, and this config stays about hooks + refresh safety.
"@typescript-eslint/no-unused-vars": "off",
"no-undef": "off",
// R7 S3a eliminated every explicit `any` (api.ts prefs/data bags → Record<string, unknown>;
// Every explicit `any` was eliminated (api.ts prefs/data bags → Record<string, unknown>;
// catch clauses → unknown + HttpError narrowing; the YouTube IFrame boundary → lib/youtube.ts
// types; i18n `t` props → TFunction), so the rule is now enforced to keep new ones from
// creeping back in. Prefer `unknown` + narrowing, or a typed boundary, over `any`.
"@typescript-eslint/no-explicit-any": "error",
// E22 S4: the client log (lib/log.ts) is the one place diagnostics go — redacted, levelled,
// The client log (lib/log.ts) is the one place diagnostics go — redacted, levelled,
// bounded. A `console.*` call is none of those, and it is invisible to the user's own log.
"no-console": "error",
"no-restricted-globals": ["error", ...networkGlobals(null)],
@@ -592,7 +592,7 @@ export default tseslint.config(
"no-restricted-syntax": [
"error",
// A next-page fetch called bare CANCELS the one in flight and sends the same cursor again;
// our requests ignore the abort, so the server ran both (E31 S4e: every feed page 2–3×).
// our requests ignore the abort, so the server ran both (every feed page 2–3×).
// lib/nextPage.ts NEXT_PAGE makes the second call join the first.
{
selector:
@@ -614,7 +614,7 @@ export default tseslint.config(
},
// Tailwind emits CSS only for a class it finds WHOLE in the source. A variant glued onto an
// interpolated prefix (`${ACT}hover:text-fg`) is never found, so it ships with no rule: every
// hover colour of the button and chip primitives was dead that way (E28 audit).
// hover colour of the button and chip primitives was dead that way (a design audit).
{
selector: `TemplateLiteral > TemplateElement:not(:first-child)[value.raw=${SPLIT_CLASS}]`,
message: SPLIT_CLASS_MESSAGE,
@@ -627,19 +627,19 @@ export default tseslint.config(
message:
"No native <select>: use ui/SegmentedToggle for a short fixed set, ui/FilterSelect for a longer one or a user's own list.",
},
// R10 S2: keep the rem system from rotting. A px-frozen `text-[Npx]` font size does NOT
// Keep the rem system from rotting. A px-frozen `text-[Npx]` font size does NOT
// scale with the Settings --font-scale slider while its rem neighbours do; use
// `text-2xs`/`text-3xs` or a `text-[Nrem]` arbitrary instead. Matches both plain strings and
// template-literal chunks; rem arbitraries (text-[0.75rem]) don't match (no "px").
{
selector: "Literal[value=/text-\\[[\\d.]+px\\]/]",
message:
"px-frozen font size doesn't scale with --font-scale: use text-2xs/text-3xs or text-[Nrem], not text-[Npx] (R10 S2).",
"px-frozen font size doesn't scale with --font-scale: use text-2xs/text-3xs or text-[Nrem], not text-[Npx].",
},
{
selector: "TemplateElement[value.raw=/text-\\[[\\d.]+px\\]/]",
message:
"px-frozen font size doesn't scale with --font-scale: use text-2xs/text-3xs or text-[Nrem], not text-[Npx] (R10 S2).",
"px-frozen font size doesn't scale with --font-scale: use text-2xs/text-3xs or text-[Nrem], not text-[Npx].",
},
// …and the same for a BOX: a `w-[150px]` stays 150px while the text inside it grows with the
// slider, so the label re-wraps or clips at large sizes. Use the spacing scale (`w-37.5` is
@@ -654,7 +654,7 @@ export default tseslint.config(
},
},
{
// E10 S1: `components/ui/` is the PLATFORM layer, and the rule that makes it a layer rather than
// `components/ui/` is the PLATFORM layer, and the rule that makes it a layer rather than
// a folder is enforced here, not in prose (see components/ui/README.md). A platform component is
// domain-free: it may import sibling primitives and generic `lib/` helpers, never a feature
// component (`../Feed`) and never a domain API slice. Without this rule the boundary erodes on
@@ -666,7 +666,7 @@ export default tseslint.config(
{
// NOTE the String.raw: these are REGEX sources, and in a plain "..." literal `\.` is an
// unknown escape that collapses to a bare `.` — the any-char wildcard. The first cut of
// this rule shipped that way and matched far less than it read like (E10 review round 1).
// this rule shipped that way and matched far less than it read like.
patterns: [
{
// `../X` (exactly one level up = a feature component). A `regex` rather than a glob:
@@ -696,7 +696,7 @@ export default tseslint.config(
},
},
{
// E11 S3: the same one-way rule one layer down. `lib/` is what components are built ON (hooks,
// The same one-way rule one layer down. `lib/` is what components are built ON (hooks,
// the API slices, pure helpers), so it may not reach back UP into `components/` — not even for a
// type. That is how the `Column` contract came to be owned by a ui component that three lib
// helpers had to import from. A piece both layers need moves down into `lib/`.
@@ -725,7 +725,7 @@ export default tseslint.config(
rules: { "no-restricted-globals": ["error", ...networkGlobals(name)] },
})),
{
// The design lab (src/design-lab, E28) is a dev-only page that never reaches the production
// The design lab (src/design-lab) is a dev-only page that never reaches the production
// bundle (devOnlyGuard fails the build if it does). Its copy is the developer's and the product
// owner's working text, not the product's, so the translate-every-label rule does not apply.
files: ["src/design-lab/**/*.{ts,tsx}"],
@@ -738,7 +738,7 @@ export default tseslint.config(
plugins: { vitest },
rules: {
// A focused test silently skips the rest of the suite; a skipped one is a test nobody runs
// (E32 — vitest's allowOnly is on outside CI, so nothing else catches a stray `.only` locally).
// (vitest's allowOnly is on outside CI, so nothing else catches a stray `.only` locally).
"vitest/no-focused-tests": "error",
"vitest/no-disabled-tests": "error",
"no-restricted-globals": "off",
@@ -750,7 +750,7 @@ export default tseslint.config(
},
},
{
// Outside src (E32): the e2e suite and the TypeScript build-tool configs went unlinted — the
// Outside src: the e2e suite and the TypeScript build-tool configs went unlinted — the
// flat config named only src/**, so `eslint .` skipped them without a word. The same base and
// typed rules as the app; Node globals, since none of it runs in the browser.
files: ["e2e/**/*.ts", "*.config.ts", "reactPlugin.ts", "devOnlyGuard.ts"],