@chappibunny/repolens 0.4.1

package/RELEASE.md

@@ -0,0 +1,52 @@
+# RepoLens Release Process
+
+## Versioning
+
+RepoLens uses semantic versioning:
+
+- Patch: bug fixes, internal cleanup, non-breaking improvements
+- Minor: new features, new commands, new publishers
+- Major: breaking CLI or config changes
+
+## Release Checklist
+
+1. Run tests: `npm test`
+2. Test tarball installation: `npm run test:install`
+3. Verify CLI works:
+   - `repolens --help`
+   - `repolens --version`
+4. Update `CHANGELOG.md`
+5. Bump version in `package.json`
+6. Commit release changes
+7. Tag the release
+8. Push branch and tag
+9. CI validates package installation automatically
+
+## Example Patch Release
+
+```bash
+# 1. Update version
+npm run release:patch  # or :minor, :major
+
+# 2. Run tests
+npm test
+
+# 3. Test installation
+npm run test:install
+
+# 4. Push release
+git push --follow-tags
+
+# 5. Verify GitHub Actions
+# Check: https://github.com/CHAPIBUNNY/repolens/actions
+```
+
+## Testing Upgrade Path
+
+To test that users can upgrade successfully:
+
+```bash
+# In a test project
+npx repolens@latest --version
+npx repolens@latest publish
+```

package/bin/repolens.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/cli.js";

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@chappibunny/repolens",
+  "version": "0.4.1",
+  "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/cli.js",
+  "bin": {
+    "repolens": "./bin/repolens.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "package.json",
+    "README.md",
+    "CHANGELOG.md",
+    "RELEASE.md"
+  ],
+  "keywords": [
+    "cli",
+    "docs",
+    "architecture",
+    "github",
+    "notion",
+    "markdown",
+    "developer-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CHAPIBUNNY/repolens.git"
+  },
+  "homepage": "https://github.com/CHAPIBUNNY/repolens#readme",
+  "bugs": {
+    "url": "https://github.com/CHAPIBUNNY/repolens/issues"
+  },
+  "author": "Charl van Zyl",
+  "scripts": {
+    "test:notion": "node notion-test.js",
+    "publish": "node src/cli.js publish --config ../../.repolens.yml",
+    "init:test": "node src/cli.js init --target /tmp/repolens-init-test",
+    "test": "NODE_ENV=test vitest run --no-watch --reporter=verbose",
+    "pack:check": "npm pack",
+    "release:check": "npm test && npm pack",
+    "test:install": "./test-install.sh",
+    "release:patch": "npm version patch",
+    "release:minor": "npm version minor",
+    "release:major": "npm version major"
+  },
+  "dependencies": {
+    "dotenv": "^17.3.1",
+    "fast-glob": "^3.3.3",
+    "js-yaml": "^4.1.0",
+    "node-fetch": "^3.3.2"
+  },
+  "optionalDependencies": {
+    "@mermaid-js/mermaid-cli": "^11.12.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  }
+}

package/src/ai/document-plan.js

@@ -0,0 +1,133 @@
+// Document plan - defines the canonical document structure
+
+export const DOCUMENT_PLAN = [
+  {
+    key: "executive_summary",
+    filename: "00-executive-summary.md",
+    title: "Executive Summary",
+    audience: "non-technical",
+    ai: true,
+    description: "High-level overview for leadership, product, and stakeholders"
+  },
+  {
+    key: "system_overview",
+    filename: "01-system-overview.md",
+    title: "System Overview",
+    audience: "mixed",
+    ai: true,
+    description: "Concise technical overview readable by all"
+  },
+  {
+    key: "business_domains",
+    filename: "02-business-domains.md",
+    title: "Business Domains",
+    audience: "mixed",
+    ai: true,
+    description: "Codebase structure translated into business language"
+  },
+  {
+    key: "architecture_overview",
+    filename: "03-architecture-overview.md",
+    title: "Architecture Overview",
+    audience: "technical",
+    ai: true,
+    description: "Layered architecture and design patterns"
+  },
+  {
+    key: "module_catalog",
+    filename: "04-module-catalog.md",
+    title: "Module Catalog",
+    audience: "technical",
+    ai: "hybrid",
+    description: "Complete inventory of code modules with AI explanations"
+  },
+  {
+    key: "route_map",
+    filename: "05-route-map.md",
+    title: "Route Map",
+    audience: "mixed",
+    ai: "hybrid",
+    description: "Application routes and API endpoints with context"
+  },
+  {
+    key: "api_surface",
+    filename: "06-api-surface.md",
+    title: "API Surface",
+    audience: "technical",
+    ai: "hybrid",
+    description: "Backend API endpoints with usage examples"
+  },
+  {
+    key: "data_flows",
+    filename: "07-data-flows.md",
+    title: "Data Flows",
+    audience: "mixed",
+    ai: true,
+    description: "Major information flows through the system"
+  },
+  {
+    key: "arch_diff",
+    filename: "08-change-impact.md",
+    title: "Architecture Diff",
+    audience: "mixed",
+    ai: true,
+    description: "Git diff analysis and impact assessment"
+  },
+  {
+    key: "system_map",
+    filename: "09-system-map.md",
+    title: "System Map",
+    audience: "mixed",
+    ai: "hybrid",
+    description: "Visual dependency graph with explanation"
+  },
+  {
+    key: "developer_onboarding",
+    filename: "10-developer-onboarding.md",
+    title: "Developer Onboarding",
+    audience: "technical",
+    ai: true,
+    description: "Quick start guide for new developers"
+  }
+];
+
+export function getDocumentByKey(key) {
+  return DOCUMENT_PLAN.find(doc => doc.key === key);
+}
+
+export function getDocumentsByAudience(audience) {
+  return DOCUMENT_PLAN.filter(doc => doc.audience === audience);
+}
+
+export function getAIDocuments() {
+  return DOCUMENT_PLAN.filter(doc => doc.ai === true || doc.ai === "hybrid");
+}
+
+export function getDeterministicDocuments() {
+  return DOCUMENT_PLAN.filter(doc => !doc.ai);
+}
+
+export function getActiveDocuments(config) {
+  // If config specifies which sections to include, filter by that
+  if (config.documentation?.sections) {
+    return DOCUMENT_PLAN.filter(doc => 
+      config.documentation.sections.includes(doc.key)
+    );
+  }
+  
+  // If features flags exist, respect them
+  if (config.features) {
+    return DOCUMENT_PLAN.filter(doc => {
+      // Always include core docs
+      if (["system_overview", "module_catalog", "route_map"].includes(doc.key)) {
+        return true;
+      }
+      
+      // Check feature flags
+      return config.features[doc.key] !== false;
+    });
+  }
+  
+  // Default: all documents
+  return DOCUMENT_PLAN;
+}

package/src/ai/generate-sections.js

@@ -0,0 +1,271 @@
+// Generate documentation sections using AI
+
+import { generateText, isAIEnabled } from "./provider.js";
+import { 
+  SYSTEM_PROMPT, 
+  createExecutiveSummaryPrompt,
+  createSystemOverviewPrompt,
+  createBusinessDomainsPrompt,
+  createArchitectureOverviewPrompt,
+  createDataFlowsPrompt,
+  createDeveloperOnboardingPrompt,
+  createModuleSummaryPrompt,
+  createRouteSummaryPrompt,
+  createAPIDocumentationPrompt
+} from "./prompts.js";
+import { info, warn } from "../utils/logger.js";
+
+export async function generateExecutiveSummary(context) {
+  if (!isAIEnabled()) {
+    return getFallbackExecutiveSummary(context);
+  }
+  
+  info("Generating executive summary with AI...");
+  
+  const result = await generateText({
+    system: SYSTEM_PROMPT,
+    user: createExecutiveSummaryPrompt(context),
+    temperature: 0.2,
+    maxTokens: 1500
+  });
+  
+  if (!result.success) {
+    warn("AI generation failed, using fallback");
+    return getFallbackExecutiveSummary(context);
+  }
+  
+  return result.text;
+}
+
+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),
+    temperature: 0.2,
+    maxTokens: 1200
+  });
+  
+  if (!result.success) {
+    return getFallbackSystemOverview(context);
+  }
+  
+  return result.text;
+}
+
+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),
+    temperature: 0.2,
+    maxTokens: 2000
+  });
+  
+  if (!result.success) {
+    return getFallbackBusinessDomains(context);
+  }
+  
+  return result.text;
+}
+
+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),
+    temperature: 0.2,
+    maxTokens: 1800
+  });
+  
+  if (!result.success) {
+    return getFallbackArchitectureOverview(context);
+  }
+  
+  return result.text;
+}
+
+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),
+    temperature: 0.2,
+    maxTokens: 1800
+  });
+  
+  if (!result.success) {
+    return getFallbackDataFlows(flows);
+  }
+  
+  return result.text;
+}
+
+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),
+    temperature: 0.2,
+    maxTokens: 2200
+  });
+  
+  if (!result.success) {
+    return getFallbackDeveloperOnboarding(context);
+  }
+  
+  return result.text;
+}
+
+// Fallback generators (deterministic, no AI)
+
+function getFallbackExecutiveSummary(context) {
+  return `# Executive Summary
+
+## What this system does
+
+${context.project.name} is a ${context.techStack.frameworks.join(", ") || "software"} application with ${context.project.modulesDetected} modules across ${context.project.filesScanned} files.
+
+## Main system areas
+
+The codebase is organized into ${context.domains.length} main domains:
+
+${context.domains.map(d => `- ${d.name}: ${d.moduleCount} modules`).join("\n")}
+
+## Technology stack
+
+- Frameworks: ${context.techStack.frameworks.join(", ") || "Not detected"}
+- Languages: ${context.techStack.languages.join(", ") || "Not detected"}
+- Build tools: ${context.techStack.buildTools.join(", ") || "Not detected"}
+
+## Key observations
+
+- ${context.project.pagesDetected} pages detected
+- ${context.project.apiRoutesDetected} API routes detected
+- Architecture patterns: ${context.patterns.join(", ") || "Standard patterns"}
+
+Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+}
+
+function getFallbackSystemOverview(context) {
+  return `# System Overview
+
+## Repository snapshot
+
+- Files scanned: ${context.project.filesScanned}
+- Modules: ${context.project.modulesDetected}
+- Pages: ${context.project.pagesDetected}
+- APIs: ${context.project.apiRoutesDetected}
+
+## Technology patterns
+
+${context.patterns.map(p => `- ${p}`).join("\n")}
+
+## Dominant domains
+
+${context.domains.slice(0, 5).map((d, i) => `${i + 1}. ${d.name} (${d.fileCount} files)`).join("\n")}
+
+Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+}
+
+function getFallbackBusinessDomains(context) {
+  let output = `# Business Domains\n\n`;
+  
+  for (const domain of context.domains) {
+    output += `## Domain: ${domain.name}\n\n`;
+    output += `${domain.description}\n\n`;
+    output += `Modules: ${domain.moduleCount}\n`;
+    output += `Files: ${domain.fileCount}\n\n`;
+    output += `Main modules:\n`;
+    output += domain.topModules.slice(0, 5).map(m => `- ${m}`).join("\n");
+    output += `\n\n`;
+  }
+  
+  output += `Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+  
+  return output;
+}
+
+function getFallbackArchitectureOverview(context) {
+  return `# Architecture Overview
+
+## Architecture style
+
+Based on detected patterns: ${context.patterns.join(", ")}
+
+## Key layers
+
+${context.domains.slice(0, 5).map(d => `- ${d.name}: ${d.description}`).join("\n")}
+
+## Technology stack
+
+- Frameworks: ${context.techStack.frameworks.join(", ")}
+- Languages: ${context.techStack.languages.join(", ")}
+- Build tools: ${context.techStack.buildTools.join(", ")}
+
+Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+}
+
+function getFallbackDataFlows(flows) {
+  let output = `# Data Flows\n\n`;
+  
+  for (const flow of flows) {
+    output += `## ${flow.name}\n\n`;
+    output += `${flow.description}\n\n`;
+    output += `Steps:\n`;
+    output += flow.steps.map((s, i) => `${i + 1}. ${s}`).join("\n");
+    output += `\n\n`;
+  }
+  
+  output += `Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+  
+  return output;
+}
+
+function getFallbackDeveloperOnboarding(context) {
+  return `# Developer Onboarding
+
+## Start here
+
+This is a ${context.project.name} repository with ${context.project.modulesDetected} modules.
+
+## Main folders
+
+${context.repoRoots.map(root => `- ${root}`).join("\n")}
+
+## Technology stack
+
+- ${context.techStack.frameworks.join(", ")}
+- ${context.techStack.languages.join(", ")}
+
+## Top modules by size
+
+${context.topModules.slice(0, 10).map((m, i) => `${i + 1}. ${m.key} (${m.fileCount} files)`).join("\n")}
+
+Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+}