@nudojs/harvester 0.4.0 → 0.4.3

package/dist/index.d.ts

@@ -7,10 +7,18 @@ import { Abs, AbsModuleExports } from '@nudojs/core';
 type HarvestedEnv = {
     globals: Record<string, Abs>;
     modules: Record<string, Record<string, Abs>>;
+    /**
+     * 收割统计。
+     *
+     * - `skipped`：**丢了**（符号没进收割面）
+     * - `degraded`：**降级**（符号在，但类型有未建模的部分 ⇒ 值域未知）——族 52 第 6 条
+     *   新增的**可选**字段（旧磁盘缓存 / 外部构造的 env 不带它 ⇒ `undefined`）。
+     */
     stats: {
         files: number;
         symbols: number;
         skipped: number;
+        degraded?: number;
     };
 };
 declare function harvestDts(files: string[], opts?: {
@@ -25,6 +33,11 @@ type DtsExportDraft = {
     dsl?: string;
     note?: string;
     kind: "function" | "value" | "class" | "other";
+    /**
+     * 投影了，但**有未建模的部分**（值域 / Promise 外壳 / 合并重载 / 未建模的
+     * 类型引用）⇒ 汇总行把它计入 `skipped`（丢失必须如实计数）。
+     */
+    partial?: boolean;
 };
 type DtsContractDraft = {
     label: string;
@@ -35,6 +48,14 @@ type DtsContractDraft = {
         files: number;
         exports: number;
         skipped: number;
+        /**
+         * 目录模式被投影预算截断掉的 `.d.ts` 数。
+         * 当前**不设**投影预算（Bug 1015：静默截断 + 汇总行说谎）⇒ 恒为 0；
+         * 字段保留：将来引入预算时按此**如实计数**。
+         */
+        droppedFiles?: number;
+        /** 目录模式**没能遍历**的目录 / 条目数（读失败 / 深度上限） */
+        droppedDirs?: number;
     };
 };
 /** 组装 `@nudo:draft` 模块（与 formatDraftModule 同纪律：不 ambient 绑定）。 */
@@ -52,7 +73,17 @@ declare function dtsPathToContractDraft(path: string, label?: string): DtsContra
  * 代数不碰 fs；这里只做「找到 dts 路径」这一层宿主职责。
  */
 
-/** 在 node_modules 中解析包根（含 @types/*） */
+/**
+ * 在 node_modules 中解析包根（含 @types/*）。
+ *
+ * 口径与 TypeScript / Node 一致（Bug 833）：
+ * 1. **包本体** `node_modules/<pkg>` 的 `types`/`typings` → `<pkg>/index.d.ts`；
+ * 2. **最后**才回落 `node_modules/@types/<pkg>`。
+ *
+ * 跨层查找时「**任意层**的包本体」先于「**任意层**的 `@types`」
+ * —— 否则更近层的 `@types/<pkg>` 会盖掉更远层的包本体，
+ * 收割到**陈旧的 @types 声明**（另一个版本的 API），且**零诊断**。
+ */
 declare function resolvePackageRoot(pkg: string, fromDir?: string): string | undefined;
 type PackageHarvest = {
     pkg: string;
@@ -120,17 +151,37 @@ type HarvestSig = {
 } | {
     k: "tuple";
     elements: HarvestSig[];
+    rest?: HarvestSig;
 } | {
     k: "obj";
     slots: Record<string, {
         v: HarvestSig;
         opt?: boolean;
     }>;
+    /** 族 27 Bug 803：索引签名（`Record<K,V>` / `obj[k]: V`）——不投影则
+     *  缓存往返会把「开放对象 + 值域」抹成闭合空对象 ⇒ 成员读 undefined ⇒ 定抛。 */
+    index?: {
+        key: HarvestSig;
+        value: HarvestSig;
+    };
+    /** 开放对象（索引签名的承载标志） */
+    open?: boolean;
 } | {
     k: "fn";
     params: string[];
     paramTypes: HarvestSig[];
     returns: HarvestSig;
+    ctor?: boolean;
+    slots?: Record<string, HarvestSig>;
+    /** 族 27 Bug 821 残留：条件类型的 `infer` 绑定线索。不投影 ⇒ 磁盘缓存
+     *  命中后条件元数据丢失 ⇒ 同一份 .d.ts 冷/热缓存给出**不同**类型。 */
+    inferFrom?: {
+        fromVar: string;
+        via: "arr" | "promise";
+        inferVar: string;
+    };
+    /** 条件类型判不出时的假支（`condFallback`） */
+    condFallback?: HarvestSig;
 } | {
     k: "sum";
     members: HarvestSig[];
@@ -163,10 +214,18 @@ type HarvestJson = {
     dtsHash: string;
     modules: Record<string, Record<string, HarvestSig>>;
     globals: Record<string, HarvestSig>;
+    /**
+     * 收割统计（族 52 第 6 条）。
+     *
+     * - `skipped`：**丢了**（符号没进收割面）
+     * - `degraded`：**降级**（符号在，但类型有未建模的部分）——**可选**字段，
+     *   没有降级时**不出现**（旧磁盘缓存没有它 ⇒ 读回是 `undefined` ⇒ 视作 0）。
+     */
     stats: {
         files: number;
         symbols: number;
         skipped: number;
+        degraded?: number;
     };
 };
 /** Abs → 签名投影（丢 pred/conf；fn 只留参数名+类型面；保留泛型 α 与 lit term） */
@@ -220,7 +279,13 @@ declare function loadHarvestEnvFromDisk(pkg: string, meta: {
 declare function harvestedValueToAbs(a: Abs): Abs;
 /**
  * 把 harvest 的 modules/globals 合成 AbsModuleExports。
- * 键同时登记：原始模块路径、包名、basename（path / @types/path）。
+ *
+ * 键的归属（Bug 835 / 1014）：
+ * - `declare module "x" { … }` 记录 → 只登记到**它自己的**键（`x` / 去 `@types/` 前缀 /
+ *   basename）；**不占包名键** —— 否则 `import { x } from "pkg"` 会拿到另一个模块的同名导出。
+ * - **包名键** → 该包**自己**的顶层导出（入口 `.d.ts` 的导出面）。
+ *   `declare global { … }` 与 script 模式 `.d.ts` 的顶层声明是 **ambient**，
+ *   TypeScript 侧不可 import（TS2305 / TS2306）⇒ **不得**进包名键。
  */
 declare function harvestToAbsModules(pkg: string, fromDir: string): Record<string, AbsModuleExports>;
 declare function packageHarvestToAbsModules(pkg: string, h: PackageHarvest): Record<string, AbsModuleExports>;
@@ -251,6 +316,11 @@ type HarvestNodeStats = {
     files: number;
     symbols: number;
     skipped: number;
+    /**
+     * 「类型未建模」的符号数（族 52 第 6 条）——**可选**字段：没有降级时**不出现**
+     * （旧磁盘缓存 / 手写 env 没有它 ⇒ `undefined` ⇒ 视作 0）。
+     */
+    degraded?: number;
 };
 type NodeEnvResult = {
     ok: true;