@chappibunny/repolens 0.4.1

package/src/renderers/render.js

@@ -0,0 +1,256 @@
+export function renderSystemOverview(cfg, scan) {
+  const notes = [];
+  
+  // Generate meaningful notes based on detected metadata
+  if (scan.metadata?.frameworks?.length) {
+    notes.push(`Tech Stack: ${scan.metadata.frameworks.join(", ")}`);
+  }
+  
+  if (scan.metadata?.languages?.size) {
+    notes.push(`Languages: ${[...scan.metadata.languages].join(", ")}`);
+  }
+  
+  if (scan.metadata?.buildTools?.length) {
+    notes.push(`Build Tools: ${scan.metadata.buildTools.join(", ")}`);
+  }
+  
+  if (scan.metadata?.testFrameworks?.length) {
+    notes.push(`Testing: ${scan.metadata.testFrameworks.join(", ")}`);
+  }
+  
+  // Add architectural insights
+  if (scan.modules.length > 50) {
+    notes.push(`Architecture: Large modular codebase with ${scan.modules.length} identified modules`);
+  } else if (scan.modules.length > 20) {
+    notes.push(`Architecture: Medium-sized modular structure with ${scan.modules.length} modules`);
+  } else if (scan.modules.length > 0) {
+    notes.push(`Architecture: Compact modular design with ${scan.modules.length} modules`);
+  }
+  
+  if (scan.api?.length > 0) {
+    notes.push(`API Coverage: ${scan.api.length} API endpoints detected`);
+  }
+  
+  if (scan.pages?.length > 0) {
+    notes.push(`UI Pages: ${scan.pages.length} application pages detected`);
+  }
+  
+  // If no meaningful data, show default message
+  if (notes.length === 0) {
+    notes.push("This is an overview based on filesystem heuristics. Add a package.json to see framework and tooling details.");
+  }
+  
+  return [
+    `# ${cfg.project.name} — System Overview`,
+    ``,
+    `What is this? This page provides a high-level snapshot of your codebase structure, showing what technologies you're using and how your code is organized.`,
+    ``,
+    `📊 Last Updated: ${new Date().toLocaleDateString("en-US", { month: "long", day: "numeric", year: "numeric" })}`,
+    ``,
+    `---`,
+    ``,
+    `## 📸 Quick Stats`,
+    ``,
+    `Here's what we found in your repository:`,
+    ``,
+    `- ${scan.filesCount} files scanned across your codebase`,
+    `- ${scan.modules.length} modules (major code sections) detected`,
+    `- ${scan.pages?.length || 0} pages in your application`,
+    `- ${scan.api.length} API endpoints for backend functionality`,
+    ``,
+    `## 📦 Largest Modules`,
+    ``,
+    `These are your biggest code modules (folders with the most files):`,
+    ``,
+    ...(scan.modules.slice(0, 10).map((m) => `- \`${m.key}\` contains ${m.fileCount} files`)),
+    ``,
+    `## 🔧 Technology Stack`,
+    ``,
+    `Your project uses these technologies:`,
+    ``,
+    ...notes.map(note => note),
+    ``,
+    `---`,
+    ``,
+    `💡 Tip: This documentation auto-updates on every push to your main branch!`,
+    ``
+  ].join("\n");
+}
+
+export function renderModuleCatalog(cfg, scan) {
+  const lines = [
+    `# 📁 Module Catalog`,
+    ``,
+    `What is this? This is a complete inventory of all code modules (folders) in your project, showing how your codebase is organized.`,
+    ``,
+    `Total modules found: ${scan.modules.length}`,
+    ``,
+    `---`,
+    ``,
+    `## All Modules`,
+    ``,
+    `Each module represents a major section of your codebase. The file count shows relative size:`,
+    ``
+  ];
+
+  if (!scan.modules.length) {
+    lines.push(`No modules detected. Configure \`module_roots\` in \`.repolens.yml\` to organize your code.`, ``);
+    return lines.join("\n");
+  }
+
+  for (const module of scan.modules.slice(0, 100)) {
+    lines.push(`- \`${module.key}\` — ${module.fileCount} files`);
+  }
+
+  if (scan.modules.length > 100) {
+    lines.push(``, `_(Showing top 100 of ${scan.modules.length} modules)_`);
+  }
+
+  lines.push(``, `---`, ``, `💡 Tip: Click any module name to see its location in your codebase.`, ``);
+
+  return lines.join("\n");
+}
+
+export function renderApiSurface(cfg, scan) {
+  const lines = [
+    `# 🔌 API Surface`,
+    ``,
+    `What is this? This page shows both the API endpoints your application provides AND the external APIs it integrates with.`,
+    ``,
+    `---`,
+    ``
+  ];
+
+  // Section 1: Internal API Endpoints (what we expose)
+  lines.push(
+    `## Internal API Endpoints`,
+    ``,
+    `These are the backend services your application provides to handle requests.`,
+    ``,
+    `Total endpoints: ${scan.api.length}`,
+    ``
+  );
+
+  if (!scan.api.length) {
+    lines.push(
+      `No API routes detected. Your project doesn't appear to have Next.js API routes yet.`,
+      ``
+    );
+  } else {
+    lines.push(
+      `Each line shows: HTTP Method → API Path → Implementation File`,
+      ``
+    );
+
+    for (const route of scan.api) {
+      lines.push(`- ${route.methods.join(", ")} \`${route.path}\` • \`${route.file}\``);
+    }
+    
+    lines.push(``);
+  }
+
+  // Section 2: External API Integrations (what we call)
+  lines.push(
+    `---`,
+    ``,
+    `## External API Integrations`,
+    ``,
+    `These are third-party services your application connects to.`,
+    ``
+  );
+
+  if (!scan.externalApis || scan.externalApis.length === 0) {
+    lines.push(
+      `No external API integrations detected.`,
+      ``
+    );
+  } else {
+    // Group by category
+    const byCategory = {};
+    for (const api of scan.externalApis) {
+      if (!byCategory[api.category]) {
+        byCategory[api.category] = [];
+      }
+      byCategory[api.category].push(api);
+    }
+
+    for (const [category, apis] of Object.entries(byCategory)) {
+      lines.push(`### ${category}`, ``);
+      for (const api of apis) {
+        lines.push(`- **${api.name}** — detected in \`${api.detectedIn}\``);
+      }
+      lines.push(``);
+    }
+  }
+
+  lines.push(
+    `---`,
+    ``,
+    `💡 Tips:`,
+    `- **Internal endpoints** handle incoming requests from users/clients`,
+    `- **External integrations** connect your app to third-party services`,
+    `- HTTP methods: GET (retrieve), POST (create), PUT/PATCH (update), DELETE (remove)`,
+    ``
+  );
+
+  return lines.join("\n");
+}
+
+export function renderRouteMap(cfg, scan) {
+  const lines = [
+    `# 🗺️ Route Map`,
+    ``,
+    `What is this? This page shows all the pages (URLs) users can visit in your application, plus the backend API endpoints that power them.`,
+    ``,
+    `---`,
+    ``
+  ];
+
+  if (scan.pages?.length) {
+    lines.push(
+      `## 🏠 Application Pages (${scan.pages.length})`,
+      ``,
+      `These are the user-facing pages in your app:`,
+      ``
+    );
+
+    for (const page of scan.pages.slice(0, 200)) {
+      lines.push(`- \`${page.path}\` • \`${page.file}\``);
+    }
+
+    lines.push(``);
+  }
+
+  if (scan.api?.length) {
+    lines.push(
+      `## 🔌 API Endpoints (${scan.api.length})`,
+      ``,
+      `These are backend services that handle data operations:`,
+      ``
+    );
+
+    for (const route of scan.api.slice(0, 200)) {
+      lines.push(`- ${route.methods.join(", ")} \`${route.path}\` • \`${route.file}\``);
+    }
+
+    lines.push(``);
+  }
+
+  if (!scan.pages?.length && !scan.api?.length) {
+    lines.push(
+      `## No Routes Detected`,
+      ``,
+      `RepoLens looks for Next.js pages and API routes. If you're using a different framework, routes might not be auto-detected yet.`,
+      ``
+    );
+  }
+
+  lines.push(
+    `---`,
+    ``,
+    `💡 Tip: URL paths starting with \`/api/\` are backend endpoints, others are user-facing pages.`,
+    ``
+  );
+
+  return lines.join("\n");
+}

package/src/renderers/renderDiff.js

@@ -0,0 +1,139 @@
+function isRouteFile(file) {
+  return (
+    file.includes("/pages/api/") ||
+    file.endsWith("/route.ts") ||
+    file.endsWith("/route.js") ||
+    file.endsWith("/page.tsx") ||
+    file.endsWith("/page.jsx") ||
+    file.endsWith("/page.ts") ||
+    file.endsWith("/page.js")
+  );
+}
+
+function routePathFromFile(file) {
+  if (file.includes("/app/")) {
+    const appIndex = file.indexOf("/app/");
+    const relative = file.slice(appIndex + 5);
+
+    return "/" + relative
+      .replace(/\/page\.(ts|tsx|js|jsx)$/, "")
+      .replace(/\/route\.(ts|tsx|js|jsx)$/, "")
+      .replace(/\[(.*?)\]/g, ":$1");
+  }
+
+  if (file.includes("/pages/api/")) {
+    const apiIndex = file.indexOf("/pages/api/");
+    const relative = file.slice(apiIndex + 11);
+
+    return "/api/" + relative.replace(/\.(ts|tsx|js|jsx)$/, "");
+  }
+
+  return file;
+}
+
+function moduleFromFile(file) {
+  const normalized = file.replace(/\\/g, "/");
+  const parts = normalized.split("/");
+
+  const roots = ["app", "components", "lib", "hooks", "store", "services", "packages", "src"];
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (roots.includes(parts[i])) {
+      return parts[i + 1] ? `${parts[i]}/${parts[i + 1]}` : parts[i];
+    }
+  }
+
+  return parts[0] || "root";
+}
+
+export function buildArchitectureDiffData(diff) {
+  const addedRoutes = diff.added.filter(isRouteFile).map(routePathFromFile);
+  const removedRoutes = diff.removed.filter(isRouteFile).map(routePathFromFile);
+
+  const impactedModules = [
+    ...new Set(
+      [...diff.added, ...diff.removed, ...diff.modified].map(moduleFromFile)
+    )
+  ].sort();
+
+  return {
+    ...diff,
+    addedRoutes,
+    removedRoutes,
+    impactedModules
+  };
+}
+
+export function renderArchitectureDiff(diff) {
+  const data = buildArchitectureDiffData(diff);
+
+  const lines = [
+    "# Architecture Diff",
+    "",
+    "RepoLens generated this from the current git diff versus the base branch.",
+    "",
+    "## Summary",
+    "",
+    `Added files: ${data.added.length}`,
+    `Removed files: ${data.removed.length}`,
+    `Modified files: ${data.modified.length}`,
+    `Added routes: ${data.addedRoutes.length}`,
+    `Removed routes: ${data.removedRoutes.length}`,
+    `Impacted modules: ${data.impactedModules.length}`,
+    ""
+  ];
+
+  if (data.addedRoutes.length) {
+    lines.push("## Added Routes", "");
+    for (const route of data.addedRoutes.slice(0, 25)) {
+      lines.push(`- \`${route}\``);
+    }
+    lines.push("");
+  }
+
+  if (data.removedRoutes.length) {
+    lines.push("## Removed Routes", "");
+    for (const route of data.removedRoutes.slice(0, 25)) {
+      lines.push(`- \`${route}\``);
+    }
+    lines.push("");
+  }
+
+  if (data.impactedModules.length) {
+    lines.push("## Impacted Modules", "");
+    for (const module of data.impactedModules.slice(0, 40)) {
+      lines.push(`- \`${module}\``);
+    }
+    lines.push("");
+  }
+
+  if (data.added.length) {
+    lines.push("## Added Files", "");
+    for (const file of data.added.slice(0, 25)) {
+      lines.push(`- \`${file}\``);
+    }
+    lines.push("");
+  }
+
+  if (data.removed.length) {
+    lines.push("## Removed Files", "");
+    for (const file of data.removed.slice(0, 25)) {
+      lines.push(`- \`${file}\``);
+    }
+    lines.push("");
+  }
+
+  if (data.modified.length) {
+    lines.push("## Modified Files", "");
+    for (const file of data.modified.slice(0, 25)) {
+      lines.push(`- \`${file}\``);
+    }
+    lines.push("");
+  }
+
+  if (!data.added.length && !data.removed.length && !data.modified.length) {
+    lines.push("No architecture-relevant changes detected.", "");
+  }
+
+  return lines.join("\n");
+}

package/src/renderers/renderMap.js

@@ -0,0 +1,224 @@
+function sanitizeNodeId(value) {
+  return value.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+function normalizeLabel(value) {
+  return value
+    .replace(/^src\//, "")
+    .replace(/^app\/\((.*?)\)/, "app/$1")
+    .replace(/\/\((.*?)\)/g, "/$1")
+    .replace(/\/+/g, "/");
+}
+
+function buildModuleGraph(modules) {
+  // Create nodes with module details
+  const nodes = modules.map(mod => ({
+    id: sanitizeNodeId(mod.key),
+    key: mod.key,
+    label: normalizeLabel(mod.key),
+    fileCount: mod.fileCount,
+    category: categorizeModule(mod.key)
+  }));
+
+  // Infer relationships based on common patterns
+  const relationships = [];
+
+  for (const source of nodes) {
+    for (const target of nodes) {
+      if (source.id === target.id) continue;
+
+      // CLI imports from core, publishers, renderers, utils
+      if (source.label === "bin" || source.label.startsWith("bin/")) {
+        if (target.label.startsWith("src/")) {
+          relationships.push({
+            from: source.id,
+            to: target.id,
+            type: "uses"
+          });
+        }
+      }
+
+      // Core modules are foundational - others depend on them
+      if (target.label.startsWith("src/core")) {
+        if (source.label.startsWith("src/publishers") || 
+            source.label.startsWith("src/renderers") ||
+            source.label.startsWith("src/delivery")) {
+          relationships.push({
+            from: source.id,
+            to: target.id,
+            type: "depends-on"
+          });
+        }
+      }
+
+      // Publishers use renderers
+      if (source.label.startsWith("src/publishers") && target.label.startsWith("src/renderers")) {
+        relationships.push({
+          from: source.id,
+          to: target.id,
+          type: "renders"
+        });
+      }
+
+      // Everything uses utils
+      if (target.label.startsWith("src/utils")) {
+        if (source.label.startsWith("src/") && source.label !== target.label) {
+          relationships.push({
+            from: source.id,
+            to: target.id,
+            type: "uses"
+          });
+        }
+      }
+
+      // Delivery uses publishers
+      if (source.label.startsWith("src/delivery") && target.label.startsWith("src/publishers")) {
+        relationships.push({
+          from: source.id,
+            to: target.id,
+          type: "publishes-via"
+        });
+      }
+
+      // Tests test everything
+      if (source.label.startsWith("tests/") || source.label.startsWith("test/")) {
+        if (!target.label.startsWith("tests/") && !target.label.startsWith("test/")) {
+          relationships.push({
+            from: source.id,
+            to: target.id,
+            type: "tests"
+          });
+        }
+      }
+    }
+  }
+
+  return { nodes, relationships };
+}
+
+function categorizeModule(key) {
+  const normalized = key.toLowerCase();
+  if (normalized.includes("core")) return "core";
+  if (normalized.includes("publisher")) return "integration";
+  if (normalized.includes("renderer")) return "business";
+  if (normalized.includes("delivery")) return "integration";
+  if (normalized.includes("util")) return "util";
+  if (normalized.includes("test")) return "test";
+  if (normalized.includes("bin")) return "cli";
+  return "other";
+}
+
+function generateUnicodeArchitectureDiagram(nodes, relationships) {
+  // Group nodes by category
+  const categories = {
+    cli: { icon: "🎯", label: "CLI Entry", nodes: [] },
+    core: { icon: "⚙️", label: "Core Logic", nodes: [] },
+    business: { icon: "📋", label: "Business Logic", nodes: [] },
+    integration: { icon: "🔌", label: "Integration", nodes: [] },
+    util: { icon: "🛠️", label: "Utilities", nodes: [] },
+    test: { icon: "✅", label: "Testing", nodes: [] },
+    other: { icon: "📦", label: "Other", nodes: [] }
+  };
+
+  // Organize nodes by category
+  for (const node of nodes) {
+    const category = categories[node.category] || categories.other;
+    category.nodes.push(node);
+  }
+
+  const lines = [];
+  lines.push("```");
+  lines.push("┌─────────────────────────────────────────────────────────────┐");
+  lines.push("│              🏗️  SYSTEM ARCHITECTURE MAP                    │");
+  lines.push("└─────────────────────────────────────────────────────────────┘");
+  lines.push("");
+
+  // Build dependency map for annotations
+  const dependencyMap = new Map();
+  for (const rel of relationships) {
+    if (!dependencyMap.has(rel.from)) {
+      dependencyMap.set(rel.from, []);
+    }
+    dependencyMap.get(rel.from).push({ to: rel.to, type: rel.type });
+  }
+
+  // Render each category with its nodes
+  for (const [catKey, category] of Object.entries(categories)) {
+    if (category.nodes.length === 0) continue;
+
+    lines.push(`${category.icon}  ${category.label.toUpperCase()}`);
+    lines.push("│");
+
+    category.nodes.forEach((node, idx) => {
+      const isLast = idx === category.nodes.length - 1;
+      const prefix = isLast ? "└──" : "├──";
+      const shortLabel = node.label.split('/').pop() || node.label;
+      const fileInfo = `(${node.fileCount} file${node.fileCount !== 1 ? 's' : ''})`;
+      
+      lines.push(`${prefix} ${shortLabel} ${fileInfo}`);
+      
+      // Show dependencies for this node
+      const deps = dependencyMap.get(node.id) || [];
+      if (deps.length > 0) {
+        const connector = isLast ? "    " : "│   ";
+        deps.slice(0, 3).forEach((dep, depIdx) => {
+          const depNode = nodes.find(n => n.id === dep.to);
+          if (depNode) {
+            const depLabel = depNode.label.split('/').pop() || depNode.label;
+            const arrow = dep.type === "tests" ? "╌→" : "→";
+            lines.push(`${connector}   ${arrow} ${depLabel}`);
+          }
+        });
+        if (deps.length > 3) {
+          lines.push(`${connector}   ... +${deps.length - 3} more`);
+        }
+      }
+    });
+    
+    lines.push("│");
+  }
+
+  lines.push("");
+  lines.push("Legend:");
+  lines.push("  →  depends on / uses");
+  lines.push("  ╌→ tests");
+  lines.push("```");
+  
+  return lines.join("\n");
+}
+
+export function renderSystemMap(scan) {
+  const modules = (scan.modules || []).slice(0, 30); // Limit for readability
+  
+  if (modules.length === 0) {
+    return [
+      "# 🏗️ System Map",
+      "",
+      "> What is this? This page shows how different parts of your codebase connect and depend on each other.",
+      "",
+      "No modules detected. Configure `module_roots` in `.repolens.yml` to visualize your architecture.",
+      ""
+    ].join("\n");
+  }
+
+  const { nodes, relationships } = buildModuleGraph(modules);
+  const architectureDiagram = generateUnicodeArchitectureDiagram(nodes, relationships);
+
+  // Build markdown output
+  const lines = [
+    "# 🏗️ System Map",
+    "",
+    "> What is this? This visual diagram shows how different parts of your codebase connect to each other. Arrows indicate dependencies (which modules use which).",
+    "",
+    `Showing: ${nodes.length} modules and ${relationships.length} relationships`,
+    "",
+    "---",
+    "",
+    "## Architecture Diagram",
+    "",
+    architectureDiagram,
+    ""
+  ];
+
+  return lines.join("\n");
+}

package/src/utils/branch.js

@@ -0,0 +1,93 @@
+import { execSync } from "node:child_process";
+
+/**
+ * Detect the current git branch from various sources
+ * Priority: CI environment → git command → fallback
+ */
+export function getCurrentBranch() {
+  // 1. Check GitHub Actions environment
+  if (process.env.GITHUB_REF_NAME) {
+    return process.env.GITHUB_REF_NAME;
+  }
+
+  // 2. Check GitLab CI environment
+  if (process.env.CI_COMMIT_REF_NAME) {
+    return process.env.CI_COMMIT_REF_NAME;
+  }
+
+  // 3. Check CircleCI environment
+  if (process.env.CIRCLE_BRANCH) {
+    return process.env.CIRCLE_BRANCH;
+  }
+
+  // 4. Try git command
+  try {
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"]
+    }).trim();
+    
+    if (branch && branch !== "HEAD") {
+      return branch;
+    }
+  } catch {
+    // Git command failed, continue to fallback
+  }
+
+  // 5. Fallback
+  return "unknown";
+}
+
+/**
+ * Normalize branch name for display (sanitize special characters)
+ */
+export function normalizeBranchName(branch) {
+  return branch
+    .replace(/\//g, "-")  // feature/auth → feature-auth
+    .replace(/[^a-zA-Z0-9-_]/g, "")  // Remove special chars
+    .toLowerCase();
+}
+
+/**
+ * Check if current branch should publish to Notion
+ * Based on config.notion.branches setting
+ */
+export function shouldPublishToNotion(config, currentBranch = getCurrentBranch()) {
+  // If no notion config, allow all branches (backward compatible)
+  if (!config.notion) {
+    return true;
+  }
+
+  // If branches not specified, allow all
+  if (!config.notion.branches || config.notion.branches.length === 0) {
+    return true;
+  }
+
+  // Check if current branch matches any allowed pattern
+  return config.notion.branches.some(pattern => {
+    // Exact match
+    if (pattern === currentBranch) {
+      return true;
+    }
+
+    // Wildcard pattern (simple glob)
+    if (pattern.includes("*")) {
+      const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+      return regex.test(currentBranch);
+    }
+
+    return false;
+  });
+}
+
+/**
+ * Get branch-qualified page title
+ */
+export function getBranchQualifiedTitle(baseTitle, branch = getCurrentBranch(), includeBranch = true) {
+  if (!includeBranch || branch === "main" || branch === "master") {
+    return baseTitle;
+  }
+
+  const normalizedBranch = normalizeBranchName(branch);
+  return `${baseTitle} [${normalizedBranch}]`;
+}