@nudojs/service 0.2.1 → 0.3.0

package/src/dts-generator.ts

@@ -1,5 +1,5 @@
 import type { TypeValue } from "@nudojs/core";
-import { T, isTemplate, getTemplateParts, simplifyUnion, typeValueEquals } from "@nudojs/core";
+import { T, isTemplate, getTemplateParts, simplifyUnion, typeValueEquals, getFnSig } from "@nudojs/core";
 import type { AnalysisResult, FunctionAnalysis } from "./analyzer.ts";
 
 export function typeValueToTSType(tv: TypeValue): string {
@@ -42,8 +42,8 @@ export function typeValueToTSType(tv: TypeValue): string {
       const params = tv.params
         .map((p) => `${p}: unknown`)
         .join(", ");
-      const returnType = (tv as any)._returnType;
-      const retStr = returnType ? typeValueToTSType(returnType) : "unknown";
+      const sig = getFnSig(tv);
+      const retStr = sig?.returnType ? typeValueToTSType(sig.returnType) : "unknown";
       return `(${params}) => ${retStr}`;
     }
     case "promise":

package/src/env-to-abs.ts

@@ -0,0 +1,57 @@
+/**
+ * env TypeValue → Abs：保留 fnSig impl，使 Promise.resolve / URL 等
+ * 在 B 路径也能产出精确字面量。
+ */
+
+import {
+  type TypeValue,
+  type Abs,
+  typeValueToAbs,
+  absToTypeValue,
+  getFnSig,
+  absFunction,
+  objOf,
+} from "@nudojs/core";
+
+export function envValueToAbs(tv: TypeValue): Abs {
+  if (!tv) return typeValueToAbs({ kind: "unknown" });
+
+  if (tv.kind === "function") {
+    const sig = getFnSig(tv);
+    if (sig?.impl) {
+      const params =
+        tv.kind === "function" && tv.params?.length
+          ? tv.params
+          : sig.paramTypes.map((_, i) => `_arg${i}`);
+      const dummyBody = {
+        type: "BlockStatement",
+        body: [],
+        directives: [],
+      } as never;
+      const impl = sig.impl;
+      return absFunction(params, {
+        body: dummyBody,
+        apply: (args: Abs[]): Abs => {
+          const tvArgs = args.map((a) => absToTypeValue(a));
+          try {
+            const r = impl(tvArgs);
+            if (!r) return typeValueToAbs(sig.returnType);
+            return envValueToAbs(r);
+          } catch {
+            return typeValueToAbs(sig.returnType);
+          }
+        },
+      });
+    }
+  }
+
+  if (tv.kind === "object") {
+    const slots: Record<string, { value: Abs }> = {};
+    for (const [k, v] of Object.entries(tv.properties)) {
+      slots[k] = { value: envValueToAbs(v) };
+    }
+    return objOf(slots);
+  }
+
+  return typeValueToAbs(tv);
+}

package/src/fn-analysis-cache.ts

@@ -0,0 +1,119 @@
+/**
+ * Per-function FunctionAnalysis cache (body-edit: recompute only dirty fns).
+ * Cleared together with B-path / whole-file analysis caches.
+ */
+import type { TypeValue } from "@nudojs/core";
+
+// Structural types — avoid importing analyzer (cycle).
+export type CachedSourceLocation = {
+  start: { line: number; column: number };
+  end: { line: number; column: number };
+};
+
+export type CachedDiagnostic = {
+  range: CachedSourceLocation;
+  severity: "error" | "warning" | "info";
+  message: string;
+  tags?: string[];
+  code?: string;
+  suggestions?: string[];
+  data?: unknown;
+  origin?: { line: number; column: number };
+};
+
+export type CachedCaseHint = {
+  line: number;
+  label: string;
+  ok: boolean;
+};
+
+export type CachedCallRecord = {
+  // opaque; cloned shallowly. Position fields that need lineDelta shift
+  // (currently only callLoc) are listed on CallRecord in evaluator.ts —
+  // keep shiftCallRecordLines in sync when adding any.
+  [k: string]: unknown;
+};
+
+export type CachedFnAnalysis = {
+  analysis: {
+    name: string;
+    loc: CachedSourceLocation;
+    paramNames: string[];
+    cases: Array<{
+      name: string;
+      args: TypeValue[];
+      result: TypeValue;
+      throws: TypeValue;
+      throwLoc?: CachedSourceLocation;
+      source?: string;
+      expected?: TypeValue;
+      aggregatedFrom?: number;
+      intension?: Record<string, unknown>;
+    }>;
+    combined?: TypeValue;
+    entryOnly?: boolean;
+    skipped?: boolean;
+    noDeclaration?: boolean;
+    fromModule?: string;
+  };
+  diagnostics: CachedDiagnostic[];
+  caseHints: CachedCaseHint[];
+  callRecords: CachedCallRecord[];
+};
+
+const fnAnalysisCache = new Map<string, CachedFnAnalysis>();
+const MAX_FN_ANALYSIS_CACHE = 1024;
+
+export function clearFnAnalysisCache(): void {
+  fnAnalysisCache.clear();
+}
+
+export function fnAnalysisCacheGet(key: string): CachedFnAnalysis | undefined {
+  const hit = fnAnalysisCache.get(key);
+  if (hit !== undefined) {
+    fnAnalysisCache.delete(key);
+    fnAnalysisCache.set(key, hit);
+  }
+  return hit;
+}
+
+export function fnAnalysisCacheSet(key: string, value: CachedFnAnalysis): void {
+  // Only evict when inserting a new key; overwrite of an existing key keeps LRU size
+  if (fnAnalysisCache.size >= MAX_FN_ANALYSIS_CACHE && !fnAnalysisCache.has(key)) {
+    const oldest = fnAnalysisCache.keys().next().value;
+    if (oldest !== undefined) fnAnalysisCache.delete(oldest);
+  }
+  fnAnalysisCache.set(key, value);
+}
+
+/**
+ * Dependency content changed: drop every per-fn entry for these entry files.
+ * Keys are `filePath\0...`, so a prefix scan is sound and cheap at LRU size.
+ */
+export function evictFnAnalysisCacheForFiles(files: string[]): number {
+  if (files.length === 0 || fnAnalysisCache.size === 0) return 0;
+  const prefixes = files.map((f) => `${f}\0`);
+  let n = 0;
+  for (const key of [...fnAnalysisCache.keys()]) {
+    if (prefixes.some((p) => key.startsWith(p))) {
+      fnAnalysisCache.delete(key);
+      n++;
+    }
+  }
+  return n;
+}
+
+export function caseDirectiveKey(
+  directives: Array<{ kind: string; name?: string; args?: TypeValue[] }>,
+  typeValueToString: (t: TypeValue) => string,
+): string {
+  return directives
+    .map((d) => {
+      if (d.kind === "case") {
+        const args = (d.args ?? []).map((a) => typeValueToString(a)).join(",");
+        return `c:${d.name ?? ""}:${args}`;
+      }
+      return d.kind;
+    })
+    .join("|");
+}

package/src/guard-generator.ts

@@ -1,10 +1,17 @@
-import type { TypeValue } from "@nudojs/core";
+import type { TypeValue, Abs } from "@nudojs/core";
+import { denoteGuard } from "@nudojs/core";
 
 export function generateGuardFunction(name: string, tv: TypeValue): string {
   const body = generateGuardBody(tv, "data");
   return `export function ${name}(data) {\n  return ${body};\n}`;
 }
 
+/** Abs 指称守卫（设计 §2.7）：比 TypeValue 投影多保留 pred */
+export function generateGuardFunctionFromAbs(name: string, abs: Abs): string {
+  const body = denoteGuard(abs, "data");
+  return `export function ${name}(data) {\n  return ${body};\n}`;
+}
+
 function generateGuardBody(tv: TypeValue, varName: string): string {
   switch (tv.kind) {
     case "literal": {

package/src/harvest-auto.ts

@@ -0,0 +1,86 @@
+/**
+ * harvest 自动化：源码裸 import → @types/package → env modules。
+ * 手动 `nudo harvest` 仍保留；这里是分析路径上的按需注入。
+ */
+
+import { parse } from "@nudojs/parser";
+import type { TypeValue } from "@nudojs/core";
+import { collectDependencySpecs } from "./static-imports.ts";
+import { harvestPackage, type PackageHarvest } from "./harvest-package.ts";
+
+/** 裸说明符 → 包名（含 scope）；相对/绝对/node: 内建返回 undefined */
+export function barePackageName(spec: string): string | undefined {
+  if (!spec) return undefined;
+  if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("node:")) return undefined;
+  const parts = spec.split("/");
+  if (spec.startsWith("@")) {
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : undefined;
+  }
+  return parts[0];
+}
+
+export function collectBarePackages(source: string): string[] {
+  try {
+    const ast = parse(source);
+    const names = new Set<string>();
+    for (const spec of collectDependencySpecs(ast)) {
+      const pkg = barePackageName(spec);
+      if (pkg) names.add(pkg);
+    }
+    return [...names];
+  } catch {
+    return [];
+  }
+}
+
+/** 进程内 harvest 缓存：同包只 walk 一次 dts */
+const harvestCache = new Map<string, PackageHarvest | null>();
+
+export function harvestPackageCached(pkg: string, fromDir: string): PackageHarvest | null {
+  const key = `${fromDir}::${pkg}`;
+  if (harvestCache.has(key)) return harvestCache.get(key)!;
+  let result: PackageHarvest | null = null;
+  try {
+    const h = harvestPackage(pkg, fromDir);
+    if (!("error" in h)) result = h;
+  } catch {
+    result = null;
+  }
+  harvestCache.set(key, result);
+  return result;
+}
+
+export function clearHarvestCache(): void {
+  harvestCache.clear();
+}
+
+/**
+ * 自动 harvest 源码中全部裸包（有 @types 或包内 dts 时）。
+ * 返回可注入 setEnvModules 的 modules 表；无包可 harvest 时为空对象。
+ */
+export function autoHarvestModules(
+  source: string,
+  fromDir: string,
+): Record<string, Record<string, TypeValue>> {
+  const packages = collectBarePackages(source);
+  if (packages.length === 0) return {};
+  const modules: Record<string, Record<string, TypeValue>> = {};
+  for (const pkg of packages) {
+    const h = harvestPackageCached(pkg, fromDir);
+    if (!h) continue;
+    for (const [mod, exports] of Object.entries(h.env.modules)) {
+      // 模块键可能是相对路径形态；同时登记裸包名与原始键
+      modules[mod] = exports;
+      if (!modules[pkg]) modules[pkg] = exports;
+      // `path` / `node:path` 等别名：basename 匹配
+      const base = mod.replace(/^@types\//, "").replace(/\\/g, "/");
+      if (base && !modules[base]) modules[base] = exports;
+    }
+    for (const [k, v] of Object.entries(h.env.globals)) {
+      // 全局 API 也挂一份到包名模块，供 default/namespace 消费
+      if (!modules[pkg]) modules[pkg] = {};
+      if (modules[pkg]![k] === undefined) modules[pkg]![k] = v;
+    }
+  }
+  return modules;
+}

package/src/harvest-node.ts

@@ -0,0 +1,48 @@
+/**
+ * 预置 Node API env：从 @types/node 的 .d.ts harvest。
+ * 与 packages/env 的手写 env 并行；此路径自动、可刷新。
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { harvestDts, type HarvestedEnv } from "@nudojs/harvester";
+import { collectDtsFiles, resolvePackageRoot } from "./harvest-package.ts";
+
+export type NodeEnvResult =
+  | { ok: true; env: HarvestedEnv; root: string; files: number }
+  | { ok: false; error: string };
+
+/** harvest @types/node（限制文件数 + 时间预算，避免拖垮启动） */
+export function harvestNodeTypes(
+  fromDir?: string,
+  maxFiles = 12,
+  maxMs = 2500,
+): NodeEnvResult {
+  // @types/node 在 node_modules/@types/node
+  const root =
+    resolvePackageRoot("@types/node", fromDir) ??
+    resolvePackageRoot("node", fromDir);
+  if (!root || !existsSync(root)) {
+    return { ok: false, error: "@types/node not found" };
+  }
+  // 优先 index.d.ts 等入口
+  const dts = collectDtsFiles(root, maxFiles);
+  if (dts.length === 0) {
+    return { ok: false, error: `no .d.ts under ${root}` };
+  }
+  const env = harvestDts(dts, { maxMs });
+  return { ok: true, env, root, files: env.stats.files };
+}
+
+/** 把 harvest 结果压成「模块名 → 导出名列表」摘要，便于日志/测试 */
+export function summarizeNodeEnv(env: HarvestedEnv): {
+  modules: string[];
+  globals: string[];
+  symbolCount: number;
+} {
+  return {
+    modules: Object.keys(env.modules).sort(),
+    globals: Object.keys(env.globals).sort().slice(0, 50),
+    symbolCount: env.stats.symbols,
+  };
+}

package/src/harvest-package.ts

@@ -0,0 +1,204 @@
+/**
+ * Host：从 npm 包 / @types 收集 .d.ts → harvestDts。
+ * 代数不碰 fs；这里只做「找到 dts 路径」这一层宿主职责。
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync } from "node:fs";
+import { join, resolve, dirname, basename } from "node:path";
+import { harvestDts, type HarvestedEnv } from "@nudojs/harvester";
+import { typeValueToString, type TypeValue } from "@nudojs/core";
+
+/** 在 node_modules 中解析包根（含 @types/*） */
+export function resolvePackageRoot(
+  pkg: string,
+  fromDir: string = process.cwd(),
+): string | undefined {
+  let dir = resolve(fromDir);
+  const bare = pkg.replace(/^@/, "").replace(/\//g, "__");
+  // 向上找 node_modules；每层重算候选（@types 优先：lodash 等包本体无 index.d.ts）
+  for (let i = 0; i < 8; i++) {
+    const typesPath = join(dir, "node_modules", "@types", bare);
+    if (existsSync(typesPath)) return typesPath;
+    const pkgPath = join(dir, "node_modules", pkg);
+    if (existsSync(pkgPath)) return pkgPath;
+    const parent = resolve(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+const SKIP_DIRS = new Set(["node_modules", "test", "tests", "docs", "doc", "examples", "__tests__"]);
+/** 单文件上限：巨型 lib.d.ts 级别拖垮 harvest */
+const MAX_DTS_BYTES = 1_500_000;
+
+/** 优先入口：index.d.ts / pkg 名 / lib 入口 */
+function dtsPriority(p: string, root: string): number {
+  const base = basename(p);
+  const rel = p.slice(root.length);
+  if (base === "index.d.ts") return 0;
+  if (base === "index.d.mts") return 1;
+  if (rel.includes("/types/") && base === "index.d.ts") return 2;
+  if (base.endsWith(".d.ts") && !base.includes(".")) return 3; // foo.d.ts
+  return 10;
+}
+
+/**
+ * 递归收集包内 .d.ts（限制数量 + 跳过超大文件 + 入口优先）。
+ */
+export function collectDtsFiles(root: string, maxFiles = 8): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    if (out.length >= maxFiles * 3) return; // 多收一点再排序截断
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (out.length >= maxFiles * 3) return;
+      if (SKIP_DIRS.has(name)) continue;
+      const p = join(dir, name);
+      let st;
+      try {
+        st = statSync(p);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) walk(p);
+      else if (name.endsWith(".d.ts") && !name.endsWith(".d.ts.map")) {
+        if (st.size > MAX_DTS_BYTES) continue;
+        out.push(p);
+      }
+    }
+  };
+  walk(root);
+  out.sort((a, b) => dtsPriority(a, root) - dtsPriority(b, root) || a.length - b.length);
+  return out.slice(0, maxFiles);
+}
+
+/** package.json types/typings 入口（若存在且合理大小） */
+function entryDtsFromPackageJson(root: string): string | undefined {
+  const pj = join(root, "package.json");
+  if (!existsSync(pj)) return undefined;
+  try {
+    const raw = JSON.parse(readFileSync(pj, "utf8")) as {
+      types?: string;
+      typings?: string;
+      exports?: Record<string, unknown>;
+    };
+    const entry = raw.types ?? raw.typings;
+    if (typeof entry === "string" && entry.endsWith(".d.ts")) {
+      const p = resolve(root, entry);
+      if (existsSync(p)) {
+        const st = statSync(p);
+        if (st.size <= MAX_DTS_BYTES) return p;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return undefined;
+}
+
+export type PackageHarvest = {
+  pkg: string;
+  root: string;
+  dtsFiles: string[];
+  env: HarvestedEnv;
+};
+
+/**
+ * 从入口 .d.ts 沿 reference path / 相对 import 做 BFS 收集。
+ * 适合 @types 包（三斜线引用图）；比整树 walk 更贴声明入口。
+ */
+export function collectDtsFromEntry(entry: string, maxFiles = 200): string[] {
+  const files: string[] = [];
+  const seen = new Set<string>();
+  const queue = [entry];
+  const REFERENCE_PATH_REGEX = /<reference\s+path=["']([^"']+)["']\s*\/>/g;
+  const RELATIVE_FROM_REGEX = /\bfrom\s+["'](\.[^"']+)["']/g;
+
+  while (queue.length > 0 && files.length < maxFiles) {
+    const current = queue.shift()!;
+    if (seen.has(current) || !existsSync(current)) continue;
+    seen.add(current);
+    if (!current.endsWith(".d.ts")) continue;
+    files.push(current);
+
+    let text: string;
+    try {
+      text = readFileSync(current, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const dir = dirname(current);
+    for (const match of text.matchAll(REFERENCE_PATH_REGEX)) {
+      queue.push(resolve(dir, match[1]!));
+    }
+    for (const match of text.matchAll(RELATIVE_FROM_REGEX)) {
+      const base = resolve(dir, match[1]!);
+      for (const candidate of [`${base}.d.ts`, join(base, "index.d.ts")]) {
+        if (existsSync(candidate)) {
+          queue.push(candidate);
+          break;
+        }
+      }
+    }
+  }
+
+  return files;
+}
+
+/** harvest 一个 npm 包（或 @types 包） */
+export function harvestPackage(
+  pkg: string,
+  fromDir?: string,
+  maxFiles = 8,
+): PackageHarvest | { error: string } {
+  const root = resolvePackageRoot(pkg, fromDir);
+  if (!root) return { error: `package not found: ${pkg}` };
+  const entry = entryDtsFromPackageJson(root) ?? join(root, "index.d.ts");
+  // 入口 BFS 优先（@types 引用图）；退化为整树 walk
+  let dtsFiles = existsSync(entry) ? collectDtsFromEntry(entry, maxFiles) : [];
+  if (dtsFiles.length === 0) {
+    const collected = collectDtsFiles(root, maxFiles);
+    dtsFiles =
+      entry && existsSync(entry) && !collected.includes(entry)
+        ? [entry, ...collected.filter((f) => f !== entry)].slice(0, maxFiles)
+        : collected;
+  }
+  if (dtsFiles.length === 0) {
+    return { error: `no .d.ts under ${root}` };
+  }
+  const env = harvestDts(dtsFiles);
+  return { pkg, root, dtsFiles, env };
+}
+
+/** harvest 结果 → 人类可读导出表 */
+export function formatHarvestSummary(h: PackageHarvest): string {
+  const lines: string[] = [];
+  lines.push(`${h.pkg}: ${h.dtsFiles.length} d.ts, ${h.env.stats.symbols} symbols`);
+  const mods = Object.keys(h.env.modules);
+  for (const m of mods.slice(0, 5)) {
+    const exports = h.env.modules[m]!;
+    const names = Object.keys(exports).slice(0, 12);
+    lines.push(`  module "${m}": ${names.join(", ")}${Object.keys(exports).length > 12 ? "…" : ""}`);
+  }
+  if (mods.length > 5) lines.push(`  … ${mods.length - 5} more modules`);
+  return lines.join("\n");
+}
+
+/** 取某个导出的 TypeValue 字符串 */
+export function lookupHarvested(
+  h: PackageHarvest,
+  moduleName: string,
+  exportName: string,
+): string | undefined {
+  const mod = h.env.modules[moduleName];
+  const tv = mod?.[exportName] ?? h.env.globals[exportName];
+  if (!tv) return undefined;
+  return typeValueToString(tv as TypeValue);
+}

package/src/harvest-to-abs.ts

@@ -0,0 +1,129 @@
+/**
+ * Harvest TypeValue 导出 → AbsModuleExports（供 Abs 模块图注入）。
+ * fnSig → absFunction + apply 直接返回声明返回类型（conf=mock）。
+ */
+
+import type { TypeValue } from "@nudojs/core";
+import {
+  T,
+  type Abs,
+  typeValueToAbs,
+  confJoin,
+  getFnSig,
+  absFunction,
+} from "@nudojs/core";
+import type { AbsModuleExports } from "@nudojs/core";
+import { dirname } from "node:path";
+import type { PackageHarvest } from "./harvest-package.ts";
+import { harvestPackageCached } from "./harvest-auto.ts";
+
+function markMockConf(a: Abs): Abs {
+  a.conf = confJoin(a.conf, "mock");
+  return a;
+}
+
+/** 单个 TypeValue 导出 → Abs（可调用） */
+export function harvestedValueToAbs(tv: TypeValue): Abs {
+  if (!tv) return markMockConf(typeValueToAbs(T.unknown));
+  const sig = getFnSig(tv);
+  if (sig) {
+    const ret = markMockConf(typeValueToAbs(sig.returnType));
+    const params =
+      tv.kind === "function" && tv.params?.length
+        ? tv.params
+        : sig.paramTypes.map((_, i) => `_arg${i}`);
+    const dummyBody = {
+      type: "BlockStatement",
+      body: [],
+      directives: [],
+    } as never;
+    return markMockConf(
+      absFunction(params, {
+        body: dummyBody,
+        apply: () => ret,
+      }),
+    );
+  }
+  return markMockConf(typeValueToAbs(tv));
+}
+
+/**
+ * 把 harvest 的 modules/globals 合成 AbsModuleExports。
+ * 键同时登记：原始模块路径、包名、basename（path / @types/path）。
+ */
+export function harvestToAbsModules(
+  pkg: string,
+  fromDir: string,
+): Record<string, AbsModuleExports> {
+  const h = harvestPackageCached(pkg, fromDir);
+  if (!h) return {};
+  return packageHarvestToAbsModules(pkg, h);
+}
+
+export function packageHarvestToAbsModules(
+  pkg: string,
+  h: PackageHarvest,
+): Record<string, AbsModuleExports> {
+  const out: Record<string, AbsModuleExports> = {};
+
+  const convertRecord = (
+    rec: Record<string, TypeValue>,
+  ): Record<string, Abs> => {
+    const named: Record<string, Abs> = {};
+    for (const [k, v] of Object.entries(rec)) {
+      named[k] = harvestedValueToAbs(v);
+    }
+    return named;
+  };
+
+  const register = (key: string, exports: AbsModuleExports) => {
+    if (!out[key]) out[key] = exports;
+  };
+
+  for (const [mod, rec] of Object.entries(h.env.modules)) {
+    const named = convertRecord(rec);
+    const exports: AbsModuleExports = { named };
+    const def = rec["default"];
+    if (def) exports.default = harvestedValueToAbs(def);
+    register(mod, exports);
+    // 包名 / 去掉 @types/ 前缀 / basename
+    register(pkg, exports);
+    const stripped = mod.replace(/^@types\//, "").replace(/\\/g, "/");
+    if (stripped) register(stripped, exports);
+    const base = stripped.split("/").filter(Boolean).pop();
+    if (base && base !== pkg) register(base, exports);
+  }
+
+  // globals 也挂到包名（default / namespace 消费）
+  const globalNamed = convertRecord(h.env.globals);
+  if (Object.keys(globalNamed).length > 0) {
+    const existing = out[pkg];
+    if (existing) {
+      out[pkg] = { named: { ...globalNamed, ...existing.named }, default: existing.default };
+    } else {
+      out[pkg] = { named: globalNamed };
+    }
+  }
+
+  return out;
+}
+
+/** 裸说明符 → Abs 导出表（走 harvest 缓存） */
+export function bareSpecToAbsModules(
+  spec: string,
+  fromFile: string,
+): AbsModuleExports | undefined {
+  // node: 内建交给 env，不 harvest
+  if (!spec || spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("node:")) {
+    return undefined;
+  }
+  const parts = spec.split("/");
+  const pkg = spec.startsWith("@")
+    ? parts.length >= 2
+      ? `${parts[0]}/${parts[1]}`
+      : undefined
+    : parts[0];
+  if (!pkg) return undefined;
+  const table = harvestToAbsModules(pkg, dirname(fromFile));
+  return table[spec] ?? table[pkg];
+}