roam-code 11.1.3__tar.gz → 11.2.0__tar.gz

{roam_code-11.1.3/src/roam_code.egg-info → roam_code-11.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 11.1.3
+Version: 11.2.0
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: MIT
@@ -51,7 +51,7 @@ Dynamic: license-file
 
 **The architectural intelligence layer for AI coding agents. Structural graph, architecture governance, multi-agent orchestration, vulnerability mapping, runtime analysis -- one CLI, zero API keys.**
 
-*139 commands · 101 MCP tools · 27 languages · 100% local*
+*140 commands · 102 MCP tools · 27 languages · 100% local*
 
 [![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)
@@ -111,6 +111,11 @@ $ roam diff                    # blast radius of uncommitted changes
 
 ## What's New in v11
 
+### v11.2 -- AST Clone Detection + Debug Artifact Rules
+- **`roam clones`**: New AST structural clone detection via subtree hashing. Finds Type-2 clones (identical control flow, different identifiers/literals) with Jaccard similarity scoring, Union-Find clustering, and automated refactoring suggestions. More precise than the metric-based `duplicates` command.
+- **9 debug artifact rules** (COR-560 through COR-568): Detect leftover `print()`, `breakpoint()`, `pdb.set_trace()`, `console.log()`, `debugger`, and `System.out.println()` in Python, JavaScript, TypeScript, and Java code. All use `ast_match` type with test file exemptions.
+- **140 commands, 102 MCP tools**.
+
 ### v11.1.2 -- SQL + Scala Tier 1, 27 Languages
 - **SQL DDL promoted to Tier 1** with dedicated `SqlExtractor` -- tables, columns, views, functions, triggers, schemas, types (enums), sequences, ALTER TABLE ADD COLUMN. Foreign keys produce graph edges; views and triggers reference source tables. Database-schema projects now work with `roam health`, `roam layers`, `roam impact`, `roam coupling` and all graph commands.
 - **Scala promoted to Tier 1** with dedicated `ScalaExtractor` -- classes, traits, objects, case classes, sealed hierarchies, val/var properties, type aliases, imports, and inheritance. Full `extends` + `with` trait mixin resolution.
@@ -118,7 +123,7 @@ $ roam diff                    # blast radius of uncommitted changes
 - `server.json` for official MCP Registry submission.
 
 ### v11.1.1 -- Command Quality Audit
-- **Full command audit**: all 139 commands reviewed for usefulness, duplicates, and test coverage. ~20 bugs fixed, 21 new test files (700+ tests), every command docstring updated with cross-references to related commands.
+- **Full command audit**: all 140 commands reviewed for usefulness, duplicates, and test coverage. ~20 bugs fixed, 21 new test files (700+ tests), every command docstring updated with cross-references to related commands.
 - **Kotlin promoted to Tier 1** via new YAML-based declarative extractor architecture. Classes, interfaces, enums, objects, functions, methods, properties, and inheritance fully extracted.
 - **7 new commands**: `roam congestion`, `roam adrs`, `roam flag-dead`, `roam test-scaffold`, `roam sbom`, `roam triage`, `roam ci-setup`.
 - **CI templates**: `roam ci-setup` generates pipelines for GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and Bitbucket.
@@ -273,7 +278,7 @@ roam health
 
 ## Commands
 
-The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. All 139 commands are organized into 7 categories.
+The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. All 140 commands are organized into 7 categories.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -531,6 +536,7 @@ The sentinel pair `<!-- roam:minimap -->` / `<!-- /roam:minimap -->` is replaced
 | `roam safe-zones` | Graph-based containment boundaries |
 | `roam coverage-gaps` | Unprotected entry points with no path to gate symbols |
 | `roam duplicates [--threshold T] [--min-lines N]` | Semantic duplicate detector: functionally equivalent code clusters with divergent edge-case handling |
+| `roam clones [--threshold T] [--min-lines N] [--scope P]` | AST structural clone detection: Type-2 clones via subtree hashing (more precise than `duplicates`) |
 
 ### Exploration
 
@@ -869,7 +875,7 @@ pip install "roam-code[mcp]"
 roam mcp
 ```
 
-101 tools, 10 resources, and 5 prompts are available in the full preset. Most tools are read-only index queries; side-effect tools are explicitly annotated.
+102 tools, 10 resources, and 5 prompts are available in the full preset. Most tools are read-only index queries; side-effect tools are explicitly annotated.
 
 **MCP v2 highlights (v11):**
 - In-process MCP execution (no subprocess shell-out per call)
@@ -936,6 +942,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_bisect_blame` | Architectural git bisect |
 | `roam_doc_intent` | Doc-to-code linking |
 | `roam_cut_analysis` | Minimum graph cut analysis |
+| `roam_clones` | AST structural clone detection (Type-2 clones) |
 | `roam_annotate_symbol` | Attach persistent notes to symbols |
 | `roam_get_annotations` | View stored annotations |
 | `roam_relate` | Show relationship between two symbols |
@@ -1512,8 +1519,8 @@ roam-code/
 ├── action.yml                         # Reusable GitHub Action
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (139 commands)
-│   ├── mcp_server.py                  # MCP server (101 tools, 10 resources, 5 prompts)
+│   ├── cli.py                         # Click CLI (140 commands)
+│   ├── mcp_server.py                  # MCP server (102 tools, 10 resources, 5 prompts)
 │   ├── db/
 │   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
 │   │   ├── schema.py                  # Tables, indexes, migrations
@@ -1607,7 +1614,7 @@ Optional: Local semantic ONNX stack (`numpy`, `onnxruntime`, `tokenizers`) via `
 ### Shipped
 
 - [x] MCP v2 agent surface: in-process execution, compound operations, presets, schemas, annotations, and compatibility profiles.
-- [x] Full command and MCP inventory parity in docs: 139 CLI commands and 101 MCP tools.
+- [x] Full command and MCP inventory parity in docs: 140 CLI commands and 102 MCP tools.
 - [x] CI hardening: composite action, changed-only mode, trend-aware gates, sticky PR updater, and SARIF guardrails.
 - [x] Performance foundation: FTS5/BM25 search, O(changed) incremental indexing, DB/index optimizations.
 - [x] Agent governance suite: `vibe-check`, `ai-readiness`, `verify`, `ai-ratio`, `duplicates`, advanced `algo` scoring/SARIF.

{roam_code-11.1.3 → roam_code-11.2.0}/README.md

@@ -4,7 +4,7 @@
 
 **The architectural intelligence layer for AI coding agents. Structural graph, architecture governance, multi-agent orchestration, vulnerability mapping, runtime analysis -- one CLI, zero API keys.**
 
-*139 commands · 101 MCP tools · 27 languages · 100% local*
+*140 commands · 102 MCP tools · 27 languages · 100% local*
 
 [![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)
@@ -64,6 +64,11 @@ $ roam diff                    # blast radius of uncommitted changes
 
 ## What's New in v11
 
+### v11.2 -- AST Clone Detection + Debug Artifact Rules
+- **`roam clones`**: New AST structural clone detection via subtree hashing. Finds Type-2 clones (identical control flow, different identifiers/literals) with Jaccard similarity scoring, Union-Find clustering, and automated refactoring suggestions. More precise than the metric-based `duplicates` command.
+- **9 debug artifact rules** (COR-560 through COR-568): Detect leftover `print()`, `breakpoint()`, `pdb.set_trace()`, `console.log()`, `debugger`, and `System.out.println()` in Python, JavaScript, TypeScript, and Java code. All use `ast_match` type with test file exemptions.
+- **140 commands, 102 MCP tools**.
+
 ### v11.1.2 -- SQL + Scala Tier 1, 27 Languages
 - **SQL DDL promoted to Tier 1** with dedicated `SqlExtractor` -- tables, columns, views, functions, triggers, schemas, types (enums), sequences, ALTER TABLE ADD COLUMN. Foreign keys produce graph edges; views and triggers reference source tables. Database-schema projects now work with `roam health`, `roam layers`, `roam impact`, `roam coupling` and all graph commands.
 - **Scala promoted to Tier 1** with dedicated `ScalaExtractor` -- classes, traits, objects, case classes, sealed hierarchies, val/var properties, type aliases, imports, and inheritance. Full `extends` + `with` trait mixin resolution.
@@ -71,7 +76,7 @@ $ roam diff                    # blast radius of uncommitted changes
 - `server.json` for official MCP Registry submission.
 
 ### v11.1.1 -- Command Quality Audit
-- **Full command audit**: all 139 commands reviewed for usefulness, duplicates, and test coverage. ~20 bugs fixed, 21 new test files (700+ tests), every command docstring updated with cross-references to related commands.
+- **Full command audit**: all 140 commands reviewed for usefulness, duplicates, and test coverage. ~20 bugs fixed, 21 new test files (700+ tests), every command docstring updated with cross-references to related commands.
 - **Kotlin promoted to Tier 1** via new YAML-based declarative extractor architecture. Classes, interfaces, enums, objects, functions, methods, properties, and inheritance fully extracted.
 - **7 new commands**: `roam congestion`, `roam adrs`, `roam flag-dead`, `roam test-scaffold`, `roam sbom`, `roam triage`, `roam ci-setup`.
 - **CI templates**: `roam ci-setup` generates pipelines for GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and Bitbucket.
@@ -226,7 +231,7 @@ roam health
 
 ## Commands
 
-The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. All 139 commands are organized into 7 categories.
+The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. All 140 commands are organized into 7 categories.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -484,6 +489,7 @@ The sentinel pair `<!-- roam:minimap -->` / `<!-- /roam:minimap -->` is replaced
 | `roam safe-zones` | Graph-based containment boundaries |
 | `roam coverage-gaps` | Unprotected entry points with no path to gate symbols |
 | `roam duplicates [--threshold T] [--min-lines N]` | Semantic duplicate detector: functionally equivalent code clusters with divergent edge-case handling |
+| `roam clones [--threshold T] [--min-lines N] [--scope P]` | AST structural clone detection: Type-2 clones via subtree hashing (more precise than `duplicates`) |
 
 ### Exploration
 
@@ -822,7 +828,7 @@ pip install "roam-code[mcp]"
 roam mcp
 ```
 
-101 tools, 10 resources, and 5 prompts are available in the full preset. Most tools are read-only index queries; side-effect tools are explicitly annotated.
+102 tools, 10 resources, and 5 prompts are available in the full preset. Most tools are read-only index queries; side-effect tools are explicitly annotated.
 
 **MCP v2 highlights (v11):**
 - In-process MCP execution (no subprocess shell-out per call)
@@ -889,6 +895,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_bisect_blame` | Architectural git bisect |
 | `roam_doc_intent` | Doc-to-code linking |
 | `roam_cut_analysis` | Minimum graph cut analysis |
+| `roam_clones` | AST structural clone detection (Type-2 clones) |
 | `roam_annotate_symbol` | Attach persistent notes to symbols |
 | `roam_get_annotations` | View stored annotations |
 | `roam_relate` | Show relationship between two symbols |
@@ -1465,8 +1472,8 @@ roam-code/
 ├── action.yml                         # Reusable GitHub Action
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (139 commands)
-│   ├── mcp_server.py                  # MCP server (101 tools, 10 resources, 5 prompts)
+│   ├── cli.py                         # Click CLI (140 commands)
+│   ├── mcp_server.py                  # MCP server (102 tools, 10 resources, 5 prompts)
 │   ├── db/
 │   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
 │   │   ├── schema.py                  # Tables, indexes, migrations
@@ -1560,7 +1567,7 @@ Optional: Local semantic ONNX stack (`numpy`, `onnxruntime`, `tokenizers`) via `
 ### Shipped
 
 - [x] MCP v2 agent surface: in-process execution, compound operations, presets, schemas, annotations, and compatibility profiles.
-- [x] Full command and MCP inventory parity in docs: 139 CLI commands and 101 MCP tools.
+- [x] Full command and MCP inventory parity in docs: 140 CLI commands and 102 MCP tools.
 - [x] CI hardening: composite action, changed-only mode, trend-aware gates, sticky PR updater, and SARIF guardrails.
 - [x] Performance foundation: FTS5/BM25 search, O(changed) incremental indexing, DB/index optimizations.
 - [x] Agent governance suite: `vibe-check`, `ai-readiness`, `verify`, `ai-ratio`, `duplicates`, advanced `algo` scoring/SARIF.

{roam_code-11.1.3 → roam_code-11.2.0}/pyproject.toml

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

{roam_code-11.1.3 → roam_code-11.2.0}/src/roam/cli.py

@@ -14,7 +14,7 @@ import click
 
 # Lazy-loading command group: imports command modules only when invoked.
 # This avoids importing networkx (~500ms) on every CLI call.
-# Total: 142 invokable command names (139 canonical commands + 3 alias pairs).
+# Total: 143 invokable command names (140 canonical commands + 3 alias pairs).
 # If this changes, update README.md, CLAUDE.md, llms-install.md, and docs copy.
 _COMMANDS = {
     "index": ("roam.commands.cmd_index", "index"),
@@ -159,6 +159,7 @@ _COMMANDS = {
     "sbom": ("roam.commands.cmd_sbom", "sbom"),
     "triage": ("roam.commands.cmd_triage", "triage"),
     "ci-setup": ("roam.commands.cmd_ci_setup", "ci_setup"),
+    "clones": ("roam.commands.cmd_clones", "clones"),
 }
 
 # Command categories for organized --help display
@@ -252,6 +253,7 @@ _CATEGORIES = {
         "visualize",
         "x-lang",
         "fingerprint",
+        "clones",
     ],
     "Exploration": [
         "search",

roam_code-11.2.0/src/roam/commands/cmd_clones.py

@@ -0,0 +1,163 @@
+"""Detect near-duplicate code via AST structural hashing.
+
+Unlike ``duplicates`` (which uses metric-based similarity from the DB),
+this command re-parses source files and compares actual AST subtree
+structures.  Detects Type-2 clones: identical control flow with different
+identifiers or literals.
+
+Related commands: ``duplicates`` (metric-based), ``suggest-refactoring``,
+``split`` (extract responsibilities).
+"""
+
+from __future__ import annotations
+
+import click
+
+from roam.commands.resolve import ensure_index
+from roam.db.connection import open_db
+from roam.output.formatter import (
+    abbrev_kind,
+    format_table,
+    json_envelope,
+    loc,
+    to_json,
+)
+
+
+@click.command()
+@click.option(
+    "--threshold",
+    default=0.70,
+    show_default=True,
+    type=click.FloatRange(0.0, 1.0),
+    help="Minimum Jaccard similarity (0.0-1.0)",
+)
+@click.option(
+    "--min-lines",
+    default=5,
+    show_default=True,
+    type=int,
+    help="Skip functions shorter than N lines",
+)
+@click.option("--scope", default=None, type=str, help="Limit to files under this path prefix")
+@click.option("--top", default=0, type=int, help="Show only top N clusters (0=all)")
+@click.pass_context
+def clones(ctx, threshold, min_lines, scope, top):
+    """Detect near-duplicate code via AST structural hashing.
+
+    Re-parses source files and compares function AST structures via subtree
+    hashing.  Finds Type-2 clones: identical control flow with different
+    identifiers or literals.
+
+    Unlike ``duplicates`` (metric-based), this uses actual tree-sitter AST
+    comparison for higher precision.
+    """
+    json_mode = ctx.obj.get("json") if ctx.obj else False
+    token_budget = ctx.obj.get("budget", 0) if ctx.obj else 0
+    ensure_index()
+
+    from roam.graph.clone_detect import detect_clones
+
+    with open_db(readonly=True) as conn:
+        pairs, clusters = detect_clones(
+            conn,
+            min_similarity=threshold,
+            min_lines=min_lines,
+            scope=scope,
+        )
+
+        if top > 0:
+            clusters = clusters[:top]
+
+        # Summary stats
+        total_functions = sum(len(c.members) for c in clusters)
+        total_pairs = len(pairs)
+        avg_sim = sum(c.avg_similarity for c in clusters) / len(clusters) if clusters else 0.0
+
+        # Estimate reducible lines
+        reducible_lines = 0
+        for c in clusters:
+            lines = sorted(m["line_end"] - m["line_start"] + 1 for m in c.members)
+            if len(lines) > 1:
+                reducible_lines += sum(lines[:-1])
+
+        verdict = (
+            f"{len(clusters)} clone cluster{'s' if len(clusters) != 1 else ''} "
+            f"found ({total_functions} functions, {round(avg_sim * 100)}% avg similarity)"
+            if clusters
+            else "No structural clones detected"
+        )
+
+        if json_mode:
+            clusters_json = []
+            for c in clusters:
+                clusters_json.append(
+                    {
+                        "cluster_id": c.cluster_id,
+                        "avg_similarity": c.avg_similarity,
+                        "size": len(c.members),
+                        "members": c.members,
+                        "pattern": c.pattern,
+                        "suggestion": c.suggestion,
+                    }
+                )
+
+            pairs_json = [
+                {
+                    "file_a": p.file_a,
+                    "func_a": p.func_a,
+                    "line_a": p.line_a,
+                    "file_b": p.file_b,
+                    "func_b": p.func_b,
+                    "line_b": p.line_b,
+                    "similarity": p.similarity,
+                }
+                for p in pairs[:50]  # Cap pair output
+            ]
+
+            click.echo(
+                to_json(
+                    json_envelope(
+                        "clones",
+                        summary={
+                            "verdict": verdict,
+                            "clusters": len(clusters),
+                            "clone_pairs": total_pairs,
+                            "total_functions": total_functions,
+                            "avg_similarity": round(avg_sim, 3),
+                            "estimated_reducible_lines": reducible_lines,
+                        },
+                        budget=token_budget,
+                        clusters=clusters_json,
+                        pairs=pairs_json,
+                    )
+                )
+            )
+            return
+
+        # Text output
+        click.echo(f"VERDICT: {verdict}")
+
+        if not clusters:
+            return
+
+        click.echo()
+        for c in clusters:
+            sim_pct = round(c.avg_similarity * 100)
+            click.echo(f"CLUSTER {c.cluster_id} -- {sim_pct}% similarity, {len(c.members)} functions:")
+            for m in c.members:
+                lines = m["line_end"] - m["line_start"] + 1
+                click.echo(
+                    f"  {m['function']:<40s} "
+                    f"{loc(m['file'], m['line_start'])}"
+                    f"  ({lines} lines, {m['ast_nodes']} AST nodes)"
+                )
+            click.echo(f"  Pattern: {c.pattern}")
+            click.echo(f"  Suggestion: {c.suggestion}")
+            click.echo()
+
+        click.echo(
+            f"SUMMARY: {len(clusters)} clusters, "
+            f"{total_functions} functions, "
+            f"~{reducible_lines} lines of reducible duplication"
+        )