@weft-js/cli 0.1.0 → 0.1.2

package/src/catalog/audit.mjs

@@ -0,0 +1,129 @@
+/** audit diagnostic entries in catalog order. */
+export const audit = [
+  // The rendered page (`weft audit`, and the end of `weft build`): what Lighthouse, a crawler and a screen reader see
+  {
+    code: 'L000',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      "The built pages weren't audited: no Chrome or Chromium on this machine, or no prerendered pages",
+    fix: 'Install Chrome, or set `WEFT_CHROME`; `weft audit --url <deploy>` audits a running site',
+  },
+  {
+    code: 'L001',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      "A control (button, link, field, frame) with no accessible name in the rendered page, at a phone's width or a desktop's: often CSS that hid its only text",
+    fix: 'Give it a name: `label` on a warp `Button` or `aria-label` on an element. For a button that shows its text on wide screens, `collapse="phone"` (or `"tablet"`) hides the text there and keeps it as the name; `display: none` takes the name with it.',
+  },
+  {
+    code: 'L002',
+    severity: 'error',
+    by: 'cli',
+    catches: 'An image with no text alternative in the rendered page',
+    fix: '`alt` on an `<img>` (`alt=""` if it shows nothing a reader needs), `label` on warp\'s `Icon` and `Image`.',
+  },
+  {
+    code: 'L003',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      'Text under WCAG contrast (4.5:1, or 3:1 when large) against what is actually behind it in the rendered page',
+    fix: "Text needs 4.5:1 against what is behind it (3:1 at 24px, or 18.7px bold). Use warp's text roles (`--warp-color-text`, `--warp-color-text-subtle`) on warp surfaces instead of a raw or faded colour.",
+  },
+  {
+    code: 'L004',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      'Another axe-core WCAG A/AA rule the rendered page breaks (the rule Lighthouse runs for Accessibility and Agentic Browsing)',
+    fix: "Each finding names the axe rule, its first remedy and the rule's page.",
+  },
+  {
+    code: 'L010',
+    severity: 'error',
+    by: 'cli',
+    catches: 'An uncaught exception or a `console.error` while the page loads',
+    fix: 'Fix the error the page throws or logs; `weft browser open <route>` then `weft browser snapshot` shows it with the page.',
+  },
+  {
+    code: 'L011',
+    severity: 'error',
+    by: 'cli',
+    catches: 'The browser logged an error loading the page: usually a missing file (404)',
+    fix: 'Usually a file the page asks for that is missing (a 404): fix the URL or ship the file.',
+  },
+  {
+    code: 'L012',
+    severity: 'error',
+    by: 'cli',
+    catches: 'A deprecated browser API in use (Lighthouse Best Practices)',
+    fix: "Replace the deprecated API; Chrome's message names what replaces it.",
+  },
+  {
+    code: 'L013',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      'An issue Chrome logs and Lighthouse counts: mixed content, a blocked cookie, a CSP or CORS failure',
+    fix: 'Open the page in Chrome and read the Issues panel for the request or element it names.',
+  },
+  {
+    code: 'L020',
+    severity: 'error',
+    by: 'cli',
+    catches: 'A built page with no `<title>`',
+    fix: '`meta: { title }` on the route, or `site.title` in weft.config.ts.',
+  },
+  {
+    code: 'L021',
+    severity: 'warning',
+    by: 'cli',
+    catches: 'A built page with no meta description',
+    fix: '`meta: { description }` on the route, or `site.description` in weft.config.ts.',
+  },
+  {
+    code: 'L022',
+    severity: 'error',
+    by: 'cli',
+    catches: '`<html>` with no `lang`',
+    fix: '`site.locale` in weft.config.ts sets it.',
+  },
+  {
+    code: 'L023',
+    severity: 'error',
+    by: 'cli',
+    catches: 'No `width=device-width` viewport meta: phones render at 980px and shrink the page',
+    fix: 'weft writes it; a custom `head` or document must keep it.',
+  },
+  {
+    code: 'L024',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      'A page told search engines not to index it through markup or HTTP headers; an error when public indexing is expected',
+    fix: 'Choose indexing intent with `build.audit.indexing` or `weft audit --indexing public|private`. For public search, remove noindex from both the page and host/proxy, then audit the production URL. Preserve intentional private exclusions.',
+  },
+  {
+    code: 'L025',
+    severity: 'error',
+    by: 'cli',
+    catches: 'A page answered with a 4xx or 5xx status',
+    fix: 'The route errors or is missing: run it with `weft dev` and read the server log.',
+  },
+  {
+    code: 'L030',
+    severity: 'warning',
+    by: 'cli',
+    catches: "The page scrolls sideways at a phone's width",
+    fix: 'Let the named element shrink: `max-inline-size: 100%`, `min-inline-size: 0` on a flex or grid child, or `overflow-x: auto` on wide content, with `tabindex="0"`, a role and a name so a keyboard can scroll it (warp\'s `Table` does this).',
+  },
+  {
+    code: 'L031',
+    severity: 'warning',
+    by: 'cli',
+    catches: 'The layout moved while the page loaded (CLS over 0.05; an error over 0.1)',
+    fix: "Reserve the space before it fills: `width` and `height` on images and video, a fixed `block-size` for what loads late, and fonts through weft's text() plugin (it matches fallback metrics).",
+  },
+]

package/src/catalog/auth.mjs

@@ -0,0 +1,40 @@
+/** auth diagnostic entries in catalog order. */
+export const auth = [
+  {
+    code: 'A001',
+    severity: 'error',
+    by: 'start',
+    catches: 'The auth secret is missing or under 32 characters on a production server',
+    fix: "Set `BETTER_AUTH_SECRET` (`openssl rand -base64 32`) in the server's environment",
+  },
+  {
+    code: 'A002',
+    severity: 'error',
+    by: 'start',
+    catches: "A function with `auth: 'user'` was called with no session (401)",
+    fix: 'Sign in first, or guard the route with `redirect()` in its `load`',
+  },
+  {
+    code: 'A003',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "`auth: 'user'`, but `ctx` has no `user`: the context file never asked for the session",
+    fix: 'Spread `session(auth, request)` into what `src/context.server.ts` returns',
+  },
+  {
+    code: 'A004',
+    severity: 'warning',
+    by: 'start',
+    catches:
+      'A mutation changed the session cookie without a redirect: the tab keeps what the last session cached',
+    fix: "`redirect()` after it: that's a full load, which drops the client cache",
+  },
+  {
+    code: 'A005',
+    severity: 'error',
+    by: 'start',
+    catches: 'The database provider has no Better Auth adapter',
+    fix: 'Pass `options.database` to `createAuth`, or use a provider that has one',
+  },
+]

package/src/catalog/compiler.mjs

@@ -0,0 +1,337 @@
+/** Compiler diagnostic entries in catalog order. */
+export const compilerDiagnostics = [
+  {
+    code: 'W000',
+    severity: 'error',
+    by: 'compiler',
+    catches: 'Syntax error; nothing else in the file is checked',
+    fix: 'Fix the syntax error first',
+  },
+  {
+    code: 'W080',
+    severity: 'error',
+    by: 'cli',
+    catches:
+      'A component with an untyped parameter that nothing renders: its props have nothing to be inferred from',
+    fix: 'Render it, delete it, or annotate the parameter',
+  },
+  {
+    code: 'W081',
+    severity: 'error',
+    by: 'cli',
+    catches: 'An exported component with no written prop type',
+    fix: '`weft fix` writes the inferred type (`weft dev` does this on save)',
+  },
+  {
+    code: 'W082',
+    severity: 'error',
+    by: 'cli',
+    catches: 'A generated `/*inferred*/` prop type no longer matches the callers',
+    fix: '`weft fix` rewrites it, or delete the comment to keep the type you have',
+  },
+  {
+    code: 'W083',
+    severity: 'warning',
+    by: 'cli',
+    catches: 'An `any` weakens an inferred prop; names where the `any` came from',
+    fix: 'Give the source a type, or annotate the prop',
+  },
+  {
+    code: 'W084',
+    severity: 'error',
+    by: 'cli',
+    catches: "One caller passes a type the component body can't handle, and the others agree",
+    fix: 'Change the caller, or make the component handle both',
+  },
+  {
+    code: 'W085',
+    severity: 'warning',
+    by: 'cli',
+    catches: "An inferred prop names a type the component's scope can't see",
+    fix: 'Move the type to module scope or export it, or annotate the parameter',
+  },
+  {
+    code: 'W001',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      'A prop or `.value` used to compute something in the component body outside `derived`/`watch`/JSX/handlers (the body runs once). `const x = props.y` and destructuring only name the prop and stay live',
+    fix: 'Wrap in `derived`, move into `watch`, or `untrack()` if a snapshot is intended',
+    example: 'export function A({ items }: any) { const n = items.length + 1; return <p>{n}</p> }',
+  },
+  {
+    code: 'W002',
+    severity: 'error',
+    by: 'compiler',
+    catches: 'Writing state inside `derived`',
+    fix: 'Move the write to a handler, or make the target `derived`',
+    example:
+      "import { state, derived } from '@weft-js/core'\nexport function A() { const a = state(0); const b = state(0); const d = derived(() => { b.value = a.value; return a.value }); return <p>{d.value}</p> }",
+  },
+  {
+    code: 'W003',
+    severity: 'error',
+    by: 'compiler',
+    catches: '`watch` writes state that its own source reads (cycle)',
+    fix: 'Use `derived`',
+    example:
+      "import { state, watch } from '@weft-js/core'\nexport function A() { const a = state(0); watch(() => a.value, v => { a.value = v + 1 }); return <p>{a.value}</p> }",
+  },
+  {
+    code: 'W004',
+    severity: 'warning',
+    by: 'compiler',
+    catches: '`watch` that only copies one value into another',
+    fix: 'Replace with `derived`',
+    example:
+      "import { state, watch } from '@weft-js/core'\nexport function A() { const a = state(0); const b = state(0); watch(() => a.value, v => { b.value = v }); return <p>{b.value}</p> }",
+  },
+  {
+    code: 'W005',
+    severity: 'error',
+    by: 'compiler',
+    catches: "`state(prop)`: React's `useState(prop)` bug, the box never follows the prop",
+    fix: '`state.linked(() => prop)`, or `untrack` for a one-time copy',
+    example:
+      "import { state } from '@weft-js/core'\nexport function A({ v }: any) { const s = state(v); return <p>{s.value}</p> }",
+  },
+  {
+    code: 'W006',
+    severity: 'error',
+    by: 'compiler',
+    catches: "Nested prop destructuring (`({ user: { name } })`) can't stay live",
+    fix: 'Read at the use site: `user.name`',
+    example: 'export function A({ user: { name } }: any) { return <p>{name}</p> }',
+  },
+  {
+    code: 'W007',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Assigning to a `Derived` (maps TS2540)',
+    fix: 'Make it `state` or `state.linked`',
+  },
+  {
+    code: 'W008',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Box/value mismatch at a prop (a `State<T>` where `T` is expected, or the reverse)',
+    fix: 'Pass `count.value` / pass `count`',
+  },
+  {
+    code: 'W010',
+    severity: 'error',
+    by: 'compiler',
+    catches: '`.map` over objects without `key`',
+    fix: '`key={item.id}` on the row root',
+    example:
+      'export function A({ xs }: any) { return <ul>{xs.map((x: any) => <li>{x.name}</li>)}</ul> }',
+  },
+  {
+    code: 'W011',
+    severity: 'error',
+    by: 'compiler',
+    catches: 'A number on the left of `&&` (renders `0`)',
+    fix: '`cond > 0 &&`',
+    example: 'export function A({ xs }: any) { return <div>{xs.length && <p>has</p>}</div> }',
+  },
+  {
+    code: 'W012',
+    severity: 'error',
+    by: 'compiler',
+    catches: '`derived(async …)`, or reads after `await` in `resource` (untracked)',
+    fix: 'Use `resource`; read before the `await`',
+    example:
+      "import { derived } from '@weft-js/core'\nexport function A() { const d = derived(async () => 1); return <p>{d.value}</p> }",
+  },
+  {
+    code: 'W013',
+    severity: 'error',
+    by: 'compiler',
+    catches: 'Early `return` inside a JSX `.map` callback',
+    fix: 'Filter first: `xs.filter(…).map(…)`',
+    example:
+      'export function A({ xs }: any) { return <ul>{xs.map((x: any) => { if (!x.ok) return null; return <li key={x.id}>{x.name}</li> })}</ul> }',
+  },
+  {
+    code: 'W014',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      'Identity-breaking `.map(p => ({ ...p, … }))` feeding a keyed list: every row re-runs on every change (in-file, and across files via props in `weft check`)',
+    fix: 'Replace only the changed item (`p.id === id ? { ...p, price } : p`), or read the changing field live',
+    example:
+      "import { state } from '@weft-js/core'\nexport function A() { const xs = state([{ id: 'a', price: 1 }]); const push = (price: number) => { xs.value = xs.value.map(p => ({ ...p, price })) }; return <ul onClick={() => push(2)}>{xs.value.map(p => <li key={p.id}>{p.price}</li>)}</ul> }",
+  },
+  {
+    code: 'W015',
+    severity: 'error',
+    by: 'compiler',
+    catches: 'A box rendered without `.value` in JSX (a child, or a native attribute)',
+    fix: 'Add `.value`',
+    example:
+      "import { state } from '@weft-js/core'\nexport function A() { const n = state(0); return <p>{n}</p> }",
+  },
+  {
+    code: 'W016',
+    severity: 'warning',
+    by: 'compiler',
+    catches: 'A non-reactive call passed as a component prop runs again whenever the prop is read',
+    fix: 'Create the value once before JSX, unless the call must run again',
+    example: 'render(() => <App api={createFakeApi()} />, root)',
+  },
+  {
+    code: 'W017',
+    severity: 'warning',
+    by: 'compiler',
+    catches:
+      'One entry of a whole object read per row (`cart[p.id]`, `cart.value[p.id]` in a keyed-list row or its props, `box.value[prop]` in a row component): every change re-runs every row',
+    fix: 'Read the entry from the box: `cart.get(p.id)`; to a row component pass the box (`State<Cart>`) and read `.get(id)` there',
+    example:
+      'export function A({ xs, cart }: any) { return <ul>{xs.map((x: any) => <li key={x.id}>{cart[x.id]}</li>)}</ul> }',
+  },
+  {
+    code: 'W018',
+    severity: 'warning',
+    by: 'compiler',
+    catches:
+      '`const x = untrack(() => …reactive…)` in a component body that only the JSX reads: it renders the setup-time value and never updates',
+    fix: '`derived(() => …)` and render `x.value`; `untrack` only for a value meant to stay fixed',
+    example:
+      "import { untrack, type State } from '@weft-js/core'\nexport function A({ id, live }: { id: string; live: State<Record<string, number>> }) { const n = untrack(() => live.get(id)); return <p>{n}</p> }",
+  },
+  {
+    code: 'W019',
+    severity: 'error',
+    by: 'compiler',
+    catches: 'Unsupported row pattern',
+    fix: 'Read from one item param',
+    example:
+      'export function L({ xs }) { return <ul>{xs.map(({ id, ...more }) => <li key={id}>{id}</li>)}</ul> }',
+  },
+  {
+    code: 'W020',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      'React hook imports and unbound standard hook names; imported custom `useX()` calls in components and local wrappers with resolved hook calls in their bodies; dependency arrays on core `watch`, `derived`, or `memo`. Local names and parameters alone do not establish a hook',
+    fix: 'Use `state` and `.value`, `watch(source, callback)` with `onCleanup`, `derived` and `.value`, `ref={el}`, or plain functions. Core `memo` returns a callable: read `value()`. Reads track dependencies. Only an empty dependency array on `derived` or `memo` has a safe autofix',
+    example:
+      "import { useState } from 'react'\nexport function A() { const [n] = useState(0); return <p>{n}</p> }",
+  },
+  {
+    code: 'W030',
+    severity: 'error',
+    by: 'cli',
+    catches: 'Module-level `state` reachable from the server entry graph (leaks across requests)',
+    fix: '`context`, or mark `state.global`',
+  },
+  {
+    code: 'W040',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      'Early `return` in a component body that depends on state (runs once, never re-checked)',
+    fix: 'Branch in JSX',
+    example:
+      "import { state } from '@weft-js/core'\nexport function A() { const n = state(0); if (n.value > 1) return null; return <p>{n.value}</p> }",
+  },
+  {
+    code: 'W041',
+    severity: 'error',
+    by: 'compiler',
+    catches: '`let` variable mutated in a handler and read in JSX (never updates)',
+    fix: 'Make it `state`',
+    example:
+      'export function A() { let n = 0; return <button onClick={() => { n++ }}>{n}</button> }',
+  },
+  {
+    code: 'W044',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      'A `key` read from `crypto.randomUUID()`, `Date.now()`, `Math.random()` or `performance.now()`: it differs between server and client, so the row is rebuilt on hydration and on every render. At runtime the same miss logs `a key differs between server and client`',
+    fix: 'Key on a stable id from the data',
+  },
+  {
+    code: 'W043',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      '`data-x={true}` or `data-x={false}` on a native element: `data-*` booleans are presence flags, so these write `data-x=""` or nothing, not React\'s `"true"` and `"false"`',
+    fix: '`data-x` for a flag (`weft fix`), or `data-x="true"` for the word. CSS matches `[data-x]`',
+  },
+  {
+    code: 'W050',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      'Raw `addEventListener`, `setInterval`, `new WebSocket` or `new EventSource` in a component with no cleanup (it outlives the component)',
+    fix: '`on(target, type, fn)` / `interval(ms, fn)` from @weft-js/core/browser, or clean it up in `onCleanup`',
+    example: "export function A() { window.addEventListener('keydown', () => {}); return <p /> }",
+  },
+  {
+    code: 'W051',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      'A @weft-js/core/browser value, `on` or `interval` created outside an owner: module scope, a timer or promise callback, an event handler, after `await`',
+    fix: "Create it in a component's (or `defineState`'s) setup, or inside `createRoot(dispose => …)`",
+    example: "import { online } from '@weft-js/core/browser'\nexport const up = online()",
+  },
+  {
+    code: 'W052',
+    severity: 'error',
+    by: 'compiler',
+    catches: '`watch` folding a stream by hand',
+    fix: '`fold` + `initial` where it is read: kept in the cache',
+    example:
+      "import { state, watch } from '@weft-js/core'\nimport { prices } from './server/prices'\nexport function A() { const tick = prices({}); const list = state([]); watch(() => tick.value, m => { list.value = [...list.value, m] }); return <p>{list.value.length}</p> }",
+  },
+  {
+    code: 'W053',
+    severity: 'error',
+    by: 'start',
+    catches: '`.live()` on a query with no `tags` (dev): no mutation can ever poke it',
+    fix: 'Add `tags` to the query, and the same tag to the mutations that change it',
+  },
+  {
+    code: 'W054',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      '`media(query)` without `ssr` in a server-rendered component (hydration mismatch); a warning when `weft check` cannot tell',
+    fix: 'Pass the server value: `media(query, { ssr: false })`',
+    example:
+      "import { media } from '@weft-js/core/browser'\nexport function A() { const dark = media('(prefers-color-scheme: dark)'); return <p>{dark.value ? 'dark' : 'light'}</p> }",
+  },
+  {
+    code: 'W056',
+    severity: 'warning',
+    by: 'compiler',
+    catches:
+      '`watch` that copies a live value (a @weft-js/core/browser value, `.live()`) into `state`',
+    fix: 'Read `live.value` directly, or `derived(() => live.value)`',
+    example:
+      "import { state, watch } from '@weft-js/core'\nimport { online } from '@weft-js/core/browser'\nexport function A() { const isOnline = online(); const up = state(true); watch(() => isOnline.value, v => { up.value = v }); return <p>{up.value}</p> }",
+  },
+  {
+    code: 'W060',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      "A `group()` from @weft-js/core/style that can't be evaluated at build: a value that isn't a literal (named with its path), a `group()` outside a top-level `const`, or an accent that isn't literal tokens",
+    fix: "Inline the token name or literal; define groups as `export const x = group('x', { … })`; raw CSS goes in `css: { … }`",
+    example:
+      "import { group } from '@weft-js/core/style'\nconst px = 13\nexport const g = group('g', { base: { pad: px } })",
+  },
+  {
+    code: 'W061',
+    severity: 'error',
+    by: 'compiler',
+    catches:
+      "`bind:x` on a native element, or `bind:x`/`bind(box)` with something that isn't a box or that isn't a component prop",
+    fix: 'Write `<Card bind:person={name} />`. A form element takes `value` and `onChange`',
+    example:
+      "import { bind, state } from '@weft-js/core'\nexport function A() { const n = state(1); return <input value={bind(n)} /> }",
+  },
+]

package/src/catalog/contracts.mjs

@@ -0,0 +1,18 @@
+/** contracts diagnostic entries in catalog order. */
+export const contracts = [
+  {
+    code: 'C001',
+    severity: 'warning',
+    by: 'cli',
+    catches:
+      "A function's `input` or `output` schema can't become JSON Schema: the contract says `{}`",
+    fix: "Use a schema with JSON Schema support (Zod 4 has it), or drop what can't be represented",
+  },
+  {
+    code: 'C002',
+    severity: 'error',
+    by: 'start',
+    catches: "A function's value failed its `output` schema (dev and tests)",
+    fix: 'Fix `run`, or the schema',
+  },
+]

package/src/catalog/database.mjs

@@ -0,0 +1,52 @@
+/** databaseQueries diagnostic entries in catalog order. */
+export const databaseQueries = [
+  {
+    code: 'Q011',
+    severity: 'warning',
+    by: 'start',
+    catches:
+      "A function read or wrote a table its `tags`/`invalidates` don't name (dev): a mutation of that table won't refresh it",
+    fix: "Add the table's name (or `table:…`) to `tags`/`invalidates`",
+  },
+  {
+    code: 'Q012',
+    severity: 'error',
+    by: 'start',
+    catches: '`@weft-js/start/db*` or `@weft-js/start/auth` reached the client graph',
+    fix: "Import it from a server module (`src/server/**`, `*.server.ts`) or a route's `load`",
+  },
+  {
+    code: 'Q013',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A database URL the driver can't open (a `postgres://` URL given to the SQLite entry, or the reverse)",
+    fix: 'Use the matching `createDb`: `@weft-js/start/db/sqlite` or `@weft-js/start/db/postgres`',
+  },
+  {
+    code: 'Q014',
+    severity: 'error',
+    by: 'start',
+    catches: "The database doesn't match the schema: a table or column is missing",
+    fix: 'Run `weft db generate`, then reload (new migrations apply on the next request)',
+  },
+]
+
+/** databaseSchema diagnostic entries in catalog order. */
+export const databaseSchema = [
+  {
+    code: 'Q015',
+    severity: 'warning',
+    by: 'cli',
+    catches: '`src/db/schema.ts` changed since the last `weft db generate`',
+    fix: 'Run `weft db generate`',
+  },
+  {
+    code: 'Q016',
+    severity: 'error',
+    by: 'start',
+    catches:
+      "A request used the database while it was down, or a migration it needs failed (503; the server log has the driver's error). Pages that run no statements still serve",
+    fix: 'Start the database and check `DATABASE_URL`, or fix the migration: the next statement tries again',
+  },
+]