@chappibunny/repolens 1.14.3 → 1.15.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.15.0
+
+### CLI usability
+
+- `init --quick` detects the repository language (Python, Go, Rust, Java/Kotlin, JavaScript/TypeScript, Ruby, PHP, C#, Swift, C/C++, and mixes of those) and writes matching `scan.include` globs and `module_roots`. It no longer defaults to JavaScript-only patterns such as `src/**/*.{ts,tsx,js,jsx,md}`
+- `init --quick` enables the Markdown publisher only. The interactive wizard can still add Notion, Confluence, GitHub Wiki, and Obsidian
+- `doctor` fails when `scan.include` matches 0 files
+- `demo` and `publish` print a warning and exit 2 when 0 files are scanned. They do not write empty documentation
+- `repolens <command> --help` prints that command's usage and flags for init, doctor, migrate, publish, demo, watch, uninstall, feedback, and mcp
+- `--target` is checked before any scan or publish. A missing path exits 2 with `Target directory not found: <path>`
+- A directory that is not a git repository is reported as `not a git repository`. Code health does not claim an average of 100/100 across 0 files
+- `watch` exits 2 when none of the `module_roots` directories exist
+- `publish --strict` exits 2 when a configured publisher is missing credentials
+- `repolens` with no arguments prints help and does not publish
+- The ASCII banner is omitted when stdout is not a terminal or `CI` is set
+- Init's next-steps text uses `repolens publish` when the CLI is installed globally, and `npx @chappibunny/repolens publish` otherwise
+
+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).
+
+## Unreleased
+
+### Release workflow
+
+- Before publishing, the release workflow queries `npm view <pkg>@<ver> version --prefer-online` up to three times, waiting 10 seconds between tries, and skips `npm publish` when that version is already on npm
+- If `npm publish` fails, the same check runs again. The step passes when the version is live
+- The GitHub Release uploads `chappibunny-repolens-*.tgz`, which is the tarball name `npm pack` writes for `@chappibunny/repolens`
+
+## Unreleased
+
+### Docs
+
+- README VS Code badge switched to a static shields.io badge (the visual-studio-marketplace badges were retired)
+- New `assets/social-preview.png` (1280x640, rendered from HTML with headless Chrome)
+
 ## 1.14.3
 
 ### Docs

package/README.md

@@ -9,7 +9,7 @@
 ```
 
 [![npm version](https://img.shields.io/npm/v/@chappibunny/repolens)](https://www.npmjs.com/package/@chappibunny/repolens)
-[![VS Code Extension](https://img.shields.io/visual-studio-marketplace/v/repolensdox.repolensdox?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=repolensdox.repolensdox)
+[![VS Code Extension](https://img.shields.io/badge/VS_Code-Marketplace-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=repolensdox.repolensdox)
 [![Tests](https://img.shields.io/github/actions/workflow/status/CHAPIBUNNY/repolens/test.yml?label=tests)](https://github.com/CHAPIBUNNY/repolens/actions/workflows/test.yml)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.CHAPIBUNNY%2Frepolens-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.CHAPIBUNNY/repolens)
@@ -29,7 +29,7 @@ RepoLens scans your repository, generates living architecture documentation, and
 
 ## 🎬 Demo
 
-> **Try it now** — no installation required. Run `npx @chappibunny/repolens demo` on any repo for an instant local preview.
+> **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.
 
 **[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.
 
@@ -173,21 +173,34 @@ Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki,
 
 | Command | Description |
 |---|---|
+| `npx @chappibunny/repolens` | Show help. A bare invocation does not publish |
 | `npx @chappibunny/repolens init` | **Interactive wizard** — configure publishers, AI, credentials |
-| `npx @chappibunny/repolens init --quick` | Minimal setup, skip wizard |
+| `npx @chappibunny/repolens init --quick` | Markdown-only setup. Globs follow the detected language |
+| `npx @chappibunny/repolens init --help` | Flags for that command. Same pattern for every command below |
 | `npx @chappibunny/repolens publish` | Scan, generate, and publish documentation |
-| `npx @chappibunny/repolens demo` | Quick local preview — no API keys needed |
-| `npx @chappibunny/repolens doctor` | Validate your setup |
-| `npx @chappibunny/repolens watch` | Auto-regenerate docs on file changes |
+| `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 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 |
 | `npx @chappibunny/repolens feedback` | Send feedback to the team |
 | `npx @chappibunny/repolens mcp` | Start the stdio MCP server (`repolens-mcp` is the same server) |
 
-> **Note:** If you installed globally with `npm install -g @chappibunny/repolens`, you can use the shorter `repolens <command>` form.
+> **Note:** If you installed globally with `npm install -g @chappibunny/repolens`, you can use the shorter `repolens <command>` form. Init's next-steps text uses that shorter form when the command on your PATH is the global install.
 > **Warning:** Do not run bare `npx repolens` — there is an unrelated `repolens@0.0.1` placeholder package on npm. Always use the scoped name `@chappibunny/repolens`.
 
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `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 |
+
+`--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.
+
 ---
 
 ## MCP server
@@ -224,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.14.3`). 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.0`). Inputs are `command` (`publish`, `demo`, or `doctor`), `config`, `node-version`, `pr-comment`, and `version`.
 
 ```yaml
 name: Architecture docs
@@ -240,7 +253,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
-      - uses: CHAPIBUNNY/repolens@v1.14.3
+      - uses: CHAPIBUNNY/repolens@v1.15.0
         with:
           command: publish
           config: .repolens.yml
@@ -248,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.14.1` has to exist before `uses: CHAPIBUNNY/repolens@v1.14.3` resolves, and `@chappibunny/repolens@1.14.3` 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.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.
 
 ## Add the badge to your repo
 
@@ -268,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`. 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. Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### System Overview (Technical Profile)
 

package/bin/repolens-mcp.js

@@ -13,7 +13,7 @@ if (wantsVersion && !wantsHelp) {
 
 if (wantsHelp) {
   const { printHelp } = await import("../src/help.js");
-  printHelp();
+  printHelp("mcp");
   process.exit(0);
 }
 

package/bin/repolens.js

@@ -2,19 +2,22 @@
 import { readFileSync } from "node:fs";
 
 const argv = process.argv.slice(2);
-const wantsHelp = argv.includes("--help") || argv.includes("-h") || argv[0] === "help";
-const wantsVersion = argv.includes("--version") || argv.includes("-v") || argv[0] === "version";
+const command = argv.find((arg) => !arg.startsWith("-"));
+const wantsHelp = argv.includes("--help") || argv.includes("-h") || command === "help";
+const wantsVersion = argv.includes("--version") || argv.includes("-v") || command === "version";
 
-// --version and --help must not load the scanner, publishers, or telemetry.
+// --version, --help, and a bare invocation must not load the scanner,
+// publishers, or telemetry. `repolens <command> --help` prints that command.
 if (wantsVersion && !wantsHelp) {
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   console.log(pkg.version || "0.0.0");
   process.exit(0);
 }
 
-if (wantsHelp) {
+if (argv.length === 0 || wantsHelp) {
   const { printHelp } = await import("../src/help.js");
-  printHelp();
+  const topic = wantsHelp && command && command !== "help" ? command : undefined;
+  printHelp(topic);
   process.exit(0);
 }
 

package/llms-install.md

@@ -11,3 +11,4 @@
 4. No API keys are needed. Tools run deterministically and offline unless `generate_docs` is called with `deterministic: false`.
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.14.3",
+  "version": "1.15.0",
   "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

@@ -264,7 +264,7 @@ export function computeCodeHealth(complexityResult, depGraph, jsdocResult, secur
 
   // Aggregate stats
   const totalFiles = modules.length;
-  const avgScore = totalFiles > 0 ? Math.round(modules.reduce((s, m) => s + m.score, 0) / totalFiles) : 100;
+  const avgScore = totalFiles > 0 ? Math.round(modules.reduce((s, m) => s + m.score, 0) / totalFiles) : null;
   const avgComplexity = totalFiles > 0 ? Math.round(modules.reduce((s, m) => s + m.complexity, 0) / totalFiles) : 0;
 
   const gradeDistribution = { A: 0, B: 0, C: 0, D: 0, F: 0 };
@@ -280,7 +280,11 @@ export function computeCodeHealth(complexityResult, depGraph, jsdocResult, secur
     ? `${totalFiles} files analyzed · Average health: ${avgScore}/100 · ${gradeDistribution.A} A, ${gradeDistribution.B} B, ${gradeDistribution.C} C, ${gradeDistribution.D} D, ${gradeDistribution.F} F`
     : "No source files analyzed.";
 
-  info(`Code health: avg ${avgScore}/100 across ${totalFiles} files (${hotspots.length} hotspots)`);
+  if (totalFiles === 0) {
+    info("Code health: no source files analyzed.");
+  } else {
+    info(`Code health: avg ${avgScore}/100 across ${totalFiles} files (${hotspots.length} hotspots)`);
+  }
 
   return {
     modules,

package/src/cli-args.js

@@ -4,6 +4,7 @@ const BOOLEAN_FLAGS = new Set([
   "--non-interactive",
   "--dry-run",
   "--force",
+  "--strict",
   "--verbose",
   "--help",
   "-h",

package/src/cli.js

@@ -17,7 +17,6 @@ import {
 import { renderSystemMap } from "./renderers/renderMap.js";
 import { renderArchitectureDiff, buildArchitectureDiffData } from "./renderers/renderDiff.js";
 
-import { publishDocs } from "./publishers/index.js";
 import { upsertPrComment } from "./delivery/comment.js";
 import { runInit } from "./init.js";
 import { runMigrate } from "./migrate.js";
@@ -32,6 +31,9 @@ import { PluginManager } from "./plugins/manager.js";
 import { printHelp } from "./help.js";
 import { parseCliArgs } from "./cli-args.js";
 import { isNonInteractiveEnvironment } from "./utils/interactive.js";
+import { shouldPrintBanner } from "./utils/banner.js";
+import { detectRepoLanguages } from "./core/languages.js";
+import { publishDocs, missingPublisherCredentials } from "./publishers/index.js";
 import { 
   initTelemetry, 
   captureError, 
@@ -49,6 +51,18 @@ const EXIT_SUCCESS = 0;
 const EXIT_ERROR = 1;
 const EXIT_VALIDATION = 2;
 
+function exitIfNoFilesScanned(scan, cfg) {
+  if ((scan?.filesCount || 0) > 0) return;
+  const patterns = Array.isArray(cfg?.scan?.include) && cfg.scan.include.length
+    ? cfg.scan.include.join(", ")
+    : "(none)";
+  error("WARNING: 0 files scanned.");
+  error(`scan.include matched no files (${patterns}).`);
+  error("Empty documentation was not written.");
+  error("Update scan.include, or run `repolens init --quick` to detect this repository's language.");
+  process.exit(EXIT_VALIDATION);
+}
+
 function formatDuration(ms) {
   if (ms < 1000) return `${ms}ms`;
   return `${(ms / 1000).toFixed(1)}s`;
@@ -172,6 +186,7 @@ async function getPackageVersion() {
 }
 
 async function printBanner() {
+  if (!shouldPrintBanner()) return;
   const version = await getPackageVersion();
   console.log(`
 ██████╗ ███████╗██████╗  ██████╗ ██╗     ███████╗███╗   ██╗███████╗
@@ -228,7 +243,8 @@ async function main() {
   // Help and version return before telemetry and the update check.
   // bin/repolens.js answers --version/--help without loading this module.
   if (parsed.help) {
-    printHelp();
+    const topic = parsed.command && parsed.command !== "help" ? parsed.command : undefined;
+    printHelp(topic);
     return;
   }
 
@@ -244,8 +260,28 @@ async function main() {
     process.exit(EXIT_VALIDATION);
   }
 
+  if (parsed.flags["--target"]) {
+    const targetPath = parsed.flags["--target"];
+    let targetIsDirectory = false;
+    try {
+      const stat = await fs.stat(targetPath);
+      targetIsDirectory = stat.isDirectory();
+    } catch {
+      targetIsDirectory = false;
+    }
+    if (!targetIsDirectory) {
+      error(`Target directory not found: ${targetPath}`);
+      process.exit(EXIT_VALIDATION);
+    }
+  }
+
   const command = parsed.command;
 
+  if (!command) {
+    printHelp();
+    return;
+  }
+
   // MCP stdio must start before telemetry and the npm update check.
   // Those both can open the network, and logs must stay off stdout.
   if (command === "mcp") {
@@ -366,11 +402,15 @@ async function main() {
       error(err.message);
       process.exit(EXIT_VALIDATION);
     }
-    await runWatch(configPath);
+    const watchResult = await runWatch(configPath);
+    if (watchResult && watchResult.ok === false) {
+      await closeTelemetry();
+      process.exit(EXIT_VALIDATION);
+    }
     return;
   }
 
-  if (command === "publish" || !command) {
+  if (command === "publish") {
     await printBanner();
     
     const commandTimer = startTimer("publish");
@@ -399,6 +439,18 @@ async function main() {
       process.exit(EXIT_VALIDATION);
     }
 
+    if (parsed.flags["--strict"]) {
+      const missing = missingPublisherCredentials(cfg);
+      if (missing.length > 0) {
+        stopTimer(commandTimer);
+        error("Missing publisher credentials (--strict):");
+        for (const item of missing) error(`  ${item}`);
+        trackUsage("publish", "failure", { step: "strict-credentials" });
+        await closeTelemetry();
+        process.exit(EXIT_VALIDATION);
+      }
+    }
+
     // Prompt for AI enhancement if GITHUB_TOKEN is available
     const aiResult = await promptForAI(cfg);
 
@@ -421,6 +473,7 @@ async function main() {
       scan = await scanRepo(cfg);
       stopTimer(scanTimer);
       info(`Detected ${scan.modules?.length || 0} modules`);
+      exitIfNoFilesScanned(scan, cfg);
     } catch (err) {
       stopTimer(commandTimer);
       captureError(err, { command: "publish", step: "scan", patterns: cfg.scan?.patterns });
@@ -514,16 +567,20 @@ async function main() {
       info(`Using config: ${configPath}`);
       cfg = await loadConfig(configPath);
     } catch {
-      info("No .repolens.yml found — using default scan patterns");
+      const detected = await detectRepoLanguages(targetDir);
+      const languageNames = detected.languages.map((lang) => lang.label).join(", ");
+      info(languageNames
+        ? `No .repolens.yml found — scanning ${languageNames}`
+        : "No .repolens.yml found — using multi-language scan patterns");
       cfg = {
         configVersion: 1,
         project: { name: path.basename(targetDir) },
         publishers: ["markdown"],
         scan: {
-          include: ["**/*.{js,ts,jsx,tsx,mjs,cjs,py,go,rs,java,rb,php,cs,swift,kt}"],
-          ignore: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/vendor/**", "**/target/**", "**/__pycache__/**"],
+          include: detected.include,
+          ignore: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/vendor/**", "**/target/**", "**/__pycache__/**", "**/.venv/**"],
         },
-        module_roots: ["src", "lib", "app", "packages"],
+        module_roots: detected.moduleRoots,
         outputs: {
           pages: [
             { key: "system_overview", title: "System Overview" },
@@ -552,7 +609,8 @@ async function main() {
       const scan = await scanRepo(cfg);
       stopTimer(scanTimer);
       info(`Detected ${scan.modules?.length || 0} modules, ${scan.filesCount || 0} files`);
-      
+      exitIfNoFilesScanned(scan, cfg);
+
       const rawDiff = getGitDiff("origin/main", cfg.__repoRoot || targetDir);
       
       info("Generating documentation set...");

package/src/core/diff.js

@@ -34,6 +34,19 @@ export function classifyDiffLine(line) {
   return { bucket: "modified", file };
 }
 
+/**
+ * Plain message for a failed git diff.
+ * A directory that is not a repository says so. The old internal
+ * "git diff failed, returning empty diff" line is not used.
+ */
+export function gitDiffFailureMessage(stderr = "", message = "") {
+  const text = `${stderr}\n${message}`;
+  if (/not a git repository/i.test(text)) {
+    return "not a git repository";
+  }
+  return "git diff could not be read; continuing with an empty diff.";
+}
+
 export function getGitDiff(baseRef = "origin/main", cwd = process.cwd(), headRef) {
   if (!isSafeGitRef(baseRef)) {
     warn("git diff skipped: base ref contains unsupported characters.");
@@ -60,7 +73,8 @@ export function getGitDiff(baseRef = "origin/main", cwd = process.cwd(), headRef
       stdio: ["ignore", "pipe", "pipe"],
     });
   } catch (error) {
-    warn("git diff failed, returning empty diff.");
+    const stderr = typeof error.stderr === "string" ? error.stderr : "";
+    warn(gitDiffFailureMessage(stderr, error.message));
     return emptyDiff();
   }