@chappibunny/repolens 1.14.3 → 1.15.0

package/src/core/languages.js

@@ -0,0 +1,268 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Language profiles used by `init --quick` and config-less `demo`.
+ * Globs are repository-wide so a Python package that lives next to setup.py
+ * is scanned even when it is not under src/.
+ */
+export const LANGUAGE_PROFILES = [
+  {
+    id: "python",
+    label: "Python",
+    markers: ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile", "poetry.lock"],
+    extensions: [".py"],
+    include: ["**/*.py"],
+    candidateRoots: ["src", "app", "lib", "api", "core", "services"],
+  },
+  {
+    id: "go",
+    label: "Go",
+    markers: ["go.mod"],
+    extensions: [".go"],
+    include: ["**/*.go"],
+    candidateRoots: ["cmd", "internal", "pkg", "api"],
+  },
+  {
+    id: "rust",
+    label: "Rust",
+    markers: ["Cargo.toml"],
+    extensions: [".rs"],
+    include: ["**/*.rs"],
+    candidateRoots: ["src", "crates"],
+  },
+  {
+    id: "java",
+    label: "Java",
+    markers: ["pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts"],
+    extensions: [".java", ".kt", ".kts", ".scala"],
+    include: ["**/*.{java,kt,kts,scala}"],
+    candidateRoots: ["src/main/java", "src/main/kotlin", "src/main/scala", "src", "app"],
+  },
+  {
+    id: "javascript",
+    label: "JavaScript",
+    markers: ["package.json", "tsconfig.json", "jsconfig.json"],
+    extensions: [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".vue", ".svelte"],
+    include: ["**/*.{js,jsx,mjs,cjs,ts,tsx,vue,svelte}"],
+    candidateRoots: ["src", "app", "lib", "pages", "components", "packages"],
+  },
+  {
+    id: "ruby",
+    label: "Ruby",
+    markers: ["Gemfile"],
+    extensions: [".rb"],
+    include: ["**/*.rb"],
+    candidateRoots: ["app", "lib"],
+  },
+  {
+    id: "php",
+    label: "PHP",
+    markers: ["composer.json"],
+    extensions: [".php"],
+    include: ["**/*.php"],
+    candidateRoots: ["src", "app", "lib"],
+  },
+  {
+    id: "csharp",
+    label: "C#",
+    markers: ["*.csproj", "*.sln"],
+    extensions: [".cs"],
+    include: ["**/*.cs"],
+    candidateRoots: ["src"],
+  },
+  {
+    id: "swift",
+    label: "Swift",
+    markers: ["Package.swift"],
+    extensions: [".swift"],
+    include: ["**/*.swift"],
+    candidateRoots: ["Sources", "src"],
+  },
+  {
+    id: "cpp",
+    label: "C",
+    markers: ["CMakeLists.txt"],
+    extensions: [".c", ".cc", ".cpp", ".h", ".hpp"],
+    include: ["**/*.{c,cc,cpp,h,hpp}"],
+    candidateRoots: ["src", "include"],
+  },
+];
+
+const EXT_TO_LANGUAGE = new Map();
+for (const profile of LANGUAGE_PROFILES) {
+  for (const ext of profile.extensions) {
+    if (!EXT_TO_LANGUAGE.has(ext)) EXT_TO_LANGUAGE.set(ext, profile.id);
+  }
+}
+
+const SKIP_DIRS = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  ".repolens",
+  ".next",
+  ".venv",
+  "venv",
+  "node_modules",
+  "vendor",
+  "target",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "__pycache__",
+  ".tox",
+  ".mypy_cache",
+]);
+
+const UNIVERSAL_CANDIDATE_ROOTS = ["src", "app", "lib", "cmd", "internal", "pkg", "packages"];
+
+export const UNIVERSAL_INCLUDE = [
+  "**/*.{js,jsx,mjs,cjs,ts,tsx,vue,svelte,py,go,rs,java,kt,kts,scala,rb,php,cs,swift,c,cc,cpp,h,hpp}",
+];
+
+const MAX_WALK_ENTRIES = 8000;
+const MAX_WALK_DEPTH = 4;
+
+function markerMatches(marker, rootNames) {
+  if (marker.startsWith("*.")) {
+    const suffix = marker.slice(1);
+    return rootNames.some((name) => name.endsWith(suffix));
+  }
+  return rootNames.includes(marker);
+}
+
+function rootRank(root) {
+  const base = root.split("/").pop() || root;
+  if (/^(tests?|specs?|__tests__|testdata)$/i.test(base)) return 2;
+  if (/^(docs|examples?|benchmarks?)$/i.test(base)) return 1;
+  return 0;
+}
+
+function compareRoots(a, b) {
+  const rank = rootRank(a) - rootRank(b);
+  if (rank !== 0) return rank;
+  return a.localeCompare(b);
+}
+
+async function dirExists(dirPath) {
+  try {
+    const stat = await fs.stat(dirPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function walkSourceTree(repoRoot) {
+  const extCounts = new Map();
+  const topLevelExts = new Map();
+  const rootNames = [];
+  let seen = 0;
+
+  async function walk(dir, depth) {
+    if (depth > MAX_WALK_DEPTH || seen >= MAX_WALK_ENTRIES) return;
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (seen >= MAX_WALK_ENTRIES) return;
+      seen += 1;
+      if (entry.isSymbolicLink()) continue;
+
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+        await walk(path.join(dir, entry.name), depth + 1);
+        continue;
+      }
+
+      if (!entry.isFile()) continue;
+      const ext = path.extname(entry.name).toLowerCase();
+      if (EXT_TO_LANGUAGE.has(ext)) {
+        extCounts.set(ext, (extCounts.get(ext) || 0) + 1);
+      }
+
+      const relDir = path.relative(repoRoot, dir);
+      if (!relDir) {
+        rootNames.push(entry.name);
+        continue;
+      }
+
+      const top = relDir.split(path.sep)[0];
+      if (!topLevelExts.has(top)) topLevelExts.set(top, new Set());
+      if (ext) topLevelExts.get(top).add(ext);
+    }
+  }
+
+  await walk(repoRoot, 0);
+  return { extCounts, topLevelExts, rootNames };
+}
+
+/**
+ * Detect languages and the scan globs / module roots that fit this repository.
+ * Always returns at least one include pattern and one module root.
+ */
+export async function detectRepoLanguages(repoRoot) {
+  const root = path.resolve(repoRoot);
+  const { extCounts, topLevelExts, rootNames } = await walkSourceTree(root);
+
+  const presentIds = new Set();
+  for (const ext of extCounts.keys()) {
+    const id = EXT_TO_LANGUAGE.get(ext);
+    if (id) presentIds.add(id);
+  }
+
+  const detected = LANGUAGE_PROFILES.filter((profile) => {
+    if (presentIds.has(profile.id)) return true;
+    return profile.markers.some((marker) => markerMatches(marker, rootNames));
+  });
+
+  const include = [];
+  const seenInclude = new Set();
+  const source = detected.length > 0 ? detected.flatMap((profile) => profile.include) : UNIVERSAL_INCLUDE;
+  for (const pattern of source) {
+    if (seenInclude.has(pattern)) continue;
+    seenInclude.add(pattern);
+    include.push(pattern);
+  }
+
+  const sourceExts = new Set();
+  const profilesForRoots = detected.length > 0 ? detected : LANGUAGE_PROFILES;
+  for (const profile of profilesForRoots) {
+    if (detected.length > 0 || presentIds.has(profile.id)) {
+      for (const ext of profile.extensions) sourceExts.add(ext);
+    }
+  }
+  if (detected.length === 0) {
+    for (const ext of EXT_TO_LANGUAGE.keys()) sourceExts.add(ext);
+  }
+
+  const moduleRoots = [];
+  for (const [dir, exts] of topLevelExts) {
+    if ([...exts].some((ext) => sourceExts.has(ext))) moduleRoots.push(dir);
+  }
+
+  if (moduleRoots.length === 0) {
+    const candidates = detected.length > 0
+      ? [...new Set(detected.flatMap((profile) => profile.candidateRoots))]
+      : UNIVERSAL_CANDIDATE_ROOTS;
+    for (const candidate of candidates) {
+      if (await dirExists(path.join(root, candidate))) moduleRoots.push(candidate);
+    }
+  }
+
+  if (moduleRoots.length === 0) moduleRoots.push(".");
+
+  moduleRoots.sort(compareRoots);
+
+  return {
+    languages: detected.map((profile) => ({ id: profile.id, label: profile.label })),
+    include,
+    moduleRoots,
+  };
+}

package/src/core/scan.js

@@ -476,20 +476,25 @@ function isValidRoutePath(p) {
   return p.startsWith("/") || /^[a-zA-Z0-9]/.test(p);
 }
 
-export async function scanRepo(cfg) {
+export async function listMatchedFiles(cfg) {
   const repoRoot = cfg.__repoRoot;
-
   const rootResolved = path.resolve(repoRoot);
-  const files = (await fg(cfg.scan.include, {
+  const files = await fg(cfg.scan.include, {
     cwd: rootResolved,
-    ignore: cfg.scan.ignore,
+    ignore: cfg.scan?.ignore || [],
     onlyFiles: true,
     followSymbolicLinks: false,
     absolute: false
-  })).filter((file) => isInsideRoot(rootResolved, path.resolve(rootResolved, file)));
+  });
+  return files.filter((file) => isInsideRoot(rootResolved, path.resolve(rootResolved, file)));
+}
+
+export async function scanRepo(cfg) {
+  const repoRoot = cfg.__repoRoot;
+  const files = await listMatchedFiles(cfg);
 
   if (files.length === 0) {
-    warn("No files matched the scan patterns. Documentation will be mostly empty. Check scan.include in .repolens.yml.");
+    warn("No files matched the scan patterns. Check scan.include in .repolens.yml.");
   }
 
   // Performance guardrails

package/src/doctor.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { loadYaml } from "./utils/yaml.js";
 import { loadConfig } from "./core/config.js";
+import { listMatchedFiles } from "./core/scan.js";
 import { detectConfigTypos } from "./core/config-schema.js";
 import { info } from "./utils/logger.js";
 import { forceCheckForUpdates } from "./utils/update-check.js";
@@ -56,8 +57,11 @@ function ok(message) {
   info(`✅ ${message}`);
 }
 
+let activeFailures = null;
+
 function fail(message) {
   info(`❌ ${message}`);
+  if (activeFailures) activeFailures.push(message);
 }
 
 function warn(message) {
@@ -66,6 +70,8 @@ function warn(message) {
 
 export async function runDoctor(targetDir = process.cwd()) {
   const repoRoot = path.resolve(targetDir);
+  const failures = [];
+  activeFailures = failures;
 
   const repolensConfigPath = path.join(repoRoot, ".repolens.yml");
   const workflowPath = path.join(repoRoot, ".github", "workflows", "repolens.yml");
@@ -172,6 +178,20 @@ export async function runDoctor(targetDir = process.cwd()) {
       fail("outputs.pages is missing or empty");
       hasFailures = true;
     }
+
+    try {
+      const matched = await listMatchedFiles(cfg);
+      if (matched.length === 0) {
+        const patterns = (cfg.scan?.include || []).join(", ") || "(none)";
+        fail(`0 files matched scan.include (${patterns}). publish and demo would write empty documentation. Update scan.include, or run \`repolens init --quick\` so the globs match this repository's language.`);
+        hasFailures = true;
+      } else {
+        ok(`scan.include matches ${matched.length} file(s)`);
+      }
+    } catch (error) {
+      fail(`Could not scan repository: ${error.message}`);
+      hasFailures = true;
+    }
   }
 
   // Validate environment variables for configured publishers
@@ -259,10 +279,11 @@ export async function runDoctor(targetDir = process.cwd()) {
 
   if (hasFailures) {
     fail("RepoLens doctor found blocking issues.");
-    process.exitCode = 1;
-    return { ok: false };
+    activeFailures = null;
+    return { ok: false, failures };
   }
 
   ok("RepoLens doctor passed.");
-  return { ok: true };
+  activeFailures = null;
+  return { ok: true, failures };
 }

package/src/help.js

@@ -1,10 +1,237 @@
-export function printHelp() {
-  console.log(`
+const EXIT_CODES = `Exit codes:
+  0  success (including a cancelled wizard, or help with no other work)
+  1  runtime error, or an unknown command
+  2  invalid flags, missing config, target directory not found,
+     a failed doctor check (including 0 files matched),
+     demo or publish scanned 0 files, watch has nothing to watch,
+     publish --strict is missing publisher credentials,
+     or feedback has no terminal`;
+
+const COMMAND_HELP = {
+  init: `
+RepoLens init — scaffold RepoLens files
+
+Usage:
+  repolens init [--target <path>] [--quick]
+
+Options:
+  --target <path>       Repository to scaffold (default: current directory)
+  --quick               Skip the wizard. Markdown publisher only.
+                        Detects the repo language and writes matching globs.
+  --non-interactive     Same as --quick
+  --verbose             Print debug logs
+  --help, -h            Show this help
+
+\`repolens init\` opens the wizard, which can add Notion, Confluence, GitHub
+Wiki, and Obsidian. \`repolens init --quick\` writes a Markdown-only config.
+It detects Python, Go, Rust, Java/Kotlin, JavaScript/TypeScript, Ruby, PHP,
+C#, Swift, and C/C++ (and combinations) and sets scan.include plus
+module_roots from the files it finds. A repository with no recognized
+language gets multi-language globs, not JavaScript-only defaults.
+
+The target directory must already exist.
+
+${EXIT_CODES}
+
+Examples:
+  repolens init
+  repolens init --quick
+  repolens init --target /path/to/repo --quick
+`,
+
+  doctor: `
+RepoLens doctor — validate a RepoLens setup
+
+Usage:
+  repolens doctor [--target <path>]
+
+Options:
+  --target <path>       Repository to validate (default: current directory)
+  --verbose             Print debug logs
+  --help, -h            Show this help
+
+Checks .repolens.yml, the GitHub workflow, publishers, scan.include,
+module_roots, and outputs.pages. A scan that matches 0 files is a blocking
+failure: publish and demo would otherwise write empty docs.
+
+The target directory must already exist.
+
+${EXIT_CODES}
+
+Examples:
+  repolens doctor
+  repolens doctor --target /path/to/repo
+`,
+
+  migrate: `
+RepoLens migrate — upgrade workflow files
+
+Usage:
+  repolens migrate [--target <path>] [--dry-run] [--force]
+
+Options:
+  --target <path>       Repository to migrate (default: current directory)
+  --dry-run             Preview changes without writing them
+  --force               Apply changes without a confirmation prompt
+  --verbose             Print debug logs
+  --help, -h            Show this help
+
+The target directory must already exist.
+
+${EXIT_CODES}
+
+Examples:
+  repolens migrate --dry-run
+  repolens migrate --force
+  repolens migrate --target /path/to/repo
+`,
+
+  publish: `
+RepoLens publish — scan, render, and publish documentation
+
+Usage:
+  repolens publish [--config <path>] [--strict]
+
+Options:
+  --config <path>       Path to .repolens.yml (auto-discovered if omitted)
+  --strict              Exit 2 when a configured publisher is missing
+                        credentials (Notion, Confluence, GitHub Wiki) or
+                        obsidian.vault. Markdown needs no credentials.
+  --verbose             Print debug logs
+  --help, -h            Show this help
+
+Without --strict, a publisher with missing credentials is skipped.
+A scan that matches 0 files exits 2 and does not write empty docs.
+\`publish\` does not accept --dry-run.
+
+${EXIT_CODES}
+
+Examples:
+  repolens publish
+  repolens publish --config /path/.repolens.yml
+  repolens publish --strict
+`,
+
+  demo: `
+RepoLens demo — local preview without API keys
+
+Usage:
+  repolens demo [--target <path>] [--config <path>]
+
+Options:
+  --target <path>       Repository to preview (default: current directory)
+  --config <path>       Path to .repolens.yml (discovered from --target)
+  --verbose             Print debug logs
+  --help, -h            Show this help
+
+With no config, demo detects the repository language and scans matching
+files (Python, Go, Rust, Java, JavaScript, and others). It does not publish
+to Notion or Confluence. A scan that matches 0 files exits 2 and does not
+write empty docs.
+
+The target directory must already exist.
+
+${EXIT_CODES}
+
+Examples:
+  repolens demo
+  repolens demo --target /path/to/repo
+`,
+
+  watch: `
+RepoLens watch — regenerate Markdown when files change
+
+Usage:
+  repolens watch [--config <path>]
+
+Options:
+  --config <path>       Path to .repolens.yml (auto-discovered if omitted)
+  --verbose             Print debug logs
+  --help, -h            Show this help
+
+Watches directories listed in module_roots. If none of those directories
+exist, watch exits 2 and tells you to fix module_roots. Press Ctrl+C to stop
+when a watch is running.
+
+${EXIT_CODES}
+
+Examples:
+  repolens watch
+  repolens watch --config /path/.repolens.yml
+`,
+
+  uninstall: `
+RepoLens uninstall — remove RepoLens-generated files
+
+Usage:
+  repolens uninstall [--target <path>] [--force]
+
+Options:
+  --target <path>       Repository to clean (default: current directory)
+  --force               Remove files without a confirmation prompt
+  --verbose             Print debug logs
+  --help, -h            Show this help
+
+Removes .repolens/, .repolens.yml, .github/workflows/repolens.yml,
+.env.example, and README.repolens.md when those files are present.
+Outside CI, a closed terminal defaults to keeping the files.
+The target directory must already exist.
+
+${EXIT_CODES}
+
+Examples:
+  repolens uninstall --target /path/to/repo
+  repolens uninstall --force
+`,
+
+  feedback: `
+RepoLens feedback — send feedback to the RepoLens team
+
+Usage:
+  repolens feedback
+
+Options:
+  --verbose             Print debug logs
+  --help, -h            Show this help
+
+Needs an interactive terminal. CI, pipes, and REPOLENS_NON_INTERACTIVE
+exit 2.
+
+${EXIT_CODES}
+
+Examples:
+  repolens feedback
+`,
+
+  mcp: `
+RepoLens mcp — stdio MCP server
+
+Usage:
+  repolens mcp
+
+Options:
+  --help, -h            Show this help
+
+Starts the Model Context Protocol server on stdio. \`repolens-mcp\` is the
+same server. Logs go to stderr. The workspace is REPOLENS_WORKSPACE or the
+current directory. Paths cannot leave that directory.
+
+${EXIT_CODES}
+
+Examples:
+  repolens mcp
+`,
+};
+
+const GLOBAL_HELP = `
 RepoLens — Repository Intelligence CLI
 
 Usage:
   repolens <command> [options]
 
+Run \`repolens <command> --help\` for that command's flags.
+With no command, RepoLens prints this help and does not publish.
+
 Commands:
   init        Scaffold RepoLens files in your repository
   doctor      Validate your RepoLens setup
@@ -20,37 +247,54 @@ Commands:
 
 Options:
   --config <path>   Path to .repolens.yml (auto-discovered if omitted)
-  --target <path>   Repository path for init, doctor, migrate, demo, uninstall
-  --quick           Scaffold without the wizard (also --non-interactive)
+  --target <path>   Repository path for init, doctor, migrate, demo, uninstall.
+                    Must already exist.
+  --quick           Scaffold without the wizard (also --non-interactive).
+                    Markdown only; globs follow the detected language.
+  --strict          publish: exit 2 when publisher credentials are missing
   --dry-run         Preview migration changes without writing them
   --force           Apply migrate or uninstall without a confirmation prompt
   --verbose         Print debug logs and full stacks on unexpected errors
   --version, -v     Print version and exit
-  --help, -h        Show this help message
+  --help, -h        Show help. After a command, show that command's help.
 
 Non-interactive sessions (CI, pipes, or REPOLENS_NON_INTERACTIVE):
   init falls back to --quick instead of waiting on the wizard
   yes/no prompts use their default and do not wait (uninstall defaults to no
     on a closed terminal outside CI; CI still removes files and tells you so)
   feedback exits with code 2 because it needs a terminal
+  the ASCII banner is hidden when stdout is not a terminal or CI is set
 
-Exit codes:
-  0  success (including a cancelled wizard)
-  1  runtime error, or an unknown command
-  2  invalid flags, missing config, or a failed doctor check
+${EXIT_CODES}
 
 Examples:
+  repolens
   repolens init
   repolens init --quick
+  repolens init --help
   repolens init --target /tmp/my-repo
   repolens doctor --target /tmp/my-repo
   repolens migrate --dry-run
   repolens publish
+  repolens publish --strict
   repolens publish --config /path/.repolens.yml
   repolens demo
   repolens watch
   repolens uninstall --target /tmp/my-repo
   repolens mcp
   repolens --version
-`);
+`;
+
+const KNOWN_COMMANDS = new Set([...Object.keys(COMMAND_HELP), "version", "help"]);
+
+export function printHelp(command) {
+  if (command && COMMAND_HELP[command]) {
+    console.log(COMMAND_HELP[command]);
+    return;
+  }
+  if (command && !KNOWN_COMMANDS.has(command)) {
+    console.log(`Unknown command: ${command}`);
+    console.log("Run 'repolens help' for the command list.\n");
+  }
+  console.log(GLOBAL_HELP);
 }