roam-code 7.5.0__tar.gz → 8.0.0__tar.gz

{roam_code-7.5.0/src/roam_code.egg-info → roam_code-8.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 7.5.0
+Version: 8.0.0
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: MIT
@@ -60,7 +60,7 @@ A semantic graph means Roam understands what functions call what, how modules de
 Codebase ──> [Index] ──> Semantic Graph ──> CLI ──> AI Agent
               │              │                │
            tree-sitter    symbols           one call
-           17 languages   + edges           replaces
+           22 languages   + edges           replaces
            git history    + metrics         5-10 tool calls
 ```
 
@@ -208,7 +208,7 @@ roam health
 
 ## Commands
 
-The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. 58 total commands are organized into 8 categories.
+The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. 55 total commands are organized into 7 categories.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -881,7 +881,7 @@ Codebase
     |
 [1] Discovery ──── git ls-files (respects .gitignore)
     |
-[2] Parse ──────── tree-sitter AST per file (17 languages)
+[2] Parse ──────── tree-sitter AST per file (22 languages)
     |
 [3] Extract ────── symbols + references (calls, imports, inheritance)
     |
@@ -1020,7 +1020,7 @@ Delete `.roam/` from your project root to clean up local data.
 git clone https://github.com/Cranot/roam-code.git
 cd roam-code
 pip install -e .
-pytest tests/   # 669 tests, Python 3.9-3.13
+pytest tests/   # 1656 tests, Python 3.9-3.13
 ```
 
 <details>
@@ -1033,7 +1033,7 @@ roam-code/
 ├── CHANGELOG.md
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (58 commands, 8 categories)
+│   ├── cli.py                         # Click CLI (55 commands, 7 categories)
 │   ├── mcp_server.py                  # MCP server (19 tools, 2 resources)
 │   ├── db/
 │   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
@@ -1045,8 +1045,8 @@ roam-code/
 │   │   ├── parser.py                  # Tree-sitter parsing
 │   │   ├── symbols.py                 # Symbol + reference extraction
 │   │   ├── relations.py               # Reference resolution -> edges
-│   │   ├── complexity.py              # Cognitive complexity (SonarSource)
-│   │   ├── git_stats.py               # Churn, co-change, blame, entropy
+│   │   ├── complexity.py              # Cognitive complexity (SonarSource) + Halstead metrics
+│   │   ├── git_stats.py               # Churn, co-change, blame, Renyi entropy
 │   │   └── incremental.py             # mtime + hash change detection
 │   ├── languages/
 │   │   ├── base.py                    # Abstract LanguageExtractor
@@ -1060,7 +1060,7 @@ roam-code/
 │   │   └── aggregator.py              # Cross-repo aggregation
 │   ├── graph/
 │   │   ├── builder.py, pagerank.py    # DB -> NetworkX, PageRank
-│   │   ├── cycles.py, clusters.py     # Tarjan SCC, Louvain
+│   │   ├── cycles.py, clusters.py     # Tarjan SCC, propagation cost, Louvain, modularity Q
 │   │   ├── layers.py, pathfinding.py  # Topo layers, k-shortest paths
 │   │   ├── split.py, why.py           # Decomposition, role classification
 │   ├── commands/
@@ -1069,7 +1069,7 @@ roam-code/
 │   └── output/
 │       ├── formatter.py               # Token-efficient formatting
 │       └── sarif.py                   # SARIF 2.1.0 output
-└── tests/                             # 669 tests across 11 test files
+└── tests/                             # 1656 tests across 28 test files
 ```
 
 </details>
@@ -1110,7 +1110,7 @@ Optional: [fastmcp](https://github.com/jlowin/fastmcp) (MCP server)
 git clone https://github.com/Cranot/roam-code.git
 cd roam-code
 pip install -e .
-pytest tests/   # All 669 tests must pass
+pytest tests/   # All 1656 tests must pass
 ```
 
 Good first contributions: add a [Tier 1 language](src/roam/languages/) (see `go_lang.py` or `php_lang.py` as templates), improve reference resolution, add benchmark repos, extend SARIF converters, add MCP tools.

{roam_code-7.5.0 → roam_code-8.0.0}/README.md

@@ -28,7 +28,7 @@ A semantic graph means Roam understands what functions call what, how modules de
 Codebase ──> [Index] ──> Semantic Graph ──> CLI ──> AI Agent
               │              │                │
            tree-sitter    symbols           one call
-           17 languages   + edges           replaces
+           22 languages   + edges           replaces
            git history    + metrics         5-10 tool calls
 ```
 
@@ -176,7 +176,7 @@ roam health
 
 ## Commands
 
-The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. 58 total commands are organized into 8 categories.
+The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. 55 total commands are organized into 7 categories.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -849,7 +849,7 @@ Codebase
     |
 [1] Discovery ──── git ls-files (respects .gitignore)
     |
-[2] Parse ──────── tree-sitter AST per file (17 languages)
+[2] Parse ──────── tree-sitter AST per file (22 languages)
     |
 [3] Extract ────── symbols + references (calls, imports, inheritance)
     |
@@ -988,7 +988,7 @@ Delete `.roam/` from your project root to clean up local data.
 git clone https://github.com/Cranot/roam-code.git
 cd roam-code
 pip install -e .
-pytest tests/   # 669 tests, Python 3.9-3.13
+pytest tests/   # 1656 tests, Python 3.9-3.13
 ```
 
 <details>
@@ -1001,7 +1001,7 @@ roam-code/
 ├── CHANGELOG.md
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (58 commands, 8 categories)
+│   ├── cli.py                         # Click CLI (55 commands, 7 categories)
 │   ├── mcp_server.py                  # MCP server (19 tools, 2 resources)
 │   ├── db/
 │   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
@@ -1013,8 +1013,8 @@ roam-code/
 │   │   ├── parser.py                  # Tree-sitter parsing
 │   │   ├── symbols.py                 # Symbol + reference extraction
 │   │   ├── relations.py               # Reference resolution -> edges
-│   │   ├── complexity.py              # Cognitive complexity (SonarSource)
-│   │   ├── git_stats.py               # Churn, co-change, blame, entropy
+│   │   ├── complexity.py              # Cognitive complexity (SonarSource) + Halstead metrics
+│   │   ├── git_stats.py               # Churn, co-change, blame, Renyi entropy
 │   │   └── incremental.py             # mtime + hash change detection
 │   ├── languages/
 │   │   ├── base.py                    # Abstract LanguageExtractor
@@ -1028,7 +1028,7 @@ roam-code/
 │   │   └── aggregator.py              # Cross-repo aggregation
 │   ├── graph/
 │   │   ├── builder.py, pagerank.py    # DB -> NetworkX, PageRank
-│   │   ├── cycles.py, clusters.py     # Tarjan SCC, Louvain
+│   │   ├── cycles.py, clusters.py     # Tarjan SCC, propagation cost, Louvain, modularity Q
 │   │   ├── layers.py, pathfinding.py  # Topo layers, k-shortest paths
 │   │   ├── split.py, why.py           # Decomposition, role classification
 │   ├── commands/
@@ -1037,7 +1037,7 @@ roam-code/
 │   └── output/
 │       ├── formatter.py               # Token-efficient formatting
 │       └── sarif.py                   # SARIF 2.1.0 output
-└── tests/                             # 669 tests across 11 test files
+└── tests/                             # 1656 tests across 28 test files
 ```
 
 </details>
@@ -1078,7 +1078,7 @@ Optional: [fastmcp](https://github.com/jlowin/fastmcp) (MCP server)
 git clone https://github.com/Cranot/roam-code.git
 cd roam-code
 pip install -e .
-pytest tests/   # All 669 tests must pass
+pytest tests/   # All 1656 tests must pass
 ```
 
 Good first contributions: add a [Tier 1 language](src/roam/languages/) (see `go_lang.py` or `php_lang.py` as templates), improve reference resolution, add benchmark repos, extend SARIF converters, add MCP tools.

{roam_code-7.5.0 → roam_code-8.0.0}/pyproject.toml

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

roam_code-8.0.0/src/roam/bridges/__init__.py

@@ -0,0 +1,2 @@
+"""Cross-language bridge framework for symbol resolution."""
+from __future__ import annotations

roam_code-8.0.0/src/roam/bridges/base.py

@@ -0,0 +1,49 @@
+"""Abstract base class for cross-language bridges."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class LanguageBridge(ABC):
+    """Base class for cross-language symbol resolution bridges.
+
+    A bridge resolves symbols that cross language boundaries:
+    - Protobuf .proto -> generated Go/Java/Python stubs
+    - Salesforce Apex -> Aura/LWC/Visualforce
+    - GraphQL schema -> TypeScript/Python codegen
+    - OpenAPI spec -> client SDKs
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Short identifier for this bridge (e.g. 'protobuf', 'salesforce')."""
+
+    @property
+    @abstractmethod
+    def source_extensions(self) -> frozenset[str]:
+        """File extensions this bridge reads from (e.g. frozenset({'.proto'}))."""
+
+    @property
+    @abstractmethod
+    def target_extensions(self) -> frozenset[str]:
+        """File extensions this bridge generates/links to."""
+
+    @abstractmethod
+    def detect(self, file_paths: list[str]) -> bool:
+        """Return True if this bridge is relevant for the given file set."""
+
+    @abstractmethod
+    def resolve(self, source_path: str, source_symbols: list[dict],
+                target_files: dict[str, list[dict]]) -> list[dict]:
+        """Resolve cross-language symbol links.
+
+        Args:
+            source_path: Path of the source file (e.g. foo.proto)
+            source_symbols: Symbols extracted from source_path
+            target_files: {path: [symbols]} for candidate target files
+
+        Returns:
+            List of edge dicts: [{"source": qualified_name, "target": qualified_name,
+                                   "kind": "x-lang", "bridge": self.name}]
+        """

roam_code-8.0.0/src/roam/bridges/bridge_protobuf.py

@@ -0,0 +1,337 @@
+"""Protobuf cross-language bridge: .proto -> generated stubs.
+
+Resolves cross-references between Protocol Buffer definitions and their
+generated code in various languages:
+- Python: *_pb2.py modules with classes matching message/service names
+- Go: *.pb.go files with CamelCase struct names
+- Java: OuterClass.MessageName pattern in *OuterClass.java
+- C++: *.pb.h / *.pb.cc with namespace::MessageName
+- TypeScript/JavaScript: *_pb.ts / *_pb.js
+"""
+from __future__ import annotations
+
+import os
+import re
+
+from roam.bridges.base import LanguageBridge
+from roam.bridges.registry import register_bridge
+
+
+# Proto source extension
+_PROTO_EXT = frozenset({".proto"})
+
+# Generated stub file patterns by language
+_GENERATED_PATTERNS: dict[str, re.Pattern] = {
+    "python": re.compile(r'_pb2\.pyi?$'),
+    "go": re.compile(r'\.pb\.go$'),
+    "java": re.compile(r'(?:OuterClass|Grpc|Proto)\.java$'),
+    "cpp_header": re.compile(r'\.pb\.h$'),
+    "cpp_source": re.compile(r'\.pb\.cc$'),
+    "typescript": re.compile(r'_pb\.(ts|d\.ts)$'),
+    "javascript": re.compile(r'_pb\.js$'),
+    "csharp": re.compile(r'\.g\.cs$'),
+    "ruby": re.compile(r'_pb\.rb$'),
+}
+
+# All target extensions that could be generated from .proto
+_TARGET_EXTS = frozenset({
+    ".py", ".pyi", ".go", ".java", ".h", ".cc", ".cpp",
+    ".ts", ".js", ".cs", ".rb",
+})
+
+# Pattern to extract package from proto file symbols
+_PROTO_PACKAGE_RE = re.compile(r'package\s+([\w.]+)')
+
+
+class ProtobufBridge(LanguageBridge):
+    """Bridge between .proto definitions and generated language stubs."""
+
+    @property
+    def name(self) -> str:
+        return "protobuf"
+
+    @property
+    def source_extensions(self) -> frozenset[str]:
+        return _PROTO_EXT
+
+    @property
+    def target_extensions(self) -> frozenset[str]:
+        return _TARGET_EXTS
+
+    def detect(self, file_paths: list[str]) -> bool:
+        """Detect if project has .proto files and potential generated stubs."""
+        has_proto = False
+        has_generated = False
+        for fp in file_paths:
+            ext = os.path.splitext(fp)[1].lower()
+            if ext == ".proto":
+                has_proto = True
+            # Check for generated stub patterns
+            basename = os.path.basename(fp)
+            for pattern in _GENERATED_PATTERNS.values():
+                if pattern.search(basename):
+                    has_generated = True
+                    break
+            if has_proto and has_generated:
+                return True
+        return False
+
+    def resolve(self, source_path: str, source_symbols: list[dict],
+                target_files: dict[str, list[dict]]) -> list[dict]:
+        """Resolve .proto symbols to their generated stubs.
+
+        Resolution strategies:
+        1. File naming: foo.proto -> foo_pb2.py, foo.pb.go, etc.
+        2. Symbol naming: message MyMessage -> class MyMessage (Python),
+           struct MyMessage (Go), MyMessage (Java inner class)
+        3. Service naming: service MyService -> MyServiceClient, MyServiceServer
+        """
+        edges: list[dict] = []
+        source_ext = os.path.splitext(source_path)[1].lower()
+
+        if source_ext != ".proto":
+            return edges
+
+        # Get the proto file stem (e.g., "foo" from "foo.proto")
+        proto_stem = os.path.basename(source_path).rsplit(".", 1)[0]
+
+        # Classify source symbols into messages, services, enums
+        messages = []
+        services = []
+        enums = []
+        for sym in source_symbols:
+            kind = sym.get("kind", "")
+            if kind in ("message", "class", "struct"):
+                messages.append(sym)
+            elif kind in ("service", "interface"):
+                services.append(sym)
+            elif kind == "enum":
+                enums.append(sym)
+
+        # Find generated target files that correspond to this proto
+        generated_targets = self._find_generated_files(proto_stem, target_files)
+
+        # For each generated file, try to match symbols
+        for tpath, tsymbols, lang in generated_targets:
+            target_symbol_names = {
+                sym.get("name", ""): sym.get("qualified_name", "")
+                for sym in tsymbols
+            }
+
+            # Match message symbols
+            for msg in messages:
+                msg_name = msg.get("name", "")
+                msg_qname = msg.get("qualified_name", msg_name)
+                matched = self._match_message(msg_name, target_symbol_names, lang)
+                for target_qname in matched:
+                    edges.append({
+                        "source": msg_qname,
+                        "target": target_qname,
+                        "kind": "x-lang",
+                        "bridge": self.name,
+                        "mechanism": "proto-message",
+                        "target_lang": lang,
+                    })
+
+            # Match service symbols
+            for svc in services:
+                svc_name = svc.get("name", "")
+                svc_qname = svc.get("qualified_name", svc_name)
+                matched = self._match_service(svc_name, target_symbol_names, lang)
+                for target_qname in matched:
+                    edges.append({
+                        "source": svc_qname,
+                        "target": target_qname,
+                        "kind": "x-lang",
+                        "bridge": self.name,
+                        "mechanism": "proto-service",
+                        "target_lang": lang,
+                    })
+
+            # Match enum symbols
+            for enum in enums:
+                enum_name = enum.get("name", "")
+                enum_qname = enum.get("qualified_name", enum_name)
+                matched = self._match_enum(enum_name, target_symbol_names, lang)
+                for target_qname in matched:
+                    edges.append({
+                        "source": enum_qname,
+                        "target": target_qname,
+                        "kind": "x-lang",
+                        "bridge": self.name,
+                        "mechanism": "proto-enum",
+                        "target_lang": lang,
+                    })
+
+        return edges
+
+    def _find_generated_files(self, proto_stem: str,
+                              target_files: dict[str, list[dict]]
+                              ) -> list[tuple[str, list[dict], str]]:
+        """Find target files that were likely generated from this proto.
+
+        Returns list of (path, symbols, language) tuples.
+        """
+        results = []
+        proto_lower = proto_stem.lower()
+
+        for tpath, tsymbols in target_files.items():
+            basename = os.path.basename(tpath).lower()
+
+            # Check each language pattern
+            for lang, pattern in _GENERATED_PATTERNS.items():
+                if pattern.search(basename):
+                    # Verify the stem matches the proto file
+                    # e.g., "foo_pb2.py" stem is "foo", "foo.pb.go" stem is "foo"
+                    generated_stem = self._extract_stem(basename, lang)
+                    if generated_stem and generated_stem == proto_lower:
+                        results.append((tpath, tsymbols, lang))
+                    break  # Only match one language per file
+
+        return results
+
+    def _extract_stem(self, basename: str, lang: str) -> str | None:
+        """Extract the original proto stem from a generated filename.
+
+        E.g., "foo_pb2.py" -> "foo", "foo.pb.go" -> "foo"
+        """
+        lower = basename.lower()
+        if lang == "python":
+            # foo_pb2.py or foo_pb2.pyi
+            m = re.match(r'^(.+)_pb2\.pyi?$', lower)
+            return m.group(1) if m else None
+        elif lang == "go":
+            # foo.pb.go
+            m = re.match(r'^(.+)\.pb\.go$', lower)
+            return m.group(1) if m else None
+        elif lang == "java":
+            # FooOuterClass.java or FooGrpc.java or FooProto.java
+            m = re.match(r'^(.+?)(?:outerclass|grpc|proto)\.java$', lower)
+            return m.group(1) if m else None
+        elif lang in ("cpp_header", "cpp_source"):
+            # foo.pb.h or foo.pb.cc
+            m = re.match(r'^(.+)\.pb\.(?:h|cc)$', lower)
+            return m.group(1) if m else None
+        elif lang == "typescript":
+            # foo_pb.ts or foo_pb.d.ts
+            m = re.match(r'^(.+)_pb\.(?:d\.)?ts$', lower)
+            return m.group(1) if m else None
+        elif lang == "javascript":
+            # foo_pb.js
+            m = re.match(r'^(.+)_pb\.js$', lower)
+            return m.group(1) if m else None
+        elif lang == "csharp":
+            # Foo.g.cs
+            m = re.match(r'^(.+)\.g\.cs$', lower)
+            return m.group(1) if m else None
+        elif lang == "ruby":
+            # foo_pb.rb
+            m = re.match(r'^(.+)_pb\.rb$', lower)
+            return m.group(1) if m else None
+        return None
+
+    def _match_message(self, msg_name: str, target_names: dict[str, str],
+                       lang: str) -> list[str]:
+        """Match a proto message name to generated symbols.
+
+        Naming conventions vary by language:
+        - Python: class MyMessage in *_pb2.py (exact name)
+        - Go: struct MyMessage in *.pb.go (CamelCase preserved)
+        - Java: inner class MyMessage inside OuterClass
+        - C++: class MyMessage in namespace
+        """
+        matched = []
+        msg_lower = msg_name.lower()
+
+        for sym_name, sym_qname in target_names.items():
+            sym_lower = sym_name.lower()
+
+            # Exact match (most common for Python, Go, C++)
+            if sym_lower == msg_lower:
+                matched.append(sym_qname)
+                continue
+
+            # Go: proto snake_case -> CamelCase
+            # e.g., my_message -> MyMessage
+            if lang == "go" and self._snake_to_camel(msg_name).lower() == sym_lower:
+                matched.append(sym_qname)
+                continue
+
+            # Java: OuterClass.MessageName pattern
+            if lang == "java" and sym_lower.endswith("." + msg_lower):
+                matched.append(sym_qname)
+                continue
+
+        return matched
+
+    def _match_service(self, svc_name: str, target_names: dict[str, str],
+                       lang: str) -> list[str]:
+        """Match a proto service name to generated symbols.
+
+        Generated service stubs commonly use suffixes:
+        - Python: MyServiceStub, MyServiceServicer
+        - Go: MyServiceClient, MyServiceServer
+        - Java: MyServiceGrpc, MyServiceBlockingStub
+        """
+        matched = []
+        svc_lower = svc_name.lower()
+
+        # Common generated suffixes for service stubs
+        suffixes = [
+            "",  # exact match
+            "client", "server", "stub", "servicer",
+            "grpc", "blockingstub", "futurestub",
+            "implbase",
+        ]
+
+        for sym_name, sym_qname in target_names.items():
+            sym_lower = sym_name.lower()
+            for suffix in suffixes:
+                if sym_lower == svc_lower + suffix:
+                    matched.append(sym_qname)
+                    break
+                # Also check with underscore separator (Python style)
+                if suffix and sym_lower == svc_lower + "_" + suffix:
+                    matched.append(sym_qname)
+                    break
+
+        return matched
+
+    def _match_enum(self, enum_name: str, target_names: dict[str, str],
+                    lang: str) -> list[str]:
+        """Match a proto enum name to generated symbols.
+
+        Enums generally keep their name across languages.
+        """
+        matched = []
+        enum_lower = enum_name.lower()
+
+        for sym_name, sym_qname in target_names.items():
+            sym_lower = sym_name.lower()
+
+            # Exact match
+            if sym_lower == enum_lower:
+                matched.append(sym_qname)
+                continue
+
+            # Go CamelCase conversion
+            if lang == "go" and self._snake_to_camel(enum_name).lower() == sym_lower:
+                matched.append(sym_qname)
+                continue
+
+        return matched
+
+    def _snake_to_camel(self, name: str) -> str:
+        """Convert snake_case to CamelCase.
+
+        E.g., my_message -> MyMessage, already_camel -> AlreadyCamel
+        """
+        if "_" not in name:
+            # Already CamelCase or single word; just capitalize first letter
+            return name[0].upper() + name[1:] if name else name
+        parts = name.split("_")
+        return "".join(p.capitalize() for p in parts if p)
+
+
+# Auto-register on import
+register_bridge(ProtobufBridge())