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
+13 -13
View File
@@ -1,8 +1,8 @@
// @vitest-environment jsdom
//
// S5: the shared <Button> primitive. These lock the load-bearing contract the migrated call sites rely
// on: variant/size paint (the E28 B1 ladder and B3 layers), the loading state (disabled + spinner +
// aria-busy), the pressed toggle, and the type="button" default that stops an action button from
// The shared <Button> primitive. These lock the load-bearing contract the migrated call sites rely
// on: variant/size paint (the DESIGN.md B1 ladder and B3 layers), the loading state (disabled +
// spinner + aria-busy), the pressed toggle, and the type="button" default that stops an action button from
// submitting a surrounding form. A glyph-only button is `IconButton` (its own test).
import { afterEach, describe, expect, it, vi } from "vitest";
import { act, render, screen, cleanup, fireEvent } from "@testing-library/react";
@@ -10,7 +10,7 @@ import { Button } from "./Button";
afterEach(cleanup);
describe("Button primitive (S5)", () => {
describe("Button primitive", () => {
it("defaults to type=button so it never submits a form", () => {
render(<Button>Go</Button>);
expect(screen.getByRole("button", { name: "Go" }).getAttribute("type")).toBe("button");
@@ -85,7 +85,7 @@ describe("Button primitive (S5)", () => {
expect(onClick).not.toHaveBeenCalled();
});
// E11 S2, measured in Chrome: a focused button that becomes natively disabled drops the focus to
// Measured in Chrome: a focused button that becomes natively disabled drops the focus to
// <body> and never gets it back, so every "Something else" press threw a keyboard user out of Home.
// jsdom has no focus fixup, so what is pinned here is the cause — native `disabled` stays off.
it("loading keeps the button natively enabled, so it keeps the focus", () => {
@@ -159,7 +159,7 @@ describe("Button primitive (S5)", () => {
it("carries the coarse-pointer minimum target and the 24 floor, a link variant too", () => {
// The tablet comfort contract: the minimum lives in the primitive, so no call site can opt
// out of it by accident. A link variant was once excluded as "text in a sentence", but every
// one stands alone, and the E28 audit measured them at 16–20px.
// one stands alone, and an audit measured them at 16–20px.
const { unmount } = render(<Button>Tap</Button>);
expect(screen.getByRole("button", { name: "Tap" }).className).toContain("touch-target");
unmount();
@@ -180,16 +180,16 @@ describe("Button primitive (S5)", () => {
// --- the accessible-name contract, pinned at the TYPE level ------------------------------------
// A button that renders no text must carry a name, and that rule is a union in Button.tsx rather
// than a doc comment because the comment version let two nameless icon buttons ship (E10 review
// round 1). But a type with no test is a type someone widens to silence a stubborn call site:
// replacing `ButtonProps` with the permissive shape left tsc, eslint, knip and vitest all green
// (round 2). Each `@ts-expect-error` below FAILS THE BUILD if the error it expects stops happening,
// than a doc comment because the comment version let two nameless icon buttons ship. But a
// type with no test is a type someone widens to silence a stubborn call site:
// replacing `ButtonProps` with the permissive shape left tsc, eslint, knip and vitest all green.
// Each `@ts-expect-error` below FAILS THE BUILD if the error it expects stops happening,
// so weakening the union turns the whole typecheck lane red.
//
// Rendered, not just declared, so eslint sees them used and the file stays one test suite.
describe("Button · disabled while it holds the focus", () => {
// A focused button that turns natively disabled loses the focus to <body> in Chrome (measured, E11
// S2) — and ~60 call sites disable the very button that was just pressed while its mutation runs.
// A focused button that turns natively disabled loses the focus to <body> in Chrome (measured)
// — and ~60 call sites disable the very button that was just pressed while its mutation runs.
// jsdom does not move the focus, so the CONTRACT is what is pinned: while focused, the button is
// unavailable by aria-disabled + a click guard, never by the native attribute.
it("keeps the native attribute off while focused, and blocks activation", () => {
@@ -255,7 +255,7 @@ describe("Button accessible-name contract (type level)", () => {
<>
{/* @ts-expect-error an icon with no children renders no text and no name */}
<Button icon={<span />} data-testid="bad-c" />
{/* @ts-expect-error the icon-only sizes moved to IconButton (E28 S3b) */}
{/* @ts-expect-error the icon-only sizes moved to IconButton */}
<Button size="icon" label="gone" />
<Button icon={<span />} label="by label" />
<Button icon={<span />} aria-label="by aria-label" />