@chappibunny/repolens 0.4.1

package/src/ai/prompts.js

@@ -0,0 +1,312 @@
+// Strict prompt templates for AI-generated documentation sections
+
+export const SYSTEM_PROMPT = `You are a senior software architect and technical writer.
+Your job is to turn structured repository analysis into clear documentation.
+
+Rules:
+- Use only the supplied context.
+- Never invent files, modules, routes, APIs, or business capabilities.
+- If context is insufficient, say so briefly and continue with what is known.
+- Write for mixed audiences when requested.
+- Prefer clear prose and short sections over bullet spam.
+- Be concrete and practical.
+- Output valid markdown only.
+- Do not mention AI, LLMs, or that you are an assistant.
+- No markdown tables unless specifically requested.
+- Use simple formatting: headings, paragraphs, lists.
+- Maximum 2 heading levels deep within sections.`;
+
+export function createExecutiveSummaryPrompt(context) {
+  return `Write an executive summary for a mixed audience of technical and non-technical readers.
+
+Use this context:
+${JSON.stringify(context, null, 2)}
+
+Requirements:
+- Explain what the system appears to do based on the modules and routes.
+- Explain the main system areas using the domain information.
+- Explain the business capabilities implied by the codebase structure.
+- Mention key external dependencies only if they are present in the context.
+- Mention architectural or operational risks if they are strongly supported by the context.
+- Do not mention file counts more than once.
+- Maximum 500 words.
+- Use this structure:
+
+# Executive Summary
+
+## What this system does
+
+## Who it serves
+
+## Core capabilities
+
+## Main system areas
+
+## Key dependencies
+
+## Operational and architectural risks
+
+## Recommended focus areas`;
+}
+
+export function createSystemOverviewPrompt(context) {
+  return `Write a system overview for a mixed audience.
+
+Use this context:
+${JSON.stringify(context, null, 2)}
+
+Requirements:
+- Provide a concise, high-level orientation to the codebase.
+- Technical enough for developers, readable enough for everyone else.
+- Focus on what is observable from the structure.
+- Maximum 400 words.
+- Use this structure:
+
+# System Overview
+
+## Repository snapshot
+
+## Main architectural layers
+
+## Dominant domains
+
+## Main technology patterns
+
+## Where most logic lives
+
+## Key observations`;
+}
+
+export function createBusinessDomainsPrompt(context) {
+  return `Write business domain documentation for a mixed audience, especially non-technical readers.
+
+Use this context:
+${JSON.stringify(context, null, 2)}
+
+Requirements:
+- Translate codebase structure into business language.
+- For each domain in the context, explain:
+  - Business responsibility
+  - Main directories/modules
+  - Dependencies
+  - User-visible functionality (inferred from structure)
+- Maximum 150 words per domain.
+- Use this structure:
+
+# Business Domains
+
+## Domain: [Name]
+
+[Business explanation]
+
+Main modules:
+- [module paths]
+
+User-visible functionality:
+[what users can do]
+
+Dependencies:
+[other domains this depends on]`;
+}
+
+export function createArchitectureOverviewPrompt(context) {
+  return `Write an architecture overview for engineers, architects, and technical PMs.
+
+Use this context:
+${JSON.stringify(context, null, 2)}
+
+Requirements:
+- Explain the layered architecture based on observable patterns.
+- Describe flows across layers.
+- Be specific about what is present in the context.
+- Maximum 600 words.
+- Use this structure:
+
+# Architecture Overview
+
+## Architecture style
+
+## Application layer
+
+## UI / component layer
+
+## Domain / service layer
+
+## Data / integration layer
+
+## Cross-cutting concerns
+
+## Dependency flow
+
+## Architectural strengths
+
+## Architectural weaknesses`;
+}
+
+export function createDataFlowsPrompt(flows, context) {
+  return `Write data flow documentation for a mixed audience.
+
+Use this flow information:
+${JSON.stringify(flows, null, 2)}
+
+And this context:
+${JSON.stringify(context, null, 2)}
+
+Requirements:
+- Explain major information flows in plain language.
+- For each flow, describe the journey from user action to system response.
+- Be concrete about which modules are involved.
+- Maximum 200 words per flow.
+- Use this structure:
+
+# Data Flows
+
+## [Flow Name]
+
+[Plain language description of the flow]
+
+Flow steps:
+[numbered steps]
+
+Involved modules:
+- [module paths]
+
+Critical dependencies:
+[what this flow depends on]`;
+}
+
+export function createDeveloperOnboardingPrompt(context) {
+  return `Write developer onboarding documentation to help new engineers get productive quickly.
+
+Use this context:
+${JSON.stringify(context, null, 2)}
+
+Requirements:
+- Guide new developers through the codebase structure.
+- Point out the most important folders and files.
+- Explain core product flows.
+- Highlight complexity hotspots.
+- Be practical and actionable.
+- Maximum 800 words.
+- Use this structure:
+
+# Developer Onboarding
+
+## Start here
+
+## Main folders
+
+## Core product flows
+
+## Important routes
+
+## Important shared libraries
+
+## Common change areas
+
+## What to understand first
+
+## Known complexity hotspots`;
+}
+
+export function createModuleSummaryPrompt(module, context) {
+  return `Write a short module documentation section.
+
+Module: ${module.key}
+File count: ${module.fileCount}
+Type: ${module.type}
+Domain: ${module.domain}
+
+Additional context:
+${JSON.stringify(context, null, 2)}
+
+Requirements:
+- Explain the module's likely purpose.
+- List concrete responsibilities.
+- Mention important dependencies from context.
+- Mention complexity or centrality if supported.
+- No speculation beyond the provided context.
+- Maximum 180 words.
+- Use this structure:
+
+## ${module.key}
+
+Purpose:
+[brief explanation]
+
+Responsibilities:
+- [concrete responsibilities]
+
+Main dependencies:
+[from context]
+
+Complexity notes:
+[if applicable]`;
+}
+
+export function createRouteSummaryPrompt(route, context) {
+  return `Write a route documentation section.
+
+Route: ${route.path}
+File: ${route.file}
+Type: ${route.type}
+
+Additional context:
+${JSON.stringify(context, null, 2)}
+
+Requirements:
+- Explain the user purpose of this route.
+- Explain the technical role.
+- Mention main dependencies.
+- Maximum 120 words.
+- Use this structure:
+
+## ${route.path}
+
+User purpose:
+[what users do here]
+
+Technical role:
+[what this route does]
+
+Main dependencies:
+[modules this uses]
+
+Notes:
+[any important observations]`;
+}
+
+export function createAPIDocumentationPrompt(api, context) {
+  return `Write API endpoint documentation.
+
+API: ${api.methods.join(", ")} ${api.path}
+File: ${api.file}
+
+Additional context:
+${JSON.stringify(context, null, 2)}
+
+Requirements:
+- Explain the purpose in plain language and technical language.
+- Describe what it returns or does.
+- Mention dependencies and integrations.
+- Mention risks if any are apparent.
+- Maximum 150 words.
+- Use this structure:
+
+## ${api.methods.join(", ")} ${api.path}
+
+Purpose:
+[plain language explanation]
+
+Source file:
+${api.file}
+
+Used by:
+[routes or components]
+
+Dependencies:
+[external services or internal modules]
+
+Risks:
+[if applicable]`;
+}

package/src/ai/provider.js

@@ -0,0 +1,134 @@
+// Provider-agnostic AI text generation
+
+import { warn, info } from "../utils/logger.js";
+
+const DEFAULT_TIMEOUT_MS = 60000;
+const DEFAULT_TEMPERATURE = 0.2;
+const DEFAULT_MAX_TOKENS = 2500;
+
+export async function generateText({ system, user, temperature, maxTokens }) {
+  // Check if AI is enabled
+  const enabled = process.env.REPOLENS_AI_ENABLED === "true";
+  
+  if (!enabled) {
+    return {
+      success: false,
+      error: "AI features are disabled. Set REPOLENS_AI_ENABLED=true to enable.",
+      fallback: true
+    };
+  }
+  
+  // Get provider configuration from environment
+  const provider = process.env.REPOLENS_AI_PROVIDER || "openai_compatible";
+  const baseUrl = process.env.REPOLENS_AI_BASE_URL;
+  const apiKey = process.env.REPOLENS_AI_API_KEY;
+  const model = process.env.REPOLENS_AI_MODEL || "gpt-4-turbo-preview";
+  const timeoutMs = parseInt(process.env.REPOLENS_AI_TIMEOUT_MS || DEFAULT_TIMEOUT_MS);
+  
+  // Validate configuration
+  if (!apiKey) {
+    warn("REPOLENS_AI_API_KEY not set. AI features disabled.");
+    return {
+      success: false,
+      error: "Missing API key",
+      fallback: true
+    };
+  }
+  
+  if (!baseUrl && provider === "openai_compatible") {
+    warn("REPOLENS_AI_BASE_URL not set. Using OpenAI default.");
+  }
+  
+  try {
+    const result = await callOpenAICompatibleAPI({
+      baseUrl: baseUrl || "https://api.openai.com/v1",
+      apiKey,
+      model,
+      system,
+      user,
+      temperature: temperature ?? DEFAULT_TEMPERATURE,
+      maxTokens: maxTokens ?? DEFAULT_MAX_TOKENS,
+      timeoutMs
+    });
+    
+    return {
+      success: true,
+      text: result,
+      fallback: false
+    };
+    
+  } catch (error) {
+    warn(`AI generation failed: ${error.message}`);
+    return {
+      success: false,
+      error: error.message,
+      fallback: true
+    };
+  }
+}
+
+async function callOpenAICompatibleAPI({ baseUrl, apiKey, model, system, user, temperature, maxTokens, timeoutMs }) {
+  const url = `${baseUrl}/chat/completions`;
+  
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: "system", content: system },
+          { role: "user", content: user }
+        ],
+        temperature,
+        max_tokens: maxTokens
+      }),
+      signal: controller.signal
+    });
+    
+    clearTimeout(timeoutId);
+    
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`API error (${response.status}): ${errorText}`);
+    }
+    
+    const data = await response.json();
+    
+    if (!data.choices || data.choices.length === 0) {
+      throw new Error("No completion returned from API");
+    }
+    
+    return data.choices[0].message.content;
+    
+  } 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() {
+  return {
+    enabled: isAIEnabled(),
+    provider: process.env.REPOLENS_AI_PROVIDER || "openai_compatible",
+    model: process.env.REPOLENS_AI_MODEL || "gpt-4-turbo-preview",
+    hasApiKey: !!process.env.REPOLENS_AI_API_KEY,
+    temperature: parseFloat(process.env.REPOLENS_AI_TEMPERATURE || DEFAULT_TEMPERATURE),
+    maxTokens: parseInt(process.env.REPOLENS_AI_MAX_TOKENS || DEFAULT_MAX_TOKENS)
+  };
+}

package/src/analyzers/context-builder.js

@@ -0,0 +1,146 @@
+// Build structured AI context from deterministic scan results
+
+import { groupModulesByDomain } from "./domain-inference.js";
+
+export function buildAIContext(scanResult, config) {
+  const { filesCount, modules, api, pages, metadata } = scanResult;
+  
+  // Get domain hints from config if available
+  const customHints = config.domains 
+    ? Object.entries(config.domains).map(([key, domain]) => ({
+        match: domain.match || [],
+        domain: key,
+        description: domain.description || key
+      }))
+    : [];
+  
+  // Group modules by business domain
+  const domainGroups = groupModulesByDomain(modules, customHints);
+  
+  // Identify top modules
+  const topModules = modules
+    .slice(0, 15)
+    .map(m => ({
+      key: m.key,
+      fileCount: m.fileCount,
+      type: inferModuleType(m.key)
+    }));
+  
+  // Categorize routes
+  const pageRoutes = pages?.slice(0, 50).map(p => ({
+    path: p.path,
+    file: p.file,
+    type: "page"
+  })) || [];
+  
+  const apiRoutes = api?.slice(0, 50).map(a => ({
+    path: a.path,
+    file: a.file,
+    methods: a.methods,
+    type: "api"
+  })) || [];
+  
+  // Build technology profile
+  const techStack = {
+    frameworks: metadata?.frameworks || [],
+    languages: metadata?.languages ? [...metadata.languages] : [],
+    buildTools: metadata?.buildTools || [],
+    testFrameworks: metadata?.testFrameworks || []
+  };
+  
+  // Identify key architectural patterns
+  const patterns = inferArchitecturalPatterns(modules);
+  
+  // Build compact context object
+  return {
+    project: {
+      name: config.project.name,
+      filesScanned: filesCount,
+      modulesDetected: modules.length,
+      pagesDetected: pages?.length || 0,
+      apiRoutesDetected: api?.length || 0
+    },
+    
+    domains: domainGroups.map(d => ({
+      name: d.name,
+      description: d.description,
+      moduleCount: d.modules.length,
+      fileCount: d.totalFiles,
+      topModules: d.modules.slice(0, 5).map(m => m.key)
+    })),
+    
+    topModules,
+    
+    routes: {
+      pages: pageRoutes,
+      apis: apiRoutes
+    },
+    
+    techStack,
+    
+    patterns,
+    
+    repoRoots: config.module_roots || []
+  };
+}
+
+function inferModuleType(modulePath) {
+  const lower = modulePath.toLowerCase();
+  
+  if (lower.includes("api")) return "api";
+  if (lower.includes("component")) return "ui";
+  if (lower.includes("lib") || lower.includes("util")) return "library";
+  if (lower.includes("hook")) return "hooks";
+  if (lower.includes("store") || lower.includes("state")) return "state";
+  if (lower.includes("page") || lower.includes("route")) return "route";
+  if (lower.includes("app")) return "app";
+  
+  return "other";
+}
+
+function inferArchitecturalPatterns(modules) {
+  const patterns = [];
+  
+  const hasAppRouter = modules.some(m => m.key.includes("app/"));
+  const hasPagesRouter = modules.some(m => m.key.includes("pages/"));
+  const hasComponents = modules.some(m => m.key.includes("component"));
+  const hasLib = modules.some(m => m.key.includes("lib"));
+  const hasHooks = modules.some(m => m.key.includes("hook"));
+  const hasStore = modules.some(m => m.key.includes("store") || m.key.includes("state"));
+  const hasApi = modules.some(m => m.key.includes("api"));
+  
+  if (hasAppRouter) patterns.push("Next.js App Router");
+  if (hasPagesRouter) patterns.push("Next.js Pages Router");
+  if (hasComponents && hasLib) patterns.push("Layered component architecture");
+  if (hasHooks) patterns.push("React hooks pattern");
+  if (hasStore) patterns.push("Centralized state management");
+  if (hasApi) patterns.push("API route pattern");
+  
+  return patterns;
+}
+
+export function buildModuleContext(modules, config) {
+  const customHints = config.domains 
+    ? Object.entries(config.domains).map(([key, domain]) => ({
+        match: domain.match || [],
+        domain: key,
+        description: domain.description || key
+      }))
+    : [];
+  
+  const domainGroups = groupModulesByDomain(modules, customHints);
+  
+  return modules.map(module => {
+    const domain = domainGroups.find(d => 
+      d.modules.some(m => m.key === module.key)
+    );
+    
+    return {
+      key: module.key,
+      fileCount: module.fileCount,
+      type: inferModuleType(module.key),
+      domain: domain?.name || "Other",
+      domainDescription: domain?.description || "Uncategorized"
+    };
+  });
+}

package/src/analyzers/domain-inference.js

@@ -0,0 +1,127 @@
+// Domain inference - map folder/file names to business domains
+
+const DEFAULT_DOMAIN_HINTS = [
+  { 
+    match: ["auth", "login", "signup", "session", "user", "account"], 
+    domain: "Authentication",
+    description: "User authentication and identity flows"
+  },
+  { 
+    match: ["stock", "chart", "price", "market", "watchlist", "ticker", "quote"], 
+    domain: "Market Data & Analysis",
+    description: "Market data retrieval, analysis, and visualization"
+  },
+  { 
+    match: ["article", "newsletter", "news", "research", "content", "blog", "post"], 
+    domain: "Content & Research",
+    description: "Content publishing, research, and insight delivery"
+  },
+  { 
+    match: ["portfolio", "positions", "holdings", "trades", "orders"], 
+    domain: "Portfolio Management",
+    description: "Portfolio tracking and trading functionality"
+  },
+  { 
+    match: ["alert", "notification", "email", "sms", "webhook"], 
+    domain: "Alerts & Notifications",
+    description: "User notification and alerting system"
+  },
+  { 
+    match: ["payment", "subscription", "billing", "stripe", "checkout"], 
+    domain: "Payments & Billing",
+    description: "Payment processing and subscription management"
+  },
+  { 
+    match: ["api", "endpoint", "route", "handler"], 
+    domain: "API Layer",
+    description: "Backend API endpoints and request handling"
+  },
+  { 
+    match: ["component", "ui", "button", "form", "modal", "dialog"], 
+    domain: "UI Components",
+    description: "Reusable user interface components"
+  },
+  { 
+    match: ["hook", "hooks", "use"], 
+    domain: "React Hooks",
+    description: "Custom React hooks for state and behavior"
+  },
+  { 
+    match: ["store", "state", "redux", "zustand", "context"], 
+    domain: "State Management",
+    description: "Application state management"
+  },
+  { 
+    match: ["lib", "util", "helper", "common", "shared"], 
+    domain: "Shared Utilities",
+    description: "Common utilities and helper functions"
+  },
+  { 
+    match: ["data", "database", "db", "prisma", "sql"], 
+    domain: "Data Layer",
+    description: "Database access and data persistence"
+  }
+];
+
+export function inferDomain(modulePath, customHints = []) {
+  const hints = [...customHints, ...DEFAULT_DOMAIN_HINTS];
+  const lowerPath = modulePath.toLowerCase();
+  
+  for (const hint of hints) {
+    for (const keyword of hint.match) {
+      if (lowerPath.includes(keyword)) {
+        return {
+          domain: hint.domain,
+          description: hint.description,
+          confidence: "pattern_match",
+          matchedKeyword: keyword
+        };
+      }
+    }
+  }
+  
+  return {
+    domain: "Other",
+    description: "Uncategorized module",
+    confidence: "none",
+    matchedKeyword: null
+  };
+}
+
+export function groupModulesByDomain(modules, customHints = []) {
+  const domainGroups = {};
+  
+  for (const module of modules) {
+    const inference = inferDomain(module.key, customHints);
+    const domainName = inference.domain;
+    
+    if (!domainGroups[domainName]) {
+      domainGroups[domainName] = {
+        name: domainName,
+        description: inference.description,
+        modules: [],
+        totalFiles: 0
+      };
+    }
+    
+    domainGroups[domainName].modules.push({
+      ...module,
+      inference
+    });
+    domainGroups[domainName].totalFiles += module.fileCount;
+  }
+  
+  // Sort domains by total files (most important first)
+  const sortedDomains = Object.values(domainGroups)
+    .sort((a, b) => b.totalFiles - a.totalFiles);
+  
+  return sortedDomains;
+}
+
+export function inferRouteDomain(routePath, customHints = []) {
+  return inferDomain(routePath, customHints);
+}
+
+export function inferApiDomain(apiPath, customHints = []) {
+  return inferDomain(apiPath, customHints);
+}