@chappibunny/repolens 1.10.0 → 1.12.0

package/src/renderers/render.js

@@ -215,7 +215,7 @@ export function renderModuleCatalog(cfg, scan, ownershipMap = {}, depGraph = nul
   return lines.join("\n");
 }
 
-export function renderApiSurface(cfg, scan) {
+export function renderApiSurface(cfg, scan, jsdocResult = null) {
   const lines = [
     `# API Surface`,
     ``,
@@ -286,6 +286,101 @@ export function renderApiSurface(cfg, scan) {
     }
   }
 
+  // Section 3: Documented Exports (from JSDoc analysis)
+  if (jsdocResult && jsdocResult.detected && jsdocResult.exports.length > 0) {
+    lines.push(
+      `---`,
+      ``,
+      `## Documented Exports`,
+      ``,
+      `Exported functions with JSDoc/TSDoc documentation. Documentation coverage: **${jsdocResult.summary?.coverage || "N/A"}**`,
+      ``
+    );
+
+    // Show deprecated functions first as warnings
+    if (jsdocResult.deprecated && jsdocResult.deprecated.length > 0) {
+      lines.push(`### ⚠️ Deprecated Functions`, ``);
+      for (const dep of jsdocResult.deprecated) {
+        lines.push(`- \`${dep.name}\` in \`${dep.source}\`: ${dep.reason}`);
+      }
+      lines.push(``);
+    }
+
+    // Group by file and show documented exports
+    const documentedExports = jsdocResult.exports.filter(e => e.jsdoc);
+    if (documentedExports.length > 0) {
+      lines.push(`### Function Documentation`, ``);
+      
+      // Group by file for better organization
+      const byFile = {};
+      for (const exp of documentedExports) {
+        if (!byFile[exp.source]) byFile[exp.source] = [];
+        byFile[exp.source].push(exp);
+      }
+
+      // Show up to 30 documented functions to avoid overwhelming output
+      let shown = 0;
+      const maxToShow = 30;
+      
+      for (const [file, exports] of Object.entries(byFile)) {
+        if (shown >= maxToShow) break;
+        
+        lines.push(`#### \`${file}\``, ``);
+        
+        for (const exp of exports) {
+          if (shown >= maxToShow) break;
+          shown++;
+          
+          const jsdoc = exp.jsdoc;
+          const isDeprecated = jsdoc.deprecated ? " ⚠️" : "";
+          
+          lines.push(`**\`${exp.name}()\`**${isDeprecated}`, ``);
+          
+          if (jsdoc.description) {
+            lines.push(jsdoc.description, ``);
+          }
+          
+          if (jsdoc.params.length > 0) {
+            lines.push(`**Parameters:**`);
+            for (const param of jsdoc.params) {
+              const opt = param.optional ? " *(optional)*" : "";
+              lines.push(`- \`${param.name}\` (\`${param.type}\`)${opt}${param.description ? `: ${param.description}` : ""}`);
+            }
+            lines.push(``);
+          }
+          
+          if (jsdoc.returns) {
+            lines.push(`**Returns:** \`${jsdoc.returns.type}\`${jsdoc.returns.description ? ` — ${jsdoc.returns.description}` : ""}`, ``);
+          }
+          
+          if (jsdoc.throws.length > 0) {
+            lines.push(`**Throws:**`);
+            for (const t of jsdoc.throws) {
+              lines.push(`- ${t}`);
+            }
+            lines.push(``);
+          }
+        }
+      }
+
+      if (documentedExports.length > maxToShow) {
+        lines.push(``, `> *Showing ${maxToShow} of ${documentedExports.length} documented exports.*`, ``);
+      }
+    }
+
+    // Summary stats
+    lines.push(
+      `---`,
+      ``,
+      `**Documentation Summary:**`,
+      `- Total exports: ${jsdocResult.summary?.totalExports || 0}`,
+      `- Documented: ${jsdocResult.summary?.documented || 0}`,
+      `- Undocumented: ${jsdocResult.summary?.undocumented || 0}`,
+      `- Coverage: ${jsdocResult.summary?.coverage || "0%"}`,
+      ``
+    );
+  }
+
   lines.push(
     `---`,
     ``,

package/src/renderers/renderAnalysis.js

@@ -494,6 +494,190 @@ export function renderArchitectureDrift(driftResult) {
   return lines.join("\n");
 }
 
+export function renderCodeHealth(healthResult) {
+  if (!healthResult?.modules?.length) {
+    return [
+      "# Code Health Report",
+      "",
+      "> No source files were available for health analysis.",
+      "",
+      "RepoLens computes a health score (0–100) per module by synthesizing cyclomatic complexity, coupling (fan-in × fan-out), documentation coverage, and security findings. Ensure your `scan.include` patterns cover the relevant source directories.",
+      ""
+    ].join("\n");
+  }
+
+  const lines = [];
+  const { stats, hotspots, topComplexFunctions, modules } = healthResult;
+
+  lines.push("# Code Health Report");
+  lines.push("");
+  lines.push(`> ${healthResult.summary}`);
+  lines.push("");
+  lines.push("This report synthesizes complexity, coupling, documentation, and security signals into a single health score per module. Lower scores indicate higher risk and maintenance burden.");
+  lines.push("");
+
+  // Overall stats
+  lines.push("## Overview");
+  lines.push("");
+  lines.push("| Metric | Value |");
+  lines.push("|--------|-------|");
+  lines.push(`| Files analyzed | ${stats.totalFiles} |`);
+  lines.push(`| Average health score | ${stats.avgScore}/100 |`);
+  lines.push(`| Average complexity | ${stats.avgComplexity} |`);
+  lines.push(`| Hotspots (score < 60) | ${hotspots.length} |`);
+  lines.push("");
+
+  // Grade distribution
+  lines.push("## Grade Distribution");
+  lines.push("");
+  lines.push("| Grade | Count | Meaning |");
+  lines.push("|-------|-------|---------|");
+  lines.push(`| 🟢 A (80–100) | ${stats.gradeDistribution.A} | Healthy — low complexity, well-documented |`);
+  lines.push(`| 🔵 B (60–79) | ${stats.gradeDistribution.B} | Acceptable — minor improvements possible |`);
+  lines.push(`| 🟡 C (40–59) | ${stats.gradeDistribution.C} | Needs attention — elevated complexity or coupling |`);
+  lines.push(`| 🟠 D (20–39) | ${stats.gradeDistribution.D} | At risk — multiple quality signals degraded |`);
+  lines.push(`| 🔴 F (0–19) | ${stats.gradeDistribution.F} | Critical — immediate refactoring recommended |`);
+  lines.push("");
+
+  // Hotspots (worst modules)
+  if (hotspots.length > 0) {
+    lines.push("## Hotspots — Priority Refactoring Targets");
+    lines.push("");
+    lines.push("These modules have the lowest health scores and should be prioritized for improvement:");
+    lines.push("");
+    lines.push("| Module | Score | Grade | Complexity | Coupling | Doc% | Security |");
+    lines.push("|--------|-------|-------|------------|----------|------|----------|");
+    for (const m of hotspots) {
+      const gradeIcon = m.grade === "C" ? "🟡" : m.grade === "D" ? "🟠" : "🔴";
+      const docCol = m.docCoverage !== null ? `${m.docCoverage}%` : "—";
+      const secCol = m.securityFindings > 0 ? `${m.securityFindings} (${m.highSecurityFindings} high)` : "—";
+      lines.push(`| \`${m.file}\` | ${m.score} | ${gradeIcon} ${m.grade} | ${m.complexity} | ${m.fanIn}↓ ${m.fanOut}↑ | ${docCol} | ${secCol} |`);
+    }
+    lines.push("");
+  }
+
+  // Most complex functions
+  if (topComplexFunctions.length > 0) {
+    lines.push("## Most Complex Functions");
+    lines.push("");
+    lines.push("These functions have the highest cyclomatic complexity and are the most likely sources of bugs:");
+    lines.push("");
+    lines.push("| Function | File | Line | Complexity |");
+    lines.push("|----------|------|------|------------|");
+    for (const fn of topComplexFunctions) {
+      lines.push(`| \`${fn.name}()\` | \`${fn.file}\` | ${fn.line} | ${fn.complexity} |`);
+    }
+    lines.push("");
+  }
+
+  // Full module listing (top 50, sorted by score)
+  const displayModules = modules.slice(0, 50);
+  lines.push("## All Modules by Health Score");
+  lines.push("");
+  if (modules.length > 50) {
+    lines.push(`*Showing 50 of ${modules.length} modules (sorted worst-first)*`);
+    lines.push("");
+  }
+  lines.push("| Module | Score | Grade | Lines | Complexity | Fan-In | Fan-Out |");
+  lines.push("|--------|-------|-------|-------|------------|--------|---------|");
+  for (const m of displayModules) {
+    const gradeIcon = m.grade === "A" ? "🟢" : m.grade === "B" ? "🔵" : m.grade === "C" ? "🟡" : m.grade === "D" ? "🟠" : "🔴";
+    lines.push(`| \`${m.file}\` | ${m.score} | ${gradeIcon} ${m.grade} | ${m.lines} | ${m.complexity} | ${m.fanIn} | ${m.fanOut} |`);
+  }
+  lines.push("");
+
+  // Scoring methodology
+  lines.push("## Scoring Methodology");
+  lines.push("");
+  lines.push("The health score (0–100) is computed from four dimensions:");
+  lines.push("");
+  lines.push("| Factor | Weight | How It's Measured |");
+  lines.push("|--------|--------|-------------------|");
+  lines.push("| Complexity | –1/pt above 10, –2/pt above 30 | Cyclomatic complexity (if/else/for/while/case/&&/\\|\\|/ternary) |");
+  lines.push("| Function complexity | –2/pt above 8 per function | Highest complexity function in the file |");
+  lines.push("| Coupling | –1/5 units above 20 | Fan-in × Fan-out (import connections) |");
+  lines.push("| Documentation | –10 if <50%, –5 if <80% | JSDoc/TSDoc coverage of exports |");
+  lines.push("| Security | –10/high, –5/medium finding | Security anti-pattern findings in file |");
+  lines.push("");
+
+  lines.push("---");
+  lines.push("");
+  lines.push("*Generated by RepoLens code health analysis. Complexity is regex-based and may differ from AST-based tools. Scores are relative indicators, not absolute quality measures.*");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export function renderSecurityHotspots(secResult) {
+  if (!secResult?.detected) {
+    return [
+      "# Security Hotspots",
+      "",
+      "> No security anti-patterns were detected in the scanned source files.",
+      "",
+      "RepoLens scans JavaScript and TypeScript source files for common security risks including code injection (`eval`), XSS (`innerHTML`), SQL injection, command injection, prototype pollution, hardcoded credentials, and insecure randomness.",
+      "",
+      "Test files, configs, and build outputs are excluded from analysis to reduce false positives.",
+      ""
+    ].join("\n");
+  }
+
+  const lines = [];
+  lines.push("# Security Hotspots");
+  lines.push("");
+  lines.push(`> ${secResult.summary}`);
+  lines.push("");
+  lines.push("This report identifies code patterns that are commonly associated with security vulnerabilities. Each finding includes the relevant CWE classification and a recommended remediation.");
+  lines.push("");
+
+  // Severity summary
+  lines.push("## Severity Overview");
+  lines.push("");
+  lines.push("| Severity | Count |");
+  lines.push("|----------|-------|");
+  if (secResult.bySeverity.high > 0) lines.push(`| 🔴 High | ${secResult.bySeverity.high} |`);
+  if (secResult.bySeverity.medium > 0) lines.push(`| 🟡 Medium | ${secResult.bySeverity.medium} |`);
+  if (secResult.bySeverity.low > 0) lines.push(`| 🔵 Low | ${secResult.bySeverity.low} |`);
+  lines.push("");
+  lines.push(`**${secResult.filesScanned}** source files scanned · **${secResult.filesWithFindingsCount || secResult.filesWithFindings?.length || 0}** files with findings`);
+  lines.push("");
+
+  // Findings by category
+  const categories = Object.keys(secResult.byCategory);
+  for (const category of categories) {
+    const findings = secResult.byCategory[category];
+    lines.push(`## ${category}`);
+    lines.push("");
+    // Use description from first finding as category overview
+    lines.push(`> ${findings[0].description}`);
+    lines.push("");
+    lines.push("| File | Line | Pattern | Severity | CWE |");
+    lines.push("|------|------|---------|----------|-----|");
+    for (const f of findings) {
+      const sev = f.severity === "high" ? "🔴 High" : f.severity === "medium" ? "🟡 Medium" : "🔵 Low";
+      lines.push(`| \`${f.file}\` | ${f.line} | ${f.name} | ${sev} | ${f.cwe} |`);
+    }
+    lines.push("");
+  }
+
+  // Affected files list
+  if (secResult.filesWithFindings?.length > 0) {
+    lines.push("## Affected Files");
+    lines.push("");
+    for (const file of secResult.filesWithFindings) {
+      lines.push(`- \`${file}\``);
+    }
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("");
+  lines.push("*Generated by RepoLens security pattern analysis. Detection is regex-based and may produce false positives. Findings should be triaged by a security-aware engineer.*");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
 function formatCategoryLabel(category) {
   const labels = {
     modules: "Modules",