@chappibunny/repolens 1.11.0 → 1.12.0

package/src/docs/generate-doc-set.js

@@ -5,6 +5,9 @@ import { inferDataFlows } from "../analyzers/flow-inference.js";
 import { analyzeGraphQL } from "../analyzers/graphql-analyzer.js";
 import { analyzeTypeScript } from "../analyzers/typescript-analyzer.js";
 import { analyzeDependencyGraph } from "../analyzers/dependency-graph.js";
+import { analyzeJSDoc } from "../analyzers/jsdoc-analyzer.js";
+import { analyzeSecurityPatterns } from "../analyzers/security-patterns.js";
+import { analyzeComplexity, computeCodeHealth } from "../analyzers/complexity-analyzer.js";
 import { buildSnapshot, loadBaseline, saveBaseline, detectDrift } from "../analyzers/drift-detector.js";
 import { parseCodeowners, buildOwnershipMap } from "../analyzers/codeowners.js";
 import { getActiveDocuments } from "../ai/document-plan.js";
@@ -25,7 +28,9 @@ import {
   renderGraphQLSchema,
   renderTypeGraph,
   renderDependencyGraph,
-  renderArchitectureDrift as renderDriftReport
+  renderArchitectureDrift as renderDriftReport,
+  renderCodeHealth,
+  renderSecurityHotspots
 } from "../renderers/renderAnalysis.js";
 import { info, warn } from "../utils/logger.js";
 import path from "node:path";
@@ -46,9 +51,15 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   let graphqlResult = { detected: false };
   let tsResult = { detected: false };
   let depGraph = { stats: {}, graph: {} };
+  let jsdocResult = { detected: false, exports: [], summary: null };
   try { graphqlResult = await analyzeGraphQL(scanFiles, repoRoot); } catch (e) { warn(`GraphQL analysis failed: ${e.message}`); }
   try { tsResult = await analyzeTypeScript(scanFiles, repoRoot); } catch (e) { warn(`TypeScript analysis failed: ${e.message}`); }
   try { depGraph = await analyzeDependencyGraph(scanFiles, repoRoot); } catch (e) { warn(`Dependency graph analysis failed: ${e.message}`); }
+  try { jsdocResult = await analyzeJSDoc(scanFiles, repoRoot); } catch (e) { warn(`JSDoc analysis failed: ${e.message}`); }
+  let securityResult = { detected: false, findings: [], bySeverity: { high: 0, medium: 0, low: 0 } };
+  try { securityResult = await analyzeSecurityPatterns(scanFiles, repoRoot); } catch (e) { warn(`Security pattern analysis failed: ${e.message}`); }
+  let complexityResult = { files: [], functions: [], filesAnalyzed: 0 };
+  try { complexityResult = await analyzeComplexity(scanFiles, repoRoot); } catch (e) { warn(`Complexity analysis failed: ${e.message}`); }
   
   // Architecture drift detection
   const outputDir = path.join(repoRoot, ".repolens");
@@ -73,6 +84,10 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   const ownershipMap = codeowners.found
     ? buildOwnershipMap(scanResult.modules, scanFiles, codeowners.rules)
     : {};
+
+  // Compute unified code health scores (synthesizes complexity + coupling + docs + security)
+  let codeHealthResult = { modules: [], summary: "No health data", stats: { totalFiles: 0, avgScore: 100, avgComplexity: 0, gradeDistribution: { A: 0, B: 0, C: 0, D: 0, F: 0 } }, hotspots: [], topComplexFunctions: [] };
+  try { codeHealthResult = computeCodeHealth(complexityResult, depGraph, jsdocResult, securityResult); } catch (e) { warn(`Code health computation failed: ${e.message}`); }
   
   // Get active documents based on config
   const activeDocuments = getActiveDocuments(config);
@@ -86,8 +101,11 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
     flows,
     graphql: graphqlResult.detected ? graphqlResult : undefined,
     typescript: tsResult.detected ? tsResult : undefined,
+    jsdoc: jsdocResult.detected ? jsdocResult : undefined,
     dependencyGraph: depGraph.stats,
     drift: driftResult,
+    security: securityResult.detected ? securityResult : undefined,
+    codeHealth: complexityResult.files.length > 0 ? true : undefined,
     codeowners: codeowners.found ? { file: codeowners.file, ruleCount: codeowners.rules.length } : undefined,
     ownershipMap: Object.keys(ownershipMap).length > 0 ? ownershipMap : undefined,
   };
@@ -117,8 +135,11 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
         diffData,
         graphqlResult,
         tsResult,
+        jsdocResult,
         depGraph,
         driftResult,
+        securityResult,
+        codeHealthResult,
         ownershipMap,
         pluginManager,
       });
@@ -167,8 +188,11 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
           diffData,
           graphqlResult,
           tsResult,
+          jsdocResult,
           depGraph,
           driftResult,
+          securityResult,
+          codeHealthResult,
         });
 
         documents.push({
@@ -203,7 +227,7 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
 
 async function generateDocument(docPlan, context) {
   const { key } = docPlan;
-  const { scanResult, config, aiContext, moduleContext, flows, diffData, graphqlResult, tsResult, depGraph, driftResult, ownershipMap, pluginManager } = context;
+  const { scanResult, config, aiContext, moduleContext, flows, diffData, graphqlResult, tsResult, jsdocResult, depGraph, driftResult, securityResult, codeHealthResult, ownershipMap, pluginManager } = context;
   
   switch (key) {
     case "executive_summary":
@@ -227,8 +251,8 @@ async function generateDocument(docPlan, context) {
       return renderRouteMapOriginal(config, scanResult, aiContext);
       
     case "api_surface":
-      // Hybrid: deterministic skeleton + AI enhancement (for now, just deterministic)
-      return renderApiSurfaceOriginal(config, scanResult);
+      // Hybrid: deterministic skeleton + JSDoc documentation
+      return renderApiSurfaceOriginal(config, scanResult, jsdocResult);
       
     case "data_flows":
       return await generateDataFlows(flows, aiContext, { depGraph, scanResult, moduleContext }, config);
@@ -258,6 +282,12 @@ async function generateDocument(docPlan, context) {
     case "architecture_drift":
       return renderDriftReport(driftResult);
       
+    case "security_hotspots":
+      return renderSecurityHotspots(securityResult);
+      
+    case "code_health":
+      return renderCodeHealth(codeHealthResult);
+      
     default: {
       // Check if a plugin provides this renderer
       if (pluginManager) {

package/src/publishers/github-wiki.js

@@ -37,6 +37,8 @@ const PAGE_ORDER = [
   "dependency_graph",
   "architecture_drift",
   "arch_diff",
+  "security_hotspots",
+  "code_health",
 ];
 
 const PAGE_TITLES = {
@@ -56,6 +58,8 @@ const PAGE_TITLES = {
   dependency_graph: "Dependency Graph",
   architecture_drift: "Architecture Drift",
   arch_diff: "Architecture Diff",
+  security_hotspots: "Security Hotspots",
+  code_health: "Code Health",
 };
 
 const PAGE_DESCRIPTIONS = {
@@ -75,6 +79,8 @@ const PAGE_DESCRIPTIONS = {
   dependency_graph: "Module and package dependency relationships.",
   architecture_drift: "Detected drift between intended and current architecture patterns.",
   arch_diff: "Architecture-level diff across branches or revisions.",
+  security_hotspots: "Security anti-patterns detected with CWE classification and severity ratings.",
+  code_health: "Cyclomatic complexity analysis with unified health scores per module.",
 };
 
 // Audience-based grouping for Home page
@@ -90,7 +96,7 @@ const AUDIENCE_GROUPS = [
     keys: [
       "architecture_overview", "module_catalog", "api_surface",
       "route_map", "system_map", "graphql_schema", "type_graph",
-      "dependency_graph", "architecture_drift",
+      "dependency_graph", "architecture_drift", "security_hotspots", "code_health",
     ],
   },
   {
@@ -120,6 +126,7 @@ const SIDEBAR_GROUPS = [
       "architecture_overview", "module_catalog", "route_map",
       "api_surface", "system_map", "graphql_schema", "type_graph",
       "dependency_graph", "architecture_drift", "arch_diff", "change_impact",
+      "security_hotspots", "code_health",
     ],
   },
 ];
@@ -142,6 +149,8 @@ const PAGE_AUDIENCE = {
   dependency_graph: "Engineers",
   architecture_drift: "Engineers · Tech Leads",
   arch_diff: "Engineers · Tech Leads",
+  security_hotspots: "Engineers · Security",
+  code_health: "All Audiences",
 };
 
 /**

package/src/publishers/markdown.js

@@ -22,7 +22,9 @@ function pageFileName(key) {
     graphql_schema: "graphql_schema.md",
     type_graph: "type_graph.md",
     dependency_graph: "dependency_graph.md",
-    architecture_drift: "architecture_drift.md"
+    architecture_drift: "architecture_drift.md",
+    security_hotspots: "security_hotspots.md",
+    code_health: "code_health.md"
   };
 
   return mapping[key] || `${key}.md`;

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",