@chappibunny/repolens 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 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.0",
   "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,125 @@ 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;
+  }
+}
+
+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`;
+  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`;
+  return md;
+}
+
+function renderBusinessDomainsJSON(d) {
+  let md = `# Business Domains\n\n`;
+  if (!Array.isArray(d.domains)) return md + 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`;
+    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`;
+  }
+  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`;
+  return md;
+}
+
+function renderDataFlowsJSON(d) {
+  let md = `# Data Flows\n\n`;
+  if (!Array.isArray(d.flows)) return md + 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`;
+  }
+  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`;
+  return md;
+}

package/src/ai/provider.js

@@ -6,7 +6,7 @@ import { executeAIRequest } from "../utils/rate-limit.js";
 const DEFAULT_TIMEOUT_MS = 60000;
 const DEFAULT_MAX_TOKENS = 2500;
 
-export async function generateText({ system, user, temperature, maxTokens, config }) {
+export async function generateText({ system, user, temperature, maxTokens, config, jsonMode, jsonSchema }) {
   // Check if AI is enabled (env var takes precedence, then config)
   const aiConfig = config?.ai || {};
   const enabled = process.env.REPOLENS_AI_ENABLED === "true" || aiConfig.enabled === true;
@@ -43,18 +43,58 @@ export async function generateText({ system, user, temperature, maxTokens, confi
   if (!baseUrl && provider === "openai_compatible") {
     warn("REPOLENS_AI_BASE_URL not set. Using OpenAI default.");
   }
+
+  // Select provider adapter
+  const adapter = getProviderAdapter(provider);
   
   try {
-    const result = await callOpenAICompatibleAPI({
-      baseUrl: baseUrl || "https://api.openai.com/v1",
+    const result = await adapter({
+      baseUrl: baseUrl || getDefaultBaseUrl(provider),
       apiKey,
       model,
       system,
       user,
       temperature: resolvedTemp,
       maxTokens: resolvedMaxTokens,
-      timeoutMs
+      timeoutMs,
+      jsonMode,
     });
+
+    // Validate JSON schema if provided
+    if (jsonMode && jsonSchema && result) {
+      const parsed = safeParseJSON(result);
+      if (!parsed) {
+        warn("AI returned invalid JSON, re-prompting once...");
+        const retryResult = await adapter({
+          baseUrl: baseUrl || getDefaultBaseUrl(provider),
+          apiKey,
+          model,
+          system,
+          user: user + "\n\nIMPORTANT: Your previous response was not valid JSON. Respond ONLY with a valid JSON object.",
+          temperature: resolvedTemp,
+          maxTokens: resolvedMaxTokens,
+          timeoutMs,
+          jsonMode,
+        });
+        const retryParsed = safeParseJSON(retryResult);
+        if (!retryParsed) {
+          warn("AI JSON re-prompt also failed, falling back to deterministic.");
+          return { success: false, error: "Invalid JSON from AI after retry", fallback: true };
+        }
+        const schemaError = validateSchema(retryParsed, jsonSchema);
+        if (schemaError) {
+          warn(`AI JSON schema mismatch after retry: ${schemaError}`);
+          return { success: false, error: schemaError, fallback: true };
+        }
+        return { success: true, text: retryResult, parsed: retryParsed, fallback: false };
+      }
+      const schemaError = validateSchema(parsed, jsonSchema);
+      if (schemaError) {
+        warn(`AI JSON schema mismatch: ${schemaError}`);
+        return { success: false, error: schemaError, fallback: true };
+      }
+      return { success: true, text: result, parsed, fallback: false };
+    }
     
     return {
       success: true,
@@ -72,7 +112,59 @@ export async function generateText({ system, user, temperature, maxTokens, confi
   }
 }
 
-async function callOpenAICompatibleAPI({ baseUrl, apiKey, model, system, user, temperature, maxTokens, timeoutMs }) {
+/**
+ * Parse JSON safely, returning null on failure.
+ */
+function safeParseJSON(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    // Try extracting JSON from markdown code blocks
+    const match = text?.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (match) {
+      try { return JSON.parse(match[1].trim()); } catch { /* fall through */ }
+    }
+    return null;
+  }
+}
+
+/**
+ * Validate an object against a simple schema (required string fields).
+ * Returns error message or null if valid.
+ */
+function validateSchema(obj, schema) {
+  if (!schema || !schema.required) return null;
+  for (const field of schema.required) {
+    if (!(field in obj)) return `Missing required field: ${field}`;
+  }
+  return null;
+}
+
+/**
+ * Get default base URL for a provider.
+ */
+function getDefaultBaseUrl(provider) {
+  switch (provider) {
+    case "anthropic": return "https://api.anthropic.com";
+    case "azure": return process.env.REPOLENS_AI_BASE_URL || "https://api.openai.com/v1";
+    case "google": return "https://generativelanguage.googleapis.com";
+    default: return "https://api.openai.com/v1";
+  }
+}
+
+/**
+ * Select the appropriate provider adapter function.
+ */
+function getProviderAdapter(provider) {
+  switch (provider) {
+    case "anthropic": return callAnthropicAPI;
+    case "google": return callGoogleAPI;
+    // "openai_compatible" and "azure" both use the OpenAI format
+    default: return callOpenAICompatibleAPI;
+  }
+}
+
+async function callOpenAICompatibleAPI({ baseUrl, apiKey, model, system, user, temperature, maxTokens, timeoutMs, jsonMode }) {
   return await executeAIRequest(async () => {
     const url = `${baseUrl}/chat/completions`;
     
@@ -94,6 +186,9 @@ async function callOpenAICompatibleAPI({ baseUrl, apiKey, model, system, user, t
       if (temperature != null) {
         body.temperature = temperature;
       }
+      if (jsonMode) {
+        body.response_format = { type: "json_object" };
+      }
 
       const response = await fetch(url, {
         method: "POST",
@@ -132,15 +227,126 @@ async function callOpenAICompatibleAPI({ baseUrl, apiKey, model, system, user, t
   });
 }
 
+/**
+ * Anthropic Messages API adapter.
+ */
+async function callAnthropicAPI({ baseUrl, apiKey, model, system, user, temperature, maxTokens, timeoutMs }) {
+  return await executeAIRequest(async () => {
+    const url = `${baseUrl}/v1/messages`;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const body = {
+        model: model || "claude-sonnet-4-20250514",
+        max_tokens: maxTokens,
+        system,
+        messages: [{ role: "user", content: user }],
+      };
+      if (temperature != null) {
+        body.temperature = temperature;
+      }
+
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": apiKey,
+          "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Anthropic API error (${response.status}): ${errorText}`);
+      }
+
+      const data = await response.json();
+
+      if (!data.content || data.content.length === 0) {
+        throw new Error("No content returned from Anthropic API");
+      }
+
+      return data.content[0].text;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        throw new Error(`Request timeout after ${timeoutMs}ms`);
+      }
+      throw error;
+    }
+  });
+}
+
+/**
+ * Google Gemini API adapter.
+ */
+async function callGoogleAPI({ baseUrl, apiKey, model, system, user, temperature, maxTokens, timeoutMs }) {
+  return await executeAIRequest(async () => {
+    const geminiModel = model || "gemini-pro";
+    const url = `${baseUrl}/v1beta/models/${geminiModel}:generateContent?key=${encodeURIComponent(apiKey)}`;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const body = {
+        contents: [{ parts: [{ text: `${system}\n\n${user}` }] }],
+        generationConfig: { maxOutputTokens: maxTokens },
+      };
+      if (temperature != null) {
+        body.generationConfig.temperature = temperature;
+      }
+
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Google API error (${response.status}): ${errorText}`);
+      }
+
+      const data = await response.json();
+
+      if (!data.candidates || data.candidates.length === 0) {
+        throw new Error("No candidates returned from Google API");
+      }
+
+      return data.candidates[0].content.parts[0].text;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        throw new Error(`Request timeout after ${timeoutMs}ms`);
+      }
+      throw error;
+    }
+  });
+}
+
 export function isAIEnabled() {
   return process.env.REPOLENS_AI_ENABLED === "true";
 }
 
 export function getAIConfig() {
+  const provider = process.env.REPOLENS_AI_PROVIDER || "openai_compatible";
+  const defaultModel = provider === "anthropic" ? "claude-sonnet-4-20250514"
+    : provider === "google" ? "gemini-pro"
+    : "gpt-5-mini";
   return {
     enabled: isAIEnabled(),
-    provider: process.env.REPOLENS_AI_PROVIDER || "openai_compatible",
-    model: process.env.REPOLENS_AI_MODEL || "gpt-5-mini",
+    provider,
+    model: process.env.REPOLENS_AI_MODEL || defaultModel,
     hasApiKey: !!process.env.REPOLENS_AI_API_KEY,
     temperature: process.env.REPOLENS_AI_TEMPERATURE ? parseFloat(process.env.REPOLENS_AI_TEMPERATURE) : undefined,
     maxTokens: parseInt(process.env.REPOLENS_AI_MAX_TOKENS || DEFAULT_MAX_TOKENS)

package/src/analyzers/codeowners.js

@@ -0,0 +1,146 @@
+// CODEOWNERS file parser
+// Maps file paths to team/individual owners
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { info } from "../utils/logger.js";
+
+/**
+ * Parse CODEOWNERS file and return ownership rules.
+ * Searches standard locations: CODEOWNERS, .github/CODEOWNERS, docs/CODEOWNERS
+ */
+export async function parseCodeowners(repoRoot) {
+  const locations = [
+    path.join(repoRoot, "CODEOWNERS"),
+    path.join(repoRoot, ".github", "CODEOWNERS"),
+    path.join(repoRoot, "docs", "CODEOWNERS"),
+  ];
+
+  for (const loc of locations) {
+    try {
+      const content = await fs.readFile(loc, "utf8");
+      const rules = parseRules(content);
+      if (rules.length > 0) {
+        info(`CODEOWNERS loaded from ${path.relative(repoRoot, loc)} (${rules.length} rules)`);
+        return { found: true, file: path.relative(repoRoot, loc), rules };
+      }
+    } catch {
+      // File doesn't exist, try next
+    }
+  }
+
+  return { found: false, file: null, rules: [] };
+}
+
+/**
+ * Parse CODEOWNERS content into pattern→owners rules.
+ */
+function parseRules(content) {
+  const rules = [];
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const parts = trimmed.split(/\s+/);
+    if (parts.length < 2) continue;
+
+    const pattern = parts[0];
+    const owners = parts.slice(1).filter(o => o.startsWith("@") || o.includes("@"));
+
+    if (owners.length > 0) {
+      rules.push({ pattern, owners });
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Find owners for a given file path using CODEOWNERS rules.
+ * Rules are matched last-match-wins (same as GitHub behavior).
+ */
+export function findOwners(filePath, rules) {
+  let matched = [];
+
+  for (const rule of rules) {
+    if (matchPattern(filePath, rule.pattern)) {
+      matched = rule.owners;
+    }
+  }
+
+  return matched;
+}
+
+/**
+ * Match a file path against a CODEOWNERS pattern.
+ * Supports: *, **, directory patterns, exact matches.
+ */
+function matchPattern(filePath, pattern) {
+  const normalized = filePath.replace(/\\/g, "/");
+
+  // Remove leading slash for consistency
+  const cleanPattern = pattern.startsWith("/") ? pattern.slice(1) : pattern;
+
+  // Directory pattern (e.g., "src/")
+  if (cleanPattern.endsWith("/")) {
+    return normalized.startsWith(cleanPattern) || normalized.includes(`/${cleanPattern}`);
+  }
+
+  // Convert glob to regex
+  let regex = cleanPattern
+    .replace(/\./g, "\\.")
+    .replace(/\*\*/g, "<<DOUBLESTAR>>")
+    .replace(/\*/g, "[^/]*")
+    .replace(/<<DOUBLESTAR>>/g, ".*");
+
+  // If pattern has no path separator, match anywhere in path
+  if (!cleanPattern.includes("/")) {
+    regex = `(^|/)${regex}($|/)`;
+  } else {
+    regex = `(^|/)${regex}$`;
+  }
+
+  try {
+    return new RegExp(regex).test(normalized);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build an ownership summary for modules.
+ * Returns a map of modulePath → owners[].
+ */
+export function buildOwnershipMap(modules, files, rules) {
+  if (!rules || rules.length === 0) return {};
+
+  const ownershipMap = {};
+
+  for (const mod of modules) {
+    const moduleFiles = files.filter(f => {
+      const normalized = f.replace(/\\/g, "/");
+      return normalized.startsWith(mod.key + "/") || normalized === mod.key;
+    });
+
+    // Find owners for representative files in this module
+    const ownerCounts = {};
+    for (const file of moduleFiles) {
+      const owners = findOwners(file, rules);
+      for (const owner of owners) {
+        ownerCounts[owner] = (ownerCounts[owner] || 0) + 1;
+      }
+    }
+
+    // Primary owners are those who own the most files in this module
+    const sortedOwners = Object.entries(ownerCounts)
+      .sort((a, b) => b[1] - a[1])
+      .map(([owner]) => owner);
+
+    if (sortedOwners.length > 0) {
+      ownershipMap[mod.key] = sortedOwners;
+    }
+  }
+
+  return ownershipMap;
+}

package/src/analyzers/context-builder.js

@@ -80,7 +80,17 @@ export function buildAIContext(scanResult, config) {
     
     patterns,
     
-    repoRoots: config.module_roots || []
+    repoRoots: config.module_roots || [],
+
+    // Monorepo workspace metadata (if detected)
+    monorepo: scanResult.monorepo?.isMonorepo ? {
+      tool: scanResult.monorepo.tool,
+      packageCount: scanResult.monorepo.packages.length,
+      packages: scanResult.monorepo.packages.slice(0, 20).map(p => ({
+        name: p.name,
+        path: p.path,
+      })),
+    } : undefined,
   };
 }
 

package/src/analyzers/monorepo-detector.js

@@ -0,0 +1,155 @@
+// Monorepo workspace detection
+// Detects npm/yarn workspaces, pnpm workspaces, and Lerna configurations
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { info } from "../utils/logger.js";
+
+/**
+ * Detect monorepo workspaces in a repository.
+ * Returns { isMonorepo, tool, packages[] } where each package has { name, path, packageJson }.
+ */
+export async function detectMonorepo(repoRoot) {
+  const result = { isMonorepo: false, tool: null, packages: [] };
+
+  // 1. Check package.json workspaces (npm/yarn)
+  const npmWorkspaces = await detectNpmWorkspaces(repoRoot);
+  if (npmWorkspaces.length > 0) {
+    result.isMonorepo = true;
+    result.tool = "npm/yarn workspaces";
+    result.packages = npmWorkspaces;
+    info(`Monorepo detected: ${result.tool} with ${result.packages.length} packages`);
+    return result;
+  }
+
+  // 2. Check pnpm-workspace.yaml
+  const pnpmWorkspaces = await detectPnpmWorkspaces(repoRoot);
+  if (pnpmWorkspaces.length > 0) {
+    result.isMonorepo = true;
+    result.tool = "pnpm workspaces";
+    result.packages = pnpmWorkspaces;
+    info(`Monorepo detected: ${result.tool} with ${result.packages.length} packages`);
+    return result;
+  }
+
+  // 3. Check lerna.json
+  const lernaPackages = await detectLerna(repoRoot);
+  if (lernaPackages.length > 0) {
+    result.isMonorepo = true;
+    result.tool = "Lerna";
+    result.packages = lernaPackages;
+    info(`Monorepo detected: ${result.tool} with ${result.packages.length} packages`);
+    return result;
+  }
+
+  return result;
+}
+
+async function detectNpmWorkspaces(repoRoot) {
+  try {
+    const pkgPath = path.join(repoRoot, "package.json");
+    const raw = await fs.readFile(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+
+    if (!pkg.workspaces) return [];
+
+    // workspaces can be an array or { packages: [...] }
+    const patterns = Array.isArray(pkg.workspaces)
+      ? pkg.workspaces
+      : pkg.workspaces.packages || [];
+
+    return await resolveWorkspacePatterns(repoRoot, patterns);
+  } catch {
+    return [];
+  }
+}
+
+async function detectPnpmWorkspaces(repoRoot) {
+  try {
+    const yamlPath = path.join(repoRoot, "pnpm-workspace.yaml");
+    const raw = await fs.readFile(yamlPath, "utf8");
+
+    // Simple YAML parsing for packages array (avoid adding js-yaml dependency for this)
+    const patterns = [];
+    let inPackages = false;
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed === "packages:") {
+        inPackages = true;
+        continue;
+      }
+      if (inPackages) {
+        if (trimmed.startsWith("- ")) {
+          patterns.push(trimmed.slice(2).replace(/['"]/g, "").trim());
+        } else if (trimmed && !trimmed.startsWith("#")) {
+          break; // End of packages list
+        }
+      }
+    }
+
+    return await resolveWorkspacePatterns(repoRoot, patterns);
+  } catch {
+    return [];
+  }
+}
+
+async function detectLerna(repoRoot) {
+  try {
+    const lernaPath = path.join(repoRoot, "lerna.json");
+    const raw = await fs.readFile(lernaPath, "utf8");
+    const lerna = JSON.parse(raw);
+
+    const patterns = lerna.packages || ["packages/*"];
+    return await resolveWorkspacePatterns(repoRoot, patterns);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve workspace glob patterns to actual package directories.
+ */
+async function resolveWorkspacePatterns(repoRoot, patterns) {
+  const packages = [];
+  const seen = new Set();
+
+  for (const pattern of patterns) {
+    // Convert glob pattern to directory search
+    // e.g. "packages/*" → list dirs in packages/
+    const basePath = pattern.replace(/\/?\*.*$/, "");
+    const searchDir = path.join(repoRoot, basePath);
+
+    try {
+      const entries = await fs.readdir(searchDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+
+        const pkgDir = path.join(searchDir, entry.name);
+        const pkgJsonPath = path.join(pkgDir, "package.json");
+
+        try {
+          const raw = await fs.readFile(pkgJsonPath, "utf8");
+          const pkg = JSON.parse(raw);
+          const relativePath = path.relative(repoRoot, pkgDir).replace(/\\/g, "/");
+
+          if (!seen.has(relativePath)) {
+            seen.add(relativePath);
+            packages.push({
+              name: pkg.name || entry.name,
+              path: relativePath,
+              version: pkg.version,
+              dependencies: Object.keys(pkg.dependencies || {}),
+              devDependencies: Object.keys(pkg.devDependencies || {}),
+            });
+          }
+        } catch {
+          // No package.json in this directory, skip
+        }
+      }
+    } catch {
+      // Directory doesn't exist, skip
+    }
+  }
+
+  return packages;
+}

package/src/core/scan.js

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { info, warn } from "../utils/logger.js";
 import { trackScan } from "../utils/telemetry.js";
+import { detectMonorepo } from "../analyzers/monorepo-detector.js";
 
 const norm = (p) => p.replace(/\\/g, "/");
 
@@ -403,6 +404,9 @@ export async function scanRepo(cfg) {
   // Detect external API integrations
   const externalApis = await detectExternalApis(files, repoRoot);
 
+  // Detect monorepo workspaces
+  const monorepo = await detectMonorepo(repoRoot);
+
   const scanResult = {
     filesCount: files.length,
     modules,
@@ -410,6 +414,7 @@ export async function scanRepo(cfg) {
     pages,
     metadata,
     externalApis,
+    monorepo,
     _files: files
   };
   

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

@@ -6,6 +6,7 @@ import { analyzeGraphQL } from "../analyzers/graphql-analyzer.js";
 import { analyzeTypeScript } from "../analyzers/typescript-analyzer.js";
 import { analyzeDependencyGraph } from "../analyzers/dependency-graph.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";
 import {
   generateExecutiveSummary,
@@ -53,6 +54,12 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   const driftResult = detectDrift(baseline, snapshot);
   // Save current snapshot as new baseline
   await saveBaseline(snapshot, outputDir);
+
+  // CODEOWNERS integration
+  const codeowners = await parseCodeowners(repoRoot);
+  const ownershipMap = codeowners.found
+    ? buildOwnershipMap(scanResult.modules, scanFiles, codeowners.rules)
+    : {};
   
   // Get active documents based on config
   const activeDocuments = getActiveDocuments(config);
@@ -68,6 +75,8 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
     typescript: tsResult.detected ? tsResult : undefined,
     dependencyGraph: depGraph.stats,
     drift: driftResult,
+    codeowners: codeowners.found ? { file: codeowners.file, ruleCount: codeowners.rules.length } : undefined,
+    ownershipMap: Object.keys(ownershipMap).length > 0 ? ownershipMap : undefined,
   };
   
   // Run afterScan hook
@@ -92,6 +101,7 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
         tsResult,
         depGraph,
         driftResult,
+        ownershipMap,
         pluginManager,
       });
       
@@ -162,7 +172,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, pluginManager } = context;
+  const { scanResult, config, aiContext, moduleContext, flows, diffData, graphqlResult, tsResult, depGraph, driftResult, ownershipMap, pluginManager } = context;
   
   switch (key) {
     case "executive_summary":
@@ -178,8 +188,8 @@ async function generateDocument(docPlan, context) {
       return await generateArchitectureOverview(aiContext);
       
     case "module_catalog":
-      // Hybrid: deterministic skeleton + AI enhancement (for now, just deterministic)
-      return renderModuleCatalogOriginal(config, scanResult);
+      // Hybrid: deterministic skeleton + ownership info
+      return renderModuleCatalogOriginal(config, scanResult, ownershipMap);
       
     case "route_map":
       // Hybrid: deterministic skeleton + AI enhancement (for now, just deterministic)

package/src/publishers/index.js

@@ -6,6 +6,7 @@ import { shouldPublishToNotion, shouldPublishToConfluence, shouldPublishToGitHub
 import { info, warn } from "../utils/logger.js";
 import { trackPublishing } from "../utils/telemetry.js";
 import { collectMetrics } from "../utils/metrics.js";
+import { loadDocCache, saveDocCache, filterChangedDocs, logCacheStats } from "../utils/doc-cache.js";
 import {
   sendDiscordNotification,
   buildDocUpdateNotification,
@@ -24,6 +25,15 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
   let publishStatus = "success";
   let notionUrl = null;
 
+  // --- Hash-based caching: skip unchanged documents ---
+  const cacheDir = path.join(process.cwd(), cfg.documentation?.output_dir || ".repolens");
+  const previousCache = await loadDocCache(cacheDir);
+  const { changedPages, unchangedKeys, newCache } = filterChangedDocs(renderedPages, previousCache);
+  logCacheStats(Object.keys(changedPages).length, unchangedKeys.length);
+
+  // Use changedPages for API publishers (Notion / Confluence / Wiki), full set for Markdown
+  const pagesForAPIs = Object.keys(changedPages).length > 0 ? changedPages : renderedPages;
+
   // Always try Notion publishing if secrets are configured
   if (publishers.includes("notion") || hasNotionSecrets()) {
     if (!hasNotionSecrets()) {
@@ -32,7 +42,7 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
     } else if (shouldPublishToNotion(cfg, currentBranch)) {
       info(`Publishing to Notion from branch: ${currentBranch}`);
       try {
-        await publishToNotion(cfg, renderedPages);
+        await publishToNotion(cfg, pagesForAPIs);
         publishedTo.push("notion");
         // Build Notion URL if published
         if (process.env.NOTION_PARENT_PAGE_ID) {
@@ -57,7 +67,7 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
     } else if (shouldPublishToConfluence(cfg, currentBranch)) {
       info(`Publishing to Confluence from branch: ${currentBranch}`);
       try {
-        await publishToConfluence(cfg, renderedPages);
+        await publishToConfluence(cfg, pagesForAPIs);
         publishedTo.push("confluence");
       } catch (err) {
         publishStatus = "failure";
@@ -89,7 +99,7 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
     } else if (shouldPublishToGitHubWiki(cfg, currentBranch)) {
       info(`Publishing to GitHub Wiki from branch: ${currentBranch}`);
       try {
-        await publishToGitHubWiki(cfg, renderedPages);
+        await publishToGitHubWiki(cfg, pagesForAPIs);
         publishedTo.push("github_wiki");
       } catch (err) {
         publishStatus = "failure";
@@ -119,6 +129,9 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
     }
   }
 
+  // Save document hash cache for next run
+  await saveDocCache(cacheDir, newCache);
+
   // Collect metrics and send Discord notification
   try {
     info("Collecting documentation metrics...");

package/src/renderers/render.js

@@ -76,6 +76,25 @@ export function renderSystemOverview(cfg, scan) {
     lines.push(``);
   }
 
+  // Monorepo workspace info
+  if (scan.monorepo?.isMonorepo && scan.monorepo.packages.length > 0) {
+    lines.push(
+      `## Monorepo Workspaces`,
+      ``,
+      `This repository is organized as a **monorepo** using **${scan.monorepo.tool}** with **${scan.monorepo.packages.length} packages**.`,
+      ``,
+      `| Package | Path | Version |`,
+      `|---------|------|---------|`
+    );
+    for (const pkg of scan.monorepo.packages.slice(0, 20)) {
+      lines.push(`| ${pkg.name} | \`${pkg.path}\` | ${pkg.version || "—"} |`);
+    }
+    if (scan.monorepo.packages.length > 20) {
+      lines.push(`| ... | *${scan.monorepo.packages.length - 20} more packages* | |`);
+    }
+    lines.push(``);
+  }
+
   lines.push(
     `---`,
     ``,
@@ -114,7 +133,8 @@ function describeModule(key) {
   return "Application module";
 }
 
-export function renderModuleCatalog(cfg, scan) {
+export function renderModuleCatalog(cfg, scan, ownershipMap = {}) {
+  const hasOwnership = Object.keys(ownershipMap).length > 0;
   const lines = [
     `# Module Catalog`,
     ``,
@@ -136,14 +156,29 @@ export function renderModuleCatalog(cfg, scan) {
 
   lines.push(
     `## Module Inventory`,
-    ``,
-    `| Module | Files | Role |`,
-    `|--------|-------|------|`
+    ``
   );
 
+  if (hasOwnership) {
+    lines.push(
+      `| Module | Files | Role | Owners |`,
+      `|--------|-------|------|--------|`
+    );
+  } else {
+    lines.push(
+      `| Module | Files | Role |`,
+      `|--------|-------|------|`
+    );
+  }
+
   for (const module of scan.modules.slice(0, 100)) {
     const desc = describeModule(module.key);
-    lines.push(`| \`${module.key}\` | ${module.fileCount} | ${desc} |`);
+    const owners = ownershipMap[module.key];
+    if (hasOwnership) {
+      lines.push(`| \`${module.key}\` | ${module.fileCount} | ${desc} | ${owners ? owners.join(", ") : "—"} |`);
+    } else {
+      lines.push(`| \`${module.key}\` | ${module.fileCount} | ${desc} |`);
+    }
   }
 
   if (scan.modules.length > 100) {

package/src/utils/doc-cache.js

@@ -0,0 +1,78 @@
+/**
+ * Hash-based document cache.
+ * Compares rendered content hashes to avoid redundant publisher API calls.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { info } from "./logger.js";
+
+const CACHE_FILENAME = "doc-hashes.json";
+
+/**
+ * Hash a string using SHA-256.
+ */
+function hashContent(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+/**
+ * Load the previous cache from disk.
+ * @returns {Record<string, string>} Map of docKey → contentHash
+ */
+export async function loadDocCache(cacheDir) {
+  try {
+    const raw = await fs.readFile(path.join(cacheDir, CACHE_FILENAME), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save the cache to disk.
+ */
+export async function saveDocCache(cacheDir, cache) {
+  await fs.mkdir(cacheDir, { recursive: true });
+  await fs.writeFile(
+    path.join(cacheDir, CACHE_FILENAME),
+    JSON.stringify(cache, null, 2),
+    "utf8"
+  );
+}
+
+/**
+ * Filter rendered pages to only those whose content has changed.
+ * Returns { changedPages, unchangedKeys, newCache }.
+ */
+export function filterChangedDocs(renderedPages, previousCache) {
+  const newCache = {};
+  const changedPages = {};
+  const unchangedKeys = [];
+
+  for (const [key, content] of Object.entries(renderedPages)) {
+    const hash = hashContent(content);
+    newCache[key] = hash;
+
+    if (previousCache[key] === hash) {
+      unchangedKeys.push(key);
+    } else {
+      changedPages[key] = content;
+    }
+  }
+
+  return { changedPages, unchangedKeys, newCache };
+}
+
+/**
+ * Log cache statistics.
+ */
+export function logCacheStats(changedCount, unchangedCount) {
+  const total = changedCount + unchangedCount;
+  if (unchangedCount > 0) {
+    info(`Cache: ${unchangedCount}/${total} documents unchanged, skipping. ${changedCount} to publish.`);
+  } else {
+    info(`Cache: All ${total} documents changed or new.`);
+  }
+}