@weft-js/cli 0.0.0-stage → 0.1.1

package/src/project.mjs

@@ -0,0 +1,219 @@
+// Project view for `weft check`: what one file can't see. Today that is cross-file W014.
+//
+// The compiler reports W014 as a warning when `xs.value = xs.value.map(p => ({ ...p, … }))` feeds a box that leaves
+// the file. Here we follow that box through JSX props (`<List items={xs.value} />`), into the component's props,
+// through `derived` and further JSX props, until a JSX `.map` renders it as a keyed list. Found: the warning becomes
+// an error with the list's location in `related`. The parse is syntax only (TypeScript's parser, no type checker).
+
+import { relative } from 'node:path'
+import ts from 'typescript'
+import { local } from './alias.mjs'
+
+const exts = ['', '.tsx', '.ts', '.jsx', '.js', '/index.tsx', '/index.ts', '/index.jsx', '/index.js']
+const isComponentName = name => /^[A-Z]/.test(name)
+
+/** `a.b.c(…).d` → ['a', 'b']: the root identifier and the first member after it. */
+function chainRoot(expr) {
+  let node = expr
+  let member
+  for (;;) {
+    if (ts.isParenthesizedExpression(node) || ts.isNonNullExpression(node) || ts.isAsExpression(node)) node = node.expression
+    else if (ts.isPropertyAccessExpression(node)) {
+      member = node.name.text
+      node = node.expression
+    } else if (ts.isElementAccessExpression(node) || ts.isCallExpression(node)) {
+      member = undefined
+      node = node.expression
+    } else break
+  }
+  return ts.isIdentifier(node) ? [node.text, member] : null
+}
+
+function isInJsx(node, stop) {
+  for (let n = node.parent; n && n !== stop; n = n.parent) if (ts.isJsxExpression(n)) return true
+  return false
+}
+
+/** Identifiers an expression reads (not property names); `props.x` is kept as 'props.x'. */
+function identifiersIn(node) {
+  const names = new Set()
+  const visit = n => {
+    if (ts.isPropertyAccessExpression(n) && ts.isIdentifier(n.expression)) names.add(`${n.expression.text}.${n.name.text}`)
+    if (ts.isIdentifier(n) && !(ts.isPropertyAccessExpression(n.parent) && n.parent.name === n)) names.add(n.text)
+    ts.forEachChild(n, visit)
+  }
+  visit(node)
+  return names
+}
+
+function componentsOf(sf) {
+  const comps = []
+  const add = (name, fn) => {
+    const param = fn.parameters[0]
+    const props = new Map()
+    let propsIdent = null
+    if (param && ts.isObjectBindingPattern(param.name)) {
+      for (const el of param.name.elements) {
+        if (el.dotDotDotToken || !ts.isIdentifier(el.name)) continue
+        const key = el.propertyName && ts.isIdentifier(el.propertyName) ? el.propertyName.text : el.name.text
+        props.set(el.name.text, key)
+      }
+    } else if (param && ts.isIdentifier(param.name)) propsIdent = param.name.text
+    comps.push({ name, fn, props, propsIdent, derives: new Map(), lists: [], edges: [] })
+  }
+  for (const st of sf.statements) {
+    if (ts.isFunctionDeclaration(st) && st.name && isComponentName(st.name.text)) add(st.name.text, st)
+    if (ts.isFunctionDeclaration(st) && !st.name && st.modifiers?.some(m => m.kind === ts.SyntaxKind.DefaultKeyword)) add('default', st)
+    if (ts.isVariableStatement(st)) {
+      for (const d of st.declarationList.declarations) {
+        if (ts.isIdentifier(d.name) && isComponentName(d.name.text) && d.initializer && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))) add(d.name.text, d.initializer)
+      }
+    }
+  }
+  for (const c of comps) {
+    const visit = n => {
+      if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.initializer && ts.isCallExpression(n.initializer)) {
+        const callee = n.initializer.expression.getText()
+        if (callee === 'derived' || callee === 'state.linked') c.derives.set(n.name.text, identifiersIn(n.initializer))
+      }
+      if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === 'map' && isInJsx(n, c.fn)) {
+        const cb = n.arguments[0]
+        const root = chainRoot(n.expression.expression)
+        if (root && cb && (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb))) c.lists.push({ root, at: n.getStart() })
+      }
+      if ((ts.isJsxSelfClosingElement(n) || ts.isJsxOpeningElement(n)) && ts.isIdentifier(n.tagName) && isComponentName(n.tagName.text)) {
+        for (const attr of n.attributes.properties) {
+          if (!ts.isJsxAttribute(attr) || !attr.initializer || !ts.isJsxExpression(attr.initializer) || !attr.initializer.expression) continue
+          const root = chainRoot(attr.initializer.expression)
+          if (root) c.edges.push({ tag: n.tagName.text, prop: attr.name.getText(), root, at: attr.getStart() })
+        }
+      }
+      ts.forEachChild(n, visit)
+    }
+    visit(c.fn.body ?? c.fn)
+  }
+  return comps
+}
+
+/**
+ * @param {Array<{ abs: string, rel: string, text: string, diagnostics: object[] }>} files
+ * @param {(file: string) => { span(start: number, end: number): number[] }} pos
+ */
+export function projectView(files, pos) {
+  // Only a W014 warning needs the project view, so most runs parse nothing here.
+  if (!files.some(f => f.diagnostics.some(d => d.code === 'W014' && d.severity === 'warning'))) return
+  const byAbs = new Map(files.map(f => [f.abs, f]))
+  for (const f of files) {
+    f.sf = ts.createSourceFile(f.abs, f.text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+    f.comps = componentsOf(f.sf)
+    f.imports = new Map()
+    for (const st of f.sf.statements) {
+      if (!ts.isImportDeclaration(st) || !st.importClause || !ts.isStringLiteral(st.moduleSpecifier)) continue
+      const spec = st.moduleSpecifier.text
+      const base = local(f.abs, spec)
+      if (!base) continue
+      const target = exts.map(e => base + e).find(p => byAbs.has(p))
+      if (!target) continue
+      if (st.importClause.name) f.imports.set(st.importClause.name.text, { file: target, name: 'default' })
+      const named = st.importClause.namedBindings
+      if (named && ts.isNamedImports(named)) for (const el of named.elements) f.imports.set(el.name.text, { file: target, name: (el.propertyName ?? el.name).text })
+    }
+  }
+
+  const lookup = (file, tag) => {
+    const own = file.comps.find(c => c.name === tag)
+    if (own) return { file, comp: own }
+    const imp = file.imports.get(tag)
+    const target = imp && byAbs.get(imp.file)
+    const comp = target?.comps.find(c => c.name === imp.name)
+    return comp ? { file: target, comp } : null
+  }
+
+  /** Prop names (of `comp`) that an expression rooted at `root` reads, following `derived` locals. */
+  const propsRead = (comp, [name, member], seen = new Set()) => {
+    if (seen.has(name)) return new Set()
+    seen.add(name)
+    if (comp.props.has(name)) return new Set([comp.props.get(name)])
+    if (name === comp.propsIdent && member) return new Set([member])
+    const out = new Set()
+    for (const dep of comp.derives.get(name) ?? []) for (const p of propsRead(comp, dep.split('.'), seen)) out.add(p)
+    return out
+  }
+
+  /** Where `comp` (transitively) renders prop `prop` as a JSX `.map`, with the JSX path that gets there. */
+  const reachesList = (file, comp, prop, seen = new Set()) => {
+    const id = `${file.abs}#${comp.name}#${prop}`
+    if (seen.has(id)) return null
+    seen.add(id)
+    for (const list of comp.lists) if (propsRead(comp, list.root).has(prop)) return { file, at: list.at, via: [] }
+    for (const edge of comp.edges) {
+      if (!propsRead(comp, edge.root).has(prop)) continue
+      const next = lookup(file, edge.tag)
+      const hit = next && reachesList(next.file, next.comp, edge.prop, seen)
+      if (hit) return { ...hit, via: [{ file, at: edge.at, tag: edge.tag, prop: edge.prop }, ...hit.via] }
+    }
+    return null
+  }
+
+  /** Locals of `comp` that read `box`, following `derived`. */
+  const readsBox = (comp, [name], box, seen = new Set()) => {
+    if (name === box) return true
+    if (seen.has(name)) return false
+    seen.add(name)
+    return [...(comp?.derives.get(name) ?? [])].some(dep => readsBox(comp, dep.split('.'), box, seen))
+  }
+
+  for (const f of files) {
+    for (const d of f.diagnostics) {
+      if (d.code !== 'W014' || d.severity !== 'warning' || !d.offset) continue
+      const box = boxOf(f.sf, d.offset[0])
+      if (!box) continue
+      const owners = f.comps.filter(c => c.fn.pos <= d.offset[0] && d.offset[0] < c.fn.end)
+      for (const comp of owners.length ? owners : f.comps) {
+        let hit = null
+        let edge
+        for (edge of comp.edges) {
+          if (!readsBox(comp, edge.root, box)) continue
+          const next = lookup(f, edge.tag)
+          hit = next && reachesList(next.file, next.comp, edge.prop)
+          if (hit) break
+        }
+        if (!hit) continue
+        const listPos = pos(hit.file).span(hit.at, hit.at)
+        const path = [{ file: f, at: edge.at, tag: edge.tag, prop: edge.prop }, ...hit.via]
+        d.severity = 'error'
+        d.project = true
+        d.why =
+          `\`.map(p => ({ ...p, … }))\` gives every item a new identity on each update, and \`${box}\` reaches a keyed list in ` +
+          `${hit.file.rel}:${listPos[0]} through ${path.map(p => `<${p.tag} ${p.prop}>`).join(' → ')}: every row re-runs on every change.`
+        d.related = [
+          ...path.map(p => ({ file: p.file.rel, span: pos(p.file).span(p.at, p.at), why: `passed as \`<${p.tag} ${p.prop}>\`` })),
+          { file: hit.file.rel, span: listPos, why: 'rendered here as a keyed list' },
+        ]
+        break
+      }
+    }
+  }
+}
+
+/** The box a flagged `.map` call writes: `box.value = …map(…)` or `const box = …map(…)`. */
+function boxOf(sf, offset) {
+  let found
+  const visit = n => {
+    if (found) return
+    if (ts.isCallExpression(n) && n.getStart() === offset) found = n
+    else if (n.pos <= offset && offset < n.end) ts.forEachChild(n, visit)
+  }
+  visit(sf)
+  for (let n = found; n; n = n.parent) {
+    if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+      const left = n.left
+      if (ts.isPropertyAccessExpression(left) && left.name.text === 'value' && ts.isIdentifier(left.expression)) return left.expression.text
+      return null
+    }
+    if (ts.isVariableDeclaration(n)) return ts.isIdentifier(n.name) ? n.name.text : null
+  }
+  return null
+}
+
+export const relPath = (root, abs) => relative(root, abs).split('\\').join('/')

package/src/props-checks.mjs

@@ -0,0 +1,46 @@
+// Prop inference in `weft check` and `weft tsc` (research 44). `W080`–`W085` come from the engine; a `TS` code is the
+// compiler's own error, reported at the source position with the inferred types applied.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, relative } from 'node:path'
+import ts from 'typescript'
+import { diagnostic, positions } from './diag.mjs'
+
+const require = createRequire(import.meta.url)
+const { Session } = require('./infer/session.cjs')
+
+const posix = p => p.split('\\').join('/')
+
+export function toDiagnostics(root, list, file) {
+  const rel = posix(relative(root, file))
+  const text = readFileSync(file, 'utf8')
+  const pos = positions(text)
+  return list.map(f => diagnostic({
+    code: f.code, severity: f.severity, file: rel, span: pos.span(f.start, f.end), offset: [f.start, f.end], why: f.why, help: f.help,
+    fix: f.edits && { description: f.help, safe: f.safe, edits: f.edits.map(e => ({ file: rel, span: pos.span(e.start, e.end), offset: [e.start, e.end], text: e.text })) },
+  }))
+}
+
+/** The checks `weft check` adds. A project with nothing to infer parses its `.tsx` files once and starts nothing. */
+export async function propChecks(root, config) {
+  if (config.check?.props === false || !existsSync(join(root, 'tsconfig.json'))) return []
+  const session = new Session(ts, root)
+  try {
+    const { findings, errors } = await session.analyze()
+    return [...findings, ...errors].flatMap(([file, list]) => toDiagnostics(root, list, file))
+  } finally {
+    session.close()
+  }
+}
+
+/** `weft tsc`: the whole project, as `tsc --noEmit` sees it with inference applied. */
+export async function propTsc(root) {
+  const session = new Session(ts, root)
+  try {
+    const { findings, errors } = await session.all()
+    return [...findings, ...errors].flatMap(([file, list]) => toDiagnostics(root, list, file))
+  } finally {
+    session.close()
+  }
+}

package/src/props-listener.mjs

@@ -0,0 +1,38 @@
+// Prop inference while `weft dev` runs. A listener of its own, hooked at file-change: it posts the changed name to a
+// worker and goes back to serving, so nothing here is on the HMR or request path (research 44 §7).
+
+import { Worker } from 'node:worker_threads'
+
+const SOURCE = /\.tsx?$/
+const SKIP = /[\\/](node_modules|\.weft|\.output|dist)[\\/]/
+
+/** @param {{ watcher: any, ws: any, config: any, close: () => Promise<void> }} server */
+export function attachProps(server, root, config) {
+  const setting = config?.check?.props
+  if (setting === false || process.env.WEFT_PROPS === 'off') return null
+  const worker = new Worker(new URL('./infer/worker.cjs', import.meta.url), { workerData: { root, write: setting !== 'manual' }, stdout: false })
+  worker.unref()
+  const stats = { saves: 0, ms: [] }
+  const post = file => { if (SOURCE.test(file) && !SKIP.test(file)) worker.postMessage(file) }
+  for (const event of ['change', 'add', 'unlink']) server.watcher.on(event, post)
+
+  const logger = server.config?.logger ?? console
+  worker.on('message', msg => {
+    if (msg.type === 'failed') return logger.warn?.(`weft props: ${msg.message}`)
+    if (msg.type === 'wrote') return logger.info?.(`weft props: wrote the inferred type in ${msg.file}`)
+    if (msg.type !== 'done') return
+    stats.saves++
+    stats.ms.push(msg.ms)
+    if (!msg.changed) return
+    const errors = msg.diagnostics.filter(d => d.severity === 'error')
+    for (const d of msg.diagnostics) logger.warn?.(`${d.file}:${d.line}  ${d.code} ${d.severity}  ${d.why}\n    fix: ${d.help}`)
+    server.ws.send({ type: 'custom', event: 'weft:props', data: msg.diagnostics })
+    // A save's HMR update has cleared any earlier overlay already, so this only ever shows the current errors.
+    if (errors.length) server.ws.send({ type: 'error', err: { message: errors.map(d => `${d.file}:${d.line} ${d.code}: ${d.why}`).join('\n'), stack: '', plugin: 'weft:props' } })
+  })
+  worker.on('error', e => logger.warn?.(`weft props stopped: ${e.message}`))
+
+  const close = server.close.bind(server)
+  server.close = async () => { worker.postMessage('close'); return close() }
+  return { worker, stats }
+}

package/src/react-checks.mjs

@@ -0,0 +1,36 @@
+// W043 and W044 in `weft check`. W043: a React habit that compiles and renders something else. `data-x={true}` is a literal, so it can
+// be told from weft's own `data-open={open}`, whose presence form `[data-open]` selectors depend on (docs/react-props.md).
+
+import { diagnostic, positions } from './diag.mjs'
+import { scanJsx } from './jsx-scan.mjs'
+
+const NATIVE = /^[a-z][\w-]*$/
+const LITERAL = /\bdata-[\w-]+\s*=\s*\{\s*(?:true|false)\s*\}/
+const RANDOM = /\b(?:crypto\.randomUUID|Date\.now|Math\.random|performance\.now)\s*\(/
+
+/** @param {{ files: { rel: string, text: string }[] }} options the checked .tsx/.jsx files */
+export function reactChecks({ files }) {
+  const out = []
+  for (const { rel, text } of files) {
+    if (!LITERAL.test(text) && !RANDOM.test(text)) continue
+    const pos = positions(text)
+    for (const el of scanJsx(text, rel).elements) {
+      for (const a of el.attrs) {
+        if (a.name === 'key' && a.kind === 'expr' && RANDOM.test(a.expr)) out.push(diagnostic({ code: 'W044', file: rel, span: pos.span(a.start, a.end), offset: [a.start, a.end], why: `\`key={${a.expr}}\` differs between the server and the client, so this row can't hydrate and is built again, and it differs on every render.` }))
+      }
+      if (!NATIVE.test(el.name)) continue
+      for (const a of el.attrs) {
+        if (!a.name.startsWith('data-') || a.kind !== 'expr' || (a.expr !== 'true' && a.expr !== 'false')) continue
+        const on = a.expr === 'true'
+        // Removing the attribute takes the space before it too.
+        const [from, to] = on ? [a.start, a.end] : [text.slice(0, a.start).trimEnd().length, a.end]
+        const why = on
+          ? `\`${a.name}={true}\` writes \`${a.name}=""\`, not React's \`"true"\`, so \`[${a.name}="true"]\` won't match. Write \`${a.name}\` for a presence flag, or \`${a.name}="true"\` for the word.`
+          : `\`${a.name}={false}\` writes no attribute, not React's \`"false"\`. Drop it, or write \`${a.name}="false"\` for the word.`
+        const fix = { description: on ? `Write \`${a.name}\`, which renders the same` : `Remove \`${a.name}\`, which renders the same`, safe: true, edits: [{ file: rel, span: pos.span(from, to), offset: [from, to], text: on ? a.name : '' }] }
+        out.push(diagnostic({ code: 'W043', file: rel, span: pos.span(a.start, a.end), offset: [a.start, a.end], why, fix }))
+      }
+    }
+  }
+  return out
+}

package/src/share-checks.mjs

@@ -0,0 +1,74 @@
+// U001–U005 in `weft check` (research 45 §10): `interaction({ share })` and `ui`. TypeScript's parser only, no type
+// checking: what's read is the call's own text, and a name counts as an interaction row only if this file made it.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import ts from 'typescript'
+import { diagnostic, positions } from './diag.mjs'
+
+const UNSTABLE = /\b(?:Math\.random|Date\.now|crypto\.randomUUID|performance\.now)\b/
+const USER_TYPED = /\b(?:location\.|URLSearchParams|useSearchParams|searchParams|params\.get)\b/
+/** warp components that take `ui`. Anything else would write `ui="[object Object]"` on its element. */
+const TAKES_UI = new Set(['Button', 'Checkbox', 'Switch', 'Radio', 'Toggle', 'Chip', 'Card'])
+
+const rowsOf = sf => {
+  const rows = new Set()
+  const visit = n => {
+    if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.initializer && ts.isCallExpression(n.initializer) && n.initializer.expression.getText?.(sf) === 'interaction') rows.add(n.name.text)
+    ts.forEachChild(n, visit)
+  }
+  visit(sf)
+  return rows
+}
+
+const warpNames = sf => {
+  const names = new Map()
+  for (const n of sf.statements) {
+    if (!ts.isImportDeclaration(n) || !n.moduleSpecifier.text.startsWith('@weft-js/warp') || !n.importClause?.namedBindings || !ts.isNamedImports(n.importClause.namedBindings)) continue
+    for (const s of n.importClause.namedBindings.elements) names.set(s.name.text, (s.propertyName ?? s.name).text)
+  }
+  return names
+}
+
+export function shareChecks(root, { files }) {
+  const out = []
+  let sharesIn
+  for (const { rel, text } of files) {
+    const usesRow = text.includes('@weft-js/core/interaction')
+    if (!usesRow && !/\bui=\{/.test(text)) continue
+    const sf = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true, /\.[jt]sx$/.test(rel) ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+    const pos = positions(text)
+    const report = (code, n, why) => out.push(diagnostic({ code, file: rel, span: pos.span(n.getStart(sf), n.end), offset: [n.getStart(sf), n.end], why }))
+    const rows = rowsOf(sf), warp = warpNames(sf)
+    const visit = n => {
+      if (ts.isCallExpression(n) && ts.isIdentifier(n.expression) && n.expression.text === 'interaction' && usesRow) {
+        const share = n.arguments[0] && ts.isObjectLiteralExpression(n.arguments[0]) ? n.arguments[0].properties.find(p => p.name?.getText(sf) === 'share') : undefined
+        if (share) {
+          sharesIn ??= rel
+          const value = share.getText(sf)
+          if (UNSTABLE.test(value)) report('U001', share, 'A `share` key that changes on every load never meets another tab or client.')
+          else if (USER_TYPED.test(value)) report('U002', share, 'This `share` key comes from what the user typed or the URL, so `realtime({ share })` is authorising a string they chose.')
+        }
+      }
+      if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+        const l = n.left
+        const target = ts.isPropertyAccessExpression(l) && l.name.text === 'value' ? l.expression : l
+        if (ts.isPropertyAccessExpression(target) && target.name.text === 'remote' && ts.isIdentifier(target.expression) && rows.has(target.expression.text))
+          report('U004', n, '`remote` is what others are doing: only the network writes it.')
+      }
+      if (ts.isJsxSelfClosingElement(n) || ts.isJsxOpeningElement(n)) {
+        const tag = n.tagName.getText(sf), ui = n.attributes.properties.find(a => ts.isJsxAttribute(a) && a.name.getText(sf) === 'ui')
+        if (ui && warp.has(tag) && !TAKES_UI.has(warp.get(tag))) report('U005', ui, `\`${warp.get(tag)}\` doesn't take \`ui\` yet, so this writes an attribute and draws nothing.`)
+      }
+      ts.forEachChild(n, visit)
+    }
+    visit(sf)
+  }
+  if (sharesIn && existsSync(join(root, 'src/routes'))) {
+    const file = ['src/realtime.server.ts', 'src/realtime.server.js'].map(f => join(root, f)).find(existsSync)
+    if (!file || !/\bshare\s*:/.test(readFileSync(file, 'utf8'))) {
+      out.push(diagnostic({ code: 'U003', file: sharesIn, span: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } }, offset: [0, 0], why: 'This app shares UI state and no `realtime({ share })` says who may: tabs work, and the socket refuses every key.' }))
+    }
+  }
+  return out
+}

package/src/site.mjs

@@ -0,0 +1,19 @@
+// Config-level page-metadata checks (research 20 §6). Without routing they see only `site`: the defaults every page
+// starts from. Route metas (Phase 3) will run the same checks on each route's merged result.
+
+const absolute = /^(https?:)?\/\//
+
+/** @param {import('./config').SiteConfig} site @param {(code: string, why: string, near: string | null) => void} report */
+export function checkSite(site, report) {
+  const image = typeof site.image === 'object' ? site.image.url : site.image
+  if (image && !site.url && !absolute.test(image)) {
+    const what = image === 'auto' ? 'The generated card (`image: \'auto\'`) is served from a relative URL' : `\`site.image\` (\`${image}\`) is relative`
+    report('H001', `${what} and \`site.url\` is not set, so og:image (and canonical, og:url) can't be absolute. Crawlers don't resolve relative URLs.`, 'image')
+  }
+  if (!site.description?.trim()) report('H003', 'Pages have no description: `site.description` is not set and no route overrides it yet.', 'site')
+  // The default page title is `name`; a template's fixed part is in every other title.
+  const fixed = site.title ? site.title.replace('%s', '').length : 0
+  if (site.name && site.name.length > 60) report('H004', `The default title \`${site.name}\` is ${site.name.length} characters (over 60).`, 'name')
+  if (fixed > 40) report('H004', `The title template's fixed part is ${fixed} characters, leaving under 20 of 60 for the page title.`, 'title')
+  if (site.description && site.description.length > 160) report('H004', `\`site.description\` is ${site.description.length} characters (over 160).`, 'description')
+}

package/src/slots.mjs

@@ -0,0 +1,96 @@
+// Slot table (research 13 §2.2) and the binding rules, resolved from config data alone. Phase 1 executes no plugin.
+
+/**
+ * Every slot a plugin can fill: how many providers it takes, where it runs, and what's used when none does.
+ * @type {{ id: string, version: number, cardinality: string, sides: string[], default: string | string[] | null, phase: string }[]}
+ */
+export const slotTable = [
+  { id: 'font.build', version: 1, cardinality: 'one', sides: ['build'], default: null, phase: '2' },
+  { id: 'media.build', version: 1, cardinality: 'one', sides: ['build'], default: null, phase: '2' },
+  { id: 'media.encode', version: 1, cardinality: 'keyed', sides: ['build', 'server'], default: null, phase: '3c' },
+  { id: 'media.server', version: 1, cardinality: 'one', sides: ['server'], default: null, phase: '3' },
+  { id: 'text.measure', version: 1, cardinality: 'one', sides: ['client', 'worker'], default: null, phase: '2 (Surfaces)' },
+  { id: 'surface.renderer', version: 1, cardinality: 'keyed', sides: ['client'], default: ['canvas2d', 'webgl2'], phase: '2 (Surfaces)' },
+  { id: 'realtime.bus', version: 1, cardinality: 'one', sides: ['server'], default: 'memory', phase: '3' },
+  { id: 'db.adapter', version: 1, cardinality: 'keyed', sides: ['server'], default: ['drizzle'], phase: '3c' },
+  { id: 'server.extension', version: 1, cardinality: 'keyed', sides: ['server'], default: null, phase: '6c' },
+  { id: 'pay.rail', version: 1, cardinality: 'keyed', sides: ['server', 'client', 'native'], default: null, phase: '6c' },
+]
+
+export function slotDef(id) {
+  const def = slotTable.find(s => s.id === id)
+  if (def) return def
+  if (/^device\.[a-z][\w-]*$/.test(id)) return { id, version: 1, cardinality: 'keyed', sides: ['native', 'client'], default: null, phase: '6b' }
+  return undefined
+}
+
+/**
+ * @param {{ plugins?: Array<{ name: string, provides?: Array<string | { slot: string, key: string }> }>, slots?: Record<string, unknown> }} config
+ * @param {(code: string, why: string, near: string) => void} report
+ * @returns {Record<string, unknown>} the `slots` block of `weft check --json`
+ */
+export function bindSlots(config, report) {
+  const plugins = config.plugins ?? []
+  const chosen = config.slots ?? {}
+  const names = new Set(plugins.map(p => p.name))
+
+  /** slot id → key ('' for `one`) → provider names */
+  const offers = new Map()
+  for (const p of [...plugins].sort((a, b) => a.name.localeCompare(b.name))) {
+    for (const item of p.provides ?? []) {
+      const { slot, key = '' } = typeof item === 'string' ? { slot: item } : item
+      if (!slotDef(slot) && !slot.startsWith(`${p.name}.`)) {
+        report('P008', `\`${p.name}\` provides \`${slot}\`, which is not a slot weft defines.`, p.name)
+        continue
+      }
+      const byKey = offers.get(slot) ?? new Map()
+      byKey.set(key, [...(byKey.get(key) ?? []), p.name])
+      offers.set(slot, byKey)
+    }
+  }
+
+  for (const [id, pick] of Object.entries(chosen)) {
+    if (!slotDef(id) && !offers.has(id)) {
+      report('P008', `\`slots\` names \`${id}\`, which is not a slot weft defines.`, id)
+      continue
+    }
+    const picks = typeof pick === 'string' ? { '': pick } : pick
+    for (const [key, name] of Object.entries(picks)) {
+      if (name.startsWith('weft:default')) continue
+      if (!names.has(name)) report('P009', `\`slots['${id}']\` picks \`${name}\`, which is not in \`plugins\`.`, id)
+      else if (!(offers.get(id)?.get(key) ?? []).includes(name)) report('P009', `\`slots['${id}']\` picks \`${name}\`, which does not provide it.`, id)
+    }
+  }
+
+  /** @type {Set<string>} */
+  const known = new Set([...slotTable.map(s => s.id), ...offers.keys()])
+  const ids = [...known].sort()
+  const out = {}
+  for (const id of ids) {
+    const def = slotDef(id) ?? { cardinality: 'one', default: null }
+    const byKey = offers.get(id) ?? new Map()
+    const pick = chosen[id]
+    const resolve = (key, fallback) => {
+      const providers = byKey.get(key) ?? []
+      const named = typeof pick === 'string' ? (key === '' ? pick : undefined) : pick?.[key]
+      if (named && (named.startsWith('weft:default') || providers.includes(named))) return named
+      if (providers.length === 1) return providers[0]
+      if (providers.length > 1) {
+        const where = key ? `\`${id}\` key \`${key}\`` : `\`${id}\``
+        report('P100', `${where} has ${providers.length} providers: ${providers.join(', ')}. Array order never decides.`, providers[0])
+        return null
+      }
+      return fallback
+    }
+    if (def.cardinality === 'one') {
+      out[id] = resolve('', typeof def.default === 'string' ? `weft:default:${def.default}` : null)
+    } else {
+      /** @type {Set<string>} */
+      const keys = new Set([...(Array.isArray(def.default) ? def.default : []), ...[...byKey.keys()].filter(Boolean)])
+      const block = {}
+      for (const key of [...keys].sort()) block[key] = resolve(key, def.default?.includes(key) ? 'weft:default' : null)
+      out[id] = block
+    }
+  }
+  return out
+}