@chappibunny/repolens 1.14.3 → 1.15.1

package/src/init.js

@@ -4,6 +4,8 @@ import { createInterface } from "node:readline/promises";
 import { spawn } from "node:child_process";
 import { info, warn } from "./utils/logger.js";
 import { isNonInteractiveEnvironment } from "./utils/interactive.js";
+import { detectRepoLanguages } from "./core/languages.js";
+import { repolensCommand } from "./utils/invocation.js";
 
 const PUBLISHER_CHOICES = ["markdown", "notion", "confluence", "github_wiki", "obsidian"];
 
@@ -315,21 +317,6 @@ const SCAN_PRESETS = {
   },
 };
 
-const DETECTABLE_ROOTS = [
-  "app",
-  "src/app",
-  "components",
-  "src/components",
-  "lib",
-  "src/lib",
-  "hooks",
-  "src/hooks",
-  "store",
-  "src/store",
-  "pages",
-  "src/pages"
-];
-
 const DEFAULT_GITHUB_WORKFLOW = `name: RepoLens Documentation
 
 on:
@@ -422,7 +409,8 @@ This repository is configured to use [RepoLens](https://github.com/CHAPIBUNNY/re
 ### Local Testing
 
 \`\`\`bash
-# Test documentation generation locally
+# Test documentation generation locally.
+# Use \`repolens publish\` when the CLI is on your PATH.
 npx @chappibunny/repolens publish
 \`\`\`
 
@@ -557,15 +545,6 @@ async function fileExists(filePath) {
   }
 }
 
-async function dirExists(dirPath) {
-  try {
-    const stat = await fs.stat(dirPath);
-    return stat.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Open a URL in the default browser (cross-platform).
  */
@@ -680,23 +659,6 @@ async function testAIKey(provider, apiKey) {
   }
 }
 
-async function detectRepoStructure(repoRoot) {
-  const detectedRoots = [];
-
-  for (const relativePath of DETECTABLE_ROOTS) {
-    const absolutePath = path.join(repoRoot, relativePath);
-    if (await dirExists(absolutePath)) {
-      detectedRoots.push(relativePath);
-    }
-  }
-
-  return detectedRoots;
-}
-
-function buildIncludePatterns(detectedRoots) {
-  return detectedRoots.map((root) => `${root}/**/*.{ts,tsx,js,jsx,md}`);
-}
-
 function buildIgnorePatterns() {
   return [
     "tools/repolens/**",
@@ -717,12 +679,18 @@ function buildIgnorePatterns() {
     "**/esm/**",
     "**/imp/**",
     "**/types/**",
-    "**/load-testing/**"
+    "**/load-testing/**",
+    "**/__pycache__/**",
+    "**/.venv/**",
+    "**/venv/**",
+    "**/vendor/**",
+    "**/target/**"
   ];
 }
 
-function buildRepoLensConfig(projectName, detectedRoots, options = {}) {
-  const includePatterns = buildIncludePatterns(detectedRoots);
+function buildRepoLensConfig(projectName, detected, options = {}) {
+  const includePatterns = detected?.include?.length ? detected.include : ["**/*.{js,jsx,ts,tsx,py,go,rs,java}"];
+  const moduleRoots = detected?.moduleRoots?.length ? detected.moduleRoots : ["."];
   const ignorePatterns = buildIgnorePatterns();
   const enableAI = options.enableAI || false;
 
@@ -734,9 +702,7 @@ function buildRepoLensConfig(projectName, detectedRoots, options = {}) {
     `  docs_title_prefix: "RepoLens"`,
     ``,
     `publishers:`,
-    `  - markdown    # Always generate local Markdown files`,
-    `  - notion      # Auto-detected: publishes if NOTION_TOKEN is set`,
-    `  - confluence  # Auto-detected: publishes if CONFLUENCE_URL is set`,
+    `  - markdown    # Local files. The wizard (repolens init) can add Notion, Confluence, GitHub Wiki, and Obsidian.`,
     ``,
     `# Docs by RepoLens badge on generated Markdown (default: on)`,
     `# branding: false`,
@@ -799,13 +765,8 @@ function buildRepoLensConfig(projectName, detectedRoots, options = {}) {
   lines.push(`scan:`);
   lines.push(`  include:`);
 
-  if (includePatterns.length) {
-    for (const pattern of includePatterns) {
-      lines.push(`    - "${pattern}"`);
-    }
-  } else {
-    lines.push(`    - "src/**/*.{ts,tsx,js,jsx,md}"`);
-    lines.push(`    - "app/**/*.{ts,tsx,js,jsx,md}"`);
+  for (const pattern of includePatterns) {
+    lines.push(`    - "${pattern}"`);
   }
 
   lines.push(``);
@@ -818,17 +779,8 @@ function buildRepoLensConfig(projectName, detectedRoots, options = {}) {
   lines.push(``);
   lines.push(`module_roots:`);
 
-  if (detectedRoots.length) {
-    for (const root of detectedRoots) {
-      lines.push(`  - "${root}"`);
-    }
-  } else {
-    lines.push(`  - "app"`);
-    lines.push(`  - "src/app"`);
-    lines.push(`  - "components"`);
-    lines.push(`  - "src/components"`);
-    lines.push(`  - "lib"`);
-    lines.push(`  - "src/lib"`);
+  for (const root of moduleRoots) {
+    lines.push(`  - "${root}"`);
   }
 
   lines.push(``);
@@ -1552,8 +1504,15 @@ export { parseConfluenceUrl, parseNotionInput };
 export async function runInit(targetDir = process.cwd(), options = {}) {
   const repoRoot = path.resolve(targetDir);
 
-  // Ensure target directory exists
-  await fs.mkdir(repoRoot, { recursive: true });
+  let targetStat;
+  try {
+    targetStat = await fs.stat(repoRoot);
+  } catch {
+    throw new Error(`Target directory not found: ${targetDir}`);
+  }
+  if (!targetStat.isDirectory()) {
+    throw new Error(`Target directory not found: ${targetDir}`);
+  }
 
   // Interactive wizard is the default (--quick skips it).
   // CI, tests, and closed stdin used to return null from the wizard and
@@ -1568,8 +1527,10 @@ export async function runInit(targetDir = process.cwd(), options = {}) {
     info("Non-interactive environment detected — running quick setup instead of the wizard.");
   }
 
-  // Prompt for Notion credentials interactively (only in non-wizard mode)
-  const notionCredentials = wizardAnswers ? null : await promptNotionCredentials();
+  // --quick is Markdown only. The wizard collects Notion and Confluence.
+  const notionCredentials = wizardAnswers || options.interactive === false
+    ? null
+    : await promptNotionCredentials();
 
   const repolensConfigPath = path.join(repoRoot, ".repolens.yml");
   const workflowDir = path.join(repoRoot, ".github", "workflows");
@@ -1587,25 +1548,31 @@ export async function runInit(targetDir = process.cwd(), options = {}) {
   const readmeExists = await fileExists(readmePath);
 
   const projectName = wizardAnswers?.projectName || detectProjectName(repoRoot);
-  const detectedRoots = wizardAnswers ? [] : await detectRepoStructure(repoRoot);
+  const detected = wizardAnswers ? null : await detectRepoLanguages(repoRoot);
 
   // Auto-detect GITHUB_TOKEN for AI enablement
   const hasGitHubToken = !!process.env.GITHUB_TOKEN;
   const configContent = wizardAnswers
     ? buildWizardConfig(wizardAnswers)
-    : buildRepoLensConfig(projectName, detectedRoots, { enableAI: hasGitHubToken });
+    : buildRepoLensConfig(projectName, detected, { enableAI: hasGitHubToken });
 
   info(`Detected project name: ${projectName}`);
 
-  if (detectedRoots.length) {
-    info(`Detected module roots:`);
-    for (const root of detectedRoots) {
+  if (detected) {
+    if (detected.languages.length) {
+      info(`Detected languages: ${detected.languages.map((lang) => lang.label).join(", ")}`);
+    } else {
+      info("No known language detected. Using multi-language scan patterns.");
+    }
+    info("module_roots:");
+    for (const root of detected.moduleRoots) {
       info(`  - ${root}`);
     }
-  } else if (!wizardAnswers) {
-    info(`No known roots detected. Falling back to default config.`);
   }
 
+  const publishCmd = repolensCommand("publish");
+  const doctorCmd = repolensCommand("doctor");
+
   if (!configExists) {
     await fs.writeFile(repolensConfigPath, configContent, "utf8");
     info(`Created ${repolensConfigPath}`);
@@ -1694,13 +1661,13 @@ NOTION_VERSION=2022-06-28
       info("   └────────────────────────────────────────────────────────────┘");
       info("");
       info("   1. source .env                   ← Load your credentials");
-      info("   2. npx @chappibunny/repolens publish   ← Test locally");
+      info(`   2. ${publishCmd}   ← Test locally`);
     } else {
-      info("   1. npx @chappibunny/repolens publish   ← Test locally");
+      info(`   1. ${publishCmd}   ← Test locally`);
     }
     info(`   ${hasLocalCredentials ? "3" : "2"}. Add GitHub secrets (see above)`);
     info(`   ${hasLocalCredentials ? "4" : "3"}. Commit and push to trigger workflow`);
-    info(`   ${hasLocalCredentials ? "5" : "4"}. Run 'npx @chappibunny/repolens doctor' to validate setup`);
+    info(`   ${hasLocalCredentials ? "5" : "4"}. Run '${doctorCmd}' to validate setup`);
     return;
   }
 
@@ -1714,7 +1681,7 @@ NOTION_VERSION=2022-06-28
     info("   Your credentials are stored in .env (gitignored)\n");
     info("Next steps:");
     info("  1. Review .repolens.yml to customize your documentation");
-    info("  2. Run 'npx @chappibunny/repolens publish' to generate your first docs (deterministic mode)");
+    info(`  2. Run '${publishCmd}' to generate your first docs (deterministic mode)`);
     info("  3. (Optional) Enable AI features:");
     info("     ── FREE: GitHub Models (recommended for GitHub Actions) ──");
     info("     REPOLENS_AI_ENABLED=true");
@@ -1745,7 +1712,7 @@ NOTION_VERSION=2022-06-28
       info("     REPOLENS_AI_API_KEY=sk-...");
       info("     See: https://github.com/CHAPIBUNNY/repolens/blob/main/AI.md");
     }
-    info(`  ${hasGitHubToken ? "3" : "4"}. Run 'npx @chappibunny/repolens publish' to test locally`);
+    info(`  ${hasGitHubToken ? "3" : "4"}. Run '${publishCmd}' to test locally`);
     info(`  ${hasGitHubToken ? "4" : "5"}. Commit the generated files`);
   }
 }

package/src/publishers/index.js

@@ -20,6 +20,39 @@ function hasNotionSecrets() {
   return !!process.env.NOTION_TOKEN && !!process.env.NOTION_PARENT_PAGE_ID;
 }
 
+/**
+ * Credentials a configured publisher still needs.
+ * Markdown has none. Used by `publish --strict`.
+ */
+export function missingPublisherCredentials(cfg) {
+  const publishers = Array.isArray(cfg?.publishers) ? cfg.publishers : [];
+  const missing = [];
+
+  if (publishers.includes("notion")) {
+    if (!process.env.NOTION_TOKEN) missing.push("NOTION_TOKEN (required for notion)");
+    if (!process.env.NOTION_PARENT_PAGE_ID) missing.push("NOTION_PARENT_PAGE_ID (required for notion)");
+  }
+
+  if (publishers.includes("confluence")) {
+    for (const key of ["CONFLUENCE_URL", "CONFLUENCE_EMAIL", "CONFLUENCE_API_TOKEN", "CONFLUENCE_SPACE_KEY"]) {
+      if (!process.env[key]) missing.push(`${key} (required for confluence)`);
+    }
+  }
+
+  if (publishers.includes("github_wiki")) {
+    if (!process.env.GITHUB_TOKEN) missing.push("GITHUB_TOKEN (required for github_wiki)");
+  }
+
+  if (publishers.includes("obsidian")) {
+    const vault = cfg?.obsidian?.vault;
+    if (typeof vault !== "string" || vault.trim() === "") {
+      missing.push("obsidian.vault (required for obsidian)");
+    }
+  }
+
+  return missing;
+}
+
 export async function publishDocs(cfg, renderedPages, scanResult, pluginManager = null) {
   const publishers = cfg.publishers || ["markdown", "notion"];
   const currentBranch = getCurrentBranch();

package/src/renderers/renderAnalysis.js

@@ -593,7 +593,7 @@ export function renderCodeHealth(healthResult) {
   lines.push("");
   lines.push("| Factor | Weight | How It's Measured |");
   lines.push("|--------|--------|-------------------|");
-  lines.push("| Complexity | –1/pt above 10, –2/pt above 30 | Cyclomatic complexity (if/else/for/while/case/&&/\\|\\|/ternary) |");
+  lines.push("| Complexity | –1/pt above 10, –2/pt above 30 | Cyclomatic complexity for JavaScript/TypeScript, Python, and Go (regex, not AST) |");
   lines.push("| Function complexity | –2/pt above 8 per function | Highest complexity function in the file |");
   lines.push("| Coupling | –1/5 units above 20 | Fan-in × Fan-out (import connections) |");
   lines.push("| Documentation | –10 if <50%, –5 if <80% | JSDoc/TSDoc coverage of exports |");
@@ -602,7 +602,7 @@ export function renderCodeHealth(healthResult) {
 
   lines.push("---");
   lines.push("");
-  lines.push("*Generated by RepoLens code health analysis. Complexity is regex-based and may differ from AST-based tools. Scores are relative indicators, not absolute quality measures.*");
+  lines.push("*Generated by RepoLens code health analysis. Complexity covers JavaScript/TypeScript, Python, and Go. It is regex-based and may differ from AST-based tools. Scores are relative indicators, not absolute quality measures.*");
   lines.push("");
 
   return lines.join("\n");

package/src/utils/banner.js

@@ -0,0 +1,9 @@
+/**
+ * The ASCII banner is for an interactive terminal.
+ * CI logs and pipes get the normal command output only.
+ */
+export function shouldPrintBanner({ isTTY = Boolean(process.stdout.isTTY), env = process.env } = {}) {
+  if (env && env.CI) return false;
+  if (!isTTY) return false;
+  return true;
+}

package/src/utils/invocation.js

@@ -0,0 +1,54 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * True when `entryPath` is the RepoLens install under npm's global prefix.
+ * npx caches live under `_npx` and are not a global install.
+ */
+export function isGlobalInstallPath(entryPath, globalPrefix) {
+  if (!entryPath || !globalPrefix) return false;
+  if (entryPath.includes(`${path.sep}_npx${path.sep}`)) return false;
+  let entry = entryPath;
+  let prefix = globalPrefix;
+  try {
+    entry = fs.realpathSync(entryPath);
+  } catch {
+    entry = path.resolve(entryPath);
+  }
+  prefix = path.resolve(globalPrefix);
+  return entry === prefix || entry.startsWith(prefix + path.sep);
+}
+
+let cachedGlobal = null;
+
+export function isGlobalInstall() {
+  if (cachedGlobal != null) return cachedGlobal;
+  const entry = process.argv[1];
+  if (!entry) {
+    cachedGlobal = false;
+    return false;
+  }
+  try {
+    const prefix = execFileSync("npm", ["prefix", "-g"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+    cachedGlobal = isGlobalInstallPath(entry, prefix);
+  } catch {
+    cachedGlobal = false;
+  }
+  return cachedGlobal;
+}
+
+/**
+ * Command shown in init's next-steps text.
+ * Global installs get `repolens publish`. Everything else gets npx.
+ */
+export function repolensCommand(subcommand, options = {}) {
+  const globalInstall = options.globalInstall ?? isGlobalInstall();
+  const bin = globalInstall ? "repolens" : "npx @chappibunny/repolens";
+  if (!subcommand) return bin;
+  return `${bin} ${subcommand}`;
+}

package/src/watch.js

@@ -37,45 +37,62 @@ async function rebuild(configPath) {
  * @param {string} configPath - Resolved path to .repolens.yml
  */
 export async function runWatch(configPath) {
-  info("Starting watch mode (Markdown only)...");
-  info("Press Ctrl+C to stop.\n");
-
-  // Initial build
-  await rebuild(configPath);
-
-  // Determine directories to watch from config
   const cfg = await loadConfig(configPath);
   const repoRoot = cfg.__repoRoot || process.cwd();
   const moduleRoots = cfg.module_roots || ["src", "app", "lib"];
 
-  let debounceTimer = null;
-
-  const onChange = () => {
-    if (debounceTimer) clearTimeout(debounceTimer);
-    debounceTimer = setTimeout(() => rebuild(configPath), DEBOUNCE_MS);
-  };
-
-  const watchers = [];
+  const watchable = [];
   for (const root of moduleRoots) {
     const dirPath = path.resolve(repoRoot, root);
     try {
       fs.accessSync(dirPath);
-      const watcher = fs.watch(dirPath, { recursive: true }, (eventType, filename) => {
-        if (filename && !filename.includes("node_modules")) {
-          info(`Change detected: ${root}/${filename}`);
-          onChange();
-        }
-      });
-      watchers.push(watcher);
-      info(`Watching: ${root}/`);
+      watchable.push({ root, dirPath });
     } catch {
       // Directory doesn't exist, skip
     }
   }
 
-  if (watchers.length === 0) {
-    warn("No directories to watch. Check module_roots in .repolens.yml");
-    return;
+  if (watchable.length === 0) {
+    const hint = "No directories to watch. Check module_roots in .repolens.yml — none of the configured roots exist.";
+    warn(hint);
+    error(hint);
+    return { ok: false, message: hint };
+  }
+
+  // A root can exist (including "." after init --quick in an empty directory)
+  // while scan.include still matches nothing. Do not wait forever in that case.
+  const scan = await scanRepo(cfg);
+  if ((scan?.filesCount || 0) === 0) {
+    const patterns = (cfg.scan?.include || []).join(", ") || "(none)";
+    const hint = `No files matched scan.include (${patterns}). Nothing to watch. Check scan.include and module_roots in .repolens.yml. Add source files or update the globs, then run watch again.`;
+    warn(hint);
+    error(hint);
+    return { ok: false, message: hint };
+  }
+
+  info("Starting watch mode (Markdown only)...");
+  info("Press Ctrl+C to stop.\n");
+
+  // Initial build only when there is something to watch.
+  await rebuild(configPath);
+
+  let debounceTimer = null;
+
+  const onChange = () => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => rebuild(configPath), DEBOUNCE_MS);
+  };
+
+  const watchers = [];
+  for (const { root, dirPath } of watchable) {
+    const watcher = fs.watch(dirPath, { recursive: true }, (eventType, filename) => {
+      if (filename && !filename.includes("node_modules")) {
+        info(`Change detected: ${root}/${filename}`);
+        onChange();
+      }
+    });
+    watchers.push(watcher);
+    info(`Watching: ${root}/`);
   }
 
   info("\nWaiting for changes...\n");