codecortex 0.21.0__tar.gz → 0.23.0__tar.gz

{codecortex-0.21.0/src/codecortex.egg-info → codecortex-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.21.0
+Version: 0.23.0
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -33,6 +33,8 @@ Requires-Dist: pytest-cov>=5; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"
 Requires-Dist: ruff>=0.16; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
+Provides-Extra: bench
+Requires-Dist: anthropic>=0.40; extra == "bench"
 Dynamic: license-file
 
 # codeintel
@@ -61,9 +63,9 @@ Prefer plain text? `codeintel map` writes a **readable architecture overview** t
 
 **What `CODE_INTEL.md` is for.** It's a *static, committable* snapshot of a codebase's shape — meant to be read (by a person or an agent) **first**, instead of reconstructing structure by grepping. It covers the cases the live `code.query` tool doesn't:
 
-- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a short, tool-naming pointer block into `AGENTS.md` (the cross-tool surface read by Codex, Cursor, Zed, and others — created with your consent if it doesn't exist yet) plus a one-line `@AGENTS.md` import into `CLAUDE.md`, and writes the fuller [`USING_CODEINTEL.md`](USING_CODEINTEL.md) guide the block points to — so an agent knows to reach for `code.query` before it reaches for grep, not just that a `CODE_INTEL.md` exists.
+- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a short, tool-naming pointer block into `AGENTS.md` (the cross-tool surface read by Codex, Cursor, Zed, and others — created with your consent if it doesn't exist yet) plus a one-line `@AGENTS.md` import into `CLAUDE.md`, and writes the fuller `USING_CODEINTEL.md` guide the block points to — into **your** repo, which is why there is no such file to click here — so an agent knows to reach for `code.query` before it reaches for grep, not just that a `CODE_INTEL.md` exists.
 - **A committed, diffable overview.** It lives *in the repo* — reviewable in a PR, browsable on GitHub, available offline. Re-run `codeintel map` after `codeintel index` to refresh it.
-- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything.
+- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything. The ranking counts `CALLS` edges into **callable** nodes only (functions, methods, classes, interfaces, routes), and skips test, generated and archived files. Both constraints are load-bearing rather than tidy-up: without them a 12,638-node TypeScript repo ranked `logger` (a *folder* node) at 716 and `onClick` at 107, and a Python repo ranked YAML and JSON keys — `flow` from a `.flow.yaml`, `feature` from a `.schema.json` — as its most depended-on symbols. This repo's own map is Python-heavy and barely showed it, which is exactly why dogfooding did not catch it.
 
 See **[docs/map-file.md](docs/map-file.md)** for the format and the `--inject` flow.
 
@@ -91,7 +93,7 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | Who calls this? | `callers` | graph | caller symbols + files |
 | What does this call? | `callees` | graph | callee symbols + files |
 | Blast radius of a change | `impact` | graph | callers **and** callees together |
-| Trace a call chain up/downstream | `chain` | graph | ordered, risk-labeled hops |
+| Trace a call chain up/downstream | `chain` | graph | ordered hops, each labelled with how it was resolved |
 | Find symbols by pattern | `pattern` | graph | matching nodes + locations |
 | Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
 | Everything about one symbol | `context` | graph + lsp | both views merged |
@@ -153,6 +155,57 @@ no benefit to set against that error rate.
 **Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
 `deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
 
+## An architecture model, as source
+
+`codeintel c4` turns the graph index into a [LikeC4](https://likec4.dev) model — architecture-as-code
+you can commit, diff and hand-edit, rather than a rendered picture you have to regenerate to read.
+Abridged output, from `--scope src/codeintel/providers`:
+
+```
+// Generated by codeintel from the graph index — do not edit by hand.
+// edges: union of IMPORTS (static module-level imports) and CALLS|USAGE (call/usage references)
+// coverage is NOT complete: dispatch through a name/lookup table can still be invisible to both
+// hotspot ranking uses IMPORTS-only fan-in, never the CALLS|USAGE union
+
+model {
+  src = area 'src' {
+    codeintel = area 'codeintel' {
+      providers = area 'providers' {
+        lsp = module 'lsp' {
+          technology 'Python'
+          metadata { path 'src/codeintel/providers/lsp.py'  churn '12'  fan_out '2' }
+        }
+        graph = module 'graph' { /* … */ }
+      }
+    }
+  }
+
+  src.codeintel.providers.lsp -[calls_usage]-> src.codeintel.providers.graph { metadata { n '2' } }
+}
+```
+
+Directories become `area`, files become `module`, and every element carries its real path plus churn
+and fan-in as `metadata` — so the model is queryable, not only drawable. Each file opens with what it
+cannot know: which edge sources it used, that coverage is incomplete, and how many references were
+folded or dropped. `npx likec4 start codeintel-c4` renders it; nothing else here needs Node.
+
+**Two edge sources, and the choice matters more than it sounds.** The default unions static `IMPORTS`
+with `CALLS|USAGE`, which recovers lazy and function-body imports. On this repo at
+`--scope src --depth 3` that is 179 relations — **134 of them `CALLS|USAGE`-only**, which renders as a
+hairball. `--edges imports` leaves the same 45 elements with 45 edges: legible, and roughly layered,
+because every remaining edge descends.
+
+**It also answers two questions without drawing anything.** `--layers` infers architectural bands
+from the import graph — 7 bands over 35 of those 45 elements, the other 10 having no module-level
+import edge either way. `--check` gates CI on a declared
+`[layers]` block in `.codeintel.toml`, exiting **2** on architectural drift — deliberately distinct
+from exit 1 for a broken run, so a CI step can tell "your architecture drifted" from "codeintel is
+broken". A config generated by `--suggest-config` is a *provably* green baseline on the commit that
+produced it, so adoption is paste-confirm-tighten rather than a wall of false positives.
+
+Full reference: **[docs/c4.md](docs/c4.md)**. Why LikeC4 and not something else, measured:
+[docs/eval-2026-08-26-likec4.md](docs/eval-2026-08-26-likec4.md).
+
 ## What makes it good
 
 - **Local-first and private.** One process on your machine — no cloud service, no API keys, no telemetry, no per-query network. Safe to point at a private repo, even with `--engine all`. (The one-time exception: `fastembed` downloads its embedding model once, then runs fully offline.)
@@ -281,7 +334,7 @@ Then it launches the exact command it registered and drives a real MCP handshake
 ```text
 v claude: registered at /Users/you/.claude.json
 
-v verified: codeintel 0.21.0 — 4 tools (code.query, code.status, code.doctor, code.map)
+v verified: codeintel 0.23.0 — 4 tools (code.query, code.status, code.doctor, code.map)
 ```
 
 If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
@@ -343,7 +396,7 @@ The optional keys are the ones worth reading when an answer surprises you:
 
 | Engine | Key ops | Install prereq |
 |---|---|---|
-| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` **0.9.x** on PATH (`pip install 'codebase-memory-mcp==0.9.*'`) — 0.10.x changed its response format and returns nothing for every op but resolution; see [docs/graph.md](docs/graph.md) |
+| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` **0.9.x or 0.10.x** on PATH — both wire dialects are read; `0.10.x` is the more accurate backend and is recommended (`pip install 'codebase-memory-mcp==0.10.*'`). See [docs/graph.md](docs/graph.md) |
 | `lsp` | `symbol`, `overview`, `context` | `uvx` on PATH — serena is fetched from GitHub on first use; see [docs/lsp.md](docs/lsp.md) |
 | `semantic` | `search`, `context` | `fastembed` + `sqlite-vec` (installed with the package) — see [docs/semantic.md](docs/semantic.md) |
 
@@ -396,7 +449,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 |---|---|
 | `codeintel help` | Every command grouped by task, with descriptions and examples (also the bare `codeintel`). A mistyped command suggests what you meant. |
 | `codeintel install [--agent auto\|claude\|codex\|gemini\|zed\|all] [--no-verify] [--relative-command]` | Register codeintel with the agents installed on this machine (`auto`, the default), then prove it by completing a real MCP handshake against the registered command |
-| `codeintel setup [project_root] [--all] [--index] [--warm] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
+| `codeintel setup [project_root] [--all] [--index] [--warm] [--languages] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
 | `codeintel prompt [project_root] [--agent auto\|claude\|codex\|gemini\|zed] [--fresh] [--deep]` | Print a paste-to-your-agent setup prompt; probes health and emits only the outstanding steps (or "just restart me" when already healthy). `--fresh` = the full sequence from `pip install`, to send a friend |
 | `codeintel index [project_root] [--quiet]` | Index a repo (semantic embeddings + best-effort graph & map refresh), with a live progress display; `--quiet` prints only the result line |
 | `codeintel serve` | Start the MCP server (stdio transport) |
@@ -406,7 +459,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
-| `codeintel c4 [project_root] [--out DIR] [--depth N] [--scope PATH] [--include-tests] [--no-index] [--json]` | Write a LikeC4 architecture model (`.c4`) of the repo's file/directory structure and its import graph — committable, diffable, hand-editable source rather than a rendered picture. Indexes the repo first if it has no graph index. See [docs/c4.md](docs/c4.md) |
+| `codeintel c4 [project_root] [--out DIR] [--depth N] [--scope PATH] [--include-tests] [--no-index] [--edges union\|imports] [--json] [--layers] [--suggest-config] [--check] [--layers-from auto\|inferred\|declared]` | Write a LikeC4 architecture model (`.c4`) of the repo's files and import graph. Indexes the repo first if it has no graph index. `--edges imports` drops the lower-confidence edges for a legible diagram; `--layers` reports inferred architectural bands; `--check` gates CI on a declared `[layers]` config, exit 2 on drift. See [An architecture model, as source](#an-architecture-model-as-source) and [docs/c4.md](docs/c4.md) |
 | `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear this repo's index — **both** semantic and graph — so it's as if never indexed; `--all` wipes every repo. Recovers from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
@@ -646,7 +699,7 @@ cd codeintel
 pip install -e .[dev]
 
 pytest tests/ -q            # ~740 tests, ~30s; fails under 83% coverage
-ruff check src tests        # lint
+ruff check src tests bench  # lint
 mypy                        # types (src/ only)
 ```
 

{codecortex-0.21.0 → codecortex-0.23.0}/README.md

@@ -24,9 +24,9 @@ Prefer plain text? `codeintel map` writes a **readable architecture overview** t
 
 **What `CODE_INTEL.md` is for.** It's a *static, committable* snapshot of a codebase's shape — meant to be read (by a person or an agent) **first**, instead of reconstructing structure by grepping. It covers the cases the live `code.query` tool doesn't:
 
-- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a short, tool-naming pointer block into `AGENTS.md` (the cross-tool surface read by Codex, Cursor, Zed, and others — created with your consent if it doesn't exist yet) plus a one-line `@AGENTS.md` import into `CLAUDE.md`, and writes the fuller [`USING_CODEINTEL.md`](USING_CODEINTEL.md) guide the block points to — so an agent knows to reach for `code.query` before it reaches for grep, not just that a `CODE_INTEL.md` exists.
+- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a short, tool-naming pointer block into `AGENTS.md` (the cross-tool surface read by Codex, Cursor, Zed, and others — created with your consent if it doesn't exist yet) plus a one-line `@AGENTS.md` import into `CLAUDE.md`, and writes the fuller `USING_CODEINTEL.md` guide the block points to — into **your** repo, which is why there is no such file to click here — so an agent knows to reach for `code.query` before it reaches for grep, not just that a `CODE_INTEL.md` exists.
 - **A committed, diffable overview.** It lives *in the repo* — reviewable in a PR, browsable on GitHub, available offline. Re-run `codeintel map` after `codeintel index` to refresh it.
-- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything.
+- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything. The ranking counts `CALLS` edges into **callable** nodes only (functions, methods, classes, interfaces, routes), and skips test, generated and archived files. Both constraints are load-bearing rather than tidy-up: without them a 12,638-node TypeScript repo ranked `logger` (a *folder* node) at 716 and `onClick` at 107, and a Python repo ranked YAML and JSON keys — `flow` from a `.flow.yaml`, `feature` from a `.schema.json` — as its most depended-on symbols. This repo's own map is Python-heavy and barely showed it, which is exactly why dogfooding did not catch it.
 
 See **[docs/map-file.md](docs/map-file.md)** for the format and the `--inject` flow.
 
@@ -54,7 +54,7 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | Who calls this? | `callers` | graph | caller symbols + files |
 | What does this call? | `callees` | graph | callee symbols + files |
 | Blast radius of a change | `impact` | graph | callers **and** callees together |
-| Trace a call chain up/downstream | `chain` | graph | ordered, risk-labeled hops |
+| Trace a call chain up/downstream | `chain` | graph | ordered hops, each labelled with how it was resolved |
 | Find symbols by pattern | `pattern` | graph | matching nodes + locations |
 | Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
 | Everything about one symbol | `context` | graph + lsp | both views merged |
@@ -116,6 +116,57 @@ no benefit to set against that error rate.
 **Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
 `deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
 
+## An architecture model, as source
+
+`codeintel c4` turns the graph index into a [LikeC4](https://likec4.dev) model — architecture-as-code
+you can commit, diff and hand-edit, rather than a rendered picture you have to regenerate to read.
+Abridged output, from `--scope src/codeintel/providers`:
+
+```
+// Generated by codeintel from the graph index — do not edit by hand.
+// edges: union of IMPORTS (static module-level imports) and CALLS|USAGE (call/usage references)
+// coverage is NOT complete: dispatch through a name/lookup table can still be invisible to both
+// hotspot ranking uses IMPORTS-only fan-in, never the CALLS|USAGE union
+
+model {
+  src = area 'src' {
+    codeintel = area 'codeintel' {
+      providers = area 'providers' {
+        lsp = module 'lsp' {
+          technology 'Python'
+          metadata { path 'src/codeintel/providers/lsp.py'  churn '12'  fan_out '2' }
+        }
+        graph = module 'graph' { /* … */ }
+      }
+    }
+  }
+
+  src.codeintel.providers.lsp -[calls_usage]-> src.codeintel.providers.graph { metadata { n '2' } }
+}
+```
+
+Directories become `area`, files become `module`, and every element carries its real path plus churn
+and fan-in as `metadata` — so the model is queryable, not only drawable. Each file opens with what it
+cannot know: which edge sources it used, that coverage is incomplete, and how many references were
+folded or dropped. `npx likec4 start codeintel-c4` renders it; nothing else here needs Node.
+
+**Two edge sources, and the choice matters more than it sounds.** The default unions static `IMPORTS`
+with `CALLS|USAGE`, which recovers lazy and function-body imports. On this repo at
+`--scope src --depth 3` that is 179 relations — **134 of them `CALLS|USAGE`-only**, which renders as a
+hairball. `--edges imports` leaves the same 45 elements with 45 edges: legible, and roughly layered,
+because every remaining edge descends.
+
+**It also answers two questions without drawing anything.** `--layers` infers architectural bands
+from the import graph — 7 bands over 35 of those 45 elements, the other 10 having no module-level
+import edge either way. `--check` gates CI on a declared
+`[layers]` block in `.codeintel.toml`, exiting **2** on architectural drift — deliberately distinct
+from exit 1 for a broken run, so a CI step can tell "your architecture drifted" from "codeintel is
+broken". A config generated by `--suggest-config` is a *provably* green baseline on the commit that
+produced it, so adoption is paste-confirm-tighten rather than a wall of false positives.
+
+Full reference: **[docs/c4.md](docs/c4.md)**. Why LikeC4 and not something else, measured:
+[docs/eval-2026-08-26-likec4.md](docs/eval-2026-08-26-likec4.md).
+
 ## What makes it good
 
 - **Local-first and private.** One process on your machine — no cloud service, no API keys, no telemetry, no per-query network. Safe to point at a private repo, even with `--engine all`. (The one-time exception: `fastembed` downloads its embedding model once, then runs fully offline.)
@@ -244,7 +295,7 @@ Then it launches the exact command it registered and drives a real MCP handshake
 ```text
 v claude: registered at /Users/you/.claude.json
 
-v verified: codeintel 0.21.0 — 4 tools (code.query, code.status, code.doctor, code.map)
+v verified: codeintel 0.23.0 — 4 tools (code.query, code.status, code.doctor, code.map)
 ```
 
 If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
@@ -306,7 +357,7 @@ The optional keys are the ones worth reading when an answer surprises you:
 
 | Engine | Key ops | Install prereq |
 |---|---|---|
-| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` **0.9.x** on PATH (`pip install 'codebase-memory-mcp==0.9.*'`) — 0.10.x changed its response format and returns nothing for every op but resolution; see [docs/graph.md](docs/graph.md) |
+| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` **0.9.x or 0.10.x** on PATH — both wire dialects are read; `0.10.x` is the more accurate backend and is recommended (`pip install 'codebase-memory-mcp==0.10.*'`). See [docs/graph.md](docs/graph.md) |
 | `lsp` | `symbol`, `overview`, `context` | `uvx` on PATH — serena is fetched from GitHub on first use; see [docs/lsp.md](docs/lsp.md) |
 | `semantic` | `search`, `context` | `fastembed` + `sqlite-vec` (installed with the package) — see [docs/semantic.md](docs/semantic.md) |
 
@@ -359,7 +410,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 |---|---|
 | `codeintel help` | Every command grouped by task, with descriptions and examples (also the bare `codeintel`). A mistyped command suggests what you meant. |
 | `codeintel install [--agent auto\|claude\|codex\|gemini\|zed\|all] [--no-verify] [--relative-command]` | Register codeintel with the agents installed on this machine (`auto`, the default), then prove it by completing a real MCP handshake against the registered command |
-| `codeintel setup [project_root] [--all] [--index] [--warm] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
+| `codeintel setup [project_root] [--all] [--index] [--warm] [--languages] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
 | `codeintel prompt [project_root] [--agent auto\|claude\|codex\|gemini\|zed] [--fresh] [--deep]` | Print a paste-to-your-agent setup prompt; probes health and emits only the outstanding steps (or "just restart me" when already healthy). `--fresh` = the full sequence from `pip install`, to send a friend |
 | `codeintel index [project_root] [--quiet]` | Index a repo (semantic embeddings + best-effort graph & map refresh), with a live progress display; `--quiet` prints only the result line |
 | `codeintel serve` | Start the MCP server (stdio transport) |
@@ -369,7 +420,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
-| `codeintel c4 [project_root] [--out DIR] [--depth N] [--scope PATH] [--include-tests] [--no-index] [--json]` | Write a LikeC4 architecture model (`.c4`) of the repo's file/directory structure and its import graph — committable, diffable, hand-editable source rather than a rendered picture. Indexes the repo first if it has no graph index. See [docs/c4.md](docs/c4.md) |
+| `codeintel c4 [project_root] [--out DIR] [--depth N] [--scope PATH] [--include-tests] [--no-index] [--edges union\|imports] [--json] [--layers] [--suggest-config] [--check] [--layers-from auto\|inferred\|declared]` | Write a LikeC4 architecture model (`.c4`) of the repo's files and import graph. Indexes the repo first if it has no graph index. `--edges imports` drops the lower-confidence edges for a legible diagram; `--layers` reports inferred architectural bands; `--check` gates CI on a declared `[layers]` config, exit 2 on drift. See [An architecture model, as source](#an-architecture-model-as-source) and [docs/c4.md](docs/c4.md) |
 | `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear this repo's index — **both** semantic and graph — so it's as if never indexed; `--all` wipes every repo. Recovers from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
@@ -609,7 +660,7 @@ cd codeintel
 pip install -e .[dev]
 
 pytest tests/ -q            # ~740 tests, ~30s; fails under 83% coverage
-ruff check src tests        # lint
+ruff check src tests bench  # lint
 mypy                        # types (src/ only)
 ```
 

{codecortex-0.21.0 → codecortex-0.23.0}/pyproject.toml

@@ -54,6 +54,14 @@ codeintel = "codeintel.__main__:main"
 [project.optional-dependencies]
 dev = ["pytest>=8", "pytest-cov>=5", "numpy>=1.24", "ruff>=0.16", "mypy>=1.11"]
 
+# `bench/agent_bench.py` only. Deliberately NOT in `dev`, and emphatically not a runtime dependency:
+# codeintel's own code makes zero outbound HTTP calls and that claim is load-bearing in the README.
+# The agent-cost benchmark is the one artifact here that talks to a model API, it is a manual paid
+# run, and nothing in `src/` or the test suite imports this. Its own extra keeps `dev` (and CI) from
+# installing an API client for code they never execute.
+#     pip install -e '.[bench]'
+bench = ["anthropic>=0.40"]
+
 # Single source of truth for the version: read from codeintel.__version__ (AST-parsed, no import).
 [tool.setuptools.dynamic]
 version = { attr = "codeintel.__version__" }
@@ -100,6 +108,17 @@ ignore = [
 # manager is a bad trade in code whose whole contract is degrading quietly.
 
 [tool.ruff.lint.per-file-ignores]
+# The oracle's fixture corpus is a micro-repository whose SOURCE is the test input. Every finding
+# ruff has here is the property under test: an import that is never used is the `IMPORT` case, a
+# star import is the abstention case, an undefined name is the injected-global case. Fixing them
+# would delete the fixtures. They are ignored as a group rather than with inline `noqa`s, so the
+# corpus keeps looking like the ordinary code it is standing in for.
+"bench/fixtures/corpus/**" = [
+    "F401",     # imported and never used -> `imports_only.py`, and both re-export links
+    "F403",     # `import *` -> the star-import abstention
+    "F405",     # name may be undefined from a star import -> the same file
+    "F821",     # undefined name -> `injected.py`, the `describe` shape
+]
 # Tests stand up fake servers on loopback, assert on hardcoded fixture tokens, and shell out to
 # the CLI under test. Flagging that as a security finding is noise.
 "tests/*" = [

{codecortex-0.21.0 → codecortex-0.23.0/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.21.0
+Version: 0.23.0
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -33,6 +33,8 @@ Requires-Dist: pytest-cov>=5; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"
 Requires-Dist: ruff>=0.16; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
+Provides-Extra: bench
+Requires-Dist: anthropic>=0.40; extra == "bench"
 Dynamic: license-file
 
 # codeintel
@@ -61,9 +63,9 @@ Prefer plain text? `codeintel map` writes a **readable architecture overview** t
 
 **What `CODE_INTEL.md` is for.** It's a *static, committable* snapshot of a codebase's shape — meant to be read (by a person or an agent) **first**, instead of reconstructing structure by grepping. It covers the cases the live `code.query` tool doesn't:
 
-- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a short, tool-naming pointer block into `AGENTS.md` (the cross-tool surface read by Codex, Cursor, Zed, and others — created with your consent if it doesn't exist yet) plus a one-line `@AGENTS.md` import into `CLAUDE.md`, and writes the fuller [`USING_CODEINTEL.md`](USING_CODEINTEL.md) guide the block points to — so an agent knows to reach for `code.query` before it reaches for grep, not just that a `CODE_INTEL.md` exists.
+- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a short, tool-naming pointer block into `AGENTS.md` (the cross-tool surface read by Codex, Cursor, Zed, and others — created with your consent if it doesn't exist yet) plus a one-line `@AGENTS.md` import into `CLAUDE.md`, and writes the fuller `USING_CODEINTEL.md` guide the block points to — into **your** repo, which is why there is no such file to click here — so an agent knows to reach for `code.query` before it reaches for grep, not just that a `CODE_INTEL.md` exists.
 - **A committed, diffable overview.** It lives *in the repo* — reviewable in a PR, browsable on GitHub, available offline. Re-run `codeintel map` after `codeintel index` to refresh it.
-- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything.
+- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything. The ranking counts `CALLS` edges into **callable** nodes only (functions, methods, classes, interfaces, routes), and skips test, generated and archived files. Both constraints are load-bearing rather than tidy-up: without them a 12,638-node TypeScript repo ranked `logger` (a *folder* node) at 716 and `onClick` at 107, and a Python repo ranked YAML and JSON keys — `flow` from a `.flow.yaml`, `feature` from a `.schema.json` — as its most depended-on symbols. This repo's own map is Python-heavy and barely showed it, which is exactly why dogfooding did not catch it.
 
 See **[docs/map-file.md](docs/map-file.md)** for the format and the `--inject` flow.
 
@@ -91,7 +93,7 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | Who calls this? | `callers` | graph | caller symbols + files |
 | What does this call? | `callees` | graph | callee symbols + files |
 | Blast radius of a change | `impact` | graph | callers **and** callees together |
-| Trace a call chain up/downstream | `chain` | graph | ordered, risk-labeled hops |
+| Trace a call chain up/downstream | `chain` | graph | ordered hops, each labelled with how it was resolved |
 | Find symbols by pattern | `pattern` | graph | matching nodes + locations |
 | Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
 | Everything about one symbol | `context` | graph + lsp | both views merged |
@@ -153,6 +155,57 @@ no benefit to set against that error rate.
 **Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
 `deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
 
+## An architecture model, as source
+
+`codeintel c4` turns the graph index into a [LikeC4](https://likec4.dev) model — architecture-as-code
+you can commit, diff and hand-edit, rather than a rendered picture you have to regenerate to read.
+Abridged output, from `--scope src/codeintel/providers`:
+
+```
+// Generated by codeintel from the graph index — do not edit by hand.
+// edges: union of IMPORTS (static module-level imports) and CALLS|USAGE (call/usage references)
+// coverage is NOT complete: dispatch through a name/lookup table can still be invisible to both
+// hotspot ranking uses IMPORTS-only fan-in, never the CALLS|USAGE union
+
+model {
+  src = area 'src' {
+    codeintel = area 'codeintel' {
+      providers = area 'providers' {
+        lsp = module 'lsp' {
+          technology 'Python'
+          metadata { path 'src/codeintel/providers/lsp.py'  churn '12'  fan_out '2' }
+        }
+        graph = module 'graph' { /* … */ }
+      }
+    }
+  }
+
+  src.codeintel.providers.lsp -[calls_usage]-> src.codeintel.providers.graph { metadata { n '2' } }
+}
+```
+
+Directories become `area`, files become `module`, and every element carries its real path plus churn
+and fan-in as `metadata` — so the model is queryable, not only drawable. Each file opens with what it
+cannot know: which edge sources it used, that coverage is incomplete, and how many references were
+folded or dropped. `npx likec4 start codeintel-c4` renders it; nothing else here needs Node.
+
+**Two edge sources, and the choice matters more than it sounds.** The default unions static `IMPORTS`
+with `CALLS|USAGE`, which recovers lazy and function-body imports. On this repo at
+`--scope src --depth 3` that is 179 relations — **134 of them `CALLS|USAGE`-only**, which renders as a
+hairball. `--edges imports` leaves the same 45 elements with 45 edges: legible, and roughly layered,
+because every remaining edge descends.
+
+**It also answers two questions without drawing anything.** `--layers` infers architectural bands
+from the import graph — 7 bands over 35 of those 45 elements, the other 10 having no module-level
+import edge either way. `--check` gates CI on a declared
+`[layers]` block in `.codeintel.toml`, exiting **2** on architectural drift — deliberately distinct
+from exit 1 for a broken run, so a CI step can tell "your architecture drifted" from "codeintel is
+broken". A config generated by `--suggest-config` is a *provably* green baseline on the commit that
+produced it, so adoption is paste-confirm-tighten rather than a wall of false positives.
+
+Full reference: **[docs/c4.md](docs/c4.md)**. Why LikeC4 and not something else, measured:
+[docs/eval-2026-08-26-likec4.md](docs/eval-2026-08-26-likec4.md).
+
 ## What makes it good
 
 - **Local-first and private.** One process on your machine — no cloud service, no API keys, no telemetry, no per-query network. Safe to point at a private repo, even with `--engine all`. (The one-time exception: `fastembed` downloads its embedding model once, then runs fully offline.)
@@ -281,7 +334,7 @@ Then it launches the exact command it registered and drives a real MCP handshake
 ```text
 v claude: registered at /Users/you/.claude.json
 
-v verified: codeintel 0.21.0 — 4 tools (code.query, code.status, code.doctor, code.map)
+v verified: codeintel 0.23.0 — 4 tools (code.query, code.status, code.doctor, code.map)
 ```
 
 If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
@@ -343,7 +396,7 @@ The optional keys are the ones worth reading when an answer surprises you:
 
 | Engine | Key ops | Install prereq |
 |---|---|---|
-| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` **0.9.x** on PATH (`pip install 'codebase-memory-mcp==0.9.*'`) — 0.10.x changed its response format and returns nothing for every op but resolution; see [docs/graph.md](docs/graph.md) |
+| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` **0.9.x or 0.10.x** on PATH — both wire dialects are read; `0.10.x` is the more accurate backend and is recommended (`pip install 'codebase-memory-mcp==0.10.*'`). See [docs/graph.md](docs/graph.md) |
 | `lsp` | `symbol`, `overview`, `context` | `uvx` on PATH — serena is fetched from GitHub on first use; see [docs/lsp.md](docs/lsp.md) |
 | `semantic` | `search`, `context` | `fastembed` + `sqlite-vec` (installed with the package) — see [docs/semantic.md](docs/semantic.md) |
 
@@ -396,7 +449,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 |---|---|
 | `codeintel help` | Every command grouped by task, with descriptions and examples (also the bare `codeintel`). A mistyped command suggests what you meant. |
 | `codeintel install [--agent auto\|claude\|codex\|gemini\|zed\|all] [--no-verify] [--relative-command]` | Register codeintel with the agents installed on this machine (`auto`, the default), then prove it by completing a real MCP handshake against the registered command |
-| `codeintel setup [project_root] [--all] [--index] [--warm] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
+| `codeintel setup [project_root] [--all] [--index] [--warm] [--languages] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
 | `codeintel prompt [project_root] [--agent auto\|claude\|codex\|gemini\|zed] [--fresh] [--deep]` | Print a paste-to-your-agent setup prompt; probes health and emits only the outstanding steps (or "just restart me" when already healthy). `--fresh` = the full sequence from `pip install`, to send a friend |
 | `codeintel index [project_root] [--quiet]` | Index a repo (semantic embeddings + best-effort graph & map refresh), with a live progress display; `--quiet` prints only the result line |
 | `codeintel serve` | Start the MCP server (stdio transport) |
@@ -406,7 +459,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
-| `codeintel c4 [project_root] [--out DIR] [--depth N] [--scope PATH] [--include-tests] [--no-index] [--json]` | Write a LikeC4 architecture model (`.c4`) of the repo's file/directory structure and its import graph — committable, diffable, hand-editable source rather than a rendered picture. Indexes the repo first if it has no graph index. See [docs/c4.md](docs/c4.md) |
+| `codeintel c4 [project_root] [--out DIR] [--depth N] [--scope PATH] [--include-tests] [--no-index] [--edges union\|imports] [--json] [--layers] [--suggest-config] [--check] [--layers-from auto\|inferred\|declared]` | Write a LikeC4 architecture model (`.c4`) of the repo's files and import graph. Indexes the repo first if it has no graph index. `--edges imports` drops the lower-confidence edges for a legible diagram; `--layers` reports inferred architectural bands; `--check` gates CI on a declared `[layers]` config, exit 2 on drift. See [An architecture model, as source](#an-architecture-model-as-source) and [docs/c4.md](docs/c4.md) |
 | `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear this repo's index — **both** semantic and graph — so it's as if never indexed; `--all` wipes every repo. Recovers from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
@@ -646,7 +699,7 @@ cd codeintel
 pip install -e .[dev]
 
 pytest tests/ -q            # ~740 tests, ~30s; fails under 83% coverage
-ruff check src tests        # lint
+ruff check src tests bench  # lint
 mypy                        # types (src/ only)
 ```
 

{codecortex-0.21.0 → codecortex-0.23.0}/src/codecortex.egg-info/SOURCES.txt

@@ -12,6 +12,8 @@ src/codeintel/__main__.py
 src/codeintel/agent_prompt.py
 src/codeintel/auth.py
 src/codeintel/c4.py
+src/codeintel/c4_check.py
+src/codeintel/c4_layers.py
 src/codeintel/cache.py
 src/codeintel/config.py
 src/codeintel/containment.py
@@ -25,6 +27,7 @@ src/codeintel/http_server.py
 src/codeintel/indexer.py
 src/codeintel/injector.py
 src/codeintel/installer.py
+src/codeintel/lang_config.py
 src/codeintel/loc.py
 src/codeintel/logconfig.py
 src/codeintel/mapper.py
@@ -72,7 +75,11 @@ src/codeintel/viewer/__init__.py
 src/codeintel/viewer/graph_template.html
 tests/test_agent_prompt.py
 tests/test_backend_reaper.py
+tests/test_bench_oracle.py
+tests/test_bench_oracle_ts.py
 tests/test_c4.py
+tests/test_c4_check.py
+tests/test_c4_layers.py
 tests/test_c4_model.py
 tests/test_c4_output.py
 tests/test_cache.py
@@ -97,6 +104,7 @@ tests/test_graph_provider.py
 tests/test_graph_real.py
 tests/test_graph_stdin.py
 tests/test_grapher.py
+tests/test_hard_exit.py
 tests/test_hardening.py
 tests/test_http_auth.py
 tests/test_http_server.py
@@ -105,6 +113,7 @@ tests/test_index_progress.py
 tests/test_indexer_binary.py
 tests/test_installer.py
 tests/test_integration.py
+tests/test_lang_config.py
 tests/test_loc_census.py
 tests/test_lsp_language_coverage.py
 tests/test_lsp_provider.py

{codecortex-0.21.0 → codecortex-0.23.0}/src/codecortex.egg-info/requires.txt

@@ -3,6 +3,9 @@ sqlite-vec>=0.1
 fastembed>=0.3
 tree-sitter-language-pack>=1.0
 
+[bench]
+anthropic>=0.40
+
 [dev]
 pytest>=8
 pytest-cov>=5

codecortex-0.23.0/src/codeintel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.23.0"

{codecortex-0.21.0 → codecortex-0.23.0}/src/codeintel/__main__.py

@@ -518,7 +518,36 @@ def build_parser() -> argparse.ArgumentParser:
     c4_parser.add_argument("--no-index", action="store_true",
                            help="Fail instead of indexing an un-indexed repo (default: index it "
                                 "first, so one command always produces a model)")
+    # The union is the default because it has higher recall; a lower-recall default would silently
+    # hide real dependencies from anyone who never read this flag. But the union is already excluded
+    # from hotspot ranking and layer inference, and it is 75% of the edges on this repo — so the
+    # diagram, the one artifact a human reads, needs a way to opt out.
+    c4_parser.add_argument("--edges", choices=["union", "imports"], default="union",
+                           help="Which edges enter the model: `union` (default — IMPORTS plus "
+                                "CALLS|USAGE, higher recall) or `imports` (static module-level "
+                                "imports only, far more legible on a large model)")
     c4_parser.add_argument("--json", action="store_true", help="Print the payload; write nothing")
+    # Phase 1 of the layer feature is inference only: `--layers` REPORTS the inferred bands, it does
+    # not add a view to the model. Named now rather than later so the flag does not change meaning
+    # between releases — a `--layers` that printed a summary in one version and emitted a diagram in
+    # the next would be the same flag doing two jobs.
+    c4_parser.add_argument("--layers", action="store_true",
+                           help="Print the inferred architectural layers (from IMPORTS only) and "
+                                "any import cycles. Reports; does not add a view to the model.")
+    c4_parser.add_argument("--suggest-config", action="store_true",
+                           help="Print a pasteable [layers] TOML block from the inferred ranks and "
+                                "write nothing — a green baseline on the tree that generated it")
+    # Exit 2, not 1. A CI step must be able to tell "codeintel is broken / the repo is not indexed"
+    # from "your architecture drifted": conflate them and the first person to hit a broken index
+    # allowlists the failure, and the gate is dead.
+    c4_parser.add_argument("--check", action="store_true",
+                           help="Check the declared [layers] config in .codeintel.toml and exit 2 "
+                                "on gating findings. Still writes the model. Exits 0 with a note if "
+                                "no [layers] block exists — nobody gets a wall they did not ask for.")
+    c4_parser.add_argument("--layers-from", choices=["auto", "inferred", "declared"], default="auto",
+                           help="Which ranking to report (default: auto — declared if a [layers] "
+                                "block exists, else inferred). `declared` exits 1 if none exists, so "
+                                "CI can assert that a config had better be present.")
 
     # doctor subcommand
     doctor_parser = subparsers.add_parser(
@@ -543,6 +572,12 @@ def build_parser() -> argparse.ArgumentParser:
     setup_parser.add_argument("--index", action="store_true",
                               help="Index this repo now (first run downloads the ~50MB model)")
     setup_parser.add_argument("--warm", action="store_true", help="Boot serena now (first run pulls it via uvx; slow)")
+    # Editing the user's serena config is a real side effect, so it needs its own flag — `run_setup`'s
+    # rule is that each flag IS consent. Without it the step still runs and reports what it WOULD do.
+    setup_parser.add_argument("--languages", action="store_true",
+                              help="Add every language this repo contains to `language_servers:` in "
+                                   ".serena/project.yml, so the LSP engine stops silently returning "
+                                   "nothing for the languages serena was not configured to serve")
     setup_parser.add_argument("--json", action="store_true", help="Emit the structured JSON report")
 
     # prompt subcommand