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

package/src/compiler/story-compiler/translate/stmt/control/index.ts

@@ -0,0 +1,11 @@
+/**
+ * 控制流族出口：if / while / for / for-of / switch 的翻译入口。
+ *
+ * 族内各文件共用 `StatementDispatch` 契约（注入式递归入口，声明在
+ * `../control-flow.ts`），并统一从 `../control-flow.ts` 取 `translateBlockBody`
+ * 下探块体——单向依赖，不反向 import 语句分发器（`statements.ts`）。
+ */
+export { translateIf } from "./branch.ts";
+export { translateFor, translateWhile } from "./loop.ts";
+export { translateForOf } from "./iter.ts";
+export { translateSwitch } from "./switch.ts";

package/src/compiler/story-compiler/translate/stmt/control/iter.ts

@@ -0,0 +1,72 @@
+import * as ts from "typescript";
+import type { StoryCommand } from "@lingfan-engine/core";
+import { diag, lookupScope } from "../../shared.ts";
+import type { BodyCtx } from "../../shared.ts";
+import { statePath } from "../../expr/state-path.ts";
+import { callWord } from "../../expr/words/index.ts";
+import { translateBlockBody } from "../control-flow.ts";
+import type { StatementDispatch } from "../control-flow.ts";
+
+export function translateForOf(
+  ctx: BodyCtx,
+  stmt: ts.ForOfStatement,
+  dispatch: StatementDispatch,
+): StoryCommand[] {
+  const initializer = stmt.initializer;
+  if (
+    !ts.isVariableDeclarationList(initializer) ||
+    initializer.declarations.length !== 1 ||
+    !ts.isIdentifier(initializer.declarations[0].name)
+  ) {
+    diag(ctx, initializer, "for-of 只支持 (let x of 集合) 形式");
+    return [];
+  }
+  const varName = initializer.declarations[0].name.text;
+  const collection = forOfCollection(ctx, stmt.expression);
+  if (collection === undefined) return [];
+  ctx.scopes.push(new Map([[varName, { kind: "let" }]]));
+  ctx.breakables.push("loop");
+  const body = translateBlockBody(ctx, stmt.statement, dispatch);
+  ctx.breakables.pop();
+  ctx.scopes.pop();
+  const op = callWord(ctx, stmt, "forIn", [varName, collection, body]);
+  return op === undefined ? [] : [op];
+}
+
+function forOfCollection(
+  ctx: BodyCtx,
+  expr: ts.Expression,
+): string | undefined {
+  const root = ctx.shared.stateRoot;
+  if (ts.isIdentifier(expr)) {
+    if (expr.text === root) {
+      diag(ctx, expr, `for-of 集合必须是 ${root} 路径或局部变量名`);
+      return undefined;
+    }
+    const scoped = lookupScope(ctx, expr.text);
+    if (
+      scoped !== undefined &&
+      (scoped.kind === "let" || scoped.kind === "param")
+    ) {
+      return `{${expr.text}}`;
+    }
+    diag(
+      ctx,
+      expr,
+      `for-of 集合 \`${expr.text}\` 必须是已声明的局部变量或 ${root} 路径`,
+    );
+    return undefined;
+  }
+  if (ts.isPropertyAccessExpression(expr)) {
+    const target = statePath(ctx, expr);
+    if (target === undefined) return undefined;
+    if (target.optional) {
+      // 迭代集合必须真实存在（缺失语义无从谈起），fail-closed
+      diag(ctx, expr, `for-of 集合不支持可选链：${target.path}`);
+      return undefined;
+    }
+    return `{${target.path}}`;
+  }
+  diag(ctx, expr, `for-of 集合只能是 ${root} 路径或局部变量名`);
+  return undefined;
+}

package/src/compiler/story-compiler/translate/stmt/control/loop.ts

@@ -0,0 +1,114 @@
+import * as ts from "typescript";
+import type { StoryCommand } from "@lingfan-engine/core";
+import { diag, isAssignmentOperator } from "../../shared.ts";
+import type { BodyCtx, Scope } from "../../shared.ts";
+import {
+  lowerCond,
+  lowerValue,
+  loweredToScriptValue,
+} from "../../expr/expr.ts";
+import { callWord } from "../../expr/words/index.ts";
+import { emitAssignment, translateIncrement } from "../../expr/assign.ts";
+import { translateBlockBody } from "../control-flow.ts";
+import type { StatementDispatch } from "../control-flow.ts";
+
+export function translateWhile(
+  ctx: BodyCtx,
+  stmt: ts.WhileStatement,
+  dispatch: StatementDispatch,
+): StoryCommand[] {
+  const cond = lowerCond(ctx, stmt.expression);
+  if (cond === undefined) return [];
+  ctx.scopes.push(new Map());
+  ctx.breakables.push("loop");
+  const body = translateBlockBody(ctx, stmt.statement, dispatch);
+  ctx.breakables.pop();
+  ctx.scopes.pop();
+  const op = callWord(ctx, stmt, "whileDo", [cond, body]);
+  return op === undefined ? [] : [op];
+}
+
+export function translateFor(
+  ctx: BodyCtx,
+  stmt: ts.ForStatement,
+  dispatch: StatementDispatch,
+): StoryCommand[] {
+  if (
+    stmt.initializer === undefined ||
+    !ts.isVariableDeclarationList(stmt.initializer)
+  ) {
+    diag(
+      ctx,
+      stmt,
+      "for 初始化只支持单个带初值的 let 声明（for (let i = 0; …)）",
+    );
+    return [];
+  }
+  const decls = stmt.initializer.declarations;
+  if (
+    decls.length !== 1 ||
+    !ts.isIdentifier(decls[0].name) ||
+    decls[0].initializer === undefined
+  ) {
+    diag(ctx, stmt.initializer, "for 初始化只支持单个带初值的 let 声明");
+    return [];
+  }
+  const lowered = lowerValue(ctx, decls[0].initializer);
+  if (lowered === undefined) return [];
+  const varName = decls[0].name.text;
+  const initOp = callWord(ctx, stmt.initializer, "letVar", [
+    varName,
+    loweredToScriptValue(lowered),
+  ]);
+  if (initOp === undefined) return [];
+  const cond =
+    stmt.condition === undefined ? undefined : lowerCond(ctx, stmt.condition);
+  if (cond === undefined) {
+    diag(ctx, stmt, "for 缺少循环条件");
+    return [];
+  }
+  const scope: Scope = new Map([[varName, { kind: "let" }]]);
+  ctx.scopes.push(scope);
+  ctx.breakables.push("loop");
+  const body = translateBlockBody(ctx, stmt.statement, dispatch);
+  const update = translateForUpdate(ctx, stmt);
+  ctx.breakables.pop();
+  ctx.scopes.pop();
+  if (update.length === 0 && stmt.incrementor !== undefined) return [];
+  if (stmt.incrementor === undefined) {
+    diag(
+      ctx,
+      stmt,
+      "for 缺少更新表达式（循环会无法推进；固定次数请用 staticFor）",
+    );
+    return [];
+  }
+  const op = callWord(ctx, stmt, "whileDo", [cond, [...body, ...update]]);
+  return op === undefined ? [] : [initOp, op];
+}
+
+function translateForUpdate(
+  ctx: BodyCtx,
+  stmt: ts.ForStatement,
+): StoryCommand[] {
+  const inc = stmt.incrementor;
+  if (inc === undefined) return [];
+  const sf = ctx.shared.mod.sf;
+  if (
+    ts.isBinaryExpression(inc) &&
+    isAssignmentOperator(inc.operatorToken.getText(sf))
+  ) {
+    return emitAssignment(
+      ctx,
+      inc,
+      inc.left,
+      inc.operatorToken.getText(sf),
+      inc.right,
+    );
+  }
+  if (ts.isPrefixUnaryExpression(inc) || ts.isPostfixUnaryExpression(inc)) {
+    return translateIncrement(ctx, inc);
+  }
+  diag(ctx, inc, "for 更新表达式只支持赋值或 ++/--");
+  return [];
+}

package/src/compiler/story-compiler/translate/stmt/control/switch.ts

@@ -0,0 +1,75 @@
+import * as ts from "typescript";
+import type { StoryCommand } from "@lingfan-engine/core";
+import { foldConst } from "../../../graph.ts";
+import { diag, lookupBinding } from "../../shared.ts";
+import type { BodyCtx } from "../../shared.ts";
+import { lowerCond } from "../../expr/expr.ts";
+import { callWord } from "../../expr/words/index.ts";
+import type { StatementDispatch } from "../control-flow.ts";
+
+function isUnlabeledBreak(stmt: ts.Statement): boolean {
+  return ts.isBreakStatement(stmt) && stmt.label === undefined;
+}
+
+export function translateSwitch(
+  ctx: BodyCtx,
+  stmt: ts.SwitchStatement,
+  dispatch: StatementDispatch,
+): StoryCommand[] {
+  const sf = ctx.shared.mod.sf;
+  const on = lowerCond(ctx, stmt.expression);
+  if (on === undefined) return [];
+  const clauses = stmt.caseBlock.clauses;
+  const cases: Array<[string | number | boolean, StoryCommand[]]> = [];
+  let defaultBody: StoryCommand[] | undefined;
+  for (let i = 0; i < clauses.length; i += 1) {
+    const clause = clauses[i];
+    const isLast = i === clauses.length - 1;
+    const body = clause.statements;
+    const endsWithBreak =
+      body.length > 0 && isUnlabeledBreak(body[body.length - 1]);
+    if (body.length === 0 && !isLast) {
+      diag(
+        ctx,
+        clause,
+        "case 体不能为空（引擎 switch 无穿透，请合并条件或补 break）",
+      );
+      continue;
+    }
+    if (body.length > 0 && !endsWithBreak && !isLast) {
+      diag(ctx, clause, "case 体必须以 break 收尾（引擎 switch 无穿透）");
+      continue;
+    }
+    ctx.scopes.push(new Map());
+    ctx.breakables.push("switch");
+    const commands = dispatch.statements(ctx, body);
+    ctx.breakables.pop();
+    ctx.scopes.pop();
+    if (ts.isDefaultClause(clause)) {
+      if (defaultBody !== undefined) {
+        diag(ctx, clause, "重复的 default 分支");
+        continue;
+      }
+      defaultBody = commands;
+      continue;
+    }
+    const value = foldConst(
+      clause.expression,
+      sf,
+      ctx.shared.diags,
+      ctx.shared.file,
+      (name) => lookupBinding(ctx, name),
+    );
+    if (value === undefined || value === null) {
+      diag(
+        ctx,
+        clause.expression,
+        "case 值必须是字面量或可折叠的模块常量/枚举成员",
+      );
+      continue;
+    }
+    cases.push([value, commands]);
+  }
+  const op = callWord(ctx, stmt, "switchOn", [on, cases, defaultBody]);
+  return op === undefined ? [] : [op];
+}

package/src/compiler/story-compiler/translate/stmt/control-flow.ts

@@ -0,0 +1,25 @@
+import * as ts from "typescript";
+import type { StoryCommand } from "@lingfan-engine/core";
+import type { BodyCtx } from "../shared.ts";
+
+/**
+ * 语句递归入口：块体与 `case` 体由此下探。
+ *
+ * 控制流语句的体内可以再出现控制流语句，本族与语句分发器天然互相递归；
+ * 入口由调用方**注入**（本模块不 import 分发器）。
+ */
+export interface StatementDispatch {
+  /** 单条语句 → 命令序列 */
+  statement(ctx: BodyCtx, stmt: ts.Statement): StoryCommand[];
+  /** 语句列表 → 命令序列 */
+  statements(ctx: BodyCtx, stmts: readonly ts.Statement[]): StoryCommand[];
+}
+
+export function translateBlockBody(
+  ctx: BodyCtx,
+  stmt: ts.Statement,
+  dispatch: StatementDispatch,
+): StoryCommand[] {
+  if (ts.isBlock(stmt)) return dispatch.statements(ctx, stmt.statements);
+  return dispatch.statement(ctx, stmt);
+}

package/src/compiler/story-compiler/translate/stmt/index.ts

@@ -0,0 +1,17 @@
+/**
+ * 语句族出口：TS 语句（含控制流）到引擎语句的翻译。
+ *
+ * 轴 = 语句层两件——语句分派（`statements.ts`）与控制流族（`control-flow.ts`
+ * 提供块体递归入口契约 `StatementDispatch` 与 `translateBlockBody`，
+ * `control/` 子目录按 if / 循环 / 迭代 / switch 分文件实现）。
+ */
+export { translateBlockBody } from "./control-flow.ts";
+export type { StatementDispatch } from "./control-flow.ts";
+export {
+  translateFor,
+  translateForOf,
+  translateIf,
+  translateSwitch,
+  translateWhile,
+} from "./control/index.ts";
+export { translateStatement, translateStatements } from "./statements.ts";

package/src/compiler/story-compiler/translate/stmt/statements.ts

@@ -0,0 +1,145 @@
+import * as ts from "typescript";
+import type { StoryCommand } from "@lingfan-engine/core";
+import { diag, isAssignmentOperator } from "../shared.ts";
+import type { BodyCtx } from "../shared.ts";
+import {
+  callWord,
+  emitAssignment,
+  emitCommand,
+  lowerValue,
+  loweredToScriptValue,
+  translateIncrement,
+  translateVariableStatement,
+} from "../expr/index.ts";
+import type { StatementDispatch } from "./control-flow.ts";
+import {
+  translateIf,
+  translateWhile,
+  translateFor,
+  translateForOf,
+  translateSwitch,
+} from "./control/index.ts";
+
+/** 语句递归入口：本文件即分发器，自引用注入给控制流族（见 `StatementDispatch`） */
+const DISPATCH: StatementDispatch = {
+  statement: translateStatement,
+  statements: translateStatements,
+};
+
+export function translateStatement(
+  ctx: BodyCtx,
+  stmt: ts.Statement,
+): StoryCommand[] {
+  const sf = ctx.shared.mod.sf;
+  if (ts.isVariableStatement(stmt))
+    return translateVariableStatement(ctx, stmt);
+  if (ts.isExpressionStatement(stmt)) {
+    const expr = stmt.expression;
+    if (ts.isCallExpression(expr)) return emitCommand(ctx, expr);
+    if (
+      ts.isBinaryExpression(expr) &&
+      isAssignmentOperator(expr.operatorToken.getText(sf))
+    ) {
+      return emitAssignment(
+        ctx,
+        expr,
+        expr.left,
+        expr.operatorToken.getText(sf),
+        expr.right,
+      );
+    }
+    if (ts.isPrefixUnaryExpression(expr) || ts.isPostfixUnaryExpression(expr)) {
+      return translateIncrement(ctx, expr);
+    }
+    diag(ctx, stmt, "表达式语句只能是词函数/函数调用或赋值");
+    return [];
+  }
+  if (ts.isIfStatement(stmt)) return translateIf(ctx, stmt, DISPATCH);
+  if (ts.isWhileStatement(stmt)) return translateWhile(ctx, stmt, DISPATCH);
+  if (ts.isDoStatement(stmt)) {
+    diag(ctx, stmt, "do-while 不支持：请改写为 while（先求值再循环）");
+    return [];
+  }
+  if (ts.isForStatement(stmt)) return translateFor(ctx, stmt, DISPATCH);
+  if (ts.isForOfStatement(stmt)) return translateForOf(ctx, stmt, DISPATCH);
+  if (ts.isForInStatement(stmt)) {
+    diag(ctx, stmt, "for-in 不支持：对象遍历请改用明确的状态键读取");
+    return [];
+  }
+  if (ts.isSwitchStatement(stmt)) return translateSwitch(ctx, stmt, DISPATCH);
+  if (ts.isReturnStatement(stmt)) {
+    if (!ctx.inFunction) {
+      diag(ctx, stmt, ctx.shared.texts.topLevelReturn());
+      return [];
+    }
+    if (stmt.expression !== undefined) {
+      // 带值 return：调用点用 `call into` 接收（语句级 const x = f(1) 降级形态）；
+      // 不带 into 的调用点把返回值静默丢弃（向后兼容旧故事）
+      const lowered = lowerValue(ctx, stmt.expression);
+      if (lowered === undefined) return [];
+      const op = callWord(ctx, stmt, "ret", [loweredToScriptValue(lowered)]);
+      return op === undefined ? [] : [op];
+    }
+    const op = callWord(ctx, stmt, "ret", []);
+    return op === undefined ? [] : [op];
+  }
+  if (ts.isBreakStatement(stmt)) {
+    if (stmt.label !== undefined) {
+      diag(ctx, stmt, "带标签 break 不支持");
+      return [];
+    }
+    if (ctx.breakables.length === 0) {
+      diag(ctx, stmt, ctx.shared.texts.breakOutsideLoop());
+      return [];
+    }
+    if (ctx.breakables[ctx.breakables.length - 1] === "switch") {
+      return [];
+    }
+    const op = callWord(ctx, stmt, "breakLoop", []);
+    return op === undefined ? [] : [op];
+  }
+  if (ts.isContinueStatement(stmt)) {
+    if (stmt.label !== undefined) {
+      diag(ctx, stmt, "带标签 continue 不支持");
+      return [];
+    }
+    for (let i = ctx.breakables.length - 1; i >= 0; i -= 1) {
+      if (ctx.breakables[i] === "loop") {
+        const op = callWord(ctx, stmt, "continueLoop", []);
+        return op === undefined ? [] : [op];
+      }
+    }
+    diag(ctx, stmt, ctx.shared.texts.continueOutsideLoop());
+    return [];
+  }
+  if (ts.isFunctionDeclaration(stmt)) {
+    if (stmt.body === undefined) return [];
+    diag(
+      ctx,
+      stmt,
+      "块内函数声明不支持：函数请声明在函数体/列体顶层（会前置为 func 命令）",
+    );
+    return [];
+  }
+  if (ts.isBlock(stmt)) return translateStatements(ctx, stmt.statements);
+  if (ts.isEmptyStatement(stmt)) return [];
+  if (ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt))
+    return [];
+  diag(
+    ctx,
+    stmt,
+    "此语句不支持转译（转译总表：if/while/for/for-of/switch/return/break/continue/let/赋值/调用）",
+  );
+  return [];
+}
+
+export function translateStatements(
+  ctx: BodyCtx,
+  statements: readonly ts.Statement[],
+): StoryCommand[] {
+  const out: StoryCommand[] = [];
+  for (const stmt of statements) {
+    out.push(...translateStatement(ctx, stmt));
+  }
+  return out;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * 翻译族的对上游出口（本文件与 `translate/` 目录同族，导出面与目录出口一致）。
+ */
+export type {
+  FuncRegistry,
+  Scope,
+  ScopeEntry,
+  SharedCtx,
+} from "./translate/index.ts";
+export {
+  createBodyCtx,
+  createSharedCtx,
+  makeFuncOp,
+  translateStatements,
+} from "./translate/index.ts";

package/src/compiler/story-compiler.ts

@@ -0,0 +1,119 @@
+import {
+  isSafeFileNameSegment,
+  type CharacterDef,
+  type Story,
+} from "@lingfan-engine/core";
+import type { StorySourceConfig } from "../config/story-config.ts";
+import {
+  defaultStoriesBuildTexts,
+  type StoriesBuildTexts,
+} from "../shared/index.ts";
+import {
+  buildGraph,
+  compileStoryFile,
+  createAssembleSession,
+  DiagBag,
+  resolveStart,
+  type CompileDiag,
+  type CompiledStory,
+  type Graph,
+} from "./story-compiler/index.ts";
+import type { CompilerConstValues } from "./compiler-contract.ts";
+
+export interface CompileStoriesResult {
+  stories: Array<{ columnId: string; sourceRelPath: string; story: Story }>;
+  diags: CompileDiag[];
+  entryColumnId?: string;
+}
+
+export function compileStories(input: {
+  readonly root: string;
+  readonly sourcesDir: string;
+  /** 布局声明（config.ts 求值产物；folders/start 必需）——图谱层只消费，不再解析 config */
+  readonly config: StorySourceConfig;
+  readonly stories: readonly string[];
+  readonly modules: readonly string[];
+  /** 编译期求值喂入；缺省 = 无被求值文件（行为不变） */
+  readonly constValues?: CompilerConstValues;
+  /** 字体名注册表（Resources/Fonts 文件名去扩展名）；缺省 = 空注册表，引用字体名即 fail-closed */
+  readonly fontNames?: ReadonlySet<string>;
+  /** 全工程角色表（编排层模块层声明收集产物）；缺省 = 空表，无前置角色命令 */
+  readonly characters?: ReadonlyMap<string, CharacterDef>;
+  /** 文案注入（Partial）；缺省 = 内建缺省文案（即构建层的既有文案） */
+  readonly texts?: Partial<StoriesBuildTexts>;
+}): CompileStoriesResult {
+  const texts: StoriesBuildTexts = {
+    ...defaultStoriesBuildTexts,
+    ...input.texts,
+  };
+  const diags = new DiagBag();
+  const graph = buildGraph(
+    input.sourcesDir,
+    diags,
+    input.config,
+    input.constValues,
+    texts,
+  );
+  if (graph === null) return { stories: [], diags: diags.list() };
+  const entry = resolveStart(graph, diags);
+
+  const session = createAssembleSession(
+    input.fontNames,
+    texts,
+    input.characters,
+  );
+  const stories: CompiledStory[] = [];
+  for (const rel of graph.coveredStories) {
+    const compiled = compileStoryFile(session, graph, diags, rel);
+    if (compiled !== undefined) stories.push(compiled);
+  }
+  checkColumnIds(graph, diags, stories, texts);
+
+  const list = diags.list();
+  if (list.length > 0) return { stories: [], diags: list };
+  return {
+    stories,
+    diags: [],
+    entryColumnId: entry,
+  };
+}
+
+function checkColumnIds(
+  graph: Graph,
+  diags: DiagBag,
+  stories: readonly CompiledStory[],
+  texts: StoriesBuildTexts,
+): void {
+  const seen = new Map<string, string>();
+  for (const item of stories) {
+    const record = graph.records.get(item.sourceRelPath);
+    const storyName = record?.story?.node.name;
+    if (
+      record === undefined ||
+      record.story === null ||
+      storyName === undefined
+    )
+      continue;
+    if (item.columnId === "" || !isSafeFileNameSegment(item.columnId)) {
+      diags.add(
+        record.rel,
+        record.sf,
+        storyName,
+        texts.columnIdUnsafe(item.columnId),
+      );
+      continue;
+    }
+    const lower = item.columnId.toLowerCase();
+    const prev = seen.get(lower);
+    if (prev !== undefined) {
+      diags.add(
+        record.rel,
+        record.sf,
+        storyName,
+        texts.columnIdDuplicate(item.columnId, prev),
+      );
+      continue;
+    }
+    seen.set(lower, item.sourceRelPath);
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,15 @@
+/**
+ * 配置域：工程清单与布局声明的读取、校验。
+ *
+ * 两者都是「先读工程声明，再决定后面怎么跑」的前置步骤，与源扫描
+ * 分成两域是因为清单读的是 `project.json`、布局读的是 `Stories.src/config.ts`，
+ * 校验规则各成一套，混在一个目录里只会让入口面变糊。
+ */
+export {
+  CONFIG_FILE,
+  assertSingleRootScript,
+  parseFolders,
+  parseStart,
+  type StorySourceConfig,
+} from "./story-config.ts";
+export { readManifest } from "./manifest-read.ts";

package/src/config/manifest-read.ts

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { MANIFEST_FILE } from "@lingfan-engine/core";
+import { StoryBuildError } from "../shared/index.ts";
+
+/**
+ * 读取工程清单（`<root>/<resourcesDir>/project.json`）。
+ * 清单是工程事实（entry/defines/shell），不归 TS 源管：缺文件与非法 JSON 都 fail-closed，
+ * 文案带实际路径便于作者定位自己漏了什么。
+ */
+export function readManifest(root: string, resourcesDir: string): unknown {
+  const manifestPath = join(root, resourcesDir, MANIFEST_FILE);
+  if (!existsSync(manifestPath)) {
+    throw new StoryBuildError(
+      `${resourcesDir}/${MANIFEST_FILE} 不存在——工程清单（entry/defines/shell）不归 TS 源管，请先建工程清单`,
+    );
+  }
+  const manifestText = readFileSync(manifestPath, "utf8");
+  try {
+    return JSON.parse(manifestText);
+  } catch (error) {
+    throw new StoryBuildError(
+      `${resourcesDir}/${MANIFEST_FILE} 不是合法 JSON：${String(error)}`,
+    );
+  }
+}