@nudojs/service 0.2.0 → 0.3.0

package/src/bpath-diagnostics.ts

@@ -0,0 +1,283 @@
+/**
+ * B 路径静态诊断（AST，不执行）：
+ * - unreachable：同块 return/throw 之后的语句
+ * - builtin-unknown：未声明的全局调用（非 import / 局部 / $runtime）
+ */
+
+import { parseSource } from "@nudojs/core";
+import type { File, Node, Statement, Identifier } from "@babel/types";
+
+export type BPathLoc = {
+  start: { line: number; column: number };
+  end: { line: number; column: number };
+};
+
+export type BPathUnreachable = { range: BPathLoc };
+export type BPathBuiltinUnknown = { name: string; range: BPathLoc };
+
+export type BPathDiagnostics = {
+  unreachable: BPathUnreachable[];
+  builtinUnknown: BPathBuiltinUnknown[];
+};
+
+function locOf(node: Node): BPathLoc | null {
+  if (!node.loc) return null;
+  return {
+    start: { line: node.loc.start.line, column: node.loc.start.column },
+    end: { line: node.loc.end.line, column: node.loc.end.column },
+  };
+}
+
+function isExit(stmt: Statement): boolean {
+  return stmt.type === "ReturnStatement" || stmt.type === "ThrowStatement";
+}
+
+function walkUnreachable(node: Node, out: BPathUnreachable[]): void {
+  const n = node as {
+    type: string;
+    body?: unknown;
+    consequent?: Node;
+    alternate?: Node | null | undefined;
+    block?: Node;
+    handler?: { body?: Node } | null;
+    finalizer?: Node | null;
+    [k: string]: unknown;
+  };
+
+  const checkBlock = (block: unknown) => {
+    if (!block) return;
+    const body =
+      (block as { body?: Statement[] }).body ??
+      (Array.isArray(block) ? (block as Statement[]) : null);
+    if (!Array.isArray(body)) return;
+    for (let i = 0; i < body.length; i++) {
+      walkUnreachable(body[i]!, out);
+      if (isExit(body[i]!)) {
+        for (let j = i + 1; j < body.length; j++) {
+          const r = locOf(body[j]!);
+          if (r) out.push({ range: r });
+        }
+        break;
+      }
+    }
+  };
+
+  switch (n.type) {
+    case "Program":
+    case "BlockStatement":
+      checkBlock(n.body);
+      break;
+    case "FunctionDeclaration":
+    case "FunctionExpression":
+    case "ArrowFunctionExpression":
+      if (n.body) walkUnreachable(n.body as Node, out);
+      break;
+    case "IfStatement":
+      if (n.consequent) walkUnreachable(n.consequent, out);
+      if (n.alternate) walkUnreachable(n.alternate, out);
+      break;
+    case "ForStatement":
+    case "ForInStatement":
+    case "ForOfStatement":
+    case "WhileStatement":
+    case "DoWhileStatement":
+      if (n.body) walkUnreachable(n.body as Node, out);
+      break;
+    case "TryStatement":
+      if (n.block) walkUnreachable(n.block as Node, out);
+      if (n.handler?.body) walkUnreachable(n.handler.body, out);
+      if (n.finalizer) walkUnreachable(n.finalizer as Node, out);
+      break;
+    case "SwitchStatement":
+      for (const c of (n as { cases?: Array<{ consequent?: Statement[] }> }).cases ?? []) {
+        checkBlock(c.consequent);
+      }
+      break;
+    case "ExportNamedDeclaration":
+    case "ExportDefaultDeclaration": {
+      const decl = (n as { declaration?: Node }).declaration;
+      if (decl) walkUnreachable(decl, out);
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+/** 文件内声明的名字（函数/类/变量/参数/import） */
+function collectDeclared(file: File): Set<string> {
+  const names = new Set<string>();
+  const addId = (id: Node | null | undefined) => {
+    if (!id) return;
+    if (id.type === "Identifier") names.add((id as Identifier).name);
+    if (id.type === "ObjectPattern") {
+      for (const p of (id as { properties: Array<{ value?: Node }> }).properties) {
+        addId(p.value);
+      }
+    }
+    if (id.type === "ArrayPattern") {
+      for (const el of (id as { elements: Array<Node | null> }).elements) addId(el);
+    }
+  };
+  const visit = (node: unknown) => {
+    if (!node || typeof node !== "object") return;
+    const o = node as { type?: string; [k: string]: unknown };
+    switch (o.type) {
+      case "FunctionDeclaration":
+      case "ClassDeclaration":
+        addId((o as { id?: Node }).id);
+        break;
+      case "VariableDeclarator":
+        addId((o as { id?: Node }).id);
+        break;
+      case "ImportSpecifier":
+      case "ImportDefaultSpecifier":
+      case "ImportNamespaceSpecifier":
+        addId((o as { local?: Node }).local);
+        break;
+      default:
+        break;
+    }
+    // params
+    if (o.params && Array.isArray(o.params)) {
+      for (const p of o.params) addId(p as Node);
+    }
+    for (const key of Object.keys(o)) {
+      if (key === "loc" || key === "start" || key === "end") continue;
+      const v = o[key];
+      if (Array.isArray(v)) v.forEach(visit);
+      else if (v && typeof v === "object") visit(v);
+    }
+  };
+  visit(file);
+  return names;
+}
+
+/** 已知可接受的全局（不报 builtin-unknown）——不含 WeakRef 等未覆盖 API */
+const KNOWN_GLOBALS = new Set([
+  "Object",
+  "Array",
+  "String",
+  "Number",
+  "Boolean",
+  "Symbol",
+  "Math",
+  "JSON",
+  "Promise",
+  "Error",
+  "TypeError",
+  "RangeError",
+  "SyntaxError",
+  "RegExp",
+  "Date",
+  "Map",
+  "Set",
+  "WeakMap",
+  "WeakSet",
+  "console",
+  "undefined",
+  "NaN",
+  "Infinity",
+  "globalThis",
+  "parseInt",
+  "parseFloat",
+  "isNaN",
+  "isFinite",
+]);
+
+function isFreeUnknown(
+  name: string,
+  declared: Set<string>,
+  seen: Set<string>,
+  known: Set<string>,
+): boolean {
+  return (
+    !declared.has(name) &&
+    !known.has(name) &&
+    !name.startsWith("$") &&
+    !seen.has(name)
+  );
+}
+
+function walkBuiltinUnknown(
+  node: Node,
+  declared: Set<string>,
+  out: BPathBuiltinUnknown[],
+  seen: Set<string>,
+  known: Set<string>,
+  parentKey?: string,
+): void {
+  const n = node as {
+    type?: string;
+    callee?: Node;
+    name?: string;
+    [k: string]: unknown;
+  };
+  const flag = (idNode: Node, name: string) => {
+    if (!isFreeUnknown(name, declared, seen, known)) return;
+    const range = locOf(idNode) ?? locOf(node);
+    if (range) {
+      out.push({ name, range });
+      seen.add(name);
+    }
+  };
+
+  if (n.type === "CallExpression" && n.callee?.type === "Identifier") {
+    flag(n.callee, (n.callee as Identifier).name);
+  } else if (
+    n.type === "Identifier" &&
+    typeof n.name === "string" &&
+    parentKey !== "key" &&
+    parentKey !== "property" &&
+    parentKey !== "local" &&
+    parentKey !== "id"
+  ) {
+    // 裸标识符引用（如 return WeakRef）
+    flag(node as Node, n.name);
+  }
+
+  for (const key of Object.keys(n)) {
+    if (key === "loc" || key === "start" || key === "end") continue;
+    const v = n[key];
+    if (Array.isArray(v)) {
+      v.forEach((x) => {
+        if (x && typeof x === "object" && "type" in (x as object)) {
+          walkBuiltinUnknown(x as Node, declared, out, seen, known, key);
+        }
+      });
+    } else if (v && typeof v === "object" && "type" in (v as object)) {
+      walkBuiltinUnknown(v as Node, declared, out, seen, known, key);
+    }
+  }
+}
+
+/**
+ * 静态收集 B 路径诊断。
+ * extraKnown：@nudo:mock / @nudo:env 已覆盖的全局名（B 注入后不再是裸原生
+ * 调用，不得误报 builtin-unknown——收集器只吃 AST，看不到指令）。
+ */
+export function collectBPathDiagnostics(
+  source: string,
+  extraKnown?: Iterable<string>,
+): BPathDiagnostics {
+  let file: File;
+  try {
+    file = parseSource(source);
+  } catch {
+    return { unreachable: [], builtinUnknown: [] };
+  }
+  const unreachable: BPathUnreachable[] = [];
+  // File → program
+  const root = (file as unknown as { type: string; program?: Node }).program ?? file;
+  walkUnreachable(root as Node, unreachable);
+
+  const declared = collectDeclared(file);
+  const known = new Set(KNOWN_GLOBALS);
+  if (extraKnown) {
+    for (const n of extraKnown) known.add(n);
+  }
+  const builtinUnknown: BPathBuiltinUnknown[] = [];
+  walkBuiltinUnknown(file, declared, builtinUnknown, new Set(), known);
+
+  return { unreachable, builtinUnknown };
+}

package/src/bpath-run.ts

@@ -0,0 +1,409 @@
+/**
+ * B 路径能力判定 + 进程内 transpile 执行（service 入口）。
+ *
+ * 分析默认 mode="analyze"：不执行顶层副作用，只保留函数定义。
+ * throws 经 callTranspiledExportFull 捕获 $throw。
+ */
+
+import {
+  runTranspiled,
+  callTranspiledExport,
+  callTranspiledExportFull,
+  setBCallCollector,
+  setMemberDiagCollector,
+  setAbsTruncationCollector,
+  typeValueToAbs,
+  createEnvironment,
+  type BCallRecord,
+  type BMemberDiag,
+  type TranspiledCallResult,
+  type Abs,
+  type AbsModuleExports,
+  stableAnalyzeKeySource,
+  formatAbs,
+  hashSource,
+  getFnImpl,
+} from "@nudojs/core";
+import { parse, extractInlineDirectives } from "@nudojs/parser";
+import { loadEnvs } from "@nudojs/cli/evaluator";
+import { evalAbsModuleGraph } from "./abs-modules-graph.ts";
+import { envValueToAbs } from "./env-to-abs.ts";
+import { clearAnalysisFileCache } from "./analysis-file-cache.ts";
+import { clearFnAnalysisCache } from "./fn-analysis-cache.ts";
+
+/** Content part for one Abs mock seed. */
+function absSeedPart(a: Abs): string {
+  const impl = getFnImpl(a);
+  if (impl?.fingerprint) return impl.fingerprint;
+  if (a.shape.k === "fn") {
+    const ret = impl?.env?.vars?.get("__nudo_mock_ret");
+    if (ret) {
+      try {
+        return `ret=${formatAbs(ret)}`;
+      } catch {
+        return "ret=?";
+      }
+    }
+    if (impl?.apply) return "apply";
+  }
+  try {
+    return formatAbs(a);
+  } catch {
+    return "?";
+  }
+}
+
+function seedFnPart(name: string, fn: { params: string[]; body: unknown; fingerprint?: string }): string {
+  if (fn.fingerprint) return `${name}:${fn.fingerprint}`;
+  const body = fn.body as { start?: number; end?: number; type?: string } | undefined;
+  const bodyKey =
+    body && typeof body.start === "number" && typeof body.end === "number"
+      ? `${body.start}:${body.end}:${body.type ?? ""}`
+      : String(body?.type ?? "?");
+  return `${name}(${fn.params.join(",")})@${bodyKey}`;
+}
+
+/**
+ * Cache key for @nudo:mock seeds: name list alone is not enough — same names
+ * with different Abs values must miss. Uses AbsFnImpl.fingerprint when the
+ * mock pipeline stamped one (formatAbs cannot see WeakMap-side returns/withArgs).
+ */
+export function mockSeedFingerprint(
+  mocks?: Record<string, Abs>,
+  seedFns?: Record<string, { params: string[]; body: unknown; fingerprint?: string }>,
+): string {
+  const parts: string[] = [];
+  if (mocks) {
+    const names = Object.keys(mocks).sort();
+    for (const n of names) parts.push(`${n}=${absSeedPart(mocks[n]!)}`);
+  }
+  if (seedFns) {
+    const names = Object.keys(seedFns).sort();
+    for (const n of names) parts.push(`fn:${seedFnPart(n, seedFns[n]!)}`);
+  }
+  if (parts.length === 0) return "-";
+  return hashSource(parts.join(";"));
+}
+
+/** @nudo:env → Abs 全局表（保留 fnSig impl） */
+export function collectEnvGlobals(envNames: string[]): Record<string, Abs> {
+  if (envNames.length === 0) return {};
+  const env = createEnvironment();
+  try {
+    loadEnvs(envNames, env);
+  } catch {
+    return {};
+  }
+  const out: Record<string, Abs> = {};
+  for (const [k, v] of Object.entries(env.getOwnBindings())) {
+    out[k] = envValueToAbs(v);
+  }
+  return out;
+}
+
+/** @nudo:env modules（path / node:path / fs…）→ AbsModuleExports */
+export function collectEnvModules(envNames: string[]): Record<string, AbsModuleExports> {
+  if (envNames.length === 0) return {};
+  const env = createEnvironment();
+  let mods: Record<string, Record<string, import("@nudojs/core").TypeValue>> = {};
+  try {
+    mods = loadEnvs(envNames, env).modules;
+  } catch {
+    return {};
+  }
+  const out: Record<string, AbsModuleExports> = {};
+  for (const [spec, exports] of Object.entries(mods)) {
+    const named: Record<string, Abs> = {};
+    for (const [k, v] of Object.entries(exports)) {
+      named[k] = envValueToAbs(v);
+    }
+    out[spec] = { named };
+  }
+  return out;
+}
+
+/** 收集 @nudo:replace + @nudo:as → transpile 注入表 */
+export function collectBPathReplacements(source: string): {
+  targets: Array<{
+    target: string;
+    varName: string;
+    stmtStart?: number;
+    stmtEnd?: number;
+  }>;
+  values: Record<string, Abs>;
+  asTargets: Array<{ varName: string; stmtStart: number; stmtEnd: number }>;
+  asValues: Record<string, Abs>;
+} {
+  const targets: Array<{
+    target: string;
+    varName: string;
+    stmtStart?: number;
+    stmtEnd?: number;
+  }> = [];
+  const values: Record<string, Abs> = {};
+  const asTargets: Array<{ varName: string; stmtStart: number; stmtEnd: number }> = [];
+  const asValues: Record<string, Abs> = {};
+  let i = 0;
+  try {
+    const file = parse(source);
+    const visitStmts = (stmts: unknown[]) => {
+      for (const stmt of stmts) {
+        if (!stmt || typeof stmt !== "object") continue;
+        const loc = (stmt as { loc?: { start: { line: number }; end: { line: number } } }).loc;
+        const dirs = extractInlineDirectives(stmt as never);
+        for (const d of dirs) {
+          if (d.kind === "replace") {
+            const varName = `__rep${i++}`;
+            targets.push({
+              target: d.targetSource,
+              varName,
+              stmtStart: loc?.start.line,
+              stmtEnd: loc?.end.line,
+            });
+            values[varName] = typeValueToAbs(d.typeExpr);
+          } else if (d.kind === "as" && loc) {
+            const varName = `__as${i++}`;
+            asTargets.push({
+              varName,
+              stmtStart: loc.start.line,
+              stmtEnd: loc.end.line,
+            });
+            asValues[varName] = typeValueToAbs(d.typeExpr);
+          }
+        }
+        const s = stmt as {
+          type?: string;
+          body?: unknown;
+          block?: unknown;
+          consequent?: unknown;
+          alternate?: unknown;
+          declaration?: unknown;
+        };
+        if (s.type === "BlockStatement" && Array.isArray(s.body)) visitStmts(s.body);
+        if (s.type === "FunctionDeclaration" || s.type === "FunctionExpression") {
+          if (s.body) visitStmts([s.body]);
+        }
+        if (s.type === "ExportNamedDeclaration" && s.declaration) {
+          visitStmts([s.declaration]);
+        }
+        if (s.type === "IfStatement") {
+          if (s.consequent) visitStmts([s.consequent]);
+          if (s.alternate) visitStmts([s.alternate]);
+        }
+      }
+    };
+    visitStmts(file.program.body);
+  } catch {
+    /* ignore */
+  }
+  return { targets, values, asTargets, asValues };
+}
+
+/** 可走 transpile+exec：env 经 loadEnvs（内置 + 已 preload 的路径型） */
+export function isBPathCapable(source: string, envNames: string[] = []): boolean {
+  void envNames;
+  // 顶层 this. 仍不支持（方法内 this 由 transpile 处理）
+  if (/(^|[^.\w$])this\s*\./.test(source) && !/\bclass\s+/.test(source)) return false;
+  return true;
+}
+
+export type BPathRunResult = {
+  exports: Record<string, unknown>;
+  modules: Record<string, AbsModuleExports>;
+  /** 顶层执行期 method-missing */
+  memberDiags?: BMemberDiag[];
+  /** 模块图 cycle/depth/missing（B 权威） */
+  moduleIssues?: import("./abs-modules-graph.ts").AbsModuleLoadIssue[];
+  /** Abs 求值递归截断的函数标签 */
+  truncatedFns?: string[];
+  /** 顶层 $callNamed 调用点（call@ 合成；不经 TypeValue collector） */
+  calls?: BCallRecord[];
+};
+
+/** 按入口文件键控：同文件同源 O(1) 身份比较（case 循环 400 次不再重哈希） */
+type BCacheEntry = {
+  stableSource: string;
+  mode: string;
+  envKey: string;
+  mockKey: string;
+  value: BPathRunResult | null;
+};
+const bRunByFile = new Map<string, BCacheEntry>();
+const MAX_B_RUN_CACHE = 32;
+
+export function clearBPathCache(): void {
+  bRunByFile.clear();
+  // 测试/宿主习惯：清 B-path 时一并丢掉整文件/函数级分析缓存
+  clearAnalysisFileCache();
+  clearFnAnalysisCache();
+}
+
+/** 依赖文件变更后：逐出以这些文件为入口的 B-path 缓存 */
+export function evictBPathCacheForFiles(files: string[]): number {
+  let n = 0;
+  for (const f of files) {
+    if (bRunByFile.delete(f)) n++;
+  }
+  return n;
+}
+
+function bPathCacheSet(
+  filePath: string,
+  stableSource: string,
+  mode: string,
+  envKey: string,
+  mockKey: string,
+  value: BPathRunResult | null,
+): void {
+  if (bRunByFile.size >= MAX_B_RUN_CACHE && !bRunByFile.has(filePath)) {
+    const oldest = bRunByFile.keys().next().value;
+    if (oldest !== undefined) bRunByFile.delete(oldest);
+  }
+  bRunByFile.set(filePath, { stableSource, mode, envKey, mockKey, value });
+}
+
+/** 模块图 + runTranspiled（默认 analyze 模式） */
+export function tryRunBPath(
+  source: string,
+  filePath: string,
+  opts: {
+    maxLoopIters?: number;
+    mode?: "exec" | "analyze";
+    envNames?: string[];
+    /** @nudo:mock → Abs，注入为全局绑定（防止顶层调用真 fetch 等） */
+    mocks?: Record<string, Abs>;
+  } = {},
+): BPathRunResult | undefined {
+  if (!isBPathCapable(source, opts.envNames ?? [])) return undefined;
+  const mode = opts.mode ?? "analyze";
+  const envKey = (opts.envNames ?? []).join(",");
+  const mockKey = mockSeedFingerprint(opts.mocks);
+  // 尾部无 @nudo 注释不参与：comment-only 编辑命中 B-path。
+  // 同 source 引用时 stable 快路径返回原串 → 下方 === 为 O(1)。
+  const stable = stableAnalyzeKeySource(source);
+  const cached = bRunByFile.get(filePath);
+  if (
+    cached &&
+    cached.stableSource === stable &&
+    cached.mode === mode &&
+    cached.envKey === envKey &&
+    cached.mockKey === mockKey
+  ) {
+    // LRU：命中移到队尾
+    bRunByFile.delete(filePath);
+    bRunByFile.set(filePath, cached);
+    return cached.value ?? undefined;
+  }
+  let out: BPathRunResult | null = null;
+  try {
+    const memberDiags: BMemberDiag[] = [];
+    const truncated = new Set<string>();
+    const topCalls: BCallRecord[] = [];
+    // collector 先于模块图：import 函数体在 evalProgramAbs 内的 method-missing 也要收
+    setMemberDiagCollector((d) => memberDiags.push(d));
+    setAbsTruncationCollector((label) => truncated.add(label));
+    setBCallCollector((r) => topCalls.push(r));
+    try {
+      const { modules: graphMods, issues } = evalAbsModuleGraph(source, filePath);
+      const envMods = collectEnvModules(opts.envNames ?? []);
+      const modules = { ...envMods, ...graphMods };
+      const { targets, values, asTargets, asValues } = collectBPathReplacements(source);
+      const envGlobals = {
+        ...collectEnvGlobals(opts.envNames ?? []),
+        ...(opts.mocks ?? {}),
+      };
+      const exports = runTranspiled(source, {
+        modules: modules as never,
+        maxLoopIters: opts.maxLoopIters,
+        mode: opts.mode ?? "analyze",
+        replacementTargets: targets.length ? targets : undefined,
+        replacements: targets.length ? values : undefined,
+        asOverrideTargets: asTargets.length ? asTargets : undefined,
+        asOverrides: asTargets.length ? asValues : undefined,
+        envGlobals: Object.keys(envGlobals).length ? envGlobals : undefined,
+      });
+      out = {
+        exports,
+        modules,
+        memberDiags: memberDiags.length ? memberDiags : undefined,
+        moduleIssues: issues.length ? issues : undefined,
+        truncatedFns: truncated.size ? [...truncated] : undefined,
+        calls: topCalls.length ? topCalls : undefined,
+      };
+    } finally {
+      setMemberDiagCollector(null);
+      setAbsTruncationCollector(null);
+      setBCallCollector(null);
+    }
+  } catch {
+    out = null;
+  }
+  bPathCacheSet(filePath, stable, mode, envKey, mockKey, out);
+  return out ?? undefined;
+}
+
+/** B 路径求值具名导出（结果 + throws）；opts.collectCalls 时附带调用点记录 */
+export function tryBPathCallFull(
+  source: string,
+  filePath: string,
+  fnName: string,
+  args: Abs[],
+  opts: {
+    collectCalls?: boolean;
+    collectMemberDiags?: boolean;
+    envNames?: string[];
+    mocks?: Record<string, Abs>;
+  } = {},
+): (TranspiledCallResult & {
+  calls?: BCallRecord[];
+  memberDiags?: BMemberDiag[];
+  moduleIssues?: import("./abs-modules-graph.ts").AbsModuleLoadIssue[];
+  truncatedFns?: string[];
+}) | undefined {
+  const run = tryRunBPath(source, filePath, { envNames: opts.envNames, mocks: opts.mocks });
+  if (!run) return undefined;
+  if (!(fnName in run.exports)) return undefined;
+  const collected: BCallRecord[] = [...(run.calls ?? [])];
+  const memberDiags: BMemberDiag[] = [];
+  if (opts.collectCalls) {
+    setBCallCollector((r) => collected.push(r));
+  }
+  if (opts.collectMemberDiags ?? true) {
+    setMemberDiagCollector((d) => memberDiags.push(d));
+  }
+  try {
+    const full = callTranspiledExportFull(run.exports, fnName, args);
+    const all = [...(run.memberDiags ?? []), ...memberDiags];
+    return {
+      ...full,
+      calls: opts.collectCalls || run.calls?.length ? collected : undefined,
+      memberDiags: all.length ? all : undefined,
+      moduleIssues: run.moduleIssues,
+      truncatedFns: run.truncatedFns,
+    };
+  } finally {
+    if (opts.collectCalls) setBCallCollector(null);
+    setMemberDiagCollector(null);
+  }
+}
+
+/** B 路径求值具名导出（仅成功结果） */
+export function tryBPathCall(
+  source: string,
+  filePath: string,
+  fnName: string,
+  args: Abs[],
+  opts: { envNames?: string[]; mocks?: Record<string, Abs> } = {},
+): Abs | undefined {
+  const full = tryBPathCallFull(source, filePath, fnName, args, opts);
+  if (!full) return undefined;
+  const r = full.result;
+  if (!r) return undefined;
+  if (r.shape.k === "never" && full.throws.shape.k !== "never") {
+    return undefined;
+  }
+  if (r.shape.k === "unknown" && !r.term) return undefined;
+  return r;
+}
+
+export { callTranspiledExport, callTranspiledExportFull };