ripple-sql 0.1.0__py3-none-any.whl

ripple/static/answer_twin.js

@@ -0,0 +1,299 @@
+// The pure half of the answer page: the text twin of ripple.answer and the
+// graph twin of graph.breaks and graph.trace. No DOM. answer_page.py inlines
+// this file into answer.html at render, and the tests run it under node.
+  // TEXT TWIN START
+  // A port of ripple.answer.breaks_lines and trace_lines. Pure functions, no DOM.
+  // tests/test_answer_page.py runs this block under node and compares it to Python.
+  var KIND_WORDS = {semantic: 'semantic model', metric: 'metric', exposure: 'exposure'};
+  function plural(n, w){ return n + ' ' + w + (n === 1 ? '' : 's'); }
+  function isDash(model){ return /^(metric|semantic|exposure):/.test(model); }
+  function headline(a){
+    var s = a.summary, parts = [];
+    if (s.models) parts.push(plural(s.models, a.noun));
+    if (s.dashboard_numbers) parts.push(plural(s.dashboard_numbers, 'dashboard number'));
+    var where = parts.length ? parts.join(' and ') : '0 ' + a.noun + 's';
+    return a.kind === 'trace'
+      ? a.target + ' comes from ' + s.columns + ' columns in ' + where
+      : s.columns + ' columns in ' + where + ' affected by ' + a.target;
+  }
+  function hasHits(a){ var s = a.summary; return !!(s.columns || s.dashboard_numbers || (a.row_level && a.row_level.length)); }
+  function breaksText(a){
+    var s = a.summary, out = [];
+    if (!hasHits(a)) return 'Nothing downstream reads ' + a.target + '.';
+    out.push(headline(a));
+    if (s.review) out.push(s.review + ' of them need review (lineage uncertain)');
+    var groups = {}, order = [];
+    a.nodes.forEach(function(n){ if (n.depth === 0 || n.kind === 'unknown') return; if (!groups[n.model]){ groups[n.model] = []; order.push(n.model); } groups[n.model].push(n); });
+    var models = order.filter(function(m){ return !isDash(m); }), dashes = order.filter(isDash);
+    if (models.length > 1){
+      var worst = models.map(function(m){ return [m, groups[m].length]; }).sort(function(x, y){ return y[1] - x[1]; }).slice(0, 3);
+      out.push('Hit hardest: ' + worst.map(function(x){ return x[0] + ' (' + x[1] + ')'; }).join(', '));
+    }
+    out.push('');
+    var via = {}; a.edges.forEach(function(e){ if (!(e.dst in via)) via[e.dst] = e.src; });
+    models.forEach(function(m){
+      var ns = groups[m], d = Math.min.apply(null, ns.map(function(n){ return n.depth; }));
+      out.push('  ' + m + ' · ' + plural(d, 'step'));
+      var g = {}, go = [];
+      ns.forEach(function(n){
+        var src = via[n.id] || '?', i = src.lastIndexOf('.'), sm = src.slice(0, i), sc = src.slice(i + 1);
+        var label = (sm && sc === n.column) ? sm : src, review = n.trust === 'review_required';
+        var key = label + '|' + review;
+        if (!g[key]){ g[key] = {label: label, review: review, cols: []}; go.push(key); }
+        g[key].cols.push(n.column);
+      });
+      go.forEach(function(k){ var x = g[k]; out.push('    ' + x.cols.join(', ') + ' ← ' + x.label + (x.review ? ' needs review' : '')); });
+    });
+    if (dashes.length){
+      out.push(''); out.push('Dashboard numbers');
+      var ent = {}, eo = [];
+      dashes.forEach(function(m){
+        var kind = m.split(':')[0], rest = m.slice(kind.length + 1), entity, cols;
+        if (kind === 'semantic'){ var i = rest.lastIndexOf('.'); entity = i > 0 ? rest.slice(0, i) : rest; cols = groups[m].map(function(n){ return n.column; }); }
+        else { entity = kind; cols = [rest]; }
+        var key = entity + '|' + kind;
+        if (!ent[key]){ ent[key] = {entity: entity, kind: kind, cols: [], review: false}; eo.push(key); }
+        ent[key].cols = ent[key].cols.concat(cols);
+        if (groups[m].some(function(n){ return n.trust === 'review_required'; })) ent[key].review = true;
+      });
+      eo.forEach(function(k){
+        var x = ent[k], line = x.entity === x.kind ? '  ' + x.kind + 's: ' + x.cols.join(', ') : '  ' + x.entity + ' (' + KIND_WORDS[x.kind] + '): ' + x.cols.join(', ');
+        out.push(line + (x.review ? ' needs review' : ''));
+      });
+    }
+    a.row_level.forEach(function(r){
+      var uses = r.uses || [], first = uses.length ? uses[0] : '', m = first.match(/\((\w+)\)$/);
+      var kinds = {}; uses.forEach(function(u){ var mm = u.match(/\((\w+)\)$/); if (mm) kinds[mm[1]] = 1; });
+      var note = (Object.keys(kinds).length === 1 && kinds.window) ? 'partitions or orders a window on it' : 'filters rows on it (' + (m ? m[1] : 'filter') + ')';
+      out.push('  ' + r.model + ' · ' + note + (r.trust === 'review_required' ? ' needs review' : ''));
+    });
+    if (!s.complete){ var cap = a.truncated_at_depth; out.push('  stopped ' + (cap ? 'at depth ' + cap : 'at the depth cap') + '; the full radius may be larger'); }
+    out.push('');
+    return out.join('\n');
+  }
+  function traceText(a){
+    var byId = {}; a.nodes.forEach(function(n){ byId[n.id] = n; });
+    var hops = a.edges.filter(function(e){ return !(byId[e.src] && byId[e.src].kind === 'unknown'); });
+    if (!hops.length) return 'No upstream lineage for ' + a.target + '.';
+    var out = [a.target + ' comes from:'];
+    hops.forEach(function(e){
+      var n = byId[e.src], pad = ''; for (var i = 0; i < n.depth; i++) pad += '  ';
+      out.push(pad + e.src + ((e.path_trust || n.trust) === 'review_required' ? ' review' : '') + ' → ' + e.dst);
+    });
+    if (a.truncated_at_depth) out.push('  stopped at depth ' + a.truncated_at_depth + '; the trail may go further back (--depth to follow it)');
+    return out.join('\n');
+  }
+  // TEXT TWIN END
+
+  // GRAPH TWIN START
+  // A port of LineageGraph.breaks/trace and ripple.answer.breaks_answer/trace_answer
+  // over the compact export the page carries (answer_page.compact_edges). Pure functions, no DOM.
+  // tests/test_answer_page.py runs this block under node and compares it to Python.
+  var TRUST = {v: 'verified', h: 'high_confidence', m: 'moderate', r: 'review_required'};
+  var RANK = {verified: 0, high_confidence: 1, moderate: 2, review_required: 3};
+  var MAX_DEPTH = 25;
+  function worse(){ var w = arguments[0]; for (var i = 1; i < arguments.length; i++) if (RANK[arguments[i]] > RANK[w]) w = arguments[i]; return w; }
+  function cmp(a, b){ return a < b ? -1 : a > b ? 1 : 0; }
+  function splitId(id){ var i = id.lastIndexOf('.'); return i < 0 ? ['', id] : [id.slice(0, i), id.slice(i + 1)]; }
+  function buildIndex(G){
+    var index = {down: Object.create(null), downByModel: Object.create(null), up: Object.create(null), ids: Object.create(null), names: Object.create(null)};
+    var reasons = G.reasons || [];
+    // an export written before names travelled, and the change page, carry none
+    var given = G.names || {};
+    Object.keys(given).forEach(function(spelling){ index.names[spelling] = given[spelling]; });
+    G.edges.forEach(function(row){
+      var s = splitId(row[0]), d = splitId(row[1]);
+      var e = {src: row[0], dst: row[1], srcModel: s[0], srcColumn: s[1], dstModel: d[0], dstColumn: d[1],
+               trust: TRUST[row[2]] || 'review_required', kind: row[3] || 'value',
+               reason: row.length > 4 ? (reasons[row[4]] || '') : ''};
+      index.ids[e.src] = 1; index.ids[e.dst] = 1;
+      (index.down[e.src] = index.down[e.src] || []).push(e);
+      (index.downByModel[e.srcModel] = index.downByModel[e.srcModel] || []).push(e);
+      (index.up[e.dst] = index.up[e.dst] || []).push(e);
+    });
+    (G.columns || []).forEach(function(id){ index.ids[id] = 1; });
+    return index;
+  }
+  // graph._askable_name over the export: the shortest dotted spelling that means
+  // only this model, so an ambiguity names models the reader can actually type
+  function askableSpelling(names, canonical){
+    var best = null;
+    for (var spelling in names){
+      var means = names[spelling];
+      if (means.length !== 1 || means[0] !== canonical || spelling.indexOf('.') < 0) continue;
+      if (best === null || spelling.length < best.length) best = spelling;
+    }
+    return best === null ? canonical : best;
+  }
+  // the one place a typed name becomes an id, a port of graph._require_target.
+  // Returns {id: ...} or {error: ..., candidates: [...]}; the page must take
+  // every spelling the command takes, and refuse the ones it refuses
+  function resolveTarget(index, typed){
+    var asked = String(typed === null || typed === undefined ? '' : typed).trim();
+    if (!asked) return {error: 'Ask for a column as model.column'};
+    var parts = splitId(asked), model = parts[0], column = parts[1];
+    var names = index.names || {}, canonical = model ? names[model.toLowerCase()] : null, also = [];
+    if (canonical && canonical.length > 1){
+      // a spelling that IS one model's own name is that model, even when
+      // another model carries it as an alias
+      var exact = canonical.filter(function(c){ return c.toLowerCase() === model.toLowerCase(); });
+      if (exact.length === 1){
+        also = canonical.filter(function(c){ return c !== exact[0]; })
+          .map(function(c){ return askableSpelling(names, c); }).sort(cmp);
+        canonical = exact;
+      }
+    }
+    if (canonical && canonical.length > 1){
+      return {
+        error: "'" + model + "' names " + canonical.length + ' different models; ask by full name',
+        candidates: canonical.map(function(c){ return askableSpelling(names, c); }).sort(cmp)
+      };
+    }
+    var tries = canonical ? [canonical[0] + '.' + column, canonical[0] + '.' + column.toLowerCase()] : [];
+    // the command lowercases a spelling before looking it up, so the page must
+    tries.push(asked, model + '.' + column.toLowerCase(), model.toLowerCase() + '.' + column.toLowerCase());
+    for (var i = 0; i < tries.length; i++){
+      if (index.ids[tries[i]]) return also.length ? {id: tries[i], alsoMatches: also} : {id: tries[i]};
+    }
+    return {error: 'No column named ' + asked + ' in this graph'};
+  }
+  function mkNode(model, column, depth, trust){
+    return {id: model + '.' + column, model: model, column: column, kind: isDash(model) ? 'dashboard' : 'model', depth: depth, trust: trust};
+  }
+  function deepest(nodes){ return Math.max.apply(null, nodes.map(function(n){ return n.depth; })); }
+  function mergeNodes(nodes){
+    var byId = Object.create(null), out = [];
+    nodes.forEach(function(n){
+      var seen = byId[n.id];
+      if (!seen){ seen = byId[n.id] = {id: n.id, model: n.model, column: n.column, kind: n.kind, depth: n.depth, trust: n.trust}; out.push(seen); return; }
+      seen.depth = Math.min(seen.depth, n.depth); seen.trust = worse(seen.trust, n.trust);
+    });
+    return out;
+  }
+  // a link may name a column the walk never listed (a wildcard, or a column reached
+  // through one); it gets a stand-in so nothing dangles. Links point away from the
+  // asked column on breaks and toward it on trace, so which end sits one step nearer depends on the kind
+  function closeEdges(nodes, edges, kind){
+    var byId = Object.create(null); nodes.forEach(function(n){ byId[n.id] = n; });
+    edges.forEach(function(e){
+      [['src', 'dst'], ['dst', 'src']].forEach(function(pair){
+        var id = e[pair[0]]; if (byId[id]) return;
+        var neighbour = byId[e[pair[1]]], parts = splitId(id), nearer = (pair[0] === 'src') === (kind === 'breaks');
+        var n = mkNode(parts[0], parts[1], Math.max(0, (neighbour ? neighbour.depth : 1) + (nearer ? -1 : 1)), 'review_required');
+        n.kind = 'unknown'; nodes.push(n); byId[id] = n;
+      });
+    });
+    return nodes;
+  }
+  // a node is expanded again when a worse path reaches it, so a downgrade
+  // propagates past a convergence point (each node expands at most RANK-many times)
+  function walkDown(index, target){
+    var expandedAt = Object.create(null), hits = Object.create(null), order = [], rows = Object.create(null), truncated = false;
+    var frontier = [[target, 0, 'verified']];
+    for (var head = 0; head < frontier.length; head++){
+      var node = frontier[head][0], depth = frontier[head][1], pathTrust = frontier[head][2], previous = expandedAt[node];
+      if (previous !== undefined && RANK[pathTrust] <= RANK[previous]) continue;
+      if (depth >= MAX_DEPTH){ truncated = true; continue; }
+      expandedAt[node] = pathTrust;
+      var parts = splitId(node), nodeModel = parts[0], nodeColumn = parts[1];
+      var outgoing = nodeColumn === '*'
+        ? (index.downByModel[nodeModel] || [])
+        : (index.down[node] || []).concat(index.down[nodeModel + '.*'] || []);
+      outgoing.forEach(function(e){
+        var star = e.srcColumn === '*' || e.dstColumn === '*' || nodeColumn === '*';
+        var trust = star ? worse(pathTrust, e.trust, 'review_required') : worse(pathTrust, e.trust);
+        if (e.kind === 'filter' || e.kind === 'join' || e.kind === 'window'){
+          var row = rows[e.dstModel] || (rows[e.dstModel] = {model: e.dstModel, uses: [], trust: trust});
+          row.uses.push(e.src + ' (' + e.kind + ')'); row.trust = worse(row.trust, trust);
+          return;
+        }
+        var hit = hits[e.dst];
+        if (!hit){ hits[e.dst] = {model: e.dstModel, column: e.dstColumn, via: e.src, trust: trust, edgeTrust: e.trust, reason: e.reason, depth: depth + 1}; order.push(e.dst); }
+        else hit.trust = worse(hit.trust, trust);
+        if (e.dstColumn.charAt(0) !== '(') frontier.push([e.dst, depth + 1, trust]);
+      });
+    }
+    // graph.breaks' key: depth, edge trust (verified first), model; the sort is stable so
+    // same-model hits keep discovery order, which is export order on both sides
+    var list = order.map(function(id){ return hits[id]; });
+    list.sort(function(a, b){ return a.depth - b.depth || RANK[a.edgeTrust] - RANK[b.edgeTrust] || cmp(a.model, b.model); });
+    var byModel = Object.create(null), modelOrder = [];
+    list.forEach(function(h){ if (!byModel[h.model]){ byModel[h.model] = []; modelOrder.push(h.model); } byModel[h.model].push(h); });
+    return {byModel: byModel, modelOrder: modelOrder, rows: rows, truncated: truncated};
+  }
+  function computeBreaks(index, target, noun){
+    var found = resolveTarget(index, target);
+    if (!found.id) return null;
+    var w = walkDown(index, found.id), t = splitId(found.id);
+    var asked = mkNode(t[0], t[1], 0, 'verified'); asked.kind = 'asked';
+    var nodes = [asked], edges = [], columns = 0, models = 0, dashboards = 0, review = 0;
+    w.modelOrder.forEach(function(m){
+      var hs = w.byModel[m];
+      if (isDash(m)) dashboards += 1; else { models += 1; columns += hs.length; }
+      hs.forEach(function(h){
+        var n = mkNode(h.model, h.column, h.depth, h.trust); nodes.push(n);
+        var edge = {src: h.via, dst: n.id, trust: h.edgeTrust, path_trust: h.trust};
+        if (h.reason) edge.reason = h.reason;
+        edges.push(edge);
+        if (h.trust === 'review_required') review += 1;
+      });
+    });
+    nodes = closeEdges(mergeNodes(nodes), edges, 'breaks');
+    var rows = Object.keys(w.rows).sort(cmp).map(function(m){ var r = w.rows[m]; return {model: r.model, uses: r.uses.slice(), trust: r.trust}; });
+    var a = {kind: 'breaks', target: asked.id, noun: noun,
+      summary: {columns: columns, models: models, dashboard_numbers: dashboards, review: review,
+                row_level_models: rows.length, deepest_hops: deepest(nodes), complete: !w.truncated},
+      nodes: nodes, edges: edges, row_level: rows};
+    if (w.truncated) a.truncated_at_depth = MAX_DEPTH;
+    if (found.alsoMatches) a.also_matches = found.alsoMatches;
+    return a;
+  }
+  function walkUp(index, target){
+    var expandedAt = Object.create(null), hops = Object.create(null), order = [], truncated = false;
+    var frontier = [[target, 0, 'verified']];
+    for (var head = 0; head < frontier.length; head++){
+      var node = frontier[head][0], depth = frontier[head][1], pathTrust = frontier[head][2], previous = expandedAt[node];
+      if (previous !== undefined && RANK[pathTrust] <= RANK[previous]) continue;
+      if (depth >= MAX_DEPTH){ truncated = true; continue; }
+      expandedAt[node] = pathTrust;
+      var parts = splitId(node), incoming = index.up[node] || [];
+      if (parts[1] !== '*') incoming = incoming.concat(index.up[parts[0] + '.*'] || []);
+      incoming.forEach(function(e){
+        if (e.kind !== 'value') return;
+        var trust = worse(pathTrust, e.trust), key = e.src + ' > ' + e.dst, hop = hops[key];
+        if (!hop){ hops[key] = {model: e.srcModel, column: e.srcColumn, feeds: e.dst, trust: trust, edgeTrust: e.trust, reason: e.reason, depth: depth + 1}; order.push(key); }
+        else hop.trust = worse(hop.trust, trust);
+        frontier.push([e.src, depth + 1, trust]);
+      });
+    }
+    var list = order.map(function(k){ return hops[k]; });
+    list.sort(function(a, b){ return a.depth - b.depth || cmp(a.model, b.model) || cmp(a.column, b.column); });
+    return {hops: list, truncated: truncated};
+  }
+  function computeTrace(index, target, noun){
+    var found = resolveTarget(index, target);
+    if (!found.id) return null;
+    var w = walkUp(index, found.id), t = splitId(found.id);
+    var asked = mkNode(t[0], t[1], 0, 'verified'); asked.kind = 'asked';
+    var nodes = [asked], edges = [];
+    w.hops.forEach(function(h){
+      var n = mkNode(h.model, h.column, h.depth, h.trust); nodes.push(n);
+      var edge = {src: n.id, dst: h.feeds, trust: h.edgeTrust, path_trust: h.trust};
+      if (h.reason) edge.reason = h.reason;
+      edges.push(edge);
+    });
+    nodes = closeEdges(mergeNodes(nodes), edges, 'trace');
+    var upstream = nodes.filter(function(n){ return n.depth > 0; }), models = Object.create(null);
+    upstream.forEach(function(n){ models[n.model] = 1; });
+    var names = Object.keys(models);
+    var a = {kind: 'trace', target: asked.id, noun: noun,
+      summary: {columns: upstream.length,
+                models: names.filter(function(m){ return !isDash(m); }).length,
+                dashboard_numbers: names.filter(function(m){ return isDash(m); }).length,
+                review: upstream.filter(function(n){ return n.trust === 'review_required'; }).length,
+                row_level_models: 0, deepest_hops: deepest(nodes), complete: !w.truncated},
+      nodes: nodes, edges: edges, row_level: []};
+    if (w.truncated) a.truncated_at_depth = MAX_DEPTH;
+    return a;
+  }
+  // GRAPH TWIN END

ripple/static/explore.js

@@ -0,0 +1,133 @@
+// EXPLORE START
+// The map: every model in its layer, the model-level links between them,
+// and a model's columns when it is clicked. Pure DOM over the map the
+// server embeds; nothing here fetches. Hover or focus a model to light its
+// whole chain, upstream and down. Past a cap, links draw only for the lit
+// chain so a large repo stays readable.
+var MAP_PER_LAYER = 40, MAP_WIRE_CAP = 400, MAP_COLUMNS = 60;
+
+function renderMap(root, map, opts){
+  var inner = root.querySelector('.board-inner'), svg = root.querySelector('.wires');
+  var esc = opts.esc, many = map.links.length > MAP_WIRE_CAP;
+  var ups = {}, downs = {}, chips = {}, lit = null;
+  map.links.forEach(function(l){
+    (ups[l.dst] = ups[l.dst] || []).push(l.src);
+    (downs[l.src] = downs[l.src] || []).push(l.dst);
+  });
+  function el(tag, cls){ var e = document.createElement(tag); if (cls) e.className = cls; return e; }
+  function label(m){
+    if (m.kind !== 'dashboard') return esc(m.id);
+    var kind = m.id.split(':')[0];
+    return esc(m.id.slice(kind.length + 1)) + ' <small>' + esc(kind) + '</small>';
+  }
+  function chain(id){
+    var seen = {}; seen[id] = true;
+    [ups, downs].forEach(function(dir){
+      var queue = [id];
+      while (queue.length){
+        var cur = queue.shift();
+        (dir[cur] || []).forEach(function(n){ if (!seen[n]){ seen[n] = true; queue.push(n); } });
+      }
+    });
+    return seen;
+  }
+  function paths(){ return Array.prototype.slice.call(svg.querySelectorAll('path')); }
+
+  var layers = [];
+  map.models.forEach(function(m){ (layers[m.layer] = layers[m.layer] || []).push(m); });
+  layers.forEach(function(models, d){
+    if (!models) return;
+    var lvl = el('div', 'lvl'), head = el('div', 'lhead');
+    var dash = models.every(function(m){ return m.kind === 'dashboard'; });
+    head.textContent = (d === 0 ? 'Sources' : dash ? 'Dashboards' : 'Layer ' + d) + ' · ' + models.length;
+    lvl.appendChild(head);
+    models.forEach(function(m, i){
+      var g = el('div', 'grp');
+      if (i >= MAP_PER_LAYER) g.hidden = true;
+      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>' : '');
+      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); });
+      b.addEventListener('mouseenter', function(){ focus(m.id); });
+      b.addEventListener('focus', function(){ focus(m.id); });
+      b.addEventListener('mouseleave', unfocus);
+      b.addEventListener('blur', unfocus);
+      g.appendChild(b); chips[m.id] = b; lvl.appendChild(g);
+    });
+    if (models.length > MAP_PER_LAYER){
+      var more = el('button', 'more-chips'); more.type = 'button';
+      more.textContent = '+ ' + (models.length - MAP_PER_LAYER) + ' more';
+      more.addEventListener('click', function(){
+        Array.prototype.slice.call(lvl.querySelectorAll('.grp')).forEach(function(x){ x.hidden = false; });
+        more.remove(); draw();
+      });
+      lvl.appendChild(more);
+    }
+    inner.appendChild(lvl);
+  });
+
+  function toggle(m, g, b){
+    var open = g.querySelector('.cols');
+    if (open){ open.remove(); b.setAttribute('aria-expanded', 'false'); draw(); return; }
+    var cols = el('div', 'cols');
+    m.columns.slice(0, MAP_COLUMNS).forEach(function(c){
+      var s = el('button', 'node in'); s.type = 'button'; s.textContent = c;
+      s.title = 'ask about ' + m.id + '.' + c;
+      s.addEventListener('click', function(){ opts.onAsk(m.id + '.' + c); });
+      cols.appendChild(s);
+    });
+    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';
+    if (note){ var n = el('span', 'gname'); n.textContent = note; cols.appendChild(n); }
+    g.appendChild(cols); b.setAttribute('aria-expanded', 'true'); draw();
+  }
+  function focus(id){
+    lit = chain(id); root.classList.add('focus');
+    Object.keys(chips).forEach(function(k){ chips[k].classList.toggle('on', !!lit[k]); });
+    if (many) draw();
+    else paths().forEach(function(p){ p.classList.toggle('on', !!(lit[p.dataset.from] && lit[p.dataset.to])); });
+  }
+  function unfocus(){
+    lit = null; root.classList.remove('focus');
+    Object.keys(chips).forEach(function(k){ chips[k].classList.remove('on'); });
+    if (many) draw();
+    else paths().forEach(function(p){ p.classList.remove('on'); });
+  }
+  function draw(){
+    svg.innerHTML = '';
+    if (root.hidden || window.innerWidth <= 680 || (many && !lit)) return;
+    var base = inner.getBoundingClientRect();
+    svg.setAttribute('width', inner.scrollWidth); svg.setAttribute('height', inner.scrollHeight);
+    map.links.forEach(function(l){
+      if (many && !(lit[l.src] && lit[l.dst])) return;
+      var from = chips[l.src], to = chips[l.dst];
+      if (!from || !to || from.parentNode.hidden || to.parentNode.hidden) return;
+      var ra = from.getBoundingClientRect(), rb = to.getBoundingClientRect();
+      var x1 = ra.right - base.left, y1 = ra.top + ra.height / 2 - base.top;
+      var x2 = rb.left - base.left, y2 = rb.top + rb.height / 2 - base.top;
+      if (x2 < x1){ x1 = ra.left - base.left; x2 = rb.right - base.left; }
+      var dx = Math.max(18, Math.abs(x2 - x1) / 2);
+      var p = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+      p.setAttribute('d', 'M' + x1 + ' ' + y1 + ' C' + (x1 + dx) + ' ' + y1 + ' ' + (x2 - dx) + ' ' + y2 + ' ' + x2 + ' ' + y2);
+      p.dataset.from = l.src; p.dataset.to = l.dst;
+      var cls = (l.review ? 'r ' : '') + (lit && lit[l.src] && lit[l.dst] ? 'on' : '');
+      if (cls.trim()) p.setAttribute('class', cls.trim());
+      svg.appendChild(p);
+    });
+  }
+  function filter(text){
+    text = (text || '').toLowerCase();
+    root.classList.toggle('filter', !!text);
+    map.models.forEach(function(m){
+      var hit = !!text && (m.id.toLowerCase().indexOf(text) >= 0 ||
+        m.columns.some(function(c){ return (m.id + '.' + c).toLowerCase().indexOf(text) >= 0; }));
+      chips[m.id].classList.toggle('hit', hit);
+    });
+  }
+  return {draw: draw, filter: filter, many: many};
+}
+// EXPLORE END

ripple/usage/__init__.py

@@ -0,0 +1,18 @@
+"""Query-history usage: what actually ran, held to the same no-guessing bar.
+
+Files say what is supposed to happen; the warehouse's query log says what
+did. This package ingests a hand-carried export of that log and aggregates
+it against the project's models. Two rules are load-bearing:
+
+- The word "unused" is banned from every surface this package feeds. A short
+  export cannot tell a quarterly job from a dead one, so the only honest
+  claim is "not seen in this window", window printed.
+- Raw query text is never persisted and never returned over MCP. The store
+  holds per-table counts only, so nothing sensitive can leak into a commit
+  or an AI conversation later.
+"""
+
+from ripple.usage.ingest import ingest_file, store_path
+from ripple.usage.report import render, render_empty
+
+__all__ = ["ingest_file", "render", "render_empty", "store_path"]

ripple/usage/cli.py

@@ -0,0 +1,78 @@
+"""CLI surface for collect: render the capability table, run one collect.
+
+Thin over collect.py so the MCP tool and this command share every rule.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+def render_capabilities(caps: dict) -> str:
+    lines = ["Warehouse CLIs on this machine:", ""]
+    sf = caps["snowflake"]
+    status = sf["cli"] if sf["cli_found"] else f"{sf['cli']} not installed"
+    lines.append(f"  snowflake   {status}")
+    if sf["connections"]:
+        marked = [
+            name + (" (default)" if name == sf["default"] else "") for name in sf["connections"]
+        ]
+        lines.append(f"              connections: {', '.join(marked)}")
+    if sf["browser_sso"]:
+        lines.append(
+            f"              browser sign-in: {', '.join(sf['browser_sso'])} "
+            "(a browser window will open)"
+        )
+    bq = caps["bigquery"]
+    status = bq["cli"] if bq["cli_found"] else f"{bq['cli']} not installed"
+    lines.append(f"  bigquery    {status}")
+    for config in bq["configurations"]:
+        active = " (active)" if config["name"] == bq["active"] else ""
+        project = config["project"] or "no project set"
+        lines.append(f"              {config['name']}: {project}{active}")
+    db = caps["databricks"]
+    status = db["cli"] if db["cli_found"] else f"{db['cli']} not installed"
+    lines.append(f"  databricks  {status}")
+    if db["profiles"]:
+        named = [p["name"] + (f" ({p['host']})" if p.get("host") else "") for p in db["profiles"]]
+        lines.append(f"              profiles: {', '.join(named)}")
+    lines.append("")
+    lines.append("try: ripple collect-usage snowflake   (your own queries, last 7 days)")
+    lines.append("The CLI runs with the login you already have; Ripple never sees a credential.")
+    return "\n".join(lines)
+
+
+def run_collect(args, load_graph) -> None:
+    from ripple.usage import collect as collect_mod
+    from ripple.usage.discover import capabilities
+
+    if not args.platform:
+        caps = capabilities()
+        print(json.dumps(caps, indent=2) if args.json else render_capabilities(caps))
+        return
+
+    from ripple.project import find_project_root
+    from ripple.usage.ingest import write_store
+    from ripple.usage.report import render
+
+    project, _ = load_graph(args)
+    try:
+        store = collect_mod.collect(
+            args.platform,
+            [m.name for m in project.models],
+            connection=args.connection,
+            days=args.days,
+            scope=args.scope,
+            region=args.region,
+            timeout=args.timeout,
+            model_aliases={m.name: set(m.aliases) for m in project.models},
+        )
+    except collect_mod.CollectError as e:
+        sys.exit(str(e))
+    write_store(find_project_root(Path(args.path)), store)
+    if args.json:
+        print(json.dumps(store, indent=2))
+        return
+    print(render(store))