roam-code 12.13__tar.gz → 12.14__tar.gz

{roam_code-12.13/src/roam_code.egg-info → roam_code-12.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.13
+Version: 12.14
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: MIT

{roam_code-12.13 → roam_code-12.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roam-code"
-version = "12.13"
+version = "12.14"
 description = "Instant codebase comprehension for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{roam_code-12.13 → roam_code-12.14}/src/roam/cli.py

@@ -474,6 +474,36 @@ class LazyGroup(click.Group):
         mod = importlib.import_module(module_path)
         return getattr(mod, attr_name)
 
+    def resolve_command(self, ctx, args):
+        """Resolve a subcommand, with a did-you-mean hint on typos.
+
+        v12.14 — Click's default ``"No such command: 'contxt'"`` ends
+        the conversation; we can do better. When the requested name
+        isn't in ``_COMMANDS`` we look for the closest existing names
+        by edit distance and surface them in the UsageError so the
+        agent can retry with the right command in one turn.
+        """
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError as exc:
+            msg = str(exc)
+            if "No such command" not in msg:
+                raise
+            # Click's UsageError exposes the bad token as its first arg
+            # in some versions; fall back to parsing the message.
+            bad = args[0] if args else ""
+            bad = bad.strip("'\"")
+            if not bad:
+                raise
+            import difflib
+
+            _ensure_plugin_commands_loaded()
+            close = difflib.get_close_matches(bad, list(_COMMANDS.keys()), n=3, cutoff=0.6)
+            if close:
+                suggestions = ", ".join(f"`roam {c}`" for c in close)
+                raise click.UsageError(f"No such command: '{bad}'. Did you mean {suggestions}?") from exc
+            raise
+
     def invoke(self, ctx):
         """Override invoke to map unhandled exceptions to standardized exit codes.
 
@@ -677,6 +707,28 @@ def _check_gate(gate_expr: str, data: dict) -> bool:
     return True
 
 
+def _run_help_all(ctx: click.Context, param: click.Parameter, value: bool) -> None:
+    """Eager callback for --help-all: print every command + short help.
+
+    The default ``roam --help`` shows priority categories + a flat
+    "More Commands" name list (66 names, no descriptions). Agents
+    mapping the territory often want every command's one-liner;
+    --help-all renders that without categorisation, sub-second
+    because the same AST short-help extraction --help uses.
+    """
+    if not value or ctx.resilient_parsing:
+        return
+    _ensure_plugin_commands_loaded()
+    click.echo("Usage: roam [OPTIONS] COMMAND [ARGS]...\n")
+    click.echo(f"All {len(_COMMANDS)} invokable command names:\n")
+    for cmd_name in sorted(_COMMANDS):
+        help_text = _short_help_via_ast(cmd_name) or ""
+        click.echo(f"  {cmd_name:32s} {help_text}")
+    click.echo()
+    click.echo("Run `roam <command> --help` for details on any command.")
+    ctx.exit(0)
+
+
 @click.group(cls=LazyGroup)
 @click.version_option(package_name="roam-code")
 @click.option(
@@ -687,6 +739,15 @@ def _check_gate(gate_expr: str, data: dict) -> bool:
     callback=_run_check,
     help="Quick setup verification: checks Python, tree-sitter, git, SQLite",
 )
+@click.option(
+    "--help-all",
+    "help_all",
+    is_flag=True,
+    is_eager=True,
+    expose_value=False,
+    callback=_run_help_all,
+    help="Print every command (no categories, no truncation) and exit.",
+)
 @click.option("--json", "json_mode", is_flag=True, help="Output in JSON format")
 @click.option("--compact", is_flag=True, help="Compact output: TSV tables, minimal JSON envelope")
 @click.option("--agent", is_flag=True, help="Agent mode: compact JSON with 500-token default budget")

{roam_code-12.13 → roam_code-12.14}/src/roam/commands/cmd_dead.py

@@ -1488,6 +1488,8 @@ def dead(
                     )
                 )
             else:
+                click.echo("VERDICT: no dead exports — every exported symbol has at least one consumer")
+                click.echo()
                 click.echo("=== Unreferenced Exports (0) ===")
                 click.echo("  (none -- all exports are referenced)")
                 if unused_assignments:

{roam_code-12.13 → roam_code-12.14}/src/roam/commands/cmd_retrieve.py

@@ -24,6 +24,77 @@ from roam.retrieve.pipeline import run_retrieve
 from roam.retrieve.semantic import semantic_coverage
 
 
+def _suggest_refinements(task: str, candidates: list[dict]) -> list[str]:
+    """Generate 2-3 refined queries when confidence is low.
+
+    Heuristics:
+    1. **Drop common NL words** — "trace the login flow" → "login flow".
+       Removes filler that diluted the lexical signal.
+    2. **Suggest --seed-files anchor** — using the file of the
+       highest-scoring candidate as a seed often promotes the right
+       neighbours.
+    3. **Pivot to roam search** — when the query contains a clear
+       identifier (PascalCase / snake_case), exact-match search may
+       beat structural retrieval.
+
+    Returns a list of human-readable suggested commands.
+    """
+    if not task:
+        return []
+    suggestions: list[str] = []
+
+    # 1. Drop NL filler — keep the noun-shaped tokens only.
+    filler = {
+        "the",
+        "a",
+        "an",
+        "is",
+        "are",
+        "of",
+        "to",
+        "in",
+        "on",
+        "for",
+        "where",
+        "what",
+        "how",
+        "find",
+        "show",
+        "tell",
+        "me",
+        "this",
+        "that",
+        "with",
+        "by",
+        "from",
+        "and",
+        "or",
+        "as",
+        "at",
+    }
+    words = task.split()
+    kept = [w for w in words if w.lower().strip(".,!?") not in filler]
+    if len(kept) < len(words) and len(kept) >= 1:
+        tighter = " ".join(kept)
+        if tighter.strip() and tighter != task:
+            suggestions.append(f'roam retrieve "{tighter}"')
+
+    # 2. Anchor on the top candidate's file.
+    if candidates:
+        top_file = (candidates[0].get("file_path") or candidates[0].get("file") or "").replace("\\", "/")
+        if top_file:
+            suggestions.append(f'roam retrieve "{task}" --seed-files {top_file}')
+
+    # 3. If the query contains an identifier-shape, suggest exact search.
+    import re
+
+    ident_match = re.search(r"\b([A-Z][A-Za-z0-9]{2,}|[a-z][a-z0-9]+(?:_[a-z0-9]+)+)\b", task)
+    if ident_match:
+        suggestions.append(f"roam search {ident_match.group(1)}")
+
+    return suggestions[:3]
+
+
 def _retrieve_confidence_score(candidates: list[dict], task: str = "") -> tuple[float, str]:
     """Return a calibrated confidence number in ``[0.0, 1.0]`` plus a
     string label (``"low"`` / ``"ok"``) for backwards compat.
@@ -313,6 +384,9 @@ def retrieve(ctx, task, budget, k, rerank, seed_files, dry_run):
                         "verdict": verdict,
                         "low_confidence": confidence == "low",
                         "confidence": confidence_score,
+                        "refinements": (
+                            _suggest_refinements(task_str, candidates) if confidence_score < 0.40 and candidates else []
+                        ),
                         "candidates": len(candidates),
                         "total_candidates": result["total_candidates"],
                         "budget": result["budget"],
@@ -375,3 +449,16 @@ def retrieve(ctx, task, budget, k, rerank, seed_files, dry_run):
             "SEMANTIC: 0 dense vectors available; zeta is currently inert. "
             "Configure semantic backend and rerun `roam index` to activate it."
         )
+
+    # 12.14 — auto-refine on low confidence. When the score crosses
+    # below 0.40 we know the user is unlikely to find the answer in
+    # the returned spans. Surface 2-3 refined queries the agent can
+    # try next: dropping generic NL words, adding a seed-files
+    # anchor, or pivoting to ``roam search`` for exact name match.
+    if confidence_score < 0.40 and candidates:
+        refined = _suggest_refinements(task_str, candidates)
+        if refined:
+            click.echo()
+            click.echo("REFINE: low confidence — try a tighter query:")
+            for r in refined:
+                click.echo(f"  {r}")

{roam_code-12.13 → roam_code-12.14}/src/roam/competitor_site_data.py

@@ -1364,7 +1364,7 @@ MAP_METADATA: dict[str, dict[str, object]] = {
         "peer": True,
         "graph": "PageRank + Tarjan + Louvain + layers",
         "note": "Graph algorithms (PageRank, SCC, Louvain, Fiedler) on tree-sitter ASTs fused with git history in SQLite. 122 MCP tools, 155 CLI commands. 19 Python idiom detectors (v12.7+).",
-        "version_evaluated": "12.13",
+        "version_evaluated": "12.14",
         "repo_url": "https://github.com/Cranot/roam-code",
     },
     "CKB/CodeMCP": {

{roam_code-12.13 → roam_code-12.14}/src/roam/mcp-server-card.json

@@ -2,7 +2,7 @@
   "$schema": "https://schemas.modelcontextprotocol.io/server-card/v1",
   "name": "roam-code",
   "display_name": "roam — instant codebase intelligence",
-  "version": "12.13",
+  "version": "12.14",
   "description": "Architectural sight for AI agents before they edit. Pre-indexes symbols, call graphs, dependencies, architecture layers, and git history into a local SQLite DB. 122 MCP tools, 10 resources, 5 prompts, 27 languages. 100% local, zero API keys.",
   "vendor": {
     "name": "Cranot",

{roam_code-12.13 → roam_code-12.14/src/roam_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.13
+Version: 12.14
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: MIT