@lingfan-engine/stories-build 0.2.0 → 0.3.0

package/src/pipeline/orchestrate.ts

@@ -1,22 +1,28 @@
-import { join } from "node:path";
+import { join, posix } from "node:path";
 import {
+  RESOURCES_DIR,
   STORIES_DIR,
   type Story,
   type StoryColumn,
 } from "@lingfan-engine/core";
 import { TS_SOURCE_MANIFEST_KEY } from "@lingfan-engine/editor";
 import {
+  DEFAULT_GENERATED_DIR,
   defaultStoriesBuildTexts,
   StoryBuildError,
   type StoriesBuildTexts,
 } from "../shared/index.ts";
-import { assertKnownGuards, assertKnownOps } from "./gates.ts";
+import {
+  assertKnownGuards,
+  assertKnownOps,
+  assertKnownUis,
+  assertUiImports,
+} from "./gates.ts";
 import { scanCellSources } from "../compiler/index.ts";
 import { runConstEvalPass } from "../const-eval/index.ts";
 import { assertRoundTrip, compileStory } from "../emit/index.ts";
 import {
   loadDefaultCompiler,
-  type CompiledStoryEntry,
   type StoriesCompiler,
 } from "../compiler/index.ts";
 import { emitArtifacts } from "../emit/index.ts";
@@ -29,7 +35,6 @@ import {
   evalConfigModule,
   mergeDefineCallsInto,
   runStateSchemaPass,
-  type LocatedDefineCall,
 } from "../const-eval/index.ts";
 import { discoverSources } from "../discovery/index.ts";
 import {
@@ -37,6 +42,13 @@ import {
   fontNameSet,
   scanFontRegistry,
 } from "../fonts/index.ts";
+import {
+  UI_DIR_NAME,
+  renderUiRegister,
+  scanUiRegistry,
+  scanUiTreeImports,
+  uiNameSet,
+} from "../ui/index.ts";
 import {
   collectDeclaredNames,
   collectEnumTypeSlotsForBuild,
@@ -47,13 +59,23 @@ import {
 } from "../typegen/index.ts";
 import { walkFiles } from "../shared/index.ts";
 import { DEFAULT_EVAL_TIMEOUT_MS } from "../const-eval/index.ts";
+import { loadPathsConfig } from "./tsconfig-paths.ts";
+import {
+  mergeDefines,
+  moduleSlotFiles,
+  raiseFormAConflict,
+  readCompiledEntry,
+} from "./merge.ts";
+import { createAliasResolver } from "../compiler/story-compiler/graph/scan/alias.ts";
+import { createUiChannel } from "../compiler/story-compiler/graph/scan/ui-specifier.ts";
+import { UI_REGISTER_BASENAME } from "../compiler/story-compiler/graph/core.ts";
 
 /** 构建产物的目录名与生成物文件名（默认值 = 参考宿主的现状目录名） */
-export const DEFAULT_SOURCES_DIR = "Stories.src";
-/** 资源目录名（相对工程根）：清单与 `Stories/**` 产物落在这下面。 */
-export const DEFAULT_RESOURCES_DIR = "Resources";
-/** 生成物目录名（相对源目录）：`fun_register.g.ts` 落在这里。 */
-export const DEFAULT_GENERATED_DIR = "gen";
+export const DEFAULT_SOURCES_DIR = "src/Stories.src";
+/** 资源目录名（相对工程根）：权威声明在引擎契约的 `RESOURCES_DIR`（此处别名转发） */
+export { RESOURCES_DIR as DEFAULT_RESOURCES_DIR } from "@lingfan-engine/core";
+/** 生成物目录名：权威声明在 `shared/generated-dir.ts`（此处只转发，保持包出口不变） */
+export { DEFAULT_GENERATED_DIR } from "../shared/index.ts";
 
 /**
  * 构建的可配置项：只列目录名这类工程布局事实（把同一工程挪到别的目录名只改这里）。
@@ -64,7 +86,7 @@ export interface StoryBuildOptions {
   readonly sourcesDir?: string;
   /** 资源目录名（相对工程根；清单与 `Stories/**` 都住在它下面） */
   readonly resourcesDir?: string;
-  /** 生成物目录名（相对源目录；`fun_register.g.ts` 落在这里） */
+  /** 生成物目录名（相对源根的父目录；`fun_register.g.ts` 落在这里） */
   readonly generatedDir?: string;
   /** 编译器注入（过渡期/测试用）；缺省 = 装载 `compiler` 域的默认实现 */
   readonly compiler?: StoriesCompiler;
@@ -84,6 +106,8 @@ const STATE_TYPEGEN_FILE = "state.gen.d.ts";
 const SCRIPT_TYPEGEN_FILE = "script.gen.d.ts";
 /** font 字面量类型面文件名（字体名注册表的键=值收窄面，内容随注册表） */
 const FONT_TYPEGEN_FILE = "font.gen.d.ts";
+/** UI 注册表生成物文件名（宿主「名字→组件」表 + 故事源具名句柄 + 类型面，内容随注册表） */
+const UI_REGISTER_FILE = `${UI_REGISTER_BASENAME}.ts`;
 
 /**
  * 编译 `root/Stories.src/` 下的 TS 源 → `root/Resources/`（纯编排，fs 全在参数 root 之下；
@@ -106,7 +130,7 @@ export async function buildStories(
   options: StoryBuildOptions = {},
 ): Promise<BuildReport> {
   const sourcesDirName = options.sourcesDir ?? DEFAULT_SOURCES_DIR;
-  const resourcesDirName = options.resourcesDir ?? DEFAULT_RESOURCES_DIR;
+  const resourcesDirName = options.resourcesDir ?? RESOURCES_DIR;
   const generatedDirName = options.generatedDir ?? DEFAULT_GENERATED_DIR;
   // 文案与求值时限：入口处一次性合并/取缺省，下游各段只收完整对象/数值（纯透传）
   const texts: StoriesBuildTexts = {
@@ -115,10 +139,42 @@ export async function buildStories(
   };
   const evalTimeoutMs = options.evalTimeoutMs ?? DEFAULT_EVAL_TIMEOUT_MS;
 
+  // 生成物目录相对工程根（默认布局 = `src/gen`）：源根名与其父目录在这里一次算清，
+  // 下游只收成品字符串。`posix.dirname("Stories.src")` = "."，故源根在工程根时
+  // 生成物仍落在 `gen/`——旧布局的路径同样由这套算法得出，不留分支。
+  const generatedRelRoot = posix.join(
+    posix.dirname(sourcesDirName),
+    generatedDirName,
+  );
+  // cell 搬运 import 说明符时要从生成物目录回指源根：两个目录都由工程根算出，
+  // 这里一次性折成相对路径（默认布局 = `"../Stories.src"`）传给扫描段。
+  const cellRootPrefix = posix.relative(generatedRelRoot, sourcesDirName);
+
   const sourcesDir = join(root, sourcesDirName);
   const resourcesDir = join(root, resourcesDirName);
   const storiesDir = join(resourcesDir, STORIES_DIR);
 
+  // 作者写的别名来自工程自己的 `tsconfig.json`：一次构建读一次，后续各段共用同一份形状。
+  // 缺失或无 `paths` ⇒ `null`，退化为纯相对路径（宿主零配置也能跑）。
+  const pathsConfig = loadPathsConfig(root);
+
+  // UI 根与源根是兄弟目录：同一套「谁在哪」的推导只在这里做一次，
+  // 扫描段与闸门文案都从这两个值出发。
+  const uiDirName = UI_DIR_NAME;
+  const uiRelRoot = posix.join(posix.dirname(sourcesDirName), uiDirName);
+  const uiRoot = join(root, uiRelRoot);
+  // 生成物里一律写相对路径（不写别名）：别名是创作期便利，一旦进生成物就把宿主
+  // 绑死在某个 tsconfig 上。默认布局下 `src/gen` 回指 `src/ui` 得 `"../ui"`。
+  const uiRelFromGenerated = posix.relative(generatedRelRoot, uiRelRoot);
+  // 注册表只读文件系统、不依赖编译，故先于通道扫描：通道要用它回答「这条具名
+  // 导入指向哪个 UI 文件」，晚一步就查不到。
+  const uiEntries = scanUiRegistry(uiRoot);
+
+  // 别名解析器与 UI 通道都在这里一次造好：UI 文件住在源根的兄弟目录 `src/ui/`，
+  // 它的沙箱比模块导入宽一级，两个消费者（cell 搬运、故事编译）共用同一份判定。
+  const alias = createAliasResolver(pathsConfig, sourcesDir);
+  const uiChannel = createUiChannel(sourcesDir, alias, uiEntries);
+
   // —— config.ts 单次求值：named exports 四导出（folders/start/vars/state）+ 形态 B
   // define 累积一并取出；布局校验（parseFolders/parseStart）、define 合并冲突与
   // 形态 A/B 互斥全部 fail-closed（读取统一走本通道，图谱层不再解析 config）——
@@ -140,7 +196,13 @@ export async function buildStories(
   // —— cell 声明扫描（构建期 AST 扫描）：源树（排除生成物目录，仅 .ts；机制不动）。
   // 源树同时是模块层 define 收集与枚举槽位回收的输入（只读复用，不重扫）——
   const sourceTree = walkFiles(sourcesDir);
-  const cellScan = scanCellSources(sourceTree, generatedDirName);
+  const cellScan = scanCellSources(
+    sourceTree,
+    generatedDirName,
+    cellRootPrefix,
+    // UI 句柄导入由 UI 通道处置：它不进生成物、也不受源根沙箱约束。
+    (_fromRel, spec) => uiChannel.classify(_fromRel, spec).kind !== "not-ui",
+  );
 
   // —— 编译期求值：含 node_modules 值导入的文件整体求值，导出常量值喂给
   // 编译器内联；求值诊断与双求值确定性闸门 fail-closed，一次报全部 ——
@@ -151,6 +213,7 @@ export async function buildStories(
     sourcesDirName,
     texts,
     evalTimeoutMs,
+    pathsConfig,
   );
 
   // —— 模块层构建期 define 收集与汇入：源模块顶层 define 语句（函数体外）AST 折叠，
@@ -163,14 +226,7 @@ export async function buildStories(
     generatedDirName,
   });
   if (evaluated.state !== undefined && moduleDefineCalls.length > 0) {
-    throw new StoryBuildError(
-      [
-        `${sourcesDirName}/${CONFIG_FILE}: 形态 A（state 导出）与模块层构建期 define 互斥——形态 A/B 二选一：`,
-        ...moduleDefineCalls.map(
-          (call) => `- ${call.origin}${defineLabel(call)}`,
-        ),
-      ].join("\n"),
-    );
+    raiseFormAConflict(sourcesDirName, CONFIG_FILE, moduleDefineCalls);
   }
   const moduleDefineConflicts = mergeDefineCallsInto(
     evaluated.defineTree,
@@ -207,6 +263,7 @@ export async function buildStories(
   const fontNames = fontNameSet(fontEntries);
 
   // —— story-compiler：故事/模块清单一次性编译（诊断非空 = fail-closed，一次报全部）——
+  // 别名解析器在上面已造好，这里直接复用（读配置与展开候选都在 `tsconfig-paths.ts`）。
   const compiler = options.compiler ?? (await loadDefaultCompiler());
   const compiled = await compiler.compileStories({
     root,
@@ -217,6 +274,8 @@ export async function buildStories(
     constValues,
     fontNames,
     characters: moduleCharacters,
+    alias,
+    uiRegistry: uiEntries,
     texts,
   });
   if (compiled.diags.length > 0) {
@@ -271,6 +330,7 @@ export async function buildStories(
   const gateOptions = {
     resourcesDir: resourcesDirName,
     sourcesDir: sourcesDirName,
+    uiDirName,
     texts,
   };
   // —— op 闸门与守卫名闸门（两条 fail-early 判定，各自带定位一次报全部）——
@@ -280,6 +340,12 @@ export async function buildStories(
     new Set(cellScan.guards.map((guard) => guard.name)),
     gateOptions,
   );
+  // —— 列级 uis 闸门：产物里声明的 UI 名必须在源里真有实现文件 ——
+  // 与导入期同一条落位规则（`ui/<名>/<名>.<扩展名>`），此处只核存在性。
+  assertKnownUis(merged, uiNameSet(uiEntries), gateOptions);
+  // —— UI import 面闸门：`src/ui/**` 的越界依赖在构建期一次报全 ——
+  // UI 不进编译链，宿主打包器又拦不住反向依赖，这里是唯一的观测点。
+  assertUiImports(scanUiTreeImports(uiRoot, uiEntries), gateOptions);
 
   // —— 编译与往返自检（config.start → project.json entry 由托管键更新落地）——
   const serialized = compileStory(merged, markedManifest);
@@ -308,7 +374,8 @@ export async function buildStories(
       configSource: sourceTree.get(CONFIG_FILE) ?? "",
       moduleFiles: moduleSlotFiles(sourceTree, moduleDefineCalls),
     }),
-    generatedDir: generatedDirName,
+    sourceRootDir: sourcesDirName,
+    generatedDir: generatedRelRoot,
   });
 
   // —— script 命名空间 ambient 声明（免导入直呼）：内容恒定、与工程状态无关，
@@ -319,30 +386,38 @@ export async function buildStories(
   // 空注册表恒产出封闭空对象，未注册名在 TS 面不可见（改拼即 TS2551）——
   const fontTypegenContent = renderFontTypegen(fontEntries);
 
+  // —— UI 注册表生成物：三段导出（宿主 uis 表 / 故事源具名句柄 / UiNameRegistry）。
+  // 恒产出：没有 UI 时 `uis` 是空表、句柄段整段省略，宿主与类型面都还有形状可引 ——
+  const uiRegisterContent = renderUiRegister(uiEntries, uiRelFromGenerated);
+
   // —— 差量写盘 + 生成物（逻辑路径，相对资源根）——
   const { added, updated, removed } = emitArtifacts({
     root,
     resourcesDir,
     storiesDir,
-    generatedRel: `${sourcesDirName}/${generatedDirName}/${GENERATED_FILE}`,
+    generatedRel: `${generatedRelRoot}/${GENERATED_FILE}`,
     serialized,
     cellScan,
     typegen: {
-      rel: `${sourcesDirName}/${generatedDirName}/${TYPEGEN_FILE}`,
+      rel: `${generatedRelRoot}/${TYPEGEN_FILE}`,
       content: typegenContent,
     },
     stateGen: {
-      rel: `${sourcesDirName}/${generatedDirName}/${STATE_TYPEGEN_FILE}`,
+      rel: `${generatedRelRoot}/${STATE_TYPEGEN_FILE}`,
       content: stateTypegenContent,
     },
     scriptGen: {
-      rel: `${sourcesDirName}/${generatedDirName}/${SCRIPT_TYPEGEN_FILE}`,
+      rel: `${generatedRelRoot}/${SCRIPT_TYPEGEN_FILE}`,
       content: scriptTypegenContent,
     },
     fontGen: {
-      rel: `${sourcesDirName}/${generatedDirName}/${FONT_TYPEGEN_FILE}`,
+      rel: `${generatedRelRoot}/${FONT_TYPEGEN_FILE}`,
       content: fontTypegenContent,
     },
+    uiGen: {
+      rel: `${generatedRelRoot}/${UI_REGISTER_FILE}`,
+      content: uiRegisterContent,
+    },
   });
 
   return {
@@ -357,103 +432,3 @@ export async function buildStories(
     warnings: drainBuildWarnings(),
   };
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** 互斥文案里的一条调用签名（path 形带键名；spec 形统一签名） */
-function defineLabel(call: LocatedDefineCall): string {
-  return call.call.kind === "path"
-    ? `define("${call.call.path}")`
-    : "define({…})";
-}
-
-/** 枚举槽位回收的模块源文（按调用落点去重排序；树里缺文本的文件跳过） */
-function moduleSlotFiles(
-  sourceTree: ReadonlyMap<string, string>,
-  calls: readonly { rel: string }[],
-): Map<string, string> {
-  const files = new Map<string, string>();
-  for (const rel of [...new Set(calls.map((call) => call.rel))].sort()) {
-    const text = sourceTree.get(rel);
-    if (text !== undefined) files.set(rel, text);
-  }
-  return files;
-}
-
-/**
- * 编译条目防御读取：取条目列（columnId 必须在产物列集中）、回填产物 sourcePath、
- * 复核 story 骨架（columns 列集 + id/entry 字符串）。更深的合法性（列 id 安全段、
- * 重复、entry 存在性等）交给 serializeProject/assembleProject 既有校验兜底。
- */
-function readCompiledEntry(
-  entry: CompiledStoryEntry,
-  sourcesDirName: string,
-): { story: Story; column: StoryColumn } {
-  const sourceLabel = `${sourcesDirName}/${entry.sourceRelPath}`;
-  if (!isRecord(entry.story) || !Array.isArray(entry.story.columns)) {
-    throw new StoryBuildError(
-      `${sourceLabel}: 编译器条目 story 缺少列集（compileStories 契约破坏）`,
-    );
-  }
-  const column = entry.story.columns.find(
-    (item) => isRecord(item) && item.id === entry.columnId,
-  );
-  if (column === undefined) {
-    throw new StoryBuildError(
-      `${sourceLabel}: 编译器条目 columnId "${entry.columnId}" 不在产物列集中（compileStories 契约破坏）`,
-    );
-  }
-  if (
-    typeof entry.story.id !== "string" ||
-    entry.story.id === "" ||
-    typeof entry.story.entry !== "string" ||
-    entry.story.entry === ""
-  ) {
-    throw new StoryBuildError(
-      `${sourceLabel}: 编译器条目 story 缺少 id/entry（compileStories 契约破坏）`,
-    );
-  }
-  const story = entry.story as unknown as Story;
-  const typedColumn = column as unknown as StoryColumn;
-  typedColumn.sourcePath = `${STORIES_DIR}/${entry.sourceRelPath.replace(/\.ts$/, ".json")}`;
-  return { story, column: typedColumn };
-}
-
-/**
- * 跨来源的 defines 合并：同键同值收敛，同键异值 = 冲突 fail-closed（一次报全部）。
- * 来源 = config 状态（config 先行：形态 A state 或形态 B define 合并树）+ 各故事文件；
- * config 与故事同键异值同样冲突。
- */
-function mergeDefines(
-  bySource: ReadonlyMap<string, { story: Story; columns: StoryColumn[] }>,
-  sourcesDirName: string,
-  schemaDefines: Record<string, unknown> = {},
-): Record<string, unknown> {
-  const merged: Record<string, unknown> = {};
-  const conflicts: string[] = [];
-  const put = (key: string, value: unknown, source: string): void => {
-    if (key in merged && merged[key] !== value) {
-      conflicts.push(
-        `- defines["${key}"] 在 ${sourcesDirName}/${source} 与先前的声明不一致（${JSON.stringify(merged[key])} ≠ ${JSON.stringify(value)}）`,
-      );
-      return;
-    }
-    merged[key] = value;
-  };
-  for (const [key, value] of Object.entries(schemaDefines)) {
-    put(key, value, "config.ts（state/define）");
-  }
-  for (const [source, { story }] of bySource) {
-    for (const [key, value] of Object.entries(story.defines ?? {})) {
-      put(key, value, source);
-    }
-  }
-  if (conflicts.length > 0) {
-    throw new StoryBuildError(
-      `跨故事文件的 defines 冲突（工程级 defines 只有一份，请统一到工程清单或消除同名异值）：\n${conflicts.join("\n")}`,
-    );
-  }
-  return merged;
-}

package/src/pipeline/tsconfig-paths.ts

@@ -0,0 +1,196 @@
+import { dirname, isAbsolute, resolve } from "node:path";
+import * as ts from "typescript";
+
+/**
+ * 工程 tsconfig 的 `compilerOptions.paths` 读取与展开（构建期，Node 侧）。
+ *
+ * 别名不是本引擎的规定：作者在工程 `tsconfig.json` 里写什么（`@/*`、`@ui/*`、`~/*`
+ * 任意形态），stories-build 就认什么。本文件只做两件事——把工程配置读成结构化形状
+ * （`loadPathsConfig`），把一条说明符展开成候选绝对路径（`expandAlias`）。
+ *
+ * 为什么不借 tsc 的 `matchPatternOrExact` / `tryParsePatterns`：两个函数不在
+ * `typescript.d.ts` 的公开面，TypeScript 升级后可能改名或消失（运行期还在，编译期不可见）。
+ * 通配匹配本身就是「前缀 + 后缀 + 最长前缀胜出」，自己实现才能长期稳定。读配置仍走公开
+ * API（`readConfigFile` + `parseJsonConfigFileContent`）。
+ *
+ * 注意事项：
+ * - 解析顺序不在这里定。调用方按「相对路径 → 引擎包 → 别名 → 不支持外部包」判定，
+ *   本文件只回答「这条说明符能展开成哪些绝对路径」。
+ * - 不遍历工程目录：解析时把 host 的 `readDirectory` 换成返回空数组，耗时与工程体量无关。
+ * - 只有 `paths` 才算别名来源，不做「没配 paths 就按约定猜前缀」的推断。
+ * - 目标模板里的 `*` 按命中段替换；`baseDir` 取**声明 paths 的那个 tsconfig 所在目录**
+ *   （子级覆盖 ⇒ 子目录，父级声明 ⇒ 父目录）；显式 `baseUrl` 优先按 baseUrl。
+ * - `extends` 只跟随相对路径与绝对路径形态；包名形态的 extends 不追（退化为工程根目录），
+ *   这类工程很少见且没有可靠的本地解析入口。
+ */
+
+/** 工程根 tsconfig 文件名（只读这一个文件，不向上/向下找） */
+const TSCONFIG_FILE = "tsconfig.json";
+
+/** 一条 `paths` 条目：通配键拆成前缀 + 后缀，精确键只按字符串全等命中 */
+export interface PathsPattern {
+  readonly prefix: string;
+  readonly suffix: string;
+  /** 目标模板（可含 `*`，按声明序） */
+  readonly targets: readonly string[];
+  /** 键里带 `*` ⇒ 通配模式；否则是精确键 */
+  readonly wildcard: boolean;
+}
+
+/** 工程 `paths` 的结构化形状：`baseDir` 是目标模板的基准目录（绝对路径） */
+export interface PathsConfig {
+  readonly patterns: readonly PathsPattern[];
+  readonly baseDir: string;
+}
+
+/**
+ * 读 `root/tsconfig.json` 的 `compilerOptions.paths`。
+ * 文件缺失、读不动或没有 `paths` ⇒ `null`（构建退化为纯相对路径，宿主零配置也能跑）。
+ */
+export function loadPathsConfig(root: string): PathsConfig | null {
+  const configPath = resolve(root, TSCONFIG_FILE);
+  if (!ts.sys.fileExists(configPath)) return null;
+  const read = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (read.error !== undefined) return null;
+  const parsed = ts.parseJsonConfigFileContent(
+    read.config,
+    // 只取配置语义，不看工程里有哪些文件：readDirectory 返回空 = 不遍历目录
+    { ...ts.sys, readDirectory: () => [] },
+    dirname(configPath),
+    undefined,
+    configPath,
+  );
+  const paths = parsed.options.paths;
+  if (paths === undefined) return null;
+  return {
+    patterns: Object.entries(paths).map(([key, targets]) => ({
+      ...splitPattern(key),
+      targets: [...targets],
+    })),
+    baseDir:
+      parsed.options.baseUrl ?? declaringDir(configPath) ?? dirname(configPath),
+  };
+}
+
+/**
+ * 按最长前缀把一条说明符展开成候选绝对路径（按声明序、去重后返回）。
+ * 未命中任何模式 ⇒ 空数组；不探测文件是否存在（存在性由调用方在自己的文件树上判）。
+ */
+export function expandAlias(
+  config: PathsConfig,
+  specifier: string,
+): readonly string[] {
+  const hit = matchPattern(config.patterns, specifier);
+  if (hit === undefined) return [];
+  const expanded: string[] = [];
+  for (const target of hit.pattern.targets) {
+    const filled = hit.pattern.wildcard
+      ? replaceStar(target, hit.middle)
+      : target;
+    const absolute = resolve(config.baseDir, filled);
+    if (!expanded.includes(absolute)) expanded.push(absolute);
+  }
+  return expanded;
+}
+
+/** 通配键拆前缀/后缀（第一个 `*` 切分，与 tsc 同一套通配语义） */
+function splitPattern(key: string): Omit<PathsPattern, "targets"> {
+  const star = key.indexOf("*");
+  if (star === -1) return { prefix: key, suffix: "", wildcard: false };
+  return {
+    prefix: key.slice(0, star),
+    suffix: key.slice(star + 1),
+    wildcard: true,
+  };
+}
+
+/**
+ * 匹配：精确键（无 `*`）先按字符串全等命中；否则在命中的通配模式里取前缀最长的那个。
+ * 前缀等长的多个模式按声明序取首个——tsconfig 里同前缀重复声明本身没有意义。
+ */
+function matchPattern(
+  patterns: readonly PathsPattern[],
+  specifier: string,
+): { pattern: PathsPattern; middle: string } | undefined {
+  let exact: PathsPattern | undefined;
+  let best: { pattern: PathsPattern; middle: string } | undefined;
+  for (const pattern of patterns) {
+    if (!pattern.wildcard) {
+      if (pattern.prefix === specifier) exact = pattern;
+      continue;
+    }
+    const fixed = pattern.prefix.length + pattern.suffix.length;
+    if (specifier.length < fixed) continue;
+    if (!specifier.startsWith(pattern.prefix)) continue;
+    if (!specifier.endsWith(pattern.suffix)) continue;
+    if (
+      best !== undefined &&
+      pattern.prefix.length <= best.pattern.prefix.length
+    )
+      continue;
+    best = {
+      pattern,
+      middle: specifier.slice(
+        pattern.prefix.length,
+        specifier.length - pattern.suffix.length,
+      ),
+    };
+  }
+  if (exact !== undefined) return { pattern: exact, middle: "" };
+  return best;
+}
+
+/** 目标模板里的 `*` 全部替换成命中段（tsc 语义：模板里的每个 `*` 都填同一个值） */
+function replaceStar(target: string, middle: string): string {
+  return target.includes("*") ? target.split("*").join(middle) : target;
+}
+
+/**
+ * 声明 `compilerOptions.paths` 的那个 tsconfig 所在目录：先看自身，再沿 `extends`
+ * 反向遍历（数组形态下后者覆盖前者）。找不到 ⇒ `null`（调用方退化为工程根目录）。
+ */
+function declaringDir(
+  configPath: string,
+  seen = new Set<string>(),
+): string | null {
+  if (seen.has(configPath)) return null;
+  seen.add(configPath);
+  const read = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (read.error !== undefined) return null;
+  const json = read.config as
+    { compilerOptions?: { paths?: unknown }; extends?: unknown } | undefined;
+  if (json?.compilerOptions?.paths !== undefined) return dirname(configPath);
+  const parents = extendsList(json?.extends);
+  for (let index = parents.length - 1; index >= 0; index -= 1) {
+    const parentPath = resolveExtends(parents[index]!, dirname(configPath));
+    if (parentPath === null) continue;
+    const found = declaringDir(parentPath, seen);
+    if (found !== null) return found;
+  }
+  return null;
+}
+
+/** `extends` 的取值形态：单条字符串或字符串数组（非字符串项忽略） */
+function extendsList(value: unknown): string[] {
+  if (typeof value === "string") return [value];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+/** 相对/绝对路径形态的 extends 解析成实际文件名；包名形态 ⇒ null（不追） */
+function resolveExtends(specifier: string, fromDir: string): string | null {
+  const looksLocal =
+    specifier.startsWith("./") ||
+    specifier.startsWith("../") ||
+    isAbsolute(specifier);
+  if (!looksLocal) return null;
+  const base = resolve(fromDir, specifier);
+  for (const candidate of [
+    base,
+    `${base}.json`,
+    resolve(base, TSCONFIG_FILE),
+  ]) {
+    if (ts.sys.fileExists(candidate)) return candidate;
+  }
+  return null;
+}

package/src/pipeline/watch.ts

@@ -8,9 +8,10 @@
  */
 import { watch } from "node:fs";
 import { join, resolve } from "node:path";
+import { RESOURCES_DIR } from "@lingfan-engine/core";
 import { DEFAULT_SOURCES_DIR, buildStories } from "./index.ts";
 import type { StoryBuildOptions } from "./orchestrate.ts";
-import { walkFiles } from "../shared/index.ts";
+import { GEN_PREFIX, walkFiles } from "../shared/index.ts";
 
 /** 相对导入抽取（单双引号皆可；type 导入同算依赖——保守向） */
 const REL_IMPORT_RE = /(?:^|[\s;])from\s+["'](\.{1,2}\/[^"']+)["']/g;
@@ -108,7 +109,7 @@ export interface WatchRoundReport {
 }
 
 /** 源树与字体目录的监听目标（相对工程根） */
-const WATCHED_FONT_DIR = join("Resources", "Fonts");
+const WATCHED_FONT_DIR = join(RESOURCES_DIR, "Fonts");
 
 /**
  * 常驻增量监听入口：首轮全量构建落基准 → `fs.watch` 监听源目录（与字体目录，
@@ -208,7 +209,7 @@ function readSourceTexts(
   const texts = new Map<string, string>();
   for (const [rel, text] of walkFiles(sourcesDir)) {
     const posix = rel.replace(/\\/g, "/");
-    if (posix.startsWith("gen/") || !posix.endsWith(".ts")) continue;
+    if (posix.startsWith(GEN_PREFIX) || !posix.endsWith(".ts")) continue;
     texts.set(`${sourcesDirName}/${posix}`, text);
   }
   return texts;

package/src/shared/generated-dir.ts

@@ -0,0 +1,31 @@
+/**
+ * 生成物目录名的唯一声明。
+ *
+ * 这个概念此前有两份独立声明——`pipeline/orchestrate.ts` 的 `DEFAULT_GENERATED_DIR`
+ * 与 `compiler/.../graph/core.ts` 的 `GEN_PREFIX`（同一目录的带斜杠写法），另有六处
+ * 现场手拼 `"gen"` / `"gen/"`。判定分散在发现域、编译器域、监听域与 UI 门禁域四处，
+ * 但判的是同一个目录，故下沉到不依赖任何业务域的 `shared/`，各处引用同一份。
+ *
+ * 为什么不能就近放：编译器域不能依赖 `pipeline/`（`pipeline/` 依赖 `compiler/`，
+ * 反向成环），而 `config/`、`discovery/`、`ui/` 又不依赖 `compiler/`——四个方向都要
+ * 用，只有 `shared/` 站得住。
+ */
+
+/**
+ * 生成物目录名：相对**源根的父目录**（默认布局下 = `src/gen`），不是相对源根。
+ *
+ * 为什么放在源根之外：生成物是「要被编译进前端工程的模块」，故事源是「只归
+ * stories-build 的创作源」。同住 `src/` 之下后，前端工程里没有任何路径指向
+ * `Stories.src/`，故事源因此结构上不可能被打包器收进最终 JS（不必靠「碰巧没人
+ * import」）。
+ */
+export const DEFAULT_GENERATED_DIR = "gen";
+
+/**
+ * 生成物目录的**路径前缀**形式（`gen/`）：`rel.startsWith(GEN_PREFIX)` 判「在此目录之下」。
+ *
+ * 带不带尾斜杠是两件事，别混用——`DEFAULT_GENERATED_DIR` 匹配目录名本身
+ * （`entry === DEFAULT_GENERATED_DIR`，用于「整目录被列为源目录」这种判定），
+ * `GEN_PREFIX` 只匹配其下的条目（`gen/x.ts` 是生成物，`gen_backup/x.ts` 不是）。
+ */
+export const GEN_PREFIX = `${DEFAULT_GENERATED_DIR}/`;

package/src/shared/index.ts

@@ -1,11 +1,15 @@
 /**
- * 通用出口：失败类型、文件遍历与集中文案表。
+ * 通用出口：失败类型、文件遍历、目录布局名、追溯上限与集中文案表。
  *
- * 这三样跨域用得多——`StoryBuildError` 被十来个文件当统一失败口径，
- * `walkFiles` 被发现、写盘、编译器三处共同依赖，`StoriesBuildTexts` 是
- * 构建期全部可注入文案的唯一出处（缺省实现 = 现场字符串）——放进任何
- * 业务域都会让别的域为了一个工具反向依赖它，故单独成域。
+ * 这几样跨域用得多——`StoryBuildError` 被十来个文件当统一失败口径，
+ * `walkFiles` 被发现、写盘、编译器三处共同依赖，`DEFAULT_GENERATED_DIR` /
+ * `GEN_PREFIX` 被发现、编译器、监听、UI 门禁四域共用（判的是同一个生成物目录），
+ * `MAX_ALIAS_HOPS` 被编译器与类型生成两域共用（同一条类型别名链的两端），
+ * `StoriesBuildTexts` 是构建期全部可注入文案的唯一出处（缺省实现 = 现场字符串）——
+ * 放进任何业务域都会让别的域为了一个工具反向依赖它，故单独成域。
  */
 export { StoryBuildError } from "./errors.ts";
+export { DEFAULT_GENERATED_DIR, GEN_PREFIX } from "./generated-dir.ts";
+export { MAX_ALIAS_HOPS } from "./limits.ts";
 export { walkFiles } from "./walk-files.ts";
 export { defaultStoriesBuildTexts, type StoriesBuildTexts } from "./texts.ts";