@chappibunny/repolens 1.15.5 → 1.16.1

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.16.1
+
+Fixes three problems found by running 1.16.0 on orval-labs/orval (a TypeScript monorepo whose test snapshots and samples dwarf the packages).
+
+### Scan defaults
+
+- Snapshot directories (`__snapshots__`, `*.snap`), sample / fixture / example / e2e-fixture directories, and `generated/` trees are dev tooling. They are left out of the file count, orphan detection, and the type graph unless `scan.include_dev_artifacts: true`. Other `scan.ignore` patterns still apply. Orval's second copy of the snapshot tree lives in `tests/generated`, so `**/generated/**` is part of that default (it was already in the `init` ignore list).
+- `repolens badge` skips the same directories. It does not read `.repolens.yml`.
+
+### Cycle priority
+
+- A cycle is no longer always "Priority: High refactor".
+- **Low — mutual recursion, probably intentional; verify** when the cycle stays inside two parent directories that import each other both ways (at least two runtime edges each way) and both directions call the imported bindings (at least two calls each way). Orval's core getters and resolvers are this shape.
+- **Low — type-only imports; verify** when every edge is `import type` or `export type`. Those cycles are not runtime edges and are not counted in `stats.cycles`.
+- **High refactor** is kept for a cycle that touches three or more parent directories.
+- A two-directory cycle with only one import each way is **Medium**.
+- The health score subtracts points for high and medium cycles. Low-priority cycles do not. Stats that do not carry the priority split keep the previous per-cycle penalty.
+- The heuristic is documented in `src/analyzers/cycle-priority.js`, [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), and [docs/KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md).
+
+### npx and devEngines
+
+- npm versions that enforce `devEngines` (newer npm) check that field on the package.json in the current directory before `npx` starts the requested package. A repo that pins a Node or package-manager the host does not meet exits `EBADDEVENGINES`. Node 20's bundled npm does not enforce `devEngines`. RepoLens never gets to run when the check fails, so this cannot be fixed inside the CLI.
+- `--ignore-engines` is not an npm flag. On npm versions that enforce `devEngines`, npm warns that it is an unknown config and still errors.
+- `--force` turns that failure into a warning and runs the command. The GitHub Action passes `--force` on its `npx` step. A manual run is `npx --force --yes @chappibunny/repolens demo`. A global install, or `node node_modules/@chappibunny/repolens/bin/repolens.js`, never asks npm to read the scanned repo's `devEngines`.
+- See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
+
+## 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 --force --yes @chappibunny/repolens@1.16.1`). `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`. The action passes `--force` so a repository `devEngines` pin does not stop `npx` on npm versions that enforce `devEngines` (newer npm). Node 20's bundled npm does not enforce that field. From a shell, use the same flag: `npx --force --yes @chappibunny/repolens demo`. `--ignore-engines` does not skip `devEngines`.
 
-Publishing docs (the npm package at tag `v1.15.5`):
+Publishing docs (the npm package at tag `v1.16.1`):
 
 ```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.1
         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.1` 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.1
         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.1` has to exist before `uses: CHAPIBUNNY/repolens@v1.16.1` resolves, and `@chappibunny/repolens@1.16.1` 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.1
         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. 1.16.1 skips snapshot, sample, fixture, example, and generated trees in the file count, orphan list, and type graph, and labels a call-heavy two-folder cycle as mutual recursion rather than a high-priority refactor. 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,5 @@
 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.
+16. CLI (1.16.1): snapshot, sample, fixture, example, and generated directories are out of the file count, orphan list, and type graph unless `scan.include_dev_artifacts` is true. A two-folder call-heavy cycle is "mutual recursion, probably intentional; verify", not "Priority: High refactor". On npm versions that enforce `devEngines` (newer npm), `npx` inside a repo with `devEngines` needs `--force`. Node 20's bundled npm does not enforce that field. `--ignore-engines` does not skip the check.

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.1",
   "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/ai/generate-sections.js

@@ -16,6 +16,7 @@ import { identifyFlowDependencies, filterNoiseFlows } from "../analyzers/flow-in
 import { isCliProject, isLibraryProject } from "../analyzers/context-builder.js";
 import { scoreMaturity } from "../analyzers/maturity.js";
 import { isNonProductPath, isTestPath } from "../utils/path-roles.js";
+import { cycleConcern, cycleHealthPenalty, cycleInsight, cycleStatusCell } from "../analyzers/cycle-priority.js";
 import { info, warn } from "../utils/logger.js";
 
 // Strip conversational patterns that LLMs sometimes inject into documentation
@@ -288,7 +289,8 @@ The system is organized around **${context.domains.length} functional domains**,
     output += `|--------|-------|--------|\n`;
     output += `| Internal imports | ${stats.totalEdges} edges | ${stats.totalEdges > 0 ? "✅ Connected" : "⚠️ Isolated"} |\n`;
     output += `| External Packages | ${externalPackagesLabel(stats)} | ${stats.externalDeps < 50 ? "✅ Manageable" : stats.externalDeps < 100 ? "⚠️ Consider audit" : "🔴 High dependency count"} |\n`;
-    output += `| Circular Dependencies | ${stats.cycles === 0 ? "cycle-free" : stats.cycles} | ${stats.cycles === 0 ? "✅ None" : `🔴 ${stats.cycles} detected`} |\n`;
+    const cycleCell = cycleStatusCell(stats);
+    output += `| Circular Dependencies | ${stats.cycles === 0 ? "cycle-free" : stats.cycles} | ${stats.cycles === 0 ? "✅ None" : `${cycleCell.mark} ${stats.cycles} detected`} |\n`;
     output += `| Orphan Files | ${stats.orphanFiles} | ${orphanStatus(stats)} |\n`;
 
     // Key insights
@@ -296,7 +298,7 @@ The system is organized around **${context.domains.length} functional domains**,
     if (stats.cycles === 0) {
       output += `- ✅ **Clean module boundaries** — No circular dependencies detected, enabling safe refactoring and testing.\n`;
     } else {
-      output += `- 🔴 **Architectural concern** — ${stats.cycles} circular dependenc${stats.cycles === 1 ? "y" : "ies"} detected. These create tight coupling and make testing difficult.\n`;
+      output += `- ${cycleInsight(stats)}\n`;
     }
     if (stats.hubs && stats.hubs.length > 0) {
       const topHub = stats.hubs[0];
@@ -828,7 +830,8 @@ function getFallbackArchitectureOverview(context, enrichment = {}) {
     output += `|--------|-------|--------|----------------|\n`;
     output += `| Import Edges | ${stats.totalEdges} | ${stats.totalEdges > 0 ? "✅" : "⚠️"} | ${stats.totalEdges > 0 ? "Healthy module connectivity" : "Consider connecting modules"} |\n`;
     output += `| External Packages | ${externalPackagesLabel(stats)} | ${stats.externalDeps < 50 ? "✅" : stats.externalDeps < 100 ? "⚠️" : "🔴"} | ${stats.externalDeps >= 100 ? "Audit for unused dependencies" : stats.externalDeps >= 50 ? "Review dependency necessity" : "Lean dependency set"} |\n`;
-    output += `| Circular Deps | ${stats.cycles} | ${stats.cycles === 0 ? "✅" : "🔴"} | ${stats.cycles === 0 ? "Clean module boundaries" : "Refactor to break cycles"} |\n`;
+    const archCycle = cycleStatusCell(stats);
+    output += `| Circular Deps | ${stats.cycles} | ${stats.cycles === 0 ? "✅" : archCycle.mark} | ${stats.cycles === 0 ? "Clean module boundaries" : archCycle.advice} |\n`;
     output += `| Orphan Files | ${stats.orphanFiles} | ${orphanRatio(stats) > ORPHAN_WARN_RATIO ? "⚠️" : "✅"} | ${stats.orphanFiles === 0 ? "All code is connected" : orphanRatio(stats) > ORPHAN_WARN_RATIO ? "Review for dead code" : "A few unconnected files (examples, type tests, entry points) are normal"} |\n`;
 
     // Architectural strengths and concerns
@@ -856,9 +859,8 @@ function getFallbackArchitectureOverview(context, enrichment = {}) {
 
     // Concerns
     const concerns = [];
-    if (stats.cycles > 0) {
-      concerns.push(`**Circular dependencies detected** — ${stats.cycles} circular dependenc${stats.cycles === 1 ? 'y' : 'ies'} create tight coupling, complicate testing, and hinder refactoring. Priority: High.`);
-    }
+    const concern = cycleConcern(stats);
+    if (concern) concerns.push(concern);
     if (stats.orphanFiles > stats.totalFiles * 0.2) {
       concerns.push(`**High orphan file ratio** — ${stats.orphanFiles}/${stats.totalFiles} files (${Math.round(stats.orphanFiles / stats.totalFiles * 100)}%) are not imported. Consider removing dead code. Priority: Medium.`);
     }
@@ -1625,8 +1627,9 @@ function externalPackagesLabel(stats) {
 function calculateHealthScore(stats, context) {
   let score = 100;
   
-  // Circular dependencies are a major concern
-  if (stats.cycles > 0) score -= Math.min(30, stats.cycles * 10);
+  // High and medium cycles cost points. Mutual recursion and type-only cycles do not.
+  // A stats object without the priority split keeps the older per-cycle penalty.
+  score -= cycleHealthPenalty(stats);
   
   // Orphan files indicate potential dead code
   const ratio = orphanRatio(stats);

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/cycle-priority.js

@@ -0,0 +1,169 @@
+// Cycle priority.
+//
+// Not every circular import is a refactor. The heuristic:
+//
+// 1. Type-only. Every edge in the cycle is `import type` or `export type`.
+//    There is no runtime cycle. Priority: Low. Wording: type-only imports; verify.
+//    These stay out of the runtime cycle list (`cycles` / `stats.cycles`).
+//
+// 2. Recursive-descent pair (mutual recursion). The cycle stays inside two parent
+//    directories, and those two directories import each other in both directions
+//    with many edges (at least 2 each way) and both directions are call-heavy
+//    (at least 2 calls of the imported bindings each way). Schema getters calling
+//    resolvers that call getters is this shape. The pair is small: two folders,
+//    not a chain across the repo. Priority: Low. Wording: mutual recursion,
+//    probably intentional; verify.
+//
+// 3. Large multi-module cycle. The cycle touches 3 or more parent directories.
+//    Priority: High refactor.
+//
+// 4. Anything else (a short accidental cycle, one import each way, no real call
+//    traffic) is Medium: review, not a blanket high-priority refactor.
+//
+// "Folder" is the file's parent directory. `index.ts` stays in its own directory
+// after the graph strips the `/index` suffix. Call counts use ESM bindings
+// (`import { fn }` then `fn(` or `ns.fn(`). A `require()` edge has no binding
+// names, so it does not count as call-heavy.
+
+export const MUTUAL_EDGE_MINIMUM = 2;
+export const MUTUAL_CALL_MINIMUM = 2;
+export const HIGH_FOLDER_MINIMUM = 3;
+
+export function folderOfFile(file) {
+  const norm = String(file || "").replace(/\\/g, "/");
+  const slash = norm.lastIndexOf("/");
+  if (slash <= 0) return ".";
+  return norm.slice(0, slash);
+}
+
+function cycleNodes(path) {
+  if (!Array.isArray(path) || path.length < 2) return [];
+  return path[0] === path[path.length - 1] ? path.slice(0, -1) : path.slice();
+}
+
+function report(path, priority, kind, label) {
+  return { path, priority, kind, label, priorityLine: priorityLine(priority, label) };
+}
+
+export function priorityLine(priority, label) {
+  if (priority === "high") return "Priority: High refactor";
+  const text = label || "review";
+  const name = priority === "low" ? "Low" : "Medium";
+  return `Priority: ${name} — ${text}`;
+}
+
+/**
+ * Classify one runtime cycle.
+ * `edges` are runtime import edges: { from, to, fromFile, toFile, calls }.
+ * `fileForKey(key)` returns the source path used for the parent directory.
+ */
+export function classifyRuntimeCycle(path, edges, fileForKey) {
+  const nodes = cycleNodes(path);
+  const folders = nodes.map((key) => folderOfFile(fileForKey(key)));
+  const uniqueFolders = [...new Set(folders)];
+
+  if (uniqueFolders.length >= HIGH_FOLDER_MINIMUM) {
+    return report(path, "high", "multi-module", "large multi-module cycle");
+  }
+
+  if (uniqueFolders.length === 2 && isRecursiveDescentPair(uniqueFolders[0], uniqueFolders[1], edges)) {
+    return report(path, "low", "mutual-recursion", "mutual recursion, probably intentional; verify");
+  }
+
+  return report(path, "medium", "small", "small cycle; review");
+}
+
+export function isRecursiveDescentPair(folderA, folderB, edges) {
+  let ab = 0;
+  let ba = 0;
+  let callsAB = 0;
+  let callsBA = 0;
+  for (const edge of edges || []) {
+    if (edge.typeOnly) continue;
+    const from = folderOfFile(edge.fromFile || edge.from);
+    const to = folderOfFile(edge.toFile || edge.to);
+    if (from === folderA && to === folderB) {
+      ab += 1;
+      callsAB += edge.calls || 0;
+    } else if (from === folderB && to === folderA) {
+      ba += 1;
+      callsBA += edge.calls || 0;
+    }
+  }
+  return ab >= MUTUAL_EDGE_MINIMUM
+    && ba >= MUTUAL_EDGE_MINIMUM
+    && callsAB >= MUTUAL_CALL_MINIMUM
+    && callsBA >= MUTUAL_CALL_MINIMUM;
+}
+
+export function classifyRuntimeCycles(cycles, edges, fileForKey) {
+  return (cycles || []).map((path) => classifyRuntimeCycle(path, edges, fileForKey));
+}
+
+export function typeOnlyReport(path) {
+  return report(path, "low", "type-only", "type-only imports; verify");
+}
+
+export function priorityCounts(reports) {
+  const counts = { high: 0, medium: 0, low: 0 };
+  for (const item of reports || []) {
+    if (item.priority === "high") counts.high += 1;
+    else if (item.priority === "low") counts.low += 1;
+    else counts.medium += 1;
+  }
+  return counts;
+}
+
+export function hasCyclePriorities(stats) {
+  return Boolean(stats) && (stats.highCycles != null || stats.mediumCycles != null || stats.lowCycles != null);
+}
+
+/** Points removed from the architecture health score. Low-priority cycles do not count. */
+export function cycleHealthPenalty(stats) {
+  if (!stats) return 0;
+  if (!hasCyclePriorities(stats)) {
+    return stats.cycles > 0 ? Math.min(30, stats.cycles * 10) : 0;
+  }
+  const high = stats.highCycles || 0;
+  const medium = stats.mediumCycles || 0;
+  return Math.min(30, high * 10 + medium * 5);
+}
+
+export function cycleStatusCell(stats) {
+  if (!stats || stats.cycles === 0) return { mark: "✅", advice: "Clean module boundaries" };
+  if (hasCyclePriorities(stats) && (stats.highCycles || 0) === 0 && (stats.lowCycles || 0) > 0 && !(stats.mediumCycles > 0)) {
+    return { mark: "🟡", advice: "mutual recursion, probably intentional; verify" };
+  }
+  if (hasCyclePriorities(stats) && (stats.highCycles || 0) === 0) {
+    return { mark: "🟡", advice: "Small cycle; review" };
+  }
+  return { mark: "🔴", advice: "Refactor to break cycles" };
+}
+
+export function cycleConcern(stats) {
+  if (!stats || !(stats.cycles > 0)) return null;
+  const noun = `circular dependenc${stats.cycles === 1 ? "y" : "ies"}`;
+  if (!hasCyclePriorities(stats)) {
+    return `**Circular dependencies detected** — ${stats.cycles} ${noun} create tight coupling, complicate testing, and hinder refactoring. Priority: High.`;
+  }
+  if ((stats.highCycles || 0) > 0) {
+    const high = stats.highCycles;
+    const highNoun = `circular dependenc${high === 1 ? "y" : "ies"}`;
+    return `**Circular dependencies detected** — ${high} large multi-module ${highNoun}. Priority: High refactor.`;
+  }
+  if ((stats.lowCycles || 0) > 0 && !(stats.mediumCycles > 0)) {
+    return `**Circular dependencies detected** — ${stats.cycles} ${noun}. mutual recursion, probably intentional; verify. Priority: Low.`;
+  }
+  return `**Circular dependencies detected** — ${stats.cycles} ${noun}. Priority: Medium.`;
+}
+
+export function cycleInsight(stats) {
+  if (!stats || !(stats.cycles > 0)) return null;
+  if (!hasCyclePriorities(stats)) {
+    return `🔴 **Architectural concern** — ${stats.cycles} circular dependenc${stats.cycles === 1 ? "y" : "ies"} detected. These create tight coupling and make testing difficult.`;
+  }
+  if ((stats.highCycles || 0) === 0) {
+    return `🟡 **Circular dependencies** — ${stats.cycles} detected. mutual recursion, probably intentional; verify. Priority: Low.`;
+  }
+  return `🔴 **Architectural concern** — ${stats.highCycles} large multi-module circular dependenc${stats.highCycles === 1 ? "y" : "ies"} detected. Priority: High refactor.`;
+}