ruth-code 0.1.0__py3-none-any.whl

ruth/__init__.py

@@ -0,0 +1,3 @@
+"""Ruth — Interactive Codebase Topology Visualizer."""
+
+__version__ = "0.1.0"

ruth/annotations/__init__.py

@@ -0,0 +1 @@
+"""Ruth annotations package — complexity scoring, coverage, vulnerability overlays."""

ruth/annotations/complexity.py

@@ -0,0 +1,128 @@
+"""Cyclomatic complexity scoring for source code.
+
+Uses a regex-based approach to count decision points:
+  - if, elif, else, for, while, except, with, case (Python)
+  - if, else if, for, while, catch, switch, case, ternary (JS/TS)
+  - match, if, loop, while, for (Rust)
+  - etc.
+
+Returns a normalized 0-100 score where:
+  0-20:  Low complexity
+  20-40: Moderate
+  40-60: High
+  60-80: Very High
+  80-100: Critical
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Callable
+
+# ── Language-specific decision point patterns ──────────────────────────
+
+_PYTHON_BRANCHES = re.compile(
+    r"\b(if|elif|for|while|except|with|and|or|assert)\b", re.MULTILINE
+)
+
+_JS_BRANCHES = re.compile(
+    r"\b(if|else\s+if|for|while|do|catch|case|switch|\?\s*|&&|\|\|)\b", re.MULTILINE
+)
+
+_RUST_BRANCHES = re.compile(
+    r"\b(if|else\s+if|match|for|while|loop|=>|&&|\|\|)\b", re.MULTILINE
+)
+
+_GO_BRANCHES = re.compile(
+    r"\b(if|else\s+if|for|switch|case|select|&&|\|\|)\b", re.MULTILINE
+)
+
+_JAVA_BRANCHES = re.compile(
+    r"\b(if|else\s+if|for|while|do|catch|case|switch|\?|&&|\|\|)\b", re.MULTILINE
+)
+
+_C_BRANCHES = re.compile(
+    r"\b(if|else\s+if|for|while|do|case|switch|\?|&&|\|\|)\b", re.MULTILINE
+)
+
+_RUBY_BRANCHES = re.compile(
+    r"\b(if|elsif|unless|while|until|for|rescue|when|and|or)\b", re.MULTILINE
+)
+
+
+BRANCH_PATTERNS: dict[str, re.Pattern] = {
+    "python":     _PYTHON_BRANCHES,
+    "typescript":  _JS_BRANCHES,
+    "javascript":  _JS_BRANCHES,
+    "rust":        _RUST_BRANCHES,
+    "go":          _GO_BRANCHES,
+    "java":        _JAVA_BRANCHES,
+    "c":           _C_BRANCHES,
+    "cpp":         _C_BRANCHES,
+    "ruby":        _RUBY_BRANCHES,
+}
+
+
+def _strip_comments(content: str, language: str) -> str:
+    """Remove comments and strings to avoid false positives."""
+    # Remove single-line comments
+    if language in ("python", "ruby"):
+        content = re.sub(r"#.*$", "", content, flags=re.MULTILINE)
+    else:
+        content = re.sub(r"//.*$", "", content, flags=re.MULTILINE)
+
+    # Remove multi-line comments
+    if language == "python":
+        content = re.sub(r'""".*?"""', "", content, flags=re.DOTALL)
+        content = re.sub(r"'''.*?'''", "", content, flags=re.DOTALL)
+    elif language in ("c", "cpp", "java", "javascript", "typescript", "go", "rust"):
+        content = re.sub(r"/\*.*?\*/", "", content, flags=re.DOTALL)
+
+    # Remove strings (simplified — avoids counting keywords in strings)
+    content = re.sub(r'"(?:[^"\\]|\\.)*"', '""', content)
+    content = re.sub(r"'(?:[^'\\]|\\.)*'", "''", content)
+
+    return content
+
+
+def compute_complexity(content: str, language: str) -> int | None:
+    """Compute a normalized complexity score for a source file.
+
+    Args:
+        content: The file content.
+        language: The programming language.
+
+    Returns:
+        An integer 0-100, or None if language is unsupported.
+    """
+    pattern = BRANCH_PATTERNS.get(language)
+    if pattern is None:
+        return None
+
+    cleaned = _strip_comments(content, language)
+    line_count = cleaned.count("\n") + 1
+
+    if line_count == 0:
+        return 0
+
+    # Count decision points
+    branch_count = len(pattern.findall(cleaned))
+
+    # Base complexity = 1 (every function has at least one path)
+    # Cyclomatic = branches + 1
+    cyclomatic = branch_count + 1
+
+    # Normalize to 0-100 scale
+    # Heuristic: density of branches per 100 lines
+    density = (branch_count / max(line_count, 1)) * 100
+
+    # Combine raw count and density
+    # A 50-line file with 20 branches is more complex than a 500-line file with 20 branches
+    raw_score = min(100, int(density * 2.5 + cyclomatic * 0.3))
+
+    return max(0, min(100, raw_score))
+
+
+def compute_function_complexity(body: str, language: str) -> int | None:
+    """Compute complexity for a single function body."""
+    return compute_complexity(body, language)

ruth/annotations/coverage.py

@@ -0,0 +1,106 @@
+"""Coverage ingestion for Ruth.
+
+Reads coverage data from standard formats:
+  - lcov.info (from Istanbul/nyc, gcov, etc.)
+  - coverage.json (Python coverage.py)
+  - cobertura XML
+
+Maps coverage percentages back to source file paths.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+def load_coverage(project_root: Path) -> dict[str, float]:
+    """Auto-detect and load coverage data from a project.
+
+    Returns:
+        Dict mapping relative file paths to coverage percentage (0-100).
+    """
+    coverage: dict[str, float] = {}
+
+    # Try lcov
+    lcov_paths = [
+        project_root / "coverage" / "lcov.info",
+        project_root / "lcov.info",
+        project_root / "coverage" / "lcov" / "lcov.info",
+    ]
+    for p in lcov_paths:
+        if p.exists():
+            coverage.update(_parse_lcov(p, project_root))
+            return coverage
+
+    # Try coverage.json (Python)
+    cov_json_paths = [
+        project_root / "coverage.json",
+        project_root / "htmlcov" / "status.json",
+    ]
+    for p in cov_json_paths:
+        if p.exists():
+            coverage.update(_parse_coverage_json(p, project_root))
+            return coverage
+
+    # Try .coverage (Python coverage.py SQLite DB — just detect it)
+    dot_coverage = project_root / ".coverage"
+    if dot_coverage.exists():
+        # Can't parse SQLite easily without coverage lib, skip
+        pass
+
+    return coverage
+
+
+def _parse_lcov(path: Path, project_root: Path) -> dict[str, float]:
+    """Parse lcov.info format."""
+    coverage: dict[str, float] = {}
+    current_file = None
+    lines_hit = 0
+    lines_found = 0
+
+    for line in path.read_text(errors="ignore").splitlines():
+        line = line.strip()
+        if line.startswith("SF:"):
+            current_file = line[3:]
+            lines_hit = 0
+            lines_found = 0
+        elif line.startswith("LH:"):
+            lines_hit = int(line[3:])
+        elif line.startswith("LF:"):
+            lines_found = int(line[3:])
+        elif line == "end_of_record" and current_file:
+            pct = (lines_hit / lines_found * 100) if lines_found > 0 else 0
+            try:
+                rel = str(Path(current_file).resolve().relative_to(project_root.resolve()))
+            except ValueError:
+                rel = current_file
+            coverage[rel] = round(pct, 1)
+            current_file = None
+
+    return coverage
+
+
+def _parse_coverage_json(path: Path, project_root: Path) -> dict[str, float]:
+    """Parse Python coverage.py JSON report."""
+    try:
+        data = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+    coverage: dict[str, float] = {}
+
+    # coverage.py format
+    files = data.get("files", {})
+    for file_path, file_data in files.items():
+        summary = file_data.get("summary", {})
+        pct = summary.get("percent_covered", 0)
+        try:
+            rel = str(Path(file_path).resolve().relative_to(project_root.resolve()))
+        except ValueError:
+            rel = file_path
+        coverage[rel] = round(pct, 1)
+
+    return coverage

ruth/cli.py

@@ -0,0 +1,167 @@
+"""Ruth CLI — entry point for `ruth serve` and related commands."""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+@click.group()
+@click.version_option(package_name="ruth")
+def cli():
+    """Ruth — Interactive Codebase Topology Visualizer.
+
+    Parses your codebase, builds a dependency/call graph, overlays code quality
+    and security metadata, then renders it as an explorable visual map.
+    """
+    pass
+
+
+@cli.command()
+@click.argument("path", default=".", type=click.Path(exists=True))
+@click.option("--port", "-p", default=4150, help="Port to serve the dashboard on.")
+@click.option("--host", "-h", default="127.0.0.1", help="Host to bind to.")
+@click.option("--no-open", is_flag=True, help="Don't auto-open the browser.")
+def serve(path: str, port: int, host: str, no_open: bool):
+    """Start Ruth server and launch the visualization dashboard.
+
+    PATH is the root directory of the codebase to analyze (defaults to current dir).
+    """
+    import webbrowser
+    from pathlib import Path as P
+    from ruth.server import create_app
+    from ruth.parser.discovery import discover_files
+
+    project_root = P(path).resolve()
+
+    console.print()
+    console.print("[bold cyan]◈ ruth[/bold cyan] [dim]v0.1.0[/dim]")
+    console.print()
+
+    # Quick scan to show stats
+    with console.status("[dim]Scanning project...[/dim]"):
+        discovery = discover_files(project_root)
+
+    # Stats table
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style="dim")
+    table.add_column(style="bold")
+    table.add_row("Project", str(project_root))
+    table.add_row("Files", str(len(discovery.files)))
+    table.add_row("Lines", f"{discovery.total_lines:,}")
+    table.add_row("Languages", ", ".join(sorted(discovery.languages)) or "—")
+    table.add_row("Directories", str(len(discovery.directories)))
+    if discovery.skipped:
+        table.add_row("Skipped", str(discovery.skipped))
+    console.print(table)
+    console.print()
+    console.print(f"  [dim]Dashboard:[/dim]  [link=http://{host}:{port}]http://{host}:{port}[/link]")
+    console.print()
+
+    app = create_app(path)
+
+    if not no_open:
+        webbrowser.open(f"http://{host}:{port}")
+
+    import uvicorn
+    uvicorn.run(app, host=host, port=port, log_level="warning")
+
+
+@cli.command()
+@click.argument("path", default=".", type=click.Path(exists=True))
+@click.option("--output", "-o", default=None, help="Output JSON file for the graph.")
+@click.option("--granularity", "-g", default="module",
+              type=click.Choice(["module", "class", "function"]),
+              help="Node granularity level.")
+def analyze(path: str, output: str | None, granularity: str):
+    """Analyze a codebase and output the dependency graph as JSON.
+
+    PATH is the root directory of the codebase to analyze.
+    """
+    import json
+    from pathlib import Path as P
+    from ruth.parser.discovery import discover_files
+    from ruth.graph.engine import build_graph
+    from ruth.annotations.coverage import load_coverage
+
+    project_root = P(path).resolve()
+
+    with console.status("[dim]Analyzing codebase...[/dim]"):
+        discovery = discover_files(project_root)
+        graph = build_graph(discovery, project_root, granularity=granularity)
+        coverage_data = load_coverage(project_root)
+        if coverage_data:
+            for node in graph["nodes"]:
+                rel_path = node["data"]["filePath"]
+                if rel_path in coverage_data:
+                    node["data"]["annotations"]["coverage"] = coverage_data[rel_path]
+
+    # Summary
+    console.print()
+    console.print("[bold cyan]◈ ruth[/bold cyan] analysis complete")
+    console.print()
+    console.print(f"  [dim]Files:[/dim]      {len(discovery.files)}")
+    console.print(f"  [dim]Nodes:[/dim]      {len(graph['nodes'])}")
+    console.print(f"  [dim]Edges:[/dim]      {len(graph['edges'])}")
+    console.print(f"  [dim]Languages:[/dim]  {', '.join(graph['languages']) or '—'}")
+    console.print()
+
+    if output:
+        with open(output, "w") as f:
+            json.dump(graph, f, indent=2)
+        console.print(f"  [green]✓[/green] Graph written to [bold]{output}[/bold]")
+    else:
+        console.print_json(json.dumps(graph, indent=2))
+
+
+@cli.command()
+@click.argument("path", default=".", type=click.Path(exists=True))
+def scan(path: str):
+    """Quick scan — show project stats without building the full graph."""
+    from pathlib import Path as P
+    from ruth.parser.discovery import discover_files
+
+    project_root = P(path).resolve()
+
+    with console.status("[dim]Scanning...[/dim]"):
+        discovery = discover_files(project_root)
+
+    console.print()
+    console.print("[bold cyan]◈ ruth[/bold cyan] scan")
+    console.print()
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style="dim")
+    table.add_column(style="bold")
+    table.add_row("Project", project_root.name)
+    table.add_row("Files", str(len(discovery.files)))
+    table.add_row("Lines", f"{discovery.total_lines:,}")
+    table.add_row("Languages", ", ".join(sorted(discovery.languages)) or "—")
+    table.add_row("Directories", str(len(discovery.directories)))
+    if discovery.skipped:
+        table.add_row("Skipped", str(discovery.skipped))
+    console.print(table)
+    console.print()
+
+    # Per-language breakdown
+    lang_counts: dict[str, int] = {}
+    lang_lines: dict[str, int] = {}
+    for f in discovery.files:
+        lang_counts[f.language] = lang_counts.get(f.language, 0) + 1
+        lang_lines[f.language] = lang_lines.get(f.language, 0) + f.line_count
+
+    if lang_counts:
+        lang_table = Table(title="Language Breakdown")
+        lang_table.add_column("Language", style="bold")
+        lang_table.add_column("Files", justify="right")
+        lang_table.add_column("Lines", justify="right")
+        for lang in sorted(lang_counts, key=lambda l: lang_lines[l], reverse=True):
+            lang_table.add_row(lang, str(lang_counts[lang]), f"{lang_lines[lang]:,}")
+        console.print(lang_table)
+
+
+if __name__ == "__main__":
+    cli()

ruth/graph/__init__.py

@@ -0,0 +1 @@
+"""Ruth graph package — builds dependency/call graphs from parsed symbols."""