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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2026 MoFeng-02
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/bin/stories-build.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * `lingfan-stories-build` 可执行入口（bin 垫片，Node 直接执行）。
+ *
+ * 为什么需要这层垫片：本包以 TypeScript 源码出口（`exports` 指向 `./src/*.ts`），
+ * 而 Node 的类型擦除**拒绝加载 node_modules 里的 .ts**（ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING）
+ * ——装了本包的工程既不能 `node` 直跑 `src/cli/cli.ts`，也不该被迫装一整套构建链。
+ * 这层垫片用本包自带依赖 `tsx` 装载真实 CLI，转调 `runBuildCli`，呈现逻辑仍然只有一份。
+ *
+ * 用法：`lingfan-stories-build [工程根]`；缺省工程根 = 工作目录（可由 DSH_STORIES_ROOT 覆盖）。
+ */
+import { tsImport } from "tsx/esm/api";
+
+const { runBuildCli } = await tsImport("../src/cli/cli.ts", import.meta.url);
+const code = await runBuildCli(process.argv.slice(2));
+if (code !== 0) process.exit(code);

package/bin/stories-watch.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * `lingfan-stories-watch` 可执行入口（bin 垫片，Node 直接执行）。
+ *
+ * 与 `stories-build.mjs` 同一层理由：本包以 TypeScript 源码出口，而 Node 的类型擦除拒绝
+ * 加载 node_modules 里的 .ts；垫片用本包自带依赖 `tsx` 装载真实 CLI，转调 `startWatchCli`。
+ *
+ * 用法：`lingfan-stories-watch [工程根]`；缺省工程根 = 工作目录（可由 DSH_STORIES_ROOT 覆盖）。
+ */
+import { tsImport } from "tsx/esm/api";
+
+const { startWatchCli } = await tsImport(
+  "../src/cli/watch-cli.ts",
+  import.meta.url,
+);
+await startWatchCli(process.argv.slice(2));

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@lingfan-engine/stories-build",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.2",
+  "type": "module",
+  "description": "Stories 创作链编译包：把 Stories.src 的多目录原生 TS 源编译成 Resources/Stories/** + project.json，并产出 cell 注册生成物",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": "./src/index.ts",
+    "./authoring": "./src/authoring.d.ts",
+    "./cell": "./src/cell/index.ts",
+    "./cli": "./src/cli/cli.ts",
+    "./watch": "./src/pipeline/watch.ts",
+    "./watch-cli": "./src/cli/watch-cli.ts"
+  },
+  "bin": {
+    "lingfan-stories-build": "./bin/stories-build.mjs",
+    "lingfan-stories-watch": "./bin/stories-watch.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "!src/**/*.test.ts"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@lingfan-engine/core": "^0.1.2",
+    "@lingfan-engine/editor": "^0.1.2",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.23.15",
+    "typescript": "~6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoFeng-02/LingFan.Engine.git",
+    "directory": "packages/stories-build"
+  },
+  "homepage": "https://github.com/MoFeng-02/LingFan.Engine#readme",
+  "bugs": {
+    "url": "https://github.com/MoFeng-02/LingFan.Engine/issues"
+  },
+  "keywords": [
+    "narrative",
+    "build",
+    "story-compiler",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/authoring.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 源侧创作垫片（随包 .d.ts）
+ * 三组声明，各管一件事：
+ *
+ * - `state`：编译器保留根，按名匹配（assign/expr 的 stateRoot），不产生绑定。
+ *   此处给宽索引签名（StateRoot），保证未接 gen 类型面的工程 tsc 通过；精确类型面
+ *   由构建产物 `gen/state.gen.d.ts` 从 config 合并树生成，工程桥文件
+ *   `import type { StoryState } from …/gen/state.gen` 后按名挂根（形态 A 亦可用
+ *   `InferStateSchema<typeof state>` 静态推导）。宽 StateRoot 仅为该桥缺省前的回退。
+ * - `jump`：真身通道 = `@lingfan-engine/editor` 词汇层词（词表出口 + emitWordCommand 特判
+ *   → emitJump）；本声明只为 IDE/类型检查补齐，不改变运行时通道。
+ * - `define` / `defineVars`：config.ts 构建期内建（求值环境注入，无运行时实体）；
+ *   全局声明供 config.ts 书写与 tsc 通过。
+ * - `StoriesConfig`：config.ts default 对象形态的类型（declare global，零 import 全局可用）；
+ *   `satisfies StoriesConfig` 给 default 导出强校验与 IDE 键名补全。
+ */
+import type { StoryCommand } from "@lingfan-engine/core";
+
+export interface StateRoot {
+  // 宽索引签名是未接 gen 桥工程的缺省回退：gen/state.gen.d.ts 已提供精确 StoryState，
+  // 桥文件引它后本接口即不参与；回退存在是为了「还没写桥」的消费工程能直接写
+  // state.player.gold += 20，unknown 做不到这一点。
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any;
+}
+
+export declare const state: StateRoot;
+
+export declare function jump(target: string | (() => void)): StoryCommand;
+
+declare global {
+  /** 形态 B：点路径或对象字面量声明初始 defines（构建期累积；同键二次定义 fail-closed）。 */
+  function define(path: string, value: unknown): void;
+  function define(spec: Record<string, unknown>): void;
+  /** 变量键声明：返回实参本身（键 = 插值键注册表的 defineKeys 域贡献）。 */
+  function defineVars<T extends Record<string, string>>(spec: T): T;
+
+  /** config.ts default 对象的键契约（folders/start 必需；version/vars/state 可缺省）。 */
+  interface StoriesConfig {
+    /** 嗯，这个是你故事的目录，我让它支持你可以这样一个扫递归，也支持多目录，看你自己需要 */
+    readonly folders: readonly string[];
+    /** 这个是你需要启动的故事，注意它对应的是你 `export default function 我是故事名称` 的这个我是故事名称，哦，这个名字你自己取 */
+    readonly start: string;
+    /** 顾名思义版本 */
+    readonly version?: number;
+    /** 这个是你需要注册的变量键，注意它对应的是你 `defineVars` 的这个 defineVars，你也可以defineVars */
+    readonly vars?: Record<string, string>;
+    /** 这个是你需要注册的状态，注意它对应的是你 `state` 的这个 state，你也可以define，都可以的 */
+    readonly state?: Record<string, unknown>;
+  }
+}

package/src/cell/errors.ts

@@ -0,0 +1,12 @@
+/** cell 声明提取失败（带 `origin` 定位：`相对路径:行`）——由调用方决定是否中断构建 */
+export class CellExtractError extends Error {
+  /** 定位：`相对路径:行`，由构造参数赋值 */
+  readonly origin: string;
+
+  /** 文案拼装：定位前置成「`相对路径:行` —— 消息」，日志一眼看到出处。 */
+  constructor(message: string, origin: string) {
+    super(`${origin} —— ${message}`);
+    this.origin = origin;
+    this.name = "CellExtractError";
+  }
+}

package/src/cell/imports.ts

@@ -0,0 +1,127 @@
+import * as ts from "typescript";
+import type { CellIssue, FileImports } from "./types.ts";
+
+/**
+ * 字面量内自由标识符校验：全部 Identifier 必须 ∈（参数、内部声明、导入绑定与全局白名单的并集），
+ * 属性位置（`ctx.get` 的 `get`）不算自由标识符。flat 集（不做作用域链——影子同名属
+ * 已注记的伪接受边界，v1 不为它上作用域机）。
+ */
+export function checkFreeIdentifiers(
+  impl: ts.Node,
+  origin: string,
+  importedNames: ReadonlySet<string>,
+  globalWhitelist: ReadonlySet<string>,
+  issues: CellIssue[],
+): void {
+  const allowed = new Set<string>([...globalWhitelist, ...importedNames]);
+  const free = new Set<string>();
+  const visit = (node: ts.Node): void => {
+    // 声明与参数：名字进 allowed，继续递归初始化/函数体
+    if (ts.isParameter(node) || ts.isVariableDeclaration(node)) {
+      if (ts.isIdentifier(node.name)) allowed.add(node.name.text);
+    } else if (
+      ts.isFunctionDeclaration(node) ||
+      ts.isClassDeclaration(node) ||
+      ts.isMethodDeclaration(node)
+    ) {
+      if (node.name !== undefined && ts.isIdentifier(node.name))
+        allowed.add(node.name.text);
+    }
+    if (ts.isIdentifier(node)) {
+      const parent = node.parent;
+      const isPropertyName =
+        parent !== undefined &&
+        ((ts.isPropertyAccessExpression(parent) && parent.name === node) ||
+          (ts.isQualifiedName(parent) && parent.right === node) ||
+          (ts.isPropertyAssignment(parent) && parent.name === node));
+      if (!isPropertyName && !allowed.has(node.text)) free.add(node.text);
+    }
+    node.forEachChild(visit);
+  };
+  visit(impl);
+  if (free.size > 0) {
+    issues.push({
+      message: `cell 内联实现引用了未导入的标识符（${[...free].map((n) => `"${n}"`).join("、")}）——把实现提为 import，或内联其依赖（不做传递闭包）`,
+      origin,
+    });
+  }
+}
+
+/** 节点所在行号（1 起；读取 AST 只做定位，不改变任何判定） */
+export function lineOf(sf: ts.SourceFile, node: ts.Node): number {
+  return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}
+
+/**
+ * 相对说明符重写：源文件（相对 Stories.src 的目录 `fromDir`）→ 生成物（`gen/`，恰深一层）。
+ * 解析到 Stories.src 内的规范相对路径后加 `../` 前缀；越出根 = null（调用方 fail-closed）；
+ * 裸说明符（包名）原样。
+ */
+export function adjustSpecifier(
+  specifier: string,
+  fromDir: string,
+): string | null {
+  if (!specifier.startsWith("./") && !specifier.startsWith("../"))
+    return specifier;
+  const segments: string[] = [];
+  for (const part of `${fromDir}/${specifier}`.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      if (segments.pop() === undefined) return null; // 越出 Stories.src 根
+      continue;
+    }
+    segments.push(part);
+  }
+  if (segments.length === 0) return null;
+  return `../${segments.join("/")}`;
+}
+
+/** 文件顶层 import 声明 → 绑定名集 + 「按 gen/ 位置重写过」的语句文本 */
+export function collectFileImports(
+  sf: ts.SourceFile,
+  text: string,
+  fromDir: string,
+  issues: CellIssue[],
+  relPath: string,
+): FileImports {
+  const statements: Array<{ adjustedText: string; bindings: string[] }> = [];
+  const bindingNames = new Set<string>();
+  for (const statement of sf.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    const bindings: string[] = [];
+    const clause = statement.importClause;
+    if (clause !== undefined) {
+      if (clause.name !== undefined) bindings.push(clause.name.text); // import X from
+      const named = clause.namedBindings;
+      if (named !== undefined && ts.isNamedImports(named)) {
+        for (const element of named.elements) bindings.push(element.name.text);
+      }
+      if (named !== undefined && ts.isNamespaceImport(named)) {
+        bindings.push(named.name.text); // import * as X
+      }
+    }
+    for (const binding of bindings) bindingNames.add(binding);
+    // 说明符重写（生成物在 gen/，比源文件深一层）
+    const raw = statement.moduleSpecifier;
+    let adjustedText = text.slice(statement.getStart(sf), statement.getEnd());
+    if (ts.isStringLiteralLike(raw)) {
+      const adjusted = adjustSpecifier(raw.text, fromDir);
+      if (adjusted === null) {
+        issues.push({
+          message: `cell 所在文件 import "${raw.text}" 越出 Stories.src——生成物无法搬运该导入`,
+          origin: `${relPath}:${lineOf(sf, statement)}`,
+        });
+        continue;
+      }
+      if (adjusted !== raw.text) {
+        const rawQuoted = text.slice(raw.getStart(sf), raw.getEnd());
+        adjustedText = adjustedText.replace(
+          rawQuoted,
+          JSON.stringify(adjusted),
+        );
+      }
+    }
+    statements.push({ adjustedText, bindings });
+  }
+  return { bindingNames, statements };
+}

package/src/cell/index.ts

@@ -0,0 +1,33 @@
+/**
+ * cell 声明提取器出口（唯一出口）：把 `Stories.src/**` 树里的 `cell("name", impl)` 调用
+ * 扫成生成注册物所需的实现文本与导入搬运集，流水线（包内 `pipeline` 域）只从这里取。
+ *
+ * 「名字在数据、实现在代码、build 做名字闭合」的提取半边。规则硬点：
+ * - 实现三形态：箭头/函数字面量（原文落生成物）、标识符引用、成员访问引用；
+ *   **调用表达式（参数固化）= L2，v1 显式不支持**；
+ * - 字面量内自由标识符必须 ∈（所在文件导入绑定、函数参数、内部声明与标准全局的并集），
+ *   引用模块级本地 const = fail-closed（**不做传递闭包**——规则简单才可靠）；
+ * - 身份键 = (face, name)、指纹 = 实现文本 trim：**同键同纹去重、同键异纹冲突**
+ *   （fail-closed 带两处定位，不隐式覆盖）；
+ * - face v1 恒 `guards`；`cell` 只认裸标识符调用（house style 解构导入）；
+ * - **导入搬运按生成物位置重写相对说明符**：生成物在 `Stories.src/gen/`（比源文件
+ *   深一层），`"./x"`/`"../x"` 必须换算到同一目标——越出 `Stories.src` 根 fail-closed。
+ */
+
+/** cell 声明提取失败（带 `origin` 定位：`相对路径:行`）——由调用方决定是否中断构建 */
+export { CellExtractError } from "./errors.ts";
+/** 单文件扫描：`cell(...)` 三类实现形态判定与逐条 fail-closed 文案 */
+export { rootIdentifier, scanFile } from "./scan-file.ts";
+/** 全树扫描：去重、指纹冲突、导入搬运 */
+export { scanCells } from "./scan-cells.ts";
+/** 生成物渲染（文本逐字节确定） */
+export { renderFunRegister } from "./render-register.ts";
+/** 标准全局白名单（16 项），供调用方比对或拼接自己的白名单 */
+export { DEFAULT_GLOBAL_WHITELIST } from "./whitelist.ts";
+/** 提取产出、问题与可配置项的形状 */
+export type {
+  CellIssue,
+  CellScan,
+  FileImports,
+  ScanCellsOptions,
+} from "./types.ts";

package/src/cell/render-register.ts

@@ -0,0 +1,33 @@
+import type { CellScan } from "./types.ts";
+
+/** 生成物渲染（逐字节确定：同扫描同文本；入库文件，手改会被覆盖） */
+export function renderFunRegister(scan: CellScan): string {
+  const lines: string[] = [];
+  lines.push(
+    "/* GENERATED by stories:build (cell) — 手改会在下次构建被覆盖 */",
+  );
+  // Record<string, GuardFn> 给字面量参数提供语境类型（strict 下无 implicit-any）
+  lines.push('import type { GuardFn } from "@lingfan-engine/core";');
+  for (const statement of scan.importStatements) lines.push(statement);
+  lines.push("");
+  lines.push(
+    "/** 故事源 cell 提取出的具名守卫注册表：宿主 `import { guards }` 直接传给引擎，零手写接入。 */",
+  );
+  lines.push("export const guards: Record<string, GuardFn> = {");
+  for (const guardEntry of scan.guards) {
+    lines.push(`  ${JSON.stringify(guardEntry.name)}: ${guardEntry.implText},`);
+  }
+  lines.push("};");
+  lines.push("");
+  lines.push(
+    "/** 守卫名的构建期登记处：故事源 `guard(name)` 引用了未登记的名字会在类型期报错。 */",
+  );
+  lines.push('declare module "@lingfan-engine/editor" {');
+  lines.push("  interface GuardNameRegistry {");
+  for (const guardEntry of scan.guards) {
+    lines.push(`    ${JSON.stringify(guardEntry.name)}: 1;`);
+  }
+  lines.push("  }");
+  lines.push("}");
+  return `${lines.join("\n")}\n`;
+}

package/src/cell/scan-cells.ts

@@ -0,0 +1,63 @@
+import { scanFile } from "./scan-file.ts";
+import type { CellIssue, CellScan, ScanCellsOptions } from "./types.ts";
+import { DEFAULT_GLOBAL_WHITELIST } from "./whitelist.ts";
+
+/**
+ * 全树扫描 + 聚合去重/冲突（输入 = 相对路径 → 文本；不含 gen/，由调用方过滤）。
+ * 同名同实现合并为一条；同名不同实现按冲突 fail-closed（不隐式覆盖）。
+ * `options.globalWhitelist` 缺省 = 标准全局白名单，给别的名字要显式注入。
+ */
+export function scanCells(
+  files: ReadonlyMap<string, string>,
+  options: ScanCellsOptions = {},
+): { errors: CellIssue[]; scan: CellScan } {
+  const globalWhitelist = options.globalWhitelist ?? DEFAULT_GLOBAL_WHITELIST;
+  const issues: CellIssue[] = [];
+  const byName = new Map<
+    string,
+    { name: string; implText: string; origin: string }
+  >();
+  const importsInOrder: string[] = [];
+  const seenImports = new Set<string>();
+
+  for (const [relPath, text] of files) {
+    for (const found of scanFile(relPath, text, globalWhitelist, issues)) {
+      const existing = byName.get(found.name);
+      if (existing === undefined) {
+        byName.set(found.name, {
+          name: found.name,
+          implText: found.implText,
+          origin: `${relPath} (cell "${found.name}")`,
+        });
+      } else if (existing.implText.trim() !== found.fingerprint) {
+        issues.push({
+          message: `cell "${found.name}" 同名不同实现（冲突）——换名字或统一实现（已有：${existing.origin}）`,
+          origin: `${relPath} (cell "${found.name}")`,
+        });
+      }
+      // 导入搬运：该 cell 所在文件中「声明了实现文本引用到的绑定」的语句（词边界匹配）
+      const needed = [...found.imports.bindingNames].filter((binding) =>
+        new RegExp(`\\b${binding}\\b`).test(found.implText),
+      );
+      for (const statement of found.imports.statements) {
+        if (!statement.bindings.some((binding) => needed.includes(binding)))
+          continue;
+        if (!seenImports.has(statement.adjustedText)) {
+          seenImports.add(statement.adjustedText);
+          importsInOrder.push(statement.adjustedText);
+        }
+      }
+    }
+  }
+
+  return {
+    errors: issues,
+    scan: {
+      guards: [...byName.values()].map(({ name, implText }) => ({
+        name,
+        implText,
+      })),
+      importStatements: importsInOrder,
+    },
+  };
+}