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

package/src/compiler/story-compiler/graph/scan/module-scan.ts

@@ -0,0 +1,199 @@
+import * as ts from "typescript";
+import { scanEnum } from "../fold.ts";
+import type { Binding, DiagBag, ModuleRecord } from "../core.ts";
+
+/**
+ * 模块语句扫描：把单个 .ts 模块的顶层语句归类登记进 ModuleRecord
+ * （导入/导出/函数/enum/const/构建期 define 与角色声明/故事 default 导出），
+ * 遇到不支持的语句形态记诊断。状态根名发现独立在 ./state-root.ts。
+ */
+
+/**
+ * node_modules 值导入的本地名登记：扫描期即收集（scanConstStatement
+ * 先于第二遍导入解析运行，const 初始化链的专用提示在登记时就要可用）。是否放行
+ * 该导入由 resolveImports 依求值喂入决定；`import type` 与纯类型元素不登记。
+ */
+function collectNpmNames(
+  record: ModuleRecord,
+  imp: ts.ImportDeclaration,
+): void {
+  const spec = ts.isStringLiteral(imp.moduleSpecifier)
+    ? imp.moduleSpecifier.text
+    : "";
+  if (
+    spec.startsWith(".") ||
+    spec === "@lingfan-engine/editor" ||
+    spec === "@lingfan-engine/core"
+  )
+    return;
+  const clause = imp.importClause;
+  if (clause === undefined || clause.isTypeOnly) return;
+  if (clause.name !== undefined) record.npmNames.add(clause.name.text);
+  if (
+    clause.namedBindings !== undefined &&
+    ts.isNamespaceImport(clause.namedBindings)
+  ) {
+    record.npmNames.add(clause.namedBindings.name.text);
+  }
+  if (
+    clause.namedBindings !== undefined &&
+    ts.isNamedImports(clause.namedBindings)
+  ) {
+    for (const el of clause.namedBindings.elements) {
+      if (el.isTypeOnly) continue;
+      record.npmNames.add(el.propertyName?.text ?? el.name.text);
+    }
+  }
+}
+
+export function scanModule(record: ModuleRecord, diags: DiagBag): void {
+  const { sf, rel } = record;
+  for (const stmt of sf.statements) {
+    if (ts.isImportDeclaration(stmt)) {
+      record.imports.push(stmt);
+      collectNpmNames(record, stmt);
+      continue;
+    }
+    if (ts.isExportDeclaration(stmt)) {
+      if (
+        stmt.moduleSpecifier !== undefined ||
+        stmt.exportClause === undefined ||
+        !ts.isNamedExports(stmt.exportClause)
+      ) {
+        diags.add(rel, sf, stmt, "转发导出不支持：请直接从来源模块导入");
+        continue;
+      }
+      for (const el of stmt.exportClause.elements) {
+        const wanted = el.propertyName?.text ?? el.name.text;
+        const binding = record.bindings.get(wanted);
+        if (binding === undefined) {
+          diags.add(rel, sf, el, `本地未声明 \`${wanted}\`，无法导出`);
+          continue;
+        }
+        record.exports.set(el.name.text, binding);
+      }
+      continue;
+    }
+    if (ts.isExportAssignment(stmt)) {
+      if (stmt.isExportEquals) {
+        diags.add(rel, sf, stmt, "不支持 export = 形式");
+        continue;
+      }
+      if (
+        ts.isFunctionDeclaration(stmt.expression) &&
+        stmt.expression.name !== undefined &&
+        stmt.expression.body !== undefined
+      ) {
+        record.story = {
+          name: stmt.expression.name.text,
+          node: stmt.expression,
+        };
+      } else {
+        diags.add(
+          rel,
+          sf,
+          stmt,
+          "default 导出必须是具名函数声明：export default function 名字() { … }",
+        );
+      }
+      continue;
+    }
+    if (ts.isFunctionDeclaration(stmt)) {
+      if (stmt.name === undefined) continue;
+      const hasDefault =
+        stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword) ??
+        false;
+      if (hasDefault) {
+        if (stmt.body === undefined) {
+          diags.add(
+            rel,
+            sf,
+            stmt,
+            "default 导出必须是具名函数声明：export default function 名字() { … }",
+          );
+          continue;
+        }
+        record.story = { name: stmt.name.text, node: stmt };
+        continue;
+      }
+      if (stmt.body === undefined) {
+        const declared: Binding = { kind: "declare", name: stmt.name.text };
+        record.bindings.set(stmt.name.text, declared);
+        if (
+          stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+        ) {
+          record.exports.set(stmt.name.text, declared);
+        }
+        continue;
+      }
+      const binding: Binding = {
+        kind: "function",
+        file: rel,
+        name: stmt.name.text,
+      };
+      record.functions.set(stmt.name.text, stmt);
+      record.bindings.set(stmt.name.text, binding);
+      if (stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+        record.exports.set(stmt.name.text, binding);
+      }
+      continue;
+    }
+    if (ts.isEnumDeclaration(stmt)) {
+      const members = scanEnum(stmt, sf, diags, rel);
+      if (members === null) continue;
+      const binding: Binding = {
+        kind: "enum",
+        file: rel,
+        name: stmt.name.text,
+        members,
+      };
+      record.bindings.set(stmt.name.text, binding);
+      if (stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+        record.exports.set(stmt.name.text, binding);
+      }
+      continue;
+    }
+    if (ts.isVariableStatement(stmt)) {
+      record.consts.push(stmt);
+      continue;
+    }
+    if (ts.isExpressionStatement(stmt) && isBuildDefineStatement(stmt)) {
+      continue; // 构建期 define 语句：由模块层收集器求值合并，图谱层不展开
+    }
+    if (ts.isExpressionStatement(stmt) && isBuildCharacterStatement(stmt)) {
+      continue; // 构建期角色声明：由模块层收集器求值前置，图谱层不展开
+    }
+    if (
+      ts.isInterfaceDeclaration(stmt) ||
+      ts.isTypeAliasDeclaration(stmt) ||
+      ts.isModuleDeclaration(stmt) ||
+      stmt.kind === ts.SyntaxKind.ImportEqualsDeclaration
+    ) {
+      continue;
+    }
+    diags.add(
+      rel,
+      sf,
+      stmt,
+      "模块层不支持此语句：只允许 const/函数/enum/导入/类型声明/default 导出、构建期 define 与构建期角色声明",
+    );
+  }
+}
+
+/** 顶层 `define(…)` 表达式语句（构建期合并树词；参数合法性由收集器判定） */
+function isBuildDefineStatement(stmt: ts.ExpressionStatement): boolean {
+  return (
+    ts.isCallExpression(stmt.expression) &&
+    ts.isIdentifier(stmt.expression.expression) &&
+    stmt.expression.expression.text === "define"
+  );
+}
+
+/** 顶层 `character(…)` 表达式语句（构建期角色声明；参数合法性由收集器判定） */
+function isBuildCharacterStatement(stmt: ts.ExpressionStatement): boolean {
+  return (
+    ts.isCallExpression(stmt.expression) &&
+    ts.isIdentifier(stmt.expression.expression) &&
+    stmt.expression.expression.text === "character"
+  );
+}

package/src/compiler/story-compiler/graph/state-root.ts

@@ -0,0 +1,147 @@
+/**
+ * 状态根名发现（SSOT）：全树唯一的 `export declare const <根名>: StoryState`
+ * （或 ambient 桥 `declare global { var <根名>: StoryState }`，注解均可是本文件
+ * type 别名链）决定源侧状态前缀，转译剥根按该名进行。无声明回退 DEFAULT_STATE_ROOT；
+ * 根名与词函数冲突、或多个异名声明并存 → fail-closed 诊断（定位声明处）。
+ */
+import * as ts from "typescript";
+import { DEFAULT_STATE_ROOT, WORD_NAMES } from "./core.ts";
+import type { DiagBag, ModuleRecord } from "./core.ts";
+
+const STATE_ROOT_ANNOTATION = "StoryState";
+const MAX_ALIAS_HOPS = 10;
+
+interface StateRootCandidate {
+  rel: string;
+  sf: ts.SourceFile;
+  node: ts.Node;
+  name: string;
+}
+
+/** 本文件 type 别名表：别名 → 目标注解文本（仅无限定标识符；限定名与复合类型不是候选注解） */
+function collectStateAliases(sf: ts.SourceFile): Map<string, string> {
+  const aliases = new Map<string, string>();
+  for (const stmt of sf.statements) {
+    if (!ts.isTypeAliasDeclaration(stmt)) continue;
+    const target =
+      ts.isTypeReferenceNode(stmt.type) && ts.isIdentifier(stmt.type.typeName)
+        ? stmt.type.typeName.text
+        : undefined;
+    if (target !== undefined) aliases.set(stmt.name.text, target);
+  }
+  return aliases;
+}
+
+function resolvesToStateAnnotation(
+  name: string,
+  aliases: ReadonlyMap<string, string>,
+): boolean {
+  let cur = name;
+  for (let hop = 0; hop <= MAX_ALIAS_HOPS; hop += 1) {
+    if (cur === STATE_ROOT_ANNOTATION) return true;
+    const next = aliases.get(cur);
+    if (next === undefined) return false;
+    cur = next;
+  }
+  return false;
+}
+
+/** 单声明的状态根判形：恰一声明、标识符名、标识符 TypeReference 注解且解析到 StoryState */
+function stateRootDeclaration(
+  stmt: ts.VariableStatement,
+  aliases: ReadonlyMap<string, string>,
+): { name: string; decl: ts.VariableDeclaration } | undefined {
+  if (stmt.declarationList.declarations.length !== 1) return undefined;
+  const decl = stmt.declarationList.declarations[0];
+  if (!ts.isIdentifier(decl.name) || decl.type === undefined) return undefined;
+  const annotation =
+    ts.isTypeReferenceNode(decl.type) && ts.isIdentifier(decl.type.typeName)
+      ? decl.type.typeName.text
+      : undefined;
+  if (
+    annotation === undefined ||
+    !resolvesToStateAnnotation(annotation, aliases)
+  ) {
+    return undefined;
+  }
+  return { name: decl.name.text, decl };
+}
+
+/**
+ * 状态根候选扫描：两种拼写都算声明——
+ * 1. 顶层 `export declare const <根名>: StoryState`（直接形态）；
+ * 2. ambient 全局增补块 `declare global { var <根名>: StoryState }`（桥文件形态：
+ *    根名不进模块作用域，只挂全局，供运行期裸名访问；块内无需 export/declare 修饰）。
+ */
+function scanStateRootCandidates(
+  rel: string,
+  sf: ts.SourceFile,
+): StateRootCandidate[] {
+  const candidates: StateRootCandidate[] = [];
+  const aliases = collectStateAliases(sf);
+  for (const stmt of sf.statements) {
+    if (!ts.isVariableStatement(stmt)) continue;
+    const modifiers = stmt.modifiers ?? [];
+    if (!modifiers.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))
+      continue;
+    if (!modifiers.some((m) => m.kind === ts.SyntaxKind.DeclareKeyword))
+      continue;
+    const found = stateRootDeclaration(stmt, aliases);
+    if (found === undefined) continue;
+    candidates.push({ rel, sf, node: found.decl, name: found.name });
+  }
+  for (const stmt of sf.statements) {
+    // declare global 的名字节点是普通 Identifier（"global"），用 GlobalAugmentation
+    // 旗标判别增补块（TS 6.0 AST：name.kind 仍为 Identifier）。
+    if (!ts.isModuleDeclaration(stmt)) continue;
+    if ((stmt.flags & ts.NodeFlags.GlobalAugmentation) === 0) continue;
+    if (stmt.body === undefined || !ts.isModuleBlock(stmt.body)) continue;
+    for (const inner of stmt.body.statements) {
+      if (!ts.isVariableStatement(inner)) continue;
+      const found = stateRootDeclaration(inner, aliases);
+      if (found === undefined) continue;
+      candidates.push({ rel, sf, node: found.decl, name: found.name });
+    }
+  }
+  return candidates;
+}
+
+export function discoverStateRoot(
+  records: ReadonlyMap<string, ModuleRecord>,
+  diags: DiagBag,
+): string {
+  const found: StateRootCandidate[] = [];
+  for (const record of records.values()) {
+    found.push(...scanStateRootCandidates(record.rel, record.sf));
+  }
+  const byName = new Map<string, StateRootCandidate>();
+  for (const candidate of found) {
+    if (!byName.has(candidate.name)) byName.set(candidate.name, candidate);
+  }
+  if (byName.size === 0) return DEFAULT_STATE_ROOT;
+  if (byName.size > 1) {
+    const names = [...byName.keys()]
+      .sort()
+      .map((n) => `\`${n}\``)
+      .join("、");
+    for (const candidate of byName.values()) {
+      diags.add(
+        candidate.rel,
+        candidate.sf,
+        candidate.node,
+        `状态根声明不唯一（${names}）：只允许一个 \`export declare const <根名>: ${STATE_ROOT_ANNOTATION}\`（ambient 桥为 \`var <根名>: ${STATE_ROOT_ANNOTATION}\`）`,
+      );
+    }
+    return DEFAULT_STATE_ROOT;
+  }
+  const [name, candidate] = [...byName.entries()][0];
+  if (WORD_NAMES.has(name)) {
+    diags.add(
+      candidate.rel,
+      candidate.sf,
+      candidate.node,
+      `状态根名 \`${name}\` 与词汇层词函数冲突：请另选标识符（\`export declare const <根名>: ${STATE_ROOT_ANNOTATION}\`）`,
+    );
+  }
+  return name;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * 图谱族的对上游出口（本文件与 `graph/` 目录同族，导出面与目录出口一致）。
+ */
+export type {
+  Binding,
+  CompileDiag,
+  ConstValue,
+  Graph,
+  ModuleRecord,
+  StoryConfig,
+} from "./graph/index.ts";
+export {
+  buildGraph,
+  DiagBag,
+  foldConst,
+  resolveStart,
+  toPosix,
+} from "./graph/index.ts";

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

@@ -0,0 +1,34 @@
+/**
+ * story-compiler 族出口：图谱、装配、翻译三个部分的对外面。
+ *
+ * 轴 = 编译流水线三段——先建图（`graph.ts`）、再装配（`assemble.ts`）、表达式与语句翻译（`translate.ts`）。
+ */
+export type {
+  Binding,
+  CompileDiag,
+  ConstValue,
+  Graph,
+  ModuleRecord,
+  StoryConfig,
+} from "./graph.ts";
+export {
+  buildGraph,
+  DiagBag,
+  foldConst,
+  resolveStart,
+  toPosix,
+} from "./graph.ts";
+export type { CompiledStory } from "./assemble.ts";
+export { compileStoryFile, createAssembleSession } from "./assemble.ts";
+export type {
+  FuncRegistry,
+  Scope,
+  ScopeEntry,
+  SharedCtx,
+} from "./translate.ts";
+export {
+  createBodyCtx,
+  createSharedCtx,
+  makeFuncOp,
+  translateStatements,
+} from "./translate.ts";

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

@@ -0,0 +1,204 @@
+import * as ts from "typescript";
+import type { StoryCommand } from "@lingfan-engine/core";
+import {
+  diag,
+  lookupBinding,
+  lookupScope,
+  lookupOwnScope,
+  declareLocal,
+} from "../shared.ts";
+import type { BodyCtx } from "../shared.ts";
+import { statePath } from "./state-path.ts";
+import { lowerValue, loweredToScriptValue } from "./expr.ts";
+import {
+  callWord,
+  emitCallCommand,
+  resolveFunctionCallee,
+} from "./words/index.ts";
+
+function assignmentTarget(
+  ctx: BodyCtx,
+  expr: ts.Expression,
+):
+  | { kind: "local"; name: string }
+  | { kind: "state"; path: string }
+  | undefined {
+  if (ts.isIdentifier(expr)) {
+    if (expr.text === ctx.shared.stateRoot) {
+      diag(
+        ctx,
+        expr,
+        `${ctx.shared.stateRoot} 必须以成员路径使用：${ctx.shared.stateRoot}.gold`,
+      );
+      return undefined;
+    }
+    const own = lookupOwnScope(ctx, expr.text);
+    if (own !== undefined) {
+      if (own.kind !== "let" && own.kind !== "param") {
+        diag(
+          ctx,
+          expr,
+          `赋值目标 \`${expr.text}\` 必须是已声明的 let 局部变量`,
+        );
+        return undefined;
+      }
+      return { kind: "local", name: expr.text };
+    }
+    if (lookupScope(ctx, expr.text) !== undefined) {
+      // 运行时 letVar 只声明进当前函数帧（外层变量原样不动），跨层赋值必然是假写入 → 构建期拦截
+      diag(
+        ctx,
+        expr,
+        `不能在内层函数给外层变量 \`${expr.text}\` 赋值：内层赋值只会声明内层新变量，不会写回外层`,
+      );
+      return undefined;
+    }
+    diag(ctx, expr, `赋值目标 \`${expr.text}\` 必须是已声明的 let 局部变量`);
+    return undefined;
+  }
+  if (ts.isPropertyAccessExpression(expr)) {
+    const target = statePath(ctx, expr);
+    if (target === undefined) return undefined;
+    if (target.optional) {
+      // 写位置不允许缺失语义（optGet 只读），fail-closed
+      diag(ctx, expr, `赋值目标不支持可选链：${target.path}`);
+      return undefined;
+    }
+    return { kind: "state", path: target.path };
+  }
+  diag(
+    ctx,
+    expr,
+    `赋值目标只能是 let 局部变量或 ${ctx.shared.stateRoot} 单层路径`,
+  );
+  return undefined;
+}
+
+function compoundValue(
+  ctx: BodyCtx,
+  node: ts.Node,
+  op: string,
+  rhs: ts.Expression,
+): string | undefined {
+  const lowered = lowerValue(ctx, rhs);
+  if (lowered === undefined) return undefined;
+  if (lowered.kind === "lit" && typeof lowered.value !== "number") {
+    diag(ctx, node, "复合赋值右侧必须是数值");
+    return undefined;
+  }
+  const rhsText = lowered.kind === "lit" ? String(lowered.value) : lowered.text;
+  return `${op} {${rhsText}}`;
+}
+
+export function emitAssignment(
+  ctx: BodyCtx,
+  node: ts.Node,
+  target: ts.Expression,
+  op: string,
+  rhs: ts.Expression,
+): StoryCommand[] {
+  const resolved = assignmentTarget(ctx, target);
+  if (resolved === undefined) return [];
+  const word = resolved.kind === "state" ? "set" : "letVar";
+  const key = resolved.kind === "state" ? resolved.path : resolved.name;
+  let value: string | number | boolean;
+  if (op === "=") {
+    const lowered = lowerValue(ctx, rhs);
+    if (lowered === undefined) return [];
+    value = loweredToScriptValue(lowered);
+  } else {
+    const compound = compoundValue(ctx, node, op, rhs);
+    if (compound === undefined) return [];
+    value = compound;
+  }
+  const op2 = callWord(ctx, node, word, [key, value]);
+  return op2 === undefined ? [] : [op2];
+}
+
+export function translateIncrement(
+  ctx: BodyCtx,
+  expr: ts.PrefixUnaryExpression | ts.PostfixUnaryExpression,
+): StoryCommand[] {
+  const op =
+    expr.operator === ts.SyntaxKind.PlusPlusToken
+      ? "+="
+      : expr.operator === ts.SyntaxKind.MinusMinusToken
+        ? "-="
+        : undefined;
+  if (op === undefined) {
+    diag(ctx, expr, "自增/自减只支持 ++ 与 --");
+    return [];
+  }
+  return emitAssignment(
+    ctx,
+    expr,
+    expr.operand,
+    op,
+    ts.factory.createNumericLiteral("1"),
+  );
+}
+
+// —— 语句转译 ——
+
+export function translateVariableStatement(
+  ctx: BodyCtx,
+  stmt: ts.VariableStatement,
+): StoryCommand[] {
+  const out: StoryCommand[] = [];
+  for (const decl of stmt.declarationList.declarations) {
+    if (!ts.isIdentifier(decl.name)) {
+      diag(ctx, decl, "解构声明不支持：数组请用 newArray 词、对象请用 dict 词");
+      continue;
+    }
+    if (decl.initializer === undefined) {
+      diag(ctx, decl, "局部变量声明必须带初始化（引擎没有未初始化的槽位）");
+      continue;
+    }
+    if (ts.isArrayLiteralExpression(decl.initializer)) {
+      diag(ctx, decl.initializer, "数组字面量不支持：请用 newArray 词");
+      continue;
+    }
+    if (ts.isObjectLiteralExpression(decl.initializer)) {
+      diag(ctx, decl.initializer, "对象字面量不支持：请用 dict 词");
+      continue;
+    }
+    // 语句级 `const x = f(1)` / `let x = f(1)`：子程序调用的**唯一**取值形态——
+    // 降级为 `call into`（结果绑定名），引擎把返回值声明成本地变量。表达式位
+    // （say 插值、赋值右值）仍拒绝：求值是命令内同步一步，中途不能挂起等 call 返回。
+    if (ts.isCallExpression(decl.initializer)) {
+      const fn = resolveFunctionCallee(ctx, decl.initializer);
+      if (fn !== undefined) {
+        const op = emitCallCommand(ctx, decl.initializer, fn, decl.name.text);
+        if (op !== undefined) out.push(op);
+        // 声明放在发射之后：实参在当前作用域里求值，不读这个新名字
+        declareLocal(ctx, decl.name.text, { kind: "let" });
+        continue;
+      }
+      // 未解析的具名 callee：与命令位同文案。值位置那句「请用语句级 const x = f(1)」
+      // 对已经在语句级的写法是错误指路，这里必须报出真实病因
+      if (ts.isIdentifier(decl.initializer.expression)) {
+        const calleeName = decl.initializer.expression.text;
+        if (
+          lookupBinding(ctx, calleeName) === undefined &&
+          lookupScope(ctx, calleeName) === undefined
+        ) {
+          diag(
+            ctx,
+            decl.initializer,
+            `未知调用目标 \`${calleeName}\`（须是词函数或声明的函数）`,
+          );
+          continue;
+        }
+      }
+    }
+    const lowered = lowerValue(ctx, decl.initializer);
+    if (lowered === undefined) continue;
+    declareLocal(ctx, decl.name.text, { kind: "let" });
+    const op = callWord(ctx, decl, "letVar", [
+      decl.name.text,
+      loweredToScriptValue(lowered),
+    ]);
+    if (op !== undefined) out.push(op);
+  }
+  return out;
+}

package/src/compiler/story-compiler/translate/expr/engine-text.ts

@@ -0,0 +1,16 @@
+/**
+ * 引擎文本字面量的渲染：把构建期已知值写成引擎源码里的字面量文本。
+ */
+export function quoteEngineString(text: string): string {
+  const escaped = text
+    .replace(/\\/g, "\\\\")
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t")
+    .replace(/"/g, '\\"');
+  return `"${escaped}"`;
+}
+
+export function engineValueText(value: string | number | boolean): string {
+  return typeof value === "string" ? quoteEngineString(value) : String(value);
+}