@weft-js/cli 0.1.1 → 0.1.3

package/src/catalog/plugins.mjs

@@ -0,0 +1,228 @@
+/** pluginConfig diagnostic entries in catalog order. */
+export const pluginConfig = [
+  {
+    code: 'P001',
+    severity: 'warning',
+    by: 'reserved',
+    catches: 'Stray top-level script file outside a declared task',
+    fix: 'Declare it in `tasks`, or delete it',
+  },
+  {
+    code: 'P002',
+    severity: 'warning',
+    by: 'cli',
+    catches: '`package.json` script that is not a `weft …` alias',
+    fix: 'Move it to `tasks` in weft.config.ts and alias `weft run <name>`',
+  },
+  {
+    code: 'P003',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Task duplicates a built-in command or another task (same name or same command)',
+    fix: 'Rename it or remove the duplicate',
+  },
+  {
+    code: 'P004',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Task without `description` or `sideEffects`',
+    fix: 'Add both (`sideEffects: []` when it has none)',
+  },
+  {
+    code: 'P005',
+    severity: 'error',
+    by: 'reserved',
+    catches: 'Write outside `scope.write`',
+    fix: 'Revert the write, or widen `scope.write` deliberately',
+  },
+  {
+    code: 'P006',
+    severity: 'warning',
+    by: 'reserved',
+    catches: 'Unreferenced one-off script',
+    fix: 'Delete it, or declare it as a task',
+  },
+  {
+    code: 'P007',
+    severity: 'error',
+    by: 'cli',
+    proposed: true,
+    catches: 'weft.config.ts fails to load or fails the schema (the Zod path is given)',
+    fix: 'Fix the key at the path shown',
+  },
+  {
+    code: 'P008',
+    severity: 'error',
+    by: 'cli',
+    proposed: true,
+    catches: '`slots` names a slot id weft does not define',
+    fix: 'Use an id from `weft check --json` `slots`',
+  },
+  {
+    code: 'P009',
+    severity: 'error',
+    by: 'cli',
+    proposed: true,
+    catches: '`slots` picks a winner that is not in `plugins` (or does not provide that slot)',
+    fix: 'Add the plugin, or pick one that provides the slot',
+  },
+]
+
+/** pluginSlots diagnostic entries in catalog order. */
+export const pluginSlots = [
+  {
+    code: 'P010',
+    severity: 'error',
+    by: 'cli',
+    catches: 'More than one weft.config file',
+    fix: 'Keep one: `.ts`, `.json` or `.yaml`',
+  },
+  {
+    code: 'P100',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Two providers for a `one` slot (or the same key in a `keyed` slot)',
+    fix: 'Remove one, or name the winner in `slots: {}`',
+  },
+  {
+    code: 'P101',
+    severity: 'error',
+    by: 'cli',
+    catches: 'A slot consumer is used but nothing provides it',
+    fix: 'Add the plugin, or set the option that disables it back',
+  },
+  {
+    code: 'P102',
+    severity: 'error',
+    by: 'reserved',
+    catches:
+      'Provider implements no slot interface version this weft supports (P102w: bound through an adapter)',
+    fix: 'Upgrade the plugin or weft',
+  },
+  {
+    code: 'P103',
+    severity: 'error',
+    by: 'reserved',
+    catches: "Plugin's `weft` peer range doesn't include the installed weft",
+    fix: 'Upgrade either side',
+  },
+  {
+    code: 'P104',
+    severity: 'error',
+    by: 'reserved',
+    catches: '`requires` names a slot that nothing provides',
+    fix: 'Add a provider',
+  },
+  {
+    code: 'P105',
+    severity: 'error',
+    by: 'reserved',
+    catches: 'Cycle in `order.before`/`after`',
+    fix: 'Remove one edge',
+  },
+  {
+    code: 'P106',
+    severity: 'error',
+    by: 'reserved',
+    catches: "Two plugins' `transform` filters matched one module with no declared order",
+    fix: 'Add `order.after` to one',
+  },
+  {
+    code: 'P107',
+    severity: 'error',
+    by: 'reserved',
+    catches: 'Unfiltered `resolveId`/`load`/`transform`, or a `config` hook',
+    fix: 'Add `filter`; move config to data',
+  },
+  {
+    code: 'P108',
+    severity: 'warning',
+    by: 'reserved',
+    catches: 'Plugin over its HMR budget share',
+    fix: 'Narrow filters, cache, or move work to `check`',
+  },
+  {
+    code: 'P109',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Undeclared permission used, or permissions widened since the lock',
+    fix: 'Declare it, then `weft plugins approve`',
+  },
+  {
+    code: 'P110',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Installed plugin integrity differs from `.weft/plugins.lock.json`',
+    fix: 'Reinstall, or approve the update',
+  },
+  {
+    code: 'P111',
+    severity: 'error',
+    by: 'cli',
+    catches: "Diagnostic code outside the plugin's namespace, or a namespace collision",
+    fix: 'Use `<short-name>/<CODE>`',
+  },
+  {
+    code: 'P112',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Plugin AGENTS section over 1 KB',
+    fix: 'Shorten; move detail to the MCP `docs` tool',
+  },
+  {
+    code: 'P113',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Token, catalog, compiler-data or Vite-config key collision',
+    fix: 'Rename in the namespace',
+  },
+  {
+    code: 'P114',
+    severity: 'error',
+    by: 'reserved',
+    catches: 'Provider runtime code in an entry chunk (eager import)',
+    fix: "Reach it only through the slot's `load()`",
+  },
+  {
+    code: 'P115',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Invalid plugin options (Zod path given)',
+    fix: 'Fix the option',
+  },
+  {
+    code: 'P116',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Same plugin twice, or `name`/`version` does not match `package.json`',
+    fix: 'Remove the duplicate',
+  },
+  {
+    code: 'P117',
+    severity: 'error',
+    by: 'cli',
+    catches: '`contribute()` is not pure',
+    fix: 'Move IO to a build-side provider',
+  },
+  {
+    code: 'P118',
+    severity: 'error',
+    by: 'reserved',
+    catches: 'Server code registered outside a server-side slot',
+    fix: 'Provide a slot, or move it into app code',
+  },
+  {
+    code: 'P119',
+    severity: 'error',
+    by: 'reserved',
+    catches: "Provider failed its slot's conformance suite",
+    fix: 'Fix the provider; the failing cases are listed',
+  },
+  {
+    code: 'P120',
+    severity: 'error',
+    by: 'cli',
+    catches: "A weft plugin's `vite` part registered directly in `vite.config.ts`",
+    fix: 'Move it to `plugins` in weft.config.ts',
+  },
+]

package/src/catalog/realtime.mjs

@@ -0,0 +1,195 @@
+/** realtime diagnostic entries in catalog order. */
+export const realtime = [
+  // Realtime (research 30 §8, research 32 §8; R for realtime).
+  {
+    code: 'R001',
+    severity: 'error',
+    by: 'start',
+    catches:
+      '`channel` or `sharedState` without `authorize` (`weft check`, `weft build`, and thrown at definition)',
+    fix: 'Add it (`() => true` must be written explicitly)',
+  },
+  {
+    code: 'R002',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "The memory bus on a multi-instance preset, or `durableObjectBus` outside `cloudflare_durable` (`weft build` fails): a message reaches one instance's clients",
+    fix: '`weft add redis` or `weft add nats`, or `realtime({ bus: postgresBus({ url }) })` in `src/realtime.server.ts`',
+  },
+  {
+    code: 'R003',
+    severity: 'warning',
+    by: 'start',
+    catches:
+      "A mutation wrote a table a live query reads, and their tags don't intersect (dev): open pages won't update",
+    fix: "Add one of the query's tags to `invalidates`",
+  },
+  {
+    code: 'R004',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A wildcard in `realtime({ origins })`, or a hand-written WebSocket handler (`crossws`, `defineWebSocketHandler`) that skips the Origin check: any site could join with a visitor's cookies",
+    fix: 'List the origins, scheme and port included; use `channel`',
+  },
+  {
+    code: 'R005',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      "A stream's `input`, a channel's `params` or client messages, or a shared key or value has an unbounded string or array (`weft build`): a client decides how much the server holds",
+    fix: 'Add `.max()`',
+  },
+  {
+    code: 'R006',
+    severity: 'warning',
+    by: 'start',
+    catches:
+      "A stream's `run` read the database before it subscribed to a topic (dev): what's published in between is lost",
+    fix: 'Call `topic.subscribe()` first, or pass `after`',
+  },
+  {
+    code: 'R007',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      '`ws`, `socket.io-client`, `reconnecting-websocket` or `@microsoft/fetch-event-source` in dependencies: weft owns the connection',
+    fix: 'Use `stream`, `.live()` or `channel`',
+  },
+  {
+    code: 'R008',
+    severity: 'error',
+    by: 'start',
+    catches:
+      'A message over 1 MiB, a request or socket frame over 64 KiB, or a client over the channel rate limit (20 messages a second)',
+    fix: 'Send less, or an id the client fetches; `limits` raises it',
+  },
+  {
+    code: 'R009',
+    severity: 'error',
+    by: 'start',
+    catches:
+      'Over 100 subscriptions or joins on a connection, or 10 connections or sockets for a user',
+    fix: 'Read fewer keys; `limits` raises it',
+  },
+  {
+    code: 'R010',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "An origin that isn't the app's own or in `realtime({ origins })` tried to open a connection",
+    fix: 'List it, scheme and port included',
+  },
+  {
+    code: 'R011',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A channel's `authorize` refused a join or a write (the status is `unauthorized`), at the join or a session re-check",
+    fix: 'Sign in, or check `authorize`',
+  },
+  {
+    code: 'R012',
+    severity: 'warning',
+    by: 'start',
+    catches:
+      "A live query reads a table `changes` reports and no tag names it, or a table `changes` doesn't list (dev): writes from outside the app won't refresh it",
+    fix: "Add the table's name to `tags`, or the table to `dbChanges`",
+  },
+  {
+    code: 'R013',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "A query marked `live: { required: true }` on a target that can't deliver a change feed: a functions preset with no external listener, or no `changes` at all (`weft check`, `weft build`, `weft doctor`)",
+    fix: "Run `weft db listen` on an always-on host and set `listener: 'external'`, deploy to a server preset, add `changes: dbChanges(db, [tables])`, or drop `required`",
+  },
+  {
+    code: 'R014',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      "`changes` on a preset with no long-running process: writes from outside the app won't reach `.live()`, which shows `degraded`",
+    fix: "Run `weft db listen` on an always-on host and set `listener: 'external'`, or deploy to a server preset",
+  },
+  {
+    code: 'R015',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A required live query, and the server's startup probe found no real change feed (a pooler, no trigger, no trigger permission, a Mongo without a replica set): the server stops rather than serve stale data, and dev answers 503",
+    fix: 'What the error names: `dbChanges(db, tables, { listenUrl })` for a direct connection, `weft db live` for triggers',
+  },
+  {
+    code: 'R016',
+    severity: 'warning',
+    by: 'start',
+    catches:
+      'The server settled on a degraded live mode (`poll` or `off`), or a working feed went down: `.live()` shows `degraded` or `reconnecting`',
+    fix: 'What the log line names; `weft doctor` lists the options',
+  },
+  {
+    code: 'R017',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "`dbChanges` on a client it can't watch or something that isn't a table, or `weft db listen` on the memory bus, which stops at that process",
+    fix: 'Use a client from `@weft-js/start/db/*` or `mongoChanges`; set `bus` in `src/realtime.server.ts`',
+  },
+  {
+    code: 'R019',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "A query's `live: { verify }` round trip failed against its target (`weft check`, `weft build`): the message names the link that broke, from `trigger` to `cleanup`",
+    fix: "What the link says: `weft db live` for a trigger, the app's log for a poke, `verify.row` for a row the query can't see",
+  },
+  {
+    code: 'R020',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      'A connection string with a password in source, in a `verify` or a target: it would be committed',
+    fix: 'Read it from the environment: `verify: { db: process.env.STAGING_DATABASE_URL }`',
+  },
+  {
+    code: 'R021',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "A `verify` target isn't available here: fails `weft build`, and `weft check` warns and skips",
+    fix: 'Set `WEFT_STAGING_URL`, `STAGING_DATABASE_URL`, or the variable its target names',
+  },
+  {
+    code: 'R022',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      'A `verify` target that looks like production, or that nothing marks as not: a round trip writes rows',
+    fix: 'Name it in `live.targets` with `production: false`; a name or host that says production is always refused',
+  },
+  {
+    code: 'R023',
+    severity: 'warning',
+    by: 'cli',
+    catches: 'A `verify` passed with only one kind of target, so some links went untested',
+    fix: 'Give it both a URL and a database',
+  },
+  {
+    code: 'R024',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "A `channel` or `sharedState` built for a target that can't hold a WebSocket (Netlify, Vercel, AWS Lambda): `weft build` fails, and where it is let through the page never dials, the channel's `status` is `unavailable` and a send rejects with R024",
+    fix: '`weft deploy hosts`, then a server host (`fly`, `render`); or `--unsafe-allow R024` with why, for a demo that may stay offline there',
+  },
+  {
+    code: 'R018',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      'A table in `changes` that no migration gives a change trigger (`weft check`, `weft build`): the server would fall back to polling',
+    fix: 'Run `weft db live`',
+  },
+]

package/src/catalog/rust.mjs

@@ -0,0 +1,75 @@
+/** rust diagnostic entries in catalog order. */
+export const rust = [
+  {
+    code: 'R101',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "A function with `impl` has no `output`, a type JSON can't carry (`z.date()`, `z.bigint()`, `z.void()`, `z.custom()`), or a one-way `.transform()` on its input (`weft build`, `weft check`, `weft dev`)",
+    fix: 'Use a codec: `z.codec(z.iso.datetime(), z.date(), { decode, encode })`. `z.null()` says a function returns nothing',
+  },
+  {
+    code: 'R102',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "A plain `z.union` of objects in a function with `impl`: it has no tag, so Rust can't tell its arms apart reliably. Scalar unions and `.nullable()` are fine",
+    fix: "Use `z.discriminatedUnion`, or set `rust: { unions: 'allow' }`",
+  },
+  {
+    code: 'R103',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "A sidecar doesn't match the contract: cargo stops where a generated type or method no longer fits (with the function's id), a binary built from another contract, an output the `output` schema rejects, or input serde refuses",
+    fix: "Fix the Rust to fit the TS declaration, which is the source of truth; `.weft/rust/<service>.rs` shows what's generated",
+  },
+  {
+    code: 'R104',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "`native()` on a preset that can't run it (no file system for an addon or a `.wasm`), on a preset with no WASM when `wasm: false` is set, or a `.wasm` that won't build (a warning on a preset the addon runs on). At run time, a build with neither for this platform (503)",
+    fix: "Use `remote('rust://<name>')`, the same crate behind `weft::router`. `rustup target add wasm32-unknown-unknown`, or `rust.services.<name>.wasm: false` if nothing needs a fallback",
+  },
+  {
+    code: 'R105',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      "A cached Rust query with `tags` that reports no table (`weft check` reads the method; `weft dev` sees the call): Q011 can't see into Rust, so nothing checks that the tags cover what it reads",
+    fix: 'Call `ctx.touch("table")` in the Rust, or drop `tags` from a query that reads no table',
+  },
+  {
+    code: 'R106',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A `remote()` call can't be made: no address, no `WEFT_RUST_SECRET`, or the sidecar refused the signature (503)",
+    fix: 'Set `WEFT_RUST_<NAME>_URL` and the same `WEFT_RUST_SECRET` on both sides. `weft dev` and `weft start` do it for what they supervise',
+  },
+  {
+    code: 'R107',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A sidecar didn't answer, or ran past the deadline (503, 504). Only that function fails",
+    fix: "Check that it's running, or raise `timeout` on `remote()`",
+  },
+  {
+    code: 'R108',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A sidecar function panicked or returned an undeclared error (500). The detail stays in the sidecar's log, under the request id",
+    fix: "Find the request id in the sidecar's log, or declare the failure in `errors`",
+  },
+  {
+    code: 'R109',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "A sidecar doesn't build for a reason no contract function explains: a compile error, no crate, or no `cargo`",
+    fix: 'Fix the crate, point `rust.services.<name>.crate` at it, or set `external: true` for one built elsewhere',
+  },
+]

package/src/catalog/server-functions.mjs

@@ -0,0 +1,92 @@
+/** serverFunctions diagnostic entries in catalog order. */
+export const serverFunctions = [
+  // Server functions and the query cache (research 27 §6; Q for query). `start`: reported by @weft-js/start while serving
+  // (the server log, and the error the call rejects with); `runtime`: thrown or warned by the client runtime.
+  {
+    code: 'Q001',
+    severity: 'error',
+    by: 'runtime',
+    catches:
+      '`q()` (a live query, a Resource) called with no owner: in `load`, a handler, a timer or module scope',
+    fix: '`await q.fetch(input)` there; `q()` in components and defineState scopes',
+  },
+  {
+    code: 'Q002',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A query's or mutation's input failed its schema (400, with the issues and their paths)",
+    fix: 'Pass what the schema accepts',
+  },
+  {
+    code: 'Q003',
+    severity: 'error',
+    by: 'start',
+    catches:
+      '`query`/`mutation` defined outside a server module: its `run` and imports would ship to the client (the build fails)',
+    fix: 'Move it to `src/server/**` or a `*.server.ts` file',
+  },
+  {
+    code: 'Q004',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A mutation called while the server handles a GET (`load`, a page render, a query's `run`)",
+    fix: 'Call it from a handler or another mutation; reads go in queries',
+  },
+  {
+    code: 'Q005',
+    severity: 'warning',
+    by: 'start',
+    catches:
+      "A server function's result doesn't survive JSON (`Date`, `Map`, `Set`, a class, `undefined` in an array, a function, `NaN`): the client sees another value",
+    fix: 'Send plain data (ISO strings, arrays, objects)',
+  },
+  {
+    code: 'Q006',
+    severity: 'error',
+    by: 'start',
+    catches:
+      'A cached (`cache: { life }`) query reads `ctx.request`, `ctx.response` or `ctx.user`: its value is shared by every user',
+    fix: 'Drop `cache`, or pass the value as input',
+  },
+  {
+    code: 'Q007',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "`redirect()` after the page started streaming (a component's query): the status is already sent",
+    fix: "Call the query in the route's `load`, which runs before the first byte",
+  },
+  {
+    code: 'Q008',
+    severity: 'warning',
+    by: 'start',
+    catches: `A mutation \`invalidates\` a tag no query declares (\`todo:*\` covers \`todo:\${id}\`): nothing refreshes`,
+    fix: "Fix the tag name, or add it to the query's `tags`",
+  },
+  {
+    code: 'Q009',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "`/_weft/fn/<id>` names no function: the page is older than the server, or the module isn't a server module",
+    fix: 'Reload; keep `query`/`mutation` exports in server modules',
+  },
+  {
+    code: 'Q010',
+    severity: 'error',
+    by: 'start',
+    catches:
+      'A mutation request without the CSRF proof (POST, JSON, `x-weft: 1`, same origin): 403',
+    fix: 'Call mutations through their stub, not a hand-made `fetch` or form',
+  },
+  {
+    code: 'S011',
+    severity: 'warning',
+    by: 'runtime',
+    catches:
+      "`mutation({ optimistic })` updated a query its invalidated tags didn't cover: the prediction has no fresh value to land on (held until a refetch)",
+    fix: "Add one of the query's tags to `invalidates`",
+  },
+]

package/src/catalog/state.mjs

@@ -0,0 +1,39 @@
+/** serverState diagnostic entries in catalog order. */
+export const serverState = [
+  {
+    code: 'S001',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      'A server object or array (`q().value`, `await q.fetch()`, or a map, filter or spread of one) copied into `state`: it goes stale and its rows lose their identity',
+    fix: 'Reference the query and `derived` from it; store ids; `state.linked` for edits, `untrack` for a deliberate snapshot',
+  },
+  {
+    code: 'S002',
+    severity: 'error',
+    by: 'runtime',
+    catches:
+      'A `defineState` scope reached on the server outside a render (module scope, `load`, a server function, a timer): it would be shared by every request',
+    fix: 'Read it in a component, a handler or a `derived`; pass values into server code as arguments',
+  },
+]
+
+/** stateTransport diagnostic entries in catalog order. */
+export const stateTransport = [
+  {
+    code: 'S012',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      '`state.linked` over a query value with no `key`: a refetch resets what someone is typing',
+    fix: 'Add `{ key: () => source.value?.id }`',
+  },
+  {
+    code: 'S013',
+    severity: 'warning',
+    by: 'runtime',
+    catches:
+      'A `local` or `session` persisted box read in a server render: the page shows `init`, then flashes to the stored value',
+    fix: "`persist: { in: 'cookie' }` if it's small, or render it client-only",
+  },
+]

package/src/catalog/style-groups.mjs

@@ -0,0 +1,54 @@
+/** styleGroups diagnostic entries in catalog order. */
+export const styleGroups = [
+  // Style groups (research 23 §3). D010 is warp's contrast gate (its own plugin); D040 and D081 are reserved by warp's docs.
+  {
+    code: 'D020',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      'Class soup: a static `class`/`className` with more than 8 classes, or the same class list (4+ classes) in two or more places',
+    fix: "Extract a style group (`group('order-card', …)`, name suggested from the component) and spread it; `weft style find` first, one may already fit",
+  },
+  {
+    code: 'D021',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      'Two style groups resolve to 90% or more of the same CSS (`similar` in .weft/styles.json)',
+    fix: 'Merge them into one group with an axis for what differs',
+  },
+  {
+    code: 'D022',
+    severity: 'info',
+    by: 'cli',
+    catches: 'The same accent (`accent: { … }` at a call site) on one group at 3 or more sites',
+    fix: 'Promote it to an axis value and pass that value at those sites',
+  },
+  {
+    code: 'D023',
+    severity: 'warning',
+    by: 'cli',
+    catches: 'A `css: { … }` escape (raw CSS) in a style group',
+    fix: 'Use the token the fix names; keep the escape only where no intent sets the property',
+  },
+  {
+    code: 'D024',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      "Styles that fight with no order: two group roots spread on one element; two compounds that can match at once and set one property differently, or an accent that sets what the site's own axis value sets (`weft check`)",
+    fix: 'One group per element (nest an element, or make it an axis); exclusive compound `when`s; drop the accent or make it an axis value',
+    example:
+      "import { group } from '@weft-js/core/style'\nconst a = group('a', { base: { pad: 'group' } })\nconst b = group('b', { base: { gap: 'related' } })\nexport function X() { return <li {...a()} {...b()} /> }",
+  },
+  {
+    code: 'D025',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      "Unknown name in a style group: an axis value, axis, state or part a call site uses that the group doesn't have, or an intent or token that isn't in the vocabulary (also a type error)",
+    fix: 'Use one of the names listed (the closest come first); `weft style explain <group>` shows them all',
+    example:
+      "import { group } from '@weft-js/core/style'\nconst card = group('card', { axes: { status: { open: {}, late: {} } } })\nexport function X() { return <article {...card({ status: 'lost' })} /> }",
+  },
+]