ripple-sql 0.1.0__py3-none-any.whl

ripple/answer_page.py

@@ -0,0 +1,214 @@
+"""The answer page: one self-contained HTML file per question.
+
+The same component the public demo uses, pointed at the user's own repo.
+It reads the answer contract and the terminal's text twin, and when the
+graph export fits the size budget it embeds the whole graph so the page
+can answer a follow-up question by itself, with no server behind it.
+
+Nothing here talks to the network. The page loads no fonts, scripts, or
+images from anywhere; it is a file. `ripple serve` renders the same template
+live (render_live), where the question box asks the local server instead.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import os
+import re
+import webbrowser
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+TEMPLATE = Path(__file__).parent / "static" / "answer.html"
+STYLE = Path(__file__).parent / "static" / "answer.css"
+TWIN = Path(__file__).parent / "static" / "answer_twin.js"
+EXPLORE = Path(__file__).parent / "static" / "explore.js"
+EMBED_BUDGET_ENV = "RIPPLE_EMBED_GRAPH_BYTES"
+DEFAULT_EMBED_BUDGET = 5_000_000
+TRUST_CODE = {"verified": "v", "high_confidence": "h", "moderate": "m", "review_required": "r"}
+
+
+def embed_budget() -> int:
+    """Bytes of graph export the page will carry so follow-ups work offline.
+    Above it the page carries the answer alone and says so. 0 disables."""
+    try:
+        return int(os.environ.get(EMBED_BUDGET_ENV, str(DEFAULT_EMBED_BUDGET)))
+    except ValueError:
+        return DEFAULT_EMBED_BUDGET
+
+
+def compact_edges(edges) -> dict:
+    """The graph as the page carries it: {"edges": rows, "reasons": strings}.
+
+    A row is [src, dst, trust code], then the kind when the link is not a
+    value link, then the index of its reason when it has one (the kind slot
+    holds "" in that case). Each distinct reason travels once."""
+    reasons: dict[str, int] = {}
+    rows = []
+    for e in edges:
+        row = [
+            f"{e.src_model}.{e.src_column}",
+            f"{e.dst_model}.{e.dst_column}",
+            TRUST_CODE.get(e.trust, "r"),
+        ]
+        kind = "" if e.kind == "value" else e.kind
+        reason = getattr(e, "reason", "") or ""
+        if reason:
+            row += [kind, reasons.setdefault(reason, len(reasons))]
+        elif kind:
+            row.append(kind)
+        rows.append(row)
+    return {"edges": rows, "reasons": list(reasons)}
+
+
+def compact_names(graph) -> dict[str, list[str]]:
+    """The spellings the command accepts, so the page resolves a typed name
+    the same way."""
+    from ripple.names import askable_names
+
+    return askable_names(graph)
+
+
+def graph_export(graph) -> dict:
+    """The whole graph as the page carries it: links, the reasons behind
+    them, the spellings that name a model, and the columns no link touches."""
+    from ripple.names import unlinked_columns
+
+    return {
+        **compact_edges(graph.edges),
+        "names": compact_names(graph),
+        "columns": unlinked_columns(graph),
+    }
+
+
+def _ripple_version() -> str:
+    try:
+        return version("ripple-sql")
+    except PackageNotFoundError:
+        return "dev"
+
+
+def title_for(answer: dict) -> str:
+    if answer["kind"] == "trace":
+        return f"Where does {answer['target']} come from?"
+    return f"What breaks if {answer['target']} changes?"
+
+
+def render(
+    answer: dict,
+    text: str,
+    project: dict | None = None,
+    edges: dict | None = None,
+    views: list[dict] | None = None,
+    change: dict | None = None,
+) -> str:
+    """The page as a string. `edges` is graph_export() of the whole graph.
+    `views` carries one {answer, text} per changed column for a change page,
+    with `change` holding the rebuild list and counts."""
+    graph = None
+    note = ""
+    if edges is not None:
+        payload = json.dumps(edges, separators=(",", ":"))
+        budget = embed_budget()
+        if budget and len(payload) <= budget:
+            graph = edges
+        else:
+            note = (
+                f"The graph export is {len(payload) / 1e6:.1f} MB, over this page's "
+                f"{budget / 1e6:.0f} MB budget, so follow-up questions need the command line."
+            )
+    data = {
+        "answer": answer,
+        "text": text,
+        "views": views or [],
+        "change": change,
+        "project": project or {},
+        "graph": graph,
+        "note": note,
+    }
+    title = "What breaks in this change?" if change else title_for(answer)
+    return _page(data, title)
+
+
+def render_live(project: dict, live: dict) -> str:
+    """The page `ripple serve` opens on: no answer yet, a question box that
+    asks the local server, the starters, and the coverage ladder. `live`
+    carries api, edges, review, ladder rows, starters, and column ids."""
+    data = {
+        "answer": None,
+        "text": "",
+        "views": [],
+        "change": None,
+        "project": project,
+        "graph": None,
+        "note": "",
+        "live": live,
+    }
+    return _page(data, f"Ripple: {project.get('root', 'this project')}")
+
+
+def _page(data: dict, title: str) -> str:
+    data = {
+        **data,
+        "generated": _dt.datetime.now().strftime("%Y-%m-%d %H:%M"),
+        "version": _ripple_version(),
+    }
+    # a column or reason could contain "</", which would end the data block early
+    blob = json.dumps(data, separators=(",", ":")).replace("</", "<\\/")
+    html = (
+        TEMPLATE.read_text(encoding="utf-8")
+        .replace("/*CSS*/", STYLE.read_text(encoding="utf-8"))
+        .replace("/*TWIN*/", TWIN.read_text(encoding="utf-8"))
+        .replace("/*EXPLORE*/", EXPLORE.read_text(encoding="utf-8"))
+    )
+    return html.replace("__TITLE__", _escape(title)).replace("__DATA__", blob)
+
+
+def default_path(root: Path, answer: dict) -> Path:
+    slug = re.sub(r"[^A-Za-z0-9_.-]+", "_", answer["target"])
+    return root / ".ripple" / "answers" / f"{answer['kind']}-{slug}.html"
+
+
+def write(
+    answer: dict,
+    text: str,
+    path: Path | None,
+    root: Path,
+    project: dict | None = None,
+    edges: dict | None = None,
+) -> Path:
+    target = path or default_path(root, answer)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(render(answer, text, project, edges), encoding="utf-8")
+    return target
+
+
+def project_info(project, root: Path) -> dict:
+    """What the page header says about the project it was made from."""
+    return {
+        "root": Path(root).name,
+        "mode": project.mode,
+        "dialect": project.dialect,
+        "models": len(project.models),
+    }
+
+
+def write_for(graph, root: Path, answer: dict, text_full: str, path: Path | None = None) -> Path:
+    """The page for one answer, with the whole graph embedded for follow-ups.
+    Under .ripple/answers unless a path is given."""
+    info = project_info(graph.project, root)
+    return write(answer, text_full, path, root, info, graph_export(graph))
+
+
+def open_in_browser(path: Path) -> bool:
+    """True when a browser took the file. False in a sandbox or over SSH,
+    where the caller prints the path instead."""
+    try:
+        return bool(webbrowser.open(path.resolve().as_uri()))
+    except Exception:
+        return False
+
+
+def _escape(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")

ripple/cache.py

@@ -0,0 +1,80 @@
+"""On-disk graph cache.
+
+A 2,000-model estate takes ~40s to analyze; asking three questions should
+not cost three builds. The cache key is a content fingerprint (path, size,
+and mtime of every file sourcefiles.py names) plus the ripple and sqlglot
+versions and the dialect, so any change anywhere invalidates it. Cache lives
+under the user cache dir, never inside the project.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import logging
+import os
+import pickle
+from pathlib import Path
+
+from ripple.sourcefiles import stamp
+
+logger = logging.getLogger(__name__)
+
+
+def _cache_dir() -> Path:
+    base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return base / "ripple"
+
+
+def _fingerprint(root: Path, dialect: str | None) -> str:
+    import sqlglot
+
+    try:
+        from ripple import __version__
+    except Exception:
+        __version__ = "0"
+    digest = hashlib.sha256()
+    digest.update(f"{__version__}|{sqlglot.__version__}|{dialect}|{root}".encode())
+    # hash ripple's own source, so editing the engine (or upgrading in place
+    # without a version bump) invalidates the cache instead of serving stale
+    # lineage. Cheap: a few dozen stats.
+    try:
+        pkg = Path(__file__).parent
+        for src in sorted(pkg.rglob("*.py")):
+            digest.update(f"{src.name}|{src.stat().st_mtime_ns}".encode())
+    except OSError:
+        pass
+    digest.update(stamp(root).encode())
+    return digest.hexdigest()
+
+
+def load(root: Path, dialect: str | None):
+    path = _cache_dir() / f"graph-{_fingerprint(root, dialect)}.pickle"
+    if not path.exists():
+        return None
+    try:
+        with open(path, "rb") as f:
+            return pickle.load(f)
+    except Exception as e:
+        logger.debug("cache read failed (%s); rebuilding", e)
+        return None
+
+
+def store(graph, root: Path, dialect: str | None) -> None:
+    path = _cache_dir() / f"graph-{_fingerprint(root, dialect)}.pickle"
+    # write-then-rename: a crash mid-write must not leave a corrupt file at
+    # the live path, where the matching fingerprint would make every later
+    # session fail the load and silently pay the full rebuild
+    tmp = path.with_suffix(f".tmp-{os.getpid()}")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        graph._jinja_env = None  # not picklable, only needed during build
+        with open(tmp, "wb") as f:
+            pickle.dump(graph, f)
+        os.replace(tmp, path)
+    except BaseException as e:
+        with contextlib.suppress(OSError):
+            tmp.unlink(missing_ok=True)
+        if not isinstance(e, Exception):
+            raise  # KeyboardInterrupt/SystemExit propagate after cleanup
+        logger.debug("cache write failed (%s); continuing without", e)