feat(metro): surface compiler warnings during a build

[YevheniiKotyrlo]

Closes #424.

Stacked on #390. The metro test tier (src/__tests__/metro/) is created by that PR, so this branch is based on it rather than on main. The first four commits are #390's; the two to review here are refactor(compiler): name the shape compile().warnings() returns and feat(metro): surface compiler warnings during a build. Once #390 lands the diff collapses to those two on its own. Happy to re-cut it onto main if you would rather they were independent — nothing in this change depends on #390's code.

What was wrong

compile(css).warnings() collects everything the compiler could not translate — 52 addWarning call sites in src/compiler/declarations.ts. src/metro/metro-transformer.ts called .stylesheet() and threw the compile result away, so the only consumer in the tree was src/jest/index.ts, behind REACT_NATIVE_CSS_TEST_DEBUG + --inspect.

The observable behaviour of an unsupported declaration was therefore: nothing happens, silently. The compiler knew, wrote it down, and dropped the note at the transform boundary.

What this does

The transformer reads .warnings() and writes one block per stylesheet:

react-native-css: src/global.css - 3 declarations dropped, no React Native equivalent
  properties: columns, float
  values: z-index: auto

Issue #424 offered three shapes and you had not picked one, so this is option 1 with option 2's escape hatch: on by default, one capped block per file, warnings: "none" to silence. The reasoning is that an opt-in flag leaves the channel unreachable for everyone who does not read the docs, which is the thing the issue is about. If you would rather it defaulted to "none", that is a one-word change in reportCompilerWarnings and I will make it.

export default withReactNativeCSS(defaultConfig, {
  warnings: "verbose", // "summary" (the default) | "verbose" | "none"
});

The noise model, and why

Metro re-transforms a file whenever its contents change, and a Tailwind build rewrites its CSS output on nearly every source save — so printing unconditionally would reprint an identical block on every keystroke for a whole session.

A block is keyed by the file and by the message it would print, so it appears when a file's set of warnings changes: the first compile, and thereafter only when a fix removes an entry or a new declaration adds one. Fix float and the next block is printed without it. The map holds one entry per CSS file, not one per transform, and lives per worker process, so restarting the bundler reprints.

Volume is capped, on a measured worst case. Compiling the Tailwind corpus already in this repo (src/__tests__/vendor/tailwind) has 387 of its 759 cases asserting a warning, over 87 distinct properties — an uncapped block would be a screenful on the single most common setup this package has. A summary therefore lists ten entries per channel, five values per property and 60 characters per value, then counts the rest and says how to see it. verbose lifts every cap.

Nothing fails a build. These are advisory; a dropped float is not a reason to refuse to bundle.

Delivery, and why console.warn

A transformer cannot reach Metro's reporter — JsTransformerConfig does not carry one, and the transform runs in a jest-worker child. It does not need to: WorkerFarm pipes each worker's stderr to the parent and forwards it as worker_stderr_chunk, which TerminalReporter._logWorkerChunk prints. With maxWorkers: 1 the worker is required in-band and the write lands on the bundler's own stderr directly. Both paths reach the terminal.

That is also why the block carries no ANSI escapes: a piped worker has no TTY, so the vendored picocolors disables itself in exactly the environment this code runs in, and colour would appear only in the in-band maxWorkers: 1 case. Consistently plain beats inconsistently coloured.

Platforms

Native only, and web carries no path at all rather than being skipped. metro-transformer.ts returns to the stock Expo transformer for platform === "web" before the compiler is reached, so a web bundle produces no warnings to surface. The test for it asserts both halves — that nothing was reported, and that the stock transformer still emitted the CSS whole (float included) — so the silence is not silence from having done nothing.

Tests

src/__tests__/metro/ gains two files, 32 tests.

• warnings.test.ts (24) drives the formatter and the reporter. Every fixture is a real compile() result rather than a hand-written CompilerWarnings literal, so a compiler that stopped warning fails these too. The one literal is the functions channel, which getWarnings() declares but no addWarning call site writes to today — the test says so, and exists so the first producer is not born unreachable.
• metro-transformer.test.ts (8) runs the real transform() against the real Expo transform worker, real lightningcss and the real compiler, and asserts the block lands on console.warn. That is the assertion that has never been true: deleting the reportCompilerWarnings call — i.e. restoring main — turns four of these red.

Every one of the 27 was mutation-proved: 22 mutations of the source, each run to confirm which tests it kills, every test killed by at least one. The set includes "the transformer never reports", "no per-file dedupe", "the dedupe is once per process", "verbose does not lift the cap", "web takes the native path" and "the path is always absolute".

Second commit — the fourth channel: diagnostics lightningcss already produced

The three channels above are things this compiler understood and cannot express. There is a fourth thing it knows and was throwing away: input lightningcss could not parse.

lightningcss has two classes of malformed CSS. One throws, and a throw is already loud. The other is recovered and reported through result.warnings with no flag needed — and both lightningcss() calls discarded that return, the first by destructuring only code, the second by ignoring it entirely.

What makes this worth a channel rather than a shrug is where the rule is lost. lightningcss passes the malformed sheet through verbatim; it is this package's own visitor that then finds nothing to extract. So the rule silently disappears and lightningcss's warning is the only evidence it existed:

@unknown-thing { .b { color: blue } }     .b vanishes,  warnings() {}
.a::wat { color: red }                    .a vanishes,  warnings() {}

Both are ordinary typos. An unsupported property in the same position already reported ({"properties":["float"]}), so the gap was specifically the syntax class.

Four decisions, each measured rather than assumed:

• One pass, not two. The second re-parses the first's output and returns the identical message for both triggers, so reading it would add only a duplicate to suppress.
• A Set, not an array. lightningcss emits one warning per occurrence and the message carries no line or column, so two copies of one mistake are a string the reader cannot tell apart from itself. Two distinct mistakes still report twice, and the test asserts both halves — a Set→array mutation turns it red.
• OWN_AT_RULE_WARNINGS filters @react-native and @nativeMapping, the complete set from atRules.ts. lightningcss calls both unknown because they are ours; reporting them would fire on every stylesheet this compiler is built to read.
• No errorRecovery. That flag converts the throwing class into more of this one — a change to what compiles, not to what is reported — and it drops more than it reports: one probe kept a single warning while silently discarding two further rules. It belongs in its own change.

Tailwind is not a noise source, measured. Every v4 authoring at-rule (@tailwind, @theme, @apply, @plugin, @source, @custom-variant, @utility) warns at the lightningcss layer, but none reach this compiler: metro-transformer.ts runs the Expo/Metro CSS worker first and compiles its output, by which point PostCSS has consumed them. Over 24 utility classes plus an inline @theme / @utility / @custom-variant / @source block, in both optimisation modes — zero surviving at-rules, zero warnings.

Checks

yarn test twice from a cold tree, identical both times:

Test Suites: 4 skipped, 61 passed, 61 of 65 total
Tests:       21 skipped, 1195 passed, 1216 total

numFailedTests: 0, numRuntimeErrorTestSuites: 0. The base (#390's branch) measured 1163 passed, 1184 total across 63 suites, so this adds 32 tests and 2 suites and breaks nothing. yarn typecheck and yarn lint both exit 0.

Also in here

compile(css).warnings() returned an inline anonymous type, so a consumer had to restate the channels or reach for ReturnType<...>. That shape is now CompilerWarnings, exported from the compiler's public types beside CompilerOptions. Separate commit, no behaviour change.