@lingfan-engine/stories-build 0.1.5 → 0.3.0

package/src/shared/limits.ts

@@ -0,0 +1,17 @@
+/**
+ * 构建期追溯类算法的统一上限。
+ *
+ * 这里放的是「追到底」这类算法的步数上限：追溯目标本身不保证可达（别名链、
+ * 引用链都可能成环），不设上限就是一个必然的挂死点。上限的取值属实现细节，
+ * 但「有没有上限、上限叫什么」是跨域约定，故只在此声明一处。
+ */
+
+/**
+ * 类型别名链的最大回溯跳数。
+ *
+ * 编译器发现状态根名（沿 `type A = B` 找到 `StoryState`）与类型生成回收枚举槽位
+ * （沿别名链找到该标识符的 import 来源）都要走这条链；两者同属「沿 TS 类型别名链
+ * 追到终点，追不到就放弃」，共用同一上限。跳数耗尽即视为「追不到」，由调用方
+ * 按各自语义回退（前者回退默认根名，后者回退内联字面量联合）。
+ */
+export const MAX_ALIAS_HOPS = 10;

package/src/shared/texts.ts

@@ -50,6 +50,24 @@ export interface StoriesBuildTexts {
   npmNameConstOnly(name: string): string;
   /** config.ts 缺失（const-eval/config-eval） */
   configMissing(sourcesDirName: string, configFile: string): string;
+  /** UI 说明符落在 `src/ui/` 之外（graph/scan/imports） */
+  uiOutside(spec: string, sourceRootName: string): string;
+  /** UI 导入的绑定名与目录名不一致（graph/scan/imports） */
+  uiBindingName(name: string, received: string): string;
+  /** UI 导入的文件名与目录名不一致（graph/scan/imports） */
+  uiFileName(name: string, file: string): string;
+  /** UI 导入必须是 default 导入（graph/scan/imports） */
+  uiDefaultImport(name: string): string;
+  /** UI 注册表里没有这个句柄名（graph/scan/ui-import） */
+  uiRegisterMissing(name: string): string;
+  /** UI 注册表不接受 default 导入与命名空间导入（graph/scan/ui-import） */
+  uiRegisterNoDefault(): string;
+  /** UI 注册表的副作用导入不取任何句柄（graph/scan/ui-import） */
+  uiRegisterSideEffect(): string;
+  /** 列级 uis 指向了不存在的 UI 目录（pipeline/gates；detail = 已折叠的明细行集） */
+  unknownUisGate(detail: string, sourcesDir: string, uiDirName: string): string;
+  /** UI 文件的 import 面越界（ui/scan-imports；detail = 已折叠的明细行集） */
+  uiImportGate(detail: string, uiDirName: string): string;
 }
 
 /** 缺省文案：即 stories-build 的既有文案。 */
@@ -82,4 +100,27 @@ export const defaultStoriesBuildTexts: StoriesBuildTexts = {
     `${sourcesDirName}/${configFile} 不存在——多目录 TS 源工程需要布局声明` +
     `（export const folders/start/vars/state）：folders 声明源目录（可含 "*" 全量兜底），` +
     `start 声明入口故事文件名`,
+  uiOutside: (spec, sourceRootName) =>
+    `UI 说明符 \`${spec}\` 必须解析到 ${sourceRootName} 的兄弟目录 \`ui/<名>/<名>.<扩展名>\`` +
+    `（UI 沙箱是源根的上一级，不是源根内部）`,
+  uiBindingName: (name, received) =>
+    `UI 导入的绑定名必须是目录名（import ${name} from ".../ui/${name}/${name}.vue"），收到 \`${received}\``,
+  uiFileName: (name, file) =>
+    `UI 文件名必须等于目录名：\`ui/${name}/\` 下只能有 \`${name}.<扩展名>\`，收到 \`${file}\``,
+  uiDefaultImport: (name) =>
+    `UI 导入必须是 default 导入（import ${name} from ".../ui/${name}/${name}.vue"）——一个 UI 只导出一个句柄`,
+  uiRegisterMissing: (name) =>
+    `UI 注册表里没有 \`${name}\`——句柄名必须与 \`ui/<名>/\` 目录名一致`,
+  uiRegisterNoDefault: () =>
+    `UI 注册表没有默认导出，也没有命名空间导出：请用具名导入（import { 句柄名 } from ".../gen/ui_register.g"）`,
+  uiRegisterSideEffect: () =>
+    "UI 注册表的副作用导入不支持：它只提供句柄，请显式导入所需句柄",
+  unknownUisGate: (detail, sourcesDir, uiDirName) =>
+    `列级 uis 声明了源里不存在的 UI（宿主按名字预加载时会落空，界面要到挂载瞬间才出现）：\n${detail}\n` +
+    `→ 在 ${sourcesDir} 的兄弟目录 \`${uiDirName}/<名>/\` 下放实现文件 \`<名>.vue|.tsx|.html|.ts\`，或从列里去掉该名字`,
+  uiImportGate: (detail, uiDirName) =>
+    `UI 文件的 import 面越界（UI 不归构建管，越界依赖只能在这里拦）：\n${detail}\n` +
+    `→ ${uiDirName}/** 下的文件只允许四类：相对路径引用 ${uiDirName}/ 内的文件、` +
+    `框架包（vue / react / react-dom / react/jsx-runtime）、` +
+    `从 @lingfan-engine/core 取纯类型（import type）、别名 @/${uiDirName}/**`,
 };

package/src/story-list/index.ts

@@ -0,0 +1,2 @@
+export { scanStoryRegistry, STORY_EXTENSIONS } from "./story-registry.ts";
+export type { StoryPath } from "./story-registry.ts";

package/src/story-list/story-registry.ts

@@ -0,0 +1,55 @@
+/**
+ * 故事文件清单注册表：扫描资源根下的故事目录，得出要装载的故事逻辑路径。
+ *
+ * 清单是**磁盘事实的投影**，不是需要作者维护的声明文件。让作者手抄名单的代价不是
+ * 「多写一行」，而是漏抄时构建期毫无察觉——漏登记的那一列要到运行期才以
+ * `unknown-column` 现形。
+ *
+ * 目录名不在这里写死：资源根与故事目录名都是 `@lingfan-engine/core` 的一处声明
+ * （`RESOURCES_DIR` / `STORIES_DIR`），构建侧、引擎侧与宿主侧的扫描共用同一份判据。
+ *
+ * 两种创作形态落在同一棵树：手写 `.story` 与 TS 源编译出的 `.json` 都是故事文件，
+ * 共用这一条扫描——创作形态不改变清单的来源。
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { compareOrdinal, STORIES_DIR } from "@lingfan-engine/core";
+
+/** 故事文件扩展名：手写文本形态 `.story` 与编译产物 `.json` 都算 */
+export const STORY_EXTENSIONS = [".story", ".json"] as const;
+
+/** 故事文件清单条目：相对资源根的逻辑路径（`<故事目录>/<章节>/<文件>`） */
+export type StoryPath = string;
+
+/**
+ * 递归扫描故事目录，返回相对资源根的逻辑路径。
+ *
+ * 顺序 = 路径码元序，与引擎组装器的装载顺序同一条判据（`compareOrdinal`）——列序因此与磁盘
+ * 布局一致，不随目录读取顺序漂移。
+ *
+ * @param storiesDir 故事目录的绝对路径（资源根下的 `<STORIES_DIR>`）
+ */
+export function scanStoryRegistry(storiesDir: string): readonly StoryPath[] {
+  const out: StoryPath[] = [];
+  const walk = (dir: string, prefix: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) continue;
+      const rel = `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) {
+        walk(join(dir, entry.name), rel);
+        continue;
+      }
+      const dot = entry.name.lastIndexOf(".");
+      if (dot <= 0) continue;
+      if (
+        (STORY_EXTENSIONS as readonly string[]).includes(
+          entry.name.slice(dot).toLowerCase(),
+        )
+      ) {
+        out.push(rel);
+      }
+    }
+  };
+  if (existsSync(storiesDir)) walk(storiesDir, STORIES_DIR);
+  return out.sort(compareOrdinal);
+}

package/src/typegen/font-render.ts

@@ -1,7 +1,7 @@
 /**
  * 字体名注册表的 ambient 类型面渲染器（`font` 全局常量字面量类型）。
  *
- * 输出 = `Stories.src/gen/font.gen.d.ts` 全文：`declare const font` 的键与值都取
+ * 输出 = `src/gen/font.gen.d.ts` 全文：`declare const font` 的键与值都取
  * 注册表字体名（引号键保非标识符名可用），未注册名在 TS 面即不存在——IDE 补全只给
  * 正名，改拼直接 TS2551。纯编译期声明，不注入运行时对象；模块自有 `font` 声明按
  * TS 遮蔽语义优先。空注册表产出 `Record<never, never>`：TS 里空对象字面量 `{}` 会

package/src/typegen/index.ts

@@ -1,7 +1,7 @@
 /**
  * 类型面生成器出口（唯一出口）。
  *
- * 生成物落 `Stories.src/gen/stories.gen.d.ts`：列名与插值键在此收窄为字面量联合类型，
+ * 生成物落 `src/gen/stories.gen.d.ts`：列名与插值键在此收窄为字面量联合类型，
  * 拼错列名/插值键在 IDE 与 `tsc --noEmit` 阶段即红，而不是等运行期才发现。
  */
 export { collectDeclaredNames } from "./collect.ts";

package/src/typegen/render.ts

@@ -1,5 +1,5 @@
 /**
- * 类型面渲染：把收集好的字符串域落成 `Stories.src/gen/stories.gen.d.ts`。
+ * 类型面渲染：把收集好的字符串域落成 `src/gen/stories.gen.d.ts`。
  *
  * 生成物只做一件事——往 `@lingfan-engine/editor` 的注册表接口里塞字面量键。接口声明在词汇层，
  * 经包根再导出后才可被合并；本文件必须带 `export {};`（没有它就是全局脚本，

package/src/typegen/script-render.ts

@@ -1,7 +1,7 @@
 /**
  * script 词汇层命名空间的 ambient 类型面渲染器（免导入直呼）。
  *
- * 输出 = `Stories.src/gen/script.gen.d.ts` 全文：一条全局 `declare const script`
+ * 输出 = `src/gen/script.gen.d.ts` 全文：一条全局 `declare const script`
  * 指向 `@lingfan-engine/editor` 根出口的 `script` 命名空间类型。纯编译期声明——不注入
  * 任何运行时对象；模块层自有同名声明按 TS 遮蔽语义优先于本全局声明，显式
  * import 与解构形态（含重命名）不受影响。内容恒定、与工程状态无关，同输入逐字节同输出。

package/src/typegen/state-enum-ast.ts

@@ -25,6 +25,7 @@
  */
 import { posix } from "node:path";
 import * as ts from "typescript";
+import { MAX_ALIAS_HOPS } from "../shared/index.ts";
 
 /** 一个可 import 的枚举 type 槽位：源文件里的本地绑定名 + 模块说明符 */
 export interface EnumTypeSlot {
@@ -42,7 +43,6 @@ export interface EnumTypeSlot {
 }
 
 /** 别名回溯上限：有限跳数防环（与 module-scan 状态根别名链同思路） */
-const MAX_ALIAS_HOPS = 10;
 
 export function collectEnumTypeSlots(
   configSource: string,

package/src/typegen/state-render.ts

@@ -3,7 +3,7 @@
  *
  * 输入 = config 求值合并树（形态 A state 树 / 形态 B define 树，与降维段同一棵）+
  * AST 侧回收的枚举 type 槽位（collectEnumTypeSlotsForBuild）。输出 =
- * `Stories.src/gen/state.gen.d.ts` 全文：嵌套对象字面量的 `export type StoryState = { … }`，
+ * `src/gen/state.gen.d.ts` 全文：嵌套对象字面量的 `export type StoryState = { … }`，
  * descriptor 叶按 type 槽位取精确类型——原生标量 / 单元素数组 leaf / 多元素数组并集 /
  * 枚举引用（import type）或内联字面量联合。
  *
@@ -24,7 +24,15 @@ export interface StateTypegenInput {
   readonly tree: unknown;
   /** 点路径 → 枚举 type 槽位列表（直接槽位与并集成员槽位，collectEnumTypeSlotsForBuild 的结果） */
   readonly enumSlots: ReadonlyMap<string, EnumTypeSlot[]>;
-  /** 生成物目录名（相对源根，如 "gen"）：import 说明符按它改写相对层级 */
+  /**
+   * 源根目录（相对工程根，默认布局 `"src/Stories.src"`；源根就是工程根时省略）：
+   * 槽位的 `source` 都是源根内路径，换算说明符要一个能对齐两个基准的原点。
+   */
+  readonly sourceRootDir?: string;
+  /**
+   * 生成物目录（相对工程根，默认布局 `"src/gen"`）：与 `sourceRootDir` 同一基准，
+   * import 说明符按两者的相对位置改写。
+   */
   readonly generatedDir: string;
 }
 
@@ -40,7 +48,11 @@ export function renderStateTypegen(input: StateTypegenInput): string {
   const used = new Map<string, EnumTypeSlot>();
   const body = renderValue(input.tree, "", 0, input.enumSlots, used);
   const lines: string[] = [HEADER, ""];
-  const importLines = renderImports(used, input.generatedDir);
+  const importLines = renderImports(
+    used,
+    input.sourceRootDir ?? "",
+    input.generatedDir,
+  );
   if (importLines.length > 0) lines.push(...importLines, "");
   lines.push(`export type StoryState = ${body ?? "Record<string, never>"};`);
   return `${lines.join("\n")}\n`;
@@ -196,6 +208,7 @@ function renderEnumUnion(values: Record<string, unknown>): string {
 
 function renderImports(
   used: ReadonlyMap<string, EnumTypeSlot>,
+  sourceRootDir: string,
   generatedDir: string,
 ): string[] {
   const bySource = new Map<string, EnumTypeSlot[]>();
@@ -206,7 +219,9 @@ function renderImports(
   }
   const lines: string[] = [];
   for (const source of [...bySource.keys()].sort()) {
-    const specifier = JSON.stringify(rewriteSpecifier(source, generatedDir));
+    const specifier = JSON.stringify(
+      rewriteSpecifier(source, sourceRootDir, generatedDir),
+    );
     const slots = bySource.get(source);
     if (slots === undefined) continue;
     for (const slot of slots.filter((s) => s.importedName === "default")) {
@@ -228,12 +243,23 @@ function renderImports(
 }
 
 /**
- * import 说明符改写：源根内相对路径（"./lib/enums"）按生成物目录换算相对层级
- * （"gen" → "../lib/enums"）；包导入原样保留。
+ * import 说明符改写：槽位路径（源根内相对路径 `"./lib/enums"`）折到工程根坐标系，
+ * 再换算到生成物目录（默认布局 `src/Stories.src/lib/enums` 对 `src/gen` →
+ * `"../../Stories.src/lib/enums"`）；包导入原样保留。
+ *
+ * 两个参数必须同基准（都相对工程根）——只把生成物目录换掉而不补源根段，会算出
+ * 丢掉 `Stories.src/` 的错误路径。
  */
-function rewriteSpecifier(source: string, generatedDir: string): string {
+function rewriteSpecifier(
+  source: string,
+  sourceRootDir: string,
+  generatedDir: string,
+): string {
   if (!source.startsWith(".")) return source;
-  const rel = posix.relative(generatedDir, posix.normalize(source));
+  const target = posix.normalize(
+    posix.join(sourceRootDir === "" ? "." : sourceRootDir, source),
+  );
+  const rel = posix.relative(generatedDir, target);
   return rel.startsWith(".") ? rel : `./${rel}`;
 }
 

package/src/ui/index.ts

@@ -0,0 +1,9 @@
+export { UI_DIR_NAME, scanUiRegistry, uiNameSet } from "./ui-registry.ts";
+export type { UiFileEntry } from "./ui-registry.ts";
+export { renderUiRegister } from "./render-register.ts";
+export {
+  checkUiImports,
+  scanUiImports,
+  scanUiTreeImports,
+} from "./scan-imports.ts";
+export type { UiImportRef, UiImportViolation } from "./scan-imports.ts";

package/src/ui/render-register.ts

@@ -0,0 +1,114 @@
+/**
+ * UI 注册表生成物的渲染器（`src/gen/ui_register.g.ts` 全文）。
+ *
+ * 一个文件三段导出，三个消费方各取一段：
+ * 1. `uis` —— 「名字 → 组件」表，宿主按 `SYS.mounts` 的键去查，查到就渲染；
+ * 2. 具名句柄 `hub` —— 故事源按具名导入直接用，不依赖 `*.vue` 的 ambient 声明；
+ * 3. `declare module "@lingfan-engine/editor"` 的 `UiNameRegistry` —— 类型面，
+ *    `mount("…")` 的字符串名字写错在类型期就红。
+ *
+ * 名字的唯一来源是 `ui/<名>/` 目录名（`scanUiRegistry`），生成物里不再归一、
+ * 不再排序（扫描已排好），同一次扫描必得同一份文本 —— 差量写盘靠这一点。
+ *
+ * 注意具名句柄只对**能当标识符的名字**生成：UI 名允许 `-`（`save-panel` 合法），
+ * 那种名字没法做导出名，只能走 `uis` 表与字符串形态。这条规则写在文件头注释里，
+ * 免得作者以为生成器漏了一个。
+ */
+import type { UiFileEntry } from "./ui-registry.ts";
+
+/** TS 标识符形态（UI 名允许 `-`，那种名字没有具名句柄） */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * 渲染 `ui_register.g.ts` 全文。
+ *
+ * @param entries 扫描出的 UI 条目（已按名字排好序）
+ * @param uiRelFromGenerated 从生成物目录到 UI 根目录的相对路径（posix，无尾斜杠），
+ *   如 `"../ui"`。生成物里一律写相对路径，不写别名 —— 别名是创作期便利，
+ *   产物与生成物里出现别名就会把宿主绑死在某个 tsconfig 上。
+ */
+export function renderUiRegister(
+  entries: readonly UiFileEntry[],
+  uiRelFromGenerated: string,
+): string {
+  const lines: string[] = [];
+  const bindings = bindingsOf(entries);
+  const handleEntries = entries.filter((entry) => IDENTIFIER.test(entry.name));
+  lines.push(
+    "/* GENERATED by stories:build (ui-register) — 手改会在下次构建被覆盖 */",
+  );
+  // 没有 UI 的工程不写这一行：未使用的类型导入会让消费工程的 `noUnusedLocals` 直接红
+  if (handleEntries.length > 0) {
+    lines.push('import type { UiHandle } from "@lingfan-engine/editor";');
+  }
+  for (const entry of entries) {
+    lines.push(
+      `import ${bindings.get(entry.name)} from ${JSON.stringify(`${uiRelFromGenerated}/${entry.name}/${entry.file}`)};`,
+    );
+  }
+  lines.push("");
+  lines.push(
+    "/** 宿主用：「名字 → 组件」表。键就是 `SYS.mounts` 里的名字，不需要再归一。 */",
+  );
+  lines.push("export const uis: Record<string, unknown> = {");
+  for (const entry of entries) {
+    lines.push(`  ${JSON.stringify(entry.name)}: ${bindings.get(entry.name)},`);
+  }
+  lines.push("};");
+
+  if (handleEntries.length > 0) {
+    lines.push("");
+    lines.push(
+      '/** 故事源用：具名句柄，与 `import hub from "…/hub.vue"` 折叠出同一个名字。 */',
+    );
+    for (const entry of handleEntries) {
+      lines.push(
+        `export const ${entry.name}: UiHandle<${JSON.stringify(entry.name)}> = { face: "uis", name: ${JSON.stringify(entry.name)} };`,
+      );
+    }
+  }
+
+  // 没有 UI 的工程到此为止：类型面登记处指向 `@lingfan-engine/editor`，
+  // 而只用 `.story` 故事源的工程没有这个依赖（它是故事源 TS 层带进来的），
+  // 空表里也没有任何名字可登记——多写一段只会让那种工程解析不到模块。
+  if (entries.length === 0) return `${lines.join("\n")}\n`;
+
+  lines.push("");
+  lines.push(
+    '/** UI 名的构建期登记处：`mount("…")` 引用了未登记的名字会在类型期报错。 */',
+  );
+  lines.push('declare module "@lingfan-engine/editor" {');
+  lines.push("  interface UiNameRegistry {");
+  for (const entry of entries) {
+    lines.push(`    ${JSON.stringify(entry.name)}: 1;`);
+  }
+  lines.push("  }");
+  lines.push("}");
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * 每个 UI 的组件导入绑定名。
+ *
+ * 不能直接用 UI 名：具名句柄 `export const hub` 已经占住了那个标识符，
+ * 同名的两个声明会重复；而且 UI 名允许 `-`（`save-panel` 合法），
+ * 那种名字根本不能当标识符。所以统一加 `View` 后缀，非法字符换成 `_`，
+ * 撞名再按出现次序加数字（同一次扫描结果稳定，文本才可差量比较）。
+ */
+function bindingsOf(
+  entries: readonly UiFileEntry[],
+): ReadonlyMap<string, string> {
+  const taken = new Set<string>();
+  const out = new Map<string, string>();
+  for (const entry of entries) {
+    const base = entry.name.replace(/[^A-Za-z0-9_$]/g, "_");
+    const seed = /^[A-Za-z_$]/.test(base) ? base : `_${base}`;
+    let candidate = `${seed}View`;
+    for (let n = 2; taken.has(candidate); n += 1) {
+      candidate = `${seed}View${n}`;
+    }
+    taken.add(candidate);
+    out.set(entry.name, candidate);
+  }
+  return out;
+}