@nudojs/service 2.0.0 → 3.0.0

package/dist/index.d.ts

@@ -479,7 +479,7 @@ declare function lookupHarvested(h: PackageHarvest, moduleName: string, exportNa
  * 手动 `nudo harvest` 仍保留；这里是分析路径上的按需注入。
  */
 
-/** 裸说明符 → 包名（含 scope）；相对/绝对/node: 内建返回 undefined */
+/** 裸说明符 → 包名（含 scope）；相对/绝对/node: 与裸 Node 内建返回 undefined */
 declare function barePackageName(spec: string): string | undefined;
 declare function collectBarePackages(source: string): string[];
 declare function harvestPackageCached(pkg: string, fromDir: string): PackageHarvest | null;
@@ -573,6 +573,34 @@ declare function bareSpecToAbsModules(spec: string, fromFile: string): AbsModule
 declare function collectEnvGlobals(envNames: string[]): Record<string, Abs>;
 /** @nudo:env modules（path / node:path / fs…）→ AbsModuleExports */
 declare function collectEnvModules(envNames: string[]): Record<string, AbsModuleExports>;
+/** Conflict when handwritten env overwrote a harvest module/export (B8). */
+type EnvHarvestConflict = {
+    module: string;
+    /** export names where env replaced a harvest binding (empty + defaulted = default only) */
+    exports: string[];
+    defaultOverwritten: boolean;
+};
+/**
+ * Install conflict collector; returns the previous one so nested/concurrent
+ * analyzeFile callers can save/restore (module-global is not re-entrant).
+ */
+declare function setEnvHarvestConflictCollector(collector: ((c: EnvHarvestConflict) => void) | null): ((c: EnvHarvestConflict) => void) | null;
+/** Read-only peek for tests / nested restore. */
+declare function getEnvHarvestConflictCollector(): ((c: EnvHarvestConflict) => void) | null;
+type MergeHarvestOptions = {
+    /**
+     * Per-call conflict sink. Takes precedence over the module-global collector
+     * installed via `setEnvHarvestConflictCollector`.
+     */
+    onConflict?: (c: EnvHarvestConflict) => void;
+};
+/**
+ * Handwritten `@nudojs/env` wins over harvest / graph modules on overlapping
+ * module keys and overlapping export names (docs/versioning.md B8 + website
+ * harvester API). Harvest-only modules/exports are kept as fill-in.
+ * Overwrites notify `opts.onConflict` or the global collector.
+ */
+declare function mergeHarvestUnderEnv(harvestModules: Record<string, AbsModuleExports>, envModules: Record<string, AbsModuleExports>, opts?: MergeHarvestOptions): Record<string, AbsModuleExports>;
 /** 收集 @nudo:replace + @nudo:as → transpile 注入表 */
 declare function collectBPathReplacements(source: string): {
     targets: Array<{
@@ -821,18 +849,57 @@ declare function collectBPathDiagnostics(source: string, extraKnown?: Iterable<s
 /**
  * 预置 Node API env：从 @types/node 的 .d.ts harvest。
  * 与 packages/env 的手写 env 并行；此路径自动、可刷新。
+ *
+ * Productization (P0-B B2/B7):
+ * - In-process cache keyed by package root + package.json mtime/size.
+ * - Terminal failures (`not-found`/`no-dts`/`failed`) also cache — no retry storm.
+ *   `disabled` is never cached (env var can flip mid-process).
+ * - `clearNodeHarvestCache()` for tests / watch invalidation.
+ * - `NUDO_HARVEST_NODE=off` disables harvest (explicit skip, not silent).
+ * - Defaults stay IDE-budgeted: maxFiles=12, maxMs=2500.
  */
 
+/** IDE-startup budgets for @types/node harvest. Do not raise casually. */
+declare const HARVEST_NODE_DEFAULT_MAX_FILES = 12;
+declare const HARVEST_NODE_DEFAULT_MAX_MS = 2500;
+type HarvestNodeStats = {
+    files: number;
+    symbols: number;
+    skipped: number;
+};
 type NodeEnvResult = {
     ok: true;
     env: HarvestedEnv;
     root: string;
     files: number;
+    stats: HarvestNodeStats;
+    /** true when this result came from the in-process cache */
+    cached: boolean;
 } | {
     ok: false;
     error: string;
+    reason: "disabled" | "not-found" | "no-dts" | "failed";
+    /** true when this failure came from the in-process cache */
+    cached?: boolean;
 };
-/** harvest @types/node（限制文件数 + 时间预算，避免拖垮启动） */
+/**
+ * Clear the in-process @types/node harvest cache.
+ * Drops **success and terminal-failure** entries (including `not-found`), so
+ * a mid-session `@types/node` install becomes visible without process restart.
+ * Tests, watch-mode dep-hash invalidation, and package-manager hooks should
+ * call this when `node_modules/@types/node` changes underneath the process.
+ */
+declare function clearNodeHarvestCache(): void;
+/** Number of cached harvest results (diagnostics / tests). */
+declare function getNodeHarvestCacheSize(): number;
+declare function isHarvestNodeDisabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * harvest @types/node（限制文件数 + 时间预算，避免拖垮启动）。
+ * Success **and** terminal failures (`not-found` / `no-dts` / `failed`) are
+ * cached in-process so IDE analysis does not re-walk / re-timeout every file.
+ * `disabled` is never cached — the env var can flip mid-process.
+ * Call `clearNodeHarvestCache()` after `@types/node` changes.
+ */
 declare function harvestNodeTypes(fromDir?: string, maxFiles?: number, maxMs?: number): NodeEnvResult;
 /** 把 harvest 结果压成「模块名 → 导出名列表」摘要，便于日志/测试 */
 declare function summarizeNodeEnv(env: HarvestedEnv): {
@@ -1321,4 +1388,4 @@ declare function emitDerivedFromRoot(rootFile: string, opts: {
     refreshExistingOnly?: boolean;
 }): EmitDerivedResult;
 
-export { ANALYSIS_ABI, type AbsGraphOptions, type AbsMockSeeds, type AbsModuleCacheEntry, type AbsModuleGraphResult, type AbsModuleLoadIssue, AnalysisConfig, type AnalysisResult, type AnalysisSession, type BPathBuiltinUnknown, type BPathDiagnostics, type BPathRunResult, type BPathUnreachable, type BindingInfo, type BuildSemanticTokensOpts, CallRecord, type CaseHint, type CaseInfo, type CaseResult, type CompletionItem, type ConstraintSourceExpr, type DepContent, type DerivedExport, type DerivedParam, type Diagnostic, type DiagnosticSeverity, type DiagnosticTag, DiagnosticsLevel, DiskCache, type DiskCacheOptions, type DraftEvidence, type EmitDerivedResult, type EmitInterfaceOpts, type EmitInterfaceResult, type EmitInterfaceSkipReason, type EmitResult, type EmitSkipReason, type FunctionAnalysis, type HoverInfo, type InferJson, type InferJsonCase, type InferJsonFunction, type InterfaceDraftEntry, type InterfaceDraftOpts, type InterfaceDraftResult, type InterfaceSurfaceEntry, type InterfaceSurfaceOpts, type LoadModule, type ModuleExports, type ModuleGraphCache, type NodeEnvResult, type PackageHarvest, type ReferenceInfo, type RootDeriveOpts, type RootDeriveResult, SEMANTIC_TOKEN_MODIFIERS, SEMANTIC_TOKEN_TYPES, type SemanticToken, type SourceLocation, type SymbolInfo, type SymbolTable, type WriteDraftResult, absToTSType, absToZodSchema, ambientSourcesOfSidecar, analysisFileCacheKey, analyzeExportsFromSource, analyzeFile, analyzeFileAsync, autoHarvestModules, barePackageName, bareSpecToAbsModules, buildCaseDirective, buildModuleGraph, buildSemanticTokens, checkCacheKey, clearAbsModuleCache, clearAnalysisFileCache, clearAnalysisSessionCaches, clearBPathCache, clearEnvPathDeps, clearFnAnalysisCache, clearHarvestCache, collectAbsBindingsFromGraph, collectBPathDiagnostics, collectBPathReplacements, collectBarePackages, collectCallRecords, collectDependencySpecs, collectDtsFromEntry, collectEnvGlobals, collectEnvModules, collectLoadDepContents, collectParamBodyAccesses, collectStaticImports, computeDirtySet, defaultAbsLoadModule, defaultLoadModule, deriveFromRoot, diagnosticsLevelForFile, draftInterface, emitDerivedFromRoot, emitInterface, encodeSemanticTokens, envPathDependents, evalAbsModuleGraph, evalProgramAbsWithModules, evictAbsModuleCacheFiles, evictAnalysisCachesForFiles, evictAnalysisFileCacheForFiles, evictBPathCacheForFiles, evictFnAnalysisCacheForFiles, extractFnConstraintSources, extractNudoImportSpecs, filterDiagnosticsByLevel, formatDerivedSection, formatDraftModule, formatDraftSummary, formatEmitSummary, formatHarvestSummary, formatInterfaceSurfaceLine, generateDts, generateFunctionDtsLines, generateGuardFunction, generateGuardFunctionFromAbs, getAbsAtPosition, getAbsAtPositionAsync, getAnalysisFileCacheSize, getAnalysisSession, getCasesForFile, getCompletionsAtPosition, getHoverAtPosition, getTypeAtPosition, getTypeAtPositionAsync, harvestNodeTypes, harvestPackage, harvestPackageCached, harvestToAbsModules, harvestedValueToAbs, ifaceCacheKey, insertGeneratedCaseDirectives, interfaceSurface, interfaceTierModifierBit, isBPathCapable, isDraftableEntry, isEnvTemplatePath, isNudoTargetPath, isProjectConfigPath, isSidecarPath, isWatchRelevantPath, lookupHarvested, mockDirectivesToAbsSeeds, noteEnvPathDeps, packageHarvestToAbsModules, relativizePath, resetAllAnalysisCaches, resolvePackageRoot, serializeCaseArg, serializeInferJson, setAnalysisSession, sha256Hex, shouldAnalyzeFile, sidecarDraftPath, hasNudoDirectives as sourceHasNudoDirectives, stripGeneratedCaseDirectives, summarizeNodeEnv, topoSortDirty, tryBPathCall, tryBPathCallFull, tryRunBPath, unifiedDiff, writeInterfaceDraft };
+export { ANALYSIS_ABI, type AbsGraphOptions, type AbsMockSeeds, type AbsModuleCacheEntry, type AbsModuleGraphResult, type AbsModuleLoadIssue, AnalysisConfig, type AnalysisResult, type AnalysisSession, type BPathBuiltinUnknown, type BPathDiagnostics, type BPathRunResult, type BPathUnreachable, type BindingInfo, type BuildSemanticTokensOpts, CallRecord, type CaseHint, type CaseInfo, type CaseResult, type CompletionItem, type ConstraintSourceExpr, type DepContent, type DerivedExport, type DerivedParam, type Diagnostic, type DiagnosticSeverity, type DiagnosticTag, DiagnosticsLevel, DiskCache, type DiskCacheOptions, type DraftEvidence, type EmitDerivedResult, type EmitInterfaceOpts, type EmitInterfaceResult, type EmitInterfaceSkipReason, type EmitResult, type EmitSkipReason, type EnvHarvestConflict, type FunctionAnalysis, HARVEST_NODE_DEFAULT_MAX_FILES, HARVEST_NODE_DEFAULT_MAX_MS, type HarvestNodeStats, type HoverInfo, type InferJson, type InferJsonCase, type InferJsonFunction, type InterfaceDraftEntry, type InterfaceDraftOpts, type InterfaceDraftResult, type InterfaceSurfaceEntry, type InterfaceSurfaceOpts, type LoadModule, type MergeHarvestOptions, type ModuleExports, type ModuleGraphCache, type NodeEnvResult, type PackageHarvest, type ReferenceInfo, type RootDeriveOpts, type RootDeriveResult, SEMANTIC_TOKEN_MODIFIERS, SEMANTIC_TOKEN_TYPES, type SemanticToken, type SourceLocation, type SymbolInfo, type SymbolTable, type WriteDraftResult, absToTSType, absToZodSchema, ambientSourcesOfSidecar, analysisFileCacheKey, analyzeExportsFromSource, analyzeFile, analyzeFileAsync, autoHarvestModules, barePackageName, bareSpecToAbsModules, buildCaseDirective, buildModuleGraph, buildSemanticTokens, checkCacheKey, clearAbsModuleCache, clearAnalysisFileCache, clearAnalysisSessionCaches, clearBPathCache, clearEnvPathDeps, clearFnAnalysisCache, clearHarvestCache, clearNodeHarvestCache, collectAbsBindingsFromGraph, collectBPathDiagnostics, collectBPathReplacements, collectBarePackages, collectCallRecords, collectDependencySpecs, collectDtsFromEntry, collectEnvGlobals, collectEnvModules, collectLoadDepContents, collectParamBodyAccesses, collectStaticImports, computeDirtySet, defaultAbsLoadModule, defaultLoadModule, deriveFromRoot, diagnosticsLevelForFile, draftInterface, emitDerivedFromRoot, emitInterface, encodeSemanticTokens, envPathDependents, evalAbsModuleGraph, evalProgramAbsWithModules, evictAbsModuleCacheFiles, evictAnalysisCachesForFiles, evictAnalysisFileCacheForFiles, evictBPathCacheForFiles, evictFnAnalysisCacheForFiles, extractFnConstraintSources, extractNudoImportSpecs, filterDiagnosticsByLevel, formatDerivedSection, formatDraftModule, formatDraftSummary, formatEmitSummary, formatHarvestSummary, formatInterfaceSurfaceLine, generateDts, generateFunctionDtsLines, generateGuardFunction, generateGuardFunctionFromAbs, getAbsAtPosition, getAbsAtPositionAsync, getAnalysisFileCacheSize, getAnalysisSession, getCasesForFile, getCompletionsAtPosition, getEnvHarvestConflictCollector, getHoverAtPosition, getNodeHarvestCacheSize, getTypeAtPosition, getTypeAtPositionAsync, harvestNodeTypes, harvestPackage, harvestPackageCached, harvestToAbsModules, harvestedValueToAbs, ifaceCacheKey, insertGeneratedCaseDirectives, interfaceSurface, interfaceTierModifierBit, isBPathCapable, isDraftableEntry, isEnvTemplatePath, isHarvestNodeDisabled, isNudoTargetPath, isProjectConfigPath, isSidecarPath, isWatchRelevantPath, lookupHarvested, mergeHarvestUnderEnv, mockDirectivesToAbsSeeds, noteEnvPathDeps, packageHarvestToAbsModules, relativizePath, resetAllAnalysisCaches, resolvePackageRoot, serializeCaseArg, serializeInferJson, setAnalysisSession, setEnvHarvestConflictCollector, sha256Hex, shouldAnalyzeFile, sidecarDraftPath, hasNudoDirectives as sourceHasNudoDirectives, stripGeneratedCaseDirectives, summarizeNodeEnv, topoSortDirty, tryBPathCall, tryBPathCallFull, tryRunBPath, unifiedDiff, writeInterfaceDraft };

package/dist/index.js

@@ -778,6 +778,49 @@ function lookupHarvested(h, moduleName, exportName) {
 }
 
 // src/harvest-auto.ts
+var NODE_BUILTINS = /* @__PURE__ */ new Set([
+  "assert",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "diagnostics_channel",
+  "dns",
+  "domain",
+  "events",
+  "fs",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "repl",
+  "stream",
+  "string_decoder",
+  "timers",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib"
+]);
 function barePackageName(spec) {
   if (!spec) return void 0;
   if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("node:")) return void 0;
@@ -785,7 +828,9 @@ function barePackageName(spec) {
   if (spec.startsWith("@")) {
     return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : void 0;
   }
-  return parts[0];
+  const name = parts[0];
+  if (NODE_BUILTINS.has(name)) return void 0;
+  return name;
 }
 function collectBarePackages(source) {
   try {
@@ -1314,6 +1359,50 @@ function collectEnvModules(envNames) {
   }
   return out;
 }
+var envHarvestConflictCollector = null;
+function setEnvHarvestConflictCollector(collector) {
+  const prev = envHarvestConflictCollector;
+  envHarvestConflictCollector = collector;
+  return prev;
+}
+function getEnvHarvestConflictCollector() {
+  return envHarvestConflictCollector;
+}
+function mergeHarvestUnderEnv(harvestModules, envModules, opts) {
+  const out = {};
+  for (const [mod, exports] of Object.entries(harvestModules)) {
+    const named = { ...exports.named };
+    out[mod] = exports.default !== void 0 ? { named, default: exports.default } : { named };
+  }
+  const notify = opts?.onConflict ?? envHarvestConflictCollector;
+  for (const [mod, envExports] of Object.entries(envModules)) {
+    const existing = out[mod];
+    if (!existing) {
+      const named2 = { ...envExports.named };
+      out[mod] = envExports.default !== void 0 ? { named: named2, default: envExports.default } : { named: named2 };
+      continue;
+    }
+    const overwritten = [];
+    for (const key of Object.keys(envExports.named)) {
+      if (existing.named[key] !== void 0) overwritten.push(key);
+    }
+    const defaultOverwritten = envExports.default !== void 0 && existing.default !== void 0;
+    if (notify && (overwritten.length > 0 || defaultOverwritten)) {
+      try {
+        notify({
+          module: mod,
+          exports: overwritten,
+          defaultOverwritten
+        });
+      } catch {
+      }
+    }
+    const named = { ...existing.named, ...envExports.named };
+    const defaultAbs = envExports.default !== void 0 ? envExports.default : existing.default;
+    out[mod] = defaultAbs !== void 0 ? { named, default: defaultAbs } : { named };
+  }
+  return out;
+}
 function collectBPathReplacements(source) {
   const targets = [];
   const values = {};
@@ -1428,7 +1517,7 @@ function tryRunBPath(source, filePath, opts = {}) {
     try {
       const { modules: graphMods, issues } = evalAbsModuleGraph(source, filePath);
       const envMods = collectEnvModules(opts.envNames ?? []);
-      const modules = { ...envMods, ...graphMods };
+      const modules = mergeHarvestUnderEnv(graphMods, envMods);
       const { targets, values, asTargets, asValues } = collectBPathReplacements(source);
       const envGlobals = {
         ...collectEnvGlobals(opts.envNames ?? []),
@@ -2352,6 +2441,24 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords,
     () => analyzeFileUncachedInner(filePath, source, activeCases, externalCallRecords, loadModule)
   );
 }
+function findModuleImportLoc(source, module) {
+  const bare = module.startsWith("node:") ? module.slice("node:".length) : module;
+  const alts = [.../* @__PURE__ */ new Set([module, bare, `node:${bare}`])];
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const alt of alts) {
+      const re = new RegExp(
+        `["'\`]${alt.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["'\`]`
+      );
+      const m = re.exec(line);
+      if (m && m.index !== void 0) {
+        return { line: i, column: m.index, length: m[0].length };
+      }
+    }
+  }
+  return null;
+}
 function analyzeFileUncachedInner(filePath, source, activeCases, externalCallRecords, loadModule) {
   const ast = parse5(source);
   const functions = extractDirectives(ast);
@@ -2360,6 +2467,18 @@ function analyzeFileUncachedInner(filePath, source, activeCases, externalCallRec
   const nodeAbsMap = /* @__PURE__ */ new Map();
   const functionResults = [];
   const caseHints = [];
+  const envHarvestConflicts = [];
+  const prevHarvestConflictCollector = setEnvHarvestConflictCollector((c) => {
+    if (!envHarvestConflicts.some((x) => x.module === c.module)) {
+      envHarvestConflicts.push(c);
+    } else {
+      const prev = envHarvestConflicts.find((x) => x.module === c.module);
+      for (const e of c.exports) {
+        if (!prev.exports.includes(e)) prev.exports.push(e);
+      }
+      prev.defaultOverwritten ||= c.defaultOverwritten;
+    }
+  });
   const fileDirectives = extractFileDirectives(ast);
   const fileEnvNames = fileDirectives.filter((d) => d.kind === "env").flatMap((d) => d.envs);
   const projectConfig = findProjectConfig(dirname7(filePath));
@@ -2449,7 +2568,7 @@ function analyzeFileUncachedInner(filePath, source, activeCases, externalCallRec
         seedFns: seeds.seedFns,
         ...loadModule ? { loadModule } : {}
       });
-      absGraphModules = { ...collectEnvModules(envNames), ...g.modules };
+      absGraphModules = mergeHarvestUnderEnv(g.modules, collectEnvModules(envNames));
       pushBModuleIssues(g.issues);
     } catch {
     }
@@ -3055,6 +3174,24 @@ function analyzeFileUncachedInner(filePath, source, activeCases, externalCallRec
     filePath,
     analysisConfig(projectConfig?.config).callSiteBudget
   );
+  setEnvHarvestConflictCollector(prevHarvestConflictCollector);
+  for (const c of envHarvestConflicts) {
+    const parts = [];
+    if (c.exports.length > 0) parts.push(`export(s) ${c.exports.join(", ")}`);
+    if (c.defaultOverwritten) parts.push("default");
+    const detail = parts.length > 0 ? ` \u2014 ${parts.join("; ")}` : "";
+    const loc = findModuleImportLoc(source, c.module);
+    const range = loc ? {
+      start: { line: loc.line, column: loc.column },
+      end: { line: loc.line, column: loc.column + loc.length }
+    } : { start: { line: 0, column: 0 }, end: { line: 0, column: 0 } };
+    diagnostics.push({
+      range,
+      severity: "warning",
+      message: `handwritten @nudo:env wins over harvest on module "${c.module}"${detail}; harvest only fills missing slots (B8). code=nudo:env-harvest-conflict`,
+      code: "nudo:env-harvest-conflict"
+    });
+  }
   return {
     functions: functionResults,
     diagnostics,
@@ -3167,7 +3304,7 @@ function collectAbsCallRecords(source, seeds, filePath, precomputedModules, envN
       }
     }
     if (envNames.length > 0) {
-      modules = { ...collectEnvModules(envNames), ...modules ?? {} };
+      modules = mergeHarvestUnderEnv(modules ?? {}, collectEnvModules(envNames));
     }
     try {
       importLocals = buildAbsImportLocalMap(source, filePath);
@@ -4293,19 +4430,97 @@ function collectLoadDepContents(filePath, source, loadModule) {
 }
 
 // src/harvest-node.ts
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync8, statSync as statSync6 } from "fs";
+import { join as join6 } from "path";
 import { harvestDts as harvestDts2 } from "@nudojs/harvester";
-function harvestNodeTypes(fromDir, maxFiles = 12, maxMs = 2500) {
+var HARVEST_NODE_DEFAULT_MAX_FILES = 12;
+var HARVEST_NODE_DEFAULT_MAX_MS = 2500;
+var nodeHarvestCache = /* @__PURE__ */ new Map();
+function notFoundCacheKey(fromDir) {
+  return `not-found|@types/node|${fromDir ?? ""}`;
+}
+function nodeHarvestCacheKey(root, maxFiles, maxMs) {
+  let sig = "nostat";
+  try {
+    const st = statSync6(join6(root, "package.json"));
+    sig = `${st.size}:${Math.floor(st.mtimeMs)}`;
+  } catch {
+  }
+  return `${root}|${maxFiles}|${maxMs}|${sig}`;
+}
+function clearNodeHarvestCache() {
+  nodeHarvestCache.clear();
+}
+function getNodeHarvestCacheSize() {
+  return nodeHarvestCache.size;
+}
+function isHarvestNodeDisabled(env = process.env) {
+  return env.NUDO_HARVEST_NODE === "off";
+}
+function harvestNodeTypes(fromDir, maxFiles = HARVEST_NODE_DEFAULT_MAX_FILES, maxMs = HARVEST_NODE_DEFAULT_MAX_MS) {
+  if (isHarvestNodeDisabled()) {
+    return {
+      ok: false,
+      error: "harvest disabled via NUDO_HARVEST_NODE=off",
+      reason: "disabled"
+    };
+  }
   const root = resolvePackageRoot("@types/node", fromDir) ?? resolvePackageRoot("node", fromDir);
   if (!root || !existsSync8(root)) {
-    return { ok: false, error: "@types/node not found" };
+    const missKey = notFoundCacheKey(fromDir);
+    const miss = nodeHarvestCache.get(missKey);
+    if (miss && !miss.ok && miss.reason === "not-found") {
+      return { ...miss, cached: true };
+    }
+    const result = {
+      ok: false,
+      error: "@types/node not found",
+      reason: "not-found"
+    };
+    nodeHarvestCache.set(missKey, result);
+    return result;
+  }
+  const key = nodeHarvestCacheKey(root, maxFiles, maxMs);
+  const hit = nodeHarvestCache.get(key);
+  if (hit) {
+    return hit.ok ? { ...hit, cached: true } : { ...hit, cached: true };
   }
   const dts = collectDtsFiles(root, maxFiles);
   if (dts.length === 0) {
-    return { ok: false, error: `no .d.ts under ${root}` };
+    const result = {
+      ok: false,
+      error: `no .d.ts under ${root}`,
+      reason: "no-dts"
+    };
+    nodeHarvestCache.set(key, result);
+    return result;
+  }
+  try {
+    const env = harvestDts2(dts, { maxMs });
+    const stats = {
+      files: env.stats.files,
+      symbols: env.stats.symbols,
+      skipped: env.stats.skipped
+    };
+    const result = {
+      ok: true,
+      env,
+      root,
+      files: stats.files,
+      stats,
+      cached: false
+    };
+    nodeHarvestCache.set(key, result);
+    return result;
+  } catch (e) {
+    const result = {
+      ok: false,
+      error: `harvest failed: ${e.message}`,
+      reason: "failed"
+    };
+    nodeHarvestCache.set(key, result);
+    return result;
   }
-  const env = harvestDts2(dts, { maxMs });
-  return { ok: true, env, root, files: env.stats.files };
 }
 function summarizeNodeEnv(env) {
   return {
@@ -5916,7 +6131,7 @@ function joinSections(base, sectionTexts) {
 
 // src/interface-draft.ts
 import { existsSync as existsSync11, readFileSync as readFileSync9, writeFileSync as writeFileSync3, realpathSync as realpathSync2 } from "fs";
-import { basename as basename3, dirname as dirname13, isAbsolute as isAbsolute2, join as join6, relative as relative3 } from "path";
+import { basename as basename3, dirname as dirname13, isAbsolute as isAbsolute2, join as join7, relative as relative3 } from "path";
 import {
   effectiveInterface as effectiveInterface2,
   formatConstraint as formatConstraint3,
@@ -6444,7 +6659,7 @@ function safeRealpath(p) {
     return realpathSync2(p);
   } catch {
     try {
-      return join6(realpathSync2(dirname13(p)), basename3(p));
+      return join7(realpathSync2(dirname13(p)), basename3(p));
     } catch {
       return p;
     }
@@ -7454,6 +7669,8 @@ export {
   ANALYSIS_ABI,
   DEFAULT_ANALYSIS_MODE,
   DiskCache,
+  HARVEST_NODE_DEFAULT_MAX_FILES,
+  HARVEST_NODE_DEFAULT_MAX_MS,
   SEMANTIC_TOKEN_MODIFIERS,
   SEMANTIC_TOKEN_TYPES,
   absToTSType,
@@ -7478,6 +7695,7 @@ export {
   clearEnvPathDeps,
   clearFnAnalysisCache,
   clearHarvestCache,
+  clearNodeHarvestCache,
   clearPathEnvCaches,
   collectAbsBindingsFromGraph,
   collectAbsInlays,
@@ -7530,7 +7748,9 @@ export {
   getAnalysisSession,
   getCasesForFile,
   getCompletionsAtPosition,
+  getEnvHarvestConflictCollector,
   getHoverAtPosition,
+  getNodeHarvestCacheSize,
   getTypeAtPosition,
   getTypeAtPositionAsync,
   harvestNodeTypes,
@@ -7546,12 +7766,14 @@ export {
   isBPathCapable,
   isDraftableEntry,
   isEnvTemplatePath,
+  isHarvestNodeDisabled,
   isNudoTargetPath,
   isProjectConfigPath,
   isSidecarPath,
   isWatchRelevantPath,
   lookupHarvested,
   matchesEmitAllowlist,
+  mergeHarvestUnderEnv,
   mockDirectivesToAbsSeeds,
   noteEnvPathDeps,
   packageHarvestToAbsModules,
@@ -7561,6 +7783,7 @@ export {
   serializeCaseArg,
   serializeInferJson,
   setAnalysisSession,
+  setEnvHarvestConflictCollector,
   sha256Hex,
   shouldAnalyzeFile,
   sidecarDraftPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nudojs/service",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "engines": {
     "node": ">=20"
   },
@@ -45,10 +45,10 @@
   "dependencies": {
     "@babel/traverse": "^7.29.0",
     "@babel/types": "^7.29.0",
-    "@nudojs/core": "2.0.0",
-    "@nudojs/parser": "0.5.0",
-    "@nudojs/env": "0.3.0",
-    "@nudojs/harvester": "0.2.5"
+    "@nudojs/core": "2.0.1",
+    "@nudojs/parser": "0.5.1",
+    "@nudojs/env": "0.4.0",
+    "@nudojs/harvester": "0.2.6"
   },
   "scripts": {
     "build": "tsup src/index.ts src/evaluator/evaluator-api.ts --format esm --dts"