@chappibunny/repolens 1.15.5 → 1.16.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.16.0
+
+### GitHub App
+
+- `repolens app` self-hosts a GitHub App webhook. It checks `X-Hub-Signature-256`, acknowledges `installation` and `installation_repositories`, and on `pull_request` `opened`, `synchronize`, `reopened`, and `ready_for_review` runs the existing architecture diff. It posts a Check Run named RepoLens (the same summary as the sticky comment) and updates that comment. A finished diff is a successful check. The check fails only when the analysis throws
+- Manifest: `app.yml` and `github-app-manifest.json`, also `repolens app --manifest`. Permissions are checks write, pull requests write, contents read, and metadata read. The hook URL in the repo is a placeholder (`https://example.com/api/github/webhooks`). This release does not register an app and CI does not need new secrets
+- The server answers 202 before the clone and scoring finish, because GitHub allows about 10 seconds for the HTTP response. Setup is in [docs/GITHUB_APP.md](docs/GITHUB_APP.md)
+
+### Security
+
+- Route parameters in `src/renderers/renderDiff.js` no longer use `/\[(.*?)\]/g`. That lazy pattern is polynomial on a long string of `[` with no `]` (CodeQL `js/polynomial-redos`, alert #6). The replacement is a linear scan, including the same pattern in `src/core/scan.js` and the route-group labels in `src/renderers/renderMap.js`. A regression test feeds 100,000 brackets and expects a fast result
+
+### Output accuracy
+
+Hands-on `repolens demo` on expressjs/express, pallets/flask, and spf13/cobra:
+
+- Express 5 has no `main` field. A description that says library, SDK, parser, toolkit, or framework is a library. Express reads as a library, not an API service
+- `app.get('query parser fn')` is a setting lookup, not a route. Comment lines are skipped. Routes in tests, examples, and docs are not the product API. The Express route map is skipped
+- A flat package at the repository root is named after the directory (`cobra`, not `root`). The system map connects that package to `doc/` (one relationship). Files with no directory belong to that flat module
+- External imports that appear only in tests or examples are development tooling even when there is no `package.json`. Flask no longer lists `site_app` and the other test fixtures as runtime packages. Cobra lists `pflag` and `mousetrap` as runtime, and `go-md2man` and `yaml` as doc tooling
+- Flask hubs are `globals.py`, `helpers.py`, `typing.py`, and `signals.py`. The three cycles (`__init__` → `app` → `cli`, and the templating / sansio chains) are real import cycles
+
+### Dependencies
+
+- `js-yaml` 4.3.2 → 5.5.0. Call the named `load` export. The YAML 1.2 Core schema still treats `true`/`false` as booleans and `yes`/`no` as strings. The merge key (`<<`) is enabled. `maxAliases` caps alias expansion. An empty file still returns `undefined`
+- `@sentry/node` 10.76.2 → 11.9.0 (`^11.8.0`). It is still optional. Its own engines exclude Node 18 (`>=20.19` or `>=22.12`). `npm ci` on Node 18 warns and continues, and a failed import still disables telemetry instead of crashing the CLI
+- Vitest 4.1.12 → 5.0.5. Its declared engines are `^22.12 || ^24 || >=26`. The runner starts on Node 20 and does not start on Node 18 (`util.styleText`). CI still runs `npm test` on Node 20 and 22, and `scripts/node18-runtime.js` on Node 18. `engines` stays `>=18`
+- `dotenv` 18.0.8 → 18.0.9 and `@modelcontextprotocol/sdk` 1.32.1 → 1.32.2
+- GitHub Actions: `actions/checkout` pin is the v6.0.3 release commit `df4cb1c`, `actions/setup-node` v7.1.0 (`949feb2`), `softprops/action-gh-release` v3.0.3 (`efb3536`). `npm audit` reports no vulnerabilities
+
+### Docs
+
+- Roadmap item 1 (GitHub App) is shipped in 1.16.0. Java and C# language support is now What's Next item 1
+- The note that a chat answer only covers what someone thought to ask, and that grounded AI Q&A sits on top of the full map, stays in the roadmap, README, known issues, and copilot instructions
+
 ## 1.15.5
 
 Fixes twelve output problems found by running 1.15.4 on mattiasw/ExifReader (a plain-JavaScript library with a flat `src/` and a build-helper `bin/`), and the two leftovers from 1.15.4.

package/README.md

@@ -119,6 +119,7 @@ Run `npx @chappibunny/repolens migrate` to automatically update your workflow fi
 | 🤖 **Autonomous** | Runs on every push via GitHub Actions — docs stay evergreen |
 | 👥 **Multi-Audience** | Technical docs + stakeholder-readable overviews from one scan |
 | 📤 **Multi-Publisher** | Notion, Confluence, GitHub Wiki, Obsidian, Markdown — together or one at a time |
+| 🗺️ **Shows what you didn't ask** | An LLM only answers the question it is given, and a newcomer doesn't know what to ask. RepoLens publishes the whole map (every module, cycle and hub) on every PR, the same way each time, with no tokens spent per question |
 | 🧠 **AI-Assisted** | Optional AI with zero-hallucination policy (structured context only) |
 | 🔍 **Smart Detection** | Frameworks, domains, data flows, dependencies, drift — all automatic |
 | 🔌 **Extensible** | Plugin system for custom renderers, publishers, and hooks |
@@ -189,6 +190,7 @@ Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki,
 | `npx @chappibunny/repolens mcp` | Start the stdio MCP server (`repolens-mcp` is the same server) |
 | `npx @chappibunny/repolens badge` | shields.io code-health JSON, SVG, or markdown. Exits 2 when nothing is scored |
 | `npx @chappibunny/repolens comment --base <ref> --head <ref>` | Architecture diff (files, modules, dependencies, health delta, new hotspots) |
+| `npx @chappibunny/repolens app` | Self-host the GitHub App webhook. `--manifest` prints the manifest |
 
 > **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`.
@@ -199,7 +201,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 (missing `module_roots`, or `scan.include` matches no files), `badge` scored 0 source files, `comment` is missing a base or head ref, `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), `badge` scored 0 source files, `comment` is missing a base or head ref, `publish --strict` is missing publisher credentials, `app` is missing its id, webhook secret, or private key, 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.
 
@@ -241,9 +243,9 @@ 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**. `publish`, `demo`, and `doctor` run the published npm package (`npx --yes @chappibunny/repolens@1.15.5`). `comment` and `badge` run from the action checkout. Inputs are `command` (`publish`, `demo`, `doctor`, `comment`, or `badge`), `config`, `node-version`, `pr-comment`, `version`, `badge-out`, `badge-url`, and `badge-link`.
+`action.yml` is a composite action named **RepoLens Architecture Docs**. `publish`, `demo`, and `doctor` run the published npm package (`npx --yes @chappibunny/repolens@1.16.0`). `comment` and `badge` run from the action checkout. Inputs are `command` (`publish`, `demo`, `doctor`, `comment`, or `badge`), `config`, `node-version`, `pr-comment`, `version`, `badge-out`, `badge-url`, and `badge-link`.
 
-Publishing docs (the npm package at tag `v1.15.5`):
+Publishing docs (the npm package at tag `v1.16.0`):
 
 ```yaml
 name: Architecture docs
@@ -258,8 +260,8 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
-      - uses: CHAPIBUNNY/repolens@v1.15.5
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: CHAPIBUNNY/repolens@v1.16.0
         with:
           command: publish
           config: .repolens.yml
@@ -267,7 +269,7 @@ jobs:
           pr-comment: ${{ github.event_name == 'pull_request' && 'true' || 'false' }}
 ```
 
-On `v1.15.2`, `pr-comment: true` runs the architecture diff from the action checkout and turns the published package's older short summary off. The diff lists modules, files, dependencies, the code-health delta, and new hotspots. It edits one sticky comment (`<!-- repolens:architecture-diff -->`) instead of adding a new comment each push. The footer is "Generated by RepoLens" and links to this repository and the [gallery](https://chapibunny.github.io/repolens/). Tag `v1.15.1` does not contain `command: comment`. Pin `v1.15.5` or a commit SHA in production.
+On `v1.15.2`, `pr-comment: true` runs the architecture diff from the action checkout and turns the published package's older short summary off. The diff lists modules, files, dependencies, the code-health delta, and new hotspots. It edits one sticky comment (`<!-- repolens:architecture-diff -->`) instead of adding a new comment each push. The footer is "Generated by RepoLens" and links to this repository and the [gallery](https://chapibunny.github.io/repolens/). Tag `v1.15.1` does not contain `command: comment`. Pin `v1.16.0` or a commit SHA in production.
 
 ```yaml
 name: RepoLens architecture comment
@@ -280,10 +282,10 @@ jobs:
   architecture:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
-      - uses: CHAPIBUNNY/repolens@v1.15.5
+      - uses: CHAPIBUNNY/repolens@v1.16.0
         with:
           command: comment
 ```
@@ -292,7 +294,7 @@ jobs:
 
 `pr-comment: true` on `publish`, `demo`, or `doctor` (when the action ref contains this change) runs the same comment after the package and turns the package's older comment off, so the pull request still gets one comment.
 
-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.5` has to exist before `uses: CHAPIBUNNY/repolens@v1.15.5` resolves, and `@chappibunny/repolens@1.15.5` has to be on npm before `publish` can install it. `command: comment` and `command: badge` do not install that package.
+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.16.0` has to exist before `uses: CHAPIBUNNY/repolens@v1.16.0` resolves, and `@chappibunny/repolens@1.16.0` has to be on npm before `publish` can install it. `command: comment` and `command: badge` do not install that package.
 
 ## Add the badge to your repo
 
@@ -327,8 +329,8 @@ jobs:
   badge:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
-      - uses: CHAPIBUNNY/repolens@v1.15.5
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: CHAPIBUNNY/repolens@v1.16.0
         with:
           command: badge
           badge-url: https://USER.github.io/REPO/repolens-badge.json
@@ -357,7 +359,7 @@ Gallery repositories already publish this. Each one has a [score page](https://c
 
 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. 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. 1.15.2 reads Python and Go imports in the dependency graph, skips comment and type-only imports, adds `repolens badge` and `repolens comment`, and adds gallery explained pages plus `llms.txt`. 1.15.3 skips Python `TYPE_CHECKING` imports, omits Node.js built-ins from external packages, groups Go hubs by package, and ignores test files as architecture-pattern evidence. 1.15.4 names the project from `package.json`, scores maturity from version, history, tests, CI, and docs, reports circular dependencies as findings, drops self-imports and noise data flows, and stops classifying `index` and `core` files by name. 1.15.5 reads a flat `src/` as one module, tells a library from a CLI by its `package.json`, splits runtime from development packages, keeps tests, examples, and build scripts out of hubs and security severity, and skips empty Route Map and GraphQL pages. 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. 1.15.2 reads Python and Go imports in the dependency graph, skips comment and type-only imports, adds `repolens badge` and `repolens comment`, and adds gallery explained pages plus `llms.txt`. 1.15.3 skips Python `TYPE_CHECKING` imports, omits Node.js built-ins from external packages, groups Go hubs by package, and ignores test files as architecture-pattern evidence. 1.15.4 names the project from `package.json`, scores maturity from version, history, tests, CI, and docs, reports circular dependencies as findings, drops self-imports and noise data flows, and stops classifying `index` and `core` files by name. 1.15.5 reads a flat `src/` as one module, tells a library from a CLI by its `package.json`, splits runtime from development packages, keeps tests, examples, and build scripts out of hubs and security severity, and skips empty Route Map and GraphQL pages. 1.16.0 adds `repolens app` (a self-hosted GitHub App webhook), names a flat package after its directory, treats a framework description as a library when `main` is absent, and keeps test and example routes out of the product API. Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### System Overview (Technical Profile)
 
@@ -419,6 +421,7 @@ When you open a pull request, RepoLens posts:
 | [Migration](docs/MIGRATION.md) | Upgrading from v0.3.0 or earlier |
 | [Stability](docs/STABILITY.md) | API contract and semver guarantees |
 | [MCP server](docs/MCP.md) | stdio server for Cursor, Claude, and VS Code |
+| [GitHub App](docs/GITHUB_APP.md) | Self-host the webhook: manifest, env vars, check run |
 
 ---
 
@@ -445,11 +448,11 @@ v1.0+ features complete — CLI, config schema, and plugin interface are frozen.
 - [x] MCP server (`repolens mcp`) for Cursor, Claude, and VS Code
 - [x] GitHub Action `RepoLens Architecture Docs` (`action.yml`)
 - [x] Docs by RepoLens badge on generated Markdown
+- [x] GitHub App webhook (`repolens app`) for a check run and the architecture comment
 
 **Next:**
-- [ ] GitHub App for automated setup and status checks
 - [ ] Java and C# language support
-- [ ] Grounded AI explanations and Q&A (`repolens ask`, PR comment, MCP, VS Code hover)
+- [ ] Grounded AI explanations and Q&A (`repolens ask`, PR comment, MCP, VS Code hover), layered on the always-published map and not a replacement for it
 - [ ] Slack notifications
 - [ ] Custom webhook support
 - [ ] Cross-repository architecture analysis

package/app.yml

@@ -0,0 +1,23 @@
+# GitHub App manifest for RepoLens.
+# Register from github-app-manifest.json (same fields) after you replace
+# hook_attributes.url with the public URL of `repolens app`.
+# Permissions stay minimal: checks write, pull requests write, contents read,
+# metadata read. This file does not create the app.
+
+name: RepoLens
+description: Posts an architecture diff as a check run and one sticky pull request comment.
+url: https://github.com/CHAPIBUNNY/repolens
+hook_attributes:
+  url: https://example.com/api/github/webhooks
+  active: true
+redirect_url: https://github.com/CHAPIBUNNY/repolens
+public: false
+default_permissions:
+  checks: write
+  pull_requests: write
+  contents: read
+  metadata: read
+default_events:
+  - installation
+  - installation_repositories
+  - pull_request

package/github-app-manifest.json

@@ -0,0 +1,22 @@
+{
+  "name": "RepoLens",
+  "description": "Posts an architecture diff as a check run and one sticky pull request comment.",
+  "url": "https://github.com/CHAPIBUNNY/repolens",
+  "hook_attributes": {
+    "url": "https://example.com/api/github/webhooks",
+    "active": true
+  },
+  "redirect_url": "https://github.com/CHAPIBUNNY/repolens",
+  "public": false,
+  "default_permissions": {
+    "checks": "write",
+    "pull_requests": "write",
+    "contents": "read",
+    "metadata": "read"
+  },
+  "default_events": [
+    "installation",
+    "installation_repositories",
+    "pull_request"
+  ]
+}

package/llms-full.txt

@@ -24,6 +24,7 @@ Agent-oriented install steps, including the Cline MCP snippet, are in llms-insta
 - `repolens watch` regenerates docs on change and exits 2 when nothing matches.
 - `repolens badge` prints a shields.io endpoint JSON document for the code-health score (0–100). `--format svg` prints a square SVG. `--format markdown --url https://host/repolens-badge.json` prints a README snippet. `--format all --out repolens-badge.json` writes JSON and SVG. Exit 2 when no JavaScript, TypeScript, Python, or Go files were scored. The score is not reported as 100 when zero files match.
 - `repolens comment --base <ref> --head <ref>` compares those commits. It prints markdown locally. In GitHub Actions, with `GITHUB_TOKEN`, `GITHUB_REPOSITORY`, and a pull_request event, it creates or updates one comment.
+- `repolens app` self-hosts a GitHub App webhook. It verifies `X-Hub-Signature-256`, posts a Check Run named RepoLens, and updates the sticky architecture comment. `repolens app --manifest` prints the manifest and needs no secrets. Listening needs `REPOLENS_APP_ID`, `REPOLENS_WEBHOOK_SECRET`, and a private key. See docs/GITHUB_APP.md.
 - `repolens mcp` starts the stdio MCP server. `repolens-mcp` is the same entry.
 
 Exit codes: 0 success, 1 runtime error or unknown command, 2 validation failure (bad flags, missing config, empty scan, and the other cases in the README).

package/llms-install.md

@@ -21,3 +21,4 @@
 12. CLI (1.15.3): Python imports under `if TYPE_CHECKING:` (including `typing.TYPE_CHECKING` and `import typing as t`) are not cycle edges. Node.js built-ins are not external packages. Go hub rows are packages. Test files are not architecture-pattern evidence, and "API route pattern" requires a route directory.
 13. CLI (1.15.4): the project name comes from `package.json` or the real directory (never `.`). Maturity uses version, history, tests, CI, and docs. Circular dependencies are findings, not architectural patterns. A package's own name is not an external dependency. `index` and `main` files are not classified by name. Noise data flows are dropped.
 14. CLI (1.15.5): a flat `src/` is one module. A package with `main`, `module`, or `exports` is a library, not a CLI. Hubs and security severity ignore tests, examples, and build scripts. External packages are split into runtime and development tooling. Route Map and GraphQL Schema are skipped when empty.
+15. CLI (1.16.0): `repolens app` self-hosts a GitHub App webhook (manifest in `app.yml`, check run plus the sticky architecture comment). A framework description is a library even without `main`. A flat package is named after its directory. Test and example routes are not the product API. Test-only imports are dev tooling on Python and Go.

package/llms.txt

@@ -17,6 +17,7 @@ RepoLens is the npm package `@chappibunny/repolens` (Node.js 18+). It is a CLI,
 - [publish](https://github.com/CHAPIBUNNY/repolens/blob/main/docs/INSTALLATION.md): `npx @chappibunny/repolens publish` scans and publishes
 - [badge](https://github.com/CHAPIBUNNY/repolens/blob/main/README.md): `npx @chappibunny/repolens badge` prints shields.io code-health JSON, SVG, or markdown
 - [comment](https://github.com/CHAPIBUNNY/repolens/blob/main/README.md): `npx @chappibunny/repolens comment --base <ref> --head <ref>` prints an architecture diff
+- [app](https://github.com/CHAPIBUNNY/repolens/blob/main/docs/GITHUB_APP.md): `npx @chappibunny/repolens app` self-hosts the GitHub App webhook. `--manifest` prints the manifest. No credentials are required to print it
 - [doctor](https://github.com/CHAPIBUNNY/repolens/blob/main/docs/INSTALLATION.md): `npx @chappibunny/repolens doctor` validates setup
 - [mcp](https://github.com/CHAPIBUNNY/repolens/blob/main/docs/MCP.md): `npx -y @chappibunny/repolens mcp` starts the stdio server
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.15.5",
+  "version": "1.16.0",
   "mcpName": "io.github.CHAPIBUNNY/repolens",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
@@ -18,7 +18,9 @@
     "repolens-mcp": "bin/repolens-mcp.js"
   },
   "files": [
+    "app.yml",
     "bin",
+    "github-app-manifest.json",
     "src",
     "package.json",
     "README.md",
@@ -86,18 +88,18 @@
     "release:major": "npm version major"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.1",
-    "dotenv": "^18.0.8",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "dotenv": "^18.0.9",
     "fast-glob": "^3.3.3",
-    "js-yaml": "^4.3.2",
+    "js-yaml": "^5.5.0",
     "zod": "4.6.7"
   },
   "optionalDependencies": {
-    "@sentry/node": "^10.42.0"
+    "@sentry/node": "^11.8.0"
   },
   "devDependencies": {
     "tinyexec": "^1.3.1",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.5"
   },
   "overrides": {
     "yauzl": ">=3.2.1",

package/src/analyzers/context-builder.js

@@ -30,20 +30,28 @@ export function computeModuleDepMetrics(depGraph) {
 
 /**
  * Find the module a file belongs to: the module with the longest key that is a path
- * prefix of the file. Files at the repository root belong to `root`.
+ * prefix of the file. Files at the repository root belong to the flat module
+ * (the directory name, or the legacy key `root`).
  */
+function flatModuleKey(modules) {
+  const marked = modules.find((mod) => mod.flat);
+  if (marked) return marked.key;
+  return modules.some((mod) => mod.key === "root") ? "root" : null;
+}
+
 function buildModuleLookup(modules) {
   const keys = modules.map((m) => m.key).sort((x, y) => y.length - x.length);
+  const flatKey = flatModuleKey(modules);
   const cache = new Map();
   return (file) => {
     const norm = String(file || "").replace(/\\/g, "/");
     if (cache.has(norm)) return cache.get(norm);
     let found = null;
     for (const key of keys) {
-      if (key === "root") continue;
+      if (key === flatKey) continue;
       if (norm === key || norm.startsWith(`${key}/`)) { found = key; break; }
     }
-    if (!found && !norm.includes("/") && keys.includes("root")) found = "root";
+    if (!found && !norm.includes("/") && flatKey) found = flatKey;
     cache.set(norm, found);
     return found;
   };

package/src/analyzers/dependency-graph.js

@@ -314,21 +314,21 @@ export async function analyzeDependencyGraph(files, repoRoot) {
  * Split external packages into runtime dependencies and development tooling.
  * A package declared in `devDependencies` is development tooling. One declared in
  * `dependencies`, `optionalDependencies`, or `peerDependencies` is runtime. An undeclared
- * package is runtime when a product file (not a test, example, or build script) imports it.
- * Without a root package.json (Python, Go) every package counts as runtime.
+ * package is runtime when a product file (not a test, example, or build script) imports it,
+ * and development tooling when only tests or examples import it. Python and Go have no
+ * package.json, so that import split is the whole decision.
  */
 async function splitExternalDeps(result, repoRoot) {
   const raw = await readFileSafe(path.join(repoRoot, "package.json"));
   let pkg = null;
   try { pkg = raw ? JSON.parse(raw) : null; } catch { pkg = null; }
-  if (!pkg) return { runtime: [...result.externalDeps], dev: [] };
 
-  const declaredRuntime = new Set([
+  const declaredRuntime = new Set(pkg ? [
     ...Object.keys(pkg.dependencies || {}),
     ...Object.keys(pkg.optionalDependencies || {}),
     ...Object.keys(pkg.peerDependencies || {}),
-  ]);
-  const declaredDev = new Set(Object.keys(pkg.devDependencies || {}));
+  ] : []);
+  const declaredDev = new Set(pkg ? Object.keys(pkg.devDependencies || {}) : []);
 
   const productImports = new Set();
   for (const node of result.nodes) {

package/src/cli-args.js

@@ -8,6 +8,9 @@ const FLAGS_WITH_VALUE = new Set([
   "--url",
   "--link",
   "--label",
+  "--port",
+  "--host",
+  "--webhook-path",
 ]);
 const BOOLEAN_FLAGS = new Set([
   "--quick",
@@ -16,6 +19,7 @@ const BOOLEAN_FLAGS = new Set([
   "--force",
   "--strict",
   "--verbose",
+  "--manifest",
   "--help",
   "-h",
   "--version",

package/src/cli.js

@@ -311,6 +311,17 @@ async function main() {
     process.exit(code);
   }
 
+  if (command === "app") {
+    const { runGitHubApp } = await import("./github-app/run.js");
+    const code = await runGitHubApp({
+      manifest: Boolean(parsed.flags["--manifest"]),
+      port: parsed.flags["--port"],
+      host: parsed.flags["--host"],
+      webhookPath: parsed.flags["--webhook-path"],
+    });
+    process.exit(code);
+  }
+
   if (command === "mcp") {
     process.env.REPOLENS_LOG_STDERR = "1";
     const { startMcpServer } = await import("./mcp/server.js");

package/src/core/scan.js

@@ -5,7 +5,8 @@ import { info, warn } from "../utils/logger.js";
 import { trackScan } from "../utils/telemetry.js";
 import { detectMonorepo } from "../analyzers/monorepo-detector.js";
 import { isInsideRoot } from "../utils/safe-path.js";
-import { isTestPath } from "../utils/path-roles.js";
+import { isNonProductPath, isTestPath } from "../utils/path-roles.js";
+import { replaceBracketParams } from "../utils/route-params.js";
 
 const norm = (p) => p.replace(/\\/g, "/");
 
@@ -93,7 +94,13 @@ async function readFileSafe(file) {
   }
 }
 
-function moduleKeyForFile(file, moduleRoots) {
+function rootModuleLabel(repoRoot) {
+  const base = path.basename(path.resolve(repoRoot || ""));
+  if (!base || base === "." || base === "..") return "root";
+  return base;
+}
+
+function moduleKeyForFile(file, moduleRoots, rootLabel = "root") {
   const normalized = norm(file);
 
   const sortedRoots = [...moduleRoots].sort((a, b) => b.length - a.length);
@@ -111,7 +118,9 @@ function moduleKeyForFile(file, moduleRoots) {
   }
 
   const parts = normalized.split("/");
-  return parts.length > 1 ? parts[0] : "root";
+  // A file next to go.mod or package.json is one module, named for the directory.
+  // Calling it "root" hid that package on the system map.
+  return parts.length > 1 ? parts[0] : rootLabel;
 }
 
 function routePathFromFile(file) {
@@ -121,10 +130,9 @@ function routePathFromFile(file) {
     const appIndex = f.indexOf("/app/");
     const relative = f.slice(appIndex + 5);
 
-    const cleaned = relative
+    const cleaned = replaceBracketParams(relative
       .replace(/\/page\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\/route\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\[(.*?)\]/g, ":$1")
+      .replace(/\/route\.(ts|tsx|js|jsx)$/, ""))
       .replace(/\/$/, "");
 
     return cleaned ? `/${cleaned}` : "/";
@@ -141,10 +149,9 @@ function routePathFromFile(file) {
     const pagesIndex = f.indexOf("/pages/");
     const relative = f.slice(pagesIndex + 7);
 
-    const cleaned = relative
+    const cleaned = replaceBracketParams(relative
       .replace(/\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\/index$/, "")
-      .replace(/\[(.*?)\]/g, ":$1")
+      .replace(/\/index$/, ""))
       .replace(/\/$/, "");
 
     return cleaned ? `/${cleaned}` : "/";
@@ -316,11 +323,13 @@ async function extractRepoMetadata(repoRoot, files = []) {
     const hasLibraryEntry = Boolean(pkg.main || pkg.module || pkg.exports || pkg.types || pkg.typings || pkg.browser);
     const isShippedApp = Boolean(allDeps["electron"] || allDeps["next"]);
     metadata.packageEntryFiles = packageEntryFiles(pkg);
-    if (hasLibraryEntry && !isShippedApp) {
-      const description = String(pkg.description || "");
-      const keywords = Array.isArray(pkg.keywords) ? pkg.keywords.join(" ") : "";
-      const saysLibrary = /\b(library|sdk|parser|toolkit|framework)\b/i.test(description);
-      const saysCli = /\bcli\b|command[- ]line/i.test(`${description} ${keywords}`);
+    const description = String(pkg.description || "");
+    const keywords = Array.isArray(pkg.keywords) ? pkg.keywords.join(" ") : "";
+    const saysLibrary = /\b(library|sdk|parser|toolkit|framework)\b/i.test(`${description} ${keywords}`);
+    const saysCli = /\bcli\b|command[- ]line/i.test(`${description} ${keywords}`);
+    // Express 5 publishes index.js with no `main` field. A description that says
+    // library or framework is enough; Node's default entry is that index.js.
+    if ((hasLibraryEntry || saysLibrary) && !isShippedApp) {
       metadata.projectKind = hasBin && !saysLibrary && saysCli ? "cli" : "library";
     } else if (hasBin && !hasLibraryEntry) {
       metadata.projectKind = "cli";
@@ -408,16 +417,37 @@ async function extractRepoMetadata(repoRoot, files = []) {
   return metadata;
 }
 
+function isCommentLine(line) {
+  const trimmed = String(line || "").trim();
+  return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");
+}
+
+function lineAt(content, index) {
+  const start = content.lastIndexOf("\n", Math.max(0, index - 1)) + 1;
+  const end = content.indexOf("\n", index);
+  return content.slice(start, end === -1 ? content.length : end);
+}
+
+/** Express route paths start with `/`. `app.get('query parser fn')` is a setting. */
+function isExpressPath(routePath) {
+  return typeof routePath === "string"
+    && routePath.length > 0
+    && routePath.length <= 200
+    && (routePath.startsWith("/") || routePath === "*");
+}
+
 function extractExpressRoutes(content) {
   const routes = [];
   const seenRoutes = new Set();
 
-  // Match app.METHOD(path) or router.METHOD(path)
+  // Match app.METHOD(path) or router.METHOD(path). Skip comments and setting lookups.
   const methodPattern = /(?:app|router)\.(get|post|put|patch|delete|all)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
   let match;
 
   while ((match = methodPattern.exec(content)) !== null) {
+    if (isCommentLine(lineAt(content, match.index))) continue;
     const [, method, path] = match;
+    if (!isExpressPath(path)) continue;
     const routeKey = `${method.toUpperCase()}:${path}`;
     
     if (!seenRoutes.has(routeKey)) {
@@ -440,7 +470,9 @@ function extractExpressRoutes(content) {
   // Match app.route(path).METHOD()
   const routePattern = /(?:app|router)\.route\s*\(\s*['"`]([^'"`]+)['"`]\s*\)([.\s\w()]*)/gi;
   while ((match = routePattern.exec(content)) !== null) {
+    if (isCommentLine(lineAt(content, match.index))) continue;
     const [, path, chain] = match;
+    if (!isExpressPath(path)) continue;
     const methods = [];
     
     if (chain.includes(".get(")) methods.push("GET");
@@ -556,21 +588,28 @@ export async function scanRepo(cfg) {
   }
 
   const moduleCounts = new Map();
+  const flatKeys = new Set();
+  const rootLabel = rootModuleLabel(repoRoot);
 
   for (const file of files) {
     // Go test files belong to the package they exercise. Counting each
     // *_test.go as its own module (the filename under module_roots) splits
     // one package into a source module and a test module.
     if (/_test\.go$/.test(norm(file))) continue;
-    const key = moduleKeyForFile(file, cfg.module_roots || []);
+    const key = moduleKeyForFile(file, cfg.module_roots || [], rootLabel);
+    if (!norm(file).includes("/")) flatKeys.add(key);
     moduleCounts.set(key, (moduleCounts.get(key) || 0) + 1);
   }
 
   const modules = [...moduleCounts.entries()]
-    .map(([key, fileCount]) => ({ key, fileCount }))
+    .map(([key, fileCount]) => ({
+      key,
+      fileCount,
+      ...(flatKeys.has(key) ? { flat: true } : {}),
+    }))
     .sort((a, b) => b.fileCount - a.fileCount);
 
-  const apiFiles = files.filter(isNextRoute);
+  const apiFiles = files.filter((file) => isNextRoute(file) && !isNonProductPath(file));
   const api = [];
 
   // Extract Next.js API routes
@@ -593,8 +632,9 @@ export async function scanRepo(cfg) {
     });
   }
 
-  // Extract Express.js routes
+  // Extract Express.js routes. Tests and examples are not the product API.
   for (const file of files) {
+    if (isNonProductPath(file)) continue;
     if (file.endsWith(".ts") || file.endsWith(".js")) {
       const absoluteFile = path.join(repoRoot, file);
       const content = await readFileSafe(absoluteFile);
@@ -613,7 +653,7 @@ export async function scanRepo(cfg) {
     }
   }
 
-  const pageFiles = files.filter(isNextPage);
+  const pageFiles = files.filter((file) => isNextPage(file) && !isNonProductPath(file));
   const pages = pageFiles.map((file) => ({
     file,
     path: routePathFromFile(file),
@@ -622,6 +662,7 @@ export async function scanRepo(cfg) {
 
   // Extract React Router routes
   for (const file of files) {
+    if (isNonProductPath(file)) continue;
     if (file.endsWith(".tsx") || file.endsWith(".jsx")) {
       const absoluteFile = path.join(repoRoot, file);
       const content = await readFileSafe(absoluteFile);
@@ -635,6 +676,7 @@ export async function scanRepo(cfg) {
 
   // Extract Vue Router routes
   for (const file of files) {
+    if (isNonProductPath(file)) continue;
     if (file.endsWith(".ts") || file.endsWith(".js") || file.endsWith(".vue")) {
       const absoluteFile = path.join(repoRoot, file);
       const content = await readFileSafe(absoluteFile);

package/src/docs/llms-text.js

@@ -34,6 +34,7 @@ RepoLens is the npm package \`@chappibunny/repolens\` (Node.js 18+). It is a CLI
 - [publish](${REPO_URL}/blob/main/docs/INSTALLATION.md): \`npx @chappibunny/repolens publish\` scans and publishes
 - [badge](${REPO_URL}/blob/main/README.md): \`npx @chappibunny/repolens badge\` prints shields.io code-health JSON, SVG, or markdown
 - [comment](${REPO_URL}/blob/main/README.md): \`npx @chappibunny/repolens comment --base <ref> --head <ref>\` prints an architecture diff
+- [app](${REPO_URL}/blob/main/docs/GITHUB_APP.md): \`npx @chappibunny/repolens app\` self-hosts the GitHub App webhook. \`--manifest\` prints the manifest. No credentials are required to print it
 - [doctor](${REPO_URL}/blob/main/docs/INSTALLATION.md): \`npx @chappibunny/repolens doctor\` validates setup
 - [mcp](${REPO_URL}/blob/main/docs/MCP.md): \`npx -y @chappibunny/repolens mcp\` starts the stdio server
 
@@ -95,6 +96,7 @@ Agent-oriented install steps, including the Cline MCP snippet, are in llms-insta
 - \`repolens watch\` regenerates docs on change and exits 2 when nothing matches.
 - \`repolens badge\` prints a shields.io endpoint JSON document for the code-health score (0–100). \`--format svg\` prints a square SVG. \`--format markdown --url https://host/repolens-badge.json\` prints a README snippet. \`--format all --out repolens-badge.json\` writes JSON and SVG. Exit 2 when no JavaScript, TypeScript, Python, or Go files were scored. The score is not reported as 100 when zero files match.
 - \`repolens comment --base <ref> --head <ref>\` compares those commits. It prints markdown locally. In GitHub Actions, with \`GITHUB_TOKEN\`, \`GITHUB_REPOSITORY\`, and a pull_request event, it creates or updates one comment.
+- \`repolens app\` self-hosts a GitHub App webhook. It verifies \`X-Hub-Signature-256\`, posts a Check Run named RepoLens, and updates the sticky architecture comment. \`repolens app --manifest\` prints the manifest and needs no secrets. Listening needs \`REPOLENS_APP_ID\`, \`REPOLENS_WEBHOOK_SECRET\`, and a private key. See docs/GITHUB_APP.md.
 - \`repolens mcp\` starts the stdio MCP server. \`repolens-mcp\` is the same entry.
 
 Exit codes: 0 success, 1 runtime error or unknown command, 2 validation failure (bad flags, missing config, empty scan, and the other cases in the README).