@chappibunny/repolens 0.4.1

package/src/core/config-schema.js

@@ -0,0 +1,266 @@
+/**
+ * RepoLens Configuration Schema Validator
+ * 
+ * Schema Version: 1
+ * 
+ * This validator ensures .repolens.yml files conform to the expected structure.
+ * Breaking changes to this schema will require a major version bump.
+ */
+
+const CURRENT_SCHEMA_VERSION = 1;
+const SUPPORTED_PUBLISHERS = ["notion", "markdown"];
+const SUPPORTED_PAGE_KEYS = [
+  "system_overview",
+  "module_catalog",
+  "api_surface",
+  "arch_diff",
+  "route_map",
+  "system_map",
+  // New AI-enhanced document types
+  "executive_summary",
+  "business_domains",
+  "architecture_overview",
+  "data_flows",
+  "change_impact",
+  "developer_onboarding"
+];
+
+class ValidationError extends Error {
+  constructor(message, path) {
+    super(message);
+    this.name = "ValidationError";
+    this.path = path;
+  }
+}
+
+/**
+ * Validate the complete config object
+ */
+export function validateConfig(config) {
+  const errors = [];
+
+  // Check schema version
+  if (config.configVersion !== undefined) {
+    if (typeof config.configVersion !== "number") {
+      errors.push("configVersion must be a number");
+    } else if (config.configVersion > CURRENT_SCHEMA_VERSION) {
+      errors.push(
+        `Config schema version ${config.configVersion} is not supported. ` +
+        `This version of RepoLens supports schema version ${CURRENT_SCHEMA_VERSION}. ` +
+        `Please upgrade RepoLens or downgrade your config.`
+      );
+    }
+  }
+
+  // Validate project section
+  if (!config.project) {
+    errors.push("Missing required section: project");
+  } else {
+    if (!config.project.name || typeof config.project.name !== "string") {
+      errors.push("project.name is required and must be a string");
+    }
+    if (config.project.docs_title_prefix && typeof config.project.docs_title_prefix !== "string") {
+      errors.push("project.docs_title_prefix must be a string");
+    }
+  }
+
+  // Validate publishers
+  if (!config.publishers) {
+    errors.push("Missing required section: publishers");
+  } else if (!Array.isArray(config.publishers)) {
+    errors.push("publishers must be an array");
+  } else if (config.publishers.length === 0) {
+    errors.push("publishers array cannot be empty");
+  } else {
+    config.publishers.forEach((pub, idx) => {
+      if (!SUPPORTED_PUBLISHERS.includes(pub)) {
+        errors.push(
+          `publishers[${idx}]: "${pub}" is not a valid publisher. ` +
+          `Supported: ${SUPPORTED_PUBLISHERS.join(", ")}`
+        );
+      }
+    });
+  }
+
+  // Validate scan section
+  if (!config.scan) {
+    errors.push("Missing required section: scan");
+  } else {
+    if (!config.scan.include || !Array.isArray(config.scan.include)) {
+      errors.push("scan.include is required and must be an array");
+    } else if (config.scan.include.length === 0) {
+      errors.push("scan.include cannot be empty");
+    }
+
+    if (!config.scan.ignore || !Array.isArray(config.scan.ignore)) {
+      errors.push("scan.ignore is required and must be an array");
+    }
+  }
+
+  // Validate module_roots (optional but must be array if present)
+  if (config.module_roots !== undefined) {
+    if (!Array.isArray(config.module_roots)) {
+      errors.push("module_roots must be an array");
+    }
+  }
+
+  // Validate outputs section
+  if (!config.outputs) {
+    errors.push("Missing required section: outputs");
+  } else {
+    if (!config.outputs.pages || !Array.isArray(config.outputs.pages)) {
+      errors.push("outputs.pages is required and must be an array");
+    } else if (config.outputs.pages.length === 0) {
+      errors.push("outputs.pages cannot be empty");
+    } else {
+      config.outputs.pages.forEach((page, idx) => {
+        if (!page.key || typeof page.key !== "string") {
+          errors.push(`outputs.pages[${idx}]: missing required field "key"`);
+        } else if (!SUPPORTED_PAGE_KEYS.includes(page.key)) {
+          errors.push(
+            `outputs.pages[${idx}]: "${page.key}" is not a valid page key. ` +
+            `Supported: ${SUPPORTED_PAGE_KEYS.join(", ")}`
+          );
+        }
+        
+        if (!page.title || typeof page.title !== "string") {
+          errors.push(`outputs.pages[${idx}]: missing required field "title"`);
+        }
+        
+        if (page.description && typeof page.description !== "string") {
+          errors.push(`outputs.pages[${idx}]: description must be a string`);
+        }
+      });
+    }
+  }
+
+  // Validate notion configuration (optional)
+  if (config.notion !== undefined) {
+    if (typeof config.notion !== "object" || Array.isArray(config.notion)) {
+      errors.push("notion must be an object");
+    } else {
+      // Validate branches filter
+      if (config.notion.branches !== undefined) {
+        if (!Array.isArray(config.notion.branches)) {
+          errors.push("notion.branches must be an array");
+        } else {
+          config.notion.branches.forEach((branch, idx) => {
+            if (typeof branch !== "string") {
+              errors.push(`notion.branches[${idx}] must be a string`);
+            }
+          });
+        }
+      }
+
+      // Validate includeBranchInTitle
+      if (config.notion.includeBranchInTitle !== undefined) {
+        if (typeof config.notion.includeBranchInTitle !== "boolean") {
+          errors.push("notion.includeBranchInTitle must be a boolean");
+        }
+      }
+    }
+  }
+
+  // Validate feature flags (optional)
+  if (config.features !== undefined) {
+    if (typeof config.features !== "object" || Array.isArray(config.features)) {
+      errors.push("features must be an object");
+    } else {
+      Object.entries(config.features).forEach(([key, value]) => {
+        if (typeof value !== "boolean") {
+          errors.push(`features.${key} must be a boolean`);
+        }
+      });
+    }
+  }
+
+  // Validate AI configuration (optional)
+  if (config.ai !== undefined) {
+    if (typeof config.ai !== "object" || Array.isArray(config.ai)) {
+      errors.push("ai must be an object");
+    } else {
+      if (config.ai.enabled !== undefined && typeof config.ai.enabled !== "boolean") {
+        errors.push("ai.enabled must be a boolean");
+      }
+      if (config.ai.mode !== undefined && !["hybrid", "full", "off"].includes(config.ai.mode)) {
+        errors.push("ai.mode must be one of: hybrid, full, off");
+      }
+      if (config.ai.temperature !== undefined && typeof config.ai.temperature !== "number") {
+        errors.push("ai.temperature must be a number");
+      }
+      if (config.ai.max_tokens !== undefined && typeof config.ai.max_tokens !== "number") {
+        errors.push("ai.max_tokens must be a number");
+      }
+    }
+  }
+
+  // Validate documentation configuration (optional)
+  if (config.documentation !== undefined) {
+    if (typeof config.documentation !== "object" || Array.isArray(config.documentation)) {
+      errors.push("documentation must be an object");
+    } else {
+      if (config.documentation.output_dir && typeof config.documentation.output_dir !== "string") {
+        errors.push("documentation.output_dir must be a string");
+      }
+      if (config.documentation.include_artifacts !== undefined && typeof config.documentation.include_artifacts !== "boolean") {
+        errors.push("documentation.include_artifacts must be a boolean");
+      }
+      if (config.documentation.sections !== undefined) {
+        if (!Array.isArray(config.documentation.sections)) {
+          errors.push("documentation.sections must be an array");
+        }
+      }
+    }
+  }
+
+  // Validate domains configuration (optional)
+  if (config.domains !== undefined) {
+    if (typeof config.domains !== "object" || Array.isArray(config.domains)) {
+      errors.push("domains must be an object");
+    } else {
+      Object.entries(config.domains).forEach(([domainKey, domain]) => {
+        if (typeof domain !== "object") {
+          errors.push(`domains.${domainKey} must be an object`);
+        } else {
+          if (!domain.match || !Array.isArray(domain.match)) {
+            errors.push(`domains.${domainKey}.match is required and must be an array`);
+          }
+          if (domain.description && typeof domain.description !== "string") {
+            errors.push(`domains.${domainKey}.description must be a string`);
+          }
+        }
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    const errorMessage = [
+      "Invalid .repolens.yml configuration:",
+      "",
+      ...errors.map(e => `  • ${e}`),
+      "",
+      "See https://github.com/CHAPIBUNNY/repolens#configuration for documentation."
+    ].join("\n");
+    
+    throw new ValidationError(errorMessage);
+  }
+
+  return true;
+}
+
+/**
+ * Get the schema version this validator supports
+ */
+export function getSchemaVersion() {
+  return CURRENT_SCHEMA_VERSION;
+}
+
+/**
+ * Check if a feature is enabled (with default fallback)
+ */
+export function isFeatureEnabled(config, featureName, defaultValue = true) {
+  if (!config.features) return defaultValue;
+  return config.features[featureName] !== undefined 
+    ? config.features[featureName] 
+    : defaultValue;
+}

package/src/core/config.js

@@ -0,0 +1,18 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { validateConfig } from "./config-schema.js";
+
+export async function loadConfig(configPath) {
+  const absoluteConfigPath = path.resolve(configPath);
+  const raw = await fs.readFile(absoluteConfigPath, "utf8");
+  const cfg = yaml.load(raw);
+
+  // Validate config against schema
+  validateConfig(cfg);
+
+  cfg.__configPath = absoluteConfigPath;
+  cfg.__repoRoot = path.dirname(absoluteConfigPath);
+
+  return cfg;
+}

package/src/core/diff.js

@@ -0,0 +1,45 @@
+import { execSync } from "node:child_process";
+import { warn } from "../utils/logger.js";
+
+export function getGitDiff(baseRef = "origin/main") {
+  let output = "";
+
+  try {
+    output = execSync(`git diff --name-status ${baseRef}`, {
+      encoding: "utf8"
+    });
+  } catch (error) {
+    warn("git diff failed, returning empty diff.");
+    return {
+      added: [],
+      removed: [],
+      modified: []
+    };
+  }
+
+  const lines = output.split("\n").filter(Boolean);
+
+  const added = [];
+  const removed = [];
+  const modified = [];
+
+  for (const line of lines) {
+    const [status, file] = line.split("\t");
+
+    if (!file) continue;
+
+    if (status === "A") {
+      added.push(file);
+    } else if (status === "D") {
+      removed.push(file);
+    } else {
+      modified.push(file);
+    }
+  }
+
+  return {
+    added,
+    removed,
+    modified
+  };
+}

package/src/core/scan.js

@@ -0,0 +1,312 @@
+import fg from "fast-glob";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { info, warn } from "../utils/logger.js";
+
+const norm = (p) => p.replace(/\\/g, "/");
+
+// Performance guardrails
+const MAX_FILES_WARNING = 10000;
+const MAX_FILES_LIMIT = 50000;
+
+function isNextRoute(file) {
+  const f = norm(file);
+  return (
+    f.includes("/pages/api/") ||
+    (f.includes("/app/") && (f.endsWith("/route.ts") || f.endsWith("/route.js")))
+  );
+}
+
+function isNextPage(file) {
+  const f = norm(file);
+
+  if (f.includes("/app/")) {
+    return (
+      f.endsWith("/page.tsx") ||
+      f.endsWith("/page.jsx") ||
+      f.endsWith("/page.ts") ||
+      f.endsWith("/page.js")
+    );
+  }
+
+  if (f.includes("/pages/") && !f.includes("/pages/api/")) {
+    return (
+      f.endsWith(".tsx") ||
+      f.endsWith(".jsx") ||
+      f.endsWith(".ts") ||
+      f.endsWith(".js")
+    );
+  }
+
+  return false;
+}
+
+async function readFileSafe(file) {
+  try {
+    return await fs.readFile(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function moduleKeyForFile(file, moduleRoots) {
+  const normalized = norm(file);
+
+  const sortedRoots = [...moduleRoots].sort((a, b) => b.length - a.length);
+
+  for (const root of sortedRoots) {
+    if (normalized === root) return root;
+    if (normalized.startsWith(`${root}/`)) {
+      const remainder = normalized.slice(root.length + 1);
+      const nextSegment = remainder.split("/")[0];
+      return nextSegment ? `${root}/${nextSegment}` : root;
+    }
+  }
+
+  const parts = normalized.split("/");
+  return parts.length > 1 ? parts[0] : "root";
+}
+
+function routePathFromFile(file) {
+  const f = norm(file);
+
+  if (f.includes("/app/")) {
+    const appIndex = f.indexOf("/app/");
+    const relative = f.slice(appIndex + 5);
+
+    const cleaned = relative
+      .replace(/\/page\.(ts|tsx|js|jsx)$/, "")
+      .replace(/\/route\.(ts|tsx|js|jsx)$/, "")
+      .replace(/\[(.*?)\]/g, ":$1")
+      .replace(/\/$/, "");
+
+    return cleaned ? `/${cleaned}` : "/";
+  }
+
+  if (f.includes("/pages/api/")) {
+    const apiIndex = f.indexOf("/pages/api/");
+    const relative = f.slice(apiIndex + 11);
+
+    return "/api/" + relative.replace(/\.(ts|tsx|js|jsx)$/, "");
+  }
+
+  if (f.includes("/pages/")) {
+    const pagesIndex = f.indexOf("/pages/");
+    const relative = f.slice(pagesIndex + 7);
+
+    const cleaned = relative
+      .replace(/\.(ts|tsx|js|jsx)$/, "")
+      .replace(/\/index$/, "")
+      .replace(/\[(.*?)\]/g, ":$1")
+      .replace(/\/$/, "");
+
+    return cleaned ? `/${cleaned}` : "/";
+  }
+
+  return file;
+}
+
+async function extractRepoMetadata(repoRoot) {
+  const metadata = {
+    hasPackageJson: false,
+    frameworks: [],
+    languages: new Set(),
+    buildTools: [],
+    testFrameworks: []
+  };
+
+  // Try to read package.json
+  try {
+    const pkgPath = path.join(repoRoot, "package.json");
+    const pkgContent = await fs.readFile(pkgPath, "utf8");
+    const pkg = JSON.parse(pkgContent);
+    metadata.hasPackageJson = true;
+
+    const allDeps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+      ...pkg.optionalDependencies
+    };
+
+    // Detect frameworks
+    if (allDeps["next"]) metadata.frameworks.push("Next.js");
+    if (allDeps["react"]) metadata.frameworks.push("React");
+    if (allDeps["vue"]) metadata.frameworks.push("Vue");
+    if (allDeps["angular"] || allDeps["@angular/core"]) metadata.frameworks.push("Angular");
+    if (allDeps["express"]) metadata.frameworks.push("Express");
+    if (allDeps["fastify"]) metadata.frameworks.push("Fastify");
+    if (allDeps["nestjs"] || allDeps["@nestjs/core"]) metadata.frameworks.push("NestJS");
+    if (allDeps["svelte"]) metadata.frameworks.push("Svelte");
+    if (allDeps["solid-js"]) metadata.frameworks.push("Solid");
+
+    // Detect test frameworks
+    if (allDeps["vitest"]) metadata.testFrameworks.push("Vitest");
+    if (allDeps["jest"]) metadata.testFrameworks.push("Jest");
+    if (allDeps["mocha"]) metadata.testFrameworks.push("Mocha");
+    if (allDeps["playwright"]) metadata.testFrameworks.push("Playwright");
+    if (allDeps["cypress"]) metadata.testFrameworks.push("Cypress");
+
+    // Detect build tools
+    if (allDeps["vite"]) metadata.buildTools.push("Vite");
+    if (allDeps["webpack"]) metadata.buildTools.push("Webpack");
+    if (allDeps["rollup"]) metadata.buildTools.push("Rollup");
+    if (allDeps["esbuild"]) metadata.buildTools.push("esbuild");
+    if (allDeps["turbo"]) metadata.buildTools.push("Turborepo");
+
+    // Detect TypeScript
+    if (allDeps["typescript"]) metadata.languages.add("TypeScript");
+  } catch {
+    // No package.json or invalid JSON
+  }
+
+  return metadata;
+}
+
+export async function scanRepo(cfg) {
+  const repoRoot = cfg.__repoRoot;
+
+  const files = await fg(cfg.scan.include, {
+    cwd: repoRoot,
+    ignore: cfg.scan.ignore,
+    onlyFiles: true
+  });
+
+  // Performance guardrails
+  if (files.length > MAX_FILES_LIMIT) {
+    throw new Error(
+      `Repository too large: ${files.length} files matched scan patterns. ` +
+      `Maximum supported: ${MAX_FILES_LIMIT}. Consider refining scan.include patterns.`
+    );
+  }
+
+  if (files.length > MAX_FILES_WARNING) {
+    warn(`Large repository detected: ${files.length} files. Scan may take longer than usual.`);
+  }
+
+  const moduleCounts = new Map();
+
+  for (const file of files) {
+    const key = moduleKeyForFile(file, cfg.module_roots || []);
+    moduleCounts.set(key, (moduleCounts.get(key) || 0) + 1);
+  }
+
+  const modules = [...moduleCounts.entries()]
+    .map(([key, fileCount]) => ({ key, fileCount }))
+    .sort((a, b) => b.fileCount - a.fileCount);
+
+  const apiFiles = files.filter(isNextRoute);
+  const api = [];
+
+  for (const file of apiFiles) {
+    const absoluteFile = path.join(repoRoot, file);
+    const content = await readFileSafe(absoluteFile);
+    const methods = [];
+
+    if (content.includes("export async function GET")) methods.push("GET");
+    if (content.includes("export async function POST")) methods.push("POST");
+    if (content.includes("export async function PUT")) methods.push("PUT");
+    if (content.includes("export async function PATCH")) methods.push("PATCH");
+    if (content.includes("export async function DELETE")) methods.push("DELETE");
+
+    api.push({
+      file,
+      path: routePathFromFile(file),
+      methods: methods.length ? methods : ["UNKNOWN"]
+    });
+  }
+
+  const pageFiles = files.filter(isNextPage);
+  const pages = pageFiles.map((file) => ({
+    file,
+    path: routePathFromFile(file)
+  }));
+
+  // Extract repository metadata
+  const metadata = await extractRepoMetadata(repoRoot);
+
+  // Detect external API integrations
+  const externalApis = await detectExternalApis(files, repoRoot);
+
+  return {
+    filesCount: files.length,
+    modules,
+    api,
+    pages,
+    metadata,
+    externalApis
+  };
+}
+
+async function detectExternalApis(files, repoRoot) {
+  const integrations = [];
+  const detectedServices = new Set();
+
+  // Common API patterns to detect
+  const apiPatterns = [
+    {
+      name: "OpenAI API",
+      patterns: [
+        /api\.openai\.com/,
+        /chat\/completions/,
+        /OPENAI.*API_KEY/,
+        /REPOLENS_AI_API_KEY/
+      ],
+      category: "AI/ML"
+    },
+    {
+      name: "Notion API",
+      patterns: [
+        /api\.notion\.com/,
+        /NOTION_TOKEN/,
+        /notion.*pages/
+      ],
+      category: "Publishing"
+    },
+    {
+      name: "npm Registry",
+      patterns: [
+        /registry\.npmjs\.org/,
+        /npm.*latest/
+      ],
+      category: "Package Management"
+    },
+    {
+      name: "GitHub API",
+      patterns: [
+        /api\.github\.com/,
+        /GITHUB_TOKEN/
+      ],
+      category: "Version Control"
+    }
+  ];
+
+  // Only scan JavaScript/TypeScript files for performance
+  const jsFiles = files.filter(f => 
+    f.endsWith('.js') || f.endsWith('.ts') || 
+    f.endsWith('.jsx') || f.endsWith('.tsx')
+  );
+
+  for (const file of jsFiles) {
+    const absoluteFile = path.join(repoRoot, file);
+    const content = await readFileSafe(absoluteFile);
+    
+    if (!content) continue;
+
+    for (const { name, patterns, category } of apiPatterns) {
+      if (detectedServices.has(name)) continue;
+
+      const matched = patterns.some(pattern => pattern.test(content));
+      
+      if (matched) {
+        integrations.push({
+          name,
+          category,
+          detectedIn: file
+        });
+        detectedServices.add(name);
+      }
+    }
+  }
+
+  return integrations;
+}