@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/.agents/skills/flawless-react/SKILL.md

@@ -0,0 +1,403 @@
+---
+name: flawless-react
+description: Generate and maintain React/Next.js/Expo test suites with flawless-react — task selection, Next.js and Expo modes, provider wrappers, MSW fixtures from an OpenAPI spec, colocated specs, route e2e, crust load pipes, the programmatic API, and how to read its findings. Use when adding component/e2e/load tests to a React codebase, when a generated flawless suite is red, or for "scaffold tests for this component" work. Deeper guidance lives in the sibling skills flawless-nextjs, flawless-unit-browser, flawless-perf-harness, flawless-perf-static, flawless-a11y, flawless-react-rules, flawless-findings, flawless-e2e, flawless-load, flawless-api-fixtures, flawless-regen, flawless-api, and flawless-expo.
+---
+
+# flawless-react
+
+Point it at a `.tsx` file or glob and it reads the component's props, state,
+hooks, children and fetches, then writes a runnable suite. Everything it emits
+is yours to edit, but most of it is REGENERATED — the suite improves, and a
+frozen file never receives the improvement. Only what the tool cannot rebuild is
+protected: `budgets.json`, `host/main.tsx`, `provider.fixtures.ts`,
+`e2e/global-setup.ts`, `e2e/params.json`, `mocks/handlers.ts`, and colocated
+specs. To keep a hand-hardened component spec, use `--colocate`; specs written
+inside the out dir are rewritten.
+
+```bash
+# one component, unit specs only
+bunx @lariocpt/flawless-react src/components/Widget.tsx --tasks unit-browser --no-interactive
+
+# a Next.js app: real fixtures, colocated specs, route e2e and load pipes
+cd apps/web
+bunx @lariocpt/flawless-react "src/app/dashboard/page.tsx" \
+  --nextjs . --api openapi.json --swagger-url=off \
+  --tasks unit-browser,perf-static,a11y,react-rules,e2e,load \
+  --colocate --no-interactive
+```
+
+## Which skill to load
+
+This skill is the map. Each plane's traps live in its own skill.
+
+| situation | skill |
+| --- | --- |
+| `--nextjs`: provider derivation and drops, module stubs, React pins, `package.json` merge, `.env` order | flawless-nextjs |
+| unit + browser spec shapes, provider wrapper, `TODO(flawless)`, registered mocks | flawless-unit-browser |
+| the runtime perf plane: `host/`, `profile/`, budgets, `--heaps`, port 5173 | flawless-perf-harness |
+| the static analyser's nine `perf/*` rules, sidecars, what a clean report means | flawless-perf-static |
+| accessibility findings (biome a11y on web, the six native rules) | flawless-a11y |
+| the curated biome correctness/suspicious sweep | flawless-react-rules |
+| triaging a findings list, REPORT.md accounting, suppressions, the counts ledger | flawless-findings |
+| route e2e against a real app: login, `params.json`, the auth wall | flawless-e2e |
+| crust load pipes, `LOAD_BASE`/`LOAD_AUTH`, baselines, anti-vacuous probes | flawless-load |
+| `--api` / `--swagger-url`, MSW handlers, synthesised fixture bodies | flawless-api-fixtures |
+| re-running over an existing suite: `--force`, `--changed`, kept vs refreshed | flawless-regen |
+| `runFlawless()` / `analyse()` from a script | flawless-api |
+| `--expo`: what runs, what refuses, native specs and selectors | flawless-expo |
+
+## Tasks
+
+| id | what it writes | needs |
+| --- | --- | --- |
+| `unit-browser` | Vitest + Testing Library specs (+ Playwright browser specs when `perf-harness` is also selected) | — |
+| `perf-harness` | `host/` bundle + Profiler/react-scan Playwright suite + heap snapshots | — |
+| `perf-static` | `reports/<C>.perf-static.json` findings, no files to run | — |
+| `a11y` | web: biome's a11y rule group; `--expo`: the tool's six native `a11y/*` rules | biome in the target project (web path only) |
+| `react-rules` | biome `correctness` + `suspicious`, curated; scratch config, local `biome.json` bypassed | biome |
+| `e2e` | `flawless/e2e/` route specs against a real dev server | running app + seeded data |
+| `load` | `flawless/load/routes.pipes` crust load pipelines | crust to run them |
+
+Pick tasks explicitly with `--tasks a,b`; with no args in a TTY you get a
+checkbox menu.
+
+Over an EXISTING suite, a re-run exits 0: `perf-harness` refreshes its derived
+files exactly as a fresh scaffold would (write-once files untouched; TaskResult
+and REPORT.md carry `status: "refreshed"`), and under `--changed` it keeps the
+harness entirely — nothing written, `status: "kept"` — so the affected-test run
+happens with any task selection. `--force` is only for regenerating what a
+plain re-run keeps (colocated specs, e2e route specs, the provider wrapper).
+See the flawless-regen skill for the full regeneration contract.
+
+## Next.js mode
+
+`--nextjs [path]` detects the router, auto-selects a provider, writes
+everything under `<root>/flawless/`, merges devDeps + `flawless:*` scripts into
+the project's `package.json`, and appends gitignore entries.
+
+Ignore entries are appended in **every** mode, not only under `--nextjs`. Outside
+Next.js mode they go to the git root (then the nearest `package.json`, then the
+out dir's parent). Until that was fixed a plain run ignored nothing it
+generated, including `<out>/e2e/.auth.json` — the file the emitted global-setup
+tells you to persist a logged-in storageState into.
+
+**Providers.** App-router `layout.tsx` is usually an async server component
+importing `next/font` or `next/headers` — unusable under jsdom. flawless
+detects that and derives `flawless/provider.tsx` from the JSX chain that
+encloses `{children}`, keeping only `"use client"` components and literal
+attributes. What it leaves out is named where you will read it: a dropped
+attribute as a `TODO(flawless)` comment beside the wrapper, a dropped provider
+layer in a block at the top of the file with the reason and the fix. A provider
+layer whose module directly imports an auth library (`@clerk/*`, `next-auth`)
+is skipped rather than mounted: the unit and browser planes replace those
+libraries with a signed-out stub, so a provider gating its children on a
+session renders *nothing* and every spec inherits the blank screen — while the
+stub already satisfies the context reads auth-consuming components make. Expect
+the components under it to fail on "Could not find Convex client" or "could not
+find … in the context" — that is the drop, not the component. `--force`
+regenerates it, so a change to the layout's provider chain reaches an existing
+suite — put the values you supply (a seeded auth state, a theme) in
+`provider.fixtures.ts` beside it, which is never regenerated under any flag.
+Pass `--provider <file>` to override — that is also the way to supply a context
+the derived wrapper dropped, since editing `provider.tsx` does not survive
+`--force`. In plain (non-Next) mode there is no derived `provider.tsx` at all:
+every render is wrapped in a per-component nest derived from hook-call,
+namespace-compound, transitive-requirement and dynamic-render evidence (a
+dynamic `<Tag />` bound from a project hook's return owes what that hook's
+values can hand out) — the app's own providers,
+convention matches for bare-module hooks, and generated shims for library
+contexts — and `--provider` sits outside that nest.
+
+**API fixtures.** Static route walking only sees `app/api/**/route.ts`, which
+is useless for catch-all APIs (Hono, tRPC). Pass `--api openapi.json` (or
+`--swagger-url http://localhost:3000/api/docs`) and real example bodies flow
+into `flawless/mocks/handlers.ts` and into each generated fetch spec. Use
+`--swagger-url=off` to skip the live-spec probe.
+
+Everything below that summary is in flawless-nextjs — module stubs and the rule
+that a named one outranks a pattern one, the Testing Library pins and how a stale
+range is repaired, the `package.json` merge with `pnpm.ignoredBuiltDependencies`,
+the two `.env` load orders, and where gitignore entries land.
+
+## React 17 / 18 / 19
+
+The app's React major (`detectAppReact` in the root `package.json`) is the
+single switch. At or above 18 the host mounts through `createRoot`; below 18
+it falls back to legacy `ReactDOM.render`, document roots render with
+`renderToStaticMarkup`, and promise-valued props are not passed. The suite's
+`react`/`react-dom` are pinned to the version the app has INSTALLED, exactly:
+`detectAppReact` reads `node_modules/react` before the declared range, because a
+caret is a floor and `^19.2.0` installs whatever is newest. Where the analysed
+sources resolve a different copy than that walk finds — a workspace whose root
+declares no react while a sibling package holds one — `appReactPin` reads the
+pin off the copy the emitted `react` aliases anchor on instead, because the pin
+and the alias have to name the same physical copy or one plane ends up with two
+React copies. Where no manifest declares a version at all — a library whose
+react is a peer, `"^18.0.0 || ^19.0.0"`, declares no version — the nearest
+installed pair is used instead,
+scoped so an ancestor's tooling react never out-votes a real declaration. Two
+React copies is the classic red-suite cause, and a pair that merely drifts is
+just as fatal — one patch off dies at load on react-dom's guard
+(`Incompatible React versions`), one major off on `Cannot read properties of
+undefined (reading 'ReactCurrentOwner')`. A stale or loose pin left in an
+existing suite manifest is rewritten by the next run (`repairReactPin`).
+Testing Library follows the app: React ≤17 gets
+`@testing-library/react@^12.1.5` + `@testing-library/dom@^8.20.1` — 13/14
+peer-require react ^18 and 14 hard-requires the `react-dom/client` entry that
+does not exist in 17. A stale 13+ range left by an older run is repaired by
+the next one (`repairRtlPin`).
+
+Two footprints complete the merge: for pnpm apps the `package.json` merge
+records `pnpm.ignoredBuiltDependencies` for the deps it introduces
+(`@playwright/test`, `msw`) — pnpm ≥10 errors on an unrecorded build-script
+decision, and `ERR_PNPM_IGNORED_BUILDS` killed the app's own `pnpm run dev`
+before Next could boot; and the suite's Vitest config reads the app's
+`.env.test.local` → `.env.example` (first value wins, env vars beat them) —
+`.env.example` last because template repos ship only the example, and its
+placeholders exist to satisfy module-scope construction.
+
+## Expo / React Native mode
+
+`--expo [<path>]`, mutually exclusive with `--nextjs`. Reads the project's SDK major, expo-router root, React Compiler and NativeWind settings off disk, defaults the entry glob to the router root, and writes to `<expoRoot>/flawless/`.
+
+**Every task runs under `--expo` except one, which refuses by a measured decision — and the tool says which.**
+
+| task | under `--expo` |
+|---|---|
+| `unit-browser` | **runs** — jest-expo + @testing-library/react-native |
+| `perf-static` | **runs** |
+| `react-rules` | **runs** |
+| `a11y` | **runs** — the native analyser: six `a11y/*` rules, no biome involved |
+| `e2e` | **runs** — route specs against `expo start --web`; cookie auth via storageState, copy-witness anti-vacuity |
+| `load` | **runs** — API-only crust pipes, harvested one hop through the app's fetch wrapper (screen → api fn → apiFetch); a 401 auth probe, not a redirect check |
+| `perf-harness` | **refuses** — measured-and-declined (~0 host-mountable components on an all-route-screens app); the refusal names the recorded evidence |
+
+A refusal is a failed `TaskResult`, not a throw: it lands in `results[]`, the `--ci` blob and `REPORT.md`. A mixed selection still runs what it can.
+
+**Do not work around a refusal by dropping `--expo`.** The DOM suite pointed at React Native emits specs that run, pass, and touch nothing — `container.querySelector("Pressable")` matches no element, and `getByRole("button")` finds nothing because React Native has no implicit roles.
+
+Two things worth knowing before reading a native run's output, both measured (`docs/archive/2026-08-expo-probes.md`):
+
+- **`a11y` on native is the tool's own analyser, and its zero carries a denominator.** Biome's 29 rules are HTML/ARIA and returned zero over 31 RN files with 82 unlabelled `<Pressable>`s (3/3 on the DOM offender fixture), so the task refused until wave 5 shipped the native engine. Its summary always says how many press targets / text inputs / icons were examined — a native zero WITHOUT that denominator is a bug, not a clean bill.
+- **The React Compiler changes what `perf-static` means, and the task honours it.** On a project with `experiments.reactCompiler: true`, 136 of 168 findings were the three memoisation rules — work the compiler already does. `perf-static` reads that state from the project's configs in every mode (`app.json`, `next.config.*`, a babel or recognised bundler config) and suppresses those three, naming the evidence in REPORT.md; the hook-deps, effect and `set-state-in-render` rules run either way. See the `flawless-perf-static` skill for the three states and what each one prints.
+
+See the `flawless-expo` skill for the native spec shapes, the selector ladder, and what a skip means.
+
+## What the generated unit specs contain
+
+Driven by static analysis, so they only assert what can be derived:
+
+- the rendered root tag, when the analyser could pin it down;
+- `children` and `className` passthrough, but only when the value provably
+  reaches the DOM — accepting a prop is not rendering it;
+- for a cva/`tv` component, that every option of every key renders a **distinct**
+  class list. Never a specific Tailwind token: `cn()` is usually tailwind-merge,
+  which drops base classes a later variant conflicts with;
+- literal copy the component renders unconditionally;
+- one test per detected interaction, with negative assertions on every other
+  handler prop (a click that fires two callbacks fails);
+- disclosures opened first: a control behind a closed `Dialog`/`Menu`/`Popover`
+  is not in the DOM, so the spec clicks its trigger — by prop label, literal
+  text, or its fixture child — clears the spies, then queries with `findBy*`;
+  static-copy assertions skip closed content outright. A root written `open`,
+  `defaultOpen` or `open={true}` is never gated;
+- a named local handler read through: `onClick={handleConfirm}` whose
+  declaration calls exactly ONE prop handler directly is asserted as that prop.
+  Two props means the handler claims neither — canary;
+- `children` handed to an `asChild`/`Slot`/`Slottable` site mounted as a
+  `<span>`, never bare text — Slot clones elements and a text child throws;
+- id-typed props never default to `""` (`flawless-<prop>` instead) — providers
+  validate ids, they do not render them;
+- state-derived tests: initial-state witnesses and handler→setter tests;
+- one `describe` per `useEffect` fetch with **success / loading / error /
+  empty** cases via `server.use(...)` overrides;
+- async server components get `await Component(props)` plus `vi.mock` stubs
+  for their non-component imports (no browser spec — they cannot mount).
+
+Everything above describes the render the component produces **at the props the
+spec passes**, not the last `return` in its body. A guard the analyser can decide
+is followed; one it cannot that returns nothing falls through to the tail; one it
+cannot that returns content produces no description at all.
+
+Client specs mock an **allowlist only** — `next/navigation`, `next/headers`,
+`server-only`, `next/link`, `next/font/*` and any `"use server"` module. Mocking
+a `cn` util would strip every className off the markup, and mocking a UI
+component would replace the element the interaction tests click.
+
+When nothing is derivable the spec emits `test.skip` naming which preconditions
+failed. **A skip with a reason is the intended output there — do not "fix" it by
+deleting the assertion or by hand-writing one.** Fix the generator, or give the
+component the `data-testid` / fixture the skip asks for.
+
+Anything the analyser could not derive is a `TODO(flawless)` marker, never a
+silently passing assertion. **The hardening loop is: run the suite, fill the
+TODOs with real fixtures, rerun.** Regenerating later will not clobber your
+work if the specs are colocated (see below).
+
+## Spec placement
+
+Default is `flawless/unit/<Name>.test.tsx`. Same-named components from
+different files get `<Parent>__<Name>`.
+
+`--colocate` writes `<source-dir>/<file>.flawless.test.tsx` beside the
+component instead (multi-component files get `<file>.<Component>.flawless...`).
+Colocated specs are **never overwritten without `--force`** — they are the ones
+you hand-harden. Run them with `bun run flawless:unit`.
+
+If the project's own test script is a bare `bun test`, it will also collect
+`*.flawless.test.tsx` and fail on vitest globals. Scope it: `"test": "bun test tests"`.
+
+## e2e and load
+
+Route specs, the global-setup login and the auth wall are flawless-e2e; crust
+pipes, `LOAD_BASE`/`LOAD_AUTH` and their baselines are flawless-load. The short
+version:
+
+e2e runs against the app's **real dev server** — MSW cannot intercept a server
+component's direct database access, so mocking it would be a lie. Seed the
+database first, fill in `flawless/e2e/global-setup.ts` (it ships a worked login
+example that persists `storageState`), and pass ids for dynamic segments:
+
+```bash
+bun run db:reset
+FLAWLESS_E2E_ID=<seeded-id> bun run flawless:e2e
+```
+
+For contract-checked runs, put crust's validation proxy in front and assert no
+response violated the spec:
+
+```bash
+crust -c 'mock-server --swagger openapi.json --port 4747 --proxy http://localhost:3001' &
+FLAWLESS_E2E_BASEURL=http://localhost:4747 bun run flawless:e2e
+crust -c 'GET :4747/__crust/violations | (v => v.violations.filter(x => x.direction === "response")) | assert (a => a.length === 0)'
+```
+
+Load pipes target the analysed page routes plus the GET endpoints its
+components actually fetch (mutations are excluded on purpose). Each line gates
+p95 against a baseline: copy a good `last-<name>.json` to `baseline-<name>.json`
+and later runs fail when p95 doubles.
+
+Two things decide whether the numbers mean anything, and both are easy to get
+wrong:
+
+- **`LOAD_BASE` must be a production build** (`bun run build && bun run start`),
+  not `next dev` — the dev server compiles routes on demand, so the first
+  request to each measures the compiler.
+- **`LOAD_AUTH` is a header line**, and for a cookie-session app that is
+  `cookie: session=<value>`, not a Bearer token. Prove it authenticates first:
+  an unauthenticated request to a dashboard route redirects to the login page,
+  which answers 200, so every pipe passes while measuring the login screen.
+
+A pipe whose ids are unfilled is emitted **commented out**, above a line naming
+which key in `flawless/e2e/params.json` to fill — a blank segment measures the
+app's 404 handler, not the route. Fill the id and regenerate with `--force`,
+which merges rather than overwrites: edited rates, hand-added flows and pipes
+you commented out yourself all survive. The task summary reports live versus
+commented counts, so REPORT.md does not call a gated pipe covered.
+
+## Reading findings
+
+`perf-static` and the biome tasks print `file:line:col rule message` and write
+`flawless/reports/*.json`; a `<Component>.flawless.json` sidecar lands next to
+each analysed source (`--no-inline-summary` to disable). Its paths are relative
+to the sidecar — resolve against its own directory — and its `a11y` and
+`reactRules` entries name the run's single aggregate, not a per-component file.
+Rules worth knowing:
+
+- `perf/hook-missing-dependency` / `hook-extraneous-dependency` — stale-closure
+  and over-firing effects, deliberately conservative (skipped when deps contain
+  member access or spreads, so a clean report is not proof).
+- `perf/unstable-child-prop` — inline object/array/arrow passed to a component
+  child; flagged harder when that child is `React.memo`-wrapped.
+- `perf/set-state-in-render` (error) — unguarded setState during render.
+- `perf/unresolved-prop` — the analyser could not synthesise a default, so the
+  generated spec passes `undefined`. Reported apart from the findings, bucketed per
+  component under REPORT.md's `## Spec quality`; fix with `--props '{"x":1}'` or by
+  editing the spec's `DEFAULTS`.
+
+Triage order, what a suppression costs, and which rule belongs to which task are
+the three skills flawless-perf-static, flawless-a11y and flawless-react-rules;
+flawless-findings keeps the REPORT.md accounting and the counts ledger.
+
+## Programmatic use
+
+```ts
+import { runFlawless } from "flawless-react";
+
+const { results, trees, outDir } = await runFlawless({
+  entry: "src/components/Widget.tsx",
+  nextjs: ".",
+  tasks: ["unit-browser", "perf-static"],
+  colocate: true,
+});
+```
+
+It never calls `process.exit`; bad input throws `UsageError`. `analyse()`,
+`analyseTree()` (the perf rules) and the scaffolders are exported too, so you
+can build your own reporting on `ComponentTree` without the CLI. `--ci` is
+shorthand for `--no-interactive --json`.
+
+## Style
+
+Generated files are reformatted with the **host project's** biome or prettier
+before the run finishes, and JSON merges preserve the file's existing
+indentation — generation should produce a clean `git diff`, not a reformat of
+your `package.json`.
+
+## Troubleshooting
+
+- **`Cannot read properties of null (reading 'useState')`** — two React copies.
+  The generated vitest config pins react/react-dom to the `node_modules` that
+  also holds `@testing-library/react`; if you moved things, fix the alias block.
+- **`window.matchMedia is not a function`** — `flawless/setup.ts` ships jsdom
+  polyfills; make sure your config still lists it in `setupFiles`.
+- **Browser specs missing** — they need the `perf-harness` host; add that task.
+- **RSC spec renders nothing** — its `vi.mock` stubs return `vi.fn()`; give
+  them real return values (that is the TODO).
+- **Playwright has no browser** — `bunx playwright install chromium`. The
+  runner attempts this automatically; `FLAWLESS_SKIP_BROWSER_INSTALL=1` opts out.
+- **Spec fails `ReferenceError: <name> is not defined`, host build printed
+  nothing** — a host resolve-plugin fall-through dropped a bare specifier's
+  module onto a variant without that export (`msw` named imports were the
+  casualty). Run `bun host/server.ts` from the suite dir to see the build;
+  check the plugin's `args.path` gates, not the spec.
+- **Every e2e route 404s while `/` loads in a browser** — the app's own
+  middleware is an auth wall (`auth.protect()`); with placeholder keys every
+  route behind it 404s. Real credentials in `e2e/global-setup.ts`, or do not
+  claim those routes.
+- **e2e dies on "Timed out waiting …ms from config.webServer", no spec run** —
+  the same wall one stage earlier. Playwright calls the server up only on a
+  2xx/3xx from the readiness url, which is the app root, and retries a 404
+  forever (`[WebServer] GET / 404` repeating in the log). Fill the credentials,
+  or set `FLAWLESS_E2E_BASEURL` to a server you started yourself — the emitted
+  config drops its own `webServer` block for that.
+- **Both Playwright configs collide** (`test.describe() called here` /
+  `No tests found`) — two `@playwright/test` copies (app root + suite). Run the
+  plane from the suite dir with its own config:
+  `node node_modules/@playwright/test/cli.js test --config e2e/playwright.config.ts`.
+  Same for vitest: `node ../node_modules/vitest/vitest.mjs run --config vitest.config.mts`.
+
+## Limits worth stating up front
+
+Static analysis only, no type checker. Imported prop types resolve two hops —
+including types from the repo's own **workspace packages** (`@scope/shared`,
+resolved through the workspace map into the package's source, barrel
+re-exports chased to the declaring file); intersections, host-element props
+(`ComponentProps<"div">`), `ComponentProps<typeof LocalX>` and cva tables all
+resolve. `z.infer`/`z.input` aliases resolve too, by reading the zod schema
+syntactically (object/enum/primitive/array/coerce, `.optional`/`.nullable`/
+`.default`/`.partial`/`.extend`; `.transform`, unions, records and dates
+bail). Non-literal unions, `Omit`/`Pick`/`Partial` and anything in
+`node_modules` do not — the prop lands in `unresolvedProps` and the type that
+defeated it in `unresolvedTypes`.
+
+Mocks come from a component's **own** imports, so one that renders `<Link>` only
+through a child gets no `next/link` mock in its own spec.
+
+Every run writes `flawless/REPORT.md`, which accounts for every component found:
+how many can mount in the browser profiling host, how many cannot and why, and
+which files yielded no component at all. Read it before quoting a coverage
+number — a file count is not coverage.
+
+A green generated suite means "nothing obviously broken", not "covered" — the
+value is in the scaffolding you harden, and in the findings.

package/.agents/skills/flawless-react-rules/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: flawless-react-rules
+description: Run and act on flawless-react's react-rules task — a curated set of Biome correctness and suspicious rules (render-return, children-prop, hook order, exhaustive deps, iterable keys, duplicate JSX props, `==`, `any`) swept with a scratch config that bypasses the project's biome.json. Use when triaging `reports/react-rules.json`, when deciding whether an index key is a real bug, when the same effect is reported by both biome and `perf-static`, or when a file produces a `parse` diagnostic instead of findings. For a11y rules see flawless-a11y; for the suppression rules shared by both sweeps see flawless-findings.
+---
+
+# flawless react-rules
+
+```bash
+bunx @lariocpt/flawless-react "src/**/*.tsx" --tasks react-rules
+```
+
+`react-rules` is one biome sweep with a hand-picked rule set and nothing else:
+`recommended: false`, then `correctness` and `suspicious` blocks enumerated rule by
+rule. The report's own note says it — *"Curated React correctness rules via Biome.
+Local biome.json is bypassed."* — because the point is to answer "does this React
+code have a known defect", not "does this repo agree with its own lint config".
+
+Findings print as `file:line:col lint/<group>/<rule> message` and land in the single
+aggregate `flawless/reports/react-rules.json`. biome must be resolvable (the target
+package's `node_modules`, any ancestor, or `PATH`); when it is not, the task fails
+naming every place it looked.
+
+## What is enabled, and what to do about it
+
+Errors unless marked otherwise.
+
+**`correctness`** — `noChildrenProp`, `noConstAssign`, `noConstantCondition`,
+`noEmptyPattern`, `noInvalidUseBeforeDeclaration`, `noPrecisionLoss`,
+`noRenderReturnValue`, `noVoidElementsWithChildren`, `noVoidTypeReturn`,
+`useExhaustiveDependencies`, `useHookAtTopLevel`, `useIsNan`, `useJsxKeyInIterable`,
+`useValidForDirection`.
+
+**`suspicious`** — `noAssignInExpressions`, `noAsyncPromiseExecutor`,
+`noCompareNegZero`, `noControlCharactersInRegex`, `noDuplicateCase`,
+`noDuplicateClassMembers`, `noDuplicateJsxProps`, `noDuplicateObjectKeys`,
+`noDuplicateParameters`, `noFallthroughSwitchClause`, `noGlobalIsFinite`,
+`noGlobalIsNan`, `noLabelVar`, `noMisleadingCharacterClass`,
+`noMisleadingInstantiator`; and as **warnings**: `noArrayIndexKey`,
+`noConfusingVoidType`, `noEmptyBlockStatements`, `noExplicitAny`,
+`noExtraNonNullAssertion`, `noDoubleEquals`, `noImplicitAnyLet`.
+
+The ones that recur on a real codebase, in the order worth spending time on:
+
+- **`useHookAtTopLevel`** — a hook behind an early return is a genuine bug: the hook
+  order changes between renders and React throws on the state update after. Fix by
+  moving the guard below the hooks or returning the placeholder from the same render
+  path.
+- **`useExhaustiveDependencies`** — biome's resolution of the same question
+  `perf-static` asks as `perf/hook-missing-dependency`. The two engines do not share
+  an implementation, so a fix that silences one should be checked against the other
+  rather than assumed to cover it.
+- **`noArrayIndexKey`** — real for an editable list: add a client-side id at
+  creation, key on it, strip the id at submit. A reasoned suppression is right for a
+  server-static list, and for anything where the index *is* the domain identity.
+  "It's only a list of labels" is not that reason.
+- **`noRenderReturnValue` / `noChildrenProp` / `noVoidElementsWithChildren`** —
+  defects that break at runtime, not style.
+- **`noDuplicateJsxProps`** — the later literal silently wins; the fix is usually
+  deleting the first, and reading why both were there.
+- **`noExplicitAny` / `noDoubleEquals` / `noEmptyBlockStatements`** (warnings) — the
+  honest options are fix, or suppress with a reason, or leave it and let the ledger
+  count stay flat. Quietly adding `// biome-ignore` to reach zero is the one option
+  that makes the codebase worse.
+
+## A parse failure is not a clean file
+
+Biome reports `parse/*` diagnostics for a file it cannot read, and a category filter
+would drop them — so every sweep would call an unreadable file clean. The runner
+lets a parse diagnostic through the filter on purpose: **a file the analyser could
+not read is never a pass.** Triage one like a finding: usually syntax biome's version
+does not know, sometimes a file that should not have been in the sweep at all.
+
+Diagnostics for files outside the swept set are dropped, so a sweep never claims
+findings in code it was not asked about.
+
+## Suppression hygiene
+
+`suppressions/*` diagnostics — biome's own "this suppression is unused" complaints —
+are **dropped from both sweeps**, because the sweep runs a scratch config with only
+its own rules and would otherwise punish you for answering a finding belonging to
+your project's config. Your project's `biome ci` does not drop them. How to make the
+two agree is in flawless-findings.
+
+## Under `--expo`
+
+`react-rules` runs on React Native — same rules, same aggregate file. Rules that only
+exist for DOM elements (`noVoidElementsWithChildren`) cannot match native JSX, so a
+lower count there is expected and is not a coverage loss. See flawless-expo.
+
+## Never
+
+- Never treat "not enabled in my project's biome.json" as a reason to dismiss a
+  finding: this sweep bypasses that config by design.
+- Never bulk-suppress `noExplicitAny` to make the number move.
+- Never count findings from the reports directory — use the task summary or
+  REPORT.md (flawless-findings).

package/.agents/skills/flawless-regen/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: flawless-regen
+description: Regenerate a flawless-react suite safely — the generated/refreshed/kept lifecycle, what a re-run rewrites vs keeps, --force's merge semantics and the colocated-spec provenance stamp, --changed's affected-test narrowing, and proving a run happened via result JSON + REPORT.md rather than stdout. Use before any regeneration over an adopted suite, after upgrading the tool, or when a --changed run appears to have done nothing.
+---
+
+# Regenerating a flawless suite
+
+> **Expo mode adds one write-once file.** `<outDir>/jest.setup.ts` is where
+> hand-written module mocks live and nothing can rebuild them from the analysis, so a
+> re-run never overwrites it — delete it to regenerate. `jest.config.cjs` and every
+> native spec under `unit/` ARE regenerated on each run, like the rest of the derived
+> suite.
+
+The model is regenerate-by-default: derived files track the tool and your
+sources, and only what the tool cannot rebuild is protected. Know the table
+before touching an adopted suite:
+
+| Category | Files | On re-run | Under `--force` |
+| --- | --- | --- | --- |
+| Write-once | `budgets.json`, `host/main.tsx` (wrapper only — the `host/registry.ts` beside it regenerates), `provider.fixtures.ts`, `e2e/global-setup.ts`, `mocks/handlers.ts`, `mock/routes.ts` | kept | **kept** |
+| Merge-kept | `e2e/params.json`, `load/routes.pipes` | kept | **merged** — your edits, rates, commented pipes survive |
+| Colocated specs | `src/**/*.flawless.test.tsx` | kept | **stamp-checked** — untouched refreshed; edited or pre-stamp kept and listed |
+| Everything else | out-dir specs, configs, generated prose, REPORT.md, sidecars | rewritten | rewritten |
+
+## The no-force run over an existing suite
+
+**Exits 0.** Every task — `perf-harness` included — refreshes its derived
+files, rewriting them as a fresh scaffold would (the standalone suite's
+package.json is MERGED — your fields win, and in Next.js mode a
+`flawless:*` script you customised is kept unless its value is one of the
+tool's own spellings — kept keys are listed in REPORT.md as
+`> Kept script(s): ...`, and deleting the key takes the tool's current
+command); write-once files are
+untouched (delete one to get a fresh copy). The perf-harness TaskResult and
+REPORT.md's task row carry a status word: `generated` (fresh out dir),
+`refreshed` (this case), or `kept` (`--changed`, below). Emission is
+deterministic, so a same-version refresh usually diffs nothing; after a tool
+upgrade expect the derived files — and the version banner on the suite's
+`playwright.config.ts` first line — to move. An exit 1 means a real
+failure, never the old harness refusal (that was findings FR-028, fixed).
+
+A regeneration with a wave-3 tool also BURNS DOWN hand-work: the three
+biggest `TODO(flawless)` clusters are now auto-filled where the source
+supports inference — server-action stubs from the action's own literal
+returns, data-dep fixtures from `Promise<T>` annotations or OpenAPI
+examples, and compound parts mounted through their own file's family.
+REPORT.md's hand-work table shows the drop; the exact count depends on how
+much of the app's surface is inferable, so never promise a number —
+markers that remain are exactly the cases inference honestly refused.
+
+## `--force` and the colocated stamp
+
+Every colocated spec opens with a provenance stamp —
+`// @flawless-generated sha256:<hex16> flawless-react@<version>` — hashing
+everything below the line (recomputed after the run's style pass, so a
+formatted spec still reads as untouched). `--force` uses it as the verdict:
+
+- stamp matches body → **rewritten** (this is the refresh you asked for);
+- stamp mismatch → you edited or reformatted it: **kept**, listed in the
+  summary as hand-edited;
+- no stamp (generated pre-stamp, or the line was deleted) → **kept**, listed
+  as pre-stamp.
+
+The escape hatch for both kept cases is the same: delete the file and re-run.
+Kept files also drop out of `handWork` tallies — their discarded render's
+TODOs are not your debt. Still commit (or stash) before forcing: the stamp
+protects hand-edited specs, but the rewrite of untouched ones is exactly what
+you're asking for, and a diff you can read beats trusting any tool.
+
+Expect new spec files for components the analyser newly detected — their
+browser specs mount through `host/registry.ts`, which the same run refreshed;
+hand registrations live in `main.tsx`'s `ALL` spread and survive (see
+flawless-unit-browser). A pre-split `main.tsx` (no `./registry` import)
+triggers the run's migration warning instead.
+
+## `--changed`
+
+`--changed` narrows only the RUN: vitest `related` walks the module graph for
+unit specs, playwright gets an anchored `--grep`, e2e runs when an affected
+component renders on a route. Over an existing suite the perf harness is
+**kept** — the scaffold writes nothing (`status: "kept"`, summary `harness
+kept (generated by flawless-react <X>, tool is <Y>)`, with X read from the
+suite's own banner; pre-banner suites report "unknown version"). The affected
+run is still gated on no task having failed, but a kept harness is a success,
+so any task selection — the full seven included — reaches the affected tests:
+
+```bash
+flawless-react "src/**/*.tsx" --nextjs . --tasks perf-harness,unit-browser,perf-static,a11y,react-rules,e2e,load --changed --no-interactive
+# --tasks matters: bare --no-interactive defaults to perf-harness ALONE, and
+# a harness-only selection has no unit/e2e suites for the affected run to run.
+```
+
+`--changed --force` regenerates: an explicit force outranks the keep. Suite
+failures reach the exit code (a failed affected suite exits 1), so
+`--ci --changed` in a hook is honest.
+
+## Proving a run happened
+
+Never take stdout as evidence — write evidence to files and check the disk:
+
+- **Programmatic runs** (sandboxes, scripts): call `runFlawless`/`runCore` and
+  write `{ exitCode, outDir, results }` to a result file. Pass `nextjs`
+  relative to a cwd you set explicitly, or pass an explicit out dir — in
+  Next.js mode the default resolves against the target root, and a scratch
+  run from the wrong cwd rewrites the target's `package.json` scripts.
+- REPORT.md is rewritten every run — a missing REPORT.md diff means the run
+  did not happen or ran somewhere else.
+- `git status --porcelain` in the target must match the expected touch surface
+  for the run kind (tiny for no-force; `--force` touches the untouched
+  colocated specs, while the ones you hardened stay out of the diff).
+- Another session may be working the same repos: check `git log -1` against
+  what you last saw before attributing a surprise diff to the tool.
+
+## Style adoption
+
+Generated files are reformatted with the host project's biome or prettier
+(including `.mts`/`.cts` configs), and JSON merges preserve the file's
+indentation — a regeneration should produce a semantic diff, never a reformat.
+If `biome ci` errors on a generated file after a regen, that is a tool bug;
+report it rather than hand-formatting generated output.
+
+## Never
+
+- Never `--force` an adopted suite with uncommitted work — the stamp keeps
+  hand-edited colocated specs, but e2e route specs and the provider wrapper
+  have no such guard, and a committed baseline is what makes any rewrite
+  reviewable.
+- Never hand-delete a spec's stamp line to "claim" it — that demotes the file
+  to pre-stamp (kept but nagged about); the file is already yours the moment
+  you edit the body.
+- Never read a mid-session change to the target app as proof your run
+  executed — only your own result file plus the REPORT.md diff counts.
+- Never reach for `--force` on a plain refresh — a no-force re-run already
+  rewrites every derived file, and `--force` adds only the untouched-colocated
+  /e2e-spec rewrite. Decide whether you want that before asking for it.