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

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

@@ -0,0 +1,102 @@
+import * as ts from "typescript";
+import { compareOrdinal } from "@lingfan-engine/core";
+import { script } from "@lingfan-engine/editor";
+
+export interface CompileDiag {
+  file: string;
+  line: number;
+  col: number;
+  message: string;
+}
+
+export class DiagBag {
+  private readonly items = new Map<string, CompileDiag>();
+
+  add(file: string, sf: ts.SourceFile, node: ts.Node, message: string): void {
+    this.addPos(file, sf, node.getStart(sf), message);
+  }
+
+  addPos(file: string, sf: ts.SourceFile, pos: number, message: string): void {
+    const { line, character } = sf.getLineAndCharacterOfPosition(pos);
+    const key = `${file}:${line + 1}:${character + 1}:${message}`;
+    this.items.set(key, { file, line: line + 1, col: character + 1, message });
+  }
+
+  list(): CompileDiag[] {
+    return [...this.items.values()].sort(
+      (a, b) =>
+        compareOrdinal(a.file, b.file) ||
+        a.line - b.line ||
+        a.col - b.col ||
+        compareOrdinal(a.message, b.message),
+    );
+  }
+}
+
+export type ConstValue = string | number | boolean | null;
+
+export type Binding =
+  | { kind: "word"; name: string }
+  | { kind: "namespace" }
+  | { kind: "function"; file: string; name: string }
+  | { kind: "declare"; name: string }
+  | { kind: "cell"; guard: string }
+  | { kind: "const"; value: ConstValue }
+  | { kind: "opaque" }
+  | {
+      kind: "enum";
+      file: string;
+      name: string;
+      members: ReadonlyMap<string, ConstValue>;
+    }
+  | { kind: "story"; file: string; name: string };
+
+export interface ModuleRecord {
+  rel: string;
+  sf: ts.SourceFile;
+  story: { name: string; node: ts.FunctionDeclaration } | null;
+  functions: Map<string, ts.FunctionDeclaration>;
+  bindings: Map<string, Binding>;
+  exports: Map<string, Binding>;
+  imports: ts.ImportDeclaration[];
+  consts: ts.VariableStatement[];
+  /** node_modules 值导入的本地名登记（扫描期即收集，是否放行由求值喂入决定） */
+  npmNames: Set<string>;
+  /** 编译期求值喂入：导出名 → JSON 可序列化值；未被求值的文件 = undefined */
+  evaluated?: Readonly<Record<string, unknown>>;
+  /** 列级字体声明（`export const columnFont = "<名>"`；仅故事文件合法，null = 未声明） */
+  columnFont: { value: string; node: ts.Node } | null;
+}
+
+export interface StoryConfig {
+  readonly folders: readonly string[];
+  readonly start: string;
+}
+
+export interface Graph {
+  files: Map<string, string>;
+  records: Map<string, ModuleRecord>;
+  config: StoryConfig;
+  configSf: ts.SourceFile;
+  coveredStories: string[];
+  /** 状态根名（发现自 `export declare const <根名>: StoryState`；无声明回退 "state"） */
+  readonly stateRoot: string;
+}
+
+export const ROOT_TS_FILES_ALLOWED = new Set(["config.ts"]);
+export const GEN_PREFIX = "gen/";
+
+/** 列级字体声明的保留导出名（`export const columnFont = "<名>"`，仅故事文件顶层） */
+export const COLUMN_FONT_DECL = "columnFont";
+
+export const WORD_NAMES: ReadonlySet<string> = new Set(
+  Object.keys(script).filter(
+    (k) => typeof (script as Record<string, unknown>)[k] === "function",
+  ),
+);
+
+export const DEFAULT_STATE_ROOT = "state";
+
+export function toPosix(p: string): string {
+  return p.replace(/\\/g, "/");
+}

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

@@ -0,0 +1,121 @@
+import * as ts from "typescript";
+import type { Binding, ConstValue, DiagBag } from "./core.ts";
+
+function foldNumeric(
+  op: string,
+  left: number,
+  right: number,
+): number | undefined {
+  switch (op) {
+    case "+":
+      return left + right;
+    case "-":
+      return left - right;
+    case "*":
+      return left * right;
+    case "/":
+      return right === 0 ? undefined : left / right;
+    case "%":
+      return right === 0 ? undefined : left % right;
+    default:
+      return undefined;
+  }
+}
+
+export function foldConst(
+  expr: ts.Expression,
+  sf: ts.SourceFile,
+  diags: DiagBag,
+  file: string,
+  lookup: (name: string) => Binding | undefined,
+): ConstValue | undefined {
+  if (ts.isNumericLiteral(expr)) return Number(expr.text);
+  if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr))
+    return expr.text;
+  if (expr.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (expr.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (expr.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isParenthesizedExpression(expr)) {
+    return foldConst(expr.expression, sf, diags, file, lookup);
+  }
+  if (
+    ts.isPrefixUnaryExpression(expr) &&
+    expr.operator === ts.SyntaxKind.MinusToken
+  ) {
+    const v = foldConst(expr.operand, sf, diags, file, lookup);
+    return typeof v === "number" ? -v : undefined;
+  }
+  if (ts.isTemplateExpression(expr)) {
+    const parts: string[] = [expr.head.text];
+    for (const span of expr.templateSpans) {
+      const v = foldConst(span.expression, sf, diags, file, lookup);
+      if (v === undefined) return undefined;
+      parts.push(String(v), span.literal.text);
+    }
+    return parts.join("");
+  }
+  if (ts.isBinaryExpression(expr)) {
+    const op = expr.operatorToken.getText(sf);
+    const left = foldConst(expr.left, sf, diags, file, lookup);
+    const right = foldConst(expr.right, sf, diags, file, lookup);
+    if (left === undefined || right === undefined) return undefined;
+    if (typeof left === "string" && typeof right === "string" && op === "+")
+      return left + right;
+    if (typeof left === "number" && typeof right === "number") {
+      const n = foldNumeric(op, left, right);
+      return n === undefined || Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+  }
+  if (ts.isConditionalExpression(expr)) {
+    const cond = foldConst(expr.condition, sf, diags, file, lookup);
+    if (cond === undefined) return undefined;
+    return cond
+      ? foldConst(expr.whenTrue, sf, diags, file, lookup)
+      : foldConst(expr.whenFalse, sf, diags, file, lookup);
+  }
+  if (ts.isIdentifier(expr)) {
+    const b = lookup(expr.text);
+    return b?.kind === "const" ? b.value : undefined;
+  }
+  if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.expression)) {
+    const b = lookup(expr.expression.text);
+    if (b?.kind === "enum") return b.members.get(expr.name.text);
+    return undefined;
+  }
+  return undefined;
+}
+
+export function scanEnum(
+  node: ts.EnumDeclaration,
+  sf: ts.SourceFile,
+  diags: DiagBag,
+  file: string,
+): Map<string, ConstValue> | null {
+  const members = new Map<string, ConstValue>();
+  let next = 0;
+  for (const m of node.members) {
+    const memberName = m.name.getText(sf);
+    if (m.initializer === undefined) {
+      members.set(memberName, next);
+      next += 1;
+      continue;
+    }
+    const value = foldConst(m.initializer, sf, diags, file, (n) => {
+      const v = members.get(n);
+      return v === undefined ? undefined : { kind: "const", value: v };
+    });
+    if (value === undefined) {
+      diags.add(
+        file,
+        sf,
+        m,
+        "枚举成员初始化仅支持字符串、数字字面量或已声明的枚举成员",
+      );
+      return null;
+    }
+    if (typeof value === "number") next = value + 1;
+    members.set(memberName, value);
+  }
+  return members;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * 图谱族出口：读源（`scan/`）与建图（`core.ts` / `build.ts` / `fold.ts` / `state-root.ts`）两段。
+ *
+ * 轴 = 编译流水线的第一段——先由 `scan/` 把模块读成记录，再由 `build.ts` 连成图，
+ * `fold.ts` 求常值、`state-root.ts` 定状态根；`core.ts` 只放共享形状与诊断袋。
+ */
+export type {
+  Binding,
+  CompileDiag,
+  ConstValue,
+  Graph,
+  ModuleRecord,
+  StoryConfig,
+} from "./core.ts";
+export { DiagBag, toPosix } from "./core.ts";
+export { foldConst } from "./fold.ts";
+export { buildGraph, resolveStart } from "./build.ts";

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

@@ -0,0 +1,277 @@
+import * as ts from "typescript";
+import { foldConst } from "../fold.ts";
+import { WORD_NAMES } from "../core.ts";
+import type { Binding, ConstValue, ModuleRecord, DiagBag } from "../core.ts";
+import {
+  defaultStoriesBuildTexts,
+  type StoriesBuildTexts,
+} from "../../../../shared/index.ts";
+
+export function scanConstStatement(
+  stmt: ts.VariableStatement,
+  record: ModuleRecord,
+  diags: DiagBag,
+  texts: StoriesBuildTexts = defaultStoriesBuildTexts,
+): void {
+  const { sf, rel } = record;
+  const declared =
+    stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.DeclareKeyword) ??
+    false;
+  if (declared) {
+    const decl0 = stmt.declarationList.declarations[0];
+    if (decl0 !== undefined && ts.isIdentifier(decl0.name)) {
+      const exported0 =
+        stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ??
+        false;
+      record.bindings.set(decl0.name.text, {
+        kind: "declare",
+        name: decl0.name.text,
+      });
+      if (exported0)
+        record.exports.set(decl0.name.text, {
+          kind: "declare",
+          name: decl0.name.text,
+        });
+    }
+    return;
+  }
+  const flags = ts.getCombinedNodeFlags(stmt.declarationList);
+  if ((flags & ts.NodeFlags.Const) === 0) {
+    diags.add(
+      rel,
+      sf,
+      stmt,
+      "模块层只允许 const 声明（let/var 请移入函数体，运行期为局部变量）",
+    );
+    return;
+  }
+  if (stmt.declarationList.declarations.length !== 1) {
+    diags.add(rel, sf, stmt, "模块层 const 每条语句只允许一个声明");
+    return;
+  }
+  const decl = stmt.declarationList.declarations[0];
+  if (decl.initializer === undefined) {
+    diags.add(rel, sf, decl, "模块层 const 必须带初始化");
+    return;
+  }
+  const exported =
+    stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ??
+    false;
+  const bind = (name: string, binding: Binding) => {
+    record.bindings.set(name, binding);
+    if (exported) record.exports.set(name, binding);
+  };
+
+  if (ts.isObjectBindingPattern(decl.name)) {
+    const initIdent = ts.isIdentifier(decl.initializer)
+      ? record.bindings.get(decl.initializer.text)
+      : undefined;
+    if (initIdent?.kind !== "namespace") {
+      diags.add(
+        rel,
+        sf,
+        decl.initializer,
+        "对象解构仅支持词汇层 script 命名空间：const { say, … } = script",
+      );
+      return;
+    }
+    for (const el of decl.name.elements) {
+      if (
+        !ts.isIdentifier(el.name) ||
+        el.propertyName !== undefined ||
+        el.initializer !== undefined ||
+        el.dotDotDotToken !== undefined
+      ) {
+        diags.add(
+          rel,
+          sf,
+          el,
+          "词汇层解构只支持 { a, b } 形式（不支持重命名/默认值/剩余）",
+        );
+        continue;
+      }
+      const name = el.name.text;
+      if (!WORD_NAMES.has(name)) {
+        diags.add(
+          rel,
+          sf,
+          el,
+          `词汇层不存在词 \`${name}\`（或该名称不是词函数）`,
+        );
+        continue;
+      }
+      bind(name, { kind: "word", name });
+    }
+    return;
+  }
+  if (!ts.isIdentifier(decl.name)) {
+    diags.add(rel, sf, decl, "模块层 const 不支持数组解构/绑定模式");
+    return;
+  }
+  const name = decl.name.text;
+  const init = decl.initializer;
+
+  if (ts.isCallExpression(init) && calleeWordName(init, record) === "cell") {
+    if (init.arguments.length !== 2 || !ts.isStringLiteral(init.arguments[0])) {
+      diags.add(rel, sf, init, "cell(name, impl) 第一实参必须是字符串字面量");
+      return;
+    }
+    bind(name, { kind: "cell", guard: init.arguments[0].text });
+    return;
+  }
+  if (
+    ts.isCallExpression(init) &&
+    calleeWordName(init, record) === "defineVars"
+  ) {
+    // 换道守卫（config 化）：变量键声明统一走 config.vars（config.ts 求值通道）。
+    // 图谱层不再收集 defineVars——保留 opaque 绑定只是防级联误报，键不进任何注册表。
+    diags.add(
+      rel,
+      sf,
+      init,
+      "defineVars 已迁入 config.ts（config.vars）——图谱模块里不再支持 defineVars 调用，请把变量键声明移入 Stories.src/config.ts",
+    );
+    bind(name, { kind: "opaque" });
+    return;
+  }
+  const initIdentBinding = ts.isIdentifier(init)
+    ? record.bindings.get(init.text)
+    : undefined;
+  if (initIdentBinding !== undefined) {
+    if (initIdentBinding.kind === "namespace") {
+      bind(name, { kind: "opaque" });
+      return;
+    }
+    if (initIdentBinding.kind === "const") {
+      bind(name, { kind: "const", value: initIdentBinding.value });
+      return;
+    }
+  }
+  if (ts.isPropertyAccessExpression(init) && ts.isIdentifier(init.expression)) {
+    const target = record.bindings.get(init.expression.text);
+    if (target?.kind === "namespace") {
+      bind(name, { kind: "opaque" });
+      return;
+    }
+  }
+  // —— 编译期求值喂入：导出名命中求值结果 ⇒ 直接绑定标量常量，跳过静态
+  // 折叠。结构语义分支（cell/defineVars/词解构/namespace）优先于此：同一份代码无论
+  // 是否经求值，结构绑定的解释保持一致 —— 求值只接管「常量值」这一条通道。
+  const evaluated = record.evaluated?.[name];
+  if (evaluated !== undefined) {
+    if (!isConstScalar(evaluated)) {
+      diags.add(
+        rel,
+        sf,
+        init,
+        `编译期求值导出 \`${name}\` 不是标量（string|number|boolean|null）——对象/数组等复合值不可作为常量绑定内联（编译期求值规则）`,
+      );
+      return;
+    }
+    bind(name, { kind: "const", value: evaluated });
+    return;
+  }
+  const value = foldConst(init, sf, diags, rel, (n) => record.bindings.get(n));
+  if (value === undefined) {
+    if (referencesNpmName(init, record.npmNames)) {
+      diags.add(rel, sf, init, texts.constNpmReference());
+      return;
+    }
+    diags.add(
+      rel,
+      sf,
+      init,
+      "模块层 const 必须内联为可折叠标量（字面量/常量运算/字符串拼接/三元/枚举成员/其他 const）",
+    );
+    return;
+  }
+  bind(name, { kind: "const", value });
+}
+
+function isConstScalar(value: unknown): value is ConstValue {
+  return (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    value === null
+  );
+}
+
+/**
+ * 取调用表达式指向的**词名**——`cell(...)` 与 `script.cell(...)` 在这里归一到同一个
+ * `"cell"`。声明词是绑定表里的普通词（`script` 是命名空间绑定、`cell` 是词绑定），
+ * 两条通道都得认：只认裸标识符会让命名空间写法掉进"模块层 const 必须内联为可折叠
+ * 标量"的兜底文案，离真正的原因（这是构建期声明）差着十万八千里。
+ *
+ * 返回 undefined 表示这个 callee 不指向任何已知词（普通函数调用、npm 值调用等），
+ * 交给调用点的其他分支处理。
+ */
+function calleeWordName(
+  call: ts.CallExpression,
+  record: ModuleRecord,
+): string | undefined {
+  const callee = call.expression;
+  if (ts.isIdentifier(callee)) {
+    const binding = record.bindings.get(callee.text);
+    if (binding?.kind === "word") return binding.name;
+    // `cell` 允许不经绑定直接出现（导入通道未记录时旧行为也认字面名），与 word 通道等价。
+    return callee.text === "cell" ? "cell" : undefined;
+  }
+  if (
+    ts.isPropertyAccessExpression(callee) &&
+    ts.isIdentifier(callee.expression)
+  ) {
+    const target = record.bindings.get(callee.expression.text);
+    if (target?.kind === "namespace") return callee.name.text;
+  }
+  return undefined;
+}
+
+function referencesNpmName(
+  node: ts.Node,
+  npmNames: ReadonlySet<string>,
+): boolean {
+  if (npmNames.size === 0) return false;
+  let found = false;
+  const visit = (n: ts.Node): void => {
+    if (found || ts.isTypeNode(n)) return;
+    if (ts.isIdentifier(n) && npmNames.has(n.text)) {
+      found = true;
+      return;
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(node);
+  return found;
+}
+
+/**
+ * node_modules 值导入的引用域仅限模块层 const 初始化链。
+ * 豁免：导入声明本身、模块层 const/let/var 语句（初始化链语境；非 const 由
+ * scanConstStatement 自报）、enum（scanEnum 自校验）与类型位置（与 import type
+ * 同语义）。其余引用（含函数体/default 导出体）一律报错。仅对被求值文件生效：
+ * 未求值文件的 npm 导入已在 resolveImports 处按原文案拒绝。
+ */
+export function assertNpmNamesConstOnly(
+  record: ModuleRecord,
+  diags: DiagBag,
+  texts: StoriesBuildTexts = defaultStoriesBuildTexts,
+): void {
+  if (record.npmNames.size === 0 || record.evaluated === undefined) return;
+  const { sf, rel } = record;
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isImportDeclaration(node) ||
+      ts.isVariableStatement(node) ||
+      ts.isEnumDeclaration(node)
+    )
+      return;
+    if (ts.isTypeNode(node)) return;
+    if (ts.isIdentifier(node) && record.npmNames.has(node.text)) {
+      diags.add(rel, sf, node, texts.npmNameConstOnly(node.text));
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+  for (const stmt of sf.statements) visit(stmt);
+}

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

@@ -0,0 +1,170 @@
+import * as ts from "typescript";
+import { WORD_NAMES, GEN_PREFIX, toPosix } from "../core.ts";
+import type { ModuleRecord, DiagBag } from "../core.ts";
+
+function resolveModuleFile(rel: string, spec: string): string | null {
+  const dirParts = toPosix(rel).split("/").slice(0, -1);
+  const specParts = toPosix(spec).split("/");
+  const out: string[] = [];
+  for (const part of [...dirParts, ...specParts]) {
+    if (part === "..") {
+      if (out.length === 0) return null;
+      out.pop();
+    } else if (part !== "." && part !== "") {
+      out.push(part);
+    }
+  }
+  const base = out.join("/");
+  if (base === "" || !base.endsWith(".ts")) return null;
+  return base;
+}
+
+function resolveModuleImportPath(rel: string, spec: string): string | null {
+  const candidates: string[] = [];
+  const normalized = toPosix(spec);
+  if (normalized.endsWith(".ts")) {
+    candidates.push(normalized);
+  } else {
+    candidates.push(`${normalized}.ts`, `${normalized}/index.ts`);
+  }
+  for (const c of candidates) {
+    const resolved = resolveModuleFile(rel, c);
+    if (resolved !== null) return resolved;
+  }
+  return null;
+}
+
+export function resolveImports(
+  record: ModuleRecord,
+  records: Map<string, ModuleRecord>,
+  diags: DiagBag,
+  editorPass: boolean,
+): void {
+  const { sf, rel } = record;
+  for (const imp of record.imports) {
+    const spec = ts.isStringLiteral(imp.moduleSpecifier)
+      ? imp.moduleSpecifier.text
+      : "";
+    if (editorPass !== (spec === "@lingfan-engine/editor")) continue;
+    const clause = imp.importClause;
+    if (clause === undefined) {
+      diags.add(rel, sf, imp, "副作用导入不支持：请显式导入所需符号");
+      continue;
+    }
+    if (spec === "@lingfan-engine/editor") {
+      if (clause.name !== undefined) {
+        diags.add(
+          rel,
+          sf,
+          clause.name,
+          '词汇层请以具名导入（import { say, … } from "@lingfan-engine/editor"）或 script 命名空间使用',
+        );
+      }
+      if (
+        clause.namedBindings !== undefined &&
+        ts.isNamespaceImport(clause.namedBindings)
+      ) {
+        record.bindings.set(clause.namedBindings.name.text, {
+          kind: "namespace",
+        });
+      }
+      if (
+        clause.namedBindings !== undefined &&
+        ts.isNamedImports(clause.namedBindings)
+      ) {
+        for (const el of clause.namedBindings.elements) {
+          if (el.isTypeOnly) continue;
+          // `import { script as ct }` 里 ct 是本地名、script 才是被导入的名字。判定与查表
+          // 一律用被导入名（propertyName 优先），绑定表的键才用本地名——两者混用会让
+          // `import { say as 说 }` 去查一个叫「说」的词（必然不存在）。
+          const imported = el.propertyName?.text ?? el.name.text;
+          if (imported === "script") {
+            record.bindings.set(el.name.text, { kind: "namespace" });
+            continue;
+          }
+          if (!WORD_NAMES.has(imported)) {
+            diags.add(rel, sf, el, `词汇层不存在词 \`${imported}\``);
+            continue;
+          }
+          record.bindings.set(el.name.text, { kind: "word", name: imported });
+        }
+      }
+      continue;
+    }
+    if (clause.isTypeOnly) continue;
+    if (spec === "@lingfan-engine/core") {
+      diags.add(rel, sf, imp, "引擎包不参与创作导入：请使用词汇层词函数");
+      continue;
+    }
+    if (!spec.startsWith(".")) {
+      if (record.evaluated === undefined) {
+        diags.add(
+          rel,
+          sf,
+          imp,
+          `导入仅限相对路径与词汇层既有出口，不支持外部包 \`${spec}\``,
+        );
+        continue;
+      }
+      // 经编译期求值的文件允许 node_modules 值导入——值经求值结果内联，
+      // 引用域仅限模块层 const 初始化链（buildGraph 末尾 assertNpmNamesConstOnly 兜底）。
+      continue;
+    }
+    const targetRel = resolveModuleImportPath(rel, spec);
+    if (targetRel === null) {
+      diags.add(rel, sf, imp, `模块说明符 \`${spec}\` 必须解析到相对 .ts 文件`);
+      continue;
+    }
+    if (targetRel.startsWith(GEN_PREFIX)) {
+      diags.add(rel, sf, imp, "gen/ 生成物不参与创作导入");
+      continue;
+    }
+    const target = records.get(targetRel);
+    if (target === undefined) {
+      diags.add(rel, sf, imp, `找不到模块：${spec}`);
+      continue;
+    }
+    if (clause.name !== undefined) {
+      if (target.story === null) {
+        diags.add(
+          rel,
+          sf,
+          clause.name,
+          `纯模块 ${targetRel} 没有 default 导出——跨故事引用请导入故事文件`,
+        );
+      } else {
+        record.bindings.set(clause.name.text, {
+          kind: "story",
+          file: targetRel,
+          name: target.story.name,
+        });
+      }
+    }
+    if (
+      clause.namedBindings !== undefined &&
+      ts.isNamespaceImport(clause.namedBindings)
+    ) {
+      diags.add(
+        rel,
+        sf,
+        clause.namedBindings,
+        "命名空间导入仅支持词汇层 script",
+      );
+    }
+    if (
+      clause.namedBindings !== undefined &&
+      ts.isNamedImports(clause.namedBindings)
+    ) {
+      for (const el of clause.namedBindings.elements) {
+        if (el.isTypeOnly) continue;
+        const wanted = el.propertyName?.text ?? el.name.text;
+        const binding = target.exports.get(wanted);
+        if (binding === undefined) {
+          diags.add(rel, sf, el, `模块 ${targetRel} 未导出 \`${wanted}\``);
+          continue;
+        }
+        record.bindings.set(el.name.text, binding);
+      }
+    }
+  }
+}

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

@@ -0,0 +1,9 @@
+/**
+ * 模块扫描族出口：读 TS 源、解析 import、收集常量与绑定声明。
+ *
+ * 轴 = 读源三部——扫描声明（`module-scan.ts`）、解析 import（`imports.ts`）、
+ * 收集常量与绑定（`bindings.ts`）。这一族只产出记录，不建图。
+ */
+export { assertNpmNamesConstOnly, scanConstStatement } from "./bindings.ts";
+export { resolveImports } from "./imports.ts";
+export { scanModule } from "./module-scan.ts";