@doccov/cli 0.15.1 → 0.17.0

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 // src/config/doccov-config.ts
-import { access } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { parse as parseYaml } from "yaml";
 
 // src/config/schema.ts
 import { z } from "zod";
@@ -95,7 +96,9 @@ var DOCCOV_CONFIG_FILENAMES = [
   "doccov.config.cts",
   "doccov.config.js",
   "doccov.config.mjs",
-  "doccov.config.cjs"
+  "doccov.config.cjs",
+  "doccov.yml",
+  "doccov.yaml"
 ];
 var fileExists = async (filePath) => {
   try {
@@ -122,6 +125,11 @@ var findConfigFile = async (cwd) => {
   }
 };
 var importConfigModule = async (absolutePath) => {
+  const ext = path.extname(absolutePath);
+  if (ext === ".yml" || ext === ".yaml") {
+    const content = await readFile(absolutePath, "utf-8");
+    return parseYaml(content);
+  }
   const fileUrl = pathToFileURL(absolutePath);
   fileUrl.searchParams.set("t", Date.now().toString());
   const module = await import(fileUrl.href);
@@ -557,6 +565,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 +1515,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 +1625,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,
@@ -1669,11 +1886,11 @@ function registerInitCommand(program, dependencies = {}) {
     ...defaultDependencies3,
     ...dependencies
   };
-  program.command("init").description("Create a DocCov configuration file").option("--cwd <dir>", "Working directory", process.cwd()).option("--format <format>", "Config format: auto, mjs, js, cjs", "auto").action((options) => {
+  program.command("init").description("Create a DocCov configuration file").option("--cwd <dir>", "Working directory", process.cwd()).option("--format <format>", "Config format: auto, mjs, js, cjs, yaml", "auto").action((options) => {
     const cwd = path6.resolve(options.cwd);
     const formatOption = String(options.format ?? "auto").toLowerCase();
     if (!isValidFormat(formatOption)) {
-      error(chalk6.red(`Invalid format "${formatOption}". Use auto, mjs, js, or cjs.`));
+      error(chalk6.red(`Invalid format "${formatOption}". Use auto, mjs, js, cjs, or yaml.`));
       process.exitCode = 1;
       return;
     }
@@ -1688,7 +1905,7 @@ function registerInitCommand(program, dependencies = {}) {
     if (targetFormat === "js" && packageType !== "module") {
       log(chalk6.yellow('Package is not marked as "type": "module"; creating doccov.config.js may require enabling ESM.'));
     }
-    const fileName = `doccov.config.${targetFormat}`;
+    const fileName = targetFormat === "yaml" ? "doccov.yml" : `doccov.config.${targetFormat}`;
     const outputPath = path6.join(cwd, fileName);
     if (fileExists2(outputPath)) {
       error(chalk6.red(`Cannot create ${fileName}; file already exists.`));
@@ -1701,7 +1918,7 @@ function registerInitCommand(program, dependencies = {}) {
   });
 }
 var isValidFormat = (value) => {
-  return value === "auto" || value === "mjs" || value === "js" || value === "cjs";
+  return ["auto", "mjs", "js", "cjs", "yaml"].includes(value);
 };
 var findExistingConfig = (cwd, fileExists2) => {
   let current = path6.resolve(cwd);
@@ -1753,12 +1970,34 @@ var findNearestPackageJson = (cwd, fileExists2) => {
   return null;
 };
 var resolveFormat = (format, packageType) => {
+  if (format === "yaml")
+    return "yaml";
   if (format === "auto") {
     return packageType === "module" ? "js" : "mjs";
   }
   return format;
 };
 var buildTemplate = (format) => {
+  if (format === "yaml") {
+    return `# doccov.yml
+# include:
+#   - "MyClass"
+#   - "myFunction"
+# exclude:
+#   - "internal*"
+
+check:
+  # minCoverage: 80
+  # maxDrift: 20
+  # examples: typecheck
+
+quality:
+  rules:
+    # has-description: warn
+    # has-params: off
+    # has-returns: off
+`;
+  }
   const configBody = `{
   // Filter which exports to analyze
   // include: ['MyClass', 'myFunction'],
@@ -1813,7 +2052,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.16.0";
 
 // src/utils/filter-options.ts
 import { mergeFilters, parseListFlag } from "@doccov/sdk";

package/dist/config/index.d.ts

@@ -38,7 +38,7 @@ declare const docCovConfigSchema: z.ZodObject<{
 }>;
 type DocCovConfigInput = z.infer<typeof docCovConfigSchema>;
 type NormalizedDocCovConfig = DocCovConfig;
-declare const DOCCOV_CONFIG_FILENAMES: readonly ["doccov.config.ts", "doccov.config.mts", "doccov.config.cts", "doccov.config.js", "doccov.config.mjs", "doccov.config.cjs"];
+declare const DOCCOV_CONFIG_FILENAMES: readonly ["doccov.config.ts", "doccov.config.mts", "doccov.config.cts", "doccov.config.js", "doccov.config.mjs", "doccov.config.cjs", "doccov.yml", "doccov.yaml"];
 interface LoadedDocCovConfig extends NormalizedDocCovConfig {
 	filePath: string;
 }

package/dist/config/index.js

@@ -1,7 +1,8 @@
 // src/config/doccov-config.ts
-import { access } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { parse as parseYaml } from "yaml";
 
 // src/config/schema.ts
 import { z } from "zod";
@@ -93,7 +94,9 @@ var DOCCOV_CONFIG_FILENAMES = [
   "doccov.config.cts",
   "doccov.config.js",
   "doccov.config.mjs",
-  "doccov.config.cjs"
+  "doccov.config.cjs",
+  "doccov.yml",
+  "doccov.yaml"
 ];
 var fileExists = async (filePath) => {
   try {
@@ -120,6 +123,11 @@ var findConfigFile = async (cwd) => {
   }
 };
 var importConfigModule = async (absolutePath) => {
+  const ext = path.extname(absolutePath);
+  if (ext === ".yml" || ext === ".yaml") {
+    const content = await readFile(absolutePath, "utf-8");
+    return parseYaml(content);
+  }
   const fileUrl = pathToFileURL(absolutePath);
   fileUrl.searchParams.set("t", Date.now().toString());
   const module = await import(fileUrl.href);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/cli",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "DocCov CLI - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -56,6 +56,7 @@
     "commander": "^14.0.0",
     "glob": "^11.0.0",
     "simple-git": "^3.27.0",
+    "yaml": "^2.8.2",
     "zod": "^3.25.0"
   },
   "devDependencies": {