ripple-sql 0.1.0__py3-none-any.whl

ripple/doctor.py

@@ -0,0 +1,225 @@
+"""`ripple doctor`: prove this install can serve an MCP client before a client tries.
+
+The documented MCP failure modes are environmental: the client spawns the wrong
+python, the server prints something that isn't JSON-RPC, or startup blows the
+client's budget (Codex kills servers at 10s). All of them look identical from
+the client side: the tool "connects and then does nothing." So the doctor does
+what a client does: spawns this install's server from an undefined working
+directory and drives a real handshake through it.
+
+Warnings never fail the command; only a broken handshake does (exit 1).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+PASS, WARN, FAIL = "ok", "warning", "failed"
+GLYPH = {PASS: "✓", WARN: "!", FAIL: "✗"}
+
+# Codex gives a server 10s to start; stay comfortably under it.
+STARTUP_BUDGET_SECONDS = 5.0
+
+
+def _version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("ripple-sql")
+    except Exception:
+        return "unknown"
+
+
+def server_command() -> list[str]:
+    """The command a client should be given, absolute paths only.
+
+    Clients spawn stdio servers with a minimal environment and an undefined
+    working directory, so a bare `ripple` that depends on the user's shell
+    PATH is exactly what breaks.
+    """
+    exe = shutil.which("ripple")
+    if exe:
+        return [str(Path(exe).resolve()), "mcp"]
+    # sys.argv[1:] forwards appended flags: without it the printed
+    # `... --path <project>` was decoration and the server silently served
+    # the client's working directory, usually /
+    return [
+        sys.executable,
+        "-c",
+        "import sys; from ripple.cli import main; main(['mcp'] + sys.argv[1:])",
+    ]
+
+
+def _check_install() -> dict:
+    return {
+        "name": "install",
+        "status": PASS,
+        "detail": f"ripple {_version()} on python {sys.version.split()[0]} at {sys.executable}",
+    }
+
+
+def _check_path() -> dict:
+    exe = shutil.which("ripple")
+    if exe is None:
+        return {
+            "name": "ripple on PATH",
+            "status": WARN,
+            "detail": (
+                "no `ripple` on PATH (fine for uvx; otherwise give your client "
+                "the absolute command printed below)"
+            ),
+        }
+    # no resolve(): a venv python is a symlink out of the venv, and following
+    # it would flag every healthy venv as a mismatch
+    same_env = Path(exe).parent == Path(sys.executable).parent
+    if not same_env:
+        return {
+            "name": "ripple on PATH",
+            "status": WARN,
+            "detail": (
+                f"{exe} belongs to a different environment than this python "
+                f"({sys.executable}); a client using the PATH one may get a "
+                "different ripple version"
+            ),
+        }
+    return {"name": "ripple on PATH", "status": PASS, "detail": exe}
+
+
+def _check_handshake(command: list[str]) -> list[dict]:
+    requests = [
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2025-06-18",
+                "capabilities": {},
+                "clientInfo": {"name": "ripple-doctor", "version": _version()},
+            },
+        },
+        {"jsonrpc": "2.0", "method": "notifications/initialized"},
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+    ]
+    payload = "".join(json.dumps(r) + "\n" for r in requests)
+    started = time.monotonic()
+    try:
+        # cwd "/" reproduces the undefined working directory clients start
+        # servers from; initialize and tools/list must not touch the filesystem
+        proc = subprocess.run(
+            command,
+            input=payload,
+            capture_output=True,
+            text=True,
+            cwd="/",
+            timeout=30,
+        )
+    except subprocess.TimeoutExpired:
+        return [
+            {
+                "name": "mcp handshake",
+                "status": FAIL,
+                "detail": f"server did not answer within 30s: {' '.join(command)}",
+            }
+        ]
+    except OSError as e:
+        return [
+            {
+                "name": "mcp handshake",
+                "status": FAIL,
+                "detail": f"could not start {' '.join(command)}: {e}",
+            }
+        ]
+    elapsed = time.monotonic() - started
+
+    checks: list[dict] = []
+    responses = {}
+    dirty = None
+    for raw in proc.stdout.splitlines():
+        if not raw.strip():
+            continue
+        try:
+            message = json.loads(raw)
+            if message.get("jsonrpc") != "2.0":
+                raise ValueError("not a JSON-RPC message")
+        except ValueError:
+            dirty = raw
+            continue
+        responses[message.get("id")] = message
+
+    init = responses.get(1, {}).get("result", {})
+    tools = responses.get(2, {}).get("result", {}).get("tools", [])
+    if init.get("serverInfo", {}).get("name") == "ripple" and tools:
+        checks.append(
+            {
+                "name": "mcp handshake",
+                "status": PASS,
+                "detail": f"initialize + tools/list answered, {len(tools)} tools",
+            }
+        )
+    else:
+        checks.append(
+            {
+                "name": "mcp handshake",
+                "status": FAIL,
+                "detail": (
+                    f"no valid handshake from {' '.join(command)}"
+                    + (f"; stderr: {proc.stderr.strip()[:300]}" if proc.stderr.strip() else "")
+                ),
+            }
+        )
+
+    checks.append(
+        {
+            "name": "clean stdout",
+            "status": PASS if dirty is None else FAIL,
+            "detail": (
+                "every stdout line is JSON-RPC"
+                if dirty is None
+                else f"stdout carried a non-protocol line, which breaks clients: {dirty[:200]!r}"
+            ),
+        }
+    )
+    slow = elapsed > STARTUP_BUDGET_SECONDS
+    checks.append(
+        {
+            "name": "startup speed",
+            "status": WARN if slow else PASS,
+            "detail": f"handshake took {elapsed:.1f}s"
+            + (" (Codex allows 10s; investigate)" if slow else ""),
+        }
+    )
+    return checks
+
+
+def run(as_json: bool = False) -> int:
+    command = server_command()
+    checks = [_check_install(), _check_path(), *_check_handshake(command)]
+    ok = all(c["status"] != FAIL for c in checks)
+
+    if as_json:
+        print(json.dumps({"ok": ok, "command": command, "checks": checks}, indent=2))
+        return 0 if ok else 1
+
+    for check in checks:
+        print(f"[{GLYPH[check['status']]}] {check['name']}: {check['detail']}")
+    print()
+    if ok:
+        project = Path(os.getcwd()).resolve()
+        print("This install can serve MCP clients. Point yours at it with absolute paths")
+        print("(clients often start servers from / with a minimal environment):")
+        import shlex
+
+        # shlex, not join: the no-binary fallback is python -c "import ...; ..."
+        # and unquoted it splits at the semicolon when pasted into a shell
+        printable = shlex.join([*command, "--path", str(project)])
+        print(f"  {printable}")
+        print(f"  e.g.  claude mcp add ripple -- {printable}")
+    else:
+        print("Something above is broken. Attach `ripple doctor --json` to a bug report.")
+    return 0 if ok else 1

ripple/engine/__init__.py

@@ -0,0 +1,111 @@
+"""SQL analysis engine.
+
+Works on any SQL, dbt projects or plain files alike.
+
+Key exports:
+
+Column Lineage (C_con - Contributing Columns):
+- extract_column_lineage_fast: Fast single-pass column extraction
+- extract_column_lineage_with_ctes: Full extraction with CTE mappings
+- extract_cte_column_lineage: Per-CTE column lineage
+- extract_cte_column_mappings: CTE name -> column mappings
+- extract_primary_source_from_macro: Primary source detection
+- trace_through_ctes: Recursive CTE tracing
+- extract_lineage_complete: Unified API with C_con + C_ref
+
+Column Dependencies (C_ref - Referenced Columns):
+- extract_column_dependencies: WHERE/HAVING/QUALIFY clause columns
+- extract_all_referenced_columns: All column references with context
+
+Types:
+- FilterDependency: Column used in filter clauses
+- JoinKeyPair: Columns used in JOIN conditions
+- ColumnDependencies: Complete C_ref result
+- UnifiedLineageResult: Combined C_con + C_ref
+
+Tech Debt:
+- analyze_unused_deps_safe: Find unused JOINs/CTEs safely
+- get_analysis_limited_message: Human-readable limitation explanation
+
+Dialect Mapping:
+- ADAPTER_TO_SQLGLOT_DIALECT: Adapter -> SQLGlot dialect mapping
+- DEFAULT_DIALECT: Default dialect (snowflake)
+- get_sqlglot_dialect: Get dialect from dbt manifest
+- get_dialect_from_adapter_type: Get dialect from adapter type string
+- get_dialect_from_config: Get dialect from a config dict with adapter_type
+- get_supported_adapters: List of supported adapter types
+"""
+
+# Column lineage (main extraction)
+from ripple.engine.column_lineage import (
+    extract_column_lineage_fast,
+    extract_column_lineage_with_ctes,
+    extract_cte_column_lineage,
+    extract_cte_column_mappings,
+    extract_lineage_complete,
+    extract_primary_source_from_macro,
+    trace_through_ctes,
+)
+
+# Column dependencies (C_ref)
+from ripple.engine.dependencies import (
+    extract_all_referenced_columns,
+    extract_column_dependencies,
+)
+
+# Dialect mapping
+from ripple.engine.dialect import (
+    ADAPTER_TO_SQLGLOT_DIALECT,
+    DEFAULT_DIALECT,
+    get_dialect_from_adapter_type,
+    get_dialect_from_config,
+    get_sqlglot_dialect,
+    get_supported_adapters,
+)
+
+# Tech debt analysis
+from ripple.engine.tech_debt import (
+    analyze_unused_deps_safe,
+    get_analysis_limited_message,
+)
+
+# Types
+from ripple.engine.types import (
+    ColumnDependencies,
+    FilterDependency,
+    JoinKeyPair,
+    TrustLevel,
+    UnifiedLineageResult,
+    WarehouseColumns,
+)
+
+__all__ = [
+    # Column lineage (C_con)
+    "extract_column_lineage_fast",
+    "extract_column_lineage_with_ctes",
+    "extract_cte_column_lineage",
+    "extract_cte_column_mappings",
+    "extract_primary_source_from_macro",
+    "trace_through_ctes",
+    "extract_lineage_complete",
+    # Column dependencies (C_ref) - NEW
+    "extract_column_dependencies",
+    "extract_all_referenced_columns",
+    # Types - NEW
+    "TrustLevel",
+    "WarehouseColumns",
+    "FilterDependency",
+    "JoinKeyPair",
+    "ColumnDependencies",
+    "UnifiedLineageResult",
+    # Tech debt
+    "analyze_unused_deps_safe",
+    "get_analysis_limited_message",
+    # Dialect
+    "ADAPTER_TO_SQLGLOT_DIALECT",
+    "DEFAULT_DIALECT",
+    "get_dialect_from_adapter_type",
+    "get_dialect_from_config",
+    "get_sqlglot_dialect",
+    "get_supported_adapters",
+]

ripple/engine/budget.py

@@ -0,0 +1,86 @@
+"""Wall-clock budget for per-file work that can wedge.
+
+Pathological SQL can wedge sqlglot for half an hour: redshift-utils admin DDL
+at parse time, and a generated 3.7MB single-line SELECT that parses in 13s and
+then spends another 139s inside qualify_tables during analysis. One budget
+covers both phases (RIPPLE_PARSE_BUDGET_S, default 20s, 0 disables).
+
+Work runs on a daemon thread abandoned at the budget. An abandoned thread
+stays busy until process exit, so after MAX_ABANDONED of them further budgeted
+work is not attempted and reports timed out immediately.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from collections.abc import Callable
+from typing import Any
+
+MAX_ABANDONED = 8
+_abandoned = 0  # kept for tests that pin the cap; the live count is _zombies
+_zombies: list[threading.Thread] = []
+
+TIMED_OUT = object()
+
+
+def _alive_zombies() -> int:
+    """Abandoned workers still burning CPU. A cumulative count never reset,
+    so a long-lived MCP session that had ever abandoned eight parses refused
+    every budgeted call after that, and each rebuild reported the whole repo
+    as timed_out."""
+    _zombies[:] = [t for t in _zombies if t.is_alive()]
+    return len(_zombies)
+
+
+def budget_seconds() -> float:
+    try:
+        return float(os.environ.get("RIPPLE_PARSE_BUDGET_S", "20"))
+    except ValueError:
+        return 20.0
+
+
+def max_sql_bytes() -> int:
+    """Statements over this size are refused before any parse or analysis.
+
+    Preferable to the thread budget wherever it applies: an abandoned worker
+    keeps holding the GIL, slowing everything after it, while a size refusal
+    costs nothing. 0 disables."""
+    try:
+        return int(os.environ.get("RIPPLE_MAX_SQL_BYTES", "1000000"))
+    except ValueError:
+        return 1_000_000
+
+
+def run_within_budget(label: str, fn: Callable[[], Any], budget: float | None = None):
+    """fn() under a wall-clock cap; returns TIMED_OUT when the budget blows.
+
+    fn must not mutate shared state: an abandoned worker runs to completion in
+    the background, and anything it wrote would race the caller.
+    """
+    global _abandoned
+    if budget is None:
+        budget = budget_seconds()
+    if budget <= 0:
+        return fn()
+    if max(_abandoned, _alive_zombies()) >= MAX_ABANDONED:
+        return TIMED_OUT
+    box: list = []
+
+    def run():
+        try:
+            box.append(fn())
+        except Exception as e:
+            box.append(e)
+
+    worker = threading.Thread(target=run, daemon=True, name=f"ripple-budget-{label}")
+    worker.start()
+    worker.join(budget)
+    if worker.is_alive():
+        _zombies.append(worker)
+        _abandoned = 0  # the live list is the count; _abandoned only pins tests
+        return TIMED_OUT
+    result = box[0] if box else None
+    if isinstance(result, Exception):
+        raise result
+    return result

ripple/engine/column_lineage.py

@@ -0,0 +1,112 @@
+"""Column lineage: re-exports from the engine submodules.
+
+Re-exports the engine's public functions from one place. Prefer importing from
+the specific submodule.
+
+Submodules:
+- types.py: Type definitions and dataclasses
+- schema_qualification.py: Warehouse schema disambiguation
+- validation.py: Trust scoring and UNION validation
+- cte_tracing.py: CTE extraction and recursive tracing
+- extraction.py: Main extraction entry points
+- dependencies.py: WHERE/JOIN column tracking (C_ref)
+
+Example:
+    from ripple.engine.extraction import extract_column_lineage_fast
+    from ripple.engine.dependencies import extract_column_dependencies
+"""
+
+# Types (from types.py)
+# CTE tracing (from cte_tracing.py)
+from ripple.engine.cte_tracing import (
+    extract_cte_column_lineage,
+    extract_cte_column_mappings,
+    trace_through_ctes,
+)
+
+# Dependencies (from dependencies.py)
+from ripple.engine.dependencies import (
+    extract_all_referenced_columns,
+    extract_column_dependencies,
+)
+
+# Main extraction (from extraction.py)
+from ripple.engine.extraction import (
+    extract_column_lineage_fast,
+    extract_column_lineage_with_ctes,
+    extract_lineage_complete,
+    extract_primary_source_from_macro,
+)
+
+# Schema qualification (from schema_qualification.py)
+from ripple.engine.schema_qualification import (
+    # Underscore-prefixed aliases
+    _build_sqlglot_schema,
+    _qualify_sql_with_schema,
+    _resolve_column_table,
+    build_sqlglot_schema,
+    qualify_sql_with_schema,
+    resolve_column_table,
+)
+from ripple.engine.types import (
+    MAX_REAL_TABLES,
+    MAX_SQL_LENGTH,
+    MAX_WAREHOUSE_TABLES,
+    ColumnDependencies,
+    FilterDependency,
+    JoinKeyPair,
+    TrustLevel,
+    UnifiedLineageResult,
+    WarehouseColumns,
+)
+
+# Validation (from validation.py)
+from ripple.engine.validation import (
+    _get_select_column_names,
+    # Underscore-prefixed aliases
+    _get_trust_level,
+    _validate_union_columns,
+    get_select_column_names,
+    get_trust_level,
+    validate_union_columns,
+)
+
+__all__ = [
+    # Main extraction functions
+    "extract_column_lineage_fast",
+    "extract_column_lineage_with_ctes",
+    "extract_lineage_complete",
+    # CTE functions
+    "extract_cte_column_lineage",
+    "extract_cte_column_mappings",
+    "extract_primary_source_from_macro",
+    "trace_through_ctes",
+    # Dependency extraction
+    "extract_column_dependencies",
+    "extract_all_referenced_columns",
+    # Types
+    "TrustLevel",
+    "WarehouseColumns",
+    "FilterDependency",
+    "JoinKeyPair",
+    "ColumnDependencies",
+    "UnifiedLineageResult",
+    # Constants
+    "MAX_WAREHOUSE_TABLES",
+    "MAX_REAL_TABLES",
+    "MAX_SQL_LENGTH",
+    # Public helpers
+    "build_sqlglot_schema",
+    "resolve_column_table",
+    "qualify_sql_with_schema",
+    "get_trust_level",
+    "get_select_column_names",
+    "validate_union_columns",
+    # Underscore-prefixed aliases
+    "_build_sqlglot_schema",
+    "_resolve_column_table",
+    "_qualify_sql_with_schema",
+    "_get_trust_level",
+    "_validate_union_columns",
+    "_get_select_column_names",
+]