@chappibunny/repolens 1.15.0 → 1.15.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.15.1
+
+### Watch and code health
+
+- `watch` exits 2 when `scan.include` matches no files, including after `init --quick` in an empty directory. It prints a hint to fix `scan.include` and `module_roots` and does not wait for changes
+- Code health analyzes Python (`.py`, `.pyw`) and Go (`.go`) as well as JavaScript and TypeScript. A Python or Go repository no longer logs `Code health: no source files analyzed` when source files were scanned. Test modules (`test_*.py`, `*_test.py`, `*_test.go`, and `tests/`) are skipped
+
+Exit codes stay 0 success, 1 runtime error or unknown command, and 2 validation failure (bad flags, missing config, missing target, doctor failure, 0 files scanned, nothing to watch, `--strict` credentials, feedback without a terminal).
+
 ## 1.15.0
 
 ### CLI usability

package/README.md

@@ -29,7 +29,7 @@ RepoLens scans your repository, generates living architecture documentation, and
 
 ## 🎬 Demo
 
-> **Try it now** — no installation required. `npx @chappibunny/repolens demo` previews the repository you point it at. It detects common languages (Python, Go, Rust, Java, JavaScript/TypeScript, and others). If the scan matches no source files, demo exits 2 and does not write empty docs.
+> **Try it now** — no installation required. `npx @chappibunny/repolens demo` previews the repository you point it at. It detects common languages (Python, Go, Rust, Java, JavaScript/TypeScript, and others). If the scan matches no source files, demo exits 2 and does not write empty docs. Code health scores JavaScript/TypeScript, Python, and Go.
 
 **[See it on real repos](https://chapibunny.github.io/repolens/)** — architecture pages RepoLens generated for Express, FastAPI, Django, Gin, mdBook, and other public projects. Deterministic mode, no API keys.
 
@@ -181,7 +181,7 @@ Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki,
 | `npx @chappibunny/repolens publish --strict` | Exit 2 when a configured publisher is missing credentials |
 | `npx @chappibunny/repolens demo` | Local preview — no API keys. Exits 2 when 0 files match |
 | `npx @chappibunny/repolens doctor` | Validate your setup, including that scan globs match files |
-| `npx @chappibunny/repolens watch` | Auto-regenerate docs on file changes. Exits 2 if nothing is watchable |
+| `npx @chappibunny/repolens watch` | Auto-regenerate docs on file changes. Exits 2 if `module_roots` are missing or `scan.include` matches no files |
 | `npx @chappibunny/repolens migrate` | Upgrade from v0.3.0 workflows ([details](docs/MIGRATION.md)) |
 | `npx @chappibunny/repolens uninstall` | Remove all RepoLens files (config, docs, workflow) |
 | `npx @chappibunny/repolens uninstall --force` | Remove without confirmation prompt |
@@ -197,7 +197,7 @@ Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki,
 |---|---|
 | `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 |
+| `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 (missing `module_roots`, or `scan.include` matches no files), `publish --strict` is missing publisher credentials, or `feedback` has no terminal |
 
 `--target` must already exist. A missing path exits 2 with `Target directory not found: <path>` before any scan. `repolens <command> --help` prints that command's flags. The ASCII banner is omitted when stdout is not a terminal or `CI` is set.
 
@@ -237,7 +237,7 @@ If `npx` reports `Unknown command: mcp`, an `.npmrc` with `min-release-age` (or
 
 ## GitHub Action
 
-`action.yml` is a composite action named **RepoLens Architecture Docs**. It runs the published npm package (`npx --yes @chappibunny/repolens@1.15.0`). Inputs are `command` (`publish`, `demo`, or `doctor`), `config`, `node-version`, `pr-comment`, and `version`.
+`action.yml` is a composite action named **RepoLens Architecture Docs**. It runs the published npm package (`npx --yes @chappibunny/repolens@1.15.1`). Inputs are `command` (`publish`, `demo`, or `doctor`), `config`, `node-version`, `pr-comment`, and `version`.
 
 ```yaml
 name: Architecture docs
@@ -253,7 +253,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
-      - uses: CHAPIBUNNY/repolens@v1.15.0
+      - uses: CHAPIBUNNY/repolens@v1.15.1
         with:
           command: publish
           config: .repolens.yml
@@ -261,7 +261,7 @@ jobs:
           pr-comment: ${{ github.event_name == 'pull_request' && 'true' || 'false' }}
 ```
 
-The action is listed on the GitHub Marketplace only after a release is published with **Publish this Action to the GitHub Marketplace** checked. Those steps are in [docs/RELEASE.md](docs/RELEASE.md). The tag `v1.15.0` has to exist before `uses: CHAPIBUNNY/repolens@v1.15.0` resolves, and `@chappibunny/repolens@1.15.0` has to be on npm before the action can install it.
+The action is listed on the GitHub Marketplace only after a release is published with **Publish this Action to the GitHub Marketplace** checked. Those steps are in [docs/RELEASE.md](docs/RELEASE.md). The tag `v1.15.1` has to exist before `uses: CHAPIBUNNY/repolens@v1.15.1` resolves, and `@chappibunny/repolens@1.15.1` has to be on npm before the action can install it.
 
 ## Add the badge to your repo
 
@@ -281,7 +281,7 @@ Generated docs also link to the [gallery](https://chapibunny.github.io/repolens/
 
 Published system maps are Unicode diagrams drawn from import edges. RepoLens does not emit Mermaid.
 
-The publisher set is Notion, Confluence, GitHub Wiki, Obsidian, and Markdown (`src/publishers`, 7 files). 1.14.0 adds the MCP server, the Marketplace action, and the docs badge. 1.14.1 sets the registry name to `io.github.CHAPIBUNNY/repolens`. 1.14.2 adds the gallery link to the badge line, `glama.json`, and `CITATION.cff`. 1.14.3 adds Cline setup docs and `llms-install.md`. 1.15.0 detects repository languages in `init --quick`, refuses empty scans, and adds per-command help. Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
+The publisher set is Notion, Confluence, GitHub Wiki, Obsidian, and Markdown (`src/publishers`, 7 files). 1.14.0 adds the MCP server, the Marketplace action, and the docs badge. 1.14.1 sets the registry name to `io.github.CHAPIBUNNY/repolens`. 1.14.2 adds the gallery link to the badge line, `glama.json`, and `CITATION.cff`. 1.14.3 adds Cline setup docs and `llms-install.md`. 1.15.0 detects repository languages in `init --quick`, refuses empty scans, and adds per-command help. 1.15.1 makes `watch` exit 2 when those globs match nothing, and scores code health for Python and Go as well as JavaScript and TypeScript. Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### System Overview (Technical Profile)
 

package/llms-install.md

@@ -12,3 +12,4 @@
 5. Verify: the server should list six tools — `get_system_overview`, `list_modules`, `get_api_surface`, `get_dependency_graph`, `get_architecture_diff`, `generate_docs`. Call `get_system_overview` with no arguments.
 6. If you see `Unknown command: mcp`, an older release was resolved (often an `.npmrc` with `min-release-age`). Use `@chappibunny/repolens@latest`.
 7. CLI (1.15.0): `repolens` with no arguments prints help. `repolens <command> --help` prints that command's flags. `init --quick` writes language-specific globs and Markdown only. `demo` and `publish` exit 2 when zero source files match, instead of writing empty docs. `publish --strict` exits 2 when publisher credentials are missing.
+8. CLI (1.15.1): `watch` exits 2 when `scan.include` matches no files (it does not print `Waiting for changes...` and hang). Code health scores Python and Go as well as JavaScript and TypeScript.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.15.0",
+  "version": "1.15.1",
   "mcpName": "io.github.CHAPIBUNNY/repolens",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",

package/src/analyzers/complexity-analyzer.js

@@ -6,7 +6,17 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { info } from "../utils/logger.js";
 
-const JS_EXTENSIONS = [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"];
+const LANGUAGE_BY_EXTENSION = {
+  ".js": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".ts": "javascript",
+  ".tsx": "javascript",
+  ".jsx": "javascript",
+  ".py": "python",
+  ".pyw": "python",
+  ".go": "go",
+};
 
 // Skip test files, build outputs, etc.
 const SKIP_PATTERNS = [
@@ -19,6 +29,10 @@ const SKIP_PATTERNS = [
   /\.min\.[jt]s$/,
   /\.d\.ts$/,
   /\.repolens\//,
+  /__pycache__\//,
+  /(?:^|\/)test_[^/]*\.py$/,
+  /_test\.py$/,
+  /_test\.go$/,
 ];
 
 function shouldSkip(filePath) {
@@ -66,6 +80,100 @@ export function computeComplexity(source) {
   return complexity;
 }
 
+function blankExceptNewlines(match) {
+  return match.replace(/[^\n]/g, " ");
+}
+
+function stripPythonNoise(source) {
+  let stripped = source.replace(/"""[\s\S]*?"""/g, blankExceptNewlines);
+  stripped = stripped.replace(/'''[\s\S]*?'''/g, blankExceptNewlines);
+  stripped = stripped.replace(/"(?:[^"\\\n]|\\.)*"/g, '""');
+  stripped = stripped.replace(/'(?:[^'\\\n]|\\.)*'/g, "''");
+  stripped = stripped.replace(/#.*$/gm, "");
+  return stripped;
+}
+
+function stripGoNoise(source) {
+  let stripped = source.replace(/`[^`]*`/g, blankExceptNewlines);
+  stripped = stripped.replace(/"(?:[^"\\\n]|\\.)*"/g, '""');
+  stripped = stripped.replace(/'(?:[^'\\\n]|\\.)*'/g, "''");
+  stripped = stripped.replace(/\/\*[\s\S]*?\*\//g, blankExceptNewlines);
+  stripped = stripped.replace(/\/\/.*$/gm, "");
+  return stripped;
+}
+
+/**
+ * Cyclomatic complexity for Python. Regex approximation: if, elif, for,
+ * while, except, and, or. Comments and strings are ignored.
+ */
+export function computePythonComplexity(source) {
+  const stripped = stripPythonNoise(source);
+  let complexity = 1;
+  const patterns = [
+    /\bif\b/g,
+    /\belif\b/g,
+    /\bfor\b/g,
+    /\bwhile\b/g,
+    /\bexcept\b/g,
+    /\band\b/g,
+    /\bor\b/g,
+  ];
+  for (const pattern of patterns) {
+    const matches = stripped.match(pattern);
+    if (matches) complexity += matches.length;
+  }
+  return complexity;
+}
+
+/**
+ * Cyclomatic complexity for Go. Regex approximation: if, for, case
+ * (switch and select branches), &&, and ||. Comments and strings are ignored.
+ */
+export function computeGoComplexity(source) {
+  const stripped = stripGoNoise(source);
+  let complexity = 1;
+  const patterns = [
+    /\bif\b/g,
+    /\bfor\b/g,
+    /\bcase\b/g,
+    /&&/g,
+    /\|\|/g,
+  ];
+  for (const pattern of patterns) {
+    const matches = stripped.match(pattern);
+    if (matches) complexity += matches.length;
+  }
+  return complexity;
+}
+
+function languageForFile(file) {
+  return LANGUAGE_BY_EXTENSION[path.extname(file).toLowerCase()] || null;
+}
+
+function complexityForLanguage(language, source) {
+  if (language === "python") return computePythonComplexity(source);
+  if (language === "go") return computeGoComplexity(source);
+  return computeComplexity(source);
+}
+
+function collectFunctions(source, pattern, nameGroup, complexityFn) {
+  const functions = [];
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    const startLine = source.slice(0, match.index).split("\n").length;
+    functions.push({ name: match[nameGroup], line: startLine, index: match.index });
+  }
+  functions.sort((a, b) => a.index - b.index);
+  return functions.map((fn, i) => {
+    const end = i + 1 < functions.length ? functions[i + 1].index : source.length;
+    return {
+      name: fn.name,
+      line: fn.line,
+      complexity: complexityFn(source.slice(fn.index, end)),
+    };
+  });
+}
+
 /**
  * Extract function-level complexity from source code.
  * Returns per-function complexity for the top-level functions.
@@ -110,24 +218,50 @@ export function extractFunctions(source) {
   return results;
 }
 
+/** Python `def` / `async def` names and their approximate complexity. */
+export function extractPythonFunctions(source) {
+  return collectFunctions(
+    source,
+    /^[ \t]*(?:async[ \t]+)?def[ \t]+(\w+)[ \t]*\(/gm,
+    1,
+    computePythonComplexity,
+  );
+}
+
+/** Go `func Name` and `func (recv) Name` declarations. */
+export function extractGoFunctions(source) {
+  return collectFunctions(
+    source,
+    /^func[ \t]+(?:\([^)\n]*\)[ \t]+)?(\w+)[ \t]*\(/gm,
+    1,
+    computeGoComplexity,
+  );
+}
+
+function functionsForLanguage(language, source) {
+  if (language === "python") return extractPythonFunctions(source);
+  if (language === "go") return extractGoFunctions(source);
+  return extractFunctions(source);
+}
+
 /**
- * Analyze complexity for all JS/TS files in the project.
+ * Analyze complexity for JavaScript/TypeScript, Python, and Go files.
  * @param {string[]} files - File paths relative to repoRoot
  * @param {string} repoRoot - Absolute path to repo root
  * @returns {Promise<Object>} Complexity analysis results
  */
 export async function analyzeComplexity(files, repoRoot) {
-  const jsFiles = files
-    .filter(f => JS_EXTENSIONS.some(ext => f.endsWith(ext)))
+  const sourceFiles = files
+    .filter(f => languageForFile(f))
     .filter(f => !shouldSkip(f));
 
   const result = {
     files: [],
     functions: [],
-    filesAnalyzed: jsFiles.length,
+    filesAnalyzed: sourceFiles.length,
   };
 
-  for (const file of jsFiles) {
+  for (const file of sourceFiles) {
     let content;
     try {
       content = await fs.readFile(path.join(repoRoot, file), "utf8");
@@ -135,9 +269,10 @@ export async function analyzeComplexity(files, repoRoot) {
       continue;
     }
 
-    const fileComplexity = computeComplexity(content);
+    const language = languageForFile(file);
+    const fileComplexity = complexityForLanguage(language, content);
     const lineCount = content.split("\n").length;
-    const funcs = extractFunctions(content);
+    const funcs = functionsForLanguage(language, content);
 
     result.files.push({
       file,

package/src/help.js

@@ -3,7 +3,8 @@ const EXIT_CODES = `Exit codes:
   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,
+     demo or publish scanned 0 files, watch has nothing to watch
+     (missing module_roots, or scan.include matches no files),
      publish --strict is missing publisher credentials,
      or feedback has no terminal`;
 
@@ -149,8 +150,10 @@ Options:
   --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
+Watches directories listed in module_roots and regenerates Markdown when
+files change. Exits 2 when none of those directories exist, and when
+scan.include matches no files (including after init --quick in an empty
+directory). It does not wait for changes in that case. Press Ctrl+C to stop
 when a watch is running.
 
 ${EXIT_CODES}

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/watch.js

@@ -37,9 +37,6 @@ 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");
-
   const cfg = await loadConfig(configPath);
   const repoRoot = cfg.__repoRoot || process.cwd();
   const moduleRoots = cfg.module_roots || ["src", "app", "lib"];
@@ -62,6 +59,20 @@ export async function runWatch(configPath) {
     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);