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

package/src/const-eval/const-expr.ts

@@ -0,0 +1,358 @@
+/**
+ * 模块层构建期 define 的常量求值器（AST 侧，零 esbuild）。
+ *
+ * config.ts 的 define 走 esbuild 求值通道（const-eval，esbuild 求值语义保证常量
+ * 折叠与标识符消解）；模块层的 define 只发生在顶层语句，值域刻意收窄为
+ * 「字面量 / 数组 / 对象 / 枚举成员引用」，本文件用 TS AST 直接折叠，不引入第二套
+ * 打包器。枚举值是唯一的非常量字面量形态：标识符按本文件 import 与本地 enum 解析，
+ * 被引用的枚举文件再按同文法折叠成员表（只认声明在该文件内的 enum，不追 re-export）。
+ *
+ * fail-closed：任何不可折叠形态（模板插值、展开、简写、计算属性、npm 枚举、
+ * 引用型枚举初始化……）都返回可读原因，由收集器统一挂源文件:行:列定位。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import * as ts from "typescript";
+import type { JsonValue } from "./const-eval.ts";
+
+/** 一个枚举的成员值表（声明序；值 = 字符串或数字） */
+type EnumTable = ReadonlyMap<string, string | number>;
+
+/** 模块 import 登记：本地名 → 模块说明符与出口名（default 导入 exportedName = "default"） */
+interface ImportedEnum {
+  readonly specifier: string;
+  readonly exportedName: string;
+}
+
+/** 求值上下文：当前模块的 import 表、本地 enum 表与跨文件枚举缓存（缓存可变） */
+export interface ConstExprContext {
+  /** 源目录绝对路径（枚举文件按它读盘） */
+  readonly sourcesDir: string;
+  /** 当前模块相对源根的 posix 路径（import 说明符按它的目录归一） */
+  readonly rel: string;
+  readonly imports: ReadonlyMap<string, ImportedEnum>;
+  readonly localEnums: ReadonlyMap<string, EnumTable>;
+  /** 已解析枚举文件的缓存：文件路径 → 枚举名 → 成员表 */
+  readonly enumFiles: Map<string, Map<string, EnumTable>>;
+}
+
+export type ConstExprResult =
+  { ok: true; value: JsonValue } | { ok: false; reason: string };
+
+/** 折叠一个表达式为 JSON 可序列化常量；任何非常量形态都返回可读原因 */
+export function evalConstExpr(
+  expr: ts.Expression,
+  ctx: ConstExprContext,
+): ConstExprResult {
+  const unwrapped = unwrapExpr(expr);
+  if (
+    ts.isStringLiteral(unwrapped) ||
+    ts.isNoSubstitutionTemplateLiteral(unwrapped)
+  ) {
+    return { ok: true, value: unwrapped.text };
+  }
+  if (ts.isNumericLiteral(unwrapped)) {
+    return { ok: true, value: Number(unwrapped.text) };
+  }
+  if (unwrapped.kind === ts.SyntaxKind.TrueKeyword)
+    return { ok: true, value: true };
+  if (unwrapped.kind === ts.SyntaxKind.FalseKeyword)
+    return { ok: true, value: false };
+  if (unwrapped.kind === ts.SyntaxKind.NullKeyword)
+    return { ok: true, value: null };
+  if (ts.isPrefixUnaryExpression(unwrapped)) {
+    return evalPrefixUnary(unwrapped);
+  }
+  if (ts.isArrayLiteralExpression(unwrapped)) {
+    return evalArray(unwrapped, ctx);
+  }
+  if (ts.isObjectLiteralExpression(unwrapped)) {
+    return evalObject(unwrapped, ctx);
+  }
+  if (ts.isIdentifier(unwrapped)) {
+    return resolveEnumObject(unwrapped.text, ctx);
+  }
+  if (
+    ts.isPropertyAccessExpression(unwrapped) &&
+    ts.isIdentifier(unwrapped.expression)
+  ) {
+    return resolveEnumMember(
+      unwrapped.expression.text,
+      unwrapped.name.text,
+      ctx,
+    );
+  }
+  if (
+    ts.isElementAccessExpression(unwrapped) &&
+    ts.isIdentifier(unwrapped.expression) &&
+    ts.isStringLiteral(unwrapped.argumentExpression)
+  ) {
+    return resolveEnumMember(
+      unwrapped.expression.text,
+      unwrapped.argumentExpression.text,
+      ctx,
+    );
+  }
+  if (ts.isTemplateExpression(unwrapped)) {
+    return {
+      ok: false,
+      reason: "模板串不支持插值——构建期 define 值请用字符串字面量",
+    };
+  }
+  return {
+    ok: false,
+    reason:
+      "值必须是可序列化常量：字符串/数字/布尔/null、数组或对象字面量、枚举成员引用",
+  };
+}
+
+/** 解包括号与 as/类型断言包裹（求值语义 = 内层表达式） */
+function unwrapExpr(expr: ts.Expression): ts.Expression {
+  if (
+    ts.isParenthesizedExpression(expr) ||
+    ts.isAsExpression(expr) ||
+    ts.isTypeAssertionExpression(expr)
+  ) {
+    return unwrapExpr(expr.expression);
+  }
+  return expr;
+}
+
+function evalPrefixUnary(expr: ts.PrefixUnaryExpression): ConstExprResult {
+  if (
+    expr.operator !== ts.SyntaxKind.MinusToken &&
+    expr.operator !== ts.SyntaxKind.PlusToken
+  ) {
+    return { ok: false, reason: "一元运算符不支持构建期折叠（只支持正负号）" };
+  }
+  const inner = unwrapExpr(expr.operand);
+  if (!ts.isNumericLiteral(inner)) {
+    return { ok: false, reason: "正负号只能作用于数字字面量" };
+  }
+  const value = Number(inner.text);
+  return {
+    ok: true,
+    value: expr.operator === ts.SyntaxKind.MinusToken ? -value : value,
+  };
+}
+
+function evalArray(
+  expr: ts.ArrayLiteralExpression,
+  ctx: ConstExprContext,
+): ConstExprResult {
+  const out: JsonValue[] = [];
+  for (const element of expr.elements) {
+    if (ts.isOmittedExpression(element)) {
+      return { ok: false, reason: "数组字面量不允许空洞" };
+    }
+    if (ts.isSpreadElement(element)) {
+      return { ok: false, reason: "数组字面量不支持展开元素" };
+    }
+    const item = evalConstExpr(element, ctx);
+    if (!item.ok) return item;
+    out.push(item.value);
+  }
+  return { ok: true, value: out };
+}
+
+function evalObject(
+  expr: ts.ObjectLiteralExpression,
+  ctx: ConstExprContext,
+): ConstExprResult {
+  const out: Record<string, JsonValue> = {};
+  for (const prop of expr.properties) {
+    if (ts.isPropertyAssignment(prop)) {
+      if (!ts.isIdentifier(prop.name) && !ts.isStringLiteral(prop.name)) {
+        return { ok: false, reason: "对象字面量不支持计算属性名" };
+      }
+      const value = evalConstExpr(prop.initializer, ctx);
+      if (!value.ok) return value;
+      out[prop.name.text] = value.value;
+      continue;
+    }
+    if (ts.isShorthandPropertyAssignment(prop)) {
+      return {
+        ok: false,
+        reason: "对象字面量不支持简写属性——请写显式的 键: 值",
+      };
+    }
+    if (ts.isSpreadAssignment(prop)) {
+      return { ok: false, reason: "对象字面量不支持展开属性" };
+    }
+    return { ok: false, reason: "对象字面量只支持普通键值属性" };
+  }
+  return { ok: true, value: out };
+}
+
+/** 标识符 → 枚举对象（本地 enum 优先，其次 import 来源的枚举文件） */
+function resolveEnumObject(
+  name: string,
+  ctx: ConstExprContext,
+): ConstExprResult {
+  const local = ctx.localEnums.get(name);
+  if (local !== undefined) {
+    return { ok: true, value: Object.fromEntries(local) };
+  }
+  const table = loadImportedEnum(name, ctx);
+  if (!table.ok) return table;
+  return { ok: true, value: Object.fromEntries(table.value) };
+}
+
+/** 枚举成员取值：`Sex.Male` / `Sex["Male"]` */
+function resolveEnumMember(
+  objName: string,
+  member: string,
+  ctx: ConstExprContext,
+): ConstExprResult {
+  const local = ctx.localEnums.get(objName);
+  if (local !== undefined) {
+    return takeEnumMember(local, objName, member);
+  }
+  const table = loadImportedEnum(objName, ctx);
+  if (!table.ok) return table;
+  return takeEnumMember(table.value, objName, member);
+}
+
+function takeEnumMember(
+  table: EnumTable,
+  objName: string,
+  member: string,
+): ConstExprResult {
+  const value = table.get(member);
+  if (value === undefined) {
+    return { ok: false, reason: `枚举 "${objName}" 没有 "${member}" 成员` };
+  }
+  return { ok: true, value };
+}
+
+/** 按模块 import 表解析枚举文件并折叠成员表（解析失败返回可读原因） */
+function loadImportedEnum(
+  name: string,
+  ctx: ConstExprContext,
+): { ok: true; value: EnumTable } | { ok: false; reason: string } {
+  const imported = ctx.imports.get(name);
+  if (imported === undefined) {
+    return {
+      ok: false,
+      reason: `无法识别的标识符 "${name}"——构建期 define 值只支持字面量与枚举成员引用`,
+    };
+  }
+  if (imported.exportedName === "default") {
+    return {
+      ok: false,
+      reason: `枚举 "${name}" 经 default 导入——构建期枚举折叠只支持具名导出的 enum`,
+    };
+  }
+  if (!imported.specifier.startsWith(".")) {
+    return {
+      ok: false,
+      reason: `枚举 "${name}" 来自 npm 包——构建期常量折叠只支持 Stories.src 内的枚举，请把枚举放进源目录再相对导入`,
+    };
+  }
+  const fileRel = resolveEnumFileRel(imported.specifier, ctx);
+  if (fileRel === undefined) {
+    return {
+      ok: false,
+      reason: `无法解析枚举导入 "${imported.specifier}"（源目录内找不到对应文件）`,
+    };
+  }
+  const cachedFile = ctx.enumFiles.get(fileRel);
+  if (cachedFile !== undefined) {
+    const cached = cachedFile.get(imported.exportedName);
+    if (cached !== undefined) return { ok: true, value: cached };
+    return {
+      ok: false,
+      reason: `"${fileRel}" 中没有名为 "${imported.exportedName}" 的枚举`,
+    };
+  }
+  const parsed = parseEnumFile(fileRel, ctx);
+  ctx.enumFiles.set(fileRel, parsed);
+  const table = parsed.get(imported.exportedName);
+  if (table === undefined) {
+    return {
+      ok: false,
+      reason: `"${fileRel}" 中没有名为 "${imported.exportedName}" 的枚举`,
+    };
+  }
+  return { ok: true, value: table };
+}
+
+/** import 说明符 → 源根内 posix 路径（相对当前模块目录归一；补 .ts / index.ts） */
+function resolveEnumFileRel(
+  specifier: string,
+  ctx: ConstExprContext,
+): string | undefined {
+  const base = posix.normalize(posix.join(posix.dirname(ctx.rel), specifier));
+  const candidates = base.endsWith(".ts")
+    ? [base]
+    : [`${base}.ts`, `${base}/index.ts`];
+  return candidates.find((cand) => existsSync(join(ctx.sourcesDir, cand)));
+}
+
+/** 读盘折叠一个枚举文件的全部 enum 声明（成员表按文法折叠，引用型初始化 fail-closed） */
+function parseEnumFile(
+  fileRel: string,
+  ctx: ConstExprContext,
+): Map<string, EnumTable> {
+  const out = new Map<string, EnumTable>();
+  let text: string;
+  try {
+    text = readFileSync(join(ctx.sourcesDir, fileRel), "utf8");
+  } catch {
+    return out;
+  }
+  const sf = ts.createSourceFile(fileRel, text, ts.ScriptTarget.Latest, true);
+  for (const stmt of sf.statements) {
+    if (!ts.isEnumDeclaration(stmt)) continue;
+    const table = foldEnumMembers(stmt);
+    if (table !== undefined) out.set(stmt.name.text, table);
+  }
+  return out;
+}
+
+/** 折叠一个 enum 声明的成员表；不可折叠成员（引用/计算名等）= 整枚举不登记 */
+function foldEnumMembers(stmt: ts.EnumDeclaration): EnumTable | undefined {
+  const table = new Map<string, string | number>();
+  let auto = 0;
+  let sawAuto = false;
+  for (const member of stmt.members) {
+    if (!ts.isIdentifier(member.name)) return undefined;
+    const init = member.initializer;
+    if (init === undefined) {
+      if (sawAuto) {
+        table.set(member.name.text, auto);
+        auto += 1;
+      } else if (table.size === 0) {
+        sawAuto = true;
+        table.set(member.name.text, 0);
+        auto = 1;
+      } else {
+        return undefined; // 字符串枚举的无初始化成员（TS 本身也报错）
+      }
+      continue;
+    }
+    const value = foldEnumInit(init);
+    if (value === undefined) return undefined;
+    if (typeof value === "number") {
+      sawAuto = true;
+      auto = value + 1;
+    }
+    table.set(member.name.text, value);
+  }
+  return table;
+}
+
+/** 枚举成员初始化器：字符串/数字字面量或带符号数字字面量；其余不支持 */
+function foldEnumInit(init: ts.Expression): string | number | undefined {
+  const unwrapped = unwrapExpr(init);
+  if (ts.isStringLiteral(unwrapped)) return unwrapped.text;
+  if (ts.isNumericLiteral(unwrapped)) return Number(unwrapped.text);
+  if (
+    ts.isPrefixUnaryExpression(unwrapped) &&
+    unwrapped.operator === ts.SyntaxKind.MinusToken
+  ) {
+    const operand = unwrapExpr(unwrapped.operand);
+    if (ts.isNumericLiteral(operand)) return -Number(operand.text);
+  }
+  return undefined;
+}

package/src/const-eval/contracts.ts

@@ -0,0 +1,31 @@
+/**
+ * const-eval 域共享契约：JSON 可序列化值、求值两态结果、define 调用与非法调用记录。
+ * 独立成文件是为了让入口 `./const-eval.ts` 与 worker 轮次 `./round/` 引用同一份声明，
+ * 又不产生「入口 ↔ 轮次」相互 import（环判据白名单为空）。
+ */
+import type { CompilerDiagnostic } from "../compiler/index.ts";
+
+/** JSON 可序列化值（求值产物的唯一合法形态）。 */
+export type JsonValue =
+  string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** 求值结果：要么拿到全部导出常量的可序列化值，要么拿到一组诊断（fail-closed）。 */
+export type ConstEvalResult =
+  | { values: Record<string, JsonValue>; defineCalls: readonly DefineCall[] }
+  | { diags: CompilerDiagnostic[] };
+
+/**
+ * define() 构建期内建的调用记录（形态 B 累积；书写序即合并序）：
+ * - `path`：`define("a.b", value)` 点路径单值声明；
+ * - `spec`：`define({...})` 对象字面量子树声明。
+ * 值在 worker 内已过 classify（JSON 安全）；非法值不进此表（走 defineBad 诊断）。
+ */
+export type DefineCall =
+  | { kind: "path"; path: string; value: JsonValue }
+  | { kind: "spec"; spec: Record<string, JsonValue> };
+
+/** define() 非法调用的记录（求值段把每条翻成诊断，统一挂入口 1:1）。 */
+export interface DefineBad {
+  readonly path: string;
+  readonly reason: string;
+}

package/src/const-eval/define-merge.ts

@@ -0,0 +1,195 @@
+/**
+ * 形态 B（define 累积）合并器：把求值期按书写序收集的 define 调用合并为一棵
+ * 纯嵌套树，供 state 降维段与 config.state（形态 A）走同一条 flattenRoot 通道。
+ *
+ * 合并文法（形态 B）：
+ * - 点路径切段折叠；空段拒（"a..b"、".a"、"a." 一律 fail-closed）；
+ * - 同键二次定义 fail-closed（不后写覆盖）；叶值与分支对象两向同键都算形状冲突；
+ * - 对象实参子树递归合并（同分支不同叶合法）；
+ * - 对象字面量里的点键不在此拦——留给降维段的统一 dotKeyError 守卫；
+ * - 数组值是叶子（裸数组拒绝发生在降维段：请用 descriptor）；
+ * - 冲突一次报全部（fail-closed，求值毕统一结算）。
+ *
+ * 多源汇入（mergeDefineCallsInto）：config.ts 的 define 树作为底树，模块层
+ * define 带 `文件:行:列` 落点汇入；冲突文案区分单位置（仅本次来源）与两处位置
+ * （既有来源 与 本次来源），全部路径的来源表随插入增量登记。
+ */
+import type { DefineCall } from "./const-eval.ts";
+
+export interface DefineMergeResult {
+  /** 合并后的纯嵌套树（只含 define 贡献；无调用 = 空对象） */
+  readonly tree: Record<string, unknown>;
+  /** 冲突清单（逐条可读；非空 = fail-closed） */
+  readonly conflicts: readonly string[];
+}
+
+/** 带落点的 define 调用（模块层收集器产物；与 LocatedDefineCall 结构兼容） */
+export interface OriginatedDefineCall {
+  readonly call: DefineCall;
+  readonly origin: string;
+}
+
+/** 跨文件来源登记：路径 → `文件:行:列`（config 段恒为 "config.ts"） */
+interface MergeContext {
+  readonly origins: Map<string, string>;
+  readonly origin: string;
+}
+
+const CONFIG_ORIGIN = "config.ts";
+
+export function mergeDefineCalls(
+  calls: readonly DefineCall[],
+): DefineMergeResult {
+  const tree: Record<string, unknown> = {};
+  const conflicts: string[] = [];
+  for (const call of calls) {
+    if (call.kind === "path") {
+      insertSegments(
+        tree,
+        call.path.split("."),
+        call.value,
+        call.path,
+        conflicts,
+      );
+    } else {
+      mergeInto(tree, call.spec, [], conflicts);
+    }
+  }
+  return { tree, conflicts };
+}
+
+/**
+ * 把带落点的模块层 define 调用汇入既有合并树（就地变异）。
+ * 返回冲突清单（非空 = fail-closed，编排层一次报全部）。
+ */
+export function mergeDefineCallsInto(
+  tree: Record<string, unknown>,
+  calls: readonly OriginatedDefineCall[],
+): readonly string[] {
+  const conflicts: string[] = [];
+  const origins = new Map<string, string>();
+  seedOrigins(tree, [], origins);
+  for (const item of calls) {
+    const ctx: MergeContext = { origins, origin: item.origin };
+    if (item.call.kind === "path") {
+      insertSegments(
+        tree,
+        item.call.path.split("."),
+        item.call.value,
+        item.call.path,
+        conflicts,
+        ctx,
+      );
+    } else {
+      mergeInto(tree, item.call.spec, [], conflicts, ctx);
+    }
+    seedOrigins(tree, [], origins);
+  }
+  return conflicts;
+}
+
+/** 全树路径登记来源（先见保留：config 底树先登记，新增路径归本次调用） */
+function seedOrigins(
+  tree: Record<string, unknown>,
+  prefix: readonly string[],
+  origins: Map<string, string>,
+): void {
+  for (const [key, value] of Object.entries(tree)) {
+    const path = [...prefix, key].join(".");
+    if (!origins.has(path)) origins.set(path, CONFIG_ORIGIN);
+    if (isBranch(value)) seedOrigins(value, [...prefix, key], origins);
+  }
+}
+
+function unitSuffix(ctx: MergeContext | undefined): string {
+  return ctx === undefined ? "" : `（${ctx.origin}）`;
+}
+
+function pairSuffix(path: string, ctx: MergeContext | undefined): string {
+  if (ctx === undefined) return "";
+  const existing = ctx.origins.get(path);
+  return existing === undefined
+    ? `（${ctx.origin}）`
+    : `——${existing} 与 ${ctx.origin}`;
+}
+
+/** 把 `value` 按段序列插入树：中途遇叶子 = 叶↔分支冲突；终点同键 = 二次定义冲突。 */
+function insertSegments(
+  tree: Record<string, unknown>,
+  segments: readonly string[],
+  value: unknown,
+  displayPath: string,
+  conflicts: string[],
+  ctx?: MergeContext,
+): void {
+  if (segments.some((segment) => segment === "")) {
+    conflicts.push(
+      `define("${displayPath}")：点路径含空段（"a..b"、".a"、"a." 形态不支持）${unitSuffix(ctx)}`,
+    );
+    return;
+  }
+  let current: Record<string, unknown> = tree;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i]!;
+    const existing = current[segment];
+    if (existing === undefined) {
+      const next: Record<string, unknown> = {};
+      current[segment] = next;
+      current = next;
+    } else if (isBranch(existing)) {
+      current = existing;
+    } else {
+      const path = segments.slice(0, i + 1).join(".");
+      conflicts.push(
+        `defines["${path}"]：键已是叶子值，不能再作为分支下钻（define("${displayPath}")）${pairSuffix(path, ctx)}`,
+      );
+      return;
+    }
+  }
+  const leaf = segments[segments.length - 1]!;
+  const existing = current[leaf];
+  if (existing !== undefined) {
+    if (isBranch(existing) && isBranch(value)) {
+      mergeInto(existing, value, segments.slice(0, -1), conflicts, ctx);
+      return;
+    }
+    const path = segments.join(".");
+    conflicts.push(
+      `defines["${path}"]：同键二次定义（fail-closed，不后写覆盖）${pairSuffix(path, ctx)}`,
+    );
+    return;
+  }
+  current[leaf] = value;
+}
+
+/** 对象实参子树合并：同分支不同叶合法；同叶/形状冲突按叶路径报。 */
+function mergeInto(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+  segments: readonly string[],
+  conflicts: string[],
+  ctx?: MergeContext,
+): void {
+  for (const key of Object.keys(source)) {
+    const incoming = source[key];
+    const existing = target[key];
+    const path = [...segments, key].join(".");
+    if (existing === undefined) {
+      target[key] = incoming;
+    } else if (isBranch(existing) && isBranch(incoming)) {
+      mergeInto(existing, incoming, [...segments, key], conflicts, ctx);
+    } else if (isBranch(existing) || isBranch(incoming)) {
+      conflicts.push(
+        `defines["${path}"]：形状冲突——叶值与分支对象不能同键（fail-closed）${pairSuffix(path, ctx)}`,
+      );
+    } else {
+      conflicts.push(
+        `defines["${path}"]：同键二次定义（fail-closed，不后写覆盖）${pairSuffix(path, ctx)}`,
+      );
+    }
+  }
+}
+
+function isBranch(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/const-eval/diag/compare.ts

@@ -0,0 +1,39 @@
+/**
+ * 两轮求值的逐键比较：确定性闸门的判据。
+ */
+import type { JsonValue } from "../contracts.ts";
+
+export function firstDeterminismDiff(
+  a: Record<string, JsonValue>,
+  b: Record<string, JsonValue>,
+): string | null {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    if (!deepEqual(a[key], b[key])) return key;
+  }
+  return null;
+}
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== typeof b) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+      return false;
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every(
+      (key) =>
+        key in b &&
+        deepEqual(
+          (a as { [k: string]: JsonValue })[key],
+          (b as { [k: string]: JsonValue })[key],
+        ),
+    );
+  }
+  return false;
+}

package/src/const-eval/diag/index.ts

@@ -0,0 +1,5 @@
+/**
+ * 诊断辅助出口（具名转发，不用 `export *`）。
+ */
+export { locateExport } from "./locate.ts";
+export { firstDeterminismDiff, deepEqual } from "./compare.ts";

package/src/const-eval/diag/locate.ts

@@ -0,0 +1,45 @@
+/**
+ * 诊断定位：在入口源里定位 `export <key>` 的 1 基 line/col。
+ */
+import { readFileSync } from "node:fs";
+
+/** 在入口源文件里定位 `export <key>` 声明（1 基 line/col）；找不到退回 1:1。 */
+export function locateExport(
+  absEntry: string,
+  key: string,
+): { line: number; col: number } {
+  let text: string;
+  try {
+    text = readFileSync(absEntry, "utf8");
+  } catch {
+    return { line: 1, col: 1 };
+  }
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const patterns =
+    key === "default"
+      ? [/(^|\n)[ \t]*export[ \t]+default\b/]
+      : [
+          new RegExp(
+            `(^|\\n)[ \\t]*export[ \t]+(?:const|let|var|async[ \t]+function|function|class)[ \t]+${escaped}\\b`,
+          ),
+          new RegExp(
+            `(^|\\n)[ \\t]*export[ \t]*\\{[^}]*\\b${escaped}\\b[^}]*\\}`,
+          ),
+        ];
+  for (const pattern of patterns) {
+    const match = pattern.exec(text);
+    if (match !== null) return offsetToPos(text, match.index + match[1].length);
+  }
+  return { line: 1, col: 1 };
+}
+
+export function offsetToPos(
+  text: string,
+  offset: number,
+): { line: number; col: number } {
+  const lines = text.slice(0, offset).split("\n");
+  return {
+    line: lines.length,
+    col: (lines[lines.length - 1] ?? "").length + 1,
+  };
+}