@chappibunny/repolens 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 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)
+
+- **Document caching**: Hash-based caching skips redundant API calls for unchanged documents. Notion, Confluence, and GitHub Wiki publishers now receive only changed pages; Markdown always gets the full set. Cache persists in `.repolens/doc-hashes.json`.
+- **Structured AI output**: AI sections now request JSON-mode responses with schema validation. If JSON parsing or schema validation fails, a single re-prompt is attempted before falling back to plain-text AI, then deterministic generation. All 6 AI document types have JSON schemas and Markdown renderers.
+- **Multi-provider AI**: Added native adapters for Anthropic (Messages API) and Google Gemini alongside existing OpenAI-compatible support. Set `REPOLENS_AI_PROVIDER` to `anthropic`, `google`, or `openai_compatible` (default). Azure OpenAI uses the OpenAI-compatible adapter.
+- **Monorepo awareness**: Automatic detection of npm/yarn workspaces, pnpm workspaces, and Lerna configurations. Scan results include workspace metadata. System Overview renderer shows package inventory table. AI context includes monorepo structure.
+- **CODEOWNERS integration**: Parses `CODEOWNERS` / `.github/CODEOWNERS` / `docs/CODEOWNERS` files. Maps file ownership to modules via last-match-wins pattern matching. Module Catalog now displays an "Owners" column when CODEOWNERS is present. Ownership data is included in artifacts.
+
+### 📊 Test Coverage
+
+- **219 tests** passing across **17 test files** (up from 188/16).
+- New `tests/tier3.test.js` with 31 tests covering caching, monorepo detection, CODEOWNERS parsing, multi-provider AI config, and structured output rendering.
+
 ## 1.4.0
 
 ### 🐛 Bug Fixes (Tier 1 — Production)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charl Van Zyl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -17,7 +17,7 @@
 
 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](STABILITY.md) · [Security hardened](SECURITY.md) · v1.4.0
+> Stable as of v1.0 — [API guarantees](STABILITY.md) · [Security hardened](SECURITY.md) · v1.5.0
 
 ---
 

package/package.json

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

package/src/ai/generate-sections.js

@@ -11,129 +11,109 @@ import {
   createDeveloperOnboardingPrompt,
   createModuleSummaryPrompt,
   createRouteSummaryPrompt,
-  createAPIDocumentationPrompt
+  createAPIDocumentationPrompt,
+  AI_SCHEMAS,
+  renderStructuredToMarkdown,
 } from "./prompts.js";
 import { info, warn } from "../utils/logger.js";
 
-export async function generateExecutiveSummary(context) {
-  if (!isAIEnabled()) {
-    return getFallbackExecutiveSummary(context);
+/**
+ * Try structured JSON mode first, fall back to plain-text AI, then deterministic.
+ */
+async function generateWithStructuredFallback(key, promptText, maxTokens, fallbackFn) {
+  if (!isAIEnabled()) return fallbackFn();
+
+  const schema = AI_SCHEMAS[key];
+
+  // Try structured JSON mode
+  if (schema) {
+    info(`Generating ${key} with structured AI...`);
+    const jsonPrompt = promptText + `\n\nRespond ONLY with a JSON object matching this schema: ${JSON.stringify({ required: schema.required })}. No markdown, no explanation — just the JSON object.`;
+
+    const result = await generateText({
+      system: SYSTEM_PROMPT,
+      user: jsonPrompt,
+      maxTokens,
+      jsonMode: true,
+      jsonSchema: schema,
+    });
+
+    if (result.success && result.parsed) {
+      const md = renderStructuredToMarkdown(key, result.parsed);
+      if (md) return md;
+    }
+    // If structured mode failed, fall through to plain-text
+    warn(`Structured AI failed for ${key}, trying plain-text mode...`);
   }
-  
-  info("Generating executive summary with AI...");
-  
+
+  // Plain-text AI fallback
+  info(`Generating ${key} with AI...`);
   const result = await generateText({
     system: SYSTEM_PROMPT,
-    user: createExecutiveSummaryPrompt(context),
-    maxTokens: 1500
+    user: promptText,
+    maxTokens,
   });
-  
+
   if (!result.success) {
     warn("AI generation failed, using fallback");
-    return getFallbackExecutiveSummary(context);
+    return fallbackFn();
   }
-  
+
   return result.text;
 }
 
+export async function generateExecutiveSummary(context) {
+  return generateWithStructuredFallback(
+    "executive_summary",
+    createExecutiveSummaryPrompt(context),
+    1500,
+    () => getFallbackExecutiveSummary(context),
+  );
+}
+
 export async function generateSystemOverview(context) {
-  if (!isAIEnabled()) {
-    return getFallbackSystemOverview(context);
-  }
-  
-  info("Generating system overview with AI...");
-  
-  const result = await generateText({
-    system: SYSTEM_PROMPT,
-    user: createSystemOverviewPrompt(context),
-    maxTokens: 1200
-  });
-  
-  if (!result.success) {
-    return getFallbackSystemOverview(context);
-  }
-  
-  return result.text;
+  return generateWithStructuredFallback(
+    "system_overview",
+    createSystemOverviewPrompt(context),
+    1200,
+    () => getFallbackSystemOverview(context),
+  );
 }
 
 export async function generateBusinessDomains(context) {
-  if (!isAIEnabled()) {
-    return getFallbackBusinessDomains(context);
-  }
-  
-  info("Generating business domains with AI...");
-  
-  const result = await generateText({
-    system: SYSTEM_PROMPT,
-    user: createBusinessDomainsPrompt(context),
-    maxTokens: 2000
-  });
-  
-  if (!result.success) {
-    return getFallbackBusinessDomains(context);
-  }
-  
-  return result.text;
+  return generateWithStructuredFallback(
+    "business_domains",
+    createBusinessDomainsPrompt(context),
+    2000,
+    () => getFallbackBusinessDomains(context),
+  );
 }
 
 export async function generateArchitectureOverview(context) {
-  if (!isAIEnabled()) {
-    return getFallbackArchitectureOverview(context);
-  }
-  
-  info("Generating architecture overview with AI...");
-  
-  const result = await generateText({
-    system: SYSTEM_PROMPT,
-    user: createArchitectureOverviewPrompt(context),
-    maxTokens: 1800
-  });
-  
-  if (!result.success) {
-    return getFallbackArchitectureOverview(context);
-  }
-  
-  return result.text;
+  return generateWithStructuredFallback(
+    "architecture_overview",
+    createArchitectureOverviewPrompt(context),
+    1800,
+    () => getFallbackArchitectureOverview(context),
+  );
 }
 
 export async function generateDataFlows(flows, context) {
-  if (!isAIEnabled()) {
-    return getFallbackDataFlows(flows);
-  }
-  
-  info("Generating data flows with AI...");
-  
-  const result = await generateText({
-    system: SYSTEM_PROMPT,
-    user: createDataFlowsPrompt(flows, context),
-    maxTokens: 1800
-  });
-  
-  if (!result.success) {
-    return getFallbackDataFlows(flows);
-  }
-  
-  return result.text;
+  return generateWithStructuredFallback(
+    "data_flows",
+    createDataFlowsPrompt(flows, context),
+    1800,
+    () => getFallbackDataFlows(flows),
+  );
 }
 
 export async function generateDeveloperOnboarding(context) {
-  if (!isAIEnabled()) {
-    return getFallbackDeveloperOnboarding(context);
-  }
-  
-  info("Generating developer onboarding with AI...");
-  
-  const result = await generateText({
-    system: SYSTEM_PROMPT,
-    user: createDeveloperOnboardingPrompt(context),
-    maxTokens: 2200
-  });
-  
-  if (!result.success) {
-    return getFallbackDeveloperOnboarding(context);
-  }
-  
-  return result.text;
+  return generateWithStructuredFallback(
+    "developer_onboarding",
+    createDeveloperOnboardingPrompt(context),
+    2200,
+    () => getFallbackDeveloperOnboarding(context),
+  );
 }
 
 // Fallback generators (deterministic, no AI)

package/src/ai/prompts.js

@@ -353,3 +353,218 @@ Dependencies:
 Risks:
 [if applicable]`;
 }
+
+// --- JSON schemas for structured AI output ---
+
+export const AI_SCHEMAS = {
+  executive_summary: {
+    required: ["whatItDoes", "whoItServes", "coreCapabilities", "mainAreas", "risks"],
+    description: "Executive summary for mixed audience",
+  },
+  system_overview: {
+    required: ["snapshot", "layers", "domains", "patterns", "observations"],
+    description: "High-level system overview",
+  },
+  business_domains: {
+    required: ["domains"],
+    description: "Business domain breakdown",
+  },
+  architecture_overview: {
+    required: ["style", "layers", "strengths", "weaknesses"],
+    description: "Architecture overview for engineers",
+  },
+  data_flows: {
+    required: ["flows"],
+    description: "Data flow documentation",
+  },
+  developer_onboarding: {
+    required: ["startHere", "mainFolders", "coreFlows", "complexityHotspots"],
+    description: "Developer onboarding guide",
+  },
+};
+
+/**
+ * Render a structured JSON response into Markdown for the given document type.
+ */
+export function renderStructuredToMarkdown(key, parsed) {
+  switch (key) {
+    case "executive_summary":
+      return renderExecutiveSummaryJSON(parsed);
+    case "system_overview":
+      return renderSystemOverviewJSON(parsed);
+    case "business_domains":
+      return renderBusinessDomainsJSON(parsed);
+    case "architecture_overview":
+      return renderArchitectureOverviewJSON(parsed);
+    case "data_flows":
+      return renderDataFlowsJSON(parsed);
+    case "developer_onboarding":
+      return renderDeveloperOnboardingJSON(parsed);
+    default:
+      return null;
+  }
+}
+
+/**
+ * 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${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${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)) {
+    // 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) {
+    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:** ${safeStr(dom.dependencies)}\n\n`;
+  }
+  return md;
+}
+
+function renderArchitectureOverviewJSON(d) {
+  let md = `# Architecture Overview\n\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)) {
+    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) {
+    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${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;
+}