jz 0.5.1 → 0.7.0

package/src/compile/plan/common.js

@@ -0,0 +1,150 @@
+/**
+ * Shared AST utilities for plan/ subsystems.
+ *
+ * Helpers used by multiple subfiles (scalarize/loops/inline). Single-use helpers
+ * stay with their consumer.
+ *
+ * @module compile/plan/common
+ */
+
+import { ctx } from '../../ctx.js'
+import { ASSIGN_OPS, some, callArgs } from '../../ast.js'
+import { constIntExpr } from '../../static.js'
+import { typedElemCtor } from '../../type.js'
+import { PASS_NAMES } from '../../optimize/index.js'
+
+/** True iff the optimizer is active (any non-falsy pass under `ctx.transform.optimize`). */
+export const optimizing = () => { const c = ctx.transform.optimize; return !!c && PASS_NAMES.some(n => c[n]) }
+
+/** Ops whose body opens a new loop scope. (`for-in`/`for-of` excluded — they
+ *  bind a fresh per-iter local on each entry, so jz lowers them differently.) */
+export const LOOP_OPS = new Set(['for', 'while', 'do', 'do-while'])
+
+/** Inline-substitution argument check — pure, side-effect-free, captures nothing. */
+export const isSimpleArg = node => {
+  if (typeof node === 'string' || typeof node === 'number') return true
+  if (!Array.isArray(node)) return false
+  if (node[0] == null) return typeof node[1] === 'number'
+  if (node[0] === 'str') return typeof node[1] === 'string'
+  if (node[0] === 'u-' || (node[0] === '-' && node.length === 2)) return isSimpleArg(node[1])
+  if (['+', '-', '*', '/', '%', '&', '|', '^', '<<', '>>', '>>>'].includes(node[0]))
+    return isSimpleArg(node[1]) && isSimpleArg(node[2])
+  return false
+}
+
+/** Maximum loop nesting under `node`. Closures (`=>`) opaque — their loops don't count. */
+export const loopDepth = (node, depth) => {
+  if (!Array.isArray(node)) return depth
+  if (node[0] === '=>') return depth
+  const here = LOOP_OPS.has(node[0]) ? depth + 1 : depth
+  let max = here
+  for (let i = 1; i < node.length; i++) {
+    const d = loopDepth(node[i], here)
+    if (d > max) max = d
+  }
+  return max
+}
+
+/** Node-count weight — drives inline cost heuristics. */
+export const nodeSize = (node) => {
+  if (!Array.isArray(node)) return 1
+  let n = 1
+  for (let i = 1; i < node.length; i++) n += nodeSize(node[i])
+  return n
+}
+
+/** Collect every binder name in `node` into `out` (lexical-scope set; doesn't
+ *  descend into nested arrow bodies — those open a new scope). */
+export const collectBindings = (node, out) => {
+  if (!Array.isArray(node)) return
+  const op = node[0]
+  if (op === '=>') return
+  if (op === 'let' || op === 'const') {
+    for (let i = 1; i < node.length; i++) collectBindingTarget(node[i], out)
+  }
+  for (let i = 1; i < node.length; i++) collectBindings(node[i], out)
+}
+
+const collectBindingTarget = (node, out) => {
+  if (typeof node === 'string') { out.add(node); return }
+  if (!Array.isArray(node)) return
+  if (node[0] === '=') collectBindingTarget(node[1], out)
+  else if (node[0] === '...' && typeof node[1] === 'string') out.add(node[1])
+  else if (node[0] === ',' || node[0] === '[]' || node[0] === '{}')
+    for (let i = 1; i < node.length; i++) collectBindingTarget(node[i], out)
+}
+
+/** True iff `node` writes to any name in `names` (incl. `++`/`--` and compound assigns). */
+export const mutatesAny = (node, names) => some(node, n => {
+  const op = n[0]
+  if ((op === '++' || op === '--') && typeof n[1] === 'string') return names.has(n[1])
+  return ASSIGN_OPS.has(op) && typeof n[1] === 'string' && names.has(n[1])
+})
+
+/** Deep-clone array-tree AST. Plain values pass through by identity. */
+export const clonePlain = node => Array.isArray(node) ? node.map(clonePlain) : node
+
+/** AST index of a `for` loop's body, or null if `stmt` isn't a `for`.
+ *  Handles both `['for', cond, body]` (3-arg while-like) and the full
+ *  `['for', init, cond, step, body]` C-style form. */
+export const forLoopBodyIndex = (stmt) =>
+  Array.isArray(stmt) && stmt[0] === 'for' ? (stmt.length === 3 ? 2 : 4) : null
+
+/** Reconstruct a `for` node with its body replaced. Preserves arity. */
+export const withForLoopBody = (stmt, body) =>
+  stmt.length === 3 ? ['for', stmt[1], body] : ['for', stmt[1], stmt[2], stmt[3], body]
+
+// === Fixed-size typed-array recognition ===
+// Shared by scalarize (replaces the literal with N locals) and inline (filters
+// inlinings that would trample a typed-array param). Tables/thresholds live here
+// so both subsystems agree on what "scalarizable" means.
+
+/** Fixed-size typed-array ctors eligible for scalar replacement, mapped to the
+ *  element store-coercion kind ('' = none, i.e. Float64Array's f64-identity).
+ *  Excluded: Float32Array (Math.fround pulls module), Uint32Array (range > i32),
+ *  Uint8ClampedArray (round-half-even clamp). Coerced (truthy) types are only
+ *  scalarized when fully local. */
+export const SCALAR_TYPED_COERCE = {
+  'new.Float64Array': '',
+  'new.Int32Array': 'i32',
+  'new.Int16Array': 'i16', 'new.Uint16Array': 'u16',
+  'new.Int8Array': 'i8', 'new.Uint8Array': 'u8',
+}
+
+// Default 64 covers the 8×8 block kernels (DCT/JPEG-shaped). Measured at 64
+// elements: scalarized form is ~2.2× SMALLER (stores fold away; local refs
+// out-LEB the memory ops they replace) and 2.5× faster than the memory form —
+// there is no LEB128 cliff in practice.
+export const maxScalarTypedArrayLen = () => ctx.transform.optimize?.scalarTypedArrayLen ?? 64
+
+/** Recognize `new TypedArrayCtor(N)` with `N` a static small integer.
+ *  Returns `{len, coerce}` or null. */
+export const fixedScalarTypedArray = (expr) => {
+  const ctor = typedElemCtor(expr)
+  if (ctor == null || !(ctor in SCALAR_TYPED_COERCE)) return null
+  const args = callArgs(expr)
+  if (!args || args.length !== 1) return null
+  const len = constIntExpr(args[0])
+  return len != null && len >= 0 && len <= maxScalarTypedArrayLen()
+    ? { len, coerce: SCALAR_TYPED_COERCE[ctor] } : null
+}
+
+/** Map of name → {len, coerce} for every fixed-size typed-array binding declared
+ *  via `let`/`const` directly in `body` (no descent into nested arrows). */
+export const fixedTypedArraysInBody = (body) => {
+  const out = new Map()
+  const walk = node => {
+    if (!Array.isArray(node) || node[0] === '=>') return
+    if (node[0] === 'let' || node[0] === 'const') {
+      for (let i = 1; i < node.length; i++) {
+        const d = node[i]
+        if (!Array.isArray(d) || d[0] !== '=' || typeof d[1] !== 'string') continue
+        const fixed = fixedScalarTypedArray(d[2])
+        if (fixed != null) out.set(d[1], fixed)
+      }
+    }
+    for (let i = 1; i < node.length; i++) walk(node[i])
+  }
+  walk(body)
+  return out
+}

package/src/compile/plan/index.js

@@ -0,0 +1,122 @@
+/**
+ * Pre-emit compile planning: bridges prepare (AST shape) and emit (wasm bytes).
+ *
+ * # Stage contract
+ *   IN:  populated `ctx` from prepare.js (functions, schemas, scopes, modules)
+ *        plus the prepared AST.
+ *   OUT: returns a `programFacts` object; mutates `ctx` so each function has
+ *        narrowed signatures, finalized global reps, and per-call decisions.
+ *
+ * # Pipeline (top-level `plan(ast)`)
+ *   1. unboxConstTypedGlobals — finalize global storage. (Global value facts
+ *      themselves are seeded by prepare via `infer.recordGlobalRep`.)
+ *   2. collectProgramFacts — sweep arrow bodies for typed-elem usage, key sets,
+ *      loop depth, control-transfer shapes; rerun if hot inlining changes the AST.
+ *   3. materializeAutoBoxSchemas / resolveClosureWidth — settle layout decisions.
+ *   4. Whole-program narrowing (skipped on simple programs):
+ *        - narrowSignatures — pick a specialization per function from call sites
+ *        - specializeBimorphicTyped — split typed-elem hot paths into two variants
+ *          when callers diverge between two ctors
+ *        - refineDynKeys — tighten dynamic property-key sets
+ *
+ * No bytes are emitted here; emit.js consumes the planned ctx + programFacts.
+ *
+ * @module plan
+ */
+
+import { ctx } from '../../ctx.js'
+import { collectProgramFacts, refreshProgramFacts } from '../program-facts.js'
+import narrowSignatures, {
+  specializeBimorphicTyped, refineDynKeys,
+  applyJsstringBoundaryCarrierStandalone, narrowBoolResults,
+  strictBoundaryTypeCheck,
+} from '../narrow.js'
+
+import { optimizing } from './common.js'
+import { adviseProgram } from './advise.js'
+import {
+  inferModuleLetTypes, unboxConstTypedGlobals, inferModuleIntGlobals,
+  flattenFuncNamespaces, devirtGlobalCalls,
+  materializeAutoBoxSchemas, resolveClosureWidth, canSkipWholeProgramNarrowing,
+} from './scope.js'
+import { inlineHotInternalCalls, inlineLocalLambdas, specializeFixedRestCalls } from './inline.js'
+import { bindNestedRowLengths, unrollRowLenPadLoops, splitCharScanLoops } from './loops.js'
+import {
+  scalarizeFunctionTypedArrays, scalarizeFunctionArrayLiterals,
+  promoteIntArrayLiterals, scalarizeFunctionObjectLiterals,
+} from './literals.js'
+
+export default function plan(ast, profiler) {
+  // Per-pass timing under `plan:` — the plan stage is the compile pipeline's
+  // multi-pass hot spot (each mutating pass triggers a whole-program fact
+  // refresh), so the profile must show WHICH pass and refresh dominate.
+  const t = profiler?.time ? (name, fn) => profiler.time(`plan:${name}`, fn) : (_, fn) => fn()
+  // AST-mutating pass: run timed; on change, re-sweep program facts (timed
+  // separately — the refreshes are usually the cost, not the passes).
+  let programFacts
+  const sweep = (name, pass) => {
+    if (t(name, pass)) programFacts = t('refreshFacts', () => refreshProgramFacts(ast, programFacts))
+  }
+
+  t('inferModuleLetTypes', () => inferModuleLetTypes(ast))
+  t('unboxConstTypedGlobals', unboxConstTypedGlobals)
+  t('inferModuleIntGlobals', () => inferModuleIntGlobals(ast))
+
+  programFacts = t('collectFacts', () => collectProgramFacts(ast))
+  // Function-namespace SROA — dissolve reassigned `f.prop` slots into module
+  // globals before inlining/narrowing, so all downstream passes see plain
+  // globals instead of the dynamic property machinery.
+  sweep('flattenFuncNamespaces', () => flattenFuncNamespaces(ast))
+  // Devirtualize calls through init-constant function globals (closure
+  // devirtualization) — must follow the SROA above, which creates the globals.
+  t('devirtGlobalCalls', () => devirtGlobalCalls(ast))
+  sweep('bindNestedRowLengths', bindNestedRowLengths)
+  sweep('unrollRowLenPadLoops', unrollRowLenPadLoops)
+  // The call-inlining family (`inlineHotInternalCalls` self-gates on `sourceInline`)
+  // is a pure speed optimization — the un-inlined calls emit correctly. Scalar
+  // replacement (`scalarize*`) and array promotion gate on `optimizing()`: off only
+  // under a fully-disabled optimizer, on for every enabled preset (incl. the
+  // `optimize:{sourceInline:false}` heap-elision-test form, which is level-2 based).
+  sweep('inlineHotInternalCalls', () => inlineHotInternalCalls(programFacts, ast))
+  sweep('bindNestedRowLengths', bindNestedRowLengths)
+  sweep('unrollRowLenPadLoops', unrollRowLenPadLoops)
+  sweep('inlineLocalLambdas', inlineLocalLambdas)
+  sweep('specializeFixedRestCalls', () => specializeFixedRestCalls(programFacts))
+  if (optimizing()) {
+    sweep('splitCharScan', splitCharScanLoops)
+    sweep('scalarizeArrayLiterals', scalarizeFunctionArrayLiterals)
+    sweep('scalarizeObjectLiterals', scalarizeFunctionObjectLiterals)
+    // Promotion runs AFTER literal scalarization (those that fully reduce to scalars
+    // are gone) and BEFORE typed-array scalarization (so a freshly-promoted array's
+    // fixed-length-typed-of-known-size variant could still participate in loop
+    // unrolling — currently it can't, since promotion produces the `[...]`-arg
+    // form rather than `new Int32Array(N)`, but the ordering keeps the door open).
+    sweep('promoteIntArrayLiterals', promoteIntArrayLiterals)
+    sweep('scalarizeTypedArrays', () => scalarizeFunctionTypedArrays(programFacts))
+  }
+  ctx.types.dynKeyVars = programFacts.dynVars
+  ctx.types.dynWriteVars = programFacts.dynWriteVars
+  ctx.types.anyDynKey = programFacts.anyDyn
+
+  t('materializeAutoBoxSchemas', () => materializeAutoBoxSchemas(programFacts))
+  t('resolveClosureWidth', () => resolveClosureWidth(programFacts))
+  if (canSkipWholeProgramNarrowing(programFacts)) {
+    // Phase J (jsstring boundary opt-in) is body-local and call-site-independent;
+    // run it even when the rest of narrowing is skipped so simple `export let
+    // f = (s) => s.length` still flips to externref. Likewise the boolean-result
+    // fact, so `export let f = (a) => a > 2` boxes its boundary atom.
+    applyJsstringBoundaryCarrierStandalone(programFacts)
+    narrowBoolResults()
+    strictBoundaryTypeCheck(programFacts)
+    adviseProgram(programFacts)
+    return programFacts
+  }
+
+  t('narrowSignatures', () => narrowSignatures(programFacts, ast))
+  t('specializeBimorphicTyped', () => specializeBimorphicTyped(programFacts))
+  t('refineDynKeys', () => refineDynKeys(programFacts))
+  strictBoundaryTypeCheck(programFacts)
+
+  adviseProgram(programFacts)
+  return programFacts
+}