@weft-js/cli 0.1.1 → 0.1.3

package/src/state-checks/core-state.mjs

@@ -0,0 +1,223 @@
+// Bind identities without loading dependencies or checking project types. Only explicit core
+// value imports and stable const aliases establish state provenance; spelling alone does not.
+import ts from 'typescript'
+
+function peel(expression) {
+  while (
+    ts.isParenthesizedExpression(expression) ||
+    ts.isAsExpression(expression) ||
+    ts.isNonNullExpression(expression) ||
+    ts.isSatisfiesExpression(expression)
+  )
+    expression = expression.expression
+  return expression
+}
+
+const member = (base, name) =>
+  base === 'namespace' && name === 'state'
+    ? 'state'
+    : base === 'state' && ['linked', 'global'].includes(name)
+      ? name
+      : undefined
+
+function binder(root, graph) {
+  const files = new Map([...graph.values()].map(({ sf }) => [sf.fileName, sf]))
+  const options = {
+    noLib: true,
+    noResolve: true,
+    types: [],
+    allowJs: true,
+    jsx: ts.JsxEmit.Preserve,
+  }
+  const host = ts.createCompilerHost(options)
+  host.getSourceFile = (file) => files.get(file)
+  host.fileExists = (file) => files.has(file)
+  host.readFile = (file) => files.get(file)?.text
+  host.getCurrentDirectory = () => root
+  return ts.createProgram([...files.keys()], options, host).getTypeChecker()
+}
+
+function written(node, symbol, out) {
+  node = peel(node)
+  if (ts.isIdentifier(node)) {
+    const sym = symbol(node)
+    if (sym) out.add(sym)
+  } else if (ts.isArrayLiteralExpression(node))
+    for (const element of node.elements)
+      written(ts.isSpreadElement(element) ? element.expression : element, symbol, out)
+  else if (ts.isObjectLiteralExpression(node)) {
+    for (const property of node.properties) {
+      if (ts.isShorthandPropertyAssignment(property)) written(property.name, symbol, out)
+      if (ts.isPropertyAssignment(property)) written(property.initializer, symbol, out)
+      if (ts.isSpreadAssignment(property)) written(property.expression, symbol, out)
+    }
+  } else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken)
+    written(node.left, symbol, out)
+}
+
+function scanWrites(sf, symbol, writes, aliases) {
+  const scan = (node) => {
+    if (ts.isBinaryExpression(node)) {
+      const operator = node.operatorToken.kind
+      if (
+        operator === ts.SyntaxKind.EqualsToken ||
+        (operator >= ts.SyntaxKind.FirstCompoundAssignment &&
+          operator <= ts.SyntaxKind.LastCompoundAssignment)
+      )
+        written(node.left, symbol, writes)
+    }
+    if (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) {
+      if ([ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator))
+        written(node.operand, symbol, writes)
+    }
+    if (
+      ts.isVariableDeclaration(node) &&
+      node.initializer &&
+      node.parent.flags & ts.NodeFlags.Const
+    )
+      aliases.push(node)
+    ts.forEachChild(node, scan)
+  }
+  scan(sf)
+}
+
+/** Resolve state, linked and explicit global calls through local binding identities. */
+export function coreState(root, graph) {
+  const checker = binder(root, graph)
+  const symbol = (node) => {
+    const parent = node.parent
+    return parent && ts.isShorthandPropertyAssignment(parent) && parent.name === node
+      ? checker.getShorthandAssignmentValueSymbol(parent)
+      : checker.getSymbolAtLocation(node)
+  }
+  const values = new Map(),
+    writes = new Set(),
+    aliases = []
+  const remember = (node, tag) => {
+    const sym = symbol(node)
+    if (sym && tag && !writes.has(sym)) values.set(sym, tag)
+  }
+  for (const { sf } of graph.values()) {
+    scanWrites(sf, symbol, writes, aliases)
+    for (const node of sf.statements) {
+      if (
+        !ts.isImportDeclaration(node) ||
+        node.moduleSpecifier.text !== '@weft-js/core' ||
+        !node.importClause ||
+        node.importClause.isTypeOnly
+      )
+        continue
+      const named = node.importClause.namedBindings
+      if (named && ts.isNamespaceImport(named)) remember(named.name, 'namespace')
+      if (named && ts.isNamedImports(named))
+        for (const spec of named.elements)
+          if (!spec.isTypeOnly && (spec.propertyName ?? spec.name).text === 'state')
+            remember(spec.name, 'state')
+    }
+  }
+  for (const sym of writes) values.delete(sym)
+  const resolve = (expression) => {
+    expression = peel(expression)
+    if (ts.isIdentifier(expression)) return values.get(symbol(expression))
+    if (ts.isPropertyAccessExpression(expression))
+      return member(resolve(expression.expression), expression.name.text)
+    if (
+      ts.isElementAccessExpression(expression) &&
+      expression.argumentExpression &&
+      ts.isStringLiteralLike(expression.argumentExpression)
+    )
+      return member(resolve(expression.expression), expression.argumentExpression.text)
+    return undefined
+  }
+  for (let round = 0; round <= aliases.length; round++) {
+    const before = values.size
+    for (const alias of aliases) {
+      const base = resolve(alias.initializer)
+      if (!base) continue
+      if (ts.isIdentifier(alias.name) && !writes.has(symbol(alias.name))) remember(alias.name, base)
+      if (ts.isObjectBindingPattern(alias.name))
+        for (const element of alias.name.elements) {
+          if (
+            !ts.isIdentifier(element.name) ||
+            element.initializer ||
+            element.dotDotDotToken ||
+            writes.has(symbol(element.name))
+          )
+            continue
+          const name = element.propertyName ?? element.name
+          if (!ts.isIdentifier(name) && !ts.isStringLiteralLike(name)) continue
+          const tag = member(base, name.text)
+          remember(element.name, tag)
+        }
+    }
+    if (values.size === before) break
+  }
+  return (expression) => resolve(expression)
+}
+
+// This syntax cannot produce undefined on normal completion. Identifiers, member reads,
+// calls and compound expressions remain unknown; type assertions add no runtime evidence.
+function nonUndefined(expression) {
+  expression = peel(expression)
+  return [
+    ts.SyntaxKind.NumericLiteral,
+    ts.SyntaxKind.BigIntLiteral,
+    ts.SyntaxKind.StringLiteral,
+    ts.SyntaxKind.NoSubstitutionTemplateLiteral,
+    ts.SyntaxKind.RegularExpressionLiteral,
+    ts.SyntaxKind.TrueKeyword,
+    ts.SyntaxKind.FalseKeyword,
+    ts.SyntaxKind.NullKeyword,
+    ts.SyntaxKind.ObjectLiteralExpression,
+    ts.SyntaxKind.ArrayLiteralExpression,
+    ts.SyntaxKind.FunctionExpression,
+    ts.SyntaxKind.ArrowFunction,
+    ts.SyntaxKind.ClassExpression,
+    ts.SyntaxKind.NewExpression,
+    ts.SyntaxKind.PrefixUnaryExpression,
+    ts.SyntaxKind.PostfixUnaryExpression,
+    ts.SyntaxKind.TypeOfExpression,
+    ts.SyntaxKind.DeleteExpression,
+  ].includes(expression.kind)
+}
+
+function iifeDefaults(call, callee, visit) {
+  const spread = call.arguments.findIndex(ts.isSpreadElement)
+  const fixed = spread < 0 ? call.arguments.length : spread
+  // A TypeScript this parameter consumes no positional argument.
+  const params = callee.parameters.filter(
+    (param) => !ts.isIdentifier(param.name) || param.name.text !== 'this',
+  )
+  for (const [index, param] of params.entries()) {
+    if (param.initializer && (index >= fixed || !nonUndefined(call.arguments[index])))
+      visit(param.initializer)
+  }
+}
+
+/** Walk module evaluation, not deferred factories or instance-field initializers. */
+export function moduleCalls(sf, report) {
+  const visit = (node) => {
+    if (ts.isCallExpression(node)) {
+      report(node)
+      const callee = peel(node.expression)
+      if (ts.isFunctionExpression(callee) || ts.isArrowFunction(callee)) {
+        iifeDefaults(node, callee, visit)
+        // Generator calls create iterators; their bodies wait for iteration.
+        if (!ts.isFunctionExpression(callee) || !callee.asteriskToken) visit(callee.body)
+      }
+    }
+    if (ts.isFunctionLike(node)) {
+      if (node.name && ts.isComputedPropertyName(node.name)) visit(node.name.expression)
+      return
+    }
+    if (
+      ts.isPropertyDeclaration(node) &&
+      !node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword)
+    ) {
+      if (ts.isComputedPropertyName(node.name)) visit(node.name.expression)
+      return
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+}

package/src/state-checks/modules.mjs

@@ -0,0 +1,17 @@
+// Shared server-module conventions and local resolution for project state checks.
+import { existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { local } from '../alias.mjs'
+
+/** Whether a file uses the server module convention. */
+export const isServerModule = (rel) =>
+  rel.startsWith('src/server/') || /\.server\.[cm]?[jt]sx?$/.test(rel)
+/** Resolve a local project module with the existing state-check extensions. */
+export 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)))
+}

package/src/state-checks/scan.mjs

@@ -0,0 +1,232 @@
+import ts from 'typescript'
+
+const KEEPS_OBJECTS = new Set([
+  'map',
+  'filter',
+  'flatMap',
+  'slice',
+  'sort',
+  'toSorted',
+  'reverse',
+  'concat',
+  'find',
+  'at',
+  'structuredClone',
+])
+const ESCAPES = new Set(['untrack', 'optimistic'])
+
+export 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 { peel, isQueryCall, isFetch, isHandle, serverValue } = analysis(queries, frames)
+
+  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)
+
+  const context = {
+    sf,
+    frames,
+    report,
+    peel,
+    isQueryCall,
+    isFetch,
+    serverValue,
+    returned,
+    handleIn,
+    flag,
+  }
+  const visit = makeVisitor(context)
+  visit(sf)
+}
+
+function analysis(queries, frames) {
+  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
+  }
+
+  return { peel, isQueryCall, isFetch, isHandle, serverValue }
+}
+
+function makeVisitor(context) {
+  const { sf, frames, peel, isQueryCall, serverValue, flag } = context
+  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) && visitCall(node, context, visit)) return
+      ts.forEachChild(node, visit)
+    } finally {
+      if (fn) frames.pop()
+    }
+  }
+  return visit
+}
+
+function visitCall(node, context, visit) {
+  const { sf, frames, report, peel, isFetch, serverValue, returned, handleIn, flag } = context
+  const c = node.expression
+  if (ts.isIdentifier(c) && ESCAPES.has(c.text)) return true
+  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 true // 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 true
+  }
+}

package/src/state-checks/server-graph.mjs

@@ -0,0 +1,65 @@
+// Server entry reachability follows local runtime ESM edges, including reexports.
+// Type-only edges do not evaluate modules. Package/dynamic imports stay outside this graph.
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import ts from 'typescript'
+import { discover } from '../files.mjs'
+import { isServerModule, moduleFile } from './modules.mjs'
+
+const source = /\.[cm]?[jt]sx?$/
+const ignored = /(?:\.d\.[cm]?ts$|\.(?:test|spec)\.[cm]?[jt]sx?$|\/(?:__tests__|test)\/)/
+const entry = (file) =>
+  isServerModule(file) ||
+  /^src\/(?:entry-server|server)\.[cm]?[jt]sx?$/.test(file) ||
+  /^src\/routes\/.*\.[jt]sx$/.test(file)
+
+function runtime(node) {
+  if (ts.isImportDeclaration(node)) {
+    const clause = node.importClause
+    if (!clause) return true
+    if (clause.isTypeOnly) return false
+    const named = clause.namedBindings
+    return (
+      !!clause.name ||
+      !named ||
+      !ts.isNamedImports(named) ||
+      !named.elements.length ||
+      named.elements.some((element) => !element.isTypeOnly)
+    )
+  }
+  if (!ts.isExportDeclaration(node) || node.isTypeOnly) return false
+  const named = node.exportClause
+  return (
+    !named ||
+    !ts.isNamedExports(named) ||
+    !named.elements.length ||
+    named.elements.some((element) => !element.isTypeOnly)
+  )
+}
+
+/** Source snapshots reachable from conventional server modules, entries and SSR route pages. */
+export function serverGraph(root, { files, exclude = [] }) {
+  const texts = new Map(
+    discover(root, {
+      include: ['src/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}', '*.server.{ts,js,mts,mjs,cts,cjs}'],
+      exclude,
+    }).map((file) => [file, readFileSync(join(root, file), 'utf8')]),
+  )
+  for (const file of files) texts.set(file.rel, file.text)
+  for (const file of texts.keys()) if (!source.test(file) || ignored.test(file)) texts.delete(file)
+  const graph = new Map()
+  const visit = (file, from) => {
+    if (graph.has(file) || !texts.has(file)) return
+    const text = texts.get(file)
+    const sf = ts.createSourceFile(join(root, file), text, ts.ScriptTarget.Latest, true)
+    graph.set(file, { sf, entry: from })
+    for (const node of sf.statements) {
+      if (!runtime(node) || !node.moduleSpecifier || !ts.isStringLiteralLike(node.moduleSpecifier))
+        continue
+      const target = moduleFile(root, file, node.moduleSpecifier.text)
+      if (target) visit(target, from)
+    }
+  }
+  for (const file of [...texts.keys()].filter(entry).sort()) visit(file, file)
+  return graph
+}