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

package/src/compiler/story-compiler/assemble/functions.ts

@@ -0,0 +1,202 @@
+/**
+ * 函数编译：把 .ts 模块里的函数声明（列内嵌套/跨列被引）翻译成 func 命令，
+ * 含参数校验、嵌套函数提升与互调、结果缓存（按 `文件#拥有者链#名` 键）。
+ * 会话与列编译入口在 ./session.ts。
+ */
+import * as ts from "typescript";
+import { compareOrdinal, type StoryCommand } from "@lingfan-engine/core";
+import type { DiagBag, Graph } from "../graph.ts";
+import {
+  createBodyCtx,
+  makeFuncOp,
+  translateStatements,
+  type FuncRegistry,
+  type Scope,
+  type ScopeEntry,
+} from "../translate.ts";
+import type { AssembleSession, CompiledFunction } from "./types.ts";
+
+function nodePos(
+  sf: ts.SourceFile,
+  node: ts.Node,
+): { file: string; line: number; col: number } {
+  const { line, character } = sf.getLineAndCharacterOfPosition(
+    node.getStart(sf),
+  );
+  return { file: sf.fileName, line: line + 1, col: character + 1 };
+}
+
+export function partitionFunctions(statements: readonly ts.Statement[]): {
+  fns: ts.FunctionDeclaration[];
+  rest: ts.Statement[];
+} {
+  const fns: ts.FunctionDeclaration[] = [];
+  const rest: ts.Statement[] = [];
+  for (const stmt of statements) {
+    if (
+      ts.isFunctionDeclaration(stmt) &&
+      stmt.name !== undefined &&
+      stmt.body !== undefined
+    ) {
+      fns.push(stmt);
+      continue;
+    }
+    rest.push(stmt);
+  }
+  return { fns, rest };
+}
+
+function readParams(
+  ctx: ReturnType<typeof createBodyCtx>,
+  decl: ts.FunctionDeclaration,
+): string[] | undefined {
+  const params: string[] = [];
+  for (const param of decl.parameters) {
+    if (!ts.isIdentifier(param.name)) {
+      diagNode(ctx, param, "函数参数必须是简单标识符");
+      return undefined;
+    }
+    if (params.includes(param.name.text)) {
+      diagNode(ctx, param, `重复的参数名 \`${param.name.text}\``);
+      return undefined;
+    }
+    if (
+      param.initializer !== undefined ||
+      param.questionToken !== undefined ||
+      param.dotDotDotToken !== undefined
+    ) {
+      diagNode(ctx, param, "函数参数不支持默认值/可选/剩余");
+      return undefined;
+    }
+    params.push(param.name.text);
+  }
+  return params;
+}
+
+function diagNode(
+  ctx: ReturnType<typeof createBodyCtx>,
+  node: ts.Node,
+  message: string,
+): void {
+  ctx.shared.diags.add(ctx.shared.file, ctx.shared.mod.sf, node, message);
+}
+
+export function tryFuncOp(
+  sf: ts.SourceFile,
+  node: ts.Node,
+  diags: DiagBag,
+  name: string,
+  params: string[],
+  body: StoryCommand[],
+): StoryCommand | undefined {
+  try {
+    return makeFuncOp(name, params, body);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    diags.add(
+      sf.fileName,
+      sf,
+      node,
+      `func 命令构建失败（${name}）：${message}`,
+    );
+    return undefined;
+  }
+}
+
+export function compileFunction(
+  session: AssembleSession,
+  graph: Graph,
+  diags: DiagBag,
+  file: string,
+  ownerChain: readonly string[],
+  decl: ts.FunctionDeclaration,
+  parentScopes: readonly Scope[],
+): CompiledFunction | undefined {
+  const mod = graph.records.get(file);
+  if (mod === undefined || decl.name === undefined) return undefined;
+  const sf = mod.sf;
+  const name = decl.name.text;
+  const key = `${file}#${[...ownerChain, name].join("#")}`;
+  const cached = session.cache.get(key);
+  if (cached !== undefined) return cached;
+
+  const registry: FuncRegistry = { refs: new Map(), names: new Map() };
+  const shared = {
+    mod,
+    file,
+    diags,
+    funcs: registry,
+    stateRoot: graph.stateRoot,
+    fontNames: session.fontNames,
+    texts: session.texts,
+  };
+  const ctx = createBodyCtx(shared, { inFunction: true, parentScopes });
+  const params = readParams(ctx, decl);
+  if (params === undefined) return undefined;
+  const paramScope = new Map<string, ScopeEntry>(
+    params.map((p) => [p, { kind: "param" }]),
+  );
+  ctx.scopes.push(paramScope);
+
+  const { fns: nestedDecls, rest } = partitionFunctions(decl.body!.statements);
+  // 函数声明提升：嵌套名先登记进本层，体翻译即可引用它们，嵌套函数之间也能互调
+  for (const nestedDecl of nestedDecls) {
+    ctx.scopes[ctx.scopes.length - 1].set(nestedDecl.name!.text, {
+      kind: "function",
+      file,
+    });
+  }
+  const bodyCommands = translateStatements(ctx, rest);
+  // 嵌套函数体继承本层作用域链（参数/局部/嵌套名只读下传）；本层翻译先完成，声明已齐备
+  const nested: CompiledFunction[] = [];
+  for (const nestedDecl of nestedDecls) {
+    const compiled = compileFunction(
+      session,
+      graph,
+      diags,
+      file,
+      [...ownerChain, name],
+      nestedDecl,
+      ctx.scopes,
+    );
+    if (compiled === undefined) continue;
+    nested.push(compiled);
+  }
+
+  const allNames = new Map<string, { file: string; line: number; col: number }>(
+    [[name, nodePos(sf, decl.name)]],
+  );
+  for (const item of nested) {
+    for (const [n, pos] of item.allNames) allNames.set(n, pos);
+  }
+  const refs = new Set<string>([
+    ...registry.refs.keys(),
+    ...nested.flatMap((item) => [...item.refs]),
+  ]);
+  const nestedOps: StoryCommand[] = [];
+  for (const item of [...nested].sort((a, b) =>
+    compareOrdinal(a.name, b.name),
+  )) {
+    const op = tryFuncOp(
+      sf,
+      decl.name,
+      diags,
+      item.name,
+      item.params,
+      item.body,
+    );
+    if (op === undefined) continue;
+    nestedOps.push(op);
+  }
+  const compiled: CompiledFunction = {
+    key,
+    file,
+    name,
+    params,
+    body: [...nestedOps, ...bodyCommands],
+    refs,
+    allNames,
+  };
+  session.cache.set(key, compiled);
+  return compiled;
+}

package/src/compiler/story-compiler/assemble/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 装配族出口：装配会话与整篇编译的入口。
+ *
+ * 轴 = 装配会话三件——形状（`types.ts`）、会话入口（`session.ts`）、函数编译细节（`functions.ts`）。
+ * 函数编译细节属族内实现，不进出口。
+ */
+export { compileStoryFile, createAssembleSession } from "./session.ts";
+export type { AssembleSession, CompiledStory } from "./session.ts";

package/src/compiler/story-compiler/assemble/session.ts

@@ -0,0 +1,207 @@
+import {
+  compareOrdinal,
+  type CharacterDef,
+  type Story,
+  type StoryCommand,
+} from "@lingfan-engine/core";
+import {
+  defaultStoriesBuildTexts,
+  type StoriesBuildTexts,
+} from "../../../shared/index.ts";
+import type { DiagBag, Graph } from "../graph.ts";
+import { compileFunction, partitionFunctions, tryFuncOp } from "./functions.ts";
+import {
+  createBodyCtx,
+  translateStatements,
+  type FuncRegistry,
+} from "../translate.ts";
+import type {
+  AssembleSession,
+  CompiledFunction,
+  CompiledStory,
+} from "./types.ts";
+
+export type { AssembleSession, CompiledStory } from "./types.ts";
+
+/**
+ * 会话与列编译：会话持有跨文件共享状态（函数缓存/字体表/文案表/全工程角色表），
+ * compileStoryFile 把单个故事文件编译成单列 Story。函数体翻译在 ./functions.ts。
+ */
+
+export function createAssembleSession(
+  fontNames: ReadonlySet<string> = new Set(),
+  texts: StoriesBuildTexts = defaultStoriesBuildTexts,
+  characters: ReadonlyMap<string, CharacterDef> = new Map(),
+): AssembleSession {
+  return { cache: new Map(), fontNames, texts, characters };
+}
+
+export function compileStoryFile(
+  session: AssembleSession,
+  graph: Graph,
+  diags: DiagBag,
+  rel: string,
+): CompiledStory | undefined {
+  const mod = graph.records.get(rel);
+  const storyName = mod?.story?.node.name;
+  if (mod === undefined || mod.story === null || storyName === undefined)
+    return undefined;
+  const storyDecl = mod.story;
+  const sf = mod.sf;
+  const columnId = storyDecl.name;
+
+  // —— 列级字体：声明值对照字体名注册表（fail-closed，与词引用同一组诊断文案）——
+  let columnFont: string | undefined;
+  if (mod.columnFont !== null) {
+    const { value, node } = mod.columnFont;
+    if (session.fontNames.has(value)) {
+      columnFont = value;
+    } else {
+      diags.add(
+        rel,
+        sf,
+        node,
+        `未注册的字体名 "${value}"——Resources/Fonts 里没有对应字体文件（字体名 = 文件名去扩展名）`,
+      );
+    }
+  }
+
+  const registry: FuncRegistry = { refs: new Map(), names: new Map() };
+  const shared = {
+    mod,
+    file: rel,
+    diags,
+    funcs: registry,
+    stateRoot: graph.stateRoot,
+    fontNames: session.fontNames,
+    texts: session.texts,
+  };
+  const ctx = createBodyCtx(shared, { inFunction: false });
+  const { fns: nestedDecls, rest } = partitionFunctions(
+    storyDecl.node.body!.statements,
+  );
+  // 函数声明提升：嵌套名先登记进列根作用域，列体即可引用它们
+  for (const nestedDecl of nestedDecls) {
+    ctx.scopes[ctx.scopes.length - 1].set(nestedDecl.name!.text, {
+      kind: "function",
+      file: rel,
+    });
+  }
+  const bodyCommands = translateStatements(ctx, rest);
+  // 嵌套函数体继承列根作用域（列级 let/嵌套名只读下传）；列体翻译先完成，声明已齐备
+  const nested: CompiledFunction[] = [];
+  for (const nestedDecl of nestedDecls) {
+    const compiled = compileFunction(
+      session,
+      graph,
+      diags,
+      rel,
+      [columnId],
+      nestedDecl,
+      ctx.scopes,
+    );
+    if (compiled === undefined) continue;
+    nested.push(compiled);
+  }
+
+  const closure = new Map<string, CompiledFunction>();
+  const worklist = [...registry.refs.keys()];
+  while (worklist.length > 0) {
+    const key = worklist.pop()!;
+    if (closure.has(key)) continue;
+    const sep = key.indexOf("#");
+    const file = key.slice(0, sep);
+    const fnName = key.slice(sep + 1);
+    const target = graph.records.get(file);
+    const decl = target?.functions.get(fnName);
+    if (target === undefined || decl === undefined) continue;
+    const compiled = compileFunction(session, graph, diags, file, [], decl, []);
+    if (compiled === undefined) continue;
+    closure.set(key, compiled);
+    worklist.push(...compiled.refs);
+  }
+
+  const columnNames = new Map<
+    string,
+    { file: string; line: number; col: number }
+  >();
+  const registerName = (
+    n: string,
+    pos: { file: string; line: number; col: number },
+  ): void => {
+    const prev = columnNames.get(n);
+    if (prev !== undefined) {
+      diags.add(
+        rel,
+        sf,
+        storyName,
+        `同列存在同名 func \`${n}\`：${prev.file}:${prev.line}:${prev.col} 与 ${pos.file}:${pos.line}:${pos.col}`,
+      );
+      return;
+    }
+    columnNames.set(n, pos);
+  };
+  const localGroup: CompiledFunction[] = [...nested];
+  const importedGroup: CompiledFunction[] = [];
+  for (const compiled of closure.values()) {
+    if (compiled.file === rel) localGroup.push(compiled);
+    else importedGroup.push(compiled);
+  }
+  for (const group of [localGroup, importedGroup]) {
+    for (const compiled of group) {
+      for (const [n, pos] of compiled.allNames) registerName(n, pos);
+    }
+  }
+
+  const commands: StoryCommand[] = [];
+  // 全工程角色表前置：模块层声明的角色进场即有（注册先于一切命令，含 func）
+  for (const def of [...session.characters.values()].sort((a, b) =>
+    compareOrdinal(a.key, b.key),
+  )) {
+    commands.push(characterCommand(def));
+  }
+  for (const group of [localGroup, importedGroup]) {
+    for (const compiled of [...group].sort((a, b) =>
+      compareOrdinal(a.name, b.name),
+    )) {
+      const op = tryFuncOp(
+        sf,
+        storyName,
+        diags,
+        compiled.name,
+        compiled.params,
+        compiled.body,
+      );
+      if (op === undefined) continue;
+      commands.push(op);
+    }
+  }
+  commands.push(...bodyCommands);
+
+  const story: Story = {
+    formatVersion: 1,
+    id: columnId,
+    entry: columnId,
+    columns: [
+      {
+        id: columnId,
+        kind: "flow",
+        ...(columnFont !== undefined ? { font: columnFont } : {}),
+        commands,
+      },
+    ],
+  };
+  return { columnId, sourceRelPath: rel, story };
+}
+
+/** 模块层角色声明 → character 命令（六字段全可选，有值才投影） */
+function characterCommand(def: CharacterDef): StoryCommand {
+  const op: StoryCommand = { op: "character", key: def.key };
+  if (def.name !== undefined) op.name = def.name;
+  if (def.color !== undefined) op.color = def.color;
+  if (def.size !== undefined) op.size = def.size;
+  if (def.font !== undefined) op.font = def.font;
+  if (def.textColor !== undefined) op.textColor = def.textColor;
+  if (def.screen !== undefined) op.screen = def.screen;
+  return op;
+}

package/src/compiler/story-compiler/assemble/types.ts

@@ -0,0 +1,37 @@
+/**
+ * 装配层的公共形状：会话状态、单列编译结果与函数体编译产物。
+ *
+ * 类型放叶子：会话实现与函数体翻译都要用这些形状，声明在任一实现里都会让另一方反向依赖。
+ */
+
+import type { CharacterDef, Story, StoryCommand } from "@lingfan-engine/core";
+import type { StoriesBuildTexts } from "../../../shared/index.ts";
+
+/** 会话：跨文件共享状态（函数缓存 / 字体表 / 文案表 / 全工程角色表） */
+export interface AssembleSession {
+  cache: Map<string, CompiledFunction>;
+  /** 字体名注册表（编排层自 Resources/Fonts 扫描；构建期字体引用检查对照源） */
+  fontNames: ReadonlySet<string>;
+  /** 集中文案表（编译入口注入，已含缺省合并；诊断文案只从这里取） */
+  texts: StoriesBuildTexts;
+  /** 全工程角色表（编排层模块层声明收集产物）：前置成每个故事 start 列头的 character 命令 */
+  characters: ReadonlyMap<string, CharacterDef>;
+}
+
+/** 单列编译结果 */
+export interface CompiledStory {
+  columnId: string;
+  sourceRelPath: string;
+  story: Story;
+}
+
+/** 一次函数编译的产物：签名、体命令、被引函数名与全部嵌套名（同列重名检查用） */
+export interface CompiledFunction {
+  key: string;
+  file: string;
+  name: string;
+  params: string[];
+  body: StoryCommand[];
+  refs: ReadonlySet<string>;
+  allNames: ReadonlyMap<string, { file: string; line: number; col: number }>;
+}

package/src/compiler/story-compiler/assemble.ts

@@ -0,0 +1,5 @@
+/**
+ * 装配族的对上游出口（本文件与 `assemble/` 目录同族，导出面与目录出口一致）。
+ */
+export { compileStoryFile, createAssembleSession } from "./assemble/index.ts";
+export type { AssembleSession, CompiledStory } from "./assemble/index.ts";

package/src/compiler/story-compiler/graph/build.ts

@@ -0,0 +1,208 @@
+import * as ts from "typescript";
+import { walkFiles, type StoriesBuildTexts } from "../../../shared/index.ts";
+import type { StorySourceConfig } from "../../../config/story-config.ts";
+import type { CompilerConstValues } from "../../compiler-contract.ts";
+import {
+  DiagBag,
+  ROOT_TS_FILES_ALLOWED,
+  GEN_PREFIX,
+  COLUMN_FONT_DECL,
+  toPosix,
+} from "./core.ts";
+import type { Graph, ModuleRecord } from "./core.ts";
+import { scanModule } from "./scan/module-scan.ts";
+import { discoverStateRoot } from "./state-root.ts";
+import {
+  scanConstStatement,
+  assertNpmNamesConstOnly,
+} from "./scan/bindings.ts";
+import { resolveImports } from "./scan/imports.ts";
+
+/**
+ * 图谱构建：布局声明（config 求值产物）为必填入参——本层不再解析 config.ts
+ *（读取/校验统一走 const-eval/config-eval），只消费 folders/start。
+ */
+export function buildGraph(
+  sourcesDir: string,
+  diags: DiagBag,
+  config: StorySourceConfig,
+  constValues?: CompilerConstValues,
+  texts?: StoriesBuildTexts,
+): Graph | null {
+  const files = new Map<string, string>();
+  for (const [rel, text] of walkFiles(sourcesDir)) {
+    const posix = toPosix(rel);
+    if (posix.startsWith(GEN_PREFIX) || !posix.endsWith(".ts")) continue;
+    files.set(posix, text);
+  }
+  if (!files.has("config.ts")) {
+    const emptySf = ts.createSourceFile(
+      "config.ts",
+      "",
+      ts.ScriptTarget.Latest,
+      true,
+    );
+    diags.addPos("config.ts", emptySf, 0, "Stories.src 根级缺少 config.ts");
+    return null;
+  }
+
+  const configSf = ts.createSourceFile(
+    "config.ts",
+    files.get("config.ts") ?? "",
+    ts.ScriptTarget.Latest,
+    true,
+  );
+  if (config.folders.length === 0) {
+    diags.addPos(
+      "config.ts",
+      configSf,
+      0,
+      'folders 为空且未包含 "*"：没有编译域',
+    );
+  }
+  for (const rel of files.keys()) {
+    if (rel.includes("/") || ROOT_TS_FILES_ALLOWED.has(rel)) continue;
+    const sf = ts.createSourceFile(
+      rel,
+      files.get(rel) ?? "",
+      ts.ScriptTarget.Latest,
+      true,
+    );
+    diags.add(
+      rel,
+      sf,
+      sf,
+      "根级除 config.ts 外不允许 .ts 文件：故事请放入 folders 目录，纯模块请放入子目录",
+    );
+  }
+
+  const records = new Map<string, ModuleRecord>();
+  for (const [rel, text] of files) {
+    if (rel === "config.ts") continue;
+    records.set(rel, {
+      rel,
+      sf: ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true),
+      story: null,
+      functions: new Map(),
+      bindings: new Map(),
+      exports: new Map(),
+      imports: [],
+      consts: [],
+      npmNames: new Set(),
+      evaluated: constValues?.[rel],
+      columnFont: null,
+    });
+  }
+
+  for (const record of records.values()) scanModule(record, diags);
+  for (const record of records.values())
+    resolveImports(record, records, diags, true);
+  for (const record of records.values()) {
+    for (const stmt of record.consts)
+      scanConstStatement(stmt, record, diags, texts);
+  }
+  collectColumnFonts(records, diags);
+  for (const record of records.values())
+    resolveImports(record, records, diags, false);
+  for (const record of records.values())
+    assertNpmNamesConstOnly(record, diags, texts);
+
+  const wildcard = config.folders.includes("*");
+  const explicit = config.folders.filter((f) => f !== "*");
+  const coveredStories: string[] = [];
+  for (const [rel, record] of records) {
+    if (record.story === null) continue;
+    const covered = wildcard || explicit.some((f) => rel.startsWith(`${f}/`));
+    if (!covered) {
+      const node =
+        record.sf.statements.find((s) => ts.isExportAssignment(s)) ?? record.sf;
+      diags.add(
+        rel,
+        record.sf,
+        node,
+        "故事文件不在 config.folders 覆盖范围内（不会被编译为列）",
+      );
+      continue;
+    }
+    coveredStories.push(rel);
+  }
+  coveredStories.sort();
+
+  const stateRoot = discoverStateRoot(records, diags);
+  return { files, records, config, configSf, coveredStories, stateRoot };
+}
+
+/**
+ * 列级字体声明拾取：`export const columnFont = "<名>"`。
+ * 值走既有 const 绑定通道（字面量 / 常量运算 / 其他 const / 编译期求值内联同源），
+ * 这里只做归属与形状裁定；字体名是否在注册表内由汇编段对照 fontNames 报（注册表
+ * 在会话上，图谱层不可见）。
+ */
+function collectColumnFonts(
+  records: ReadonlyMap<string, ModuleRecord>,
+  diags: DiagBag,
+): void {
+  for (const record of records.values()) {
+    const binding = record.exports.get(COLUMN_FONT_DECL);
+    if (binding === undefined) continue;
+    const stmt = record.consts.find((s) => {
+      const decl = s.declarationList.declarations[0];
+      return (
+        decl !== undefined &&
+        ts.isIdentifier(decl.name) &&
+        decl.name.text === COLUMN_FONT_DECL
+      );
+    });
+    const node = stmt ?? record.sf;
+    if (record.story === null) {
+      diags.add(
+        record.rel,
+        record.sf,
+        node,
+        "columnFont 只能声明在故事文件（default 导出列）的模块顶层",
+      );
+      continue;
+    }
+    if (
+      binding.kind !== "const" ||
+      typeof binding.value !== "string" ||
+      binding.value === ""
+    ) {
+      diags.add(
+        record.rel,
+        record.sf,
+        node,
+        "columnFont 必须折叠为非空字符串字面量（字体名 = Resources/Fonts 文件名去扩展名）",
+      );
+      continue;
+    }
+    record.columnFont = { value: binding.value, node };
+  }
+}
+
+export function resolveStart(graph: Graph, diags: DiagBag): string | undefined {
+  const candidates = graph.coveredStories.filter((rel) => {
+    const idx = rel.lastIndexOf("/");
+    return (idx === -1 ? rel : rel.slice(idx + 1)) === graph.config.start;
+  });
+  if (candidates.length === 0) {
+    diags.addPos(
+      "config.ts",
+      graph.configSf,
+      0,
+      `start \`${graph.config.start}\` 没有命中任何覆盖内故事文件`,
+    );
+    return undefined;
+  }
+  if (candidates.length > 1) {
+    diags.addPos(
+      "config.ts",
+      graph.configSf,
+      0,
+      `start \`${graph.config.start}\` 命中多个故事文件：${candidates.join("、")}`,
+    );
+    return undefined;
+  }
+  const record = graph.records.get(candidates[0]);
+  return record?.story?.name;
+}