@barefootjs/jsx 0.17.0 → 0.18.0

package/src/ssr-seed-plan.ts

@@ -0,0 +1,146 @@
+/**
+ * Backend-neutral SSR seed plan — which signals/memos an adapter may seed
+ * in-template at SSR time, and from what scope.
+ *
+ * Design principle: the IR/analyzer side ANALYZES and attaches structured
+ * information; adapters only EMIT. The "is this binding derivable from names
+ * already in template scope" decision used to live (triplicated) in the
+ * template adapters' seed paths; this module computes it once, on the IR, so
+ * every adapter consumes the same plan and only supplies its own syntax.
+ *
+ * Ordering / acyclicity guarantee: `steps` lists the component's signals
+ * first, then its memos, each group in declaration order (matching
+ * `IRMetadata.signals` / `IRMetadata.memos`). A binding's name only enters
+ * the scope set AFTER its own step is decided, so a `derived` step's `frees`
+ * can only name `baseScope` entries or EARLIER steps — self- and
+ * forward-references are rejected by construction, and a consumer emitting
+ * the steps top-to-bottom never reads an undeclared local.
+ *
+ * Module-scope pure-string consts count as in-scope (they are part of
+ * `baseScope`) because every adapter compile-time-inlines them to their
+ * literal value — `collectModuleStringConsts` is the shared source of that
+ * set — so a reference to one is never a template-variable read.
+ *
+ * A `derived` step with EMPTY `frees` is a constant expression (e.g.
+ * `createSignal('b')`): the plan still classifies it as derived because the
+ * expression is fully analyzable; emit-side constant-skipping (adapters keep
+ * their existing ssr-defaults seeding for such inits) is an adapter concern,
+ * not a plan concern. Likewise the plan makes no backend-specific choices —
+ * no target-variable checks, no self-shadowing rules, no per-backend shape
+ * catalogs — those stay in the adapters.
+ */
+
+import { collectModuleStringConsts } from './augment-inherited-props.ts'
+import { envSignalReaderFor, type EnvSignalReader } from './adapters/env-signal.ts'
+import {
+  extractArrowBodyExpression,
+  freeIdentifiers,
+  isSupported,
+  parseExpression,
+  type ParsedExpr,
+} from './expression-parser.ts'
+import type { IRMetadata } from './types.ts'
+
+/**
+ * One binding in component declaration order (signals first, then memos —
+ * matching `IRMetadata` order and the adapters' iteration).
+ *
+ * - `env-reader`: an env signal whose `envReader` key resolves in the shared
+ *   registry (`envSignalReaderFor`). The runtime provides the per-request
+ *   reader, so there is nothing to seed; the name still enters scope so a
+ *   later derived step may reference it. An `envReader` key UNKNOWN to the
+ *   registry falls through to the normal derived/opaque rules instead.
+ * - `derived`: the binding's value expression is a supported shape whose free
+ *   identifiers are all in scope at this point (baseScope + earlier steps) —
+ *   an adapter may seed it in-template by lowering `parsed`/`expr`.
+ * - `opaque`: not seedable this way (empty init, unsupported shape,
+ *   unanalyzable free set, out-of-scope reference, or a block-bodied memo).
+ *   The name still enters scope for later steps; adapters keep their static
+ *   ssr-defaults seeding for it.
+ */
+export type SsrSeedStep =
+  | { kind: 'env-reader'; name: string; reader: EnvSignalReader }
+  | { kind: 'derived'; name: string; origin: 'signal' | 'memo'; expr: string; parsed: ParsedExpr; frees: string[] }
+  | { kind: 'opaque'; name: string; origin: 'signal' | 'memo' }
+
+export interface SsrSeedPlan {
+  /**
+   * Names in scope before any step: props params, the props-object name
+   * (when the component takes an undestructured props object), and module
+   * pure-string consts (compile-time inlined by every adapter).
+   */
+  baseScope: string[]
+  steps: SsrSeedStep[]
+}
+
+/**
+ * Classify one value expression against the current scope: `derived` when it
+ * parses to a supported shape whose free identifiers are all `available`
+ * (an unanalyzable free set — `freeIdentifiers` → null — fails safe to
+ * opaque). The scope check runs over the parsed SOURCE tree, so a shadowed
+ * name (`items.filter((p) => p.ok) && p`, where the trailing `p` is a
+ * different, unbound reference from the callback's own param) is rejected.
+ */
+function classify(
+  name: string,
+  origin: 'signal' | 'memo',
+  expr: string,
+  parsed: ParsedExpr,
+  available: ReadonlySet<string>,
+): SsrSeedStep {
+  if (!isSupported(parsed).supported) return { kind: 'opaque', name, origin }
+  const frees = freeIdentifiers(parsed)
+  if (frees === null) return { kind: 'opaque', name, origin }
+  for (const free of frees) {
+    if (!available.has(free)) return { kind: 'opaque', name, origin }
+  }
+  return { kind: 'derived', name, origin, expr, parsed, frees: [...frees] }
+}
+
+/**
+ * Compute the component's SSR seed plan from its metadata. See the module
+ * doc for the contract. Memo steps are gated to EXPRESSION-BODIED memos
+ * (`extractArrowBodyExpression` returns the body): a block-bodied memo is
+ * `opaque` even when the analyzer folded it to a `parsed` expression.
+ */
+export function computeSsrSeedPlan(metadata: IRMetadata): SsrSeedPlan {
+  const baseScope: string[] = metadata.propsParams.map(p => p.name)
+  if (metadata.propsObjectName) baseScope.push(metadata.propsObjectName)
+  for (const name of collectModuleStringConsts(metadata.localConstants).keys()) {
+    baseScope.push(name)
+  }
+
+  const available = new Set<string>(baseScope)
+  const steps: SsrSeedStep[] = []
+
+  for (const signal of metadata.signals) {
+    if (signal.envReader) {
+      const reader = envSignalReaderFor(signal.envReader)
+      if (reader) {
+        steps.push({ kind: 'env-reader', name: signal.getter, reader })
+        available.add(signal.getter)
+        continue
+      }
+    }
+    const expr = signal.initialValue.trim()
+    steps.push(
+      expr === ''
+        ? { kind: 'opaque', name: signal.getter, origin: 'signal' }
+        : classify(signal.getter, 'signal', expr, parseExpression(expr), available),
+    )
+    available.add(signal.getter)
+  }
+
+  for (const memo of metadata.memos) {
+    const body = extractArrowBodyExpression(memo.computation)
+    const expr = body?.trim() ?? ''
+    steps.push(
+      expr === ''
+        ? { kind: 'opaque', name: memo.name, origin: 'memo' }
+        : classify(memo.name, 'memo', expr, memo.parsed ?? parseExpression(expr), available),
+    )
+    available.add(memo.name)
+  }
+
+  return { baseScope, steps }
+}

package/src/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ParsedExpr, ParsedStatement } from './expression-parser.ts'
+import type { SsrSeedPlan } from './ssr-seed-plan.ts'
 
 /**
  * Loop-hoisted sort comparator for the `.sort().map()` / `.toSorted().map()`
@@ -694,6 +695,26 @@ export interface RestExcludeKey {
   isIdent: boolean
 }
 
+/**
+ * Structured, non-string form of a `.map()` callback destructure accessor
+ * step — one entry per `.foo` / `["a-b"]` / `[0]` step folded into
+ * {@link LoopParamBinding.path}. Adapters that need to build their own
+ * accessor expression (rather than splice `path` in as a JS suffix) walk
+ * `segments` instead of parsing `path` with a regex (repo rule: never parse
+ * JS/TS syntax with regex or string matching).
+ *
+ * - `{ kind: 'field', key, isIdent }`: an object-property step. `isIdent`
+ *   uses the same `ts.isIdentifierStart`/`isIdentifierPart` classification
+ *   as {@link RestExcludeKey.isIdent} — an adapter choosing between a native
+ *   `.foo` accessor and a quoted/bracketed one (`["data-priority"]`, a
+ *   quoted map key, ...) reads this instead of re-deriving the identifier
+ *   rule itself.
+ * - `{ kind: 'index', index }`: an array-position step (`[0]`, `[1]`, ...).
+ */
+export type LoopBindingPathSegment =
+  | { kind: 'field'; key: string; isIdent: boolean }
+  | { kind: 'index'; index: number }
+
 /**
  * Destructured binding extracted from a `.map()` callback's item parameter.
  *
@@ -720,6 +741,24 @@ export interface LoopParamBinding {
   rest?:
     | { kind: 'object'; exclude: readonly RestExcludeKey[] }
     | { kind: 'array'; from: number }
+  /**
+   * Structured form of `path` (see {@link LoopBindingPathSegment}).
+   *
+   * - Fixed bindings (`rest` unset): the full accessor from the loop item to
+   *   this binding, one segment per `path` step. Always non-empty — a fixed
+   *   binding always has at least one accessor step.
+   * - Rest bindings (`rest` set): the structured form of the PARENT prefix
+   *   (i.e. of `path`, which for rest bindings holds the parent prefix, not
+   *   an accessor to the rest binding itself) — possibly empty when the
+   *   rest sits at the loop root (`({ ...rest }) => …` / `([...rest]) => …`).
+   *
+   * Optional only so older/foreign IR (built before this field existed)
+   * still type-checks; `extractLoopParamBindings` always populates it now.
+   * Downstream gates (`isLowerableLoopDestructure`) treat a missing
+   * `segments` as "unknown shape" and refuse conservatively rather than
+   * reading it as "binding at the loop root".
+   */
+  segments?: readonly LoopBindingPathSegment[]
 }
 
 export interface IRComponent {
@@ -1526,6 +1565,16 @@ export interface IRMetadata {
    * resolves the compiled module rather than the source `.tsx`.
    */
   clientSignalImportSources?: Set<string>
+  /**
+   * Backend-neutral SSR seed plan: per-binding derived/opaque/env-reader
+   * classification in declaration order, plus the base scope, computed by
+   * `computeSsrSeedPlan` from this metadata. Attached by `buildMetadata` and
+   * serialized into IR JSON like the rest of the metadata; template adapters
+   * consume it instead of re-deriving scope/derivability themselves (their
+   * target-syntax choices — lowering, self-shadow rules, constant-emit
+   * guards — stay adapter-side).
+   */
+  ssrSeedPlan?: SsrSeedPlan
 }
 
 // =============================================================================
@@ -1699,6 +1748,24 @@ export interface ErrorSuggestion {
   replacement?: string
 }
 
+/**
+ * A diagnostic an adapter intentionally emits for a shared conformance
+ * fixture (packages/adapter-tests) instead of lowering it — the adapter's
+ * machine-readable known-limitations declaration. Consumed by the adapter's
+ * own conformance test (as `expectedDiagnostics`) and by `bf compat`
+ * (issue-URL attribution). Tracked limitations carry the `known-limitation`
+ * label: https://github.com/piconic-ai/barefootjs/labels/known-limitation
+ */
+export interface ConformancePin {
+  /** Diagnostic code, e.g. 'BF101'. */
+  code: string
+  severity: 'error' | 'warning'
+  /** Tracking issue URL (known-limitation label) for this refusal, when one exists. */
+  issue?: string
+}
+/** Keyed by shared-fixture id (`JSXFixture.id`). */
+export type ConformancePins = Record<string, ReadonlyArray<ConformancePin>>
+
 // =============================================================================
 // Compile Options & Results
 // =============================================================================
@@ -1759,6 +1826,15 @@ export interface FileOutput {
   path: string
   content: string
   type: 'markedTemplate' | 'clientJs' | 'ir' | 'sourceMap' | 'types' | 'ssrDefaults'
+  /**
+   * The exported component this file was generated for. Set on
+   * `markedTemplate` / `ssrDefaults` outputs so the build pipeline can pair
+   * them per component without guessing from file basenames — a
+   * single-component file's template is named after the SOURCE file
+   * (`index.html.ep`), not the component, so the basename alone can't
+   * recover the component name (#2132).
+   */
+  componentName?: string
 }
 
 export interface CompileResult {