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

package/src/cell/scan-file.ts

@@ -0,0 +1,108 @@
+import * as ts from "typescript";
+import { checkFreeIdentifiers, collectFileImports, lineOf } from "./imports.ts";
+import type { CellIssue, FileImports } from "./types.ts";
+
+/** 沿成员/下标链下钻取最左标识符名（`cc.getInfo` → "cc"） */
+export function rootIdentifier(node: ts.Node): string | undefined {
+  let cursor: ts.Node = node;
+  while (
+    ts.isPropertyAccessExpression(cursor) ||
+    ts.isElementAccessExpression(cursor)
+  ) {
+    cursor = cursor.expression;
+  }
+  return ts.isIdentifier(cursor) ? cursor.text : undefined;
+}
+
+/**
+ * 单文件扫描：收集 `cell(...)` 调用（含校验），fail 项进 issues 不中断其它文件。
+ * 实现三形态之外的参数形态按各自文案 fail-closed——判定条件与文案逐字固定。
+ */
+export function scanFile(
+  relPath: string,
+  text: string,
+  globalWhitelist: ReadonlySet<string>,
+  issues: CellIssue[],
+): Array<{
+  name: string;
+  implText: string;
+  fingerprint: string;
+  imports: FileImports;
+}> {
+  const sf = ts.createSourceFile(relPath, text, ts.ScriptTarget.Latest, true);
+  const fromDir = relPath.includes("/")
+    ? relPath.slice(0, relPath.lastIndexOf("/"))
+    : "";
+  const fileImports = collectFileImports(sf, text, fromDir, issues, relPath);
+  const found: Array<{
+    name: string;
+    implText: string;
+    fingerprint: string;
+    imports: FileImports;
+  }> = [];
+  const origin = (node: ts.Node): string => `${relPath}:${lineOf(sf, node)}`;
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === "cell"
+    ) {
+      const [nameArg, implArg] = node.arguments;
+      if (nameArg === undefined || !ts.isStringLiteralLike(nameArg)) {
+        issues.push({
+          message:
+            'cell 第一个参数必须是字符串字面量名（如 cell("gold-non-negative", …)）',
+          origin: origin(node),
+        });
+      } else if (implArg === undefined) {
+        issues.push({
+          message: "cell 缺第二个参数（实现）",
+          origin: origin(node),
+        });
+      } else if (ts.isCallExpression(implArg)) {
+        issues.push({
+          message:
+            "cell 实现不支持调用表达式（参数固化属 L2）——改为函数字面量或引用导入的函数",
+          origin: origin(implArg),
+        });
+      } else if (
+        ts.isArrowFunction(implArg) ||
+        ts.isFunctionExpression(implArg)
+      ) {
+        const implText = text.slice(implArg.getStart(sf), implArg.getEnd());
+        checkFreeIdentifiers(
+          implArg,
+          origin(implArg),
+          fileImports.bindingNames,
+          globalWhitelist,
+          issues,
+        );
+        found.push({
+          name: nameArg.text,
+          implText,
+          fingerprint: implText.trim(),
+          imports: fileImports,
+        });
+      } else {
+        const root = rootIdentifier(implArg);
+        if (root === undefined || !fileImports.bindingNames.has(root)) {
+          issues.push({
+            message: `cell 引用形态的根标识符必须是本文件导入的绑定${root === undefined ? "" : `（收到 "${root}"，非导入绑定——本地绑定不搬运）`}`,
+            origin: origin(implArg),
+          });
+        } else {
+          const implText = text.slice(implArg.getStart(sf), implArg.getEnd());
+          found.push({
+            name: nameArg.text,
+            implText,
+            fingerprint: implText.trim(),
+            imports: fileImports,
+          });
+        }
+      }
+    }
+    node.forEachChild(visit);
+  };
+  visit(sf);
+  return found;
+}

package/src/cell/types.ts

@@ -0,0 +1,27 @@
+/** 提取产出（书写序；已按（注册面, 名字）+ 实现文本指纹去重） */
+export interface CellScan {
+  guards: ReadonlyArray<{ readonly name: string; readonly implText: string }>;
+  /** 生成物头部的 import 语句（说明符已按 gen/ 位置重写；跨文件去重，保序） */
+  importStatements: readonly string[];
+}
+
+/** 单条问题（origin = "相对路径:行"） */
+export interface CellIssue {
+  readonly message: string;
+  readonly origin: string;
+}
+
+/** cell 所在文件的 import 上下文：绑定名 + 重写后的语句文本 */
+export interface FileImports {
+  readonly bindingNames: ReadonlySet<string>;
+  readonly statements: ReadonlyArray<{
+    readonly adjustedText: string;
+    readonly bindings: readonly string[];
+  }>;
+}
+
+/** `scanCells` 的可配置项（整项缺省 = 内建默认值，调用方只给要覆盖的那一项） */
+export interface ScanCellsOptions {
+  /** 允许在内联实现里直接引用的全局名（缺省 = 标准全局白名单 16 项） */
+  readonly globalWhitelist?: ReadonlySet<string>;
+}

package/src/cell/whitelist.ts

@@ -0,0 +1,22 @@
+/**
+ * 标准全局白名单（字面量内允许直接引用；刻意最小——需要更多就走 import）。
+ * 16 项逐字固定；调用方要放开别的名字，经 `scanCells` 的 `globalWhitelist` 注入。
+ */
+export const DEFAULT_GLOBAL_WHITELIST: ReadonlySet<string> = new Set([
+  "JSON",
+  "Math",
+  "String",
+  "Number",
+  "Boolean",
+  "Object",
+  "Array",
+  "Date",
+  "isNaN",
+  "isFinite",
+  "parseInt",
+  "parseFloat",
+  "Infinity",
+  "NaN",
+  "undefined",
+  "console",
+]);

package/src/cli/cli.ts

@@ -0,0 +1,99 @@
+/**
+ * TS 故事源编译 CLI（`pnpm stories:build`，tsx 运行；创作期工具，Node 侧）：
+ * `Stories.src/config.ts`（布局声明：folders 多目录 + start 入口故事，全局恰一）→
+ * 源发现（default 具名故事函数 = 故事文件，仅具名导出 = 模块，覆盖外 default = 报错）→
+ * story-compiler（`compileStories` 契约，诊断非空 fail-closed）→ `serializeProject`
+ * （单列拆分 + 清单托管键更新——与编辑器写回同一条布局规则；`config.start` →
+ * `project.json` entry）→ `assembleProject` 往返自检 → 差量写盘
+ * `Resources/Stories/**` + `project.json`（陈旧列文件清理；产物路径 = 源文件路径镜像）。
+ *
+ * 本文件是**入口与呈现**：流水线在 `./index`（唯一出口），这里只做三件事——解析可选的
+ * 位置参数工程根、跑一次编译、把 `BuildReport` 打印成人读的几段（完成行 / 零差量 /
+ * 新增 / 更新 / 清理陈旧 / 词汇层提示）。失败一律打到 stderr 并返回退出码 1，便于脚本
+ * 链中断。
+ *
+ * 两种触发方式共用 `runBuildCli`：仓内 `pnpm stories:build` 经底部主模块守卫直接跑本文件
+ * （tsx 解释 TS）；装了本包的工程经 `bin` 里的 `.mjs` 垫片跑——node_modules 内的 TS 不能靠
+ * Node 类型擦除加载，垫片用 tsx 的 `tsImport` 装本文件再调同一个 `runBuildCli`，两条路
+ * 因此共用一份呈现逻辑。
+ *
+ * 用法：`<工程根可省略>`；缺省工程根 = 进程工作目录（调用方脚本已 cd 到宿主工程根，
+ * 或经 DSH_STORIES_ROOT 指明——包内没有「谁在调我、宿主工程在哪」这件事实）。
+ * 测试不经这里——它们直接调 `buildStories`（纯编排，fs 全在参数 root 之下）。
+ */
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  DEFAULT_SOURCES_DIR,
+  StoryBuildError,
+  buildStories,
+} from "../index.ts";
+
+export { StoryBuildError, buildStories, type BuildReport } from "../index.ts";
+
+/** 工程根：位置参数优先，其次 `DSH_STORIES_ROOT`，最后进程工作目录 */
+export function resolveBuildRoot(argv: readonly string[]): string {
+  const envRoot = process.env.DSH_STORIES_ROOT;
+  return resolve(
+    argv[0] ??
+      (envRoot !== undefined && envRoot !== "" ? envRoot : process.cwd()),
+  );
+}
+
+/**
+ * 跑一次编译并把结果打到标准输出/标准错误，返回进程退出码。
+ * 不调用 `process.exit`——谁来决定退出由调用方（主模块守卫或 bin 垫片）负责。
+ */
+export async function runBuildCli(
+  argv: readonly string[] = process.argv.slice(2),
+): Promise<number> {
+  const root = resolveBuildRoot(argv);
+  try {
+    const report = await buildStories(root);
+    console.log(
+      `TS 故事源编译完成：${DEFAULT_SOURCES_DIR}/${report.source} → story "${report.storyId}"（${report.columns} 列）`,
+    );
+    if (
+      report.added.length === 0 &&
+      report.updated.length === 0 &&
+      report.removed.length === 0
+    ) {
+      console.log("已是最新（零差量）");
+    }
+    if (report.added.length > 0) {
+      console.log(
+        `新增（${report.added.length}）：\n  ${report.added.join("\n  ")}`,
+      );
+    }
+    if (report.updated.length > 0) {
+      console.log(
+        `更新（${report.updated.length}）：\n  ${report.updated.join("\n  ")}`,
+      );
+    }
+    if (report.removed.length > 0) {
+      console.log(
+        `清理陈旧（${report.removed.length}）：\n  ${report.removed.join("\n  ")}`,
+      );
+    }
+    if (report.warnings.length > 0) {
+      console.warn(
+        `词汇层类型提示（${report.warnings.length} 条，不拦构建——引擎求值时将 type-error）：\n${report.warnings
+          .map((w) => `  - ${w.expression}：${w.message}`)
+          .join("\n")}`,
+      );
+    }
+    return 0;
+  } catch (error) {
+    console.error(
+      `[stories:build] 失败：${error instanceof StoryBuildError ? error.message : String(error)}`,
+    );
+    return 1;
+  }
+}
+
+// —— 主模块守卫：仅直接执行时跑（tests 直测 buildStories，bin 垫片直调 runBuildCli）——
+// 可选位置参数 = 工程根（默认 = 工作目录，可由 DSH_STORIES_ROOT 覆盖）
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const code = await runBuildCli();
+  if (code !== 0) process.exit(code);
+}

package/src/cli/watch-cli.ts

@@ -0,0 +1,42 @@
+/**
+ * TS 故事源增量监听 CLI（`pnpm stories:watch`，tsx 运行；创作期工具，Node 侧）：
+ * 常驻进程入口——首轮全量构建，之后监听源目录递归变更，防抖合并后进程内重跑构建。
+ *
+ * 本文件是入口与呈现：监听实现在 `../pipeline/watch.ts`。失败轮不退出——
+ * 创作期半成品是常态，修复后保存即重试。
+ *
+ * 与 `./cli.ts` 同一套两路触发：仓内 `pnpm stories:watch` 经主模块守卫直接跑本文件；
+ * 装了本包的工程经 `bin` 里 `.mjs` 垫片用 tsx 装载本文件后调 `startWatchCli`。
+ *
+ * 用法：`<工程根可省略>`；缺省工程根 = 进程工作目录（或 DSH_STORIES_ROOT）。
+ */
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { watchStories } from "../pipeline/watch.ts";
+
+/** 工程根：位置参数优先，其次 `DSH_STORIES_ROOT`，最后进程工作目录 */
+export function resolveWatchRoot(argv: readonly string[]): string {
+  const envRoot = process.env.DSH_STORIES_ROOT;
+  return resolve(
+    argv[0] ??
+      (envRoot !== undefined && envRoot !== "" ? envRoot : process.cwd()),
+  );
+}
+
+/** 起常驻监听并绑定 SIGINT 优雅退出；返回 `watchStories` 给的停止函数 */
+export async function startWatchCli(
+  argv: readonly string[] = process.argv.slice(2),
+): Promise<() => void> {
+  const root = resolveWatchRoot(argv);
+  const stop = await watchStories(root);
+  process.on("SIGINT", () => {
+    stop();
+    process.exit(0);
+  });
+  return stop;
+}
+
+// —— 主模块守卫：仅直接执行时常驻（tests 直测 watchStories / affectedStories）——
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  await startWatchCli();
+}

package/src/compiler/cell-scan.ts

@@ -0,0 +1,27 @@
+import { scanCells, type CellScan } from "../cell/index.ts";
+import { StoryBuildError } from "../shared/index.ts";
+
+/**
+ * cell 声明扫描（构建期 AST 扫描）：`Stories.src` 树（排除生成物目录，仅 `.ts`）。
+ * 「名字在数据、实现在代码、build 做名字闭合」：实现住生成模块，故事 JSON 只留名字。
+ * 任一条扫描问题都 fail-closed，一次报全部（每条带 `路径:行` 定位）。
+ */
+export function scanCellSources(
+  sourcesTree: ReadonlyMap<string, string>,
+  generatedDir: string,
+): CellScan {
+  const cellSourceTree = new Map<string, string>();
+  for (const [rel, text] of sourcesTree) {
+    if (rel.startsWith(`${generatedDir}/`) || !rel.endsWith(".ts")) continue;
+    cellSourceTree.set(rel, text);
+  }
+  const cellScanResult = scanCells(cellSourceTree);
+  if (cellScanResult.errors.length > 0) {
+    throw new StoryBuildError(
+      `cell 声明扫描失败：\n${cellScanResult.errors
+        .map((issue) => `- ${issue.origin}：${issue.message}`)
+        .join("\n")}`,
+    );
+  }
+  return cellScanResult.scan;
+}

package/src/compiler/compiler-contract.ts

@@ -0,0 +1,87 @@
+import { StoryBuildError } from "../shared/index.ts";
+import type { StoriesBuildTexts } from "../shared/index.ts";
+import type { StorySourceConfig } from "../config/story-config.ts";
+
+/**
+ * story-compiler 契约（编译器下游的唯一对接面）：
+ * `compileStories({ root, sourcesDir, stories, modules })` 一次性编译全部故事文件，
+ * 产物 = 列粒度条目（`columnId` + `sourceRelPath` + `story`）+ 诊断集。
+ * 诊断非空 = fail-closed（编排层一次报全部）；`story` 为 parseStory 同形结构。
+ */
+export interface CompiledStoryEntry {
+  /** 该条目对应的列 id（须存在于 `story.columns`） */
+  readonly columnId: string;
+  /** 源文件相对 `Stories.src/` 的 posix 路径（如 `chapters/prologue.ts`） */
+  readonly sourceRelPath: string;
+  /** parseStory 同形结构（引擎 Story；条目为列粒度） */
+  readonly story: unknown;
+}
+
+export interface CompilerDiagnostic {
+  readonly file: string;
+  readonly line: number;
+  readonly col: number;
+  readonly message: string;
+}
+
+export interface CompiledStories {
+  readonly stories: readonly CompiledStoryEntry[];
+  readonly diags: readonly CompilerDiagnostic[];
+}
+
+/**
+ * 编译期求值喂入：文件相对 `Stories.src/` 的 posix 路径 → 导出名 →
+ * 求值出的 JSON 可序列化值。由编排层求值段（const-eval-pass）填充；缺省 =
+ * 没有被求值的文件，编译器行为与未接入求值时逐字一致。
+ */
+export type CompilerConstValues = Readonly<
+  Record<string, Readonly<Record<string, unknown>>>
+>;
+
+export interface StoriesCompiler {
+  compileStories(input: {
+    readonly root: string;
+    readonly sourcesDir: string;
+    /** 布局声明（config.ts 求值产物；folders/start 必需）——图谱层只消费，不再解析 config */
+    readonly config: StorySourceConfig;
+    /** 故事文件清单（相对 `Stories.src/`，posix；default 导出 Story 的 .ts） */
+    readonly stories: readonly string[];
+    /** 模块文件清单（相对 `Stories.src/`，posix；被 import 的支撑 .ts） */
+    readonly modules: readonly string[];
+    /** 编译期求值喂入；缺省 = 无被求值文件（行为不变） */
+    readonly constValues?: CompilerConstValues;
+    /** 字体名注册表（Resources/Fonts 文件名去扩展名）；缺省 = 空注册表，引用字体名即 fail-closed */
+    readonly fontNames?: ReadonlySet<string>;
+    /** 全工程角色表（编排层模块层声明收集产物）；缺省 = 空表，无前置角色命令 */
+    readonly characters?: ReadonlyMap<
+      string,
+      import("@lingfan-engine/core").CharacterDef
+    >;
+    /** 文案注入（Partial）；缺省 = 内建缺省文案（即构建层的既有文案） */
+    readonly texts?: Partial<StoriesBuildTexts>;
+  }): CompiledStories | Promise<CompiledStories>;
+}
+
+/**
+ * 默认编译器装载：`./story-compiler.ts`（本域内的编译器实现；文件缺席 = fail-closed 带指引）。
+ *
+ * 这里写死带扩展名的相对路径，不走 bundler 式的无扩展名解析：包内源码由 tsx/Node 直接跑
+ * TypeScript，Node 的 ESM 解析不补 `.ts`，无扩展名会解析失败。
+ */
+export async function loadDefaultCompiler(): Promise<StoriesCompiler> {
+  const specifier = "./story-compiler.ts";
+  try {
+    const mod = (await import(specifier)) as {
+      compileStories?: StoriesCompiler["compileStories"];
+    };
+    if (typeof mod.compileStories !== "function") {
+      throw new Error("模块缺 compileStories 导出");
+    }
+    return { compileStories: mod.compileStories };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new StoryBuildError(
+      `story-compiler 未就绪（${specifier} 装载失败：${message}）——编排契约已按 compileStories 收敛，等待编译器交付对接`,
+    );
+  }
+}

package/src/compiler/extension-load.ts

@@ -0,0 +1,67 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  loadDeclaredExtensions,
+  type ExtensionModuleLoader,
+} from "@lingfan-engine/core";
+import { StoryBuildError } from "../shared/index.ts";
+
+/** Node 侧缺省装载器：相对说明符按工程根解析（与 Stories.src/Resources 同级），裸说明符交给 Node */
+export function defaultExtensionLoader(root: string): ExtensionModuleLoader {
+  return async (specifier: string) =>
+    specifier.startsWith("./") || specifier.startsWith("../")
+      ? import(relativeSpecifierUrl(root, specifier))
+      : import(specifier);
+}
+
+/**
+ * 相对说明符 → 可导入的 file URL：Node 的 ESM 解析不给 .ts 补扩展名（包内源码直接跑 TS），
+ * 而清单里的相对说明符沿用 bundler 习惯（`./ext/foo`）。这里先按原样试，文件不存在再补 `.ts`，
+ * 让两种写法都能落盘——加载失败仍是 fail-closed，只是不再因写法差异误报。
+ */
+function relativeSpecifierUrl(root: string, specifier: string): string {
+  const target = resolve(root, specifier);
+  const candidates = [target, `${target}.ts`, `${target}/index.ts`];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return pathToFileURL(candidate).href;
+  }
+  return pathToFileURL(target).href;
+}
+
+/** 清单 `extensions` 声明读取与形状校验（缺席/为空 = 空数组零装载；形状非法 fail-closed） */
+export function readDeclaredExtensions(manifest: unknown): string[] {
+  const declared = (manifest as { extensions?: unknown } | null)?.extensions;
+  if (declared === undefined) return [];
+  if (!Array.isArray(declared)) {
+    throw new StoryBuildError(
+      `清单 extensions 必须为数组（扩展模块说明符声明），收到 ${JSON.stringify(declared)}`,
+    );
+  }
+  for (const specifier of declared) {
+    if (typeof specifier !== "string" || specifier === "") {
+      throw new StoryBuildError(
+        `清单 extensions 条目必须为非空模块说明符，收到 ${JSON.stringify(specifier)}`,
+      );
+    }
+  }
+  return declared as string[];
+}
+
+/** 声明制装载（与运行期同一契约）+ 该轮装载到的全部 op 名（unknown-op 闸门的判定输入）+ 扩展 id */
+export async function loadExtensions(
+  root: string,
+  manifest: unknown,
+): Promise<{ declared: string[]; opNames: Set<string>; ids: string[] }> {
+  const declared = readDeclaredExtensions(manifest);
+  const loaded = await loadDeclaredExtensions(
+    declared,
+    defaultExtensionLoader(root),
+  );
+  const opNames = new Set(
+    loaded.flatMap((extension) => (extension.ops ?? []).map((def) => def.op)),
+  );
+  // id 供类型面生成器写 `ext.<id>.${string}` 插值键模式（加载期拿到的就是已解析的 id）
+  const ids = loaded.map((extension) => extension.id);
+  return { declared, opNames, ids };
+}

package/src/compiler/index.ts

@@ -0,0 +1,22 @@
+/**
+ * 编译器域：把 `Stories.src` 的 TS 源编译成引擎故事对象。
+ *
+ * 对外只有 `loadDefaultCompiler` 与 `compileStories` 两条——宿主既可以
+ * 走默认实现，也可以注入自己的编译器（测试就是这么干的）。外部扩展模块的
+ * 装载、cell 声明的扫描也在这域：它们是「读源」的三种不同入口，共用同一套
+ * fail-closed 口径。
+ */
+export {
+  loadDefaultCompiler,
+  type CompiledStories,
+  type CompiledStoryEntry,
+  type CompilerConstValues,
+  type CompilerDiagnostic,
+  type StoriesCompiler,
+} from "./compiler-contract.ts";
+export {
+  loadExtensions,
+  readDeclaredExtensions,
+  defaultExtensionLoader,
+} from "./extension-load.ts";
+export { scanCellSources } from "./cell-scan.ts";