ripple-sql 0.1.0__tar.gz → 0.1.2__tar.gz

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/CHANGELOG.md

@@ -6,6 +6,19 @@ Notable changes to Ripple. The format follows
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-09-09
+
+### Fixed
+- A symlink whose target is gone matched the SQL, YAML, LookML, macro, and seed globs and crashed the load with a traceback on the first real folder the published build ran in. One helper, `files_under`, now serves every project glob and keeps regular files only.
+
+## [0.1.1] - 2026-09-09
+
+### Changed
+- The map's home page says what it is for in one line ("Pick a column. See what breaks if it changes, or where it comes from.") and offers one example column to try; the five most-read columns come back with an answer. A source table's chip no longer shows a count, since the number was the columns some model happened to name, not the table; opening one says the list is not declared in the project and points at the Coverage rung that adds it.
+
+### Fixed
+- Run from a home directory or the root of a disk, ripple refuses in one sentence instead of reading every SQL file the user owns. Progress lines ("scanning ...") reach a pipe as they are printed, not when the process exits.
+
 ## [0.1.0] - 2026-09-08
 
 First public release.
@@ -222,5 +235,7 @@ First public release.
 ### Removed
 - The dark whole-graph canvas that `ripple serve` used to open (`static/index.html`). Every surface now draws one answer.
 
-[Unreleased]: https://github.com/bteh/ripple/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/bteh/ripple/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/bteh/ripple/releases/tag/v0.1.2
+[0.1.1]: https://github.com/bteh/ripple/releases/tag/v0.1.1
 [0.1.0]: https://github.com/bteh/ripple/releases/tag/v0.1.0

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ripple-sql
-Version: 0.1.0
+Version: 0.1.2
 Summary: Offline column-level SQL lineage. See what breaks before you merge.
 Project-URL: Homepage, https://github.com/bteh/ripple
 Project-URL: Repository, https://github.com/bteh/ripple

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ripple-sql"
-version = "0.1.0"
+version = "0.1.2"
 description = "Offline column-level SQL lineage. See what breaks before you merge."
 readme = "README.md"
 requires-python = ">=3.10"

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/cli.py

@@ -570,10 +570,12 @@ def utf8_streams() -> None:
     for stream in (sys.stdin, sys.stdout, sys.stderr):
         if stream is None or not hasattr(stream, "reconfigure"):
             continue
+        # line buffered either way: "scanning ..." must show while the scan
+        # runs, not when the process exits, even through a pipe
         if stream.isatty():
-            stream.reconfigure(errors="replace")
+            stream.reconfigure(errors="replace", line_buffering=True)
         else:
-            stream.reconfigure(encoding="utf-8", errors="replace")
+            stream.reconfigure(encoding="utf-8", errors="replace", line_buffering=True)
 
 
 def main(argv: list[str] | None = None) -> None:
@@ -726,7 +728,12 @@ def main(argv: list[str] | None = None) -> None:
         "doctor": cmd_doctor,
         "serve": cmd_serve,
     }
-    handlers[args.command](args)
+    from ripple.loaders.types import NotAProject
+
+    try:
+        handlers[args.command](args)
+    except NotAProject as e:
+        sys.exit(str(e))
 
 
 if __name__ == "__main__":

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/home.py

@@ -130,10 +130,14 @@ def model_map(nodes: list[dict], edges) -> dict:
     members: dict[str, dict] = {}
     for n in nodes:
         source = n["type"] == "source"
+        columns = [c for c in n.get("columns") or [] if _is_column(c)]
         members[n["name"]] = {
             "id": n["name"],
             "kind": "source" if source else "model",
-            "columns": [c for c in n.get("columns") or [] if _is_column(c)],
+            "columns": columns,
+            # a source with no declared list only shows the columns some
+            # model happens to name; the page must not present that as the table
+            "declared": bool(columns),
             "status": None if source else n.get("status"),
             "path": None if source else n.get("path"),
         }
@@ -156,6 +160,7 @@ def model_map(nodes: list[dict], edges) -> dict:
             "id": name,
             "kind": kind,
             "columns": sorted(seen.get(name, {})),
+            "declared": kind == "dashboard",
             "status": None,
             "path": None,
         }

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/loaders/dbt.py

@@ -24,6 +24,7 @@ from ripple.loaders.types import (
     DEFAULT_DIALECT,
     Model,
     Project,
+    files_under,
     relative_posix,
 )
 
@@ -124,7 +125,7 @@ def _seed_tables(root: Path) -> list[Model]:
 
     seeds: list[Model] = []
     for seed_dir in _seed_dirs(root):
-        for path in sorted(seed_dir.rglob("*.csv")):
+        for path in files_under(seed_dir, "*.csv"):
             try:
                 with open(path, newline="", encoding="utf-8", errors="replace") as f:
                     header = next(csv.reader(f), [])
@@ -257,7 +258,9 @@ def _load_dbt_raw(root: Path, dialect: str | None) -> Project:
         "run 'dbt compile' for exact lineage."
     ]
     model_dirs = _dbt_model_dirs(root)
-    pairs = sorted(((d, p) for d in model_dirs for p in d.rglob("*.sql")), key=lambda t: t[1])
+    pairs = sorted(
+        ((d, p) for d in model_dirs for p in files_under(d, "*.sql")), key=lambda t: t[1]
+    )
     # a slice of every model, the same sample the sql-dir loader sniffs
     sample = "\n".join(p.read_text(errors="replace", encoding="utf-8")[:4000] for _, p in pairs)[
         :200000

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/loaders/dbt_config.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
+from ripple.loaders.types import files_under
+
 
 def _project_vars(root: Path) -> dict:
     """Declared vars from dbt_project.yml. A sub-dict scoped under the
@@ -236,7 +238,7 @@ def _macro_sources(root: Path) -> list[tuple[str | None, str]]:
             macros_dir = base / dir_name
             if not macros_dir.is_dir():
                 continue
-            for macro_file in sorted(macros_dir.rglob("*.sql")):
+            for macro_file in files_under(macros_dir, "*.sql"):
                 resolved = macro_file.resolve()
                 if resolved in seen_files:
                     continue

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/loaders/sqldir.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 from ripple.engine.budget import TIMED_OUT, budget_seconds, max_sql_bytes, run_within_budget
 from ripple.loaders.identity import directory_identity
-from ripple.loaders.types import IGNORE_DIRS, Model, Project, relative_posix
+from ripple.loaders.types import IGNORE_DIRS, Model, Project, files_under, relative_posix
 
 
 def _iter_sql_files(root: Path, exclude: list[Path] | None = None) -> tuple[list[Path], int]:
@@ -19,7 +19,7 @@ def _iter_sql_files(root: Path, exclude: list[Path] | None = None) -> tuple[list
     kept: list[Path] = []
     skipped = 0
     excluded = [d.resolve() for d in (exclude or [])]
-    for path in sorted(root.rglob("*.sql")):
+    for path in files_under(root, "*.sql"):
         dirs = path.relative_to(root).parts[:-1]
         if any(part in IGNORE_DIRS or part.startswith(".") for part in dirs):
             skipped += 1

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/loaders/types.py

@@ -169,6 +169,16 @@ def find_project_root(start: Path) -> Path:
     for candidate in [current, *current.parents]:
         if (candidate / "dbt_project.yml").exists():
             return candidate
+    # every caller passes through here before it stamps the cache or reads
+    # a file, so this is where a whole machine is refused
+    if whole_machine(current):
+        where = (
+            "your home directory" if current == Path.home().resolve() else "the root of the disk"
+        )
+        raise NotAProject(
+            f"{current} is {where}, not a project; run ripple inside a project folder, "
+            "or pass the folder with --path"
+        )
     return current
 
 
@@ -195,3 +205,23 @@ def relative_posix(path, root) -> str:
     OS, so a model's path is the same string in a PR comment written on
     Linux and on the laptop that reads it."""
     return path.relative_to(root).as_posix()
+
+
+class NotAProject(ValueError):
+    """The path is a whole machine, not a project: reading it would crawl
+    everything under the home directory or the disk."""
+
+
+def whole_machine(path: Path) -> bool:
+    """True for the home directory and for the root of a disk. A plain-SQL
+    scan starts wherever the command runs, and from either of those it
+    would read every file the user owns."""
+    here = Path(path).resolve()
+    return here == Path.home().resolve() or here == Path(here.anchor)
+
+
+def files_under(root: Path, pattern: str) -> list[Path]:
+    """The regular files matching a glob under root, sorted. A symlink whose
+    target is gone matches the glob and is not a file; reading it raised a
+    traceback on the first real folder this ran in."""
+    return sorted(p for p in root.rglob(pattern) if p.is_file())

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/lookml.py

@@ -16,6 +16,7 @@ from pathlib import Path
 
 import yaml
 
+from ripple.loaders.types import files_under
 from ripple.project import IGNORE_DIRS
 from ripple.semantic import DownstreamEdge
 
@@ -133,7 +134,7 @@ def load_lookml_downstream(root: Path) -> list[DownstreamEdge]:
         return []
 
     edges: list[DownstreamEdge] = []
-    for path in sorted(root.rglob("*.lkml")):
+    for path in files_under(root, "*.lkml"):
         parts = path.relative_to(root).parts[:-1]
         if any(p in IGNORE_DIRS or p.startswith(".") for p in parts):
             continue

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/project.py

@@ -49,7 +49,7 @@ __all__ = [
 
 def load_project(path: str | Path = ".", dialect: str | None = None) -> Project:
     start = Path(path).resolve()
-    root = find_project_root(start)
+    root = find_project_root(start)  # refuses a home directory or a disk root
     # If we're standing above several dbt projects (a monorepo), gather them
     # all. find_project_root only walks UP to the nearest one, so scan DOWN.
     scan_root = root if (root / "dbt_project.yml").exists() else start

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/semantic.py

@@ -19,6 +19,7 @@ from pathlib import Path
 
 import yaml
 
+from ripple.loaders.types import files_under
 from ripple.project import IGNORE_DIRS
 
 _REF = re.compile(r"ref\(\s*['\"]([^'\"]+)['\"]\s*(?:,\s*['\"]([^'\"]+)['\"])?\s*\)")
@@ -47,7 +48,7 @@ def _ref_model(value) -> str | None:
 
 
 def _iter_schema_docs(root: Path):
-    for path in sorted(root.rglob("*.yml")) + sorted(root.rglob("*.yaml")):
+    for path in files_under(root, "*.yml") + files_under(root, "*.yaml"):
         parts = path.relative_to(root).parts[:-1]
         if any(p in IGNORE_DIRS or p.startswith(".") for p in parts):
             continue

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/static/answer.css

@@ -24,6 +24,7 @@ h1 code{font:500 24px/1 var(--mono); letter-spacing:0}
 .sum b{color:var(--ink); font-weight:600}
 .sum > span{position:relative}
 .sum > span + span::before{content:""; position:absolute; left:-9px; top:.3em; height:.9em; border-left:1px solid var(--line-strong)}
+.lede{margin:14px 0 0; font-size:16px; color:var(--ink); text-wrap:pretty}
 
 .ask{display:flex; flex-wrap:wrap; gap:8px; align-items:center; margin:28px 0 0; padding:16px 0 14px; border-top:1px solid var(--line); border-bottom:1px solid var(--line)}
 .ask input,.ask select{font:400 14px var(--mono); padding:8px 10px; border:1px solid var(--line-strong); border-radius:var(--r); background:var(--surface); color:var(--ink); min-width:0; height:36px}
@@ -105,6 +106,7 @@ pre{margin:0; padding:16px 22px 18px; overflow-x:auto; font:400 13px/1.65 var(--
 .cols{transition:opacity .18s var(--ease)}
 .wires path.on{stroke:var(--accent); stroke-width:1.5}
 .cols{display:flex; flex-direction:column; gap:5px; margin:0 0 6px 10px; padding-left:10px; border-left:1px solid var(--line)}
+.cols .gname{max-width:36ch; white-space:normal; line-height:1.45; padding-top:2px}
 .cols .node{cursor:pointer}
 .cols .node:hover{border-color:var(--accent); color:var(--accent-strong)}
 .more-chips{font:500 12.5px var(--sans); color:var(--accent); background:none; border:0; padding:4px 0; cursor:pointer; text-align:left}

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/static/answer.html

@@ -13,6 +13,7 @@
   <p class="eyebrow"><span class="mark" aria-hidden="true"></span><span id="eyebrow">Ripple</span></p>
   <h1 id="title"></h1>
   <p class="sum" id="sum"></p>
+  <p class="lede" id="lede" hidden>Pick a column. See what breaks if it changes, or where it comes from.</p>
 
   <div class="change" id="change" hidden><span class="lab">In this change</span></div>
 
@@ -77,7 +78,8 @@
     demo.hidden = false;
     mapEl.hidden = true;
     nav.hidden = !mapApi;
-    if (mapApi && L.starters.length) document.getElementById('starters').hidden = false;
+    document.getElementById('lede').hidden = true;
+    if (mapApi) starterStrip(true);
     document.getElementById('eyebrow').textContent = 'Ripple · ' + (DATA.change ? 'what this change breaks' : (a.kind === 'trace' ? 'where it comes from' : 'what breaks'));
     document.getElementById('title').innerHTML = a.kind === 'trace'
       ? 'Where does <code>' + esc(a.target) + '</code> come from?'
@@ -185,6 +187,14 @@
 
   // ---- the home state: ripple serve opens here, on the whole project ----
   var P = DATA.project || {}, L = DATA.live;
+  // one example on the map ("Try"), the five most-read columns with an answer
+  function starterStrip(all){
+    var strip = document.getElementById('starters');
+    if (!L || !L.starters.length) return;
+    strip.hidden = false;
+    strip.querySelector('.lab').textContent = all ? 'Start with' : 'Try';
+    Array.prototype.slice.call(strip.querySelectorAll('button')).forEach(function(b, i){ b.hidden = !all && i > 0; });
+  }
   function home(){
     current = null;
     demo.hidden = true;
@@ -200,9 +210,9 @@
     if (L.review) bits.push('<b>' + L.review + ' need review</b>');
     document.getElementById('sum').innerHTML = bits.map(function(b){ return '<span>' + b + '</span>'; }).join('');
     document.title = 'Ripple: ' + (P.root || 'local');
+    document.getElementById('lede').hidden = !mapApi;
     if (mapApi){
-      // the map is the place to start; the starter chips come back with an answer
-      document.getElementById('starters').hidden = true;
+      starterStrip(false);
       mapEl.hidden = false;
       mapApi.filter(document.getElementById('q').value.trim());
       requestAnimationFrame(mapApi.draw);

{ripple_sql-0.1.0 → ripple_sql-0.1.2}/src/ripple/static/explore.js

@@ -47,7 +47,8 @@ function renderMap(root, map, opts){
       var broken = m.status && m.status !== 'ok' && m.status !== 'star_only';
       var b = el('button', 'mdl' + (m.kind === 'source' ? ' src' : '') + (m.kind === 'dashboard' ? ' bi' : '') + (broken ? ' r' : ''));
       b.type = 'button'; b.dataset.id = m.id; b.setAttribute('aria-expanded', 'false');
-      b.innerHTML = label(m) + (m.columns.length ? ' <small>' + m.columns.length + '</small>' : '');
+      // a source's count would be the columns some model names, not the table's width
+      b.innerHTML = label(m) + (m.declared && m.kind !== 'source' && m.columns.length ? ' <small>' + m.columns.length + '</small>' : '');
       var reads = (ups[m.id] || []).length, feeds = (downs[m.id] || []).length;
       b.title = (m.path || m.id) + ' · reads ' + reads + ', feeds ' + feeds + (broken ? ' · ' + m.status.replace('_', ' ') : '');
       b.addEventListener('click', function(){ toggle(m, g, b); });
@@ -81,7 +82,9 @@ function renderMap(root, map, opts){
     });
     var note = null;
     if (m.columns.length > MAP_COLUMNS) note = '+ ' + (m.columns.length - MAP_COLUMNS) + ' more, ask by name';
-    else if (!m.columns.length) note = m.kind === 'source' ? 'columns unknown, see Coverage' : 'no columns known';
+    else if (!m.declared && m.kind === 'source') note = (m.columns.length ? 'only the columns this project names; the full list is' : 'no column list; it is') +
+      ' not declared in the project (a select * reads it unnamed). Coverage below adds it.';
+    else if (!m.columns.length) note = 'no columns known';
     if (note){ var n = el('span', 'gname'); n.textContent = note; cols.appendChild(n); }
     g.appendChild(cols); b.setAttribute('aria-expanded', 'true'); draw();
   }