@chappibunny/repolens 1.5.0 → 1.5.3

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.5.3
+
+### 🔧 Improvements
+
+- **CI test gate**: Publish workflow now runs the full Vitest suite before publishing. The `publish` job requires both `security` and `test` jobs to pass.
+
+### 🧪 Test Coverage
+
+- **Renderer unit tests** (`tests/renderers.test.js`): 33 tests covering all four `render.js` exports (`renderSystemOverview`, `renderModuleCatalog`, `renderApiSurface`, `renderRouteMap`), `renderSystemMap` (with/without depGraph, categories, limits), and `renderDiff.js` (`buildArchitectureDiffData` route detection, `renderArchitectureDiff` truncation).
+- **311 tests** passing across **21 test files** (up from 278/20).
+
+## 1.5.2
+
+### 🐛 Bug Fixes
+
+- **retry-after: 0 honoured**: Fixed falsy-zero bug in `fetchWithRetry` where `retry-after: 0` header was ignored (fell through to `baseDelayMs`). Now properly honours the server's hint, even when it's zero.
+
+### 🧪 Test Quality
+
+- **Mock HTTP server integration tests** (`tests/http-integration.test.js`): 17 tests exercising `fetchWithRetry` against a real local HTTP server — retry on 429/500, timeout handling, header validation, Notion/Confluence block/format generation.
+- **Rate-limit concurrent stress tests** (`tests/rate-limit-stress.test.js`): 9 tests firing 20–50 parallel requests through the token bucket to verify throttling, deadlock freedom, burst behaviour, and `batchRequests` concurrency control.
+- **Watch mode test refactor** (`tests/watch.test.js`): Replaced fake timers with real temp directories and real `fs.watch` events. Tests now create actual files, observe filesystem watcher callbacks, and verify debounced rebuilds without `vi.useFakeTimers()`.
+- **278 tests** passing across **20 test files** (up from 251/18).
+
+## 1.5.1
+
+### 🐛 Bug Fixes
+
+- **[object Object] rendering fix**: All 6 structured AI renderers now use safe coercion helpers (`safeStr`, `toBulletList`, `toHeadingSections`) that handle strings, arrays, objects, and null values robustly. Prevents `[object Object]` from appearing in Notion/Confluence/Markdown output when AI returns unexpected shapes.
+
+### 🔧 Improvements — Robustness
+
+- **Fetch timeout**: All HTTP requests via `fetchWithRetry` now enforce a 30-second timeout (configurable via `timeoutMs`). Prevents publishers from hanging indefinitely on stalled connections. `AbortError` is converted to a friendly timeout message.
+- **Per-document error isolation**: Extended analysis (GraphQL, TypeScript, dependency graph, drift detection) now wraps each phase in try/catch. A failing analyzer no longer blocks the entire doc generation pipeline.
+- **Partial-success publishing**: Publisher orchestration no longer throws on the first failure. If Notion fails but Confluence/Markdown succeed, all remaining publishers still run. Failures are logged as warnings. Only throws if *all* publishers fail.
+
+### 📊 Test Coverage
+
+- **251 tests** passing across **18 test files** (up from 224/17).
+- New `tests/robustness.test.js` with 27 tests covering: rate limiter, context builder, flow inference, Discord integration, PR comment module, telemetry, write-doc-set file I/O, fetch timeout, doc generation error isolation, and partial-success publishing.
+
 ## 1.5.0
 
 ### 🚀 New Features (Tier 3 — Differentiation)

package/package.json

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

package/src/ai/prompts.js

@@ -405,73 +405,166 @@ export function renderStructuredToMarkdown(key, parsed) {
   }
 }
 
+/**
+ * Safely convert any AI response value to a readable string.
+ * Handles: strings, arrays (of strings or objects), plain objects, and other types.
+ */
+function safeStr(val) {
+  if (val == null) return "";
+  if (typeof val === "string") return val;
+  if (Array.isArray(val)) return val.map(safeStr).join(", ");
+  if (typeof val === "object") {
+    // Try common field patterns the AI might use
+    if (val.name) return val.description ? `${val.name}: ${val.description}` : val.name;
+    if (val.title) return val.description ? `${val.title}: ${val.description}` : val.title;
+    // Fallback: render object key/value pairs
+    return Object.entries(val).map(([k, v]) => `${k}: ${typeof v === "string" ? v : safeStr(v)}`).join("; ");
+  }
+  return String(val);
+}
+
+/**
+ * Convert a value to a bullet list.
+ * Handles strings, arrays of strings, arrays of objects, and plain objects.
+ */
+function toBulletList(val) {
+  if (val == null) return "";
+  if (typeof val === "string") return val;
+  if (Array.isArray(val)) {
+    return val.map(item => {
+      if (typeof item === "string") return `- ${item}`;
+      if (typeof item === "object" && item !== null) {
+        const label = item.name || item.title || Object.keys(item)[0] || "";
+        const desc = item.description || item[Object.keys(item)[0]];
+        if (label && desc && label !== desc) return `- **${label}**: ${desc}`;
+        return `- ${safeStr(item)}`;
+      }
+      return `- ${String(item)}`;
+    }).join("\n");
+  }
+  if (typeof val === "object") {
+    // Object with key/value pairs → render as list
+    return Object.entries(val).map(([k, v]) => `- **${k}**: ${typeof v === "string" ? v : safeStr(v)}`).join("\n");
+  }
+  return String(val);
+}
+
+/**
+ * Convert a value to a heading-based section list (### heading per item).
+ */
+function toHeadingSections(val) {
+  if (val == null) return "";
+  if (typeof val === "string") return val;
+  if (Array.isArray(val)) {
+    return val.map(item => {
+      if (typeof item === "string") return `### ${item}`;
+      if (typeof item === "object" && item !== null) {
+        const label = item.name || item.title || Object.keys(item)[0] || "Section";
+        const desc = item.description || item[Object.keys(item)[0]] || "";
+        return `### ${label}\n\n${typeof desc === "string" ? desc : safeStr(desc)}`;
+      }
+      return `### ${String(item)}`;
+    }).join("\n\n");
+  }
+  if (typeof val === "object") {
+    return Object.entries(val).map(([k, v]) => `### ${k}\n\n${typeof v === "string" ? v : safeStr(v)}`).join("\n\n");
+  }
+  return String(val);
+}
+
 function renderExecutiveSummaryJSON(d) {
   let md = `# Executive Summary\n\n`;
-  md += `## What This System Does\n\n${d.whatItDoes}\n\n`;
-  md += `## Who It Serves\n\n${d.whoItServes}\n\n`;
-  md += `## Core Capabilities\n\n`;
-  if (Array.isArray(d.coreCapabilities)) {
-    md += d.coreCapabilities.map(c => `- ${c}`).join("\n") + "\n\n";
-  } else {
-    md += `${d.coreCapabilities}\n\n`;
-  }
-  md += `## Main System Areas\n\n${Array.isArray(d.mainAreas) ? d.mainAreas.map(a => `- **${a.name || a}**${a.description ? `: ${a.description}` : ""}`).join("\n") : d.mainAreas}\n\n`;
-  if (d.dependencies) md += `## Key Dependencies\n\n${Array.isArray(d.dependencies) ? d.dependencies.map(dep => `- ${dep}`).join("\n") : d.dependencies}\n\n`;
-  md += `## Operational and Architectural Risks\n\n${Array.isArray(d.risks) ? d.risks.map(r => `- ${r}`).join("\n") : d.risks}\n\n`;
-  if (d.focusAreas) md += `## Recommended Focus Areas\n\n${Array.isArray(d.focusAreas) ? d.focusAreas.map(f => `- ${f}`).join("\n") : d.focusAreas}\n`;
+  md += `## What This System Does\n\n${safeStr(d.whatItDoes)}\n\n`;
+  md += `## Who It Serves\n\n${safeStr(d.whoItServes)}\n\n`;
+  md += `## Core Capabilities\n\n${toBulletList(d.coreCapabilities)}\n\n`;
+  md += `## Main System Areas\n\n${toBulletList(d.mainAreas)}\n\n`;
+  if (d.dependencies) md += `## Key Dependencies\n\n${toBulletList(d.dependencies)}\n\n`;
+  md += `## Operational and Architectural Risks\n\n${toBulletList(d.risks)}\n\n`;
+  if (d.focusAreas) md += `## Recommended Focus Areas\n\n${toBulletList(d.focusAreas)}\n`;
   return md;
 }
 
 function renderSystemOverviewJSON(d) {
   let md = `# System Overview\n\n`;
-  md += `## Repository Snapshot\n\n${d.snapshot}\n\n`;
-  md += `## Main Architectural Layers\n\n${Array.isArray(d.layers) ? d.layers.map(l => `- **${l.name || l}**${l.description ? `: ${l.description}` : ""}`).join("\n") : d.layers}\n\n`;
-  md += `## Dominant Domains\n\n${Array.isArray(d.domains) ? d.domains.map(dom => `- ${dom}`).join("\n") : d.domains}\n\n`;
-  md += `## Main Technology Patterns\n\n${Array.isArray(d.patterns) ? d.patterns.map(p => `- ${p}`).join("\n") : d.patterns}\n\n`;
-  md += `## Key Observations\n\n${Array.isArray(d.observations) ? d.observations.map(o => `- ${o}`).join("\n") : d.observations}\n`;
+  md += `## Repository Snapshot\n\n${safeStr(d.snapshot)}\n\n`;
+  md += `## Main Architectural Layers\n\n${toBulletList(d.layers)}\n\n`;
+  md += `## Dominant Domains\n\n${toBulletList(d.domains)}\n\n`;
+  md += `## Main Technology Patterns\n\n${toBulletList(d.patterns)}\n\n`;
+  md += `## Key Observations\n\n${toBulletList(d.observations)}\n`;
   return md;
 }
 
 function renderBusinessDomainsJSON(d) {
   let md = `# Business Domains\n\n`;
-  if (!Array.isArray(d.domains)) return md + d.domains;
+  if (!Array.isArray(d.domains)) {
+    // Handle object-style domains: { "Auth": { description: "..." }, ... }
+    if (typeof d.domains === "object" && d.domains !== null) {
+      for (const [name, info] of Object.entries(d.domains)) {
+        const desc = typeof info === "string" ? info : info?.description || safeStr(info);
+        md += `## ${name}\n\n${desc}\n\n`;
+        if (info?.modules) md += `**Key modules:** ${safeStr(info.modules)}\n\n`;
+        if (info?.userFunctionality) md += `**User-visible functionality:** ${info.userFunctionality}\n\n`;
+        if (info?.dependencies) md += `**Dependencies:** ${safeStr(info.dependencies)}\n\n`;
+      }
+      return md;
+    }
+    return md + safeStr(d.domains);
+  }
   for (const dom of d.domains) {
-    md += `## ${dom.name}\n\n${dom.description || ""}\n\n`;
-    if (dom.modules) md += `**Key modules:** ${Array.isArray(dom.modules) ? dom.modules.join(", ") : dom.modules}\n\n`;
+    const name = dom.name || dom.title || safeStr(dom);
+    md += `## ${name}\n\n${dom.description || ""}\n\n`;
+    if (dom.modules) md += `**Key modules:** ${safeStr(dom.modules)}\n\n`;
     if (dom.userFunctionality) md += `**User-visible functionality:** ${dom.userFunctionality}\n\n`;
-    if (dom.dependencies) md += `**Dependencies:** ${Array.isArray(dom.dependencies) ? dom.dependencies.join(", ") : dom.dependencies}\n\n`;
+    if (dom.dependencies) md += `**Dependencies:** ${safeStr(dom.dependencies)}\n\n`;
   }
   return md;
 }
 
 function renderArchitectureOverviewJSON(d) {
   let md = `# Architecture Overview\n\n`;
-  md += `## Architecture Style\n\n${d.style}\n\n`;
-  md += `## Layers\n\n${Array.isArray(d.layers) ? d.layers.map(l => `### ${l.name || l}\n\n${l.description || ""}`).join("\n\n") : d.layers}\n\n`;
-  md += `## Architectural Strengths\n\n${Array.isArray(d.strengths) ? d.strengths.map(s => `- ${s}`).join("\n") : d.strengths}\n\n`;
-  md += `## Architectural Weaknesses\n\n${Array.isArray(d.weaknesses) ? d.weaknesses.map(w => `- ${w}`).join("\n") : d.weaknesses}\n`;
+  md += `## Architecture Style\n\n${safeStr(d.style)}\n\n`;
+  md += `## Layers\n\n${toHeadingSections(d.layers)}\n\n`;
+  md += `## Architectural Strengths\n\n${toBulletList(d.strengths)}\n\n`;
+  md += `## Architectural Weaknesses\n\n${toBulletList(d.weaknesses)}\n`;
   return md;
 }
 
 function renderDataFlowsJSON(d) {
   let md = `# Data Flows\n\n`;
-  if (!Array.isArray(d.flows)) return md + d.flows;
+  if (!Array.isArray(d.flows)) {
+    if (typeof d.flows === "object" && d.flows !== null) {
+      for (const [name, info] of Object.entries(d.flows)) {
+        const desc = typeof info === "string" ? info : info?.description || safeStr(info);
+        md += `## ${name}\n\n${desc}\n\n`;
+        if (info?.steps) md += `**Steps:**\n${toBulletList(info.steps)}\n\n`;
+        if (info?.modules) md += `**Involved modules:** ${safeStr(info.modules)}\n\n`;
+      }
+      return md;
+    }
+    return md + safeStr(d.flows);
+  }
   for (const flow of d.flows) {
-    md += `## ${flow.name}\n\n${flow.description || ""}\n\n`;
-    if (flow.steps) md += `**Steps:**\n${Array.isArray(flow.steps) ? flow.steps.map((s, i) => `${i + 1}. ${s}`).join("\n") : flow.steps}\n\n`;
-    if (flow.modules) md += `**Involved modules:** ${Array.isArray(flow.modules) ? flow.modules.join(", ") : flow.modules}\n\n`;
-    if (flow.criticalDependencies) md += `**Critical dependencies:** ${flow.criticalDependencies}\n\n`;
+    const name = flow.name || flow.title || safeStr(flow);
+    md += `## ${name}\n\n${flow.description || ""}\n\n`;
+    if (flow.steps) {
+      const steps = Array.isArray(flow.steps)
+        ? flow.steps.map((s, i) => `${i + 1}. ${safeStr(s)}`).join("\n")
+        : safeStr(flow.steps);
+      md += `**Steps:**\n${steps}\n\n`;
+    }
+    if (flow.modules) md += `**Involved modules:** ${safeStr(flow.modules)}\n\n`;
+    if (flow.criticalDependencies) md += `**Critical dependencies:** ${safeStr(flow.criticalDependencies)}\n\n`;
   }
   return md;
 }
 
 function renderDeveloperOnboardingJSON(d) {
   let md = `# Developer Onboarding\n\n`;
-  md += `## Start Here\n\n${d.startHere}\n\n`;
-  md += `## Main Folders\n\n${Array.isArray(d.mainFolders) ? d.mainFolders.map(f => `- **${f.name || f}**${f.description ? `: ${f.description}` : ""}`).join("\n") : d.mainFolders}\n\n`;
-  md += `## Core Product Flows\n\n${Array.isArray(d.coreFlows) ? d.coreFlows.map(f => `- ${f}`).join("\n") : d.coreFlows}\n\n`;
-  if (d.importantRoutes) md += `## Important Routes\n\n${Array.isArray(d.importantRoutes) ? d.importantRoutes.map(r => `- ${r}`).join("\n") : d.importantRoutes}\n\n`;
-  if (d.sharedLibraries) md += `## Important Shared Libraries\n\n${Array.isArray(d.sharedLibraries) ? d.sharedLibraries.map(l => `- ${l}`).join("\n") : d.sharedLibraries}\n\n`;
-  md += `## Known Complexity Hotspots\n\n${Array.isArray(d.complexityHotspots) ? d.complexityHotspots.map(h => `- ${h}`).join("\n") : d.complexityHotspots}\n`;
+  md += `## Start Here\n\n${safeStr(d.startHere)}\n\n`;
+  md += `## Main Folders\n\n${toBulletList(d.mainFolders)}\n\n`;
+  md += `## Core Product Flows\n\n${toBulletList(d.coreFlows)}\n\n`;
+  if (d.importantRoutes) md += `## Important Routes\n\n${toBulletList(d.importantRoutes)}\n\n`;
+  if (d.sharedLibraries) md += `## Important Shared Libraries\n\n${toBulletList(d.sharedLibraries)}\n\n`;
+  md += `## Known Complexity Hotspots\n\n${toBulletList(d.complexityHotspots)}\n`;
   return md;
 }

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

@@ -27,7 +27,7 @@ import {
   renderDependencyGraph,
   renderArchitectureDrift as renderDriftReport
 } from "../renderers/renderAnalysis.js";
-import { info } from "../utils/logger.js";
+import { info, warn } from "../utils/logger.js";
 import path from "node:path";
 
 export async function generateDocumentSet(scanResult, config, diffData = null, pluginManager = null) {
@@ -43,17 +43,25 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   const scanFiles = scanResult._files || [];
   
   info("Running extended analysis...");
-  const graphqlResult = await analyzeGraphQL(scanFiles, repoRoot);
-  const tsResult = await analyzeTypeScript(scanFiles, repoRoot);
-  const depGraph = await analyzeDependencyGraph(scanFiles, repoRoot);
+  let graphqlResult = { detected: false };
+  let tsResult = { detected: false };
+  let depGraph = { stats: {}, graph: {} };
+  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}`); }
   
   // Architecture drift detection
   const outputDir = path.join(repoRoot, ".repolens");
-  const baseline = await loadBaseline(outputDir);
-  const snapshot = buildSnapshot(scanResult, depGraph, graphqlResult, tsResult);
-  const driftResult = detectDrift(baseline, snapshot);
-  // Save current snapshot as new baseline
-  await saveBaseline(snapshot, outputDir);
+  let baseline = null;
+  let snapshot = null;
+  let driftResult = { drifts: [], summary: "No drift data available" };
+  try {
+    baseline = await loadBaseline(outputDir);
+    snapshot = buildSnapshot(scanResult, depGraph, graphqlResult, tsResult);
+    driftResult = detectDrift(baseline, snapshot);
+    // Save current snapshot as new baseline
+    await saveBaseline(snapshot, outputDir);
+  } catch (e) { warn(`Drift detection failed: ${e.message}`); }
 
   // CODEOWNERS integration
   const codeowners = await parseCodeowners(repoRoot);

package/src/publishers/index.js

@@ -22,6 +22,7 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
   const publishers = cfg.publishers || ["markdown", "notion"];
   const currentBranch = getCurrentBranch();
   const publishedTo = [];
+  const publishErrors = [];
   let publishStatus = "success";
   let notionUrl = null;
 
@@ -49,8 +50,9 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
           notionUrl = `https://notion.so/${process.env.NOTION_PARENT_PAGE_ID}`;
         }
       } catch (err) {
-        publishStatus = "failure";
-        throw err;
+        warn(`Notion publish failed: ${err.message}`);
+        publishErrors.push({ publisher: "notion", error: err });
+        publishStatus = "partial";
       }
     } else {
       const allowedBranches = cfg.notion?.branches?.join(", ") || "none configured";
@@ -70,8 +72,9 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
         await publishToConfluence(cfg, pagesForAPIs);
         publishedTo.push("confluence");
       } catch (err) {
-        publishStatus = "failure";
-        throw err;
+        warn(`Confluence publish failed: ${err.message}`);
+        publishErrors.push({ publisher: "confluence", error: err });
+        publishStatus = "partial";
       }
     } else {
       const allowedBranches = cfg.confluence?.branches?.join(", ") || "none configured";
@@ -86,8 +89,9 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
       await publishToMarkdown(cfg, renderedPages);
       publishedTo.push("markdown");
     } catch (err) {
-      publishStatus = "failure";
-      throw err;
+      warn(`Markdown publish failed: ${err.message}`);
+      publishErrors.push({ publisher: "markdown", error: err });
+      publishStatus = "partial";
     }
   }
 
@@ -102,8 +106,9 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
         await publishToGitHubWiki(cfg, pagesForAPIs);
         publishedTo.push("github_wiki");
       } catch (err) {
-        publishStatus = "failure";
-        throw err;
+        warn(`GitHub Wiki publish failed: ${err.message}`);
+        publishErrors.push({ publisher: "github_wiki", error: err });
+        publishStatus = "partial";
       }
     } else {
       const allowedBranches = cfg.github_wiki?.branches?.join(", ") || "none configured";
@@ -195,4 +200,15 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
   if (pluginManager) {
     await pluginManager.runHook("afterPublish", { publishedTo, publishStatus });
   }
+
+  // Report partial failures
+  if (publishErrors.length > 0) {
+    const failedNames = publishErrors.map(e => e.publisher).join(", ");
+    if (publishedTo.length > 0) {
+      warn(`Partial publish: succeeded for [${publishedTo.join(", ")}], failed for [${failedNames}]`);
+    } else {
+      // All publishers failed — throw the first error
+      throw publishErrors[0].error;
+    }
+  }
 }

package/src/utils/retry.js

@@ -13,7 +13,8 @@ export async function fetchWithRetry(url, options = {}, config = {}) {
     retries = 3,
     baseDelayMs = 500,
     maxDelayMs = 4000,
-    label = "request"
+    label = "request",
+    timeoutMs = 30000
   } = config;
 
   let attempt = 0;
@@ -21,26 +22,40 @@ export async function fetchWithRetry(url, options = {}, config = {}) {
 
   while (attempt <= retries) {
     try {
-      const response = await fetch(url, options);
+      // Apply timeout via AbortController
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      const fetchOpts = { ...options, signal: controller.signal };
+      let response;
+      try {
+        response = await fetch(url, fetchOpts);
+      } finally {
+        clearTimeout(timer);
+      }
 
       if (!isRetryableStatus(response.status)) {
         return response;
       }
 
       const retryAfterHeader = response.headers.get("retry-after");
-      const retryAfterMs = retryAfterHeader
+      const retryAfterMs = retryAfterHeader != null
         ? Number(retryAfterHeader) * 1000
         : null;
 
-      const delay = retryAfterMs || Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+      const delay = retryAfterMs != null ? retryAfterMs : Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
 
       warn(`${label} failed with retryable status ${response.status}. Retrying in ${delay}ms (attempt ${attempt + 1}/${retries + 1})`);
       await sleep(delay);
     } catch (error) {
       lastError = error;
 
+      // Convert AbortError to a friendlier timeout message
+      if (error.name === "AbortError") {
+        lastError = new Error(`${label} timed out after ${timeoutMs}ms`);
+      }
+
       const delay = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
-      warn(`${label} threw error: ${error.message}. Retrying in ${delay}ms (attempt ${attempt + 1}/${retries + 1})`);
+      warn(`${label} threw error: ${lastError.message}. Retrying in ${delay}ms (attempt ${attempt + 1}/${retries + 1})`);
       await sleep(delay);
     }