@doccov/cli 0.24.1 → 0.25.0

package/dist/cli.js

@@ -153,8 +153,8 @@ import { Command } from "commander";
 
 // src/commands/check/index.ts
 import {
+  buildDocCovSpec,
   DocCov,
-  enrichSpec,
   NodeFileSystem,
   parseExamplesFlag,
   resolveTarget
@@ -292,15 +292,13 @@ import chalk3 from "chalk";
 // src/commands/check/utils.ts
 import * as fs from "node:fs";
 import * as path2 from "node:path";
-import {
-  DRIFT_CATEGORIES,
-  parseMarkdownFiles
-} from "@doccov/sdk";
+import { getExportDrift, parseMarkdownFiles } from "@doccov/sdk";
+import { DRIFT_CATEGORIES } from "@doccov/spec";
 import { glob } from "glob";
-function collectDriftsFromExports(exports) {
+function collectDriftsFromExports(exports, doccov) {
   const results = [];
   for (const exp of exports) {
-    for (const drift of exp.docs?.drift ?? []) {
+    for (const drift of getExportDrift(exp, doccov)) {
       results.push({ export: exp, drift });
     }
   }
@@ -315,16 +313,16 @@ function groupByExport(drifts) {
   }
   return map;
 }
-function collectDrift(exportsList) {
+function collectDrift(exports, doccov) {
   const drifts = [];
-  for (const entry of exportsList) {
-    const drift = entry.docs?.drift;
-    if (!drift || drift.length === 0) {
+  for (const exp of exports) {
+    const exportDrifts = getExportDrift(exp, doccov);
+    if (exportDrifts.length === 0) {
       continue;
     }
-    for (const d of drift) {
+    for (const d of exportDrifts) {
       drifts.push({
-        name: entry.name,
+        name: exp.name,
         type: d.type,
         issue: d.issue ?? "Documentation drift detected.",
         suggestion: d.suggestion,
@@ -353,11 +351,11 @@ async function loadMarkdownFiles(patterns, cwd) {
 }
 
 // src/commands/check/fix-handler.ts
-async function handleFixes(spec, options, deps) {
+async function handleFixes(openpkg, doccov, options, deps) {
   const { isPreview, targetDir } = options;
   const { log, error } = deps;
   const fixedDriftKeys = new Set;
-  const allDrifts = collectDriftsFromExports(spec.exports ?? []);
+  const allDrifts = collectDriftsFromExports(openpkg.exports ?? [], doccov);
   if (allDrifts.length === 0) {
     return { fixedDriftKeys, editsApplied: 0, filesModified: 0 };
   }
@@ -443,8 +441,7 @@ function generateEditForExport(exp, drifts, targetDir, log) {
   if (location.hasExisting && location.existingJSDoc) {
     existingPatch = parseJSDocToPatch(location.existingJSDoc);
   }
-  const expWithDrift = { ...exp, docs: { ...exp.docs, drift: drifts } };
-  const fixes = generateFixesForExport(expWithDrift, existingPatch);
+  const fixes = generateFixesForExport(exp, existingPatch, drifts);
   if (fixes.length === 0)
     return null;
   const mergedPatch = mergeFixes(fixes, existingPatch);
@@ -499,7 +496,7 @@ function displayPreview(editsByFile, targetDir, log) {
 }
 
 // src/commands/check/output.ts
-import { generateReport } from "@doccov/sdk";
+import { generateReportFromDocCov } from "@doccov/sdk";
 import chalk5 from "chalk";
 
 // src/reports/changelog-renderer.ts
@@ -937,6 +934,7 @@ function renderHtml(stats, options = {}) {
 </html>`;
 }
 // src/reports/pr-comment.ts
+import { getExportDrift as getExportDrift3 } from "@doccov/sdk";
 function extractReturnType(schema) {
   if (!schema)
     return "void";
@@ -954,7 +952,7 @@ function extractReturnType(schema) {
   return "unknown";
 }
 function renderPRComment(data, opts = {}) {
-  const { diff, headSpec } = data;
+  const { diff, headSpec, doccov } = data;
   const limit = opts.limit ?? 10;
   const lines = [];
   const hasStaleRefs = (opts.staleDocsRefs?.length ?? 0) > 0;
@@ -987,7 +985,7 @@ function renderPRComment(data, opts = {}) {
     lines.push("");
     lines.push("### Doc drift detected");
     lines.push("");
-    renderDriftIssues(lines, diff.newUndocumented, headSpec, opts, limit);
+    renderDriftIssues(lines, diff.newUndocumented, headSpec, doccov, opts, limit);
   }
   if (opts.staleDocsRefs && opts.staleDocsRefs.length > 0) {
     lines.push("");
@@ -1069,18 +1067,16 @@ function renderUndocumentedExports(lines, undocumented, headSpec, opts, limit) {
     lines.push(`_...and ${undocumented.length - count} more undocumented exports_`);
   }
 }
-function renderDriftIssues(lines, _undocumented, headSpec, opts, limit) {
+function renderDriftIssues(lines, _undocumented, headSpec, doccov, opts, limit) {
   const driftIssues = [];
   for (const exp of headSpec.exports) {
-    const drifts = exp.docs?.drift;
-    if (drifts) {
-      for (const d of drifts) {
-        driftIssues.push({
-          exportName: exp.name,
-          file: exp.source?.file,
-          drift: d
-        });
-      }
+    const drifts = doccov ? getExportDrift3(exp, doccov) : [];
+    for (const d of drifts) {
+      driftIssues.push({
+        exportName: exp.name,
+        file: exp.source?.file,
+        drift: d
+      });
     }
   }
   if (driftIssues.length === 0) {
@@ -1222,12 +1218,10 @@ function renderDetailsTable(lines, diff) {
   }
 }
 // src/reports/stats.ts
-import {
-  DRIFT_CATEGORIES as DRIFT_CATEGORIES2,
-  isFixableDrift
-} from "@doccov/sdk";
-function computeStats(spec) {
-  const exports = spec.exports ?? [];
+import { getExportAnalysis, getExportDrift as getExportDrift4, isFixableDrift } from "@doccov/sdk";
+import { DRIFT_CATEGORIES as DRIFT_CATEGORIES2 } from "@doccov/spec";
+function computeStats(openpkg, doccov) {
+  const exports = openpkg.exports ?? [];
   const signals = {
     description: { covered: 0, total: 0 },
     params: { covered: 0, total: 0 },
@@ -1245,8 +1239,9 @@ function computeStats(spec) {
   let partiallyDocumented = 0;
   let undocumented = 0;
   for (const exp of exports) {
-    const score = exp.docs?.coverageScore ?? 0;
-    const missing = exp.docs?.missing ?? [];
+    const analysis = getExportAnalysis(exp, doccov);
+    const score = analysis?.coverageScore ?? 0;
+    const missing = analysis?.missing ?? [];
     for (const sig of ["description", "params", "returns", "examples"]) {
       signals[sig].total++;
       if (!missing.includes(sig))
@@ -1262,7 +1257,7 @@ function computeStats(spec) {
       partiallyDocumented++;
     else
       undocumented++;
-    for (const d of exp.docs?.drift ?? []) {
+    for (const d of getExportDrift4(exp, doccov)) {
       const item = {
         exportName: exp.name,
         type: d.type,
@@ -1283,12 +1278,15 @@ function computeStats(spec) {
     count,
     avgScore: Math.round(totalScore / count)
   })).sort((a, b) => b.count - a.count);
-  const sortedExports = exports.map((e) => ({
-    name: e.name,
-    kind: e.kind,
-    score: e.docs?.coverageScore ?? 0,
-    missing: e.docs?.missing ?? []
-  })).sort((a, b) => a.score - b.score);
+  const sortedExports = exports.map((e) => {
+    const analysis = getExportAnalysis(e, doccov);
+    return {
+      name: e.name,
+      kind: e.kind,
+      score: analysis?.coverageScore ?? 0,
+      missing: analysis?.missing ?? []
+    };
+  }).sort((a, b) => a.score - b.score);
   const driftSummary = {
     total: driftIssues.length,
     byCategory: {
@@ -1301,9 +1299,9 @@ function computeStats(spec) {
   const exportsWithDrift = new Set(driftIssues.map((d) => d.exportName)).size;
   const driftScore = exports.length === 0 ? 0 : Math.round(exportsWithDrift / exports.length * 100);
   return {
-    packageName: spec.meta.name ?? "unknown",
-    version: spec.meta.version ?? "0.0.0",
-    coverageScore: spec.docs?.coverageScore ?? 0,
+    packageName: openpkg.meta.name ?? "unknown",
+    version: openpkg.meta.version ?? "0.0.0",
+    coverageScore: doccov.summary.score,
     driftScore,
     totalExports: exports.length,
     fullyDocumented,
@@ -1359,7 +1357,8 @@ function writeReports(options) {
 // src/commands/check/output.ts
 function displayTextOutput(options, deps) {
   const {
-    spec,
+    openpkg,
+    doccov,
     coverageScore,
     minCoverage,
     maxDrift,
@@ -1371,7 +1370,7 @@ function displayTextOutput(options, deps) {
     specInfos
   } = options;
   const { log } = deps;
-  const totalExportsForDrift = spec.exports?.length ?? 0;
+  const totalExportsForDrift = openpkg.exports?.length ?? 0;
   const exportsWithDrift = new Set(driftExports.map((d) => d.name)).size;
   const driftScore = totalExportsForDrift === 0 ? 0 : Math.round(exportsWithDrift / totalExportsForDrift * 100);
   const coverageFailed = coverageScore < minCoverage;
@@ -1392,9 +1391,9 @@ function displayTextOutput(options, deps) {
       }
     }
   }
-  const pkgName = spec.meta?.name ?? "unknown";
-  const pkgVersion = spec.meta?.version ?? "";
-  const totalExports = spec.exports?.length ?? 0;
+  const pkgName = openpkg.meta?.name ?? "unknown";
+  const pkgVersion = openpkg.meta?.version ?? "";
+  const totalExports = openpkg.exports?.length ?? 0;
   log("");
   log(chalk5.bold(`${pkgName}${pkgVersion ? `@${pkgVersion}` : ""}`));
   log("");
@@ -1463,8 +1462,8 @@ function displayTextOutput(options, deps) {
 function handleNonTextOutput(options, deps) {
   const {
     format,
-    spec,
-    rawSpec,
+    openpkg,
+    doccov,
     coverageScore,
     minCoverage,
     maxDrift,
@@ -1476,8 +1475,8 @@ function handleNonTextOutput(options, deps) {
     cwd
   } = options;
   const { log } = deps;
-  const stats = computeStats(spec);
-  const report = generateReport(rawSpec);
+  const stats = computeStats(openpkg, doccov);
+  const report = generateReportFromDocCov(openpkg, doccov);
   const jsonContent = JSON.stringify(report, null, 2);
   let formatContent;
   switch (format) {
@@ -1510,7 +1509,7 @@ function handleNonTextOutput(options, deps) {
       cwd
     });
   }
-  const totalExportsForDrift = spec.exports?.length ?? 0;
+  const totalExportsForDrift = openpkg.exports?.length ?? 0;
   const exportsWithDrift = new Set(driftExports.map((d) => d.name)).size;
   const driftScore = totalExportsForDrift === 0 ? 0 : Math.round(exportsWithDrift / totalExportsForDrift * 100);
   const coverageFailed = coverageScore < minCoverage;
@@ -1521,14 +1520,14 @@ function handleNonTextOutput(options, deps) {
 
 // src/commands/check/validation.ts
 import { validateExamples } from "@doccov/sdk";
-async function runExampleValidation(spec, options) {
+async function runExampleValidation(openpkg, options) {
   const { validations, targetDir, timeout = 5000, installTimeout = 60000 } = options;
   const typecheckErrors = [];
   const runtimeDrifts = [];
-  const result = await validateExamples(spec.exports ?? [], {
+  const result = await validateExamples(openpkg.exports ?? [], {
     validations,
     packagePath: targetDir,
-    exportNames: (spec.exports ?? []).map((e) => e.name),
+    exportNames: (openpkg.exports ?? []).map((e) => e.name),
     timeout,
     installTimeout
   });
@@ -1654,19 +1653,24 @@ function registerCheckCommand(program, dependencies = {}) {
       }
       steps.next();
       const resolveExternalTypes = !options.skipResolve;
-      const doccov = createDocCov({
+      const analyzer = createDocCov({
         resolveExternalTypes,
         maxDepth: options.maxTypeDepth,
         useCache: options.cache !== false,
         cwd: options.cwd
       });
       const analyzeOptions = resolvedFilters.visibility ? { filters: { visibility: resolvedFilters.visibility } } : {};
-      const specResult = await doccov.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
+      const specResult = await analyzer.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
       if (!specResult) {
         throw new Error("Failed to analyze documentation coverage.");
       }
       steps.next();
-      const spec = enrichSpec(specResult.spec);
+      const openpkg = specResult.spec;
+      const doccov = buildDocCovSpec({
+        openpkg,
+        openpkgPath: entryFile,
+        packagePath: targetDir
+      });
       const format = options.format ?? "text";
       steps.next();
       const specWarnings = specResult.diagnostics.filter((d) => d.severity === "warning");
@@ -1677,7 +1681,7 @@ function registerCheckCommand(program, dependencies = {}) {
       let typecheckErrors = [];
       let runtimeDrifts = [];
       if (hasExamples) {
-        const validation = await runExampleValidation(spec, {
+        const validation = await runExampleValidation(openpkg, {
           validations,
           targetDir
         });
@@ -1693,13 +1697,16 @@ function registerCheckCommand(program, dependencies = {}) {
       const staleRefs = await validateMarkdownDocs({
         docsPatterns,
         targetDir,
-        exportNames: (spec.exports ?? []).map((e) => e.name)
+        exportNames: (openpkg.exports ?? []).map((e) => e.name)
       });
-      const coverageScore = spec.docs?.coverageScore ?? 0;
-      const allDriftExports = [...collectDrift(spec.exports ?? []), ...runtimeDrifts];
+      const coverageScore = doccov.summary.score;
+      const allDriftExports = [
+        ...collectDrift(openpkg.exports ?? [], doccov),
+        ...runtimeDrifts
+      ];
       let driftExports = hasExamples ? allDriftExports : allDriftExports.filter((d) => d.category !== "example");
       if (shouldFix && driftExports.length > 0) {
-        const fixResult = await handleFixes(spec, { isPreview, targetDir }, { log, error });
+        const fixResult = await handleFixes(openpkg, doccov, { isPreview, targetDir }, { log, error });
         if (!isPreview) {
           driftExports = driftExports.filter((d) => !fixResult.fixedDriftKeys.has(`${d.name}:${d.issue}`));
         }
@@ -1708,8 +1715,8 @@ function registerCheckCommand(program, dependencies = {}) {
       if (format !== "text") {
         const passed2 = handleNonTextOutput({
           format,
-          spec,
-          rawSpec: specResult.spec,
+          openpkg,
+          doccov,
           coverageScore,
           minCoverage,
           maxDrift,
@@ -1726,7 +1733,8 @@ function registerCheckCommand(program, dependencies = {}) {
         return;
       }
       const passed = displayTextOutput({
-        spec,
+        openpkg,
+        doccov,
         coverageScore,
         minCoverage,
         maxDrift,
@@ -2131,7 +2139,7 @@ function printGitHubAnnotations(diff, log) {
 }
 
 // src/commands/info.ts
-import { DocCov as DocCov2, enrichSpec as enrichSpec2, NodeFileSystem as NodeFileSystem2, resolveTarget as resolveTarget2 } from "@doccov/sdk";
+import { buildDocCovSpec as buildDocCovSpec2, DocCov as DocCov2, NodeFileSystem as NodeFileSystem2, resolveTarget as resolveTarget2 } from "@doccov/sdk";
 import chalk8 from "chalk";
 function registerInfoCommand(program) {
   program.command("info [entry]").description("Show brief documentation coverage summary").option("--cwd <dir>", "Working directory", process.cwd()).option("--package <name>", "Target package name (for monorepos)").option("--skip-resolve", "Skip external type resolution from node_modules").action(async (entry, options) => {
@@ -2142,17 +2150,22 @@ function registerInfoCommand(program) {
         package: options.package,
         entry
       });
-      const { entryFile } = resolved;
+      const { entryFile, targetDir } = resolved;
       const resolveExternalTypes = !options.skipResolve;
-      const doccov = new DocCov2({
+      const analyzer = new DocCov2({
         resolveExternalTypes
       });
-      const specResult = await doccov.analyzeFileWithDiagnostics(entryFile);
+      const specResult = await analyzer.analyzeFileWithDiagnostics(entryFile);
       if (!specResult) {
         throw new Error("Failed to analyze documentation coverage.");
       }
-      const spec = enrichSpec2(specResult.spec);
-      const stats = computeStats(spec);
+      const openpkg = specResult.spec;
+      const doccov = buildDocCovSpec2({
+        openpkg,
+        openpkgPath: entryFile,
+        packagePath: targetDir
+      });
+      const stats = computeStats(openpkg, doccov);
       console.log("");
       console.log(chalk8.bold(`${stats.packageName}@${stats.version}`));
       console.log("");
@@ -2353,7 +2366,7 @@ var detectRepoInfo = (cwd, fileExists2, readFileSync4) => {
 import * as fs6 from "node:fs";
 import * as path8 from "node:path";
 import {
-  buildDocCovSpec,
+  buildDocCovSpec as buildDocCovSpec3,
   DocCov as DocCov3,
   detectPackageManager,
   NodeFileSystem as NodeFileSystem3,
@@ -2364,7 +2377,7 @@ import { validateDocCovSpec } from "@doccov/spec";
 import { normalize, validateSpec } from "@openpkg-ts/spec";
 import chalk10 from "chalk";
 // package.json
-var version = "0.24.0";
+var version = "0.24.1";
 
 // src/commands/spec.ts
 var defaultDependencies4 = {
@@ -2467,7 +2480,7 @@ function registerSpecCommand(program, dependencies = {}) {
       steps.next();
       let doccovSpec = null;
       if (!options.openpkgOnly) {
-        doccovSpec = buildDocCovSpec({
+        doccovSpec = buildDocCovSpec3({
           openpkgPath: "openpkg.json",
           openpkg: normalized,
           packagePath: targetDir

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/cli",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "DocCov CLI - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -48,7 +48,7 @@
   "dependencies": {
     "@ai-sdk/anthropic": "^1.0.0",
     "@ai-sdk/openai": "^1.0.0",
-    "@doccov/sdk": "^0.24.1",
+    "@doccov/sdk": "^0.25.0",
     "@doccov/spec": "^0.24.1",
     "@inquirer/prompts": "^7.8.0",
     "@openpkg-ts/spec": "^0.11.1",