@chappibunny/repolens 1.9.4 → 1.9.6

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.9.6
+
+### 📹 Documentation
+
+- **Updated demo video**: README now embeds new Loom demo video
+
+## 1.9.5
+
+### ✨ UX Improvements
+
+- **AI Provider Presets**: New `REPOLENS_AI_PRESET` environment variable for one-line AI setup. Supports `github`, `openai`, `anthropic`, and `google` presets that automatically configure provider, base URL, and model.
+
+- **Progress Indicator**: Document generation now shows step-by-step progress: `[1/15] Generating executive_summary...`, `[2/15] Generating business_domains...`, etc.
+
+- **Config Typo Detection**: `repolens doctor` now detects typos in config keys and suggests corrections using Levenshtein distance. For example: `Unknown config key "projet" — did you mean "project"?`
+
+- **Cache Age Display**: Publishing shows when the cache was last updated: `Cache: 5/15 documents unchanged (last run: 2h ago)`.
+
+- **Verbose Export**: The `--verbose` flag and `isVerbose` constant are now exported from logger for use by plugins and custom scripts.
+
+### 🧪 Tests
+
+- Updated doc-cache tests to verify new `{ cache, age }` return format
+- **380 tests passing** across 22 test files
+
 ## 1.9.3
 
 ### ✨ Premium Deterministic Documentation

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](docs/STABILITY.md) · [Security hardened](SECURITY.md) · v1.9.4
+> Stable as of v1.0 — [API guarantees](docs/STABILITY.md) · [Security hardened](SECURITY.md) · v1.9.6
 
 ---
 
@@ -25,9 +25,9 @@ RepoLens scans your repository, generates living architecture documentation, and
 
 > **Try it now** — no installation required. Run `npx @chappibunny/repolens demo` on any repo for an instant local preview.
 
-[![RepoLens Demo](https://img.youtube.com/vi/Lpyg0dGsiws/maxresdefault.jpg)](https://youtu.be/Lpyg0dGsiws)
+<div style="position: relative; padding-bottom: 40.955631399317404%; height: 0;"><iframe src="https://www.loom.com/embed/8e077624e69f41319fd93acbbe03871e" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
 
-▶️ *Click to watch on YouTube*
+▶️ *Click to watch demo*
 
 <details>
 <summary>🔍 <strong>Supported Languages</strong> (16 auto-detected)</summary>

package/docs/ENVIRONMENT.md

@@ -36,6 +36,7 @@
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `REPOLENS_AI_ENABLED` | No | Enable AI-powered sections (`true`/`false`) |
+| `REPOLENS_AI_PRESET` | No | Quick setup preset: `github`, `openai`, `anthropic`, `google` (overrides provider/baseUrl/model) |
 | `REPOLENS_AI_PROVIDER` | No | Provider: `openai_compatible` (default), `anthropic`, `google`, `github` |
 | `REPOLENS_AI_API_KEY` | No | API key for AI provider (not needed for `github` provider) |
 | `REPOLENS_AI_BASE_URL` | No | API base URL (auto-set per provider; override for custom endpoints) |
@@ -43,7 +44,28 @@
 | `REPOLENS_AI_TEMPERATURE` | No | Generation temperature (omitted by default for GPT-5 compatibility) |
 | `REPOLENS_AI_MAX_TOKENS` | No | Max completion tokens per request (default: `2000`) |
 
-> **GitHub Models (free):** Set `REPOLENS_AI_PROVIDER=github` in GitHub Actions — uses `GITHUB_TOKEN` automatically, no separate API key required. See [AI.md](AI.md) for details.
+### AI Presets (Quick Setup)
+
+Instead of configuring provider, base URL, and model separately, use a preset:
+
+```bash
+# GitHub Models (free in GitHub Actions)
+REPOLENS_AI_PRESET=github
+
+# OpenAI
+REPOLENS_AI_PRESET=openai
+REPOLENS_AI_API_KEY=sk-...
+
+# Anthropic
+REPOLENS_AI_PRESET=anthropic
+REPOLENS_AI_API_KEY=sk-ant-...
+
+# Google Gemini
+REPOLENS_AI_PRESET=google
+REPOLENS_AI_API_KEY=...
+```
+
+> **GitHub Models (free):** Set `REPOLENS_AI_PRESET=github` in GitHub Actions — uses `GITHUB_TOKEN` automatically, no separate API key required. See [AI.md](AI.md) for details.
 
 ## Telemetry
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.9.4",
+  "version": "1.9.6",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",

package/src/ai/provider.js

@@ -6,6 +6,33 @@ import { executeAIRequest } from "../utils/rate-limit.js";
 const DEFAULT_TIMEOUT_MS = 60000;
 const DEFAULT_MAX_TOKENS = 2500;
 
+/**
+ * AI Provider Presets - one env var to configure common providers.
+ * REPOLENS_AI_PRESET takes precedence over individual settings.
+ */
+const AI_PRESETS = {
+  github: {
+    provider: "github",
+    baseUrl: "https://models.inference.ai.azure.com",
+    model: "gpt-4o-mini",
+  },
+  openai: {
+    provider: "openai_compatible",
+    baseUrl: "https://api.openai.com/v1",
+    model: "gpt-4o-mini",
+  },
+  anthropic: {
+    provider: "anthropic",
+    baseUrl: "https://api.anthropic.com",
+    model: "claude-sonnet-4-20250514",
+  },
+  google: {
+    provider: "google",
+    baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+    model: "gemini-2.0-flash",
+  },
+};
+
 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 || {};
@@ -19,13 +46,21 @@ export async function generateText({ system, user, temperature, maxTokens, confi
     };
   }
   
-  // Get provider configuration (env vars take precedence, then config, then defaults)
-  const provider = process.env.REPOLENS_AI_PROVIDER || aiConfig.provider || "openai_compatible";
-  const baseUrl = process.env.REPOLENS_AI_BASE_URL || aiConfig.base_url;
+  // Check for preset (takes precedence over individual settings)
+  const preset = process.env.REPOLENS_AI_PRESET?.toLowerCase();
+  const presetConfig = preset ? AI_PRESETS[preset] : null;
+  
+  if (preset && !presetConfig) {
+    warn(`Unknown AI preset "${preset}". Valid presets: ${Object.keys(AI_PRESETS).join(", ")}`);
+  }
+  
+  // Get provider configuration (preset > env vars > config > defaults)
+  const provider = presetConfig?.provider || process.env.REPOLENS_AI_PROVIDER || aiConfig.provider || "openai_compatible";
+  const baseUrl = presetConfig?.baseUrl || process.env.REPOLENS_AI_BASE_URL || aiConfig.base_url;
   // For "github" provider, fall back to GITHUB_TOKEN when no explicit AI key is set
   const apiKey = process.env.REPOLENS_AI_API_KEY
     || (provider === "github" ? process.env.GITHUB_TOKEN : undefined);
-  const model = process.env.REPOLENS_AI_MODEL || aiConfig.model || getDefaultModel(provider);
+  const model = presetConfig?.model || process.env.REPOLENS_AI_MODEL || aiConfig.model || getDefaultModel(provider);
   const timeoutMs = parseInt(process.env.REPOLENS_AI_TIMEOUT_MS || aiConfig.timeout_ms || DEFAULT_TIMEOUT_MS);
   
   // Use config values as fallback for maxTokens; temperature only when explicitly set

package/src/core/config-schema.js

@@ -367,3 +367,89 @@ export function isFeatureEnabled(config, featureName, defaultValue = true) {
     ? config.features[featureName] 
     : defaultValue;
 }
+
+// Valid top-level config keys
+const VALID_CONFIG_KEYS = [
+  "configVersion",
+  "project",
+  "publishers",
+  "scan",
+  "module_roots",
+  "outputs",
+  "notion",
+  "confluence",
+  "github_wiki",
+  "discord",
+  "features",
+  "ai",
+  "documentation",
+  "domains",
+  "plugins",
+];
+
+/**
+ * Calculate Levenshtein distance between two strings.
+ */
+function levenshteinDistance(a, b) {
+  const matrix = Array.from({ length: a.length + 1 }, (_, i) =>
+    Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
+  );
+  
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,      // deletion
+        matrix[i][j - 1] + 1,      // insertion
+        matrix[i - 1][j - 1] + cost // substitution
+      );
+    }
+  }
+  
+  return matrix[a.length][b.length];
+}
+
+/**
+ * Find closest matching valid key for a typo.
+ * @param {string} typo - The potentially misspelled key
+ * @param {string[]} validKeys - Array of valid keys
+ * @param {number} maxDistance - Maximum Levenshtein distance to consider (default: 3)
+ * @returns {string|null} - Suggestion or null if no close match
+ */
+function findClosestKey(typo, validKeys, maxDistance = 3) {
+  let closest = null;
+  let minDist = Infinity;
+  
+  for (const key of validKeys) {
+    const dist = levenshteinDistance(typo.toLowerCase(), key.toLowerCase());
+    if (dist < minDist && dist <= maxDistance) {
+      minDist = dist;
+      closest = key;
+    }
+  }
+  
+  return closest;
+}
+
+/**
+ * Check config for typos in top-level keys.
+ * @param {object} config - The parsed config object
+ * @returns {Array<{key: string, suggestion: string}>} - List of detected typos with suggestions
+ */
+export function detectConfigTypos(config) {
+  const typos = [];
+  
+  for (const key of Object.keys(config)) {
+    if (!VALID_CONFIG_KEYS.includes(key)) {
+      const suggestion = findClosestKey(key, VALID_CONFIG_KEYS);
+      if (suggestion) {
+        typos.push({ key, suggestion });
+      }
+    }
+  }
+  
+  return typos;
+}
+
+// Export constants for use in doctor
+export { SUPPORTED_PUBLISHERS, SUPPORTED_PAGE_KEYS, VALID_CONFIG_KEYS };

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

@@ -99,7 +99,12 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   }
 
   // Generate each document
+  const totalDocs = activeDocuments.length;
+  let docIndex = 0;
+  
   for (const docPlan of activeDocuments) {
+    docIndex++;
+    info(`[${docIndex}/${totalDocs}] Generating ${docPlan.key}...`);
     let content = null;
     
     try {

package/src/doctor.js

@@ -1,6 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import yaml from "js-yaml";
 import { loadConfig } from "./core/config.js";
+import { detectConfigTypos } from "./core/config-schema.js";
 import { info } from "./utils/logger.js";
 import { forceCheckForUpdates } from "./utils/update-check.js";
 
@@ -112,13 +114,34 @@ export async function runDoctor(targetDir = process.cwd()) {
   let cfg = null;
 
   if (await fileExists(repolensConfigPath)) {
+    // First parse YAML to check for typos (before full validation)
+    let rawConfig = null;
     try {
-      cfg = await loadConfig(repolensConfigPath);
-      ok("RepoLens config parsed successfully");
-    } catch (error) {
-      fail(`RepoLens config is invalid: ${error.message}`);
+      const rawYaml = await fs.readFile(repolensConfigPath, "utf8");
+      rawConfig = yaml.load(rawYaml);
+      
+      // Check for config key typos before validation
+      if (rawConfig && typeof rawConfig === "object") {
+        const typos = detectConfigTypos(rawConfig);
+        for (const { key, suggestion } of typos) {
+          warn(`Unknown config key "${key}" — did you mean "${suggestion}"?`);
+        }
+      }
+    } catch (yamlError) {
+      fail(`RepoLens config has invalid YAML syntax: ${yamlError.message}`);
       hasFailures = true;
     }
+    
+    // Now run full validation
+    if (rawConfig) {
+      try {
+        cfg = await loadConfig(repolensConfigPath);
+        ok("RepoLens config parsed successfully");
+      } catch (error) {
+        fail(`RepoLens config is invalid: ${error.message}`);
+        hasFailures = true;
+      }
+    }
   }
 
   if (cfg) {

package/src/publishers/index.js

@@ -28,9 +28,9 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
 
   // --- Hash-based caching: skip unchanged documents ---
   const cacheDir = path.join(process.cwd(), cfg.documentation?.output_dir || ".repolens");
-  const previousCache = await loadDocCache(cacheDir);
+  const { cache: previousCache, age: cacheAge } = await loadDocCache(cacheDir);
   const { changedPages, unchangedKeys, newCache } = filterChangedDocs(renderedPages, previousCache);
-  logCacheStats(Object.keys(changedPages).length, unchangedKeys.length);
+  logCacheStats(Object.keys(changedPages).length, unchangedKeys.length, cacheAge);
 
   // Use changedPages for API publishers (Notion / Confluence / Wiki), full set for Markdown
   const pagesForAPIs = Object.keys(changedPages).length > 0 ? changedPages : renderedPages;

package/src/utils/doc-cache.js

@@ -6,7 +6,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { info } from "./logger.js";
+import { info, verbose } from "./logger.js";
 
 const CACHE_FILENAME = "doc-hashes.json";
 
@@ -19,14 +19,19 @@ function hashContent(content) {
 
 /**
  * Load the previous cache from disk.
- * @returns {Record<string, string>} Map of docKey → contentHash
+ * @returns {{ cache: Record<string, string>, age: number|null }} Map of docKey → contentHash and cache age in ms
  */
 export async function loadDocCache(cacheDir) {
+  const cachePath = path.join(cacheDir, CACHE_FILENAME);
   try {
-    const raw = await fs.readFile(path.join(cacheDir, CACHE_FILENAME), "utf8");
-    return JSON.parse(raw);
+    const [raw, stat] = await Promise.all([
+      fs.readFile(cachePath, "utf8"),
+      fs.stat(cachePath),
+    ]);
+    const age = Date.now() - stat.mtimeMs;
+    return { cache: JSON.parse(raw), age };
   } catch {
-    return {};
+    return { cache: {}, age: null };
   }
 }
 
@@ -65,14 +70,25 @@ export function filterChangedDocs(renderedPages, previousCache) {
   return { changedPages, unchangedKeys, newCache };
 }
 
+/**
+ * Format duration in human-readable form.
+ */
+function formatAge(ms) {
+  if (ms < 60000) return `${Math.round(ms / 1000)}s ago`;
+  if (ms < 3600000) return `${Math.round(ms / 60000)}m ago`;
+  if (ms < 86400000) return `${Math.round(ms / 3600000)}h ago`;
+  return `${Math.round(ms / 86400000)}d ago`;
+}
+
 /**
  * Log cache statistics.
  */
-export function logCacheStats(changedCount, unchangedCount) {
+export function logCacheStats(changedCount, unchangedCount, cacheAge = null) {
   const total = changedCount + unchangedCount;
+  const ageStr = cacheAge ? ` (last run: ${formatAge(cacheAge)})` : "";
   if (unchangedCount > 0) {
-    info(`Cache: ${unchangedCount}/${total} documents unchanged, skipping. ${changedCount} to publish.`);
+    info(`Cache: ${unchangedCount}/${total} documents unchanged, skipping. ${changedCount} to publish.${ageStr}`);
   } else {
-    info(`Cache: All ${total} documents changed or new.`);
+    info(`Cache: All ${total} documents changed or new.${ageStr}`);
   }
 }

package/src/utils/logger.js

@@ -1,6 +1,6 @@
 import { sanitizeSecrets } from "./secrets.js";
 
-const isVerbose = process.argv.includes("--verbose");
+export const isVerbose = process.argv.includes("--verbose");
 const isTest = process.env.NODE_ENV === "test";
 
 // Terminal color support detection
@@ -71,6 +71,16 @@ export function log(...args) {
   }
 }
 
+/**
+ * Verbose-only logging (alias for log, for semantic clarity).
+ * Only outputs when --verbose flag is present.
+ */
+export function verbose(...args) {
+  if (!isTest && isVerbose) {
+    console.log("[RepoLens]", ...sanitizeArgs(args));
+  }
+}
+
 export function info(...args) {
   if (!isTest) {
     console.log("[RepoLens]", ...sanitizeArgs(args));