@lingfan-engine/stories-build 0.0.0-stage → 0.1.2

package/src/const-eval/round/evaluate.ts

@@ -0,0 +1,149 @@
+/**
+ * 单轮求值：worker 生命周期（超时/错误兜底）与打包/执行结果翻译成诊断。
+ */
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+import type { CompilerDiagnostic } from "../../compiler/index.ts";
+import type {
+  ConstEvalResult,
+  DefineCall,
+  DefineBad,
+  JsonValue,
+} from "../contracts.ts";
+import { locateExport } from "../diag/index.ts";
+import { WORKER_SOURCE } from "./source.ts";
+
+interface WorkerExportsMessage {
+  kind: "exports";
+  values: Record<string, unknown>;
+  bad: { key: string; reason: string }[];
+  defineCalls: DefineCall[];
+  defineBad: DefineBad[];
+}
+interface WorkerEsbuildMessage {
+  kind: "esbuild-error";
+  diags: CompilerDiagnostic[];
+}
+interface WorkerRuntimeMessage {
+  kind: "runtime-error";
+  message: string;
+}
+type WorkerOutcome =
+  | WorkerExportsMessage
+  | WorkerEsbuildMessage
+  | WorkerRuntimeMessage
+  | { kind: "timeout" };
+
+export async function evaluateOnce(
+  absEntry: string,
+  esbuildPath: string,
+  timeoutMs: number,
+): Promise<ConstEvalResult> {
+  const outcome = await runWorkerRound({
+    entry: absEntry,
+    esbuildPath,
+    workDir: path.dirname(absEntry),
+    timeoutMs,
+  });
+
+  switch (outcome.kind) {
+    case "exports": {
+      if (outcome.bad.length > 0) {
+        return {
+          diags: outcome.bad.map((item) => {
+            const at = locateExport(absEntry, item.key);
+            return {
+              file: absEntry,
+              line: at.line,
+              col: at.col,
+              message: `导出 "${item.key}" 非 JSON 可序列化（${item.reason}）——编译期求值产物仅取 JSON 可序列化值`,
+            };
+          }),
+        };
+      }
+      if (outcome.defineBad.length > 0) {
+        return {
+          diags: outcome.defineBad.map((item) => ({
+            file: absEntry,
+            line: 1,
+            col: 1,
+            message: `define("${item.path}")：${item.reason}——define 值文法与 state 同规（仅 JSON 可序列化值；函数/undefined/symbol/bigint 拒）`,
+          })),
+        };
+      }
+      // worker 分类已保证 JSON 安全，边界处收窄类型
+      return {
+        values: outcome.values as Record<string, JsonValue>,
+        defineCalls: outcome.defineCalls,
+      };
+    }
+    case "esbuild-error":
+      return { diags: outcome.diags };
+    case "runtime-error":
+      return {
+        diags: [
+          {
+            file: absEntry,
+            line: 1,
+            col: 1,
+            message: `编译期求值失败：模块顶层执行抛错 —— ${outcome.message}`,
+          },
+        ],
+      };
+    case "timeout":
+      return {
+        diags: [
+          {
+            file: absEntry,
+            line: 1,
+            col: 1,
+            message: `编译期求值超时（>${timeoutMs}ms）——模块顶层代码未在时限内完成求值`,
+          },
+        ],
+      };
+  }
+}
+
+function runWorkerRound(data: {
+  entry: string;
+  esbuildPath: string;
+  workDir: string;
+  timeoutMs: number;
+}): Promise<WorkerOutcome> {
+  return new Promise((resolve) => {
+    const worker = new Worker(WORKER_SOURCE, { eval: true, workerData: data });
+    let settled = false;
+    const finish = (outcome: WorkerOutcome): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      void worker.terminate();
+      resolve(outcome);
+    };
+    const timer = setTimeout(() => finish({ kind: "timeout" }), data.timeoutMs);
+    worker.on("message", (message: { kind?: unknown }) => {
+      if (
+        message !== null &&
+        typeof message === "object" &&
+        typeof message.kind === "string"
+      ) {
+        finish(message as WorkerOutcome);
+      } else {
+        finish({ kind: "runtime-error", message: "worker 返回了未知消息形态" });
+      }
+    });
+    worker.on("error", (error: unknown) => {
+      finish({
+        kind: "runtime-error",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    });
+    worker.on("exit", (code: number) => {
+      if (!settled)
+        finish({
+          kind: "runtime-error",
+          message: `worker 异常退出（exit code ${code}）`,
+        });
+    });
+  });
+}

package/src/const-eval/round/index.ts

@@ -0,0 +1,4 @@
+/**
+ * const-eval worker 轮次出口（具名转发，不用 `export *`）。
+ */
+export { evaluateOnce } from "./evaluate.ts";

package/src/const-eval/round/source.ts

@@ -0,0 +1,134 @@
+/**
+ * worker 源码模板：`String.raw` + 文件内无 `$` 插值起点，搬迁时内容必须逐字保持。
+ */
+export const WORKER_SOURCE = String.raw`
+const { parentPort, workerData } = require("node:worker_threads");
+const { createRequire } = require("node:module");
+const path = require("node:path");
+
+/** 返回 null = JSON 可序列化；否则返回不可序列化原因。 */
+function classify(value, seen) {
+  if (value === undefined) return "undefined";
+  if (value === null || typeof value === "string" || typeof value === "boolean") return null;
+  if (typeof value === "number") return Number.isFinite(value) ? null : "非有限数值（NaN/Infinity）";
+  if (typeof value === "function") return "函数（function）";
+  if (typeof value === "bigint") return "bigint";
+  if (typeof value === "symbol") return "symbol";
+  if (typeof value !== "object") return "不可序列化类型（" + String(typeof value) + "）";
+  if (seen.has(value)) return "循环引用";
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        if (!(i in value)) return "数组空洞（undefined 元素）";
+        const element = classify(value[i], seen);
+        if (element !== null) return element;
+      }
+      return null;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+      const name = (proto.constructor && proto.constructor.name) || "unknown";
+      return "非普通对象（" + name + " 实例：Date/Map/Set/class 等不保证可序列化）";
+    }
+    for (const key of Object.keys(value)) {
+      const member = classify(value[key], seen);
+      if (member !== null) return member;
+    }
+    return null;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+(async () => {
+  try {
+    const requireEsbuild = createRequire(workerData.esbuildPath);
+    const esbuild = requireEsbuild(workerData.esbuildPath);
+    const result = await esbuild.build({
+      entryPoints: [workerData.entry],
+      bundle: true,
+      write: false,
+      format: "cjs",
+      platform: "node",
+      logLevel: "silent",
+      absWorkingDir: workerData.workDir,
+    });
+    const code = result.outputFiles[0].text;
+
+    const moduleObj = { exports: {} };
+    const runRequire = createRequire(workerData.entry);
+
+    // define / defineVars：config.ts 构建期内建（求值环境注入，无运行时实体）。
+    // define 二态：字符串首参 = 点路径单值；普通对象首参 = 子树声明；值过 classify
+    // 才入列（非法值进 defineBad，由求值段翻成诊断）。defineVars 返回实参本身，
+    // 使 export const vars = defineVars({...}) 的导出值 = 键集对象（vars 键来源）。
+    const defineCalls = [];
+    const defineBad = [];
+    function define(pathOrSpec, value) {
+      if (typeof pathOrSpec === "string") {
+        const reason = classify(value, new Set());
+        if (reason !== null) {
+          defineBad.push({ path: pathOrSpec, reason: "值不可序列化（" + reason + "）" });
+          return;
+        }
+        defineCalls.push({ kind: "path", path: pathOrSpec, value: value });
+        return;
+      }
+      if (pathOrSpec !== null && typeof pathOrSpec === "object" && !Array.isArray(pathOrSpec)) {
+        const reason = classify(pathOrSpec, new Set());
+        if (reason !== null) {
+          defineBad.push({ path: "(对象实参)", reason: "对象实参不可序列化（" + reason + "）" });
+          return;
+        }
+        defineCalls.push({ kind: "spec", spec: pathOrSpec });
+        return;
+      }
+      defineBad.push({ path: "(实参)", reason: "首参须为点路径字符串或对象字面量" });
+    }
+    function defineVars(spec) {
+      return spec;
+    }
+
+    const factory = new Function(
+      "module",
+      "exports",
+      "require",
+      "__filename",
+      "__dirname",
+      "define",
+      "defineVars",
+      code,
+    );
+    factory(moduleObj, moduleObj.exports, runRequire, workerData.entry, path.dirname(workerData.entry), define, defineVars);
+    try { delete moduleObj.exports.__esModule; } catch { /* 不可删则忽略 */ }
+
+    const values = {};
+    const bad = [];
+    for (const key of Object.keys(moduleObj.exports)) {
+      const reason = classify(moduleObj.exports[key], new Set());
+      if (reason === null) values[key] = moduleObj.exports[key];
+      else bad.push({ key, reason });
+    }
+    parentPort.postMessage({ kind: "exports", values, bad, defineCalls, defineBad });
+  } catch (error) {
+    if (error !== null && typeof error === "object" && Array.isArray(error.errors)) {
+      const diags = error.errors.map((item) => {
+        const at = item.location ?? null;
+        return {
+          file: (at && at.file) || workerData.entry,
+          line: (at && at.line) || 1,
+          col: ((at && at.column) ?? 0) + 1,
+          message: item.text ?? String(item),
+        };
+      });
+      parentPort.postMessage({ kind: "esbuild-error", diags });
+      return;
+    }
+    parentPort.postMessage({
+      kind: "runtime-error",
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+})();
+`;

package/src/const-eval/state-schema.ts

@@ -0,0 +1,269 @@
+/**
+ * state 降维段（编排层）：把状态初始声明递归降维成扁平点路径 defines
+ * （引擎初始化通道，session 无条件 Set，零引擎改动），经 mergeDefines 并入工程 defines。
+ *
+ * 输入双形态（二选一，由 config 求值段保证互斥；皆缺省 = 无 schema 贡献）：
+ * - 形态 A：`config.state` 导出的嵌套树；
+ * - 形态 B：define() 调用合并出的纯嵌套树（config-eval/define-merge 的产物）。
+ * 两棵树走同一条降维文法（合流点唯一），本段自身不再读文件、不再求值。
+ *
+ * 降维文法（与包出口的 InferStateSchema 一一对应）：
+ * - 嵌套对象递归拼接点路径（源形态只有嵌套一种，点路径键 fail-closed）；descriptor
+ *   { type, default } 取 default；
+ * - descriptor type ∈ "number"|"string"|"boolean" | 枚举对象（值全为 string|number）|
+ *   单元素数组 [leaf]，default 与 type 做一致性校验；多元素数组 = 成员槽位并集
+ *   （成员：保留字标量/枚举对象/null/[leaf]/嵌套并集；default 须落在至少一个成员
+ *   值域内，未知成员 fail-closed 一次报全部）；
+ * - 形态非法 fail-closed（一次报全部）；值形态无法保留源位置，诊断统一挂
+ *   `config.ts:1:1`，以键路径上下文定位。
+ */
+import { CONFIG_FILE } from "../config/story-config.ts";
+import { StoryBuildError } from "../shared/index.ts";
+
+const PRIMITIVE_TYPES: ReadonlySet<string> = new Set([
+  "number",
+  "string",
+  "boolean",
+]);
+
+/**
+ * 把 config 求值产物（形态 A 的 state 树 / 形态 B 的 define 合并树）降维为扁平 defines。
+ * 同步纯函数：求值已在上游完成，此处只做文法校验与展平。
+ */
+export function runStateSchemaPass(
+  stateTree: unknown,
+  defineTree: Record<string, unknown>,
+  sourcesDirName: string,
+): Record<string, unknown> {
+  const origin = { line: 1, col: 1 };
+  const errors: string[] = [];
+  const defines: Record<string, unknown> = {};
+  if (stateTree !== undefined)
+    flattenRoot(stateTree, defines, errors, origin, "state");
+  flattenRoot(defineTree, defines, errors, origin, "define");
+  if (errors.length > 0) {
+    throw new StoryBuildError(
+      `state schema 降维失败（${errors.length} 条）：\n${errors
+        .map(
+          (message) =>
+            `- ${sourcesDirName}/${CONFIG_FILE}:${origin.line}:${origin.col} ${message}`,
+        )
+        .join("\n")}`,
+    );
+  }
+  return defines;
+}
+
+function flattenRoot(
+  schema: unknown,
+  out: Record<string, unknown>,
+  errors: string[],
+  origin: { line: number; col: number },
+  rootLabel: string,
+): void {
+  if (!isPlainObject(schema)) {
+    errors.push(`${rootLabel} 根必须是键集对象`);
+    return;
+  }
+  for (const [key, value] of Object.entries(schema)) {
+    if (key.includes(".")) {
+      errors.push(dotKeyError(key));
+      continue;
+    }
+    flattenValue(value, key, out, errors, origin);
+  }
+}
+
+/** 点路径键统一拒绝：扁平 defines 键由降维展平产生，源形态只有嵌套一种。 */
+const dotKeyError = (key: string): string =>
+  `${key}：点路径键不支持（源形态统一纯嵌套对象，扁平 defines 键由降维展平产生）`;
+
+function flattenValue(
+  value: unknown,
+  path: string,
+  out: Record<string, unknown>,
+  errors: string[],
+  origin: { line: number; col: number },
+): void {
+  if (isPlainObject(value)) {
+    if ("type" in value || "default" in value) {
+      if (validateDescriptor(value, path, errors)) out[path] = value.default;
+      return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+      if (key.includes(".")) {
+        errors.push(dotKeyError(`${path}.${key}`));
+        continue;
+      }
+      flattenValue(child, `${path}.${key}`, out, errors, origin);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    errors.push(
+      `${path}：数组值请用 descriptor { type: [leaf], default: [...] }`,
+    );
+    return;
+  }
+  if (
+    value === undefined ||
+    typeof value === "function" ||
+    typeof value === "symbol" ||
+    typeof value === "bigint"
+  ) {
+    errors.push(`${path}：不可序列化的 schema 值`);
+    return;
+  }
+  out[path] = value;
+}
+
+/**
+ * 校验 descriptor；返回 true 表示合法（default 已随之写入 defines）。
+ * 诊断文本只带路径不带行列（`config.ts` 的挂点在整条消息末尾统一给出），
+ * 所以这里不收 origin——多一个用不上的参数只会让调用方以为它能定位。
+ */
+function validateDescriptor(
+  descriptor: Record<string, unknown>,
+  path: string,
+  errors: string[],
+): boolean {
+  if (!("default" in descriptor)) {
+    errors.push(`${path}：descriptor 缺 default`);
+    return false;
+  }
+  const type = descriptor.type;
+  const def = descriptor.default;
+  if (typeof type === "string" && PRIMITIVE_TYPES.has(type)) {
+    const ok =
+      (type === "number" && typeof def === "number" && Number.isFinite(def)) ||
+      (type === "string" && typeof def === "string") ||
+      (type === "boolean" && typeof def === "boolean");
+    if (!ok)
+      errors.push(`${path}：descriptor type "${type}" 与 default 不一致`);
+    return ok;
+  }
+  if (Array.isArray(type)) {
+    if (type.length >= 2) return validateUnion(type, def, path, errors);
+    if (type.length !== 1) {
+      errors.push(
+        `${path}：数组 descriptor 的 type 不能为空数组（单元素 [leaf] 或多元素并集）`,
+      );
+      return false;
+    }
+    if (!Array.isArray(def)) {
+      errors.push(`${path}：数组 descriptor 的 default 必须是数组`);
+      return false;
+    }
+    const bad = def.filter((element) => !leafMatches(type[0], element)).length;
+    if (bad > 0)
+      errors.push(`${path}：数组 default 有 ${bad} 个元素与 leaf 类型不一致`);
+    return bad === 0;
+  }
+  const enumValues = asEnumValues(type);
+  if (enumValues !== undefined) {
+    if (
+      (typeof def !== "string" && typeof def !== "number") ||
+      !enumValues.includes(def)
+    ) {
+      errors.push(`${path}：descriptor default 不在枚举值域内`);
+      return false;
+    }
+    return true;
+  }
+  errors.push(`${path}：无法识别的 descriptor type`);
+  return false;
+}
+
+function leafMatches(leaf: unknown, value: unknown): boolean {
+  if (typeof leaf === "string" && PRIMITIVE_TYPES.has(leaf)) {
+    return (
+      (leaf === "number" &&
+        typeof value === "number" &&
+        Number.isFinite(value)) ||
+      (leaf === "string" && typeof value === "string") ||
+      (leaf === "boolean" && typeof value === "boolean")
+    );
+  }
+  const enumValues = asEnumValues(leaf);
+  return (
+    enumValues !== undefined &&
+    (typeof value === "string" || typeof value === "number") &&
+    enumValues.includes(value)
+  );
+}
+
+/**
+ * 并集成员槽位校验（type 为多元素数组）：逐成员按文法归类，未知成员
+ * fail-closed 一次报全部；default 落在至少一个成员值域内即合法。
+ */
+function validateUnion(
+  members: readonly unknown[],
+  def: unknown,
+  path: string,
+  errors: string[],
+): boolean {
+  let unknownCount = 0;
+  members.forEach((member, index) => {
+    if (isKnownUnionMember(member)) return;
+    errors.push(
+      `${path}：并集第 ${index + 1} 个成员无法识别（只允许 "number"/"string"/"boolean"、枚举对象、null 与 [leaf]）`,
+    );
+    unknownCount += 1;
+  });
+  if (unknownCount > 0) return false;
+  if (members.some((member) => unionMatches(member, def))) return true;
+  errors.push(`${path}：descriptor default 不在并集值域内`);
+  return false;
+}
+
+/** 并集成员文法判定：null / 保留字标量 / 枚举对象 / [leaf] / 嵌套并集（递归）。 */
+function isKnownUnionMember(member: unknown): boolean {
+  if (member === null) return true;
+  if (typeof member === "string") return PRIMITIVE_TYPES.has(member);
+  if (Array.isArray(member)) {
+    if (member.length === 1) return isValidLeaf(member[0]);
+    return member.every(isKnownUnionMember);
+  }
+  return asEnumValues(member) !== undefined;
+}
+
+/** default 是否落在单个并集成员的值域内（与 isKnownUnionMember 同构逐分支匹配）。 */
+function unionMatches(member: unknown, value: unknown): boolean {
+  if (member === null) return value === null;
+  if (typeof member === "string" && PRIMITIVE_TYPES.has(member))
+    return leafMatches(member, value);
+  if (Array.isArray(member)) {
+    if (member.length === 1)
+      return (
+        Array.isArray(value) &&
+        value.every((element) => leafMatches(member[0], element))
+      );
+    return member.some((nested) => unionMatches(nested, value));
+  }
+  const enumValues = asEnumValues(member);
+  return (
+    enumValues !== undefined &&
+    (typeof value === "string" || typeof value === "number") &&
+    enumValues.includes(value)
+  );
+}
+
+/** leaf 槽位是否合法（保留字标量或枚举对象）——并集数组成员复用。 */
+function isValidLeaf(leaf: unknown): boolean {
+  if (typeof leaf === "string" && PRIMITIVE_TYPES.has(leaf)) return true;
+  return asEnumValues(leaf) !== undefined;
+}
+
+/** 枚举对象判定：非空普通对象且值全为 string|number（descriptor 不落此形——type 槽位专用）。 */
+function asEnumValues(value: unknown): (string | number)[] | undefined {
+  if (!isPlainObject(value)) return undefined;
+  const values = Object.values(value);
+  if (values.length === 0) return undefined;
+  return values.every((v) => typeof v === "string" || typeof v === "number")
+    ? (values as (string | number)[])
+    : undefined;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/discovery/index.ts

@@ -0,0 +1,7 @@
+/**
+ * 源发现域：把 `Stories.src` 按 folders 声明扫成待编译清单。
+ *
+ * 这一域只负责「哪些文件算数、入口是哪个、有没有漏登记的 default 导出」，
+ * 不碰编译也不碰写盘——那些在各目的域里。
+ */
+export { discoverSources, type DiscoveredSources } from "./source-discovery.ts";