roam-code 12.7.0__tar.gz → 12.8.0__tar.gz

{roam_code-12.7.0/src/roam_code.egg-info → roam_code-12.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.7.0
+Version: 12.8.0
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: MIT
@@ -60,9 +60,11 @@ Dynamic: license-file
 
 # roam-code
 
-**The architectural intelligence layer for AI coding agents. Structural graph, architecture governance, multi-agent orchestration, vulnerability mapping, runtime analysis -- one CLI, zero API keys.**
+**Architectural sight for AI coding agents — before they edit.**
 
-*152 commands · 118 MCP tools · 27 languages · 100% local*
+A local code graph (SQLite + tree-sitter + git history) that gives any agent — Claude Code, Cursor, Aider, Continue, your own — five high-leverage verbs: `understand`, `retrieve`, `context`, `preflight`, `critique`. The other 148 specialised commands are advanced surface for specialised workflows.
+
+*154 commands · 120 MCP tools · 27 languages · 100% local · zero API keys*
 
 [![PyPI version](https://img.shields.io/pypi/v/roam-code?style=flat-square&color=blue)](https://pypi.org/project/roam-code/)
 [![GitHub stars](https://img.shields.io/github/stars/Cranot/roam-code?style=flat-square)](https://github.com/Cranot/roam-code/stargazers)
@@ -81,7 +83,7 @@ Roam is a structural intelligence engine for software. It pre-indexes your codeb
 Unlike LSPs (editor-bound, language-specific) or Sourcegraph (hosted search), Roam provides architecture-level graph queries -- offline, cross-language, and compact. It goes beyond comprehension: Roam governs architecture through budget gates, simulates refactoring outcomes, orchestrates multi-agent swarms with zero-conflict guarantees, maps vulnerability reachability paths, and enables graph-level code editing without syntax errors.
 
 ```
-Codebase ──> [Index] ──> Semantic Graph ──> 139 Commands ──> AI Agent
+Codebase ──> [Index] ──> Semantic Graph ──> 152 Commands ──> AI Agent
               │              │                  │
            tree-sitter    symbols            comprehend
            27 languages   + edges            govern
@@ -89,6 +91,21 @@ Codebase ──> [Index] ──> Semantic Graph ──> 139 Commands ──> AI
            runtime traces + architecture     orchestrate
 ```
 
+### Start here — the 5 verbs that cover ~80% of agent workflows
+
+```bash
+pip install roam-code
+
+cd your-repo/
+roam understand                       # 1. landing pad — what is this codebase?
+roam retrieve "where is auth?"        # 2. graph-aware retrieval for free-form tasks
+roam context AuthService              # 3. exact files+lines to read before changing
+roam preflight AuthService            # 4. blast radius + tests + complexity check
+git diff | roam critique              # 5. patch verifier — clones-not-edited, hot-path
+```
+
+That's the full mental model. The other CLI surface — `taint`, `fleet`, `cga`, `simulate`, `mutate`, `partition`, `attest`, `eval-retrieve`, `oracle`, `py-types`, `py-modern`, `dark-matter`, `clones`, `propagation`, `fingerprint`, etc. — is advanced surface for specialised workflows; you'll never need most of them.
+
 ### The problem
 
 Coding agents explore codebases inefficiently: dozens of grep/read cycles, high token cost, no structural understanding. Roam replaces this with one graph query:
@@ -139,7 +156,7 @@ $ roam diff                    # blast radius of uncommitted changes
 - **`personalized_pagerank()`** in `graph/pagerank.py`: NetworkX `personalization=` wrapper with empty-seed fallback to global PR; biases ranking toward query-relevant nodes for the retrieve reranker.
 - **`.roam/config.toml`** (new): zero-dep TOML loader (stdlib `tomllib` → `tomli` → in-tree subset parser). Tunable retrieve weights (`alpha`/`beta`/`gamma`/`delta`/`epsilon`), `tokens_per_line`, `lexical_baseline`, `first_stage_token_cap`, `default_budget`, `default_k`, `default_rerank`.
 - **DX corrections from dogfood pass**: `roam --detail <cmd>` is the canonical group-level flag; misleading "use --detail" hints in 7 commands rewritten to point users at `roam --detail <cmd>`. `--top N` aliased on `complexity`/`algo`/`rules` (`--top 0` means unlimited on `rules`). `roam fingerprint` no longer refuses graphs ≥5,000 symbols (new soft-warn threshold 20k, hard cap 100k).
-- **152 CLI commands, 118 MCP tools** (`fleet`, `ask`, `taint`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`) and `roam_taint_classify` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
+- **154 CLI commands, 120 MCP tools** (`fleet`, `ask`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`), `roam_taint_classify`, `roam_pytest_fixtures`, and `roam_hover` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
 
 ## What's New in v11
 
@@ -310,7 +327,7 @@ roam health
 
 ## Commands
 
-**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 147 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **152 commands organised into 7 categories**, but you don't need to know that to start.
+**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 149 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **154 commands organised into 7 categories**, but you don't need to know that to start.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -349,6 +366,7 @@ roam health
 | `roam file <path> [--full] [--changed] [--deps-of PATH]` | File skeleton: all definitions with signatures, cognitive load index, health score |
 | `roam symbol <name> [--full]` | Symbol definition + callers + callees + metrics. Supports `file:symbol` disambiguation |
 | `roam context <symbol> [--task MODE] [--for-file PATH]` | AI-optimized context: definition + callers + callees + files-to-read with line ranges |
+| `roam hover <symbol>` | One-line architectural summary: kind, location, blast-radius bucket, top caller, top callee. Bounded at ~200 tokens for IDE hover panels |
 | `roam retrieve <task> [--budget N] [--k N] [--seed-files PATH]` | Graph-aware context for free-form tasks: FTS5 + structural rerank (PageRank + clones) + token budget |
 | `roam critique [--input DIFF] [--intent TEXT] [--high-callers N]` | Verify a patch against the graph: clones-not-edited + blast radius + intent-vs-semantic-diff. Pipe `git diff` in. Exit 5 on high severity. |
 | `roam fleet plan <goal> [--n-agents N] [--adapter raw\|composio\|copilot]` | Graph-aware planner: Louvain partition + co-change + PageRank anchors → `.roam-fleet.json` for Composio/Copilot CLI/raw. |
@@ -402,6 +420,7 @@ roam health
 | `roam complexity [--bumpy-road] [--include-tooling]` | Per-function cognitive complexity (SonarSource-compatible, triangular nesting penalty) + Halstead metrics (volume, difficulty, effort, bugs) + cyclomatic density |
 | `roam py-types [--detail] [--include-tests] [--ci --min-coverage N]` | Python type-annotation health: % of public functions with full annotations, ``Any`` usage, legacy ``typing.Optional/Dict/List`` (PEP 585/604 modernisation candidates), per-file worst offenders. CI-gateable via ``--ci --min-coverage N`` (exit 5 below threshold). Default-excludes test files |
 | `roam py-modern [--detail]` | Modern-Python adoption signal: counts walrus operator (PEP 572), match statements (PEP 634), PEP 604 ``X \| None``, PEP 585 ``dict[…]``, PEP 695 type aliases, f-strings vs ``.format()``. Reports type-modernisation % and f-string adoption % to gauge migration progress |
+| `roam pytest-fixtures [SYMBOL] [--max-depth N]` | Inventory pytest fixture chains. With no SYMBOL, prints the project-wide fixture count and the top fixtures by dependent count. With a fixture or test name, walks the implicit fixture-parameter dependency graph to show what each test transitively requires. Resolves through ``conftest.py`` chains |
 | `roam algo [--task T] [--confidence C] [--profile P]` | Algorithm anti-pattern detection: 23-pattern catalog detects suboptimal algorithms (O(n^2) loops, N+1 queries, quadratic string building, branching recursion, loop-invariant calls) and suggests better approaches with Big-O improvements. Confidence calibration via caller-count + runtime traces, evidence paths, impact scoring, framework-aware N+1 packs, and language-aware fix templates. Alias: `roam math` |
 | `roam n1 [--confidence C] [--verbose]` | Implicit N+1 I/O detection: finds ORM model computed properties (`$appends`/accessors) that trigger lazy-loaded DB queries in collection contexts. Cross-references with eager loading config. Supports Laravel, Django, Rails, SQLAlchemy, JPA |
 | `roam over-fetch [--threshold N] [--confidence C]` | Detect models serializing too many fields: large `$fillable` without `$hidden`/`$visible`, direct controller returns bypassing API Resources, poor exposed-to-hidden ratio |
@@ -654,7 +673,7 @@ The sentinel pair `<!-- roam:minimap -->` / `<!-- /roam:minimap -->` is replaced
 |--------|-------------|
 | `roam --json <command>` | Structured JSON output with consistent envelope |
 | `roam --compact <command>` | Token-efficient output: TSV tables, minimal JSON envelope |
-| `roam --sarif <command>` | SARIF 2.1.0 output for dead, health, complexity, rules, secrets, and algo (GitHub/CI integration) |
+| `roam --sarif <command>` | SARIF 2.1.0 output for dead, health, complexity, rules, secrets, algo, py-types, py-modern (GitHub/CI integration) |
 | `roam health --gate` | CI quality gate. Reads `.roam-gates.yml` thresholds. Exit code 5 on failure |
 
 </details>
@@ -950,7 +969,7 @@ ROAM_MCP_LITE=0 roam mcp
 Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`, `roam_complete`, `roam_complexity_report`, `roam_context`, `roam_dead_code`, `roam_deps`, `roam_diagnose`, `roam_diagnose_issue`, `roam_diff`, `roam_expand_toolset`, `roam_explore`, `roam_file_info`, `roam_health`, `roam_impact`, `roam_pr_risk`, `roam_preflight`, `roam_prepare_change`, `roam_review_change`, `roam_search_symbol`, `roam_syntax_check`, `roam_trace`, `roam_understand`, `roam_uses`.
 
 <details>
-<summary><strong>MCP tool list (all 118)</strong></summary>
+<summary><strong>MCP tool list (all 120)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
@@ -961,6 +980,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_search_symbol` | Find symbols by name |
 | `roam_complete` | Prefix completion for symbols/paths/commands (FTS5-backed) |
 | `roam_context` | Files-to-read for modifying a symbol |
+| `roam_hover` | Single-line architectural summary — kind, blast-radius bucket, top caller, top callee |
 | `roam_retrieve` | Graph-aware context for free-form tasks (FTS5 + structural rerank + token budget) |
 | `roam_critique` | Verify a patch against the graph (clones-not-edited + blast radius) |
 | `roam_fleet_plan` | Plan a multi-agent fleet — graph-aware partition emits .roam-fleet.json |
@@ -984,6 +1004,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_complexity_report` | Per-symbol cognitive complexity |
 | `roam_py_types` | Python type-annotation health (% public typed, Any, legacy typing) |
 | `roam_py_modern` | Modern-Python adoption (walrus, match, PEP 604/585/695, f-strings) |
+| `roam_pytest_fixtures` | pytest fixture chain — top fixtures by dependent count, or per-symbol dependency walk |
 | `roam_tour` | Auto-generated onboarding guide |
 | `roam_diagnose` | Root cause analysis for debugging |
 | `roam_visualize` | Generate Mermaid or DOT architecture diagrams |

{roam_code-12.7.0 → roam_code-12.8.0}/README.md

@@ -2,9 +2,11 @@
 
 # roam-code
 
-**The architectural intelligence layer for AI coding agents. Structural graph, architecture governance, multi-agent orchestration, vulnerability mapping, runtime analysis -- one CLI, zero API keys.**
+**Architectural sight for AI coding agents — before they edit.**
 
-*152 commands · 118 MCP tools · 27 languages · 100% local*
+A local code graph (SQLite + tree-sitter + git history) that gives any agent — Claude Code, Cursor, Aider, Continue, your own — five high-leverage verbs: `understand`, `retrieve`, `context`, `preflight`, `critique`. The other 148 specialised commands are advanced surface for specialised workflows.
+
+*154 commands · 120 MCP tools · 27 languages · 100% local · zero API keys*
 
 [![PyPI version](https://img.shields.io/pypi/v/roam-code?style=flat-square&color=blue)](https://pypi.org/project/roam-code/)
 [![GitHub stars](https://img.shields.io/github/stars/Cranot/roam-code?style=flat-square)](https://github.com/Cranot/roam-code/stargazers)
@@ -23,7 +25,7 @@ Roam is a structural intelligence engine for software. It pre-indexes your codeb
 Unlike LSPs (editor-bound, language-specific) or Sourcegraph (hosted search), Roam provides architecture-level graph queries -- offline, cross-language, and compact. It goes beyond comprehension: Roam governs architecture through budget gates, simulates refactoring outcomes, orchestrates multi-agent swarms with zero-conflict guarantees, maps vulnerability reachability paths, and enables graph-level code editing without syntax errors.
 
 ```
-Codebase ──> [Index] ──> Semantic Graph ──> 139 Commands ──> AI Agent
+Codebase ──> [Index] ──> Semantic Graph ──> 152 Commands ──> AI Agent
               │              │                  │
            tree-sitter    symbols            comprehend
            27 languages   + edges            govern
@@ -31,6 +33,21 @@ Codebase ──> [Index] ──> Semantic Graph ──> 139 Commands ──> AI
            runtime traces + architecture     orchestrate
 ```
 
+### Start here — the 5 verbs that cover ~80% of agent workflows
+
+```bash
+pip install roam-code
+
+cd your-repo/
+roam understand                       # 1. landing pad — what is this codebase?
+roam retrieve "where is auth?"        # 2. graph-aware retrieval for free-form tasks
+roam context AuthService              # 3. exact files+lines to read before changing
+roam preflight AuthService            # 4. blast radius + tests + complexity check
+git diff | roam critique              # 5. patch verifier — clones-not-edited, hot-path
+```
+
+That's the full mental model. The other CLI surface — `taint`, `fleet`, `cga`, `simulate`, `mutate`, `partition`, `attest`, `eval-retrieve`, `oracle`, `py-types`, `py-modern`, `dark-matter`, `clones`, `propagation`, `fingerprint`, etc. — is advanced surface for specialised workflows; you'll never need most of them.
+
 ### The problem
 
 Coding agents explore codebases inefficiently: dozens of grep/read cycles, high token cost, no structural understanding. Roam replaces this with one graph query:
@@ -81,7 +98,7 @@ $ roam diff                    # blast radius of uncommitted changes
 - **`personalized_pagerank()`** in `graph/pagerank.py`: NetworkX `personalization=` wrapper with empty-seed fallback to global PR; biases ranking toward query-relevant nodes for the retrieve reranker.
 - **`.roam/config.toml`** (new): zero-dep TOML loader (stdlib `tomllib` → `tomli` → in-tree subset parser). Tunable retrieve weights (`alpha`/`beta`/`gamma`/`delta`/`epsilon`), `tokens_per_line`, `lexical_baseline`, `first_stage_token_cap`, `default_budget`, `default_k`, `default_rerank`.
 - **DX corrections from dogfood pass**: `roam --detail <cmd>` is the canonical group-level flag; misleading "use --detail" hints in 7 commands rewritten to point users at `roam --detail <cmd>`. `--top N` aliased on `complexity`/`algo`/`rules` (`--top 0` means unlimited on `rules`). `roam fingerprint` no longer refuses graphs ≥5,000 symbols (new soft-warn threshold 20k, hard cap 100k).
-- **152 CLI commands, 118 MCP tools** (`fleet`, `ask`, `taint`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`) and `roam_taint_classify` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
+- **154 CLI commands, 120 MCP tools** (`fleet`, `ask`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`), `roam_taint_classify`, `roam_pytest_fixtures`, and `roam_hover` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
 
 ## What's New in v11
 
@@ -252,7 +269,7 @@ roam health
 
 ## Commands
 
-**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 147 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **152 commands organised into 7 categories**, but you don't need to know that to start.
+**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 149 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **154 commands organised into 7 categories**, but you don't need to know that to start.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -291,6 +308,7 @@ roam health
 | `roam file <path> [--full] [--changed] [--deps-of PATH]` | File skeleton: all definitions with signatures, cognitive load index, health score |
 | `roam symbol <name> [--full]` | Symbol definition + callers + callees + metrics. Supports `file:symbol` disambiguation |
 | `roam context <symbol> [--task MODE] [--for-file PATH]` | AI-optimized context: definition + callers + callees + files-to-read with line ranges |
+| `roam hover <symbol>` | One-line architectural summary: kind, location, blast-radius bucket, top caller, top callee. Bounded at ~200 tokens for IDE hover panels |
 | `roam retrieve <task> [--budget N] [--k N] [--seed-files PATH]` | Graph-aware context for free-form tasks: FTS5 + structural rerank (PageRank + clones) + token budget |
 | `roam critique [--input DIFF] [--intent TEXT] [--high-callers N]` | Verify a patch against the graph: clones-not-edited + blast radius + intent-vs-semantic-diff. Pipe `git diff` in. Exit 5 on high severity. |
 | `roam fleet plan <goal> [--n-agents N] [--adapter raw\|composio\|copilot]` | Graph-aware planner: Louvain partition + co-change + PageRank anchors → `.roam-fleet.json` for Composio/Copilot CLI/raw. |
@@ -344,6 +362,7 @@ roam health
 | `roam complexity [--bumpy-road] [--include-tooling]` | Per-function cognitive complexity (SonarSource-compatible, triangular nesting penalty) + Halstead metrics (volume, difficulty, effort, bugs) + cyclomatic density |
 | `roam py-types [--detail] [--include-tests] [--ci --min-coverage N]` | Python type-annotation health: % of public functions with full annotations, ``Any`` usage, legacy ``typing.Optional/Dict/List`` (PEP 585/604 modernisation candidates), per-file worst offenders. CI-gateable via ``--ci --min-coverage N`` (exit 5 below threshold). Default-excludes test files |
 | `roam py-modern [--detail]` | Modern-Python adoption signal: counts walrus operator (PEP 572), match statements (PEP 634), PEP 604 ``X \| None``, PEP 585 ``dict[…]``, PEP 695 type aliases, f-strings vs ``.format()``. Reports type-modernisation % and f-string adoption % to gauge migration progress |
+| `roam pytest-fixtures [SYMBOL] [--max-depth N]` | Inventory pytest fixture chains. With no SYMBOL, prints the project-wide fixture count and the top fixtures by dependent count. With a fixture or test name, walks the implicit fixture-parameter dependency graph to show what each test transitively requires. Resolves through ``conftest.py`` chains |
 | `roam algo [--task T] [--confidence C] [--profile P]` | Algorithm anti-pattern detection: 23-pattern catalog detects suboptimal algorithms (O(n^2) loops, N+1 queries, quadratic string building, branching recursion, loop-invariant calls) and suggests better approaches with Big-O improvements. Confidence calibration via caller-count + runtime traces, evidence paths, impact scoring, framework-aware N+1 packs, and language-aware fix templates. Alias: `roam math` |
 | `roam n1 [--confidence C] [--verbose]` | Implicit N+1 I/O detection: finds ORM model computed properties (`$appends`/accessors) that trigger lazy-loaded DB queries in collection contexts. Cross-references with eager loading config. Supports Laravel, Django, Rails, SQLAlchemy, JPA |
 | `roam over-fetch [--threshold N] [--confidence C]` | Detect models serializing too many fields: large `$fillable` without `$hidden`/`$visible`, direct controller returns bypassing API Resources, poor exposed-to-hidden ratio |
@@ -596,7 +615,7 @@ The sentinel pair `<!-- roam:minimap -->` / `<!-- /roam:minimap -->` is replaced
 |--------|-------------|
 | `roam --json <command>` | Structured JSON output with consistent envelope |
 | `roam --compact <command>` | Token-efficient output: TSV tables, minimal JSON envelope |
-| `roam --sarif <command>` | SARIF 2.1.0 output for dead, health, complexity, rules, secrets, and algo (GitHub/CI integration) |
+| `roam --sarif <command>` | SARIF 2.1.0 output for dead, health, complexity, rules, secrets, algo, py-types, py-modern (GitHub/CI integration) |
 | `roam health --gate` | CI quality gate. Reads `.roam-gates.yml` thresholds. Exit code 5 on failure |
 
 </details>
@@ -892,7 +911,7 @@ ROAM_MCP_LITE=0 roam mcp
 Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`, `roam_complete`, `roam_complexity_report`, `roam_context`, `roam_dead_code`, `roam_deps`, `roam_diagnose`, `roam_diagnose_issue`, `roam_diff`, `roam_expand_toolset`, `roam_explore`, `roam_file_info`, `roam_health`, `roam_impact`, `roam_pr_risk`, `roam_preflight`, `roam_prepare_change`, `roam_review_change`, `roam_search_symbol`, `roam_syntax_check`, `roam_trace`, `roam_understand`, `roam_uses`.
 
 <details>
-<summary><strong>MCP tool list (all 118)</strong></summary>
+<summary><strong>MCP tool list (all 120)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
@@ -903,6 +922,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_search_symbol` | Find symbols by name |
 | `roam_complete` | Prefix completion for symbols/paths/commands (FTS5-backed) |
 | `roam_context` | Files-to-read for modifying a symbol |
+| `roam_hover` | Single-line architectural summary — kind, blast-radius bucket, top caller, top callee |
 | `roam_retrieve` | Graph-aware context for free-form tasks (FTS5 + structural rerank + token budget) |
 | `roam_critique` | Verify a patch against the graph (clones-not-edited + blast radius) |
 | `roam_fleet_plan` | Plan a multi-agent fleet — graph-aware partition emits .roam-fleet.json |
@@ -926,6 +946,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_complexity_report` | Per-symbol cognitive complexity |
 | `roam_py_types` | Python type-annotation health (% public typed, Any, legacy typing) |
 | `roam_py_modern` | Modern-Python adoption (walrus, match, PEP 604/585/695, f-strings) |
+| `roam_pytest_fixtures` | pytest fixture chain — top fixtures by dependent count, or per-symbol dependency walk |
 | `roam_tour` | Auto-generated onboarding guide |
 | `roam_diagnose` | Root cause analysis for debugging |
 | `roam_visualize` | Generate Mermaid or DOT architecture diagrams |

{roam_code-12.7.0 → roam_code-12.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roam-code"
-version = "12.7.0"
+version = "12.8.0"
 description = "Instant codebase comprehension for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -130,7 +130,6 @@ ignore = [
     "E501",   # line-too-long — handled by ruff format; remaining are long strings/SQL
     "E731",   # lambda-assignment — used for concise dispatch tables
     "E741",   # ambiguous variable names (G, l, etc.) — common in graph code
-    "F841",   # unused-variable — often intentional destructuring
 ]
 
 [tool.ruff.lint.per-file-ignores]

{roam_code-12.7.0 → roam_code-12.8.0}/src/roam/ask/recipes.py

@@ -240,6 +240,28 @@ RECIPES: list[Recipe] = [
             "attack-surface review. Failures gate-able in CI via exit 5."
         ),
     ),
+    Recipe(
+        name="fixture-impact",
+        intent=(
+            "Show what tests / fixtures break if a pytest fixture is renamed, removed, or has its return shape changed"
+        ),
+        examples=(
+            "if I rename cli_runner what tests break",
+            "what depends on the cli_runner fixture",
+            "who uses indexed_project",
+            "blast radius of indexed_project",
+            "find tests that consume mock_db_session",
+        ),
+        keywords=("fixture", "fixtures", "pytest", "conftest"),
+        commands=(("pytest-fixtures", ("{symbol}", "--reverse")),),
+        summary=(
+            "Walks the implicit pytest fixture-parameter dependency graph "
+            "in reverse — fixtures and tests that consume the named fixture "
+            "transitively. Pass the fixture name as an identifier (snake_case "
+            "or PascalCase). ``--json`` for the full list when output is "
+            "capped."
+        ),
+    ),
     Recipe(
         name="dead-code-sweep",
         intent="Find unused or unreachable symbols ready for deletion",

{roam_code-12.7.0 → roam_code-12.8.0}/src/roam/catalog/python_idioms.py

@@ -210,19 +210,46 @@ def _project_root_for_conn(conn: sqlite3.Connection) -> str:
     return parent
 
 
+# Per-process cache of file-text reads. With 19 detectors each calling
+# ``_file_text`` per file, an uncached implementation does 19×N disk
+# reads. Cache keyed by ``(id(conn), file_id)`` so distinct DB
+# connections don't collide. Cleared at module unload (or via
+# ``_clear_file_text_cache()`` in tests). Bounded in size at 4096
+# entries to avoid unbounded growth on huge repos; LRU-evicted.
+from collections import OrderedDict as _OrderedDict
+
+_FILE_TEXT_CACHE: _OrderedDict = _OrderedDict()
+_FILE_TEXT_CACHE_MAX = 4096
+
+
+def _clear_file_text_cache() -> None:
+    """Clear the file-text cache. Call from tests that want clean state."""
+    _FILE_TEXT_CACHE.clear()
+
+
 def _file_text(conn: sqlite3.Connection, file_id: int) -> str | None:
     """Read the source text of a file via roam.index — but the index
     doesn't store source. Instead we read from disk via the file path
     resolved against the project root (paths in the index are
     project-relative, so a bare ``open(path)`` fails when the caller
     isn't sitting at the project root).
-    Fast (mmap) and safe to no-op on read errors.
+
+    Caches results across calls within a process so all 19+ detectors
+    pay the disk read once per file rather than 19+ times.
     """
+    cache_key = (id(conn), file_id)
+    cached = _FILE_TEXT_CACHE.get(cache_key)
+    if cached is not None:
+        # LRU bump
+        _FILE_TEXT_CACHE.move_to_end(cache_key)
+        return cached if cached != "" else None  # sentinel for "tried, failed"
     row = conn.execute("SELECT path FROM files WHERE id = ?", (file_id,)).fetchone()
     if row is None:
+        _FILE_TEXT_CACHE[cache_key] = ""
         return None
     path = row[0]
     if not path:
+        _FILE_TEXT_CACHE[cache_key] = ""
         return None
     # Resolve project-relative path via the DB's location.
     root = _project_root_for_conn(conn)
@@ -233,9 +260,15 @@ def _file_text(conn: sqlite3.Connection, file_id: int) -> str | None:
             path = _osp.join(root, path)
     try:
         with open(path, encoding="utf-8", errors="replace") as f:
-            return f.read()
+            text = f.read()
     except OSError:
+        _FILE_TEXT_CACHE[cache_key] = ""
         return None
+    _FILE_TEXT_CACHE[cache_key] = text
+    # LRU eviction
+    if len(_FILE_TEXT_CACHE) > _FILE_TEXT_CACHE_MAX:
+        _FILE_TEXT_CACHE.popitem(last=False)
+    return text
 
 
 # Triple-quoted strings (greedy across newlines), single/double quoted
@@ -250,27 +283,39 @@ _SINGLE_QUOTE_RE = re.compile(r'("(?:\\.|[^"\\\n])*"|\'(?:\\.|[^\'\\\n])*\')')
 _COMMENT_RE = re.compile(r"#[^\n]*")
 
 
+_STRIP_CACHE: _OrderedDict = _OrderedDict()
+_STRIP_CACHE_MAX = 4096
+
+
 def _strip_strings_and_comments(text: str) -> str:
     """Replace strings + comments with same-length whitespace so the
     detector regexes don't false-match inside docstrings or comments.
 
     Length-preserving so ``text.count("\n", 0, match.start())`` still
-    yields the original line number. Test the dogfood case:
-    ``r"def\\s+\\w+\\s*\\(...."`` regex source no longer trips
-    ``_MUTABLE_DEFAULT_RE`` when it scans python_idioms.py itself.
+    yields the original line number. Cached because all detectors
+    that strip apply the same transform — without caching we re-strip
+    once per detector per file.
     """
     if not text:
         return text
+    # Cache key: id() of the original string (CPython gives unique
+    # ids while alive). Combined with len() to catch the rare case
+    # of id-reuse after string GC.
+    key = (id(text), len(text))
+    cached = _STRIP_CACHE.get(key)
+    if cached is not None:
+        _STRIP_CACHE.move_to_end(key)
+        return cached
 
     def _blank(match: re.Match) -> str:
-        # Preserve newlines — re-blanking with spaces would collapse
-        # multi-line docstrings into one logical line for downstream
-        # regexes that use ``^`` / ``$`` anchors.
         return "".join(" " if c != "\n" else "\n" for c in match.group(0))
 
     out = _TRIPLE_QUOTE_RE.sub(_blank, text)
     out = _SINGLE_QUOTE_RE.sub(_blank, out)
     out = _COMMENT_RE.sub(_blank, out)
+    _STRIP_CACHE[key] = out
+    if len(_STRIP_CACHE) > _STRIP_CACHE_MAX:
+        _STRIP_CACHE.popitem(last=False)
     return out
 
 
@@ -932,12 +977,25 @@ def detect_django_n1(conn: sqlite3.Connection) -> list[dict]:
             text = _strip_strings_and_comments(text)
         if not text:
             continue
-        # Quick reject: skip files with no Django ORM hints
-        if ".objects." not in text and ".all()" not in text:
+        # Require a Django ORM hint anywhere in the file. Without
+        # ``.objects.`` (the manager indicator) or an explicit Django
+        # import, a ``.all()`` shape might be a custom collection or a
+        # different ORM — firing would be a false positive.
+        has_django_hint = ".objects." in text or "from django" in text or "import django" in text
+        if not has_django_hint:
             continue
         sym_index = _line_to_symbol(conn, file_id)
         for match in _DJANGO_ALL_THEN_FOR.finditer(text):
             line_no = text.count("\n", 0, match.start()) + 1
+            # Suppress when the queryset chain already eager-loads via
+            # select_related or prefetch_related. Look back from the
+            # ``.all()`` call to the assignment (or 200 chars max) for
+            # those calls. They defuse the N+1 — firing here would be a
+            # false positive.
+            chain_start = max(0, match.start() - 200)
+            chain = text[chain_start : match.start()]
+            if "select_related(" in chain or "prefetch_related(" in chain:
+                continue
             sym = _enclosing_symbol(line_no, sym_index)
             if sym is None:
                 continue
@@ -1013,6 +1071,19 @@ def detect_sqlalchemy_lazy(conn: sqlite3.Connection) -> list[dict]:
         sym_index = _line_to_symbol(conn, file_id)
         for match in _SQLALCHEMY_ALL_THEN_DOT.finditer(text):
             line_no = text.count("\n", 0, match.start()) + 1
+            # Suppress when the query expression already eager-loads via
+            # joinedload / selectinload / contains_eager. Look back from
+            # the ``.all()`` call to the start of the statement (or 200
+            # chars, whichever is shorter).
+            chain_start = max(0, match.start() - 200)
+            chain = text[chain_start : match.start()]
+            if (
+                "joinedload(" in chain
+                or "selectinload(" in chain
+                or "contains_eager(" in chain
+                or "subqueryload(" in chain
+            ):
+                continue
             sym = _enclosing_symbol(line_no, sym_index)
             if sym is None:
                 continue

{roam_code-12.7.0 → roam_code-12.8.0}/src/roam/cli.py

@@ -56,6 +56,8 @@ _COMMANDS = {
     "complexity": ("roam.commands.cmd_complexity", "complexity"),
     "py-types": ("roam.commands.cmd_py_types", "py_types"),
     "py-modern": ("roam.commands.cmd_py_modern", "py_modern"),
+    "pytest-fixtures": ("roam.commands.cmd_pytest_fixtures", "pytest_fixtures"),
+    "hover": ("roam.commands.cmd_hover", "hover"),
     "debt": ("roam.commands.cmd_debt", "debt"),
     "conventions": ("roam.commands.cmd_conventions", "conventions"),
     "bus-factor": ("roam.commands.cmd_bus_factor", "bus_factor"),
@@ -219,6 +221,7 @@ _CATEGORIES = {
         "verify-imports",
         "diff",
         "context",
+        "hover",
         "retrieve",
         "critique",
         "fleet",
@@ -245,6 +248,7 @@ _CATEGORIES = {
         "complexity",
         "py-types",
         "py-modern",
+        "pytest-fixtures",
         "algo",
         "n1",
         "over-fetch",

roam_code-12.8.0/src/roam/commands/cmd_hover.py

@@ -0,0 +1,130 @@
+"""``roam hover`` — single-line architectural summary suitable for an
+IDE hover panel or chat-inline reference.
+
+Designed to fit in ~200 tokens regardless of the symbol. Where ``roam
+context`` returns a full briefing (signature, callers, related files,
+tests, model fields, etc.), ``roam hover`` returns the minimum useful
+gloss: kind, qualified name, location, blast-radius bucket, top
+caller, top callee. Pairs with a hover-on-symbol IDE plugin.
+"""
+
+from __future__ import annotations
+
+import click
+
+from roam.commands.resolve import ensure_index, find_symbol, symbol_not_found
+from roam.db.connection import open_db
+from roam.output.formatter import abbrev_kind, json_envelope, loc, to_json
+
+
+def _blast_bucket(in_degree: int) -> str:
+    """Coarse classifier: how nervous should an editor be about
+    changing this symbol? Buckets match ``roam impact`` thresholds."""
+    if in_degree >= 50:
+        return "large"
+    if in_degree >= 10:
+        return "moderate"
+    if in_degree >= 1:
+        return "small"
+    return "none"
+
+
+def _top_neighbour(conn, sym_id: int, *, direction: str) -> dict | None:
+    """Highest-PageRank caller (direction='in') or callee (direction='out')."""
+    if direction == "in":
+        edge_clause = "e.target_id = ? AND s.id = e.source_id"
+    else:
+        edge_clause = "e.source_id = ? AND s.id = e.target_id"
+    rows = conn.execute(
+        f"""
+        SELECT s.id, s.name, s.qualified_name, s.kind, f.path AS file_path,
+               s.line_start, COALESCE(gm.pagerank, 0) AS pr
+        FROM edges e
+        JOIN symbols s ON {edge_clause}
+        JOIN files f ON s.file_id = f.id
+        LEFT JOIN graph_metrics gm ON gm.symbol_id = s.id
+        WHERE e.kind IN ('call', 'inherits', 'imports')
+        ORDER BY pr DESC
+        LIMIT 1
+        """,
+        (sym_id,),
+    ).fetchall()
+    if not rows:
+        return None
+    r = rows[0]
+    return {
+        "name": r["qualified_name"] or r["name"],
+        "kind": r["kind"],
+        "file_path": r["file_path"],
+        "line_start": r["line_start"],
+    }
+
+
+@click.command()
+@click.argument("symbol")
+@click.pass_context
+def hover(ctx, symbol: str):
+    """Show a one-line architectural summary for SYMBOL.
+
+    Output is bounded at ~200 tokens regardless of the symbol — kind,
+    qualified name, location, blast-radius bucket, top caller, top
+    callee. Designed for IDE hover panels and chat-inline references
+    where ``roam context`` is too verbose.
+    """
+    json_mode = ctx.obj.get("json") if ctx.obj else False
+    ensure_index()
+
+    with open_db(readonly=True) as conn:
+        sym = find_symbol(conn, symbol)
+        if sym is None:
+            click.echo(symbol_not_found(conn, symbol, json_mode=json_mode))
+            raise SystemExit(1)
+        sym_id = sym["id"]
+
+        metrics = conn.execute(
+            "SELECT in_degree, out_degree, pagerank FROM graph_metrics WHERE symbol_id = ?",
+            (sym_id,),
+        ).fetchone()
+        in_d = metrics["in_degree"] if metrics else 0
+        out_d = metrics["out_degree"] if metrics else 0
+        pr = float(metrics["pagerank"] or 0) if metrics else 0.0
+
+        bucket = _blast_bucket(in_d)
+        top_caller = _top_neighbour(conn, sym_id, direction="in")
+        top_callee = _top_neighbour(conn, sym_id, direction="out")
+
+    qn = sym["qualified_name"] or sym["name"]
+    file_loc = loc(sym["file_path"], sym["line_start"])
+    kind_short = abbrev_kind(sym["kind"])
+
+    if json_mode:
+        click.echo(
+            to_json(
+                json_envelope(
+                    "hover",
+                    summary={
+                        "verdict": (f"{kind_short} {qn} — {bucket} blast radius ({in_d} in, {out_d} out)"),
+                        "kind": sym["kind"],
+                        "qualified_name": qn,
+                        "file_path": sym["file_path"],
+                        "line_start": sym["line_start"],
+                        "in_degree": in_d,
+                        "out_degree": out_d,
+                        "pagerank": round(pr, 6),
+                        "blast_bucket": bucket,
+                    },
+                    top_caller=top_caller,
+                    top_callee=top_callee,
+                )
+            )
+        )
+        return
+
+    click.echo(f"{kind_short}  {qn}  {file_loc}")
+    click.echo(f"  blast radius: {bucket} ({in_d} callers, {out_d} callees, pr={pr:.4f})")
+    if top_caller:
+        c_loc = loc(top_caller["file_path"], top_caller["line_start"])
+        click.echo(f"  top caller:   {top_caller['name']}  {c_loc}")
+    if top_callee:
+        c_loc = loc(top_callee["file_path"], top_callee["line_start"])
+        click.echo(f"  top callee:   {top_callee['name']}  {c_loc}")

{roam_code-12.7.0 → roam_code-12.8.0}/src/roam/commands/cmd_preflight.py

@@ -196,6 +196,12 @@ def _check_blast_radius(conn, sym_ids, file_paths):
 # ---------------------------------------------------------------------------
 
 
+# Once the blast radius dumps every test file in the repo, the
+# "Suggested tests:" line stops being a suggestion and becomes a wall
+# of text. This cap is the boundary between actionable and unactionable.
+_MAX_SUGGESTED_TEST_FILES = 15
+
+
 def _check_affected_tests(conn, sym_ids, file_paths):
     """Find tests that need to run."""
     results = _gather_affected_tests(conn, sym_ids, file_paths)
@@ -212,7 +218,13 @@ def _check_affected_tests(conn, sym_ids, file_paths):
             seen.add(r["file"])
             test_files.append(r["file"])
 
-    pytest_cmd = "pytest " + " ".join(test_files) if test_files else ""
+    truncated_files = len(test_files) > _MAX_SUGGESTED_TEST_FILES
+    if truncated_files:
+        suggested = test_files[:_MAX_SUGGESTED_TEST_FILES]
+        suffix = f"  # (+{len(test_files) - _MAX_SUGGESTED_TEST_FILES} more)"
+        pytest_cmd = "pytest " + " ".join(suggested) + suffix
+    else:
+        pytest_cmd = "pytest " + " ".join(test_files) if test_files else ""
     severity = _test_severity(direct, transitive, colocated)
 
     return {
@@ -222,6 +234,7 @@ def _check_affected_tests(conn, sym_ids, file_paths):
         "total": len(results),
         "test_files": test_files,
         "pytest_command": pytest_cmd,
+        "pytest_command_truncated": truncated_files,
         "severity": severity,
     }