@dimina-kit/compiler 0.0.1-dev.20260706064107 → 0.0.1-dev.20260706131625

package/README.md

@@ -160,17 +160,19 @@ Node 宿主（Electron devtools、CLI watch 服务等）用这个导出替代直
 
 dmcc 每次 `build()` 都新建 3 个 worker_threads、编完销毁，每次重编都要重新加载 sass/postcss/esbuild/oxc 并重启 esbuild 服务进程；本 pool 只在第一次付这笔钱。实测 watch 热重编（`dimina/fe/example` 全部 5 个 demo）比 dmcc 快 1.6–4×（base 826→207ms、weui 2716→763ms）；冷启动略慢于 dmcc（3 个 worker 首次加载 bundle），"打开一次、保存无数次"的 devtools 场景下净赚。数据与方法见 [`docs/compile-fs-experiments.md`](./docs/compile-fs-experiments.md)。
 
-**dmcc drop-in（默认导出）**——签名、返回值、日志面貌与 dmcc `build()` 一致，宿主原有的日志抓取（`✔ 输出编译产物` / `✖ <stage>` / `<workPath> 编译出错:`）不用改：
+**dmcc drop-in（默认导出）**——签名、成功返回值、日志面貌与 dmcc `build()` 一致，宿主原有的日志抓取（`✔ 输出编译产物` / `✖ <stage>` / `<workPath> 编译出错:`）不用改。**错误路径与 dmcc 刻意分歧：编译失败会 reject**（dmcc 吞错 resolve undefined，失败编译与"无 app 信息"从此不可区分，宿主会带着兜底 appId 启动一个只能 404 的会话）——失败时先照旧把 `✖ <stage>` + `编译出错:` 打到 stderr，再把错误抛给调用方：
 
 ```js
 import build from '@dimina-kit/compiler/pool-node'
 
 // 首次调用起常驻 worker,后续调用(watch 重编)复用
 const appInfo = await build(outputDir, workPath, true, { sourcemap: true, fileTypes })
-// 成功 → { appId, name, path };失败 → undefined(错误已打到 stderr,同 dmcc)
+// 成功 → { appId, name, path };编译失败 → reject(错误同时已打到 stderr,日志面貌同 dmcc)
 ```
 
-配套导出：`warmDefaultPool()` 提前创建这个 singleton 池并拉起 stage worker（不 build、无输出，项目无关——热备胎宿主在没有项目打开时调用,让第一次真实 build 从热池起步）；`disposeDefaultPool()` 显式回收。
+配套导出：`warmDefaultPool()` 提前创建这个 singleton 池并拉起 stage worker（不 build、无输出，项目无关——热备胎宿主在没有项目打开时调用,让第一次真实 build 从热池起步）；`disposeDefaultPool()` 显式回收；`oxcNativeBindingHint(message)` 把 oxc-parser 的 "Cannot find native binding" 报错映射成打包提示（其他消息返回 null）——stage 失败的 reject message 命中时会自动附带这条提示。
+
+> **Electron 打包分发注意（oxc-parser 运行时绑定）**：Node 编译路径依赖 oxc-parser，其运行时需要 `@oxc-parser/binding-<platform>-<arch>`（平台原生 `.node`）或 `@oxc-parser/binding-wasm32-wasi`（wasm 兜底）**二者之一实际存在于分发包内**。它们都不是宿主的直接依赖，electron-builder 等工具收集依赖时容易丢——丢了之后每次编译都在 logic stage 报 `Cannot find native binding`。宿主打包时请把其中一个显式声明为自己的 dependency（或在打包配置里强制收集）。
 
 **结构化用法（`createNodeCompilerPool`）**——要抛错误对象、显式回收 worker 时用：
 

package/dist/pool.node.js

@@ -248,7 +248,9 @@ function createNodeCompilerPool({
     for (const r of results) {
       if (!r || r.type === "error") {
         const info = r && r.error;
-        const err = new Error(`[compiler] stage "${r && r.stage}" failed: ${info && info.message || "unknown error"}`);
+        const cause = info && info.message || "unknown error";
+        const hint = oxcNativeBindingHint(cause);
+        const err = new Error(`[compiler] stage "${r && r.stage}" failed: ${cause}${hint ? ` \u2014 ${hint}` : ""}`);
         if (info && info.stack) err.stack = info.stack;
         err.stage = r && r.stage;
         err.code = "compiler-stage-error";
@@ -297,6 +299,10 @@ function createNodeCompilerPool({
   return { build: build2, dispose, stages, _slots: workers };
 }
 var STAGE_TITLES = { logic: "\u7F16\u8BD1\u9875\u9762\u903B\u8F91", view: "\u7F16\u8BD1\u9875\u9762\u6587\u4EF6", style: "\u7F16\u8BD1\u6837\u5F0F\u6587\u4EF6" };
+function oxcNativeBindingHint(message) {
+  if (!/Cannot find native binding/i.test(String(message))) return null;
+  return `oxc-parser \u7684\u8FD0\u884C\u65F6\u7ED1\u5B9A\u6CA1\u6709\u88AB\u6253\u8FDB\u5BBF\u4E3B\u5E94\u7528\uFF1A@dimina-kit/compiler \u7684 Node \u7F16\u8BD1\u8DEF\u5F84\u9700\u8981 @oxc-parser/binding-${process.platform}-${process.arch}\uFF08\u5E73\u53F0\u539F\u751F\u7ED1\u5B9A\uFF09\u6216 @oxc-parser/binding-wasm32-wasi\uFF08wasm \u515C\u5E95\uFF09\u4E8C\u8005\u4E4B\u4E00\u5B9E\u9645\u5B58\u5728\u4E8E\u5305\u5185\u3002\u6253\u5305\u5206\u53D1\uFF08\u5982 electron-builder\uFF09\u65F6\u8BF7\u628A\u5176\u4E2D\u4E00\u4E2A\u663E\u5F0F\u58F0\u660E\u4E3A\u5BBF\u4E3B\u4F9D\u8D56\uFF0C\u907F\u514D\u4F9D\u8D56\u6536\u96C6\u65F6\u88AB\u4E22\u5F03`;
+}
 var singleton = null;
 async function build(outputDir, workPath, useAppIdDir = true, options = {}) {
   if (!singleton) singleton = createNodeCompilerPool();
@@ -307,7 +313,7 @@ async function build(outputDir, workPath, useAppIdDir = true, options = {}) {
   } catch (e) {
     if (e && e.stage) console.error(`\u2716 ${STAGE_TITLES[e.stage] || e.stage}`);
     console.error(`${workPath} \u7F16\u8BD1\u51FA\u9519: ${e && e.message}`);
-    return void 0;
+    throw e;
   }
 }
 async function warmDefaultPool() {
@@ -325,5 +331,6 @@ export {
   createNodeCompilerPool,
   build as default,
   disposeDefaultPool,
+  oxcNativeBindingHint,
   warmDefaultPool
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/compiler",
-  "version": "0.0.1-dev.20260706064107",
+  "version": "0.0.1-dev.20260706131625",
   "description": "dmcc compiler bundles (browser + node) that drive @dimina/compiler against a caller-injected node:fs replacement (no bundled fs)",
   "license": "MIT",
   "type": "module",

package/scripts/test-pool-node.js

@@ -8,7 +8,7 @@
 // and require our pool to match dmcc only where dmcc matches itself. Assets (uuid-named)
 // are matched by CONTENT hash multiset instead of name. Sourcemap is asserted against
 // dmcc's own map (parity), since that is the format devtools already consumes.
-import { readdirSync, readFileSync, statSync, rmSync, mkdirSync } from 'node:fs'
+import { readdirSync, readFileSync, statSync, rmSync, mkdirSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { createHash } from 'node:crypto'
 import path from 'node:path'
@@ -42,7 +42,12 @@ function readTree(root) {
 }
 
 const dmccBuild = (await import('../../../dimina/fe/packages/compiler/src/index.js')).default
-const { createNodeCompilerPool } = await import('../dist/pool.node.js')
+const poolNodeModule = await import('../dist/pool.node.js')
+const { createNodeCompilerPool } = poolNodeModule
+// Destructured lazily below (may be absent pre-fix): the default drop-in build(),
+// the pure oxc-native-binding-hint mapper, and the lazy-singleton disposer.
+const defaultBuild = poolNodeModule.default
+const { oxcNativeBindingHint, disposeDefaultPool } = poolNodeModule
 
 // --- reference: dmcc twice ------------------------------------------------
 console.log(`[ref] dmcc build ×2 (sourcemap) from ${APP}`)
@@ -113,5 +118,90 @@ checkAgainstDmcc(readTree(path.join(dir('ours1'), appInfo1.appId)), 'cold')
 checkAgainstDmcc(readTree(path.join(dir('ours2'), appInfo2.appId)), 'warm')
 
 console.log(`[sourcemap] logic.js.map: ${refMap.sources.length} sources, sourcesContent present, matches dmcc ✅`)
-console.log(failed ? '\n❌ FAIL' : '\n✅ PASS: resident Node pool is dmcc-equivalent (incl. sourcemap) on cold+warm builds')
+
+// --- failure contract: the default drop-in build() must REJECT a broken compile ------------------
+// (never resolve undefined and let the caller mistake a failed compile for success), and the pool
+// must expose a pure helper that turns a missing-oxc-native-binding message into an actionable
+// packaging hint (checked as a string mapping only — a real environment can't be made to lack the
+// binding on demand).
+console.log("[fail] broken fixture: default build() must reject, not resolve undefined")
+function writeBrokenFixture(root) {
+  const write = (rel, content) => {
+    const target = path.join(root, rel)
+    mkdirSync(path.dirname(target), { recursive: true })
+    writeFileSync(target, content)
+  }
+  write('project.config.json', JSON.stringify({ appid: 'fixture_app_broken', projectname: 'fixture-broken' }))
+  write('app.json', JSON.stringify({ pages: ['pages/index/index'] }))
+  write('app.js', 'App({})\n')
+  write('app.wxss', 'page { font-size: 14px; }\n')
+  write('pages/index/index.json', '{}\n')
+  // Unbalanced brace + bad tokens — same corruption shape used by devkit's
+  // open-project-compile-log fixture, chosen because it fails the logic stage
+  // rather than being silently absorbed by esbuild's error-tolerant fallback.
+  write('pages/index/index.js', 'Page({ data: { msg: "hi" } })\nconst broken = {{{ ;;; <<<\n')
+  write('pages/index/index.wxml', '<view>{{msg}}</view>\n')
+  write('pages/index/index.wxss', '.x { color: red; }\n')
+}
+const brokenRoot = dir('broken-fixture')
+mkdirSync(brokenRoot, { recursive: true })
+writeBrokenFixture(brokenRoot)
+
+if (typeof defaultBuild !== 'function') {
+  fail('pool.node.js must have a default export `build(outputDir, workPath, useAppIdDir?, options?)` — default export is missing/not a function')
+}
+else {
+  let brokenResolvedValue
+  let brokenRejectedError
+  try {
+    brokenResolvedValue = await defaultBuild(dir('broken-out'), brokenRoot, true, {})
+  }
+  catch (e) {
+    brokenRejectedError = e
+  }
+  if (brokenRejectedError === undefined) {
+    fail(`default build() must REJECT on a broken compile — instead it resolved to ${JSON.stringify(brokenResolvedValue)} (a swallowed error looks like success to every caller)`)
+  }
+  else if (!(brokenRejectedError instanceof Error) || !brokenRejectedError.message) {
+    fail(`default build() rejected but without a usable Error message: ${brokenRejectedError}`)
+  }
+  else if (!/stage "logic" failed/.test(brokenRejectedError.message)) {
+    fail(`default build() rejection message must name the failing stage, got: ${brokenRejectedError.message.split('\n')[0]}`)
+  }
+  else if (!/Transform failed/.test(brokenRejectedError.message)) {
+    fail(`default build() rejection message must carry the underlying compile reason (esbuild transform failure), got: ${brokenRejectedError.message.split('\n')[0]}`)
+  }
+  else {
+    console.log(`[fail] ✅ default build() rejected with: ${brokenRejectedError.message.split('\n')[0]}`)
+  }
+}
+
+// --- oxcNativeBindingHint: pure message -> actionable-packaging-hint mapper -----------------------
+if (typeof oxcNativeBindingHint !== 'function') {
+  fail('pool.node.js must export a named `oxcNativeBindingHint(message)` helper — export is missing')
+}
+else {
+  const hint = oxcNativeBindingHint('Cannot find native binding. It means oxc-parser was not installed correctly for this platform.')
+  if (typeof hint !== 'string' || !hint.includes('@oxc-parser/binding-') || !hint.includes('wasm32-wasi')) {
+    fail(`oxcNativeBindingHint must mention both the native platform binding package (@oxc-parser/binding-*) and the wasm32-wasi fallback, got: ${JSON.stringify(hint)}`)
+  }
+  else {
+    console.log('[fail] ✅ oxcNativeBindingHint surfaces a packaging fix for a missing native binding')
+  }
+  const noHint = oxcNativeBindingHint('some unrelated compile error')
+  if (noHint !== null) {
+    fail(`oxcNativeBindingHint must return null for a message that is not the native-binding failure, got: ${JSON.stringify(noHint)}`)
+  }
+}
+
+// The default export is a lazy module-level singleton pool (resident worker threads) — the
+// broken-fixture build above spun it up, so the process cannot exit cleanly without disposing it.
+if (typeof disposeDefaultPool !== 'function') {
+  fail('pool.node.js must export `disposeDefaultPool()` to tear down the lazy default-export singleton pool')
+}
+else {
+  await disposeDefaultPool()
+}
+
+console.log(failed ? '\n❌ FAIL' : '\n✅ PASS: resident Node pool is dmcc-equivalent (incl. sourcemap) on cold+warm builds, and rejects broken compiles')
 process.exit(failed ? 1 : 0)

package/src/pool-node.js

@@ -167,7 +167,9 @@ export function createNodeCompilerPool({
     for (const r of results) {
       if (!r || r.type === 'error') {
         const info = r && r.error
-        const err = new Error(`[compiler] stage "${r && r.stage}" failed: ${(info && info.message) || 'unknown error'}`)
+        const cause = (info && info.message) || 'unknown error'
+        const hint = oxcNativeBindingHint(cause)
+        const err = new Error(`[compiler] stage "${r && r.stage}" failed: ${cause}${hint ? ` — ${hint}` : ''}`)
         if (info && info.stack) err.stack = info.stack
         err.stage = r && r.stage
         err.code = 'compiler-stage-error' // worker-reported compile error — never retried
@@ -232,19 +234,40 @@ export function createNodeCompilerPool({
 // user-facing compile-log lines a host (e.g. devkit/devtools' log panel) already scrapes.
 const STAGE_TITLES = { logic: '编译页面逻辑', view: '编译页面文件', style: '编译样式文件' }
 
+/**
+ * Map a failure message to an actionable packaging hint when it is oxc-parser's
+ * "missing runtime binding" error (thrown when NEITHER the platform-native
+ * `@oxc-parser/binding-<platform>` package NOR the `@oxc-parser/binding-wasm32-wasi`
+ * fallback resolves at runtime). Neither package is a direct dependency of a
+ * typical host, so app bundlers (e.g. electron-builder's dependency collection)
+ * silently drop them — and the raw oxc message says nothing about packaging.
+ * Returns null for every other message.
+ * @param {string} message
+ * @returns {string | null}
+ */
+export function oxcNativeBindingHint(message) {
+  if (!/Cannot find native binding/i.test(String(message))) return null
+  return 'oxc-parser 的运行时绑定没有被打进宿主应用：@dimina-kit/compiler 的 Node 编译路径需要 '
+    + `@oxc-parser/binding-${process.platform}-${process.arch}（平台原生绑定）或 `
+    + '@oxc-parser/binding-wasm32-wasi（wasm 兜底）二者之一实际存在于包内。'
+    + '打包分发（如 electron-builder）时请把其中一个显式声明为宿主依赖，避免依赖收集时被丢弃'
+}
+
 // Lazy singleton pool — a DROP-IN replacement for dmcc's `build(targetPath, workPath,
-// useAppIdDir, options)`, matching its behavior on BOTH the happy and error paths so a
-// host that consumed dmcc keeps working unchanged:
+// useAppIdDir, options)` with ONE deliberate divergence on the error path:
 //   • the first call spins up the resident workers; every later call (a watch rebuild)
 //     reuses them warm;
 //   • on success it emits `✔ 输出编译产物` on stdout (dmcc's listr2 completion line — the
 //     pool has no listr2, so the equivalent user-facing line is surfaced here);
-//   • on failure it reports the failing stage + summary on stderr and RESOLVES undefined
-//     (never rethrows), exactly like dmcc's build() catch (index.js) — the host normalizes
-//     undefined to a null appInfo and the error detail (incl. dmcc's own
-//     `[logic] esbuild 转换失败 …`) still reaches the log channel.
-// Callers that want structured throwing errors + explicit teardown should use
-// createNodeCompilerPool() directly instead.
+//   • on failure it reports the failing stage + summary on stderr (same lines a dmcc
+//     host already scrapes: `✖ <stage>` + `<workPath> 编译出错: …`) and then REJECTS
+//     with the error. dmcc's own build() swallows the error and resolves undefined,
+//     which makes a failed compile indistinguishable from benign "no app info" — a
+//     host would start a session that can only 404. Rejecting keeps the log surface
+//     identical while giving callers a real failure signal; a resolved null/undefined
+//     no longer means "compile failed", only "no app info to report".
+// Callers that want structured errors (`.stage`/`.code`) + explicit teardown should
+// use createNodeCompilerPool() directly instead.
 let singleton = null
 export default async function build(outputDir, workPath, useAppIdDir = true, options = {}) {
   if (!singleton) singleton = createNodeCompilerPool()
@@ -255,7 +278,7 @@ export default async function build(outputDir, workPath, useAppIdDir = true, opt
   } catch (e) {
     if (e && e.stage) console.error(`✖ ${STAGE_TITLES[e.stage] || e.stage}`)
     console.error(`${workPath} 编译出错: ${e && e.message}`)
-    return undefined
+    throw e
   }
 }