@pyreon/compiler 0.15.0 → 0.16.0

package/src/jsx.ts

@@ -29,31 +29,21 @@
  */
 
 import { parseSync } from 'oxc-parser'
-import { createRequire } from 'node:module'
-import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'node:path'
 import { REACT_EVENT_REMAP } from './event-names'
+import { loadNativeBinding } from './load-native'
 
 // ─── Native binary auto-detection ────────────────────────────────────────────
-// Try to load the Rust napi-rs binary for 3.7-8.2x faster transforms.
-// Falls back to the JS implementation below if the binary isn't available
-// (wrong platform, CI environment, WASM runtime like StackBlitz, etc.)
+// Two-path resolution: in-tree binary first (dev mode), then per-platform
+// npm package (production install via optionalDependencies). Falls through
+// to the JS implementation below when both paths fail (wrong platform, CI
+// environment, WASM runtime like StackBlitz, missing per-platform package).
 //
-// Uses createRequire for ESM compatibility — __dirname and require() don't
-// exist in ESM modules.
+// See `load-native.ts` for the resolution logic.
 type NativeTransformFn = (code: string, filename: string, ssr: boolean, knownSignals: string[] | null) => TransformResult
-let nativeTransformJsx: NativeTransformFn | null = null
-
-try {
-  const __filename = fileURLToPath(import.meta.url)
-  const __dirname = dirname(__filename)
-  const nativeRequire = createRequire(import.meta.url)
-  const nativePath = join(__dirname, '..', 'native', 'pyreon-compiler.node')
-  const native = nativeRequire(nativePath) as { transformJsx: NativeTransformFn }
-  nativeTransformJsx = native.transformJsx
-} catch {
-  // Native binary not available — JS fallback will be used
-}
+const nativeBinding = loadNativeBinding(import.meta.url)
+const nativeTransformJsx: NativeTransformFn | null = nativeBinding
+  ? (nativeBinding.transformJsx as NativeTransformFn)
+  : null
 
 export interface CompilerWarning {
   /** Warning message */
@@ -774,19 +764,19 @@ export function transformJSX_JS(
   if (replacements.length === 0 && hoists.length === 0) return { code, warnings }
 
   replacements.sort((a, b) => a.start - b.start)
-  const parts: string[] = []
-  let lastPos = 0
+  const outParts: string[] = []
+  let outPos = 0
   for (const r of replacements) {
-    parts.push(code.slice(lastPos, r.start))
-    parts.push(r.text)
-    lastPos = r.end
+    outParts.push(code.slice(outPos, r.start))
+    outParts.push(r.text)
+    outPos = r.end
   }
-  parts.push(code.slice(lastPos))
-  let result = parts.join('')
+  outParts.push(code.slice(outPos))
+  let output = outParts.join('')
 
   if (hoists.length > 0) {
     const preamble = hoists.map((h) => `const ${h.name} = /*@__PURE__*/ ${h.text}\n`).join('')
-    result = preamble + result
+    output = preamble + output
   }
 
   if (needsTplImport) {
@@ -798,16 +788,16 @@ export function transformJSX_JS(
     const reactivityImports = needsBindImportGlobal
       ? `\nimport { _bind } from "@pyreon/reactivity";`
       : ''
-    result =
+    output =
       `import { ${runtimeDomImports.join(', ')} } from "@pyreon/runtime-dom";${reactivityImports}\n` +
-      result
+      output
   }
 
   if (needsRpImport) {
-    result = `import { _rp } from "@pyreon/core";\n` + result
+    output = `import { _rp } from "@pyreon/core";\n` + output
   }
 
-  return { code: result, usesTemplates: needsTplImport, warnings }
+  return { code: output, usesTemplates: needsTplImport, warnings }
 
   // ── Template emission helpers ─────────────────────────────────────────────
 

package/src/load-native.ts

@@ -0,0 +1,155 @@
+/**
+ * Native binding loader — resolves the @pyreon/compiler napi-rs binary
+ * via two paths in priority order:
+ *
+ *   1. **In-tree binary** at `<package>/native/pyreon-compiler.node`.
+ *      Populated by `scripts/build-native.ts` during local development
+ *      (Phase 2). Faster path because it skips npm-package resolution.
+ *
+ *   2. **Per-platform npm package** (Phase 5b — not active until per-
+ *      platform packages are published). Resolves `@pyreon/compiler-
+ *      <platform>-<arch>[-<libc>]` via the standard Node module
+ *      resolution algorithm. End users on machines without a local
+ *      `cargo` install will hit this path: `bun install` resolves
+ *      `optionalDependencies` to the matching per-platform package and
+ *      this loader picks it up.
+ *
+ *   3. **JS fallback** (caller's responsibility) — if both paths fail,
+ *      `loadNativeBinding()` returns `null` and the caller uses the
+ *      pure-JS implementation. Slower but correctness-equivalent.
+ *
+ * Platform detection follows the napi-rs convention. Linux variants
+ * include a `libc` suffix (`gnu` for glibc, `musl` for musl) per
+ * https://napi.rs/docs/cli/build#deployment.
+ *
+ * The two-path resolution lets dev-mode (where `cargo build` produced
+ * an in-tree binary) and production-mode (where the user has only the
+ * published per-platform package) coexist with no flag flipping.
+ */
+
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+export interface NativeBinding {
+  transformJsx: (
+    code: string,
+    filename: string,
+    ssr: boolean,
+    knownSignals: string[] | null,
+  ) => unknown
+}
+
+// Local Node-process surface. `@pyreon/runtime-dom` ships an ambient
+// `declare var process: { env: { NODE_ENV?: string } }` to enforce the
+// bundler-agnostic dev-gate pattern, which narrows `process` for ANY
+// file pulled in by runtime-dom's typecheck — including this one when
+// imported via the `bun` condition. Casting through a local interface
+// restores access to the platform/arch/report fields we genuinely need.
+interface NodeProcess {
+  platform: string
+  arch: string
+  report?: {
+    getReport(): unknown
+  }
+}
+const nodeProcess = process as unknown as NodeProcess
+
+/**
+ * Resolve the per-platform package name following the napi-rs naming
+ * convention: `@pyreon/compiler-<platform>-<arch>[-<libc>]`.
+ *
+ * Examples:
+ *   darwin + arm64        → @pyreon/compiler-darwin-arm64
+ *   darwin + x64          → @pyreon/compiler-darwin-x64
+ *   linux + x64 + gnu     → @pyreon/compiler-linux-x64-gnu
+ *   linux + arm64 + gnu   → @pyreon/compiler-linux-arm64-gnu
+ *   win32 + x64 + msvc    → @pyreon/compiler-win32-x64-msvc
+ *
+ * Returns `null` for unsupported (platform, arch) combinations — caller
+ * skips per-platform resolution entirely and falls through to JS.
+ */
+export function getPlatformPackageName(
+  platform: string = nodeProcess.platform,
+  arch: string = nodeProcess.arch,
+  libc: string | null = detectLibc(platform),
+): string | null {
+  // Build the suffix for libc-bearing platforms (Linux glibc/musl,
+  // Windows MSVC). Single source of truth — no per-platform branching.
+  const suffix = libc ? `-${libc}` : ''
+  // Allowlist of (platform, arch) combos that the cross-platform CI
+  // workflow actually builds. Keep in sync with
+  // `.github/workflows/release-native.yml` matrix.
+  const supported: Record<string, string[]> = {
+    darwin: ['arm64', 'x64'],
+    linux: ['x64', 'arm64'],
+    win32: ['x64'],
+  }
+  if (!supported[platform]?.includes(arch)) return null
+  return `@pyreon/compiler-${platform}-${arch}${suffix}`
+}
+
+/**
+ * Detect the libc family for the current Linux runtime. Returns:
+ *   - `'gnu'` on glibc-based distros (Debian, Ubuntu, RHEL, …)
+ *   - `'musl'` on musl-based distros (Alpine, …)
+ *   - `null` on macOS / Windows (no libc differentiation)
+ *   - `'msvc'` on Windows (we only ship MSVC binaries)
+ *
+ * `process.report.getReport().header.glibcVersionRuntime` is the
+ * Node-canonical detection: present on glibc, absent on musl. Falls
+ * back to `gnu` on read failure since glibc is the more common case.
+ */
+function detectLibc(platform: string): string | null {
+  if (platform === 'win32') return 'msvc'
+  if (platform !== 'linux') return null
+  try {
+    const report = nodeProcess.report?.getReport()
+    if (typeof report === 'object' && report !== null) {
+      const header = (report as { header?: { glibcVersionRuntime?: string } }).header
+      return header?.glibcVersionRuntime ? 'gnu' : 'musl'
+    }
+  } catch {
+    // Best-effort detection — fall through to glibc default.
+  }
+  return 'gnu'
+}
+
+/**
+ * Load the native binding by trying paths in order:
+ *   1. In-tree binary (`<package>/native/pyreon-compiler.node`)
+ *   2. Per-platform npm package (`@pyreon/compiler-<triple>`)
+ *
+ * Returns `null` if both paths fail — caller falls back to the
+ * pure-JS implementation. NEVER throws — every error path swallows
+ * silently because a missing native binary is a perf optimization
+ * miss, not a correctness failure.
+ */
+export function loadNativeBinding(metaUrl: string): NativeBinding | null {
+  const nativeRequire = createRequire(metaUrl)
+
+  // Path 1: in-tree binary (dev mode + Phase 2 local-build path).
+  try {
+    const __filename = fileURLToPath(metaUrl)
+    const __dirname = dirname(__filename)
+    const nativePath = join(__dirname, '..', 'native', 'pyreon-compiler.node')
+    return nativeRequire(nativePath) as NativeBinding
+  } catch {
+    // In-tree binary not present — fall through to per-platform package.
+  }
+
+  // Path 2: per-platform npm package (production install path).
+  // Will start working once Phase 5b publishes the per-platform
+  // packages and `optionalDependencies` resolves them at install time.
+  const pkgName = getPlatformPackageName()
+  if (pkgName !== null) {
+    try {
+      return nativeRequire(pkgName) as NativeBinding
+    } catch {
+      // Per-platform package not installed (typical pre-Phase-5b
+      // state, or a platform we don't yet ship binaries for).
+    }
+  }
+
+  return null
+}

package/src/pyreon-intercept.ts

@@ -41,6 +41,14 @@
  *  - `as-unknown-as-vnodechild` — defensive `as unknown as VNodeChild`
  *                       cast on JSX returns is unnecessary (`JSX.Element`
  *                       is already assignable to `VNodeChild`).
+ *  - `island-never-with-registry-entry` — an `island()` declared with
+ *                       `hydrate: 'never'` is also registered in the same
+ *                       file's `hydrateIslands({ ... })` call. The whole
+ *                       point of `'never'` is shipping zero client JS;
+ *                       registering pulls the component module into the
+ *                       client bundle graph (the runtime short-circuits
+ *                       and never calls the loader, but the bundler still
+ *                       includes the import). Drop the registry entry.
  *
  * Two-mode surface mirrors `react-intercept.ts`:
  *  - `detectPyreonPatterns(code)` — diagnostics only
@@ -81,6 +89,7 @@ export type PyreonDiagnosticCode =
   | 'signal-write-as-call'
   | 'static-return-null-conditional'
   | 'as-unknown-as-vnodechild'
+  | 'island-never-with-registry-entry'
 
 export interface PyreonDiagnostic {
   /** Machine-readable code for filtering + programmatic handling */
@@ -114,6 +123,21 @@ interface DetectContext {
    * patterns that should be `sig.set(value)`.
    */
   signalBindings: Set<string>
+  /**
+   * Names of `island()` declarations carrying `hydrate: 'never'`. Populated
+   * by `collectNeverIslandNames()` before the main detection walk. Used by
+   * `detectIslandNeverWithRegistry` to flag entries in
+   * `hydrateIslands({ ... })` whose key matches a never-strategy island.
+   *
+   * Cross-call detection: the never-vs-registry mismatch is only catchable
+   * when both sides live in the same source. In real apps the `island()`
+   * declarations sit in `src/islands.ts` and the `hydrateIslands()` call
+   * sits in `src/entry-client.ts`. The static detector covers the common
+   * "all in one file" case (which catches the bug while users are first
+   * learning the API); the cross-file case is the territory of `pyreon
+   * doctor --check-islands` (separate PR / future scope).
+   */
+  neverIslandNames: Set<string>
 }
 
 function getNodeText(ctx: DetectContext, node: ts.Node): string {
@@ -647,6 +671,101 @@ function detectAsUnknownAsVNodeChild(ctx: DetectContext, node: ts.AsExpression):
   )
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// Island never-with-registry detection
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Pre-pass: walk the source for `island(loader, { name: 'X', hydrate: 'never' })`
+ * call expressions and collect the `name` field of each never-strategy island.
+ *
+ * Recognized shape (mirrors `@pyreon/vite-plugin`'s `scanIslandDeclarations`):
+ *
+ *   island(() => import('./X'), { name: 'X', hydrate: 'never' })
+ *
+ * Edge cases the AST-walker deliberately doesn't cover (unrecognized calls
+ * fall through and don't populate the set — false-negatives, not false
+ * positives):
+ *
+ *   - Loader is a variable, not an inline arrow
+ *   - Name is a variable / template / spread, not a string literal
+ *   - Options come from a spread (`island(loader, opts)`)
+ *
+ * The same rules apply on the registry side (`detectIslandNeverWithRegistry`):
+ * unrecognized keys won't match. Both halves are syntactic — a semantic
+ * cross-package audit lives in `pyreon doctor --check-islands` (separate PR).
+ */
+function collectNeverIslandNames(sf: ts.SourceFile): Set<string> {
+  const names = new Set<string>()
+  function walk(node: ts.Node): void {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'island' &&
+      node.arguments.length >= 2
+    ) {
+      const opts = node.arguments[1]
+      if (opts && ts.isObjectLiteralExpression(opts)) {
+        let nameVal: string | undefined
+        let hydrateVal: string | undefined
+        for (const prop of opts.properties) {
+          if (!ts.isPropertyAssignment(prop)) continue
+          const key = prop.name
+          const keyText = ts.isIdentifier(key)
+            ? key.text
+            : ts.isStringLiteral(key)
+              ? key.text
+              : ''
+          if (keyText === 'name' && ts.isStringLiteral(prop.initializer)) {
+            nameVal = prop.initializer.text
+          } else if (keyText === 'hydrate' && ts.isStringLiteral(prop.initializer)) {
+            hydrateVal = prop.initializer.text
+          }
+        }
+        if (nameVal && hydrateVal === 'never') {
+          names.add(nameVal)
+        }
+      }
+    }
+    ts.forEachChild(node, walk)
+  }
+  walk(sf)
+  return names
+}
+
+/**
+ * Flag entries in `hydrateIslands({ X: () => import('./X'), ... })` whose
+ * key matches an `island()` name declared with `hydrate: 'never'` in the
+ * same file. Each matching entry produces one diagnostic at the property's
+ * location so the IDE highlights exactly which key needs to go.
+ */
+function detectIslandNeverWithRegistry(ctx: DetectContext, node: ts.CallExpression): void {
+  if (ctx.neverIslandNames.size === 0) return
+  const callee = node.expression
+  if (!ts.isIdentifier(callee) || callee.text !== 'hydrateIslands') return
+  const arg = node.arguments[0]
+  if (!arg || !ts.isObjectLiteralExpression(arg)) return
+  for (const prop of arg.properties) {
+    if (!ts.isPropertyAssignment(prop) && !ts.isShorthandPropertyAssignment(prop)) continue
+    const key = prop.name
+    const keyText = ts.isIdentifier(key)
+      ? key.text
+      : ts.isStringLiteral(key)
+        ? key.text
+        : ''
+    if (!keyText || !ctx.neverIslandNames.has(keyText)) continue
+    pushDiag(
+      ctx,
+      prop,
+      'island-never-with-registry-entry',
+      `island "${keyText}" was declared with \`hydrate: 'never'\` and MUST NOT be registered in \`hydrateIslands({ ... })\`. The whole point of the \`'never'\` strategy is shipping zero client JS — registering pulls the component module into the client bundle graph (the runtime short-circuits never-strategy before the registry lookup, but the bundler still includes the import). Drop this entry; the framework handles never-strategy islands at SSR with no client-side wiring.`,
+      getNodeText(ctx, prop),
+      `// remove the "${keyText}" entry — never-strategy islands need no registry entry`,
+      false,
+    )
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // Visitor
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -674,6 +793,7 @@ function visitNode(ctx: DetectContext, node: ts.Node): void {
     detectEmptyTheme(ctx, node)
     detectRawEventListener(ctx, node)
     detectSignalWriteAsCall(ctx, node)
+    detectIslandNeverWithRegistry(ctx, node)
   }
   if (ts.isJsxAttribute(node)) {
     detectOnClickUndefined(ctx, node)
@@ -701,6 +821,7 @@ export function detectPyreonPatterns(code: string, filename = 'input.tsx'): Pyre
     code,
     diagnostics: [],
     signalBindings: collectSignalBindings(sf),
+    neverIslandNames: collectNeverIslandNames(sf),
   }
   visit(ctx, sf)
   // Sort by (line, column) for stable ordering when multiple patterns fire.
@@ -723,6 +844,11 @@ export function hasPyreonPatterns(code: string): boolean {
     // static-return-null-conditional: `if (...) return null` anywhere
     /\bif\s*\([^)]+\)\s*\{?\s*return\s+null\b/.test(code) ||
     // as-unknown-as-vnodechild
-    /\bas\s+unknown\s+as\s+VNodeChild\b/.test(code)
+    /\bas\s+unknown\s+as\s+VNodeChild\b/.test(code) ||
+    // island-never-with-registry-entry: a never-strategy declaration AND a
+    // hydrateIslands call must both appear in the same source for the bug
+    // shape to trigger. Pre-filter on EITHER half — the AST walker fast-
+    // exits when the never-island set is empty.
+    (/\bisland\s*\(/.test(code) && /\bhydrate\s*:\s*['"]never['"]/.test(code))
   )
 }