@doccov/sdk 0.30.7 → 0.31.1

package/dist/shared/{chunk-ehne5cde.js → chunk-ee3ctqje.js}

@@ -1452,6 +1452,8 @@ function detectAllExampleIssues(entry, registry) {
         type: "example-syntax-error",
         target: `example[${i}]`,
         issue: `@example contains invalid syntax: ${message}`,
+        expected: "valid syntax",
+        actual: message,
         suggestion: "Check for missing brackets, semicolons, or typos."
       });
       continue;
@@ -1482,6 +1484,8 @@ function detectAllExampleIssues(entry, registry) {
             type: "example-drift",
             target: identifier,
             issue: `@example references "${identifier}" which does not exist in this package.`,
+            expected: identifier,
+            actual: hasCloseMatch ? suggestion.value : undefined,
             suggestion: hasCloseMatch ? `Did you mean "${suggestion.value}"?` : undefined
           });
         }
@@ -1506,6 +1510,8 @@ function detectExampleRuntimeErrors(entry, runtimeResults) {
       type: "example-runtime-error",
       target: `example[${i}]`,
       issue: isTimeout ? `@example timed out after ${result.duration}ms.` : `@example throws at runtime: ${errorMessage}`,
+      expected: "successful execution",
+      actual: errorMessage,
       suggestion: isTimeout ? "Check for infinite loops or long-running operations." : "Fix the example code or update it to match the current API."
     });
   }
@@ -1571,6 +1577,8 @@ function detectExampleAssertionFailures(entry, runtimeResults) {
           type: "example-assertion-failed",
           target: `example[${i}]:line${assertion.lineNumber}`,
           issue: `Assertion expected "${assertion.expected}" but no output was produced`,
+          expected: assertion.expected,
+          actual: "(no output)",
           suggestion: "Ensure the example produces output for each assertion"
         });
         continue;
@@ -1580,6 +1588,8 @@ function detectExampleAssertionFailures(entry, runtimeResults) {
           type: "example-assertion-failed",
           target: `example[${i}]:line${assertion.lineNumber}`,
           issue: `Assertion failed: expected "${assertion.expected}" but got "${actual}"`,
+          expected: assertion.expected,
+          actual,
           suggestion: `Update assertion to: // => ${actual}`
         });
       }
@@ -1643,6 +1653,8 @@ function detectParamDrift(entry) {
             type: "param-mismatch",
             target: documentedName,
             issue: `JSDoc documents property "${propertyPath}" on parameter "${prefix}" which does not exist.`,
+            expected: documentedName,
+            actual: propsArray.length > 0 ? propsArray.map((p) => `${prefix}.${p}`).join(", ") : undefined,
             suggestion: suggestionText2
           });
           continue;
@@ -1662,6 +1674,8 @@ function detectParamDrift(entry) {
       type: "param-mismatch",
       target: documentedName,
       issue: `JSDoc documents parameter "${documentedName}" which is not present in the signature.`,
+      expected: documentedName,
+      actual: paramsArray.join(", ") || undefined,
       suggestion: suggestionText
     });
   }
@@ -1704,6 +1718,8 @@ function detectOptionalityDrift(entry) {
       type: "optionality-mismatch",
       target: docParam.name,
       issue,
+      expected: documentedOptional ? `[${docParam.name}]` : docParam.name,
+      actual: actualOptional ? "optional" : "required",
       suggestion
     });
   }
@@ -1751,6 +1767,8 @@ function detectParamTypeDrift(entry) {
       type: "param-type-mismatch",
       target: documentedParam.name,
       issue: buildParamTypeMismatchIssue(documentedParam.name, documentedParam.type, declaredType),
+      expected: documentedParam.type,
+      actual: declaredType,
       suggestion: `Update @param {${declaredType}} ${documentedParam.name} to match the signature.`
     });
   }
@@ -1771,6 +1789,8 @@ function detectDeprecatedDrift(entry) {
         type: "deprecated-mismatch",
         target,
         issue: `Declaration for "${target}" is marked deprecated but @deprecated is missing from the docs.`,
+        expected: "not deprecated",
+        actual: "deprecated",
         suggestion: "Add an @deprecated tag explaining the replacement or removal timeline."
       }
     ];
@@ -1780,6 +1800,8 @@ function detectDeprecatedDrift(entry) {
       type: "deprecated-mismatch",
       target,
       issue: `JSDoc marks "${target}" as deprecated but the TypeScript declaration is not.`,
+      expected: "@deprecated",
+      actual: "not deprecated",
       suggestion: "Remove the @deprecated tag or deprecate the declaration."
     }
   ];
@@ -1801,6 +1823,8 @@ function detectVisibilityDrift(entry) {
       type: "visibility-mismatch",
       target,
       issue: buildVisibilityIssue(target, exportDocVisibility, exportActualVisibility),
+      expected: formatDocVisibilityTag(exportDocVisibility.tagName),
+      actual: exportActualVisibility,
       suggestion: buildVisibilitySuggestion(exportDocVisibility, exportActualVisibility)
     });
   }
@@ -1821,6 +1845,8 @@ function detectVisibilityDrift(entry) {
       type: "visibility-mismatch",
       target: qualifiedTarget,
       issue: buildVisibilityIssue(qualifiedTarget, memberDocVisibility, memberActualVisibility),
+      expected: formatDocVisibilityTag(memberDocVisibility.tagName),
+      actual: memberActualVisibility,
       suggestion: buildVisibilitySuggestion(memberDocVisibility, memberActualVisibility)
     });
   }
@@ -1886,11 +1912,12 @@ function formatDocVisibilityTag(tagName) {
   }
   return trimmed.startsWith("@") ? trimmed : `@${trimmed}`;
 }
-function detectBrokenLinks(entry, registry) {
+function detectBrokenLinks(entry, registry, options) {
   if (!registry) {
     return [];
   }
   const drifts = [];
+  const { moduleGraph } = options ?? {};
   const patterns = [
     { pattern: /\{@link\s+([^}\s|]+)(?:\s*\|[^}]*)?\}/g, type: "@link" },
     { pattern: /\{@see\s+([^}\s]+)\}/g, type: "@see" },
@@ -1914,15 +1941,21 @@ function detectBrokenLinks(entry, registry) {
       if (target.includes("/") || target.includes("@")) {
         continue;
       }
-      if (!registry.all.has(rootName) && !registry.all.has(target)) {
-        const suggestion = findClosestMatch(rootName, registry.allNames);
-        drifts.push({
-          type: "broken-link",
-          target,
-          issue: `{${type} ${target}} references a symbol that does not exist.`,
-          suggestion: suggestion ? `Did you mean "${suggestion.value}"?` : undefined
-        });
+      if (registry.all.has(rootName) || registry.all.has(target)) {
+        continue;
+      }
+      if (moduleGraph?.all.has(rootName) || moduleGraph?.all.has(target)) {
+        continue;
       }
+      const suggestion = findClosestMatch(rootName, registry.allNames);
+      drifts.push({
+        type: "broken-link",
+        target,
+        issue: `{${type} ${target}} references a symbol that does not exist.`,
+        expected: target,
+        actual: suggestion?.value,
+        suggestion: suggestion ? `Did you mean "${suggestion.value}"?` : undefined
+      });
     }
   }
   return drifts;
@@ -1946,6 +1979,8 @@ function detectAsyncMismatch(entry) {
       type: "async-mismatch",
       target: "returns",
       issue: "Function returns Promise but documentation does not indicate async behavior.",
+      expected: "sync",
+      actual: "Promise",
       suggestion: "Add @async tag or document @returns {Promise<...>}."
     });
   }
@@ -1954,6 +1989,8 @@ function detectAsyncMismatch(entry) {
       type: "async-mismatch",
       target: "returns",
       issue: "Documentation indicates async but function does not return Promise.",
+      expected: "@async / Promise",
+      actual: "sync",
       suggestion: "Remove @async tag or update @returns type."
     });
   }
@@ -1992,6 +2029,8 @@ function detectReturnTypeDrift(entry) {
       type: "return-type-mismatch",
       target: "returns",
       issue: buildReturnTypeMismatchIssue(documentedType, documentedNormalized, declaredType),
+      expected: documentedType,
+      actual: declaredType,
       suggestion: `Update @returns to ${declaredType}.`
     }
   ];
@@ -2027,6 +2066,8 @@ function detectGenericConstraintDrift(entry) {
       type: "generic-constraint-mismatch",
       target: doc.name,
       issue: buildGenericConstraintMismatchIssue(doc.name, doc.constraint, actualConstraint),
+      expected: doc.constraint ?? "none",
+      actual: actualConstraint ?? "none",
       suggestion: buildGenericConstraintSuggestion(doc.name, actualConstraint)
     });
   }
@@ -2061,6 +2102,8 @@ function detectPropertyTypeDrift(entry) {
         type: "property-type-drift",
         target: memberName,
         issue: `Property "${memberName}" documented as {${documentedType}} but actual type is ${actualType}.`,
+        expected: documentedType,
+        actual: actualType,
         suggestion: `Update @type {${actualType}} to match the declaration.`
       });
     }
@@ -2117,16 +2160,16 @@ function buildExportRegistry(spec) {
   const allNames = Array.from(all);
   return { exports, types, all, callableNames, typeNames, allExportNames, allNames };
 }
-function computeDrift(spec) {
+function computeDrift(spec, options) {
   const registry = buildExportRegistry(spec);
   const exports = new Map;
   for (const entry of spec.exports ?? []) {
-    const drift = computeExportDrift(entry, registry);
+    const drift = computeExportDrift(entry, registry, options);
     exports.set(entry.id ?? entry.name, drift);
   }
   return { exports };
 }
-function computeExportDrift(entry, registry) {
+function computeExportDrift(entry, registry, options) {
   const hasDescription = Boolean(entry.description);
   const hasTags = (entry.tags?.length ?? 0) > 0;
   const hasExamples = (entry.examples?.length ?? 0) > 0;
@@ -2141,12 +2184,20 @@ function computeExportDrift(entry, registry) {
     drifts.push(...detectAllExampleIssues(entry, registry));
   }
   if (hasDescription || hasTags) {
-    drifts.push(...detectBrokenLinks(entry, registry));
+    drifts.push(...detectBrokenLinks(entry, registry, { moduleGraph: options?.moduleGraph }));
   }
   return drifts;
 }
 
 // src/analysis/health.ts
+function isExportDocumented(exp) {
+  if (exp.description && exp.description.trim().length > 0)
+    return true;
+  const meaningfulTags = exp.tags?.filter((t) => t.name !== "internal") ?? [];
+  if (meaningfulTags.length > 0)
+    return true;
+  return false;
+}
 function computeHealth(input) {
   const {
     coverageScore,
@@ -2197,11 +2248,92 @@ function computeHealth(input) {
   return result;
 }
 
+// src/analysis/presets.ts
+var DEFAULT_REQUIREMENTS = {
+  description: true,
+  params: false,
+  returns: false,
+  examples: false,
+  since: false
+};
+var PRESETS = {
+  minimal: {
+    description: true,
+    params: false,
+    returns: false,
+    examples: false,
+    since: false
+  },
+  verbose: {
+    description: true,
+    params: true,
+    returns: true,
+    examples: false,
+    since: false
+  },
+  "types-only": {
+    description: false,
+    params: false,
+    returns: false,
+    examples: false,
+    since: false
+  }
+};
+function resolveRequirements(style, require2) {
+  const base = style ? PRESETS[style] : DEFAULT_REQUIREMENTS;
+  if (require2) {
+    return {
+      description: require2.description ?? base.description,
+      params: require2.params ?? base.params,
+      returns: require2.returns ?? base.returns,
+      examples: require2.examples ?? base.examples,
+      since: require2.since ?? base.since
+    };
+  }
+  return { ...base };
+}
+
 // src/analysis/doccov-builder.ts
 import { DRIFT_CATEGORIES } from "@doccov/spec";
-function buildDocCovSpec(options) {
-  const { openpkg, openpkgPath, forgottenExports, apiSurfaceIgnore } = options;
+function hasInternalTag(exp) {
+  return exp.tags?.some((t) => t.name === "internal") ?? false;
+}
+var YIELD_BATCH_SIZE = 5;
+async function buildDocCovSpec(options) {
+  const {
+    openpkg,
+    openpkgPath,
+    forgottenExports,
+    apiSurfaceIgnore,
+    entryExportNames,
+    onProgress,
+    onExportAnalyzed,
+    style,
+    require: require2
+  } = options;
   const registry = buildExportRegistry(openpkg);
+  const requirements = resolveRequirements(style, require2);
+  const allExports = (openpkg.exports ?? []).filter((exp) => !hasInternalTag(exp));
+  const total = allExports.length;
+  const analysisResults = [];
+  for (let i = 0;i < total; i++) {
+    const exp = allExports[i];
+    onProgress?.(i + 1, total, exp.name);
+    if (i % YIELD_BATCH_SIZE === 0 && i > 0) {
+      await new Promise((r) => setImmediate(r));
+    }
+    const coverage = computeExportCoverage(exp, requirements);
+    const rawDrifts = computeExportDrift(exp, registry);
+    const categorizedDrifts = rawDrifts.map((d) => toCategorizedDrift(d));
+    analysisResults.push({ coverage, drifts: categorizedDrifts, exp });
+  }
+  const byName = new Map;
+  for (const result of analysisResults) {
+    const name = result.exp.name;
+    const existing = byName.get(name) ?? [];
+    existing.push(result);
+    byName.set(name, existing);
+  }
   const exports = {};
   let totalScore = 0;
   let documentedCount = 0;
@@ -2219,30 +2351,46 @@ function buildDocCovSpec(options) {
   };
   let totalDrift = 0;
   let fixableDrift = 0;
-  for (const exp of openpkg.exports ?? []) {
-    const coverage = computeExportCoverage(exp);
-    const rawDrifts = computeExportDrift(exp, registry);
-    const categorizedDrifts = rawDrifts.map((d) => toCategorizedDrift(d));
-    const exportId = exp.id ?? exp.name;
-    exports[exportId] = {
-      coverageScore: coverage.score,
-      missing: coverage.missing.length > 0 ? coverage.missing : undefined,
-      drift: categorizedDrifts.length > 0 ? categorizedDrifts : undefined
+  for (const [name, overloads] of byName) {
+    const bestResult = overloads.reduce((best, curr) => curr.coverage.score > best.coverage.score ? curr : best);
+    const exportId = bestResult.exp.id ?? name;
+    const allMissing = new Set;
+    for (const r of overloads) {
+      for (const m of r.coverage.missing) {
+        allMissing.add(m);
+      }
+    }
+    const allDrifts = [];
+    for (const r of overloads) {
+      allDrifts.push(...r.drifts);
+    }
+    const analysis = {
+      coverageScore: bestResult.coverage.score,
+      missing: allMissing.size > 0 ? Array.from(allMissing) : undefined,
+      drift: allDrifts.length > 0 ? allDrifts : undefined
     };
-    totalScore += coverage.score;
-    if (coverage.score === 100)
+    if (overloads.length > 1) {
+      analysis.overloadCount = overloads.length;
+    }
+    exports[exportId] = analysis;
+    if (onExportAnalyzed) {
+      const idx = Object.keys(exports).length;
+      await onExportAnalyzed(exportId, name, analysis, idx, byName.size);
+    }
+    totalScore += bestResult.coverage.score;
+    if (isExportDocumented(bestResult.exp))
       documentedCount++;
-    for (const rule of coverage.missing) {
+    for (const rule of bestResult.coverage.missing) {
       missingByRule[rule]++;
     }
-    for (const d of categorizedDrifts) {
+    for (const d of allDrifts) {
       driftByCategory[d.category]++;
       totalDrift++;
       if (d.fixable)
         fixableDrift++;
     }
   }
-  const exportCount = openpkg.exports?.length ?? 0;
+  const exportCount = byName.size;
   const coverageScore = exportCount > 0 ? Math.round(totalScore / exportCount) : 100;
   const health = computeHealth({
     coverageScore,
@@ -2265,7 +2413,7 @@ function buildDocCovSpec(options) {
     },
     health
   };
-  const apiSurface = computeApiSurface(forgottenExports, openpkg.types?.length ?? 0, apiSurfaceIgnore);
+  const apiSurface = computeApiSurface(forgottenExports, openpkg.types?.length ?? 0, apiSurfaceIgnore, entryExportNames);
   return {
     doccov: "1.0.0",
     source: {
@@ -2280,11 +2428,12 @@ function buildDocCovSpec(options) {
     ...apiSurface ? { apiSurface } : {}
   };
 }
-function computeApiSurface(forgottenExports, exportedTypesCount, ignoreList) {
+function computeApiSurface(forgottenExports, exportedTypesCount, ignoreList, entryExportNames) {
   if (!forgottenExports)
     return;
   const ignoreSet = new Set(ignoreList ?? []);
-  const filteredExports = forgottenExports.filter((f) => !ignoreSet.has(f.name));
+  const entryExportSet = new Set(entryExportNames ?? []);
+  const filteredExports = forgottenExports.filter((f) => !ignoreSet.has(f.name) && !entryExportSet.has(f.name));
   const forgotten = filteredExports.map((f) => ({
     name: f.name,
     definedIn: f.definedIn ? { file: f.definedIn } : undefined,
@@ -2305,36 +2454,52 @@ function computeApiSurface(forgottenExports, exportedTypesCount, ignoreList) {
     completeness
   };
 }
-function computeExportCoverage(exp) {
+function computeExportCoverage(exp, requirements) {
   const missing = [];
   let points = 0;
   let maxPoints = 0;
-  maxPoints += 30;
-  if (exp.description && exp.description.trim().length > 0) {
-    points += 30;
+  const descRequired = requirements.description;
+  if (descRequired) {
+    maxPoints += 30;
+    if (exp.description && exp.description.trim().length > 0) {
+      points += 30;
+    } else {
+      missing.push("description");
+    }
   } else {
-    missing.push("description");
+    if (!exp.description || exp.description.trim().length === 0) {
+      missing.push("description");
+    }
   }
   const isCallable = exp.kind === "function" || exp.kind === "class";
   if (isCallable && exp.signatures?.length) {
     const sig = exp.signatures[0];
     const params = sig.parameters ?? [];
     if (params.length > 0) {
-      maxPoints += 25;
+      const paramsRequired = requirements.params;
+      if (paramsRequired) {
+        maxPoints += 25;
+      }
       const documentedParams = params.filter((p) => p.description && p.description.trim().length > 0);
       if (documentedParams.length === params.length) {
-        points += 25;
+        if (paramsRequired)
+          points += 25;
       } else if (documentedParams.length > 0) {
-        points += Math.round(documentedParams.length / params.length * 25);
+        if (paramsRequired)
+          points += Math.round(documentedParams.length / params.length * 25);
         missing.push("params");
       } else {
         missing.push("params");
       }
     }
     if (exp.kind === "function" && sig.returns) {
-      maxPoints += 20;
+      const returnsRequired = requirements.returns;
+      if (returnsRequired) {
+        maxPoints += 20;
+      }
       if (sig.returns.description && sig.returns.description.trim().length > 0) {
-        points += 20;
+        if (returnsRequired)
+          points += 20;
       } else {
         missing.push("returns");
       }
@@ -2349,9 +2514,13 @@ function computeExportCoverage(exp) {
       }
     }
   }
-  maxPoints += 15;
+  const examplesRequired = requirements.examples;
+  if (examplesRequired) {
+    maxPoints += 15;
+  }
   if (exp.examples && exp.examples.length > 0) {
-    points += 15;
+    if (examplesRequired)
+      points += 15;
   } else {
     missing.push("examples");
   }
@@ -2507,35 +2676,45 @@ function isExportFullyDocumented(exp, doccov) {
 // src/analysis/report.ts
 import * as fs3 from "node:fs";
 import * as path3 from "node:path";
-function generateReport(spec, openpkgPath = "openpkg.json") {
-  const doccov = buildDocCovSpec({ openpkg: spec, openpkgPath });
+async function generateReport(spec, openpkgPath = "openpkg.json") {
+  const doccov = await buildDocCovSpec({ openpkg: spec, openpkgPath });
   return generateReportFromDocCov(spec, doccov);
 }
 function generateReportFromDocCov(openpkg, doccov) {
   const exportsData = {};
   const missingByRule = {};
+  const openpkgExportsById = new Map;
+  for (const exp of openpkg.exports ?? []) {
+    const id = exp.id ?? exp.name;
+    if (!openpkgExportsById.has(id)) {
+      openpkgExportsById.set(id, exp);
+    }
+  }
   let documentedExports = 0;
   let totalDrift = 0;
-  for (const exp of openpkg.exports ?? []) {
-    const analysis = getExportAnalysis(exp, doccov);
+  for (const [exportId, analysis] of Object.entries(doccov.exports)) {
+    const openpkgExp = openpkgExportsById.get(exportId);
     const data = {
-      name: exp.name,
-      kind: exp.kind,
-      coverageScore: analysis?.coverageScore ?? 100
+      name: openpkgExp?.name ?? exportId,
+      kind: openpkgExp?.kind ?? "unknown",
+      coverageScore: analysis.coverageScore
     };
-    if (analysis?.missing && analysis.missing.length > 0) {
+    if (analysis.missing && analysis.missing.length > 0) {
       data.missing = analysis.missing;
       for (const ruleId of analysis.missing) {
         missingByRule[ruleId] = (missingByRule[ruleId] ?? 0) + 1;
       }
-    } else {
+    }
+    if (openpkgExp && isExportDocumented(openpkgExp)) {
       documentedExports++;
     }
-    if (analysis?.drift && analysis.drift.length > 0) {
+    if (analysis.drift && analysis.drift.length > 0) {
       data.drift = analysis.drift;
       totalDrift += analysis.drift.length;
     }
-    const exportId = exp.id ?? exp.name;
+    if (analysis.overloadCount && analysis.overloadCount > 1) {
+      data.overloadCount = analysis.overloadCount;
+    }
     exportsData[exportId] = data;
   }
   const coverage = {
@@ -2778,6 +2957,226 @@ function renderApiSurface(spec) {
 `);
 }
 
+// src/analysis/module-graph.ts
+function buildModuleGraph(specs) {
+  const modules = new Map;
+  const exports = new Map;
+  const types = new Map;
+  const all = new Set;
+  for (const spec of specs) {
+    const moduleName = spec.meta.name;
+    const moduleExports = new Set;
+    const moduleTypes = new Set;
+    for (const exp of spec.exports ?? []) {
+      moduleExports.add(exp.name);
+      all.add(exp.name);
+      if (exp.id) {
+        moduleExports.add(exp.id);
+        all.add(exp.id);
+      }
+      if (!exports.has(exp.name)) {
+        exports.set(exp.name, moduleName);
+      }
+      if (exp.kind === "namespace" && exp.members) {
+        for (const member of exp.members) {
+          if (!member.name)
+            continue;
+          moduleExports.add(member.name);
+          all.add(member.name);
+          if (!exports.has(member.name)) {
+            exports.set(member.name, moduleName);
+          }
+        }
+      }
+    }
+    for (const type of spec.types ?? []) {
+      moduleTypes.add(type.name);
+      all.add(type.name);
+      if (type.id) {
+        moduleTypes.add(type.id);
+        all.add(type.id);
+      }
+      if (!types.has(type.name)) {
+        types.set(type.name, moduleName);
+      }
+    }
+    modules.set(moduleName, {
+      name: moduleName,
+      exports: moduleExports,
+      types: moduleTypes
+    });
+  }
+  return { modules, exports, types, all };
+}
+function findSymbolModule(graph, symbol) {
+  return graph.exports.get(symbol) ?? graph.types.get(symbol);
+}
+function symbolExistsInGraph(graph, symbol) {
+  return graph.all.has(symbol);
+}
+
+// src/analysis/incremental.ts
+import * as fs4 from "node:fs";
+import * as os from "node:os";
+import * as path4 from "node:path";
+
+class IncrementalAnalyzer {
+  tempPath;
+  totalExpected;
+  resultCount = 0;
+  fileHandle;
+  constructor(options = {}) {
+    const tempDir = options.tempDir ?? os.tmpdir();
+    const prefix = options.prefix ?? "doccov";
+    this.tempPath = path4.join(tempDir, `${prefix}-${Date.now()}-${process.pid}.ndjson`);
+  }
+  get path() {
+    return this.tempPath;
+  }
+  get count() {
+    return this.resultCount;
+  }
+  setTotal(total) {
+    this.totalExpected = total;
+  }
+  async init() {
+    if (!this.fileHandle) {
+      this.fileHandle = await fs4.promises.open(this.tempPath, "a");
+      const header = {
+        type: "header",
+        startedAt: new Date().toISOString(),
+        totalExpected: this.totalExpected,
+        pid: process.pid
+      };
+      await this.fileHandle.appendFile(JSON.stringify(header) + `
+`);
+    }
+  }
+  async writeResult(result) {
+    await this.init();
+    const line = JSON.stringify({ type: "result", ...result }) + `
+`;
+    await this.fileHandle.appendFile(line);
+    this.resultCount++;
+  }
+  async writeExportAnalysis(id, name, analysis) {
+    const result = {
+      id,
+      name,
+      coverageScore: analysis.coverageScore,
+      missing: analysis.missing,
+      drift: analysis.drift,
+      overloadCount: analysis.overloadCount,
+      timestamp: Date.now()
+    };
+    await this.writeResult(result);
+  }
+  async getPartialResults() {
+    try {
+      if (this.fileHandle) {
+        await this.fileHandle.close();
+        this.fileHandle = undefined;
+      }
+      const content = await fs4.promises.readFile(this.tempPath, "utf-8");
+      const lines = content.split(`
+`).filter(Boolean);
+      const results = [];
+      let totalExpected;
+      for (const line of lines) {
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed.type === "header") {
+            totalExpected = parsed.totalExpected;
+          } else if (parsed.type === "result") {
+            const { type, ...result } = parsed;
+            results.push(result);
+          }
+        } catch {}
+      }
+      return {
+        results,
+        totalExpected,
+        interrupted: totalExpected !== undefined && results.length < totalExpected
+      };
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return { results: [], interrupted: false };
+      }
+      throw err;
+    }
+  }
+  async cleanup() {
+    try {
+      if (this.fileHandle) {
+        await this.fileHandle.close();
+        this.fileHandle = undefined;
+      }
+      await fs4.promises.unlink(this.tempPath);
+    } catch {}
+  }
+  cleanupSync() {
+    try {
+      if (this.fileHandle) {
+        this.fileHandle = undefined;
+      }
+      fs4.unlinkSync(this.tempPath);
+    } catch {}
+  }
+  exists() {
+    return fs4.existsSync(this.tempPath);
+  }
+  getPartialResultsSync() {
+    try {
+      const content = fs4.readFileSync(this.tempPath, "utf-8");
+      const lines = content.split(`
+`).filter(Boolean);
+      const results = [];
+      let totalExpected;
+      for (const line of lines) {
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed.type === "header") {
+            totalExpected = parsed.totalExpected;
+          } else if (parsed.type === "result") {
+            const { type, ...result } = parsed;
+            results.push(result);
+          }
+        } catch {}
+      }
+      return {
+        results,
+        totalExpected,
+        interrupted: totalExpected !== undefined && results.length < totalExpected
+      };
+    } catch {
+      return { results: [], interrupted: false };
+    }
+  }
+}
+function findOrphanedTempFiles(tempDir = os.tmpdir(), prefix = "doccov") {
+  try {
+    const files = fs4.readdirSync(tempDir);
+    return files.filter((f) => f.startsWith(prefix) && f.endsWith(".ndjson")).map((f) => path4.join(tempDir, f));
+  } catch {
+    return [];
+  }
+}
+function cleanupOrphanedTempFiles(tempDir = os.tmpdir(), prefix = "doccov", maxAge = 60 * 60 * 1000) {
+  const files = findOrphanedTempFiles(tempDir, prefix);
+  const now = Date.now();
+  let cleaned = 0;
+  for (const file of files) {
+    try {
+      const stat = fs4.statSync(file);
+      if (now - stat.mtimeMs > maxAge) {
+        fs4.unlinkSync(file);
+        cleaned++;
+      }
+    } catch {}
+  }
+  return cleaned;
+}
+
 // src/extract/schema/index.ts
 import {
   arktypeAdapter,
@@ -2847,8 +3246,8 @@ async function detectRuntimeSchemas(context) {
 }
 
 // src/utils/project-root.ts
-import * as fs4 from "node:fs";
-import * as path4 from "node:path";
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
 var PROJECT_ROOT_MARKERS = [
   ".git",
   "pnpm-workspace.yaml",
@@ -2858,39 +3257,39 @@ var PROJECT_ROOT_MARKERS = [
   "rush.json"
 ];
 function findProjectRoot(startDir) {
-  let dir = path4.resolve(startDir);
-  const root = path4.parse(dir).root;
+  let dir = path5.resolve(startDir);
+  const root = path5.parse(dir).root;
   while (dir !== root) {
     for (const marker of PROJECT_ROOT_MARKERS) {
-      const markerPath = path4.join(dir, marker);
-      if (fs4.existsSync(markerPath)) {
+      const markerPath = path5.join(dir, marker);
+      if (fs5.existsSync(markerPath)) {
         return dir;
       }
     }
-    const pkgPath = path4.join(dir, "package.json");
-    if (fs4.existsSync(pkgPath)) {
+    const pkgPath = path5.join(dir, "package.json");
+    if (fs5.existsSync(pkgPath)) {
       try {
-        const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
+        const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
         if (pkg.workspaces) {
           return dir;
         }
       } catch {}
     }
-    dir = path4.dirname(dir);
+    dir = path5.dirname(dir);
   }
-  return path4.resolve(startDir);
+  return path5.resolve(startDir);
 }
 function getDoccovDir(cwd) {
   const projectRoot = findProjectRoot(cwd);
-  return path4.join(projectRoot, ".doccov");
+  return path5.join(projectRoot, ".doccov");
 }
 
 // src/analysis/history.ts
-import * as fs5 from "node:fs";
-import * as path5 from "node:path";
+import * as fs6 from "node:fs";
+import * as path6 from "node:path";
 var HISTORY_DIR = ".doccov/history";
 function getHistoryDir(cwd) {
-  return path5.join(getDoccovDir(cwd), "history");
+  return path6.join(getDoccovDir(cwd), "history");
 }
 var RETENTION_DAYS = 90;
 function getSnapshotFilename(timestamp) {
@@ -2905,7 +3304,7 @@ function getSnapshotFilename(timestamp) {
 }
 function computeSnapshot(spec, options) {
   const exports = spec.exports ?? [];
-  const documented = exports.filter((e) => e.description && e.description.trim().length > 0);
+  const documented = exports.filter(isExportDocumented);
   const driftCount = exports.reduce((sum, e) => {
     const docs = e.docs;
     return sum + (docs?.drift?.length ?? 0);
@@ -2925,23 +3324,23 @@ function computeSnapshot(spec, options) {
 }
 function saveSnapshot(snapshot, cwd) {
   const historyDir = getHistoryDir(cwd);
-  if (!fs5.existsSync(historyDir)) {
-    fs5.mkdirSync(historyDir, { recursive: true });
+  if (!fs6.existsSync(historyDir)) {
+    fs6.mkdirSync(historyDir, { recursive: true });
   }
   const filename = getSnapshotFilename(new Date(snapshot.timestamp));
-  const filepath = path5.join(historyDir, filename);
-  fs5.writeFileSync(filepath, JSON.stringify(snapshot, null, 2));
+  const filepath = path6.join(historyDir, filename);
+  fs6.writeFileSync(filepath, JSON.stringify(snapshot, null, 2));
 }
 function loadSnapshots(cwd) {
   const historyDir = getHistoryDir(cwd);
-  if (!fs5.existsSync(historyDir)) {
+  if (!fs6.existsSync(historyDir)) {
     return [];
   }
-  const files = fs5.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
+  const files = fs6.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
   const snapshots = [];
   for (const file of files) {
     try {
-      const content = fs5.readFileSync(path5.join(historyDir, file), "utf-8");
+      const content = fs6.readFileSync(path6.join(historyDir, file), "utf-8");
       snapshots.push(JSON.parse(content));
     } catch {}
   }
@@ -2982,14 +3381,14 @@ function formatDelta(delta) {
 }
 function pruneHistory(cwd, keepCount = 100) {
   const historyDir = getHistoryDir(cwd);
-  if (!fs5.existsSync(historyDir)) {
+  if (!fs6.existsSync(historyDir)) {
     return 0;
   }
-  const files = fs5.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
+  const files = fs6.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
   const toDelete = files.slice(keepCount);
   for (const file of toDelete) {
     try {
-      fs5.unlinkSync(path5.join(historyDir, file));
+      fs6.unlinkSync(path6.join(historyDir, file));
     } catch {}
   }
   return toDelete.length;
@@ -3085,4 +3484,4 @@ function getExtendedTrend(spec, cwd, options) {
   };
 }
 
-export { isFixableDrift, generateFix, generateFixesForExport, mergeFixes, categorizeDrifts, generateForgottenExportFixes, groupFixesByFile, applyForgottenExportFixes, previewForgottenExportFixes, ts, parseJSDocToPatch, applyPatchToJSDoc, serializeJSDoc, findJSDocLocation, applyEdits, createSourceFile, isBuiltInIdentifier, detectExampleRuntimeErrors, parseAssertions, hasNonAssertionComments, detectExampleAssertionFailures, buildExportRegistry, computeDrift, computeExportDrift, computeHealth, buildDocCovSpec, DRIFT_CATEGORIES2 as DRIFT_CATEGORIES, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, categorizeDrift, groupDriftsByCategory, getDriftSummary, formatDriftSummaryLine, calculateAggregateCoverage, ensureSpecCoverage, getExportAnalysis, getExportScore, getExportDrift, getExportMissing, isExportFullyDocumented, generateReport, generateReportFromDocCov, loadCachedReport, saveReport, isCachedReportValid, renderApiSurface, extractSchemaOutputType, getRegisteredAdapters, getSupportedLibraries, extractSchemaType, extractStandardSchemas, extractStandardSchemasFromProject, findAdapter, isSchemaType, isStandardJSONSchema, resolveCompiledPath, detectRuntimeSchemas, findProjectRoot, getDoccovDir, HISTORY_DIR, computeSnapshot, saveSnapshot, loadSnapshots, getTrend, renderSparkline, formatDelta, pruneHistory, loadSnapshotsForDays, generateWeeklySummaries, getExtendedTrend };
+export { isFixableDrift, generateFix, generateFixesForExport, mergeFixes, categorizeDrifts, generateForgottenExportFixes, groupFixesByFile, applyForgottenExportFixes, previewForgottenExportFixes, ts, parseJSDocToPatch, applyPatchToJSDoc, serializeJSDoc, findJSDocLocation, applyEdits, createSourceFile, isBuiltInIdentifier, detectExampleRuntimeErrors, parseAssertions, hasNonAssertionComments, detectExampleAssertionFailures, buildExportRegistry, computeDrift, computeExportDrift, isExportDocumented, computeHealth, DEFAULT_REQUIREMENTS, PRESETS, resolveRequirements, buildDocCovSpec, DRIFT_CATEGORIES2 as DRIFT_CATEGORIES, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, categorizeDrift, groupDriftsByCategory, getDriftSummary, formatDriftSummaryLine, calculateAggregateCoverage, ensureSpecCoverage, getExportAnalysis, getExportScore, getExportDrift, getExportMissing, isExportFullyDocumented, generateReport, generateReportFromDocCov, loadCachedReport, saveReport, isCachedReportValid, renderApiSurface, buildModuleGraph, findSymbolModule, symbolExistsInGraph, IncrementalAnalyzer, findOrphanedTempFiles, cleanupOrphanedTempFiles, extractSchemaOutputType, getRegisteredAdapters, getSupportedLibraries, extractSchemaType, extractStandardSchemas, extractStandardSchemasFromProject, findAdapter, isSchemaType, isStandardJSONSchema, resolveCompiledPath, detectRuntimeSchemas, findProjectRoot, getDoccovDir, HISTORY_DIR, computeSnapshot, saveSnapshot, loadSnapshots, getTrend, renderSparkline, formatDelta, pruneHistory, loadSnapshotsForDays, generateWeeklySummaries, getExtendedTrend };