@doccov/cli 0.15.1 → 0.16.0

package/dist/cli.js

@@ -557,6 +557,205 @@ function renderHtml(stats, options = {}) {
 </body>
 </html>`;
 }
+// src/reports/pr-comment.ts
+function renderPRComment(data, opts = {}) {
+  const { diff, headSpec } = data;
+  const limit = opts.limit ?? 10;
+  const lines = [];
+  const hasIssues = diff.newUndocumented.length > 0 || diff.driftIntroduced > 0 || diff.breaking.length > 0 || opts.minCoverage !== undefined && diff.newCoverage < opts.minCoverage;
+  const statusIcon = hasIssues ? diff.coverageDelta < 0 ? "❌" : "⚠️" : "✅";
+  lines.push(`## ${statusIcon} DocCov — Documentation Coverage`);
+  lines.push("");
+  const targetStr = opts.minCoverage !== undefined ? ` (target: ${opts.minCoverage}%) ${diff.newCoverage >= opts.minCoverage ? "✅" : "❌"}` : "";
+  lines.push(`**Patch coverage:** ${diff.newCoverage}%${targetStr}`);
+  if (diff.newUndocumented.length > 0) {
+    lines.push(`**New undocumented exports:** ${diff.newUndocumented.length}`);
+  }
+  if (diff.driftIntroduced > 0) {
+    lines.push(`**Doc drift issues:** ${diff.driftIntroduced}`);
+  }
+  if (diff.newUndocumented.length > 0) {
+    lines.push("");
+    lines.push("### Undocumented exports in this PR");
+    lines.push("");
+    renderUndocumentedExports(lines, diff.newUndocumented, headSpec, opts, limit);
+  }
+  if (diff.driftIntroduced > 0 && headSpec) {
+    lines.push("");
+    lines.push("### Doc drift detected");
+    lines.push("");
+    renderDriftIssues(lines, diff.newUndocumented, headSpec, opts, limit);
+  }
+  const fixGuidance = renderFixGuidance(diff);
+  if (fixGuidance) {
+    lines.push("");
+    lines.push("### How to fix");
+    lines.push("");
+    lines.push(fixGuidance);
+  }
+  lines.push("");
+  lines.push("<details>");
+  lines.push("<summary>View full report</summary>");
+  lines.push("");
+  renderDetailsTable(lines, diff);
+  lines.push("");
+  lines.push("</details>");
+  return lines.join(`
+`);
+}
+function renderUndocumentedExports(lines, undocumented, headSpec, opts, limit) {
+  if (!headSpec) {
+    for (const name of undocumented.slice(0, limit)) {
+      lines.push(`- \`${name}\``);
+    }
+    if (undocumented.length > limit) {
+      lines.push(`- _...and ${undocumented.length - limit} more_`);
+    }
+    return;
+  }
+  const byFile = new Map;
+  const undocSet = new Set(undocumented);
+  for (const exp of headSpec.exports) {
+    if (undocSet.has(exp.name)) {
+      const file = exp.source?.file ?? "unknown";
+      const list = byFile.get(file) ?? [];
+      list.push(exp);
+      byFile.set(file, list);
+    }
+  }
+  let count = 0;
+  for (const [file, exports] of byFile) {
+    if (count >= limit)
+      break;
+    const fileLink = buildFileLink(file, opts);
+    lines.push(`\uD83D\uDCC1 ${fileLink}`);
+    for (const exp of exports) {
+      if (count >= limit) {
+        lines.push(`- _...and more_`);
+        break;
+      }
+      const sig = formatExportSignature(exp);
+      lines.push(`- \`${sig}\``);
+      const missing = getMissingSignals(exp);
+      if (missing.length > 0) {
+        lines.push(`  - Missing: ${missing.join(", ")}`);
+      }
+      count++;
+    }
+    lines.push("");
+  }
+  if (undocumented.length > count) {
+    lines.push(`_...and ${undocumented.length - count} more undocumented exports_`);
+  }
+}
+function renderDriftIssues(lines, _undocumented, headSpec, 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
+        });
+      }
+    }
+  }
+  if (driftIssues.length === 0) {
+    lines.push("_No specific drift details available_");
+    return;
+  }
+  for (const issue of driftIssues.slice(0, limit)) {
+    const fileRef = issue.file ? `\`${issue.file}\`` : "unknown file";
+    const fileLink = issue.file ? buildFileLink(issue.file, opts) : fileRef;
+    lines.push(`⚠️ ${fileLink}: \`${issue.exportName}\``);
+    lines.push(`- ${issue.drift.issue}`);
+    if (issue.drift.suggestion) {
+      lines.push(`- Fix: ${issue.drift.suggestion}`);
+    }
+    lines.push("");
+  }
+  if (driftIssues.length > limit) {
+    lines.push(`_...and ${driftIssues.length - limit} more drift issues_`);
+  }
+}
+function buildFileLink(file, opts) {
+  if (opts.repoUrl && opts.sha) {
+    const url = `${opts.repoUrl}/blob/${opts.sha}/${file}`;
+    return `[\`${file}\`](${url})`;
+  }
+  return `\`${file}\``;
+}
+function formatExportSignature(exp) {
+  const prefix = `export ${exp.kind === "type" ? "type" : exp.kind === "interface" ? "interface" : exp.kind === "class" ? "class" : "function"}`;
+  if (exp.kind === "function" && exp.signatures?.[0]) {
+    const sig = exp.signatures[0];
+    const params = sig.parameters?.map((p) => `${p.name}${p.required === false ? "?" : ""}`).join(", ") ?? "";
+    const ret = sig.returns?.tsType ?? "void";
+    return `${prefix} ${exp.name}(${params}): ${ret}`;
+  }
+  if (exp.kind === "type" || exp.kind === "interface") {
+    return `${prefix} ${exp.name}`;
+  }
+  if (exp.kind === "class") {
+    return `${prefix} ${exp.name}`;
+  }
+  return `export ${exp.kind} ${exp.name}`;
+}
+function getMissingSignals(exp) {
+  const missing = [];
+  if (!exp.description) {
+    missing.push("description");
+  }
+  if (exp.kind === "function" && exp.signatures?.[0]) {
+    const sig = exp.signatures[0];
+    const undocParams = sig.parameters?.filter((p) => !p.description) ?? [];
+    if (undocParams.length > 0) {
+      missing.push(`\`@param ${undocParams.map((p) => p.name).join(", ")}\``);
+    }
+    if (!sig.returns?.description && sig.returns?.tsType !== "void") {
+      missing.push("`@returns`");
+    }
+  }
+  return missing;
+}
+function renderFixGuidance(diff) {
+  const sections = [];
+  if (diff.newUndocumented.length > 0) {
+    sections.push(`**For undocumented exports:**
+` + "Add JSDoc/TSDoc blocks with description, `@param`, and `@returns` tags.");
+  }
+  if (diff.driftIntroduced > 0) {
+    sections.push(`**For doc drift:**
+` + "Update the code examples in your markdown files to match current signatures.");
+  }
+  if (diff.breaking.length > 0) {
+    sections.push(`**For breaking changes:**
+` + "Consider adding a migration guide or updating changelog.");
+  }
+  if (sections.length === 0) {
+    return "";
+  }
+  sections.push(`
+Push your changes — DocCov re-checks automatically.`);
+  return sections.join(`
+
+`);
+}
+function renderDetailsTable(lines, diff) {
+  const delta = (n) => n > 0 ? `+${n}` : n === 0 ? "0" : String(n);
+  lines.push("| Metric | Before | After | Delta |");
+  lines.push("|--------|--------|-------|-------|");
+  lines.push(`| Coverage | ${diff.oldCoverage}% | ${diff.newCoverage}% | ${delta(diff.coverageDelta)}% |`);
+  lines.push(`| Breaking changes | - | ${diff.breaking.length} | - |`);
+  lines.push(`| New exports | - | ${diff.nonBreaking.length} | - |`);
+  lines.push(`| Undocumented | - | ${diff.newUndocumented.length} | - |`);
+  if (diff.driftIntroduced > 0 || diff.driftResolved > 0) {
+    const driftDelta = diff.driftIntroduced - diff.driftResolved;
+    lines.push(`| Drift | - | - | ${delta(driftDelta)} |`);
+  }
+}
 // src/reports/stats.ts
 import { isFixableDrift } from "@doccov/sdk";
 import {
@@ -1308,7 +1507,7 @@ function registerDiffCommand(program, dependencies = {}) {
     ...defaultDependencies2,
     ...dependencies
   };
-  program.command("diff [base] [head]").description("Compare two OpenPkg specs and detect breaking changes").option("--base <file>", 'Base spec file (the "before" state)').option("--head <file>", 'Head spec file (the "after" state)').option("--format <format>", "Output format: text, json, markdown, html, github", "text").option("--stdout", "Output to stdout instead of writing to .doccov/").option("-o, --output <file>", "Custom output path").option("--cwd <dir>", "Working directory", process.cwd()).option("--limit <n>", "Max items to show in terminal/reports", "10").option("--min-coverage <n>", "Minimum coverage % for HEAD spec (0-100)").option("--max-drift <n>", "Maximum drift % for HEAD spec (0-100)").option("--strict <preset>", "Fail on conditions: ci, release, quality").option("--docs <glob>", "Glob pattern for markdown docs to check for impact", collect, []).option("--ai", "Use AI for deeper analysis and fix suggestions").option("--no-cache", "Bypass cache and force regeneration").action(async (baseArg, headArg, options) => {
+  program.command("diff [base] [head]").description("Compare two OpenPkg specs and detect breaking changes").option("--base <file>", 'Base spec file (the "before" state)').option("--head <file>", 'Head spec file (the "after" state)').option("--format <format>", "Output format: text, json, markdown, html, github, pr-comment", "text").option("--stdout", "Output to stdout instead of writing to .doccov/").option("-o, --output <file>", "Custom output path").option("--cwd <dir>", "Working directory", process.cwd()).option("--limit <n>", "Max items to show in terminal/reports", "10").option("--repo-url <url>", "GitHub repo URL for file links (pr-comment format)").option("--sha <sha>", "Commit SHA for file links (pr-comment format)").option("--min-coverage <n>", "Minimum coverage % for HEAD spec (0-100)").option("--max-drift <n>", "Maximum drift % for HEAD spec (0-100)").option("--strict <preset>", "Fail on conditions: ci, release, quality").option("--docs <glob>", "Glob pattern for markdown docs to check for impact", collect, []).option("--ai", "Use AI for deeper analysis and fix suggestions").option("--no-cache", "Bypass cache and force regeneration").action(async (baseArg, headArg, options) => {
     try {
       const baseFile = options.base ?? baseArg;
       const headFile = options.head ?? headArg;
@@ -1418,6 +1617,16 @@ function registerDiffCommand(program, dependencies = {}) {
         case "github":
           printGitHubAnnotations(diff, log);
           break;
+        case "pr-comment": {
+          const content = renderPRComment({ diff, baseName, headName, headSpec }, {
+            repoUrl: options.repoUrl,
+            sha: options.sha,
+            minCoverage,
+            limit
+          });
+          log(content);
+          break;
+        }
       }
       const failures = validateDiff(diff, headSpec, {
         minCoverage,
@@ -1813,7 +2022,7 @@ import { DocCov as DocCov3, NodeFileSystem as NodeFileSystem3, resolveTarget as
 import { normalize, validateSpec } from "@openpkg-ts/spec";
 import chalk8 from "chalk";
 // package.json
-var version = "0.15.0";
+var version = "0.15.1";
 
 // src/utils/filter-options.ts
 import { mergeFilters, parseListFlag } from "@doccov/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/cli",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "DocCov CLI - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",