@weft-js/cli 0.0.0-stage → 0.1.1

package/src/start.mjs

@@ -0,0 +1,296 @@
+// `weft dev`, `weft build` and `weft routes` for an app with src/routes: they run @weft-js/start (research 25 §6–7).
+// @weft-js/start resolves from the app first (its own version), then from this workspace.
+
+import { audit, builtPublic } from './audit.mjs'
+import { writeMap } from './map.mjs'
+import { spawn, spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { parseEnv } from 'node:util'
+import { dbLayer } from './db-layer.mjs'
+import { diagnostic, locate, positions } from './diag.mjs'
+import { loadConfig } from './load-config.mjs'
+import { sync } from './plugins.mjs'
+import { requireTrust } from './trust.mjs'
+import { attachProps } from './props-listener.mjs'
+import { host, presetFor } from './deploy/hosts.mjs'
+
+export async function start(root, sub) {
+  let file
+  try {
+    file = createRequire(join(root, 'package.json')).resolve(`@weft-js/start/${sub}`)
+  } catch {
+    const sibling = new URL(`../../start/src/${sub}.mjs`, import.meta.url)
+    if (!existsSync(sibling)) throw Object.assign(new Error('@weft-js/start is not installed in this project'), { code: 'E_USAGE' })
+    file = sibling
+  }
+  return import(typeof file === 'string' ? pathToFileURL(file).href : file.href)
+}
+
+/** The config's `site` (metadata defaults), and the config diagnostics. Slot files are synced first, so @weft-js/core/vite
+ * finds the build-side providers (`.weft/slots/<id>.build.json`, research 26 §3.1). */
+async function site(root) {
+  const loaded = await loadConfig(root)
+  if (!loaded.diagnostics.some(d => d.code === 'P007') && loaded.config?.plugins?.length) sync(root, loaded)
+  // A build on a config that doesn't load would quietly drop every plugin: fonts, tokens and slots.
+  const bad = loaded.diagnostics.find(d => d.code === 'P007')
+  if (bad) throw Object.assign(new Error(`P007: ${bad.message ?? bad.why}`), { code: 'E_REFUSED' }) // the config's fault, not the command's
+  return { site: siteOf(loaded), hydration: loaded.config?.hydration, diagnostics: loaded.diagnostics }
+}
+
+/** `site` with what plugins know about the app's look (`card` in a manifest): warp's colours, the text plugin's faces. */
+export function siteOf(loaded) {
+  const base = loaded.config?.site ?? {}
+  const given = (loaded.contributions ?? []).map(c => c.manifest.card).filter(Boolean)
+  if (!given.length) return base
+  const card = Object.assign({}, ...given)
+  return { ...base, card: { ...card, ...base.card, fonts: { ...card.fonts, ...base.card?.fonts } } }
+}
+
+/** `runtime` in weft.config.ts or `--runtime`, as a Nitro preset (research 28 §5). */
+export const PRESETS = { node: 'node', bun: 'bun', deno: 'deno_server' }
+/** With no `runtime` in the config, the one running this: a machine may have only that one. */
+export const hostRuntime = () => (process.versions.deno ? 'deno' : process.versions.bun ? 'bun' : 'node')
+
+/** `.env` under what's already set. Not `process.loadEnvFile`: on Deno the file wins. */
+function loadEnv(root) {
+  const file = join(root, '.env')
+  if (existsSync(file)) for (const [key, value] of Object.entries(parseEnv(readFileSync(file, 'utf8')))) process.env[key] ??= value
+}
+
+export async function devCommand(root, { port } = {}) {
+  // Production takes the host's environment; dev takes `.env`. What's already set wins.
+  loadEnv(root)
+  requireTrust(root, await loadConfig(root))
+  const { dev } = await start(root, 'app')
+  await writeMap(root)
+  const config = await site(root)
+  const rust = (await loadConfig(root)).config?.rust
+  const { devSidecars, usesRemote } = await start(root, 'sidecar')
+  // Before the dev server: its worker inherits the addresses, and a request can't reach a sidecar that's still building.
+  const sidecars = usesRemote(root) ? await devSidecars({ root, site: config.site, rust }) : undefined
+  const server = await dev({ root, ...config, port })
+  if (server.watcher) server.weftProps = attachProps(server, root, (await loadConfig(root)).config)
+  if (sidecars) {
+    sidecars.attach(server)
+    const close = server.close.bind(server)
+    server.close = async () => (await sidecars.close(), close())
+  }
+  return server
+}
+
+/**
+ * `--unsafe-allow` and `build.unsafeAllow`: codes (or a family, `L`, or `all`) a build reports and goes on past instead
+ * of failing on. For forcing a deploy you have looked at; each one it lets through is listed, as a warning, every build.
+ */
+export function unsafeAllowed(flag, config) {
+  const reasons = config?.build?.unsafeAllow ?? {}
+  const codes = [...String(flag ?? '').split(','), ...Object.keys(reasons)].map(c => c.trim()).filter(Boolean)
+  const allows = d => codes.some(c => c === 'all' || c === d.code || (/^[A-Z]$/.test(c) && d.code.startsWith(c)))
+  const reason = d => reasons[d.code] ?? reasons[d.code[0]] ?? reasons.all ?? (flag ? '--unsafe-allow' : '')
+  return { allows, let: d => ({ ...d, severity: 'warning', why: `UNSAFE, let through (${reason(d)}): ${d.why}` }) }
+}
+
+export async function buildCommand(root, { preset, runtime, unsafeAllow } = {}) {
+  requireTrust(root, await loadConfig(root))
+  const unsafe = unsafeAllowed(unsafeAllow, (await loadConfig(root)).config)
+  const forced = []
+  const { build } = await start(root, 'app')
+  const { writeContract } = await start(root, 'contract')
+  const t = performance.now()
+  const config = await site(root)
+  const chosen = runtime ?? (await loadConfig(root)).config?.runtime ?? hostRuntime()
+  // `deploy.target` picks the preset when nothing else does: a build for Fly is the runtime's server, for Netlify `netlify`
+  const target = !preset && !runtime && (await loadConfig(root)).config?.deploy?.target
+  if (target) preset = presetFor(host(target), chosen)
+  if (!preset && !PRESETS[chosen]) throw Object.assign(new Error(`unknown runtime "${chosen}": use ${Object.keys(PRESETS).join(', ')}`), { code: 'E_USAGE' })
+  preset ??= PRESETS[chosen]
+  // A build holds no secrets: an app's env check stands down, and server modules load without a database.
+  const held = process.env.WEFT_BUILD
+  process.env.WEFT_BUILD = '1'
+  try {
+    const rust = (await loadConfig(root)).config?.rust
+    const refuse = d => {
+      if (unsafe.allows(d)) return void forced.push(unsafe.let(d))
+      // a finding, not a misuse: exit 1 with the fix and the way past it, never the usage text
+      throw Object.assign(new Error(`${d.code}: ${d.why}${d.rendered ? `\n${d.rendered}` : ''}\nTo build anyway: --unsafe-allow ${d.code}, or build.unsafeAllow in weft.config.ts with why.`), { code: 'E_REFUSED' })
+    }
+    // What the preset can't do fails now, not after a build: a verify runs at the end, against a target that's up.
+    const { readLivePlan } = await start(root, 'contract')
+    const plan = await readLivePlan({ root, site: config.site, preset, live: (await loadConfig(root)).config?.live, verify: false })
+    const unlive = plan.diagnostics.find(d => d.severity === 'error')
+    if (unlive) refuse(unlive)
+    const { buildSidecars, shipSidecars, startSidecars, usesRemote } = await start(root, 'sidecar')
+    const contracted = () => writeContract({ root, site: config.site, preset, rust })
+    let warned = []
+    // Sidecars first: prerendering a share card runs its route's `load`, which may read one.
+    const running = usesRemote(root) ? await contracted().then(async c => {
+      const stop = c.diagnostics.find(d => d.severity === 'error')
+      if (stop) refuse(stop)
+      const built = await buildSidecars({ root, contract: c.contract, rust, preset })
+      const failed = built.diagnostics.find(d => d.severity === 'error')
+      if (failed) refuse(failed)
+      warned = built.diagnostics
+      return startSidecars({ root, built: true, log: () => {} })
+    }) : undefined
+    const before = { ...process.env }
+    Object.assign(process.env, running?.env)
+    let output
+    try {
+      ({ output } = await build({ root, ...config, preset, logLevel: 'warn' }))
+    } finally {
+      running?.close()
+      for (const k of Object.keys(running?.env ?? {})) before[k] === undefined ? delete process.env[k] : (process.env[k] = before[k])
+    }
+    const contract = await writeContract({ root, site: config.site, preset, rust, live: (await loadConfig(root)).config?.live, verify: true })
+    for (const refused of contract.diagnostics.filter(d => d.severity === 'error')) refuse(refused)
+    if (running) shipSidecars(root)
+    await writeMap(root)
+    // Last, the pages as built, in a clean Chrome at a phone's width and a desktop's (audit.mjs): an error fails the build.
+    const settings = (await loadConfig(root)).config?.build?.audit ?? true
+    const audited = settings === false
+      ? { diagnostics: [diagnostic({ code: 'L000', severity: 'warning', file: 'weft.config.ts', why: '`build.audit` is false: the built pages were not audited.' })] }
+      : await audit(root, { dir: builtPublic(root), ...(typeof settings === 'object' && settings) })
+    const pages = audited.diagnostics.map(d => (d.severity === 'error' && unsafe.allows(d) ? unsafe.let(d) : d))
+    const kept = [...contract.diagnostics.filter(d => !(d.severity === 'error' && unsafe.allows(d))), ...warned].map(d => diagnostic({ file: '.weft/contract.json', ...d }))
+    const diagnostics = [...kept, ...pages, ...forced.map(d => diagnostic({ file: '.weft/contract.json', ...d }))]
+    return { ok: !diagnostics.some(d => d.severity === 'error'), preset, output, contract: contract.path, functions: contract.functions, audited: audited.pages?.length ?? 0, diagnostics, ms: Math.round(performance.now() - t) }
+  } finally {
+    if (held === undefined) delete process.env.WEFT_BUILD
+    else process.env.WEFT_BUILD = held
+  }
+}
+
+/** The built server's command for each runtime: `.env` for a local run, the host's environment otherwise. */
+const SERVERS = { node: ['node', ['--disable-warning=ExperimentalWarning']], bun: ['bun', ['run']], deno: ['deno', ['run', '-A']] }
+
+/** `weft start`: run `.output/` on the runtime it was built for. Resolves with the exit code. */
+export async function startCommand(root, { runtime } = {}) {
+  const chosen = runtime ?? (await loadConfig(root)).config?.runtime ?? hostRuntime()
+  if (!SERVERS[chosen]) throw Object.assign(new Error(`unknown runtime "${chosen}": use ${Object.keys(SERVERS).join(', ')}`), { code: 'E_USAGE' })
+  loadEnv(root)
+  const [cmd, flags] = SERVERS[chosen]
+  // Sidecars first: the server's environment has their addresses, and they outlive a crash of either side.
+  const { startSidecars } = await start(root, 'sidecar')
+  const sidecars = await startSidecars({ root })
+  // The running binary when it can be: Deno on Windows doesn't find itself on PATH.
+  const child = spawn(chosen === hostRuntime() ? process.execPath : cmd, [...flags, join('.output', 'server', 'index.mjs')], { cwd: root, stdio: 'inherit', env: { ...process.env, ...sidecars.env } })
+  process.once('SIGINT', () => child.kill('SIGINT'))
+  process.once('SIGTERM', () => child.kill('SIGTERM'))
+  return new Promise(ok => { child.on('close', code => { sidecars.close(); ok(code ?? 0) }) })
+}
+
+/** The hash `weft db generate` records and Q015 compares. */
+export const schemaHash = text => createHash('sha256').update(text).digest('hex').slice(0, 16)
+
+/** What `weft db` takes. There's no `migrate`: new migrations apply on the next request. */
+export const DB_COMMANDS = ['generate', 'live', 'listen']
+
+/** `weft db generate [name]`: the data layer's migration, on Node like all of dev (research 28 §2, 34 §4). */
+export async function dbCommand(root, sub, name) {
+  if (!DB_COMMANDS.includes(sub)) throw Object.assign(new Error(`weft db ${sub ?? ''}: use generate (new migrations apply on the next request), live or listen`), { code: 'E_USAGE' })
+  if (sub === 'live') return dbLive(root)
+  if (sub === 'listen') return dbListen(root)
+  const layer = await dbLayer(root)
+  if (!layer) throw Object.assign(new Error('this app has no database: `weft add db` adds one'), { code: 'E_USAGE' })
+  const output = layer.generate(root, name)
+  const schema = layer.schema && join(root, layer.schema)
+  if (schema && existsSync(schema)) writeFileSync(join(root, layer.migrations, '.schema-hash'), schemaHash(readFileSync(schema)) + '\n')
+  return { ok: true, output }
+}
+
+/**
+ * Route findings as diagnostics, pointing at the `meta` export, or at where one goes. H011's fix is that export, as an
+ * edit an agent can apply: not safe, since the words are a start and not the page's best.
+ */
+export function routeDiagnostics(root, found) {
+  const text = f => { try { return readFileSync(join(root, f), 'utf8') } catch { return '' } }
+  return found.map(({ code, severity, file, route, why, help }) => {
+    const source = text(file)
+    const at = code === 'H011' && help?.startsWith('export const') && !/\bexport\s+(?:const|function|async function)\s+meta\b/.test(source) ? source.indexOf('export default') : -1
+    const place = positions(source)
+    const fix = at >= 0 && { fix: { safe: false, description: 'Add `meta`', edits: [{ file, span: place.span(at, at), offset: [at, at], text: `${help}\n\n` }] } }
+    return { ...diagnostic({ code, severity, file, why, help, ...locate(source, 'meta'), ...fix }), route }
+  })
+}
+
+/** `weft db live`: a migration that adds change triggers to the tables in `changes` (Postgres, SQLite, MySQL). */
+async function dbLive(root) {
+  const held = process.env.WEFT_BUILD
+  process.env.WEFT_BUILD = '1'
+  const config = await site(root)
+  const { withRealtime } = await start(root, 'contract')
+  const { changeSql } = await start(root, 'changes-sql')
+  let sql, tables
+  try {
+    ({ sql, tables } = await withRealtime({ root, site: config.site }, async ({ changes }) => {
+      if (!changes?.defs) throw Object.assign(new Error('`src/realtime.server.ts` has no `changes: dbChanges(db, [tables])`'), { code: 'E_USAGE' })
+      const defs = await changes.defs()
+      return { sql: changeSql(changes.dialect, defs), tables: defs.map(t => t.name) }
+    }))
+  } finally {
+    if (held === undefined) delete process.env.WEFT_BUILD
+    else process.env.WEFT_BUILD = held
+  }
+  const layer = await dbLayer(root)
+  if (layer?.layer !== 'drizzle') return { ok: true, output: `${sql}\n-- add this to a migration of your data layer` }
+  const req = createRequire(join(root, 'package.json'))
+  const bin = join(dirname(req.resolve('drizzle-kit')), 'bin.cjs')
+  const r = spawnSync(process.execPath, [bin, 'generate', '--custom', '--name=weft_live'], { cwd: root, encoding: 'utf8' })
+  if (r.status !== 0) throw Object.assign(new Error(`drizzle-kit generate failed:\n${r.stdout}${r.stderr}`), { code: 'E_INTERNAL' })
+  const { entries } = JSON.parse(readFileSync(join(root, layer.migrations, 'meta', '_journal.json'), 'utf8'))
+  const file = join(layer.migrations, `${entries.at(-1).tag}.sql`)
+  writeFileSync(join(root, file), sql)
+  return { ok: true, output: `${file}: change triggers for ${tables.join(', ')}. They apply on the next request.` }
+}
+
+/** `weft db listen`: the change feed as its own process, for an app on functions. Runs until SIGINT or SIGTERM. */
+async function dbListen(root) {
+  if (existsSync(join(root, '.env'))) process.loadEnvFile(join(root, '.env'))
+  const config = await site(root)
+  const { withRealtime } = await start(root, 'contract')
+  await withRealtime({ root, site: config.site }, async ({ changes, bus }, server) => {
+    if (!changes) throw Object.assign(new Error('`src/realtime.server.ts` has no `changes`'), { code: 'E_USAGE' })
+    const { listen } = await server.ssrLoadModule('@weft-js/start/listen')
+    const stop = await listen({ changes, bus: bus ?? { name: 'memory' } })
+    await new Promise(ok => { process.once('SIGINT', ok); process.once('SIGTERM', ok) })
+    await stop()
+  })
+  return { ok: true, output: 'weft db listen: stopped' }
+}
+
+/** `weft doctor`: what live data does on this deploy target, and what to do about what it can't. */
+export async function doctorCommand(root, { preset, runtime } = {}) {
+  const config = await site(root)
+  const chosen = runtime ?? (await loadConfig(root)).config?.runtime ?? 'node'
+  const held = process.env.WEFT_BUILD
+  process.env.WEFT_BUILD = '1'
+  try {
+    const { readLivePlan } = await start(root, 'contract')
+    const plan = await readLivePlan({ root, site: config.site, preset: preset ?? PRESETS[chosen], live: (await loadConfig(root)).config?.live, verify: false })
+    return { ...plan, diagnostics: plan.diagnostics.map(d => diagnostic({ file: 'src/realtime.server.ts', ...d })) }
+  } finally {
+    if (held === undefined) delete process.env.WEFT_BUILD
+    else process.env.WEFT_BUILD = held
+  }
+}
+
+/** Every route's merged metadata, tags and card mode (`--meta`), or just the route table. */
+export async function routesCommand(root, { meta, preset } = {}) {
+  const config = await site(root)
+  if (meta) {
+    const { routesMeta } = await start(root, 'inspect')
+    const result = await routesMeta({ root, site: config.site, preset })
+    return { ...result, diagnostics: [...config.diagnostics, ...routeDiagnostics(root, result.diagnostics)] }
+  }
+  const { scanRoutes, filePath } = await start(root, 'routes')
+  const manifest = scanRoutes(root)
+  return {
+    version: 1, ok: true, problems: manifest.problems,
+    routes: manifest.routes.map(r => ({ path: r.kind === 'page' ? filePath(manifest, r) : r.kind, kind: r.kind, file: r.file, layouts: r.layouts, params: r.params, card: r.card ?? null })),
+    diagnostics: config.diagnostics,
+  }
+}

package/src/state-checks.mjs

@@ -0,0 +1,213 @@
+// S001 and S012 in `weft check` (research 14 §3.1, §3.4, research 29 §4): server values copied into state, and
+// `state.linked` over one with no `key`. X037: a resource or query made beside the `<Boundary>` meant to wait for it.
+// These need to know which imports are queries, so they read the server modules; the compiler sees one file at a time. TypeScript's parser only, no type checking, and a name's taint lasts for the
+// function it was declared in, so a same-named primitive elsewhere isn't flagged.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import ts from 'typescript'
+import { local } from './alias.mjs'
+import { diagnostic, positions } from './diag.mjs'
+import { discover } from './files.mjs'
+
+const isServerModule = rel => rel.startsWith('src/server/') || /\.server\.[cm]?[jt]sx?$/.test(rel)
+const KEEPS_OBJECTS = new Set(['map', 'filter', 'flatMap', 'slice', 'sort', 'toSorted', 'reverse', 'concat', 'find', 'at', 'structuredClone'])
+const ESCAPES = new Set(['untrack', 'optimistic'])
+
+/** `export const name = query(` in a module: the names of its queries. */
+const queriesOf = text => new Set([...text.matchAll(/export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*query\s*\(/g)].map(m => m[1]))
+
+function moduleFile(root, from, spec) {
+  const abs = local(join(root, from), spec)
+  if (!abs) return undefined
+  const base = relative(root, abs).split('\\').join('/').replace(/\.js$/, '')
+  return ['', '.ts', '.tsx', '.mts', '.js', '/index.ts'].map(x => base + x).find(f => /\.[cm]?[jt]sx?$/.test(f) && existsSync(join(root, f)))
+}
+
+/** Local names of the queries `sf` imports from server modules. */
+function importedQueries(root, rel, sf, cache) {
+  const out = new Set()
+  for (const n of sf.statements) {
+    if (!ts.isImportDeclaration(n) || !n.importClause?.namedBindings || !ts.isNamedImports(n.importClause.namedBindings)) continue
+    const file = moduleFile(root, rel, n.moduleSpecifier.text)
+    if (!file || !isServerModule(file)) continue
+    if (!cache.has(file)) cache.set(file, queriesOf(readFileSync(join(root, file), 'utf8')))
+    for (const s of n.importClause.namedBindings.elements) if (cache.get(file).has((s.propertyName ?? s.name).text)) out.add(s.name.text)
+  }
+  return out
+}
+
+function scan(rel, text, queries, report) {
+  const sf = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true, /\.[jt]sx$/.test(rel) ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+  const frames = [{ handles: new Set(), values: new Set() }]
+  const has = (kind, name) => frames.some(f => f[kind].has(name))
+  const peel = e => { while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isNonNullExpression(e) || ts.isSatisfiesExpression(e)) e = e.expression; return e }
+
+  const isQueryCall = e => ts.isCallExpression(e) && (ts.isIdentifier(e.expression) ? queries.has(e.expression.text) : ts.isPropertyAccessExpression(e.expression) && e.expression.name.text === 'live' && ts.isIdentifier(e.expression.expression) && queries.has(e.expression.expression.text))
+  const isFetch = e => ts.isCallExpression(e) && ts.isPropertyAccessExpression(e.expression) && e.expression.name.text === 'fetch' && ts.isIdentifier(e.expression.expression) && queries.has(e.expression.expression.text)
+  const isHandle = e => { e = peel(e); return isQueryCall(e) || (ts.isIdentifier(e) && has('handles', e.text)) }
+
+  /** The expression holds a whole server object or array, or a derived copy of one. A picked field isn't one. */
+  function serverValue(e) {
+    e = peel(e)
+    if (ts.isIdentifier(e)) return has('values', e.text)
+    if (ts.isAwaitExpression(e)) return isFetch(peel(e.expression)) || isQueryCall(peel(e.expression))
+    if (ts.isPropertyAccessExpression(e)) return e.name.text === 'value' && isHandle(e.expression)
+    if (ts.isElementAccessExpression(e)) return serverValue(e.expression)
+    if (ts.isBinaryExpression(e) && [ts.SyntaxKind.QuestionQuestionToken, ts.SyntaxKind.BarBarToken].includes(e.operatorToken.kind)) return serverValue(e.left) || serverValue(e.right)
+    if (ts.isConditionalExpression(e)) return serverValue(e.whenTrue) || serverValue(e.whenFalse)
+    if (ts.isCallExpression(e)) {
+      const c = e.expression
+      return ts.isPropertyAccessExpression(c) && KEEPS_OBJECTS.has(c.name.text) && serverValue(c.expression)
+    }
+    if (ts.isArrayLiteralExpression(e)) return e.elements.some(x => ts.isSpreadElement(x) && serverValue(x.expression))
+    if (ts.isObjectLiteralExpression(e)) return e.properties.some(p => ts.isSpreadAssignment(p) && serverValue(p.expression))
+    return false
+  }
+
+  const returned = fn => {
+    if (!ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn)) return undefined
+    if (!ts.isBlock(fn.body)) return fn.body
+    const r = fn.body.statements.find(ts.isReturnStatement)
+    return r?.expression
+  }
+  /** The first handle a function's body reads: the source `state.linked` follows. */
+  function handleIn(node) {
+    /** @type {string | undefined} */
+    let found
+    const walk = n => {
+      if (found) return
+      if (ts.isPropertyAccessExpression(n) && n.name.text === 'value' && isHandle(n.expression)) found = n.expression.getText(sf)
+      else ts.forEachChild(n, walk)
+    }
+    walk(node)
+    return found
+  }
+  const flag = (node, why) => report('S001', node.getStart(sf), node.end, why)
+
+  function visit(node) {
+    if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && ESCAPES.has(node.name.text)) return
+    if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name) && ESCAPES.has(node.name.text)) return
+    const fn = ts.isFunctionLike(node)
+    if (fn) frames.push({ handles: new Set(), values: new Set() })
+    try {
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+        const init = peel(node.initializer)
+        if (isQueryCall(init)) frames.at(-1).handles.add(node.name.text)
+        else if (serverValue(init)) frames.at(-1).values.add(node.name.text)
+      }
+      if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isPropertyAccessExpression(node.left) && node.left.name.text === 'value' && serverValue(node.right))
+        flag(node, `A server value is copied into \`${node.left.expression.getText(sf)}\`: the copy goes stale, and its rows lose their identity.`)
+      if (ts.isCallExpression(node)) {
+        const c = node.expression
+        if (ts.isIdentifier(c) && ESCAPES.has(c.text)) return
+        if (ts.isPropertyAccessExpression(c) && ts.isIdentifier(c.expression) && c.expression.text === 'state' && c.name.text === 'linked') {
+          const source = handleIn(node.arguments[0] ?? node)
+          if (source && node.arguments.length < 2) {
+            const at = node.arguments[0].end
+            report('S012', node.getStart(sf), node.end, `\`state.linked\` over \`${source}\` has no \`key\`: a refetch resets what someone is typing.`,
+              { description: `Key it by the row: \`{ key: () => ${source}.value?.id }\``, safe: false, edits: [[at, at, `, { key: () => ${source}.value?.id }`]] })
+          }
+          return // the declared editing path: not S001
+        }
+        if (ts.isIdentifier(c) && c.text === 'state' && node.arguments[0] && serverValue(node.arguments[0]))
+          flag(node, 'A server value is copied into `state`: the copy goes stale, and its rows lose their identity.')
+        if (ts.isPropertyAccessExpression(c) && c.name.text === 'set' && node.arguments.length === 1) {
+          const r = returned(node.arguments[0])
+          if (r && serverValue(r)) flag(node, `A server value is copied into \`${c.expression.getText(sf)}\`: the copy goes stale, and its rows lose their identity.`)
+        }
+        // The value a callback gets from a query: `watch(() => q.value, v => …)`, `q.fetch().then(v => …)`.
+        const fed = ts.isIdentifier(c) && c.text === 'watch' && returned(node.arguments[0]) && serverValue(returned(node.arguments[0])) ? node.arguments[1]
+          : ts.isPropertyAccessExpression(c) && c.name.text === 'then' && isFetch(peel(c.expression)) ? node.arguments[0] : undefined
+        if (fed && (ts.isArrowFunction(fed) || ts.isFunctionExpression(fed)) && ts.isIdentifier(fed.parameters[0]?.name)) {
+          frames.push({ handles: new Set(), values: new Set([fed.parameters[0].name.text]) })
+          ts.forEachChild(node, visit)
+          frames.pop()
+          return
+        }
+      }
+      ts.forEachChild(node, visit)
+    } finally {
+      if (fn) frames.pop()
+    }
+  }
+  visit(sf)
+}
+
+/** The local names `resource` is imported as from @weft-js/core. */
+const resourceNames = sf => new Set(sf.statements.flatMap(n => ts.isImportDeclaration(n) && n.moduleSpecifier.text === '@weft-js/core' && n.importClause?.namedBindings && ts.isNamedImports(n.importClause.namedBindings)
+  ? n.importClause.namedBindings.elements.filter(s => (s.propertyName ?? s.name).text === 'resource').map(s => s.name.text) : []))
+
+/**
+ * X037: a `resource` or query made in a component's own body and read inside a `<Boundary>` that component renders. A
+ * Boundary waits for what is made while its children are built, so it never sees this one: no fallback shows, and the
+ * content renders with nothing in it. Only a read inside the Boundary's children counts: reading it elsewhere is fine.
+ * @param {ts.SourceFile} sf @param {Set<string>} makers names whose call makes one (`resource` and the queries)
+ */
+function madeBesideBoundary(sf, makers, report) {
+  const peel = e => { while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isNonNullExpression(e) || ts.isSatisfiesExpression(e)) e = e.expression; return e }
+  const maker = e => {
+    e = peel(e)
+    if (!ts.isCallExpression(e)) return undefined
+    const c = e.expression
+    const name = ts.isIdentifier(c) ? c.text : ts.isPropertyAccessExpression(c) && c.name.text === 'live' && ts.isIdentifier(c.expression) ? c.expression.text : undefined
+    return name !== undefined && makers.has(name) ? e : undefined
+  }
+  const nested = n => ts.isFunctionDeclaration(n) || (ts.isVariableDeclaration(n) && !!n.initializer && (ts.isArrowFunction(n.initializer) || ts.isFunctionExpression(n.initializer)))
+  function component(fn) {
+    /** @type {Map<string, ts.CallExpression>} */
+    const made = new Map()
+    for (const st of fn.body.statements) {
+      if (!ts.isVariableStatement(st)) continue
+      for (const d of st.declarationList.declarations) {
+        const call = ts.isIdentifier(d.name) && d.initializer ? maker(d.initializer) : undefined
+        if (call) made.set(d.name.text, call)
+      }
+    }
+    if (!made.size) return
+    const done = new Set()
+    const read = n => {
+      if (ts.isIdentifier(n) && made.has(n.text) && !done.has(n.text) && !(ts.isPropertyAccessExpression(n.parent) && n.parent.name === n)) {
+        done.add(n.text)
+        const call = made.get(n.text)
+        report('X037', call.getStart(sf), call.end, `\`${n.text}\` is made here, beside the <Boundary> that shows it, so that Boundary never waits for it: no fallback shows, and the content renders before the data. Make it in a component rendered inside the Boundary.`)
+      }
+      ts.forEachChild(n, read)
+    }
+    const find = n => {
+      if (nested(n)) return // another component, with its own body
+      if (ts.isJsxElement(n) && n.openingElement.tagName.getText(sf) === 'Boundary') n.children.forEach(read)
+      else ts.forEachChild(n, find)
+    }
+    fn.body.statements.forEach(find)
+  }
+  const visit = n => {
+    if ((ts.isFunctionDeclaration(n) || ts.isArrowFunction(n) || ts.isFunctionExpression(n)) && n.body && ts.isBlock(n.body)) component(n)
+    ts.forEachChild(n, visit)
+  }
+  visit(sf)
+}
+
+/** @param {string} root @param {{ files: { rel: string, text: string }[], exclude?: string[] }} options */
+export function stateChecks(root, { files, exclude = [] }) {
+  const out = []
+  const cache = new Map()
+  const checked = new Set(files.map(f => f.rel))
+  // Scopes usually live in plain .ts files, which the compiler pass doesn't read.
+  const extra = discover(root, { include: ['src/**/*.ts'], exclude }).filter(f => !checked.has(f) && !isServerModule(f) && !/\.(d|test|spec)\.ts$/.test(f))
+  const all = [...files.map(f => [f.rel, f.text]), ...extra.map(f => [f, readFileSync(join(root, f), 'utf8')])]
+  for (const [rel, text] of all) {
+    const copies = /\b(state|watch|set)\b/.test(text), boundary = /\.[jt]sx$/.test(rel) && text.includes('<Boundary')
+    if (isServerModule(rel) || !(copies || boundary)) continue
+    const sf = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, boundary, /\.[jt]sx$/.test(rel) ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+    const queries = importedQueries(root, rel, sf, cache)
+    const pos = positions(text)
+    const report = (code, start, end, why, fix) => {
+      const offset = [start, end]
+      out.push(diagnostic({ code, file: rel, span: pos.span(start, end), offset, why, fix: fix && { description: fix.description, safe: fix.safe, edits: fix.edits.map(([a, b, t]) => ({ file: rel, span: pos.span(a, b), offset: [a, b], text: t })) } }))
+    }
+    if (copies && queries.size) scan(rel, text, queries, report)
+    if (boundary) madeBesideBoundary(sf, new Set([...queries, ...resourceNames(sf)]), report)
+  }
+  return out
+}