roam-code 13.7.1__tar.gz → 13.8.0__tar.gz

{roam_code-13.7.1 → roam_code-13.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 13.7.1
+Version: 13.8.0
 Summary: Local codebase intelligence for AI coding agents: structural repo map, change-safety gates, MCP security receipts, and tamper-evident ChangeEvidence packets. 100% local, zero API keys, zero network egress.
 Author: Cranot
 License-Expression: Apache-2.0
@@ -80,7 +80,7 @@ Dynamic: license-file
 <sub>Credential-free · 100% local by default (opt-in `metrics-push` is the only outbound surface) · tamper-evident `ChangeEvidence` packets · Apache 2.0 · runs entirely on your machine</sub>
 
 <!-- BEGIN auto-count:readme-headline-counts -->
-<sub>268 commands · 243 MCP tools (16 in the default `core` preset) · 28 languages</sub>
+<sub>272 commands · 243 MCP tools (16 in the default `core` preset) · 28 languages</sub>
 <!-- END auto-count:readme-headline-counts -->
 
 ![roam terminal demo](docs/assets/roam-terminal-demo.gif)
@@ -445,7 +445,7 @@ Full release notes in [CHANGELOG.md](CHANGELOG.md).
 ## Core commands
 
 <!-- BEGIN auto-count:readme-canonical-mention -->
-**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining ~263 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 **268 commands (261 canonical + 7 aliases) organised into 7 categories** (aliases for muscle memory: `math` → `algo`, `churn` → `weather`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`, `refs` → `uses`), 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 ~267 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 **272 commands (265 canonical + 7 aliases) organised into 7 categories** (aliases for muscle memory: `math` → `algo`, `churn` → `weather`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`, `refs` → `uses`), but you don't need to know that to start.
 <!-- END auto-count:readme-canonical-mention -->
 
 | Verb | What it does |
@@ -460,7 +460,7 @@ The full surface spans **7 categories** — Getting Started, Daily Workflow, Cod
 
 <details>
 <!-- BEGIN auto-count:readme-cli-command-list-summary -->
-<summary><strong>Full command reference — canonical command list (all 261)</strong></summary>
+<summary><strong>Full command reference — canonical command list (all 265)</strong></summary>
 <!-- END auto-count:readme-cli-command-list-summary -->
 
 The complete, always-current list with flags and examples lives in the [Command Reference](https://roam-code.com/docs/command-reference).
@@ -664,7 +664,7 @@ See [Using Roam via MCP](https://roam-code.com/docs/mcp-usage) for the first-run
 | `roam_diff` | Show the blast radius of your edits BEFORE you commit. Run after Edit/Write tools to see affected symbols, files, tests, plus coupling and fitness warnings. Use when user asks 'what did my change break?', 'safe to commit?'. Replaces ad-hoc `git diff --stat` inspection with graph-aware impact data. For PR-level risk verdict, use roam_pr_risk. |
 | `roam_disambiguate` | List every symbol matching a name with file/line/kind/signature/PageRank — pick the right overload. |
 | `roam_doc_intent` | Link documentation to code: find drift, dead refs, undocumented symbols. |
-| `roam_doc_staleness` | Detect stale docstrings: docs whose body has drifted since the comment was written. Uses ``git blame`` to compare docstring timestamps against code body timestamps. Different from ``roam_docs_coverage`` (missing docs ranked by PageRank) and ``roam_stale_refs`` (dangling doc links) -- this audits what existing docs SAY. |
+| `roam_doc_staleness` | Run a semantic docstring-drift audit: flag documented parameters, returns, or raises that no longer match code. Pass ``include_prose_drift`` to include optional blame-only summary drift. Different from ``roam_docs_coverage`` (missing docs ranked by PageRank) and ``roam_stale_refs`` (dangling doc links) -- this audits concrete claims in existing docs. |
 | `roam_docs_coverage` | Doc coverage + stale-doc drift with PageRank-ranked missing docs. |
 | `roam_doctor` | Setup diagnostics: Python version, tree-sitter, git, index existence, freshness, SQLite. |
 | `roam_dogfood` | One-shot full-stack run: audit + pr-analyze + audit-trail + conformance. |

{roam_code-13.7.1 → roam_code-13.8.0}/README.md

@@ -13,7 +13,7 @@
 <sub>Credential-free · 100% local by default (opt-in `metrics-push` is the only outbound surface) · tamper-evident `ChangeEvidence` packets · Apache 2.0 · runs entirely on your machine</sub>
 
 <!-- BEGIN auto-count:readme-headline-counts -->
-<sub>268 commands · 243 MCP tools (16 in the default `core` preset) · 28 languages</sub>
+<sub>272 commands · 243 MCP tools (16 in the default `core` preset) · 28 languages</sub>
 <!-- END auto-count:readme-headline-counts -->
 
 ![roam terminal demo](docs/assets/roam-terminal-demo.gif)
@@ -378,7 +378,7 @@ Full release notes in [CHANGELOG.md](CHANGELOG.md).
 ## Core commands
 
 <!-- BEGIN auto-count:readme-canonical-mention -->
-**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining ~263 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 **268 commands (261 canonical + 7 aliases) organised into 7 categories** (aliases for muscle memory: `math` → `algo`, `churn` → `weather`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`, `refs` → `uses`), 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 ~267 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 **272 commands (265 canonical + 7 aliases) organised into 7 categories** (aliases for muscle memory: `math` → `algo`, `churn` → `weather`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`, `refs` → `uses`), but you don't need to know that to start.
 <!-- END auto-count:readme-canonical-mention -->
 
 | Verb | What it does |
@@ -393,7 +393,7 @@ The full surface spans **7 categories** — Getting Started, Daily Workflow, Cod
 
 <details>
 <!-- BEGIN auto-count:readme-cli-command-list-summary -->
-<summary><strong>Full command reference — canonical command list (all 261)</strong></summary>
+<summary><strong>Full command reference — canonical command list (all 265)</strong></summary>
 <!-- END auto-count:readme-cli-command-list-summary -->
 
 The complete, always-current list with flags and examples lives in the [Command Reference](https://roam-code.com/docs/command-reference).
@@ -597,7 +597,7 @@ See [Using Roam via MCP](https://roam-code.com/docs/mcp-usage) for the first-run
 | `roam_diff` | Show the blast radius of your edits BEFORE you commit. Run after Edit/Write tools to see affected symbols, files, tests, plus coupling and fitness warnings. Use when user asks 'what did my change break?', 'safe to commit?'. Replaces ad-hoc `git diff --stat` inspection with graph-aware impact data. For PR-level risk verdict, use roam_pr_risk. |
 | `roam_disambiguate` | List every symbol matching a name with file/line/kind/signature/PageRank — pick the right overload. |
 | `roam_doc_intent` | Link documentation to code: find drift, dead refs, undocumented symbols. |
-| `roam_doc_staleness` | Detect stale docstrings: docs whose body has drifted since the comment was written. Uses ``git blame`` to compare docstring timestamps against code body timestamps. Different from ``roam_docs_coverage`` (missing docs ranked by PageRank) and ``roam_stale_refs`` (dangling doc links) -- this audits what existing docs SAY. |
+| `roam_doc_staleness` | Run a semantic docstring-drift audit: flag documented parameters, returns, or raises that no longer match code. Pass ``include_prose_drift`` to include optional blame-only summary drift. Different from ``roam_docs_coverage`` (missing docs ranked by PageRank) and ``roam_stale_refs`` (dangling doc links) -- this audits concrete claims in existing docs. |
 | `roam_docs_coverage` | Doc coverage + stale-doc drift with PageRank-ranked missing docs. |
 | `roam_doctor` | Setup diagnostics: Python version, tree-sitter, git, index existence, freshness, SQLite. |
 | `roam_dogfood` | One-shot full-stack run: audit + pr-analyze + audit-trail + conformance. |

{roam_code-13.7.1 → roam_code-13.8.0}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roam-code"
-version = "13.7.1"
+version = "13.8.0"
 description = "Local codebase intelligence for AI coding agents: structural repo map, change-safety gates, MCP security receipts, and tamper-evident ChangeEvidence packets. 100% local, zero API keys, zero network egress."
 readme = "README.md"
 requires-python = ">=3.10"

{roam_code-13.7.1 → roam_code-13.8.0}/src/roam/catalog/detectors.py

@@ -1730,6 +1730,27 @@ _IO_WRAPPER_NAMES = {
     "for_each_repo",
 }
 
+# Batch writes are the anti-N+1 shape. Keep them out of the loop-I/O
+# detector even when they appear lexically inside a loop body.
+_IO_BATCH_CALLS = {
+    "executemany",
+    "executebatch",
+    "executescript",
+    "bulkcreate",
+    "bulkinsert",
+    "bulkupdate",
+    "insertmany",
+    "copyfrom",
+    "addall",
+    "writerows",
+}
+
+
+def _is_batch_io_call(call: str) -> bool:
+    """Return True for batched writes that should not trip N+1 I/O."""
+    return _call_leaf(call).lower().replace("_", "") in _IO_BATCH_CALLS
+
+
 # D body-level signals that the loop iterates CHUNKS, not
 # individual items. When any of these patterns appear in the function body,
 # the inner I/O calls operate on a batch (WHERE IN (...) form), not per-item,
@@ -2230,6 +2251,8 @@ def _io_classify_call(
     though the leaf matches a cache identifier; user feedback called
     out the Promise<T> vs T distinction explicitly.
     """
+    if _is_batch_io_call(c):
+        return None, None
     # D2: if call name matches cache allowlist BUT is awaited in the body,
     # the await says it really IS asynchronous I/O — escalate to medium.
     memory_result = _classify_known_in_memory_call(c, snippet)

{roam_code-13.7.1 → roam_code-13.8.0}/src/roam/cli.py

@@ -164,6 +164,7 @@ _COMMANDS = {
     "clusters": ("roam.commands.cmd_clusters", "clusters"),
     "layers": ("roam.commands.cmd_layers", "layers"),
     "cycles": ("roam.commands.cmd_cycles", "cycles"),
+    "cycle-break": ("roam.commands.cmd_cycle_break", "cycle_break"),
     "weather": ("roam.commands.cmd_weather", "weather"),
     "churn": ("roam.commands.cmd_weather", "weather"),
     "dead": ("roam.commands.cmd_dead", "dead"),
@@ -329,6 +330,7 @@ _COMMANDS = {
     "vuln-map": ("roam.commands.cmd_vuln_map", "vuln_map_cmd"),
     "vuln-reach": ("roam.commands.cmd_vuln_reach", "vuln_reach"),
     "ingest-trace": ("roam.commands.cmd_ingest_trace", "ingest_trace_cmd"),
+    "profile-import": ("roam.commands.cmd_profile_import", "profile_import"),
     "hotspots": ("roam.commands.cmd_hotspots", "hotspots"),
     "why-slow": ("roam.commands.cmd_why_slow", "why_slow"),
     "schema": ("roam.commands.cmd_schema", "schema_cmd"),
@@ -395,6 +397,7 @@ _COMMANDS = {
     "smells": ("roam.commands.cmd_smells", "smells"),
     "mcp-setup": ("roam.commands.cmd_mcp_setup", "mcp_setup"),
     "verify-imports": ("roam.commands.cmd_verify_imports", "verify_imports_cmd"),
+    "vue-emits": ("roam.commands.cmd_vue_emits", "vue_emits"),
     "vulns": ("roam.commands.cmd_vulns", "vulns"),
     "metrics": ("roam.commands.cmd_metrics", "metrics"),
     "congestion": ("roam.commands.cmd_congestion", "congestion"),
@@ -420,6 +423,7 @@ _COMMANDS = {
     "delete-check": ("roam.commands.cmd_delete_check", "delete_check_cmd"),
     "history-grep": ("roam.commands.cmd_history_grep", "history_grep_cmd"),
     "surface": ("roam.commands.cmd_surface", "surface"),
+    "surface-gaps": ("roam.commands.cmd_surface_gaps", "surface_gaps"),
     "commands": ("roam.commands.cmd_commands", "commands_cmd"),
     "explain-command": ("roam.commands.cmd_explain_command", "explain_command"),
     "db-check": ("roam.commands.cmd_db_check", "db_check"),
@@ -484,6 +488,7 @@ _CATEGORIES = {
         "stats",
         "telemetry",
         "surface",
+        "surface-gaps",
         "commands",
         "explain-command",
         "db-check",
@@ -611,10 +616,12 @@ _CATEGORIES = {
         "forecast",
         "bisect",
         "ingest-trace",
+        "profile-import",
         "hotspots",
         "why-slow",
         "eval-retrieve",
         "boundary",
+        "vue-emits",
     ],
     "Architecture": [
         "map",
@@ -625,6 +632,7 @@ _CATEGORIES = {
         "layers",
         "clusters",
         "cycles",
+        "cycle-break",
         "spectral",
         "coupling",
         "dark-matter",
@@ -1163,6 +1171,7 @@ _MODE_ALWAYS_ALLOWED: frozenset[str] = frozenset(
         "help-search",
         "help-all",
         "surface",
+        "surface-gaps",
         "doctor",
         "exit-codes",
         "version",

roam_code-13.8.0/src/roam/commands/cmd_cycle_break.py

@@ -0,0 +1,277 @@
+"""Recommend the smallest resolved extraction that breaks each file cycle.
+
+Output formats: text (default), ``--json``. SARIF is deliberately NOT
+emitted because cycle-break's deliverable is a refactoring recommendation
+(the minimum extraction edge-set that severs each import cycle) — not a set
+of per-location rule violations, which is the unit SARIF encodes.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+import click
+import networkx as nx
+
+from roam.capability import roam_capability
+from roam.commands.resolve import empty_corpus_state, ensure_index
+from roam.db.connection import find_project_root, open_db
+from roam.graph.builder import build_file_graph
+from roam.graph.cycles import find_cycles, find_minimum_cycle_break_edge_sets
+from roam.index.relations import _extract_imported_names, _read_source_text
+from roam.output.formatter import json_envelope, to_json
+
+
+def _path(graph: nx.DiGraph, file_id: int) -> str:
+    return str(graph.nodes[file_id].get("path", file_id))
+
+
+def _imported_names(
+    source_path: str,
+    project_root: str,
+    cache: dict[str, set[str] | None],
+) -> set[str] | None:
+    if source_path not in cache:
+        source = _read_source_text(source_path, project_root)
+        cache[source_path] = _extract_imported_names(source) if source is not None else None
+    return cache[source_path]
+
+
+def _crossing_symbols(
+    conn: sqlite3.Connection,
+    source_file_id: int,
+    target_file_id: int,
+    imported_names: set[str] | None,
+    cache: dict[tuple[int, int], list[dict]],
+) -> list[dict]:
+    if imported_names is None:
+        return []
+    cache_key = (source_file_id, target_file_id)
+    if cache_key in cache:
+        return cache[cache_key]
+    rows = conn.execute(
+        "SELECT DISTINCT target.id, target.name, target.kind, edge.kind "
+        "FROM edges edge "
+        "JOIN symbols source ON source.id = edge.source_id "
+        "JOIN symbols target ON target.id = edge.target_id "
+        "WHERE source.file_id = ? AND target.file_id = ? "
+        "ORDER BY target.name, target.kind, target.id, edge.kind",
+        (source_file_id, target_file_id),
+    ).fetchall()
+
+    symbols: dict[int, dict] = {}
+    for symbol_id, name, kind, edge_kind in rows:
+        if name not in imported_names:
+            continue
+        symbol = symbols.setdefault(
+            symbol_id,
+            {"id": symbol_id, "name": name, "kind": kind, "relationship_kinds": []},
+        )
+        if edge_kind not in symbol["relationship_kinds"]:
+            symbol["relationship_kinds"].append(edge_kind)
+    resolved = list(symbols.values())
+    names = [symbol["name"] for symbol in resolved]
+    cache[cache_key] = resolved if len(names) == len(set(names)) else []
+    return cache[cache_key]
+
+
+def _ordered_members(graph: nx.DiGraph, members: list[int], removed: list[tuple[int, int]]) -> list[int]:
+    candidate = graph.subgraph(members).copy()
+    candidate.remove_edges_from(removed)
+    return list(nx.lexicographical_topological_sort(candidate, key=lambda file_id: _path(graph, file_id)))
+
+
+def _candidate_details(
+    conn: sqlite3.Connection,
+    graph: nx.DiGraph,
+    members: list[int],
+    removed: list[tuple[int, int]],
+    project_root: str,
+    imported_names_cache: dict[str, set[str] | None],
+    crossing_symbols_cache: dict[tuple[int, int], list[dict]],
+) -> tuple[tuple, list[int], list[dict], bool]:
+    ordered = _ordered_members(graph, members, removed)
+    edges = []
+    for source, target in removed:
+        source_path = _path(graph, source)
+        edges.append(
+            {
+                "source": {"id": source, "file": source_path},
+                "target": {"id": target, "file": _path(graph, target)},
+                "symbols": _crossing_symbols(
+                    conn,
+                    source,
+                    target,
+                    _imported_names(source_path, project_root, imported_names_cache),
+                    crossing_symbols_cache,
+                ),
+            }
+        )
+
+    resolved = all(edge["symbols"] for edge in edges)
+    symbol_count = sum(len(edge["symbols"]) for edge in edges)
+    ordered_paths = tuple(_path(graph, file_id) for file_id in ordered)
+    edge_paths = tuple((edge["source"]["file"], edge["target"]["file"]) for edge in edges)
+    rank = (not resolved, symbol_count if resolved else 0, ordered_paths, edge_paths)
+    return rank, ordered, edges, resolved
+
+
+def _recommendation(edge: dict, cycle_path: str) -> str:
+    names = [symbol["name"] for symbol in edge["symbols"]]
+    rendered = ", ".join(f"`{name}`" for name in names)
+    noun = "symbol" if len(names) == 1 else "symbols"
+    source = edge["source"]["file"]
+    target = edge["target"]["file"]
+    return (
+        f"Extract {noun} {rendered} from `{target}` into a new leaf module imported by both "
+        f"`{source}` and `{target}` to break `{cycle_path}`."
+    )
+
+
+def _analyze_cycle(
+    conn: sqlite3.Connection,
+    graph: nx.DiGraph,
+    members: list[int],
+    project_root: str,
+    imported_names_cache: dict[str, set[str] | None],
+    crossing_symbols_cache: dict[tuple[int, int], list[dict]],
+) -> dict:
+    candidates = find_minimum_cycle_break_edge_sets(graph, members)
+    if not candidates:
+        ordered = sorted(members, key=lambda file_id: _path(graph, file_id))
+        return {
+            "members": [{"id": file_id, "file": _path(graph, file_id)} for file_id in ordered],
+            "closing_edges": [],
+            "recommendations": [],
+            "recommendation_state": "minimum_break_not_computed",
+            "recommendation_reason": "exact search is limited to SCCs with at most 14 internal edges",
+        }
+
+    _rank, ordered, edges, resolved = min(
+        (
+            _candidate_details(
+                conn,
+                graph,
+                members,
+                removed,
+                project_root,
+                imported_names_cache,
+                crossing_symbols_cache,
+            )
+            for removed in candidates
+        ),
+        key=lambda item: item[0],
+    )
+    ordered_paths = [_path(graph, file_id) for file_id in ordered]
+    cycle_path = " → ".join([*ordered_paths, ordered_paths[0]])
+    recommendations = []
+    if resolved:
+        for edge in edges:
+            edge["recommendation"] = _recommendation(edge, cycle_path)
+            recommendations.append(edge["recommendation"])
+
+    return {
+        "members": [{"id": file_id, "file": _path(graph, file_id)} for file_id in ordered],
+        "closing_edges": edges,
+        "recommendations": recommendations,
+        "recommendation_state": "resolved" if resolved else "unresolved_crossing_symbols",
+    }
+
+
+@roam_capability(
+    name="cycle-break",
+    category="architecture",
+    summary="Recommend the minimum resolved extraction that breaks each file cycle",
+    maturity="stable",
+    mcp_expose=False,
+    side_effect=False,
+    task_required=False,
+    destructive=False,
+    stale_sensitive=True,
+    ai_safe=True,
+    requires_index=True,
+)
+@click.command(name="cycle-break")
+@click.option("--json", "json_output", is_flag=True, help="Output in JSON format.")
+@click.pass_context
+def cycle_break(ctx, json_output):
+    """Recommend minimal symbol extractions that break file dependency cycles."""
+    json_mode = json_output or (ctx.obj.get("json") if ctx.obj else False)
+    token_budget = ctx.obj.get("budget", 0) if ctx.obj else 0
+    ensure_index()
+
+    with open_db(readonly=True) as conn:
+        empty = empty_corpus_state(conn)
+        if empty is not None:
+            if json_mode:
+                click.echo(
+                    to_json(
+                        json_envelope(
+                            "cycle-break",
+                            summary={"verdict": "no dependency graph to analyze", "cycle_count": 0, **empty},
+                            cycles=[],
+                            budget=token_budget,
+                        )
+                    )
+                )
+            return
+
+        graph = build_file_graph(conn)
+        raw_cycles = find_cycles(graph)
+        project_root = str(find_project_root())
+        imported_names_cache: dict[str, set[str] | None] = {}
+        crossing_symbols_cache: dict[tuple[int, int], list[dict]] = {}
+        findings = [
+            _analyze_cycle(
+                conn,
+                graph,
+                members,
+                project_root,
+                imported_names_cache,
+                crossing_symbols_cache,
+            )
+            for members in raw_cycles
+        ]
+        recommendation_count = sum(len(finding["recommendations"]) for finding in findings)
+        cycle_noun = "cycle" if len(findings) == 1 else "cycles"
+        recommendation_noun = "recommendation" if recommendation_count == 1 else "recommendations"
+        verdict = (
+            f"{len(findings)} file dependency {cycle_noun}; "
+            f"{recommendation_count} minimal extraction {recommendation_noun}"
+            if findings
+            else "No file dependency cycles"
+        )
+
+        if json_mode:
+            click.echo(
+                to_json(
+                    json_envelope(
+                        "cycle-break",
+                        summary={
+                            "verdict": verdict,
+                            "cycle_count": len(findings),
+                            "recommendation_count": recommendation_count,
+                            "cycle_count_definition": (
+                                "strongly-connected components (Tarjan SCC) of the indexed file dependency graph"
+                            ),
+                        },
+                        cycles=findings,
+                        budget=token_budget,
+                    )
+                )
+            )
+            return
+
+        if not findings:
+            return
+        click.echo(f"VERDICT: {verdict}")
+        for index, finding in enumerate(findings, 1):
+            members = [member["file"] for member in finding["members"]]
+            click.echo(f"\n  cycle {index}: {' → '.join([*members, members[0]])}")
+            for edge in finding["closing_edges"]:
+                click.echo(f"    closing edge: {edge['source']['file']} → {edge['target']['file']}")
+                names = ", ".join(symbol["name"] for symbol in edge["symbols"])
+                if names:
+                    click.echo(f"    symbols: {names}")
+            for recommendation in finding["recommendations"]:
+                click.echo(f"    recommendation: {recommendation}")

{roam_code-13.7.1 → roam_code-13.8.0}/src/roam/commands/cmd_dead.py

@@ -57,7 +57,7 @@ from roam.rules.dataflow import collect_dataflow_findings
 # older dead-export classifier shape (e.g. before scaffolding was
 # recognised). Bump per the rules in roam.catalog.versions when the
 # classifier or action verdict mapping changes meaningfully.
-DEAD_DETECTOR_VERSION: str = "1.0.0"
+DEAD_DETECTOR_VERSION: str = "1.1.0"
 
 
 def _dead_finding_id(symbol_id: int, file_path: str, kind: str) -> str:
@@ -480,7 +480,7 @@ def _scaffolding_signals(docstring: str | None) -> dict | None:
     }
 
 
-def _dead_action(r, file_imported, tested=False):
+def _dead_action(r, file_imported, tested=False, external_facing=False):
     """Compute actionable verdict and confidence % for a dead symbol.
 
     Uses tiered confidence scoring (inspired by Vulture and Meta's dead
@@ -536,6 +536,12 @@ def _dead_action(r, file_imported, tested=False):
     if tested:
         return "REVIEW", 70
 
+    # Explicit package surfaces have legitimate consumers outside the
+    # indexed repository. Internal call-graph silence alone cannot make
+    # these symbols safe to delete.
+    if external_facing:
+        return "REVIEW", 70
+
     # CLI command functions — loaded dynamically via LazyGroup/importlib
     if base.startswith("cmd_") and kind == "function":
         return "INTENTIONAL", 20
@@ -1052,6 +1058,12 @@ def _dead_reason(r, consumer_meta, file_import_meta, sibling_meta):
     fmeta = file_import_meta.get(r["file_id"], {})
     smeta = sibling_meta.get(r["file_id"], {})
     test_consumers = cmeta.get("test_consumers", 0)
+    public_surface_reason = cmeta.get("public_surface_reason")
+    if public_surface_reason:
+        test_clause = f"; used by {test_consumers} test consumer(s)" if test_consumers else ""
+        return (
+            f"external-facing public surface ({public_surface_reason}); no internal production consumers{test_clause}"
+        )
     if test_consumers:
         return f"no production consumers; used by {test_consumers} test consumer(s)"
 
@@ -1164,6 +1176,10 @@ def _analyze_dead(conn):
         return [], [], set(), {}, {}, {}
 
     consumer_meta = _dead_consumer_meta(conn, [r["id"] for r in rows])
+    from roam.commands.dead_public_surface import public_surface_reasons
+
+    for symbol_id, reason in public_surface_reasons(rows, find_project_root()).items():
+        consumer_meta[symbol_id]["public_surface_reason"] = reason
     rows = [r for r in rows if consumer_meta.get(r["id"], {}).get("production_consumers", 0) == 0]
     if not rows:
         return [], [], set(), consumer_meta, {}, {}
@@ -2439,6 +2455,7 @@ def dead(
                     r,
                     r["file_id"] in imported_files,
                     consumer_meta.get(r["id"], {}).get("test_consumers", 0) > 0,
+                    bool(consumer_meta.get(r["id"], {}).get("public_surface_reason")),
                 ),
             )
             for r in all_items
@@ -2632,6 +2649,7 @@ def dead(
                         r,
                         r["file_id"] in imported_files,
                         consumer_meta.get(r["id"], {}).get("test_consumers", 0) > 0,
+                        bool(consumer_meta.get(r["id"], {}).get("public_surface_reason")),
                     )[0]
                     for r in items
                 ]
@@ -2658,7 +2676,7 @@ def dead(
                 fmeta = file_import_meta.get(r["file_id"], {})
                 smeta = sibling_meta.get(r["file_id"], {})
                 tested = cmeta.get("test_consumers", 0) > 0
-                action, confidence = _dead_action(r, file_imported, tested)
+                action, confidence = _dead_action(r, file_imported, tested, bool(cmeta.get("public_surface_reason")))
                 scaffolding_evidence = _scaffolding_signals(r["docstring"] if "docstring" in r.keys() else None)
                 d = {
                     "name": r["name"],
@@ -2943,7 +2961,12 @@ def dead(
                 click.echo("Top dead symbols (high confidence):")
                 for r in high[:5]:
                     tested = consumer_meta.get(r["id"], {}).get("test_consumers", 0) > 0
-                    action, confidence = _dead_action(r, True, tested)
+                    action, confidence = _dead_action(
+                        r,
+                        True,
+                        tested,
+                        bool(consumer_meta.get(r["id"], {}).get("public_surface_reason")),
+                    )
                     click.echo(
                         f"  {action} {confidence}%  {r['name']}  {abbrev_kind(r['kind'])}  {loc(r['file_path'], r['line_start'])}"
                     )
@@ -3072,7 +3095,12 @@ def dead(
             table_rows = []
             for r in high:
                 tested = consumer_meta.get(r["id"], {}).get("test_consumers", 0) > 0
-                action, confidence = _dead_action(r, True, tested)
+                action, confidence = _dead_action(
+                    r,
+                    True,
+                    tested,
+                    bool(consumer_meta.get(r["id"], {}).get("public_surface_reason")),
+                )
                 row = [
                     f"{action} {confidence}%",
                     r["name"],
@@ -3125,7 +3153,12 @@ def dead(
             table_rows = []
             for r in low:
                 tested = consumer_meta.get(r["id"], {}).get("test_consumers", 0) > 0
-                action, confidence = _dead_action(r, False, tested)
+                action, confidence = _dead_action(
+                    r,
+                    False,
+                    tested,
+                    bool(consumer_meta.get(r["id"], {}).get("public_surface_reason")),
+                )
                 row = [
                     f"{action} {confidence}%",
                     r["name"],