CLI reference

Usage

flawless-react <entry-or-glob> [options]
flawless-react                       (interactive menu)

The positional is a .tsx file path or a glob such as "src/**/*.tsx". Each matched file is analysed as its own entry component and runs against every selected task.

Resolution is deliberately simple: if the positional resolves to a path that exists, that single file is the entry. Otherwise it is treated as a glob relative to the current directory — and a value with no glob characters that does not exist on disk matches nothing, so the run stops with no files matched.

Run with no positional in a TTY and you get the interactive menu instead: a prompt for the path or glob, a prompt for the output directory, and a checkbox list of the seven tasks with perf-harness and perf-static preselected. --no-interactive disables that path entirely, in which case a positional and --tasks are required.

Options

Every flag that takes a value accepts both --flag value and --flag=value. An unrecognised --flag is an error rather than a silently ignored argument.

Tasks

The seven task ids are exactly these. Anything else — including plausible-looking transpositions of these very words — is rejected by --tasks.

Selecting nothing leaves the run with perf-harness alone. Task order on the command line is the order they run in, and each task’s findings are printed as they complete.

The e2e suite is not green before it is real

A generated route spec used to claim three things: a response came back, its status was under 500, and the console stayed clean. All three are true of a login screen. An unauthenticated request to a protected page redirects to /login, Playwright follows the redirect, and the login page answers 200 — so thirty route specs could pass having tested one form nobody asked them to test.

global-setup.ts ships as a hand-fill stub, so that was the default state of a freshly generated suite, not an edge case.

Two things close it, and neither is a flag you can forget:

• Every spec asserts where it landed. After networkidle it compares the final pathname against the route it navigated to, trailing slashes normalised. The failure names both ways out — authenticate in global-setup.ts, or change the expectation if the redirect is what the route is supposed to do. Reading after networkidle means a client-side router.push counts too, not only a server 302.
• REPORT.md says the auth hook is still a stub, until it isn’t. The check is byte-identity against what the tool emits, so it clears the moment you edit the file — and filling the hook in while leaving the TODO comment does not keep nagging you.

The fix lives in the route specs, not in the setup stub, and that is deliberate: global-setup.ts is yours the moment it exists and is never overwritten — not even by --force — so a guard added there would never reach a single already-generated suite. Route specs are rewritten under --force, which is how the fix reaches suites that already exist.

This one is verified by running the emitted spec in a real browser against a server that redirects, red before the hook is filled and green after. Reading the spec is exactly what let the old behaviour survive: every assertion in it looked perfectly reasonable.

Task availability and biome

perf-harness, unit-browser, perf-static, e2e and load are self-contained and work anywhere. a11y and react-rules shell out to biome, which the standalone binary cannot carry inside itself, so it is looked for in three places in order: this package’s own node_modules/.bin/biome, then node_modules/.bin/biome in the project being scanned, then biome on PATH. If none of the three hits, both tasks fail with a message naming the paths that were tried.

Any React codebase that already lints with biome satisfies this for free. Otherwise, add it to the project you are scanning:

Or install flawless-react from the source package, which carries @biomejs/biome as a real dependency so all seven tasks work with no further setup. That channel needs Bun >= 1.1 on the machine running it.

Output and reporting

Beyond whatever the selected tasks write, every run produces:

• <outDir>/reports/summary.json — a timestamp plus, per task, its id, ok flag, one-line summary, output count, finding count, and error if it failed.
• <outDir>/REPORT.md — the human account of the same run: how many components can mount, what was excluded and why, and a table of the hand-work still outstanding.
• A <Component>.flawless.json next to each analysed source file, unless --no-inline-summary. It holds per-task finding counts, the three highest-severity findings, and paths to the full a11y, react-rules, and perf-static reports. This is what makes issues surface where the code lives rather than only in a terminal that has scrolled away.

Findings are printed grouped by file, one line each as severity line:column rule message, followed by a summary table with a status, file count, and finding count per task.

Each entry in results carries what the task did

Alongside ok, a task reports a status of "generated", "refreshed" or "kept". The distinction is the whole point of a re-run: a fresh output directory is generated, a re-run over an existing one refreshes the derived files while write-once files hold, and a run that deliberately wrote nothing — --changed over an untouched harness — is kept. All three are ok: true. Reading only the ok flag turns a healthy re-run and a first generation into the same event, which is exactly the reading that used to report a working suite as “task threw”. See Regenerate without losing work.

The two streams are decided separately

--json (and --ci, which implies it) hands stdout to the caller: exactly one JSON blob, nothing else, so piping the whole stream into a parser always works.

That is a statement about stdout, not a vow of silence. Diagnostics keep going to stderr — a file the sweep could not parse and skipped, an OpenAPI spec it ignored, a test-script collision, a Next.js emit that failed. Those lines are the only account of work a run quietly dropped, so an unattended caller should capture stderr as well as parse stdout. Both streams used to share one flag, which meant the mode built for machines was the one that lost them.

Embedding the tool with runFlawless? log controls the stdout narration and is off by default. quiet controls the stderr diagnostics and is off by default too — meaning the warnings speak, unless you pass quiet: true to silence them.

Running the generated tests

--run-tests runs the suites after generation. It only fires when perf-harness, unit-browser or e2e was selected and no task failed, and in an interactive run you are asked to confirm instead. It runs bun install in the output directory first if node_modules is missing, then test:unit, test:perf, and test:browser as the selected tasks warrant, and prints which suites failed.

Exit 0 does not mean the suites passed

Ask for a run that cannot happen — --run-tests with only a11y selected, say — and there is nothing to run: no task in that selection generates a suite. The run used to end there, exit 0, nothing on stderr, and a --json blob byte-for-byte the shape of a green suite run. Two very different outcomes, one indistinguishable result.

So the blob carries testRun, and it has three states:

The invariant worth relying on: mode: "none" if and only if nothing executed, so a green field never appears on a phase that ran nothing. Both runners used to return a bare boolean, and true meant either “every suite passed” or “no suite ran” — one of them printed “all affected suites passed” having spawned nothing at all.

The same sentence goes to stderr, so an interactive run is told too. And errors accounts for a failure that belongs to no task — a Next.js emit that threw exits 1 with every entry in results still ok: true, and before this the blob had nowhere to say why. Between the two, every red run is explicable from the blob alone.

Exit codes