@chappibunny/repolens 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.12.0
+
+### 🛡️ Security Pattern Detection
+
+New static analysis for security anti-patterns with CWE classification:
+
+- **16 anti-patterns** across 8 categories: Code Injection (eval), XSS (innerHTML), SQL Injection, Command Injection, Path Traversal, Prototype Pollution, Hardcoded Credentials, Insecure Randomness, ReDoS
+- Each finding includes severity (high/medium/low), file location, code snippet, and CWE ID
+- New renderer: `renderSecurityHotspots()` with severity breakdown, category grouping, and remediation guidance
+- New document type: **Security Hotspots** (`security_hotspots`)
+- Skips test files, build outputs, configs, `.min.js`, `.d.ts` to reduce noise
+- 30 new tests in `security-patterns.test.js`
+
+### 📊 Complexity & Code Health Scoring
+
+Cyclomatic complexity analysis with unified health scoring:
+
+- **Per-file and per-function complexity**: Counts if/else/for/while/case/catch/&&/||/??/ternary with comment and string stripping
+- **Unified health score** (0–100, A–F grades) per module synthesizing:
+  - Cyclomatic complexity penalties
+  - Coupling metrics (fan-in × fan-out from dependency graph)
+  - JSDoc documentation coverage
+  - Security findings severity
+- New renderer: `renderCodeHealth()` with grade distribution, hotspot table, top complex functions, and scoring methodology
+- New document type: **Code Health** (`code_health`)
+- 41 new tests in `code-health.test.js`
+
+### 📝 JSDoc/TSDoc Extraction
+
+API Surface enrichment with documentation extraction:
+
+- Parses `@param`, `@returns`, `@deprecated`, `@example`, `@throws`, `@since` tags
+- Enriches API Surface document with parameter types, descriptions, and deprecation notices
+- Coverage reporting (e.g., "89/167 exports documented (53%)")
+- 16 new tests in `jsdoc-analyzer.test.js`
+
+### 📈 Numbers
+
+- **17 document types** (up from 15): added Security Hotspots + Code Health
+- **480 tests** passing across 25 test files (up from 393 across 22)
+- **12 analyzers** in the pipeline
+
 ## 1.11.0
 
 ### 🧙 Smart URL Parsing in Wizard

package/README.md

@@ -10,14 +10,14 @@
 
 [![npm version](https://img.shields.io/npm/v/@chappibunny/repolens)](https://www.npmjs.com/package/@chappibunny/repolens)
 [![VS Code Extension](https://img.shields.io/visual-studio-marketplace/v/CHAPIBUNNY.repolens-architecture?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=CHAPIBUNNY.repolens-architecture)
-[![Tests](https://img.shields.io/badge/tests-380%20passing-brightgreen)](https://github.com/CHAPIBUNNY/repolens/actions)
+[![Tests](https://img.shields.io/badge/tests-480%20passing-brightgreen)](https://github.com/CHAPIBUNNY/repolens/actions)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 **Your architecture docs are already outdated.** RepoLens fixes that.
 
 RepoLens scans your repository, generates living architecture documentation, and publishes it to Notion, Confluence, GitHub Wiki, or Markdown — automatically on every push. Engineers get technical docs. Stakeholders get readable system overviews. Nobody writes a word.
 
-> Stable as of v1.0 — [API guarantees](docs/STABILITY.md) · [Security hardened](SECURITY.md) · v1.9.12
+> Stable as of v1.0 — [API guarantees](docs/STABILITY.md) · [Security hardened](SECURITY.md) · v1.12.0
 
 ---
 
@@ -92,13 +92,13 @@ Run `npx @chappibunny/repolens migrate` to automatically update your workflow fi
 
 ## 📋 What It Generates
 
-**15 document types** for three audiences — no manual writing required:
+**17 document types** for three audiences — no manual writing required:
 
 | Audience | Documents |
 |---|---|
 | **Stakeholders** (founders, PMs, ops) | Executive Summary · Business Domains · Data Flows |
-| **Everyone** | System Overview · Developer Onboarding · Change Impact · Architecture Drift |
-| **Engineers** | Architecture Overview · Module Catalog · API Surface · Route Map · System Map · GraphQL Schema · TypeScript Type Graph · Dependency Graph |
+| **Everyone** | System Overview · Developer Onboarding · Change Impact · Architecture Drift · Code Health |
+| **Engineers** | Architecture Overview · Module Catalog · API Surface · Route Map · System Map · GraphQL Schema · TypeScript Type Graph · Dependency Graph · Security Hotspots |
 
 **Two modes:** Deterministic (free, fast, always works) or AI-Enhanced (optional — GitHub Models, OpenAI, Anthropic, Google, Azure, Ollama).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",

package/src/ai/document-plan.js

@@ -120,6 +120,22 @@ export const DOCUMENT_PLAN = [
     audience: "mixed",
     ai: false,
     description: "Structural changes compared to baseline snapshot"
+  },
+  {
+    key: "security_hotspots",
+    filename: "15-security-hotspots.md",
+    title: "Security Hotspots",
+    audience: "technical",
+    ai: false,
+    description: "Security anti-pattern detection with CWE classification"
+  },
+  {
+    key: "code_health",
+    filename: "16-code-health.md",
+    title: "Code Health Report",
+    audience: "mixed",
+    ai: false,
+    description: "Per-module health scores from complexity, coupling, docs, and security"
   }
 ];
 

package/src/ai/generate-sections.js

@@ -94,7 +94,7 @@ export async function generateExecutiveSummary(context, enrichment = {}, config)
   return generateWithStructuredFallback(
     "executive_summary",
     createExecutiveSummaryPrompt(context),
-    1500,
+    3000,
     () => getFallbackExecutiveSummary(context, enrichment),
     config,
   );
@@ -104,7 +104,7 @@ export async function generateSystemOverview(context, enrichment = {}, config) {
   return generateWithStructuredFallback(
     "system_overview",
     createSystemOverviewPrompt(context),
-    1200,
+    2500,
     () => getFallbackSystemOverview(context, enrichment),
     config,
   );
@@ -114,7 +114,7 @@ export async function generateBusinessDomains(context, enrichment = {}, config)
   return generateWithStructuredFallback(
     "business_domains",
     createBusinessDomainsPrompt(context),
-    2000,
+    3500,
     () => getFallbackBusinessDomains(context, enrichment),
     config,
   );
@@ -124,7 +124,7 @@ export async function generateArchitectureOverview(context, enrichment = {}, con
   return generateWithStructuredFallback(
     "architecture_overview",
     createArchitectureOverviewPrompt(context),
-    1800,
+    3500,
     () => getFallbackArchitectureOverview(context, enrichment),
     config,
   );
@@ -134,7 +134,7 @@ export async function generateDataFlows(flows, context, enrichment = {}, config)
   return generateWithStructuredFallback(
     "data_flows",
     createDataFlowsPrompt(flows, context),
-    1800,
+    3500,
     () => getFallbackDataFlows(flows, context, enrichment),
     config,
   );
@@ -144,7 +144,7 @@ export async function generateDeveloperOnboarding(context, enrichment = {}, conf
   return generateWithStructuredFallback(
     "developer_onboarding",
     createDeveloperOnboardingPrompt(context),
-    2200,
+    4000,
     () => getFallbackDeveloperOnboarding(context, enrichment),
     config,
   );

package/src/ai/provider.js

@@ -4,7 +4,7 @@ import { warn, info } from "../utils/logger.js";
 import { executeAIRequest } from "../utils/rate-limit.js";
 
 const DEFAULT_TIMEOUT_MS = 60000;
-const DEFAULT_MAX_TOKENS = 2500;
+const DEFAULT_MAX_TOKENS = 4000;
 
 /**
  * AI Provider Presets - one env var to configure common providers.
@@ -245,8 +245,16 @@ async function callOpenAICompatibleAPI({ baseUrl, apiKey, model, system, user, t
           { role: "system", content: system },
           { role: "user", content: user }
         ],
-        max_completion_tokens: maxTokens
       };
+      
+      // GPT-5+ and o-series models require max_completion_tokens; older models use max_tokens
+      const usesNewTokenParam = /^(gpt-5|gpt-4\.1|o[34]-|o3)/.test(model);
+      if (usesNewTokenParam) {
+        body.max_completion_tokens = maxTokens;
+      } else {
+        body.max_tokens = maxTokens;
+      }
+      
       // Only send temperature when explicitly configured — some models
       // (e.g. gpt-5-mini) reject any non-default value
       if (temperature != null) {
@@ -279,7 +287,23 @@ async function callOpenAICompatibleAPI({ baseUrl, apiKey, model, system, user, t
         throw new Error("No completion returned from API");
       }
       
-      return data.choices[0].message.content;
+      const choice = data.choices[0];
+      const content = choice.message?.content;
+      const finishReason = choice.finish_reason || "unknown";
+      
+      // Handle truncation - warn with actionable advice
+      if (finishReason === "length") {
+        if (!content || content.trim().length === 0) {
+          warn(`AI response truncated (hit ${maxTokens} token limit). Increase REPOLENS_AI_MAX_TOKENS or the per-document limit.`);
+        } else {
+          warn(`AI response may be incomplete (finish_reason: length). Consider increasing token limits.`);
+        }
+      } else if (!content || content.trim().length === 0) {
+        warn(`AI response empty (finish_reason: ${finishReason})`);
+      }
+      
+      // Handle null/undefined content (some models return null in certain cases)
+      return content ?? "";
       
     } catch (error) {
       clearTimeout(timeoutId);

package/src/analyzers/complexity-analyzer.js

@@ -0,0 +1,297 @@
+// Complexity & Code Health analyzer
+// Computes per-file cyclomatic complexity, then synthesizes all analyzers
+// (dep graph, JSDoc, security) into a per-module health score.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { info } from "../utils/logger.js";
+
+const JS_EXTENSIONS = [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"];
+
+// Skip test files, build outputs, etc.
+const SKIP_PATTERNS = [
+  /node_modules\//,
+  /\.test\.[jt]sx?$/,
+  /\.spec\.[jt]sx?$/,
+  /\btest[s]?\//,
+  /\bdist\//,
+  /\bbuild\//,
+  /\.min\.[jt]s$/,
+  /\.d\.ts$/,
+  /\.repolens\//,
+];
+
+function shouldSkip(filePath) {
+  return SKIP_PATTERNS.some(p => p.test(filePath));
+}
+
+/**
+ * Count cyclomatic complexity for a source string.
+ * Each decision point adds 1 to the baseline of 1.
+ */
+export function computeComplexity(source) {
+  // Strip comments to avoid false positives
+  let stripped = source.replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n]/g, " "));
+  stripped = stripped.replace(/(?<!:)\/\/.*$/gm, "");
+  // Strip string literals to avoid matching keywords inside strings
+  stripped = stripped.replace(/`[^`]*`/g, '""');
+  stripped = stripped.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+  stripped = stripped.replace(/'(?:[^'\\]|\\.)*'/g, "''");
+
+  let complexity = 1; // baseline
+
+  // Decision point patterns
+  const patterns = [
+    /\bif\s*\(/g,
+    /\belse\s+if\s*\(/g,
+    /\bfor\s*\(/g,
+    /\bwhile\s*\(/g,
+    /\bcase\s+/g,
+    /\bcatch\s*\(/g,
+    /(?<!\?)\?\s*(?![.?])/g,   // ternary ? but not optional chaining ?. or nullish ??
+    /&&/g,
+    /\|\|/g,
+    /\?\?/g,                 // nullish coalescing
+  ];
+
+  for (const pattern of patterns) {
+    const matches = stripped.match(pattern);
+    if (matches) complexity += matches.length;
+  }
+
+  // Subtract double-counted else-if (already counted by if)
+  const elseIfMatches = stripped.match(/\belse\s+if\s*\(/g);
+  if (elseIfMatches) complexity -= elseIfMatches.length;
+
+  return complexity;
+}
+
+/**
+ * Extract function-level complexity from source code.
+ * Returns per-function complexity for the top-level functions.
+ */
+export function extractFunctions(source) {
+  const functions = [];
+  const lines = source.split("\n");
+
+  // Match exported/declared function signatures
+  const funcPattern = /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/g;
+  const arrowPattern = /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:\([^)]*\)|\w+)\s*=>/g;
+
+  let match;
+
+  while ((match = funcPattern.exec(source)) !== null) {
+    const startLine = source.slice(0, match.index).split("\n").length;
+    functions.push({ name: match[1], line: startLine, index: match.index });
+  }
+
+  while ((match = arrowPattern.exec(source)) !== null) {
+    const startLine = source.slice(0, match.index).split("\n").length;
+    functions.push({ name: match[1], line: startLine, index: match.index });
+  }
+
+  // Sort by position in file
+  functions.sort((a, b) => a.index - b.index);
+
+  // Compute complexity for each function's body (approximation: from start to next function)
+  const results = [];
+  for (let i = 0; i < functions.length; i++) {
+    const start = functions[i].index;
+    const end = i + 1 < functions.length ? functions[i + 1].index : source.length;
+    const body = source.slice(start, end);
+    const complexity = computeComplexity(body);
+    results.push({
+      name: functions[i].name,
+      line: functions[i].line,
+      complexity,
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Analyze complexity for all JS/TS files in the project.
+ * @param {string[]} files - File paths relative to repoRoot
+ * @param {string} repoRoot - Absolute path to repo root
+ * @returns {Promise<Object>} Complexity analysis results
+ */
+export async function analyzeComplexity(files, repoRoot) {
+  const jsFiles = files
+    .filter(f => JS_EXTENSIONS.some(ext => f.endsWith(ext)))
+    .filter(f => !shouldSkip(f));
+
+  const result = {
+    files: [],
+    functions: [],
+    filesAnalyzed: jsFiles.length,
+  };
+
+  for (const file of jsFiles) {
+    let content;
+    try {
+      content = await fs.readFile(path.join(repoRoot, file), "utf8");
+    } catch {
+      continue;
+    }
+
+    const fileComplexity = computeComplexity(content);
+    const lineCount = content.split("\n").length;
+    const funcs = extractFunctions(content);
+
+    result.files.push({
+      file,
+      complexity: fileComplexity,
+      lines: lineCount,
+      functions: funcs.length,
+      maxFunctionComplexity: funcs.length > 0 ? Math.max(...funcs.map(f => f.complexity)) : fileComplexity,
+    });
+
+    for (const fn of funcs) {
+      result.functions.push({ ...fn, file });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Synthesize signals from all analyzers into per-module health scores.
+ *
+ * Health score (0–100) is computed from:
+ *   - Complexity penalty: high cyclomatic complexity
+ *   - Coupling penalty: high fan-in * fan-out product
+ *   - Documentation bonus: JSDoc coverage
+ *   - Security penalty: findings in this file
+ *
+ * @param {Object} complexityResult - From analyzeComplexity()
+ * @param {Object} depGraph - From analyzeDependencyGraph()
+ * @param {Object} jsdocResult - From analyzeJSDoc()
+ * @param {Object} securityResult - From analyzeSecurityPatterns()
+ * @returns {Object} Code health report
+ */
+export function computeCodeHealth(complexityResult, depGraph, jsdocResult, securityResult) {
+  const modules = [];
+
+  // Build lookup maps
+  const depMap = new Map();
+  if (depGraph?.nodes) {
+    for (const node of depGraph.nodes) {
+      depMap.set(node.file, {
+        fanIn: node.importedBy?.length || 0,
+        fanOut: node.imports?.length || 0,
+      });
+    }
+  }
+
+  const securityByFile = new Map();
+  if (securityResult?.findings) {
+    for (const finding of securityResult.findings) {
+      if (!securityByFile.has(finding.file)) securityByFile.set(finding.file, []);
+      securityByFile.get(finding.file).push(finding);
+    }
+  }
+
+  const jsdocByFile = new Map();
+  if (jsdocResult?.byFile) {
+    for (const [file, exports] of Object.entries(jsdocResult.byFile)) {
+      const total = exports.length;
+      const documented = exports.filter(e => e.jsdoc != null).length;
+      jsdocByFile.set(file, { total, documented, coverage: total > 0 ? documented / total : 1 });
+    }
+  }
+
+  for (const fileInfo of complexityResult.files) {
+    const { file, complexity, lines, maxFunctionComplexity } = fileInfo;
+
+    // Coupling
+    const dep = depMap.get(file) || { fanIn: 0, fanOut: 0 };
+    const coupling = dep.fanIn * dep.fanOut;
+
+    // Documentation coverage (default 100% if not tracked)
+    const docInfo = jsdocByFile.get(file) || { total: 0, documented: 0, coverage: 1 };
+
+    // Security findings
+    const findings = securityByFile.get(file) || [];
+    const highFindings = findings.filter(f => f.severity === "high").length;
+    const mediumFindings = findings.filter(f => f.severity === "medium").length;
+
+    // Score calculation (0–100, higher is healthier)
+    let score = 100;
+
+    // Complexity penalty: -1 per complexity point above 10, -2 above 30
+    if (complexity > 10) score -= Math.min(25, (complexity - 10) * 1);
+    if (complexity > 30) score -= Math.min(15, (complexity - 30) * 2);
+
+    // Max function complexity penalty: -2 per point above 8
+    if (maxFunctionComplexity > 8) score -= Math.min(15, (maxFunctionComplexity - 8) * 2);
+
+    // Coupling penalty: penalize files with high fan-in AND fan-out
+    if (coupling > 20) score -= Math.min(15, Math.floor((coupling - 20) / 5));
+
+    // Documentation bonus/penalty
+    if (docInfo.total > 0) {
+      if (docInfo.coverage < 0.5) score -= 10;
+      else if (docInfo.coverage < 0.8) score -= 5;
+    }
+
+    // Security penalty
+    score -= highFindings * 10;
+    score -= mediumFindings * 5;
+
+    score = Math.max(0, Math.min(100, score));
+
+    const grade = score >= 80 ? "A" : score >= 60 ? "B" : score >= 40 ? "C" : score >= 20 ? "D" : "F";
+
+    modules.push({
+      file,
+      score,
+      grade,
+      lines,
+      complexity,
+      maxFunctionComplexity,
+      fanIn: dep.fanIn,
+      fanOut: dep.fanOut,
+      coupling,
+      docCoverage: docInfo.total > 0 ? Math.round(docInfo.coverage * 100) : null,
+      securityFindings: findings.length,
+      highSecurityFindings: highFindings,
+    });
+  }
+
+  // Sort by score ascending (worst first)
+  modules.sort((a, b) => a.score - b.score);
+
+  // Aggregate stats
+  const totalFiles = modules.length;
+  const avgScore = totalFiles > 0 ? Math.round(modules.reduce((s, m) => s + m.score, 0) / totalFiles) : 100;
+  const avgComplexity = totalFiles > 0 ? Math.round(modules.reduce((s, m) => s + m.complexity, 0) / totalFiles) : 0;
+
+  const gradeDistribution = { A: 0, B: 0, C: 0, D: 0, F: 0 };
+  for (const m of modules) gradeDistribution[m.grade]++;
+
+  const topComplexFunctions = [...complexityResult.functions]
+    .sort((a, b) => b.complexity - a.complexity)
+    .slice(0, 15);
+
+  const hotspots = modules.filter(m => m.score < 60).slice(0, 20);
+
+  const summary = totalFiles > 0
+    ? `${totalFiles} files analyzed · Average health: ${avgScore}/100 · ${gradeDistribution.A} A, ${gradeDistribution.B} B, ${gradeDistribution.C} C, ${gradeDistribution.D} D, ${gradeDistribution.F} F`
+    : "No source files analyzed.";
+
+  info(`Code health: avg ${avgScore}/100 across ${totalFiles} files (${hotspots.length} hotspots)`);
+
+  return {
+    modules,
+    summary,
+    stats: {
+      totalFiles,
+      avgScore,
+      avgComplexity,
+      gradeDistribution,
+    },
+    hotspots,
+    topComplexFunctions,
+  };
+}