@nudojs/service 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,22 @@
-import { Node } from '@babel/types';
-import { TypeValue } from '@nudojs/core';
+import { Node, File } from '@babel/types';
+import { TypeValue, Abs, PolyFn, AbsModuleExports, AstEnv, Phi, BMemberDiag, BCallRecord, TranspiledCallResult } from '@nudojs/core';
+export { AbsInlay, BMemberDiag, collectAbsInlays } from '@nudojs/core';
+import { CallRecord } from '@nudojs/cli/evaluator';
+export { CallRecord } from '@nudojs/cli/evaluator';
+import { HarvestedEnv } from '@nudojs/harvester';
+import { FunctionWithDirectives } from '@nudojs/parser';
+
+/**
+ * Per-function FunctionAnalysis cache (body-edit: recompute only dirty fns).
+ * Cleared together with B-path / whole-file analysis caches.
+ */
+
+declare function clearFnAnalysisCache(): void;
+/**
+ * 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.
+ */
+declare function evictFnAnalysisCacheForFiles(files: string[]): number;
 
 type SourceLocation = {
     start: {
@@ -18,6 +35,14 @@ type Diagnostic = {
     severity: DiagnosticSeverity;
     message: string;
     tags?: DiagnosticTag[];
+    code?: string;
+    suggestions?: string[];
+    data?: unknown;
+    /** provenance of the receiver value (callsite argument that flowed into the error) */
+    origin?: {
+        line: number;
+        column: number;
+    };
 };
 type CaseResult = {
     name: string;
@@ -25,13 +50,45 @@ type CaseResult = {
     result: TypeValue;
     throws: TypeValue;
     throwLoc?: SourceLocation;
+    source?: "directive" | "callsite";
+    /** `@nudo:case "name" (…) => expected` — presence means the case is a test assertion */
+    expected?: TypeValue;
+    /** number of additional call sites folded into a symbolic case */
+    aggregatedFrom?: number;
+    /**
+     * 内涵摘要（代数 generalize）：无损 Abs + term/pred/conf。
+     * 仅在 entry@ / call@（Abs 路径）填充；外延 TypeValue 不变。
+     */
+    intension?: {
+        display?: string;
+        term?: string;
+        pred?: string;
+        conf?: string;
+        /** 无损 Abs 单行（formatAbs） */
+        abs?: string;
+        /** 无损 Abs 多行（formatAbsMultiline） */
+        absMultiline?: string;
+    };
+    /** 无损 Abs（denote/守卫用）；仅 Abs 路径 case 填充 */
+    abs?: Abs;
 };
 type FunctionAnalysis = {
     name: string;
     loc: SourceLocation;
+    paramNames: string[];
     cases: CaseResult[];
     combined?: TypeValue;
-    assertionErrors?: string[];
+    entryOnly?: boolean;
+    skipped?: boolean;
+    /**
+     * True for functions collected from CJS-style bindings/assignments
+     * (`exports.X = fn`, `module.exports = fn`, `const f = fn`): their name has
+     * no declaration-level stability, so .d.ts generation skips them while
+     * infer/JSON output still reports them.
+     */
+    noDeclaration?: boolean;
+    /** absolute path of the module this function is imported from (externalFunctions only) */
+    fromModule?: string;
 };
 type BindingInfo = {
     type: TypeValue;
@@ -46,15 +103,80 @@ type AnalysisResult = {
     functions: FunctionAnalysis[];
     diagnostics: Diagnostic[];
     bindings: Map<string, BindingInfo>;
+    /**
+     * Node identity is from the analysis-time parse. A later re-parse of the
+     * same source returns a *different* File (new Nodes) if the AST LRU evicted
+     * the original — lookups must use the File that produced this result, not a
+     * freshly parsed one. getTypeAtPosition rebuilds its own map and is unaffected.
+     */
     nodeTypeMap: Map<Node, TypeValue>;
     caseHints: CaseHint[];
+    /** functions imported from other modules, synthesized from cross-file call sites observed while analyzing this file */
+    externalFunctions?: FunctionAnalysis[];
 };
 type CompletionItem = {
     label: string;
     kind: "property" | "method" | "variable";
     detail?: string;
 };
-declare function analyzeFile(filePath: string, source: string, activeCases?: Map<string, number>): AnalysisResult;
+type SymbolInfo = {
+    name: string;
+    kind: "function" | "variable" | "class" | "parameter";
+    loc: SourceLocation;
+    uri?: string;
+};
+type ReferenceInfo = {
+    name: string;
+    loc: SourceLocation;
+    uri?: string;
+};
+type SymbolTable = {
+    definitions: Map<string, SymbolInfo>;
+    references: ReferenceInfo[];
+};
+/** mtime 边缓存：key 为文件路径，edges 为已抽取的相对 import 边（与 buildModuleGraph 返回语义一致）。 */
+type ModuleGraphCache = Map<string, {
+    mtimeMs: number;
+    size: number;
+    edges: string[];
+}>;
+/** Statically extract each file's relative import edges (extension resolution identical to CLI resolveModule: ''/'.js'/'.ts'/'.mjs'; bare npm specifiers skipped). */
+declare function buildModuleGraph(files: string[], cache?: ModuleGraphCache): {
+    imports: Map<string, Set<string>>;
+    dependents: Map<string, Set<string>>;
+};
+/** changed plus its transitive dependents (reverse-edge BFS); cycle-safe via visited. */
+declare function computeDirtySet(dependents: Map<string, Set<string>>, changedFile: string): string[];
+/** Topological order with dependencies before dependents (only imports edges internal to dirty; cycles tolerated — remaining files appended in arbitrary order). */
+declare function topoSortDirty(imports: Map<string, Set<string>>, dirty: string[]): string[];
+/**
+ * Async entry to analyzeFile: preloads path-based env files
+ * (`/// @nudo:env ./nudo-harvest-node.ts`) via dynamic import — impossible
+ * synchronously in ESM — then runs the sync analysis, which picks the
+ * preloaded factories up from the env-loader cache. The sync analyzeFile
+ * signature is unchanged for existing consumers (LSP, MCP, vite-plugin).
+ */
+declare function analyzeFileAsync(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[]): Promise<AnalysisResult>;
+/**
+ * 调用点发现（阶段一）：在"使用现场"文件（测试 / 上层应用）中求值
+ * 顶层代码，收集它对（外部模块导出的）函数的调用记录。每条记录带
+ * 真实的实参类型与结果类型——后续 analyzeFile 将其注入合成 case，
+ * 使被使用方从 entry-only（参数全 unknown）升级为真实调用形态。
+ *
+ * 只做求值与记录，不产出诊断；求值异常不抛出（使用现场文件可能
+ * 依赖未 mock 的全局，收集不到就收集不到，不能拖垮主分析）。
+ */
+declare function collectCallRecords(filePath: string, source: string): CallRecord[];
+/**
+ * 整文件分析。同 (path, source, cases, external) 命中 memo → O(1)。
+ * 不再每次 clearBPathCache：B 路径按本文件 source 键控。
+ *
+ * 宿主契约：入口 source 未变但依赖模块内容变了时，必须调用
+ * `evictBPathCacheForFiles` / `evictAnalysisFileCacheForFiles` /
+ * `evictFnAnalysisCacheForFiles`（LSP 已接好）。非 LSP 宿主
+ * （CLI watch / vite-plugin）在 dep 变更时应 `clearBPathCache()` 或上述逐出。
+ */
+declare function analyzeFile(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[]): AnalysisResult;
 type CaseInfo = {
     functionName: string;
     caseName: string;
@@ -68,10 +190,521 @@ declare function getCasesForFile(filePath: string, source: string): {
     }[];
     loc: SourceLocation;
 }[];
+/** Async entry to getTypeAtPosition with path-env preloading (see analyzeFileAsync). */
+declare function getTypeAtPositionAsync(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): Promise<TypeValue | null>;
 declare function getTypeAtPosition(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): TypeValue | null;
+type HoverInfo = {
+    /** 外延 TypeValue 展示（bridge 有损，仅兜底） */
+    typeText: string;
+    /** 内涵签名（代数 generalize） */
+    intension?: string;
+    /** 无损 Abs 单行展示（shape / term / pred / conf） */
+    abs?: string;
+    /** 无损 Abs 多行展示 */
+    absMultiline?: string;
+};
+/**
+ * LSP hover：优先无损 Abs（类型即计算本体），TypeValue 仅作外延对照。
+ * 节点表也是 Abs（collectAbsNodeTypes），不经 bridge。
+ */
+declare function getHoverAtPosition(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): HoverInfo | null;
 declare function getCompletionsAtPosition(filePath: string, source: string, line: number, column: number): CompletionItem[];
 
+/**
+ * `nudo infer --json` 稳定契约 v1（CI / Agent）。
+ *
+ * 字段只增不改语义：
+ * - ext_*：TypeValue 投影字符串（有损，兼容）
+ * - intension.abs*：无损 Abs 展示（主线）
+ */
+
+type InferJsonCase = {
+    name: string;
+    /** TypeValue 投影（有损外延） */
+    args: string[];
+    result: string;
+    throws: string | null;
+    source: string | null;
+    aggregatedFrom?: number;
+    /** 无损内涵（Abs）；无则省略 */
+    intension?: {
+        display?: string;
+        abs?: string;
+        absMultiline?: string;
+        term?: string;
+        pred?: string;
+        conf?: string;
+    };
+};
+type InferJsonFunction = {
+    name: string;
+    loc: SourceLocation;
+    entryOnly: boolean;
+    noDeclaration?: boolean;
+    cases: InferJsonCase[];
+    combined?: string;
+};
+type InferJson = {
+    version: 1;
+    file: string;
+    summary: {
+        functions: number;
+        externalFunctions: number;
+        cases: number;
+        diagnostics: number;
+    };
+    functions: InferJsonFunction[];
+    externalFunctions?: Array<{
+        name: string;
+        fromModule?: string;
+        cases: InferJsonCase[];
+    }>;
+    diagnostics: Array<{
+        range: SourceLocation;
+        severity: string;
+        message: string;
+        code?: string;
+        suggestions?: string[];
+        tags?: string[];
+        origin?: {
+            line: number;
+            column: number;
+        };
+    }>;
+};
+declare function serializeInferJson(result: AnalysisResult, file: string): InferJson;
+
+/**
+ * nudo 推断目标文件判定（纯扩展名规则，路径无需存在）。
+ *
+ * 规则：.js / .mjs / .ts 可作为推断目标；其余扩展（.cjs/.tsx/.jsx/.mts/.d.ts…）
+ * 一律 false。两类显式排除：
+ *  - .d.ts —— 类型声明文件（harvester 的输入），不是可求值的实现源码；
+ *  - .tsx / .jsx —— JSX 构造的求值超出 nudo 推断器范围。
+ *
+ * 消费方：CLI 的 collectNudoFiles/watch 过滤/doctor 目录展开（.ts 放开后统一
+ * 走本函数，避免各处手写 endsWith 漂移），以及 LSP 的 isNudoFile（接线由
+ * LSP 侧负责）。
+ */
+declare function isNudoTargetPath(path: string): boolean;
+
+/**
+ * 相对/绝对 specifier → 模块源码。
+ * CLI / LSP / vite / check 共用同一扩展名表，避免门禁结果分叉。
+ */
+type LoadModule = (spec: string, fromFile: string) => string | undefined;
+/** 默认 loadModule：支持 .js/.mjs/.ts 与 index 入口 */
+declare function defaultLoadModule(spec: string, fromFile: string): string | undefined;
+
+/**
+ * Host 侧多文件解析（非代数层）。
+ *
+ * 分层：
+ *   algebra = 纯抽象解释：吃 AST / source string，不碰 fs/path
+ *   host   = 读文件、解析相对 import/require、把 source 喂给代数
+ *   Node/打包器 = 真正的模块加载与执行
+ *
+ * 引擎不做 bundler；这里只为「跨文件类型事实」做最薄的静态扫描。
+ */
+
+type ModuleExports = {
+    path: string;
+    named: Map<string, string>;
+    defaultExport?: string;
+    source: string;
+    poly: Map<string, PolyFn>;
+};
+/** 从 AST 收集静态相对依赖（ESM import + CJS require） */
+declare function collectDependencySpecs(ast: File): string[];
+/** 分析单文件导出 + 内涵签名（source 由 host 提供） */
+declare function analyzeExportsFromSource(filePath: string, source: string): ModuleExports;
+/**
+ * 从入口文件沿静态相对 import/require 收集（仅类型事实，不是运行时加载器）。
+ * bare specifier（npm 包）跳过——交给 harvest / env。
+ */
+declare function collectStaticImports(entryFile: string, maxDepth?: number): Map<string, ModuleExports>;
+
+/**
+ * Host：从 npm 包 / @types 收集 .d.ts → harvestDts。
+ * 代数不碰 fs；这里只做「找到 dts 路径」这一层宿主职责。
+ */
+
+/** 在 node_modules 中解析包根（含 @types/*） */
+declare function resolvePackageRoot(pkg: string, fromDir?: string): string | undefined;
+type PackageHarvest = {
+    pkg: string;
+    root: string;
+    dtsFiles: string[];
+    env: HarvestedEnv;
+};
+/**
+ * 从入口 .d.ts 沿 reference path / 相对 import 做 BFS 收集。
+ * 适合 @types 包（三斜线引用图）；比整树 walk 更贴声明入口。
+ */
+declare function collectDtsFromEntry(entry: string, maxFiles?: number): string[];
+/** harvest 一个 npm 包（或 @types 包） */
+declare function harvestPackage(pkg: string, fromDir?: string, maxFiles?: number): PackageHarvest | {
+    error: string;
+};
+/** harvest 结果 → 人类可读导出表 */
+declare function formatHarvestSummary(h: PackageHarvest): string;
+/** 取某个导出的 TypeValue 字符串 */
+declare function lookupHarvested(h: PackageHarvest, moduleName: string, exportName: string): string | undefined;
+
+/**
+ * harvest 自动化：源码裸 import → @types/package → env modules。
+ * 手动 `nudo harvest` 仍保留；这里是分析路径上的按需注入。
+ */
+
+/** 裸说明符 → 包名（含 scope）；相对/绝对/node: 内建返回 undefined */
+declare function barePackageName(spec: string): string | undefined;
+declare function collectBarePackages(source: string): string[];
+declare function harvestPackageCached(pkg: string, fromDir: string): PackageHarvest | null;
+declare function clearHarvestCache(): void;
+/**
+ * 自动 harvest 源码中全部裸包（有 @types 或包内 dts 时）。
+ * 返回可注入 setEnvModules 的 modules 表；无包可 harvest 时为空对象。
+ */
+declare function autoHarvestModules(source: string, fromDir: string): Record<string, Record<string, TypeValue>>;
+
+/**
+ * Host：import 图（相对 + 裸包 harvest）→ Abs 导出表 → 注入入口。
+ * 读 fs / 解析路径 / harvest 在这里；core 只收 modules 表。
+ */
+
+type AbsLoadModule = (spec: string, fromFile: string) => string | undefined;
+/** 相对说明符 → 源码 */
+declare function defaultAbsLoadModule(spec: string, fromFile: string): string | undefined;
+/** 模块加载守卫：与 TypeValue loadModuleEnv 口径对齐，供 analyzer 映射诊断 */
+type AbsModuleLoadIssue = {
+    kind: "cycle" | "depth" | "missing";
+    /** 诊断定位用标签（文件 basename 或 require/import 说明符） */
+    label: string;
+    reason: string;
+};
+type AbsModuleGraphResult = {
+    /** 入口 import 说明符 → 依赖导出表 */
+    modules: Record<string, AbsModuleExports>;
+    /** 绝对路径 → 导出表（含依赖；循环时占位为空） */
+    byPath: Map<string, AbsModuleExports>;
+    /** cycle / depth / missing（B 路径权威，避免 TypeValue 叠报） */
+    issues: AbsModuleLoadIssue[];
+};
+type AbsGraphOptions = {
+    loadModule?: AbsLoadModule;
+    seedVars?: Record<string, Abs>;
+    seedFns?: Record<string, {
+        params: string[];
+        body: Node;
+        async?: boolean;
+    }>;
+    maxDepth?: number;
+};
+/** 会话级依赖模块缓存条目：stat 指纹 + 导出 + 子树装载 issue。 */
+type AbsModuleCacheEntry = {
+    mtimeMs: number;
+    size: number;
+    exports: AbsModuleExports;
+    /** 该模块子树首次求值时记录的 cycle/depth/missing；命中时重放。 */
+    issues: AbsModuleLoadIssue[];
+};
+declare function clearAbsModuleCache(): void;
+declare function evictAbsModuleCacheFiles(paths: string[]): void;
+/**
+ * 递归求值相对依赖 + 裸包 harvest，产出入口可用的 modules 表。
+ * 循环依赖：先放空表再回填（与 TypeValue 路径 partial 口径一致），
+ * 并记录 cycle/depth/missing 供诊断。
+ */
+declare function evalAbsModuleGraph(entrySource: string, entryFile: string, opts?: AbsGraphOptions): AbsModuleGraphResult;
+/** 便捷：入口求值 + 依赖 Abs 注入 */
+declare function evalProgramAbsWithModules(source: string, entryFile: string, opts?: AbsGraphOptions & {
+    file?: unknown;
+}): {
+    env: AstEnv;
+    last: Abs;
+    phi: Phi;
+};
+/**
+ * 收集顶层绑定名 → Abs（含相对 import / 裸包 harvest 注入）。
+ * 供 bindings / hover 从 Abs 投影，不必走 TypeValue evaluator。
+ */
+declare function collectAbsBindingsFromGraph(source: string, filePath: string, opts?: AbsGraphOptions): Map<string, Abs>;
+
+/**
+ * Harvest TypeValue 导出 → AbsModuleExports（供 Abs 模块图注入）。
+ * fnSig → absFunction + apply 直接返回声明返回类型（conf=mock）。
+ */
+
+/** 单个 TypeValue 导出 → Abs（可调用） */
+declare function harvestedValueToAbs(tv: TypeValue): Abs;
+/**
+ * 把 harvest 的 modules/globals 合成 AbsModuleExports。
+ * 键同时登记：原始模块路径、包名、basename（path / @types/path）。
+ */
+declare function harvestToAbsModules(pkg: string, fromDir: string): Record<string, AbsModuleExports>;
+declare function packageHarvestToAbsModules(pkg: string, h: PackageHarvest): Record<string, AbsModuleExports>;
+/** 裸说明符 → Abs 导出表（走 harvest 缓存） */
+declare function bareSpecToAbsModules(spec: string, fromFile: string): AbsModuleExports | undefined;
+
+/** @nudo:env → Abs 全局表（保留 fnSig impl） */
+declare function collectEnvGlobals(envNames: string[]): Record<string, Abs>;
+/** @nudo:env modules（path / node:path / fs…）→ AbsModuleExports */
+declare function collectEnvModules(envNames: string[]): Record<string, AbsModuleExports>;
+/** 收集 @nudo:replace + @nudo:as → transpile 注入表 */
+declare 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>;
+};
+/** 可走 transpile+exec：env 经 loadEnvs（内置 + 已 preload 的路径型） */
+declare function isBPathCapable(source: string, envNames?: string[]): boolean;
+type BPathRunResult = {
+    exports: Record<string, unknown>;
+    modules: Record<string, AbsModuleExports>;
+    /** 顶层执行期 method-missing */
+    memberDiags?: BMemberDiag[];
+    /** 模块图 cycle/depth/missing（B 权威） */
+    moduleIssues?: AbsModuleLoadIssue[];
+    /** Abs 求值递归截断的函数标签 */
+    truncatedFns?: string[];
+    /** 顶层 $callNamed 调用点（call@ 合成；不经 TypeValue collector） */
+    calls?: BCallRecord[];
+};
+declare function clearBPathCache(): void;
+/** 依赖文件变更后：逐出以这些文件为入口的 B-path 缓存 */
+declare function evictBPathCacheForFiles(files: string[]): number;
+/** 模块图 + runTranspiled（默认 analyze 模式） */
+declare function tryRunBPath(source: string, filePath: string, opts?: {
+    maxLoopIters?: number;
+    mode?: "exec" | "analyze";
+    envNames?: string[];
+    /** @nudo:mock → Abs，注入为全局绑定（防止顶层调用真 fetch 等） */
+    mocks?: Record<string, Abs>;
+}): BPathRunResult | undefined;
+/** B 路径求值具名导出（结果 + throws）；opts.collectCalls 时附带调用点记录 */
+declare 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?: AbsModuleLoadIssue[];
+    truncatedFns?: string[];
+}) | undefined;
+/** B 路径求值具名导出（仅成功结果） */
+declare function tryBPathCall(source: string, filePath: string, fnName: string, args: Abs[], opts?: {
+    envNames?: string[];
+    mocks?: Record<string, Abs>;
+}): Abs | undefined;
+
+declare function clearAnalysisFileCache(): void;
+declare function getAnalysisFileCacheSize(): number;
+/** 依赖变更后：按入口文件逐出 */
+declare function evictAnalysisFileCacheForFiles(files: string[]): number;
+
+/**
+ * 依赖内容变更后：按入口文件定向逐出 service 层缓存。
+ * 调用方应传「以这些文件为入口」的路径（脏集里的 dependents），
+ * 而不是变更的 dep 文件本身——dep 自己 source 变了会自然 miss。
+ */
+declare function evictAnalysisCachesForFiles(files: string[]): void;
+/**
+ * 清空全部会话级分析缓存（service + core）。
+ * 适用于：CLI watch 增量批前、vite buildStart / watchChange、测试隔离。
+ * 比定向逐出重，但保证无陈旧命中；单次 analyze 内部的 per-fn / generalize
+ * memo 不受影响（它们在同一轮里先写后读）。
+ */
+declare function clearAnalysisSessionCaches(): void;
+/** 比 clearAnalysisSessionCaches 更彻底：再丢 AST LRU（测试 / 进程复用场景） */
+declare function resetAllAnalysisCaches(): void;
+
+/**
+ * env TypeValue → Abs：保留 fnSig impl，使 Promise.resolve / URL 等
+ * 在 B 路径也能产出精确字面量。
+ */
+
+declare function envValueToAbs(tv: TypeValue): Abs;
+
+/**
+ * B 路径静态诊断（AST，不执行）：
+ * - unreachable：同块 return/throw 之后的语句
+ * - builtin-unknown：未声明的全局调用（非 import / 局部 / $runtime）
+ */
+type BPathLoc = {
+    start: {
+        line: number;
+        column: number;
+    };
+    end: {
+        line: number;
+        column: number;
+    };
+};
+type BPathUnreachable = {
+    range: BPathLoc;
+};
+type BPathBuiltinUnknown = {
+    name: string;
+    range: BPathLoc;
+};
+type BPathDiagnostics = {
+    unreachable: BPathUnreachable[];
+    builtinUnknown: BPathBuiltinUnknown[];
+};
+/**
+ * 静态收集 B 路径诊断。
+ * extraKnown：@nudo:mock / @nudo:env 已覆盖的全局名（B 注入后不再是裸原生
+ * 调用，不得误报 builtin-unknown——收集器只吃 AST，看不到指令）。
+ */
+declare function collectBPathDiagnostics(source: string, extraKnown?: Iterable<string>): BPathDiagnostics;
+
+/**
+ * 预置 Node API env：从 @types/node 的 .d.ts harvest。
+ * 与 packages/env 的手写 env 并行；此路径自动、可刷新。
+ */
+
+type NodeEnvResult = {
+    ok: true;
+    env: HarvestedEnv;
+    root: string;
+    files: number;
+} | {
+    ok: false;
+    error: string;
+};
+/** harvest @types/node（限制文件数 + 时间预算，避免拖垮启动） */
+declare function harvestNodeTypes(fromDir?: string, maxFiles?: number, maxMs?: number): NodeEnvResult;
+/** 把 harvest 结果压成「模块名 → 导出名列表」摘要，便于日志/测试 */
+declare function summarizeNodeEnv(env: HarvestedEnv): {
+    modules: string[];
+    globals: string[];
+    symbolCount: number;
+};
+
+/**
+ * Semantic tokens 图例（tokenTypes 下标即 LSP 编码里的 tokenType 值）。
+ * 与 LSP server capabilities 里声明的 legend 必须逐字对齐——server.ts 直接
+ * 导入本常量注册，保证「提取端索引」与「客户端图例」单一来源。
+ * 顺序沿用 lsp 包原 legend（function/variable/parameter/property 在前），
+ * 末尾追加 method（对象字面量方法键），只追加不重排，客户端索引稳定。
+ */
+declare const SEMANTIC_TOKEN_TYPES: readonly ["function", "variable", "parameter", "property", "type", "keyword", "string", "number", "comment", "decorator", "method"];
+declare const SEMANTIC_TOKEN_MODIFIERS: readonly ["declaration", "readonly", "deprecated", "unreachable"];
+type SemanticToken = {
+    line: number;
+    char: number;
+    length: number;
+    typeIndex: number;
+    modifierBitmask: number;
+};
+/** LSP 标准相对五元组编码：deltaLine/deltaStartChar/length/tokenType/tokenModifiers。 */
+declare function encodeSemanticTokens(tokens: SemanticToken[]): number[];
+/**
+ * 从源码提取 semantic tokens 并按 LSP 相对编码返回扁平 number[]。
+ *
+ * 上色范围（声明位优先，未解析的 token 一律不上色）：
+ * - 顶层 const/let/var 声明的绑定名：推断为函数绑定 → function，否则 variable
+ *   （函数体内部的声明不做 env 反查——外层同名绑定会串味，统一 variable）；
+ * - 函数声明/函数表达式的名字 → function；所有函数的参数 → parameter；
+ * - 对象字面量的键：值为函数 → method，否则 property。
+ *
+ * 推断复用 evaluateProgram 的绑定分析（与补全/诊断同一求值链），不另建
+ * 符号体系；解析失败返回 []，求值中断则按已绑定的部分结果继续上色。
+ */
+declare function buildSemanticTokens(filePath: string, source: string): number[];
+
 declare function typeValueToTSType(tv: TypeValue): string;
+/**
+ * 为单个函数生成 .d.ts 声明行（JSDoc + 单一 widen 主签名）。
+ * service 的 generateDts 与 CLI `--dts`（infer/watch）共用本函数，
+ * 两条路径输出保持一致。
+ */
+declare function generateFunctionDtsLines(fn: FunctionAnalysis): string[];
 declare function generateDts(result: AnalysisResult): string;
 
-export { type AnalysisResult, type BindingInfo, type CaseHint, type CaseInfo, type CaseResult, type CompletionItem, type Diagnostic, type DiagnosticSeverity, type DiagnosticTag, type FunctionAnalysis, type SourceLocation, analyzeFile, generateDts, getCasesForFile, getCompletionsAtPosition, getTypeAtPosition, typeValueToTSType };
+declare function typeValueToZodSchema(tv: TypeValue): string;
+
+declare function generateGuardFunction(name: string, tv: TypeValue): string;
+/** Abs 指称守卫（设计 §2.7）：比 TypeValue 投影多保留 pred */
+declare function generateGuardFunctionFromAbs(name: string, abs: Abs): string;
+
+/** 单个 TypeValue → parseTypeValueExpr 可解析回去的表达式文本；不可表达返回 null */
+declare function serializeCaseArg(tv: TypeValue): string | null;
+/**
+ * 组装单行 ` * @nudo:case "name" (a, b)` 指令文本（无尾换行）。
+ * 任一实参不可序列化、或名字含双引号/换行（名字正则 `"([^"]+)"` 承载不了）→ 整体 null。
+ */
+declare function buildCaseDirective(name: string, args: TypeValue[]): string | null;
+/**
+ * 从源码剥离所有本模块生成的 @nudo:case 指令（名字以 call@ 开头，整行删除）。
+ * 若所属 JSDoc 块因此只剩空 ` *` 行（无其他 @nudo:* 指令、无文字内容），
+ * 连块首 `/**` 行与块尾行整块删除。绝不碰非 case 指令与普通注释。
+ * 注意：手写但以 call@ 命名的 case 同样会被删——call@ 前缀保留为生成物标记。
+ * removed 返回被删指令名列表（按出现顺序）。
+ */
+declare function stripGeneratedCaseDirectives(source: string): {
+    source: string;
+    removed: string[];
+};
+type EmitSkipReason = "hand-written" | "already-generated" | "entry-only" | "no-serializable-cases" | "no-declaration" | "skipped";
+type EmitResult = {
+    source: string;
+    changed: boolean;
+    written: Array<{
+        fn: string;
+        cases: string[];
+    }>;
+    skipped: Array<{
+        fn: string;
+        reason: EmitSkipReason;
+        detail?: string;
+    }>;
+};
+/**
+ * 把 analysis 中的合成 case（source === "callsite"）固化为源码指令：
+ *
+ * 1. 源码已有任何非 call@ 命名的 case → skip "hand-written"；
+ *    已有 call@ case → skip "already-generated"。
+ * 2. fn.skipped / fn.noDeclaration / fn.entryOnly → 对应 skip。
+ * 3. 逐 case 序列化；个别不可序列化的丢弃并在 skipped 记
+ *    no-serializable-cases（函数整体仍写可序列化子集，全不可序列化才整函数跳过）。
+ * 4. 写入位置：函数声明行正上方——已有 JSDoc 块则插到 `/**` 行后，
+ *    无块则新建三行块。缩进取声明行的 loc.start.column（babel 0 基列）。
+ *    多函数编辑按行号从下往上应用，避免行号漂移。
+ */
+declare function insertGeneratedCaseDirectives(source: string, analysis: AnalysisResult): EmitResult;
+/** 行级 unified diff：`--- a/path` 头 + `@@` hunk + 上下文 3 行；相同返回 "" */
+declare function unifiedDiff(a: string, b: string, path: string): string;
+
+/**
+ * @nudo:mock / sinon 指令 → Abs seed（供 evalProgramAbs）。
+ * host 层：依赖 parser 指令形态；core 只吃 seedVars/seedFns。
+ */
+
+type AbsMockSeeds = {
+    seedVars: Record<string, Abs>;
+    seedFns: Record<string, {
+        params: string[];
+        body: Node;
+        async?: boolean;
+        fingerprint?: string;
+    }>;
+};
+/** 从函数上的 @nudo:mock 指令收集 Abs seed */
+declare function mockDirectivesToAbsSeeds(functions: Array<{
+    directives: FunctionWithDirectives["directives"];
+}>): AbsMockSeeds;
+
+export { type AbsGraphOptions, type AbsMockSeeds, type AbsModuleCacheEntry, type AbsModuleGraphResult, type AbsModuleLoadIssue, type AnalysisResult, type BPathBuiltinUnknown, type BPathDiagnostics, type BPathRunResult, type BPathUnreachable, type BindingInfo, type CaseHint, type CaseInfo, type CaseResult, type CompletionItem, type Diagnostic, type DiagnosticSeverity, type DiagnosticTag, type EmitResult, type EmitSkipReason, type FunctionAnalysis, type HoverInfo, type InferJson, type InferJsonCase, type InferJsonFunction, type LoadModule, type ModuleExports, type ModuleGraphCache, type NodeEnvResult, type PackageHarvest, type ReferenceInfo, SEMANTIC_TOKEN_MODIFIERS, SEMANTIC_TOKEN_TYPES, type SemanticToken, type SourceLocation, type SymbolInfo, type SymbolTable, analyzeExportsFromSource, analyzeFile, analyzeFileAsync, autoHarvestModules, barePackageName, bareSpecToAbsModules, buildCaseDirective, buildModuleGraph, buildSemanticTokens, clearAbsModuleCache, clearAnalysisFileCache, clearAnalysisSessionCaches, clearBPathCache, clearFnAnalysisCache, clearHarvestCache, collectAbsBindingsFromGraph, collectBPathDiagnostics, collectBPathReplacements, collectBarePackages, collectCallRecords, collectDependencySpecs, collectDtsFromEntry, collectEnvGlobals, collectEnvModules, collectStaticImports, computeDirtySet, defaultAbsLoadModule, defaultLoadModule, encodeSemanticTokens, envValueToAbs, evalAbsModuleGraph, evalProgramAbsWithModules, evictAbsModuleCacheFiles, evictAnalysisCachesForFiles, evictAnalysisFileCacheForFiles, evictBPathCacheForFiles, evictFnAnalysisCacheForFiles, formatHarvestSummary, generateDts, generateFunctionDtsLines, generateGuardFunction, generateGuardFunctionFromAbs, getAnalysisFileCacheSize, getCasesForFile, getCompletionsAtPosition, getHoverAtPosition, getTypeAtPosition, getTypeAtPositionAsync, harvestNodeTypes, harvestPackage, harvestPackageCached, harvestToAbsModules, harvestedValueToAbs, insertGeneratedCaseDirectives, isBPathCapable, isNudoTargetPath, lookupHarvested, mockDirectivesToAbsSeeds, packageHarvestToAbsModules, resetAllAnalysisCaches, resolvePackageRoot, serializeCaseArg, serializeInferJson, stripGeneratedCaseDirectives, summarizeNodeEnv, topoSortDirty, tryBPathCall, tryBPathCallFull, tryRunBPath, typeValueToTSType, typeValueToZodSchema, unifiedDiff };