feat(webkit): add the consumer adoption pipeline (report, canary, reusable gate)

[isaque-bock-azion]

Why

The design system publishes twelve ESLint rules, a stylelint config, a versioned catalog, an MCP and an adoption CLI — and had no workflow_call. A consumer could not call the gate. So docs wrote its own script to aggregate ESLint JSON, and site and console-kit would have written the same one again.

This is the esteira: two commands the design system owns, and one reusable workflow that wires them into any repo with a single uses:.

jobs:
  webkit:
    uses: aziontech/webkit/.github/workflows/webkit-consumer-gate.yml@main

The four stages, deliberately not equally strict

Stage	Blocks?	Why
wiring — webkit doctor	yes	If the wiring is broken the stages below measure the wrong thing. Covers version drift too: it warns on any dependency still pinned to latest.
canary — webkit canary	yes	The only stage that fails when the measurement itself stops working.
adoption — webkit report	no	Score and tables to the run Summary, JSON as an artifact. fail-on: new turns it into a ratchet.
style — stylelint	no	Tokens in authored CSS.

webkit-gate is the single check to mark required: it passes when every stage succeeded or was cleanly skipped, so a consumer can disable a stage without changing which check is required. Same declare -A aggregator and the same SHA-pinned actions as governance.yml.

Three findings that shaped the code

These were measured on the real docs project (pnpm + Astro, eslint 9.39.5), not reasoned about.

1. The preset never applied to .astro

FILES did not list .astro, so on an Astro consumer none of the twelve rules applied to any Astro file. It failed open and silently — the files were linted, reported nothing, and read as clean.

Canary plus a .vue control: identical content reported 3 violations as .vue and zero as .astro. With the extension in the list, four rules fire and it surfaced 3 real hardcoded colours that had been invisible.

⚠️ Consumer impact: an Astro project that upgrades will see new findings in files that were previously unmeasured. That is the fix working, but it is a behaviour change on a previously-green lint. Say so if the review would rather ship it as breaking.

2. The ESLint Node API and the ESLint CLI disagree

Entry point	.astro findings
new ESLint().lintFiles(['.'])	0 — fatal Unexpected token interface per file
node node_modules/…/eslint/bin/eslint.js .	0 — same failure
node_modules/.bin/eslint .	3 — correct

The API returned a fatal parse error for every .astro file even though calculateConfigForFile() reported the right parser and processor for those same files. Spawning the resolved bin file with node failed identically. The shim is what differs: pnpm's .bin/eslint exports NODE_PATH into its .pnpm directories before exec'ing node, and without it ESLint cannot resolve the Astro parser and silently falls back to the default one.

All three paths succeed. Two just return a smaller number. So webkit report goes through the same entry point the project's own lint script uses — the number is correct by construction, not by luck.

3. Every way of losing the rules is silent — hence the canary

What breaks	What you see
The catalog does not resolve	one stderr line; 8 of 12 rules quietly disabled
An extension missing from files	nothing at all for those files
A config edit drops the preset	a lint that still passes

In all three cases the adoption number reads better, not worse. I hit two of them while building this. The canary writes fixtures that violate a rule on purpose and asserts each is still flagged by that exact rule — it is the one check that goes red when the measurement stops working.

Design decisions worth reviewing

• The score counts clean UI files, not violations. A file with twenty findings weighs the same as one with a single finding, so the number moves when a file is finished rather than when the cheapest findings across the repo are cleared. Same shape as the console-kit architecture report, so the two are comparable.
• The baseline is a multiset (<file>::<rule>, one key per occurrence), so a second violation of an already-baselined rule in the same file counts as introduced. A plain set would let it evade. Copied deliberately from scripts/check-authoring.mjs.
• The report always states what it did not look at — no-style-override cannot run on .astro, raw markup is caught by no rule yet, and an unresolved catalog is announced before the numbers. A report that hides its own blind spots is worse than no report.
• --fail-on new refuses to run without a baseline rather than inventing an empty one and reporting everything as new.

Verification

• test:toolkit — 134 pass, 0 fail (19 new: 15 for the report, 4 pinning the presets)
• authoring ratchet — 229 known, 0 new
• catalog:check — no drift · eslint src --max-warnings 0 — clean · prettier — clean
• End to end against docs: webkit report → 72 violations in 30 files, 65% — identical to that repo's own eslint and to its CI run
• Ratchet exercised: 72 recorded → 0 new on a clean run (exit 0) → one violation introduced → exit 1 with the file and rule named, score 65% → 64%
• Canary: 5/5 fire in docs; correctly reports all-fail in a project the rules do not reach; removes its fixtures in a finally

Not in this PR

• Rolling it out. docs currently runs a local script that this replaces; swapping it for the reusable workflow is a follow-up in that repo, then site and console-kit.
• A rule for raw markup (<button> where a component exists). Named as a gap in every report until it exists.
• webkit init does not yet add .webkit-canary/ to .gitignore. The canary removes the folder in a finally, so only a hard crash could leave it behind.

Note

Pushed over SSH: the HTTPS credential in this environment is an OAuth App without the workflow scope, so it refuses to create .github/workflows/*. The repo's origin was left on HTTPS, unchanged.

---

CI

Governance Gate green — all 18 jobs, including the four Vitest browser shards, the four visual-regression shards, and Consumer smoke test (init + build).

One fixup was needed: lint-staged matches packages/webkit/**/*.{js,ts,vue}, which does not include .mjs, so the new test file skipped the pre-commit formatter and only the CI format:check (whose glob does include .mjs) caught it. Worth widening that glob separately — every test/**/*.test.mjs in this package is in the same blind spot.