跳到主要内容

@nudojs/harvester

Nudo 声明收割器(harvester)的 API 参考。@nudojs/harvester 把 TypeScript .d.ts 声明转换为 Nudo env 定义 —— 即用 @nudojs/core 的 Abs 构造器重建这些类型的 TypeScript 源码。

它是 env 包 / 分析用库,不是产品 CLI 动词。用于编写 @nudojs/env 类型面,或程序化生成路径式 /// @nudo:env 模块。日常分析由 @nudojs/service 自动补洞 @types,无需直接调用本包。

公开 API​

该包从 src/index.ts 导出两个函数和一个类型。

harvestDts​

harvestDts(files: string[], opts?: { maxFileBytes?: number; maxMs?: number }): HarvestedEnv

从磁盘读取给定的 .d.ts 文件路径,并用 TypeScript 编译器分两个阶段解析。opts.maxFileBytes(默认 1_500_000)跳过超大文件;opts.maxMs 设置截止时间,超限后剩余文件计入 skipped。

  1. 收集 —— 把每个模块/全局声明(declare module "..."、命名空间、interface、class、类型别名、函数重载、export = / export * from 再导出)收集进共享符号表。
  2. 物化 —— 把收集到的符号转换为 Abs 值(见 core)。物化只在整张符号表填充完毕后运行,因此跨文件引用与文件顺序无关,均可解析。

结果与 core 的 EnvDefinition 形状一致({ globals, modules }),因此产出的 env 可以直接接入 /// @nudo:env 加载路径。

type HarvestedEnv = {
globals: Record<string, Abs>;
modules: Record<string, Record<string, Abs>>;
stats: { files: number; symbols: number; skipped: number };
};
  • globals —— 全局作用域中声明的符号(如 @types/node 的 Buffer、process)
  • modules —— 按模块键控的记录,同时以裸名和带前缀名注册(同一条记录同时有 "path" 和 "node:path" 两个键)
  • stats —— 工具用计数:解析的文件数、产出的符号数、跳过的声明数(不支持的语法)

示例:

import { harvestDts } from "@nudojs/harvester";

const env = harvestDts(["node_modules/@types/node/fs.d.ts"]);
env.stats; // { files: 1, symbols: …, skipped: … }

emitEnvModule​

emitEnvModule(env: HarvestedEnv, pkgName: string): string

把 HarvestedEnv 渲染为可导入的 TypeScript 源码,导出单个 defineEnv() 函数:

import { emitEnvModule } from "@nudojs/harvester";

const code = emitEnvModule(env, "@types/node");

产出文件遵循如下形状(被多个键共享的模块记录 —— 例如 "path" 与 "node:path" 指向同一记录 —— 只产出一次 const,各键引用它):

// Auto-generated by @nudojs/harvester — DO NOT EDIT
// Source package: @types/node
import { num, str, bool, never as absNever, unknown as absUnknown, numLit, strLit, boolLit, objOf, relationFn, abs as makeAbs } from "@nudojs/core";

export function defineEnv() {
const mod0: Record<string, unknown> = {
// …各模块符号…
};

return {
globals: {
// …全局符号…
},
modules: {
path: mod0,
"node:path": mod0,
},
};
}

单个符号使用 Abs 构造器 —— 例如从 @types/node 收割出的这些条目:

platform: relationFn([], makeAbs({ k: "sum", members: [strLit("aix"), strLit("android"), strLit("darwin"), /* … */ strLit("netbsd")] }, undefined, undefined, "exact"), { conf: "exact" }),
join: relationFn([makeAbs({ k: "arr", element: str() }, undefined, undefined, "exact")], str(), { conf: "exact" }),

使用收割出的 env​

在 JavaScript 源文件顶部用基于路径的 /// @nudo:env 指令引入生成的文件(与指令文档中的具名环境 es / web / node 不同):

/// @nudo:env nudo-harvest-node.ts
import { join } from "node:path";

export function buildKey(dir, name) {
const p = join(dir, name);
return p + ".md";
}

const key = buildKey("docs", "readme");

对该文件运行 nudo test,可以看到收割出的 join 签名贯穿调用点:

=== buildKey ===

call@L9 ("docs", "readme") => `${string}.md`

基于路径的 env 文件通过动态 import 加载,因此异步消费方(nudo check/nudo test、analyzeFileAsync、LSP 验证路径)会预加载它们;同步的 analyzeFile 在文件声明了路径 env 时会降级。异步工具链应优先使用 analyzeFileAsync。

自动 harvest 路径(三态)​

分析遇到裸 import(import x from "commander")时,Nudo 不会凭空发明类型。自动路径遵循三态:

Import 目标行为产品路径
JS 源码包含可用 .js/.mjs(如 commander、ms、debug)通过 Abs 求值器 / checkSource 执行源码nudo check / nudo test / LSP —— zero-FP 门禁 无需手写 mock
类型包——已装 @types/* 或包自带 .d.tsharvest 声明(harvestPackage / harvestNodeTypes / bareSpecToAbsModules → env modules)分析时模块图自动注入;内建 API 仍以手写 @nudojs/env 为主
两者皆无自动路径返回空 modules使用 @nudo:mock、路径 /// @nudo:env 或侧车提示——见下方 mock 边界

库 helper vs 生产注入。 @nudojs/harvester 导出的 autoHarvestModules 是工具/测试用的程序化 harvest helper。生产分析注入走 evalAbsModuleGraph → bareSpecToAbsModules(harvest-to-abs.ts),再经 mergeHarvestUnderEnv 让手写 @nudojs/env 在重叠处 wins。不存在第二条分析注入路径。

barePackageName("lodash/fp") → lodash;相对 / 绝对 / node: 说明符永远不会成为 harvest 目标(内建走手写 env)。

性能预算(@types/node)​

@nudojs/harvester 的 harvestNodeTypes 有预算保护,避免巨大 .d.ts 图拖垮 IDE 启动:

预算默认说明
maxFiles12入口优先收集 node_modules/@types/node 下声明
maxMs2500传给 harvestDts;超预算文件计入 stats.skipped
关闭NUDO_HARVEST_NODE=off返回 { ok: false, reason: "disabled" } —— 显式而非静默

结果在进程内与磁盘缓存(HarvestJson,~/.cache/nudo/deps / NUDO_DEPS_CACHE_DIR)——成功与终态结果,键:包根 + dts 内容哈希 + 预算。disabled(NUDO_HARVEST_NODE=off)不进缓存。@types/node 在 watch/测试中变更后应调用 clearNodeHarvestCache()。harvest 未命中/失败时降级为手写 @nudojs/env node 面(degraded: true)。手写 @nudojs/env 在重叠模块键 / 导出名上 wins——分析路径经 @nudojs/service 的 mergeHarvestUnderEnv 注入(harvest 只补缺失槽)。不要把 harvest 产物当作类型系统真相源。

覆盖基线(resolved / unknown / mock-required)由 pnpm run coverage:env 生成到 docs/reports/env-coverage-baseline.{json,md}。解析率不是完备性承诺。

Mock 边界(诚实清单)​

仍建议手写 mock 的类别(与 docs/design/limitations.md §2 调用点天花板对齐):

  • Native bindings(child_process.spawn、原生 addon)—— env 可有签名,无副作用模拟
  • 动态 require / 计算模块图(字面量 / 常量折叠子集已解析;其余诚实 unknown)
  • 流机器回调(Node Transform 运行时驱动的内部回调)
  • browser/node 双入口变体——调用点记录不跨文件注入
  • 无调用现场的函数—— entry@ 兜底是诚实结果,参数是无约束的 any;该面上的 entry may-throw 仍是 L2(nudo:entry-may-throw),不是免检通行证

另见语言语义 — mock 边界。

Export inventory​

由 node scripts/gen-api-docs.mjs 从包导出面(PUBLIC_API.md / src/index.ts)生成 —— 请勿手改本块(或在 pnpm run docs:gen 里一并再生)。每行名字带稳定锚点 #slug(符号名小写)。

名称种类说明签名
absToHarvestSigfnAbs → 签名投影(丢 pred/conf;fn 只留参数名+类型面;保留泛型 α 与 lit term)absToHarvestSig(a: Abs): HarvestSig
autoHarvestModulesfn自动 harvest 源码中全部裸包(有 @types 或包内 dts 时)。autoHarvestModules( source: string, fromDir: string, ): Record
barePackageNamefn裸说明符 → 包名(含 scope);相对/绝对/node: 与裸 Node 内建返回 undefinedbarePackageName(spec: string): string | undefined
bareSpecToAbsModulesfn裸说明符 → Abs 导出表(走 harvest 缓存)bareSpecToAbsModules( spec: string, fromFile: string, ): AbsModuleExports | undefined
clearHarvestCachefn—clearHarvestCache(): void
clearNodeHarvestCachefnClear the in-process @types/node harvest cache.clearNodeHarvestCache(): void
collectBarePackagesfn—collectBarePackages(source: string): string[]
collectDtsFromEntryfn从入口 .d.ts 沿 reference path / 相对 import 做 BFS 收集。collectDtsFromEntry(entry: string, maxFiles = 200): string[]
depsCacheRootfn依赖包层缓存根(跨项目);off/0 关闭depsCacheRoot(): string | undefined
dtsClosureHashfndts 闭包内容哈希(覆盖每个实际读到的文件,不只入口);读故障语义见 dtsClosureHashDetaileddtsClosureHash(files: string[]): string
DtsContractDrafttype—DtsContractDraft = { label: string; files: string[]; exports: DtsExportDraft[]; draftSource: string; stats: { files: number; exports: num...
DtsExportDrafttype—DtsExportDraft = { name: string; dsl?: string; note?: string; kind: "function" | "value" | "class" | "other"; partial?: boolean; }
dtsPathToContractDraftfn目录/文件入口:内部解析 .d.ts 列表。dtsPathToContractDraft( path: string, label?: string, ): DtsContractDraft
dtsToContractDraftfn从 .d.ts 路径列表生成契约草稿(不写盘)。dtsToContractDraft( dtsFiles: string[], label?: string, opts?: { acceptTarget?: string }, ): DtsContractDraft
emitEnvModulefn—emitEnvModule(env: HarvestedEnv, pkgName: string): string
formatDtsContractDraftfn组装 @nudo:draft 模块(与 formatDraftModule 同纪律:不 ambient 绑定)。formatDtsContractDraft( label: string, files: string[], exports: DtsExportDraft[], acceptTarget?: string, ): string
formatHarvestSummaryfnharvest 结果 → 人类可读导出表formatHarvestSummary(h: PackageHarvest): string
getHarvestCacheSizefn测试/诊断:当前条目数(≤ HARVEST_CACHE_MAX)getHarvestCacheSize(): number
getNodeHarvestCacheSizefnNumber of cached harvest results (diagnostics / tests).getNodeHarvestCacheSize(): number
handwrittenNodeEnvfn手写 @nudojs/env node 面(B2 降级链):harvest 未命中/失败时仍给出 可分析的 Node API 声明;与 harvest 重叠处由 mergeHarvestUnderEnv 让手写 wins。handwrittenNodeEnv(): HarvestedEnv | null
HARVEST_NODE_DEFAULT_MAX_FILESconstIDE-startup budgets for @types/node harvest.const HARVEST_NODE_DEFAULT_MAX_FILES
HARVEST_NODE_DEFAULT_MAX_MSconst—const HARVEST_NODE_DEFAULT_MAX_MS
harvestCacheKeyfnL2 键:pkg + version + knobs + dtsClosureHash(相对化;content-addressable)harvestCacheKey( pkg: string, meta: { dtsHash: string; maxFiles: number; pkgVersion?: string }, ): string
harvestDtsfn—harvestDts( files: string[], opts?: { maxFileBytes?: number; maxMs?: number }, ): HarvestedEnv
HarvestedEnvtypeHarvested env:Abs 原生(与 EnvDefinition 同形)。HarvestedEnv = { globals: Record<string, Abs>; modules: Record<string, Record<string, Abs>>; stats: { files: number; symbols: number; ski...
harvestedValueToAbsfn单个 Abs 导出 → 可调用 mock(fn 槽按 relation α 替换,或返回声明返回类型)harvestedValueToAbs(a: Abs): Abs
HarvestJsontype—HarvestJson = { v: 1; pkg: string; pkgVersion?: string; knobs: { maxFiles: number; abi: string }; dtsHash: string; modules: Record<string...
HarvestNodeStatstype—HarvestNodeStats = { files: number; symbols: number; skipped: number; degraded?: number; }
harvestNodeTypesfnharvest @types/node(限制文件数 + 时间预算,避免拖垮启动)。harvestNodeTypes( fromDir?: string, maxFiles: number = HARVEST_NODE_DEFAULT_MAX_FILES, maxMs: number = HARVEST_NODE_DEFAULT_MAX_MS, ): NodeEnvResult
harvestPackagefnharvest 一个 npm 包(或 @types 包)harvestPackage( pkg: string, fromDir?: string, maxFiles = 24, ): PackageHarvest
harvestPackageCachedfn—harvestPackageCached(pkg: string, fromDir: string): PackageHarvest | null
harvestPackageWithDiskfnL2 + L0:磁盘优先(跳过 harvestDts 解析),miss 再 harvest 并写盘。harvestPackageWithDisk( pkg: string, fromDir: string, maxFiles = 24, ): PackageHarvest | null
HarvestSigtype签名投影节点(可 JSON 化;足够 mock Abs 的 shape 面)。HarvestSig = | { k: "prim"; type: string } | { k: "unknown" } | { k: "any" } | { k: "never" } | { k: "lit"; value: number | string | bool...
harvestSigToAbsfn签名投影 → mock Abs(conf 合 mock)harvestSigToAbs(sig: HarvestSig): Abs
isHarvestNodeDisabledfn—isHarvestNodeDisabled(env: NodeJS.ProcessEnv = process.env): boolean
lookupHarvestedfn取某个导出的展示串(formatShape)lookupHarvested( h: PackageHarvest, moduleName: string, exportName: string, ): string | undefined
materializeHarvestJsonfnHarvestJson → mock Abs 导出表(materialize);损坏/版本不符 → nullmaterializeHarvestJson(j: unknown): HarvestedEnv | null
NodeEnvResulttype—NodeEnvResult = | { ok: true; env: HarvestedEnv; root: string; files: number; stats: HarvestNodeStats; cached: boolean; degraded?: boolea...
PackageHarvesttype—PackageHarvest = { pkg: string; root: string; dtsFiles: string[]; env: HarvestedEnv; }
packageHarvestToAbsModulesfn把 harvest 的 modules/globals 合成 AbsModuleExports。packageHarvestToAbsModules( pkg: string, h: PackageHarvest, ): Record<string, AbsModuleExports>
readHarvestDiskfn—readHarvestDisk(root: string, key: string): HarvestJson | undefined
resolvePackageRootfn在 node_modules 中解析包根(含 @types/*)。resolvePackageRoot( pkg: string, fromDir: string = process.cwd(), ): string | undefined
serializeHarvestJsonfn—serializeHarvestJson( pkg: string, env: HarvestedEnv, meta: { dtsHash: string; maxFiles: number; pkgVersion?: string }, ): HarvestJson
writeHarvestDiskfn—writeHarvestDisk(root: string, key: string, value: HarvestJson): void