@barefootjs/jsx 0.19.1 → 0.21.0

package/src/rich-type-evidence.ts

@@ -0,0 +1,159 @@
+/**
+ * Type-evidence resolution for the rich-type method-call refusal (#2273).
+ *
+ * `resolveReceiverType` answers one question: "what TypeScript type, if any,
+ * does this `ParsedExpr` evaluate to?" — using only the structured metadata
+ * already collected at IR-build time (`propsType` / `typeDefinitions`), never
+ * a fresh type-checker pass. It is deliberately conservative: any receiver
+ * shape it doesn't recognize (a call result, computed access, a local not in
+ * `bindings`, …) resolves to `null` ("no evidence"), which the caller must
+ * treat as "don't flag" rather than "flag as unknown". A false negative here
+ * only misses a refusal; a false positive would incorrectly block valid code.
+ */
+
+import type { IRMetadata, PropertyInfo, TypeInfo } from './types.ts'
+import type { ParsedExpr } from './expression-parser.ts'
+
+/**
+ * Built-in JS/TS types whose instance methods have no catalogued lowering
+ * (spec/subset-conformance.md). A prop typed as one of these is opaque past
+ * this point — the adapters have no structural representation for `Date`,
+ * `Map`, etc., only for the primitives/arrays/plain-objects the IR already
+ * lowers. Names only (no generic args) — compare against `baseTypeName`.
+ *
+ * Two shapes deliberately escape this catalogue (conservative misses, not
+ * bugs — a miss only skips a refusal, never misdiagnoses):
+ *   - keyword-typed `bigint` / `symbol` annotations lower to
+ *     `{ kind: 'unknown' }` in `typeNodeToTypeInfo` (only the object-form
+ *     `BigInt` / `Symbol` type references reach `kind: 'interface'` and
+ *     match here);
+ *   - a local alias of a host type (`type Timestamp = Date`) resolves to
+ *     the alias NAME — `derefNamedType` only fills in `properties` from a
+ *     declaration, it never rewrites `raw` to the alias target — so the
+ *     catalogue lookup sees `Timestamp`, not `Date`.
+ */
+export const HOST_RICH_TYPE_NAMES: ReadonlySet<string> = new Set([
+  'Date',
+  'Map',
+  'Set',
+  'WeakMap',
+  'WeakSet',
+  'URL',
+  'URLSearchParams',
+  'RegExp',
+  'Promise',
+  'Error',
+  'Symbol',
+  'BigInt',
+  'Function',
+])
+
+/**
+ * Strip generic type arguments from a `TypeInfo.raw` string (`Map<string,
+ * string>` → `Map`) so a parametrized host type still matches the bare-name
+ * catalogue above. `raw` is source-verbatim (`typeNodeToTypeInfo`), so this
+ * is a plain substring split on the first `<` — not a type-syntax parse.
+ */
+export function baseTypeName(raw: string): string {
+  const idx = raw.indexOf('<')
+  return (idx === -1 ? raw : raw.slice(0, idx)).trim()
+}
+
+type EvidenceMetadata = Pick<IRMetadata, 'propsType' | 'propsObjectName' | 'propsParams' | 'typeDefinitions'>
+
+/**
+ * Collapse a union to its single non-nullish arm (`Date | null` → `Date`),
+ * recursively, so an optional rich-typed prop still carries evidence. A
+ * union with more than one non-nullish arm has no single answer and is left
+ * as-is (its `kind` is `'union'`, which never matches the `'interface'`
+ * check callers gate on).
+ */
+function isNullishArm(t: TypeInfo): boolean {
+  if (t.kind === 'primitive' && (t.primitive === 'null' || t.primitive === 'undefined')) return true
+  // `null` as a type annotation is a `ts.LiteralTypeNode` (not the
+  // `NullKeyword` `typeNodeToTypeInfo`'s primitive switch checks for), so it
+  // falls through to `{ kind: 'unknown', raw: 'null' }` there — a pre-existing
+  // gap in that shared helper, out of scope to fix here. Match on `raw` too
+  // so `Date | null` still strips down to `Date`.
+  return t.kind === 'unknown' && (t.raw === 'null' || t.raw === 'undefined')
+}
+
+export function stripUnion(type: TypeInfo | null): TypeInfo | null {
+  if (!type || type.kind !== 'union' || !type.unionTypes) return type
+  const nonNullish = type.unionTypes.filter((t) => !isNullishArm(t))
+  return nonNullish.length === 1 ? stripUnion(nonNullish[0]) : type
+}
+
+/**
+ * Resolve a named type (`{ kind: 'interface', raw: 'Props' }`) that carries
+ * no inline `properties` to its declaration's field list via
+ * `metadata.typeDefinitions`. A type already carrying properties (an inline
+ * object literal type, or a type resolved from `tsTypeToTypeInfo`) is
+ * returned unchanged — this only fills in the gap left by a *named*
+ * reference, which `typeNodeToTypeInfo` intentionally resolves to
+ * `{ kind: 'interface', raw }` with no member walk of its own.
+ */
+export function derefNamedType(type: TypeInfo, meta: EvidenceMetadata): TypeInfo {
+  if (type.kind !== 'interface') return type
+  if (type.properties && type.properties.length > 0) return type
+  const name = baseTypeName(type.raw)
+  const def = meta.typeDefinitions.find((d) => d.name === name)
+  if (!def?.properties) return type
+  return { ...type, properties: def.properties }
+}
+
+/**
+ * Resolve one property's type off an object-shaped receiver type, deref'ing
+ * a named type first (`Props.createdAt`) and stripping a nullable union off
+ * the result (`Date | null` field). Returns `null` when the receiver has no
+ * evidence, or the property isn't found on it.
+ */
+function lookupProperty(objType: TypeInfo | null, propName: string, meta: EvidenceMetadata): TypeInfo | null {
+  const stripped = stripUnion(objType)
+  if (!stripped) return null
+  const deref = derefNamedType(stripped, meta)
+  const prop = deref.properties?.find((p: PropertyInfo) => p.name === propName)
+  return prop ? stripUnion(prop.type) : null
+}
+
+/**
+ * Resolve the TypeInfo of a receiver expression, using only propsType /
+ * propsParams / typeDefinitions and the caller-supplied local bindings.
+ * `bindings` maps a name to its known type — or explicitly to `null` for a
+ * shadow the caller has proven carries no evidence (e.g. an arrow param, a
+ * loop item whose array type isn't known). A `bindings` hit always wins over
+ * the props fallback, matching JS lexical shadowing.
+ *
+ * Only two `ParsedExpr` shapes carry evidence: a bare identifier and a
+ * non-computed member access. Everything else (calls, computed/index
+ * access, literals, …) resolves to `null` — see the module doc.
+ */
+export function resolveReceiverType(
+  expr: ParsedExpr,
+  meta: EvidenceMetadata,
+  bindings: ReadonlyMap<string, TypeInfo | null>,
+): TypeInfo | null {
+  if (expr.kind === 'identifier') {
+    if (bindings.has(expr.name)) return stripUnion(bindings.get(expr.name) ?? null)
+    if (meta.propsObjectName !== null) {
+      // Object-props mode: props are only reachable through the props object,
+      // so a bare identifier is never a prop — treating every name that
+      // happens to match a propsType field as one would misattribute module
+      // consts / imports that share a field's name.
+      return expr.name === meta.propsObjectName ? stripUnion(meta.propsType) : null
+    }
+    // Destructured mode: only a declared param binding is a prop (membership
+    // via propsParams, which carries LOCAL names — including rename targets).
+    // The TYPE must come from propsType.properties keyed by the SOURCE prop
+    // name: propsParams' own `type` degrades to `unknown` for non-primitive
+    // props (`collectMemberTypes`' primitives-only gate).
+    const param = meta.propsParams.find((p) => p.name === expr.name && !p.isRest)
+    if (!param) return null
+    return lookupProperty(meta.propsType, param.sourceName ?? param.name, meta)
+  }
+  if (expr.kind === 'member' && !expr.computed) {
+    const objType = resolveReceiverType(expr.object, meta, bindings)
+    return lookupProperty(objType, expr.property, meta)
+  }
+  return null
+}

package/src/rich-type-refusal.ts

@@ -0,0 +1,311 @@
+/**
+ * Rich-type method-call refusal (#2273).
+ *
+ * A method call on a prop typed as a built-in "host rich type" (`Date`,
+ * `Map`, …) has no catalogued lowering — no adapter can emit `.toISOString()`
+ * into a template. Left unchecked, such a call transliterates into the
+ * target template's own dot-call syntax and dies at request time (a Go
+ * template `.CreatedAt.ToISOString` panic, a Jinja `AttributeError`, …),
+ * once per adapter, only once someone renders the page. This module makes
+ * that gap loud at compile time instead: `checkRichTypeMethodCalls` walks
+ * every expression position the compiler already treats as template-lowered
+ * and pushes BF021 for any call this build has no evidence a lowering plugin
+ * (or `/* @client *\/`) will handle.
+ *
+ * Deliberately conservative in both directions:
+ *   - `resolveReceiverType` (rich-type-evidence.ts) returns `null` — no
+ *     opinion — for any receiver shape it can't prove a type for, so an
+ *     untyped / generic / call-result receiver is silently allowed through
+ *     rather than misdiagnosed.
+ *   - A `/* @client *\/` node is skipped entirely (its expression already
+ *     opts out of SSR lowering), and a call a registered lowering plugin
+ *     claims (`prepareLoweringMatchers`) is exempt — the seam #2274 and
+ *     later plugins use to catalogue a rich-type API without touching this
+ *     module.
+ */
+
+import type {
+  IRNode,
+  IRMetadata,
+  CompilerError,
+  SourceLocation,
+  TypeInfo,
+  AttrValue,
+  IRTemplatePart,
+} from './types.ts'
+import type { ParsedExpr } from './expression-parser.ts'
+import { parseExpression } from './expression-parser.ts'
+import { prepareLoweringMatchers, type LoweringMatcher } from './lowering-registry.ts'
+import { ErrorCodes } from './errors.ts'
+import { resolveReceiverType, baseTypeName, HOST_RICH_TYPE_NAMES } from './rich-type-evidence.ts'
+
+type Bindings = ReadonlyMap<string, TypeInfo | null>
+const EMPTY_BINDINGS: Bindings = new Map()
+
+/**
+ * Walk `root` looking for a method call on a host rich-typed receiver with
+ * no catalogued lowering, pushing BF021 into `errors` for each one found.
+ * Mirrors `attachParsedExpressions`' tree coverage (jsx-to-ir.ts) so every
+ * position that reaches a template gets checked, but reads `.parsed` rather
+ * than attaching it, and additionally skips anything under `/* @client *\/`.
+ */
+export function checkRichTypeMethodCalls(root: IRNode, metadata: IRMetadata, errors: CompilerError[]): void {
+  // Every evidence chain roots at propsType (bare prop, props.x, loop item of
+  // a prop array) — with no props type there is nothing to prove, so skip the
+  // walk (and the matcher preparation / on-demand template-part parses).
+  if (!metadata.propsType) return
+  const matchers = prepareLoweringMatchers(metadata)
+  const seen = new Set<string>()
+  walkNode(root, metadata, EMPTY_BINDINGS, matchers, errors, seen)
+}
+
+function isLoweringClaimed(matchers: readonly LoweringMatcher[], callee: ParsedExpr, args: readonly ParsedExpr[]): boolean {
+  return matchers.some((m) => m(callee, args) !== null)
+}
+
+/** Best-effort dotted-path text for the diagnostic message's receiver description. */
+function describeReceiverPath(expr: ParsedExpr): string {
+  if (expr.kind === 'identifier') return expr.name
+  if (expr.kind === 'member' && !expr.computed) return `${describeReceiverPath(expr.object)}.${expr.property}`
+  return '<expression>'
+}
+
+/**
+ * Whether the receiver path roots at a prop (bare destructured prop or a
+ * `props.x` chain) rather than a locally-bound name (loop item, arrow param).
+ * Decides whether the diagnostic may call the receiver a "prop" — a loop
+ * item's `i.at` is prop-DERIVED but not itself a prop, and naming it one
+ * would misdirect the fix toward the props type.
+ */
+function receiverRootIsProp(expr: ParsedExpr, bindings: Bindings): boolean {
+  let root = expr
+  while (root.kind === 'member' && !root.computed) root = root.object
+  return root.kind === 'identifier' && !bindings.has(root.name)
+}
+
+function pushDiagnostic(
+  errors: CompilerError[],
+  seen: Set<string>,
+  loc: SourceLocation,
+  method: string,
+  receiverPath: string,
+  isProp: boolean,
+  typeName: string,
+): void {
+  const key = `${loc.start.line}:${loc.start.column}:${receiverPath}.${method}`
+  if (seen.has(key)) return
+  seen.add(key)
+  const receiver = isProp ? `prop '${receiverPath}'` : `'${receiverPath}'`
+  errors.push({
+    code: ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+    severity: 'error',
+    message: `Expression cannot be compiled to marked template: method '.${method}()' on ${receiver} of host type '${typeName}' has no catalogued lowering.`,
+    loc,
+    suggestion: {
+      message: 'Add /* @client */ to evaluate this expression on the client only, or pre-compute the value server-side.',
+    },
+  })
+}
+
+/**
+ * Recurse a parsed expression tree, checking every `call` node along the way
+ * and descending into every sub-expression (so a rich-type call nested
+ * inside a larger expression — a template literal interpolation, an object
+ * literal value, an arrow body, …) is still found. `bindings` carries local
+ * type evidence (loop item / arrow param shadows) down into the recursion.
+ */
+function checkExpr(
+  expr: ParsedExpr,
+  loc: SourceLocation,
+  meta: IRMetadata,
+  bindings: Bindings,
+  matchers: readonly LoweringMatcher[],
+  errors: CompilerError[],
+  seen: Set<string>,
+): void {
+  const recurse = (e: ParsedExpr, b: Bindings = bindings) => checkExpr(e, loc, meta, b, matchers, errors, seen)
+
+  switch (expr.kind) {
+    case 'call': {
+      if (expr.callee.kind === 'member') {
+        const receiverType = resolveReceiverType(expr.callee.object, meta, bindings)
+        if (receiverType && receiverType.kind === 'interface') {
+          const typeName = baseTypeName(receiverType.raw)
+          const inFileShadow = meta.typeDefinitions.some((d) => d.name === typeName)
+          if (HOST_RICH_TYPE_NAMES.has(typeName) && !inFileShadow && !isLoweringClaimed(matchers, expr.callee, expr.args)) {
+            pushDiagnostic(
+              errors,
+              seen,
+              loc,
+              expr.callee.property,
+              describeReceiverPath(expr.callee.object),
+              receiverRootIsProp(expr.callee.object, bindings),
+              typeName,
+            )
+          }
+        }
+      }
+      recurse(expr.callee)
+      for (const arg of expr.args) recurse(arg)
+      break
+    }
+    case 'member':
+      recurse(expr.object)
+      break
+    case 'index-access':
+      recurse(expr.object)
+      recurse(expr.index)
+      break
+    case 'binary':
+      recurse(expr.left)
+      recurse(expr.right)
+      break
+    case 'unary':
+      recurse(expr.argument)
+      break
+    case 'conditional':
+      recurse(expr.test)
+      recurse(expr.consequent)
+      recurse(expr.alternate)
+      break
+    case 'logical':
+      recurse(expr.left)
+      recurse(expr.right)
+      break
+    case 'template-literal':
+      for (const part of expr.parts) if (part.type === 'expression') recurse(part.expr)
+      break
+    case 'arrow': {
+      const shadowed = new Map(bindings)
+      for (const param of expr.params) shadowed.set(param, null)
+      recurse(expr.body, shadowed)
+      break
+    }
+    case 'array-literal':
+      for (const el of expr.elements) recurse(el)
+      break
+    case 'object-literal':
+      for (const prop of expr.properties) recurse(prop.value)
+      break
+    case 'array-method':
+      recurse(expr.object)
+      for (const arg of expr.args) recurse(arg)
+      break
+    case 'identifier':
+    case 'literal':
+    case 'regex':
+    case 'unsupported':
+      break
+  }
+}
+
+/** `IRTemplatePart.ternary.condition` / `.lookup.key` carry no attached parse (unlike every other position here), so parse on demand. */
+function walkTemplateParts(
+  parts: readonly IRTemplatePart[],
+  loc: SourceLocation,
+  meta: IRMetadata,
+  bindings: Bindings,
+  matchers: readonly LoweringMatcher[],
+  errors: CompilerError[],
+  seen: Set<string>,
+): void {
+  for (const part of parts) {
+    if (part.type === 'ternary') {
+      const trimmed = part.condition.trim()
+      if (trimmed) checkExpr(parseExpression(trimmed), loc, meta, bindings, matchers, errors, seen)
+    } else if (part.type === 'lookup') {
+      const trimmed = part.key.trim()
+      if (trimmed) checkExpr(parseExpression(trimmed), loc, meta, bindings, matchers, errors, seen)
+    }
+  }
+}
+
+function walkAttrValue(
+  value: AttrValue,
+  clientOnly: boolean | undefined,
+  loc: SourceLocation,
+  meta: IRMetadata,
+  bindings: Bindings,
+  matchers: readonly LoweringMatcher[],
+  errors: CompilerError[],
+  seen: Set<string>,
+): void {
+  if (clientOnly) return
+  if (value.kind === 'expression') {
+    if (value.parsed) checkExpr(value.parsed, loc, meta, bindings, matchers, errors, seen)
+    if (value.parts) walkTemplateParts(value.parts, loc, meta, bindings, matchers, errors, seen)
+  } else if (value.kind === 'spread') {
+    if (value.parsed) checkExpr(value.parsed, loc, meta, bindings, matchers, errors, seen)
+  } else if (value.kind === 'template') {
+    walkTemplateParts(value.parts, loc, meta, bindings, matchers, errors, seen)
+  }
+}
+
+function walkNode(
+  node: IRNode,
+  meta: IRMetadata,
+  bindings: Bindings,
+  matchers: readonly LoweringMatcher[],
+  errors: CompilerError[],
+  seen: Set<string>,
+): void {
+  if (node.type === 'expression') {
+    if (!node.clientOnly && node.parsed) checkExpr(node.parsed, node.loc, meta, bindings, matchers, errors, seen)
+  } else if (node.type === 'conditional') {
+    if (!node.clientOnly && node.parsedCondition) checkExpr(node.parsedCondition, node.loc, meta, bindings, matchers, errors, seen)
+  } else if (node.type === 'if-statement') {
+    if (node.parsedCondition) checkExpr(node.parsedCondition, node.loc, meta, bindings, matchers, errors, seen)
+  }
+
+  if (node.type === 'element') {
+    for (const attr of node.attrs) walkAttrValue(attr.value, attr.clientOnly, attr.loc, meta, bindings, matchers, errors, seen)
+  } else if (node.type === 'component') {
+    for (const prop of node.props) walkAttrValue(prop.value, prop.clientOnly, prop.loc, meta, bindings, matchers, errors, seen)
+  } else if (node.type === 'provider') {
+    walkAttrValue(node.valueProp.value, node.valueProp.clientOnly, node.valueProp.loc, meta, bindings, matchers, errors, seen)
+  }
+
+  switch (node.type) {
+    case 'element':
+    case 'component':
+    case 'fragment':
+    case 'provider':
+      for (const child of node.children) walkNode(child, meta, bindings, matchers, errors, seen)
+      break
+    case 'async':
+      walkNode(node.fallback, meta, bindings, matchers, errors, seen)
+      for (const child of node.children) walkNode(child, meta, bindings, matchers, errors, seen)
+      break
+    case 'loop': {
+      if (node.clientOnly) break
+      if (node.arrayParsed) checkExpr(node.arrayParsed, node.loc, meta, bindings, matchers, errors, seen)
+      const loopBindings = new Map(bindings)
+      const arrayType = node.arrayParsed ? resolveReceiverType(node.arrayParsed, meta, bindings) : null
+      loopBindings.set(node.param, arrayType?.kind === 'array' ? arrayType.elementType ?? null : null)
+      if (node.index) loopBindings.set(node.index, null)
+      for (const child of node.children) walkNode(child, meta, loopBindings, matchers, errors, seen)
+      if (node.childComponent) {
+        for (const child of node.childComponent.children) walkNode(child, meta, loopBindings, matchers, errors, seen)
+      }
+      for (const nested of node.nestedComponents ?? []) {
+        for (const child of nested.children) walkNode(child, meta, loopBindings, matchers, errors, seen)
+      }
+      for (const frag of node.flatMapCallback?.fragments ?? []) {
+        walkNode(frag.ir, meta, loopBindings, matchers, errors, seen)
+      }
+      break
+    }
+    case 'conditional':
+      // A clientOnly conditional's branches never reach any template (the
+      // whole expression defers to hydrate), so walking them would flag calls
+      // whose own suggested remediation — /* @client */ — is already applied.
+      if (node.clientOnly) break
+      walkNode(node.whenTrue, meta, bindings, matchers, errors, seen)
+      walkNode(node.whenFalse, meta, bindings, matchers, errors, seen)
+      break
+    case 'if-statement':
+      walkNode(node.consequent, meta, bindings, matchers, errors, seen)
+      if (node.alternate) walkNode(node.alternate, meta, bindings, matchers, errors, seen)
+      break
+  }
+}

package/src/types.ts

@@ -90,6 +90,15 @@ export interface ParamInfo {
   defaultContainsArrow?: boolean
   /** When true, the parameter is a rest spread (`...args`) — emit must prepend `...`. */
   isRest?: boolean
+  /**
+   * Source property name for an aliased destructured prop (`{ createdAt: c }`
+   * → name: 'c', sourceName: 'createdAt'). Set ONLY when the binding renames —
+   * an un-aliased binding leaves it unset so existing IR shapes/snapshots are
+   * untouched. Consumers keying into `propsType.properties` must use
+   * `sourceName ?? name` (the param's own `type` degrades to `unknown` for
+   * non-primitive props — `collectMemberTypes`' primitives-only gate).
+   */
+  sourceName?: string
 }
 
 // =============================================================================