querydig 0.1.0 → 0.2.0

package/dist/live-DSIYWIT4.js

@@ -0,0 +1,697 @@
+import {
+  RULE_MAP,
+  sqlShape
+} from "./chunk-YKUITQ6N.js";
+
+// src/live/correlate.ts
+import { createHash } from "crypto";
+
+// src/live/match.ts
+var norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+function singular(s) {
+  if (s.endsWith("ies") && s.length > 4) return s.slice(0, -3) + "y";
+  if (/(ses|xes|zes|ches|shes)$/.test(s)) return s.slice(0, -2);
+  if (s.endsWith("s") && !s.endsWith("ss") && s.length > 3) return s.slice(0, -1);
+  return s;
+}
+function resolveTable(name, tables) {
+  if (!name) return void 0;
+  const all = [...tables];
+  const n = norm(name);
+  const ns = singular(n);
+  const exact = all.find((t) => t === name);
+  if (exact) return exact;
+  const byNorm = all.find((t) => norm(t) === n);
+  if (byNorm) return byNorm;
+  const bySingular = all.find((t) => singular(norm(t)) === ns);
+  if (bySingular) return bySingular;
+  const byDjango = all.find((t) => t.includes("_") && singular(norm(t.split("_").pop())) === ns);
+  return byDjango;
+}
+function indexCovers(index, filterKeys, sortKeys) {
+  const keys = index.keys.map((k) => k.key);
+  const f = [...new Set(filterKeys)];
+  if (!f.length && !sortKeys.length) return false;
+  const prefix = keys.slice(0, f.length);
+  if (f.some((k) => !prefix.includes(k))) return false;
+  const rest = index.keys.slice(f.length, f.length + sortKeys.length);
+  if (rest.length < sortKeys.length) return !sortKeys.length;
+  const same = sortKeys.every((s, i) => rest[i].key === s.key && rest[i].dir === s.dir);
+  const reversed = sortKeys.every((s, i) => rest[i].key === s.key && rest[i].dir === -s.dir);
+  return same || reversed;
+}
+function suggestIndex(adapter, table, filterKeys, sortKeys) {
+  const keys = [...new Set(filterKeys)].map((key) => ({ key, dir: 1 }));
+  for (const s of sortKeys) if (!keys.some((k) => k.key === s.key)) keys.push(s);
+  if (!keys.length) return void 0;
+  if (adapter === "mongodb") return `db.${table}.createIndex({ ${keys.map((k) => `${/^[A-Za-z_$][\w$]*$/.test(k.key) ? k.key : `"${k.key}"`}: ${k.dir}`).join(", ")} })`;
+  return `CREATE INDEX CONCURRENTLY ON "${table}" (${keys.map((k) => `"${k.key}"${k.dir === -1 ? " DESC" : ""}`).join(", ")});`;
+}
+function matchSlowQuery(q, shapes, shapeTables) {
+  if (!q.table) return void 0;
+  const set = new Set(q.filterKeys);
+  let best;
+  for (const s of shapes) {
+    if (shapeTables.get(s.id) !== q.table) continue;
+    const overlap = s.filterKeys.filter((k) => set.has(k)).length;
+    const exact = overlap === set.size && overlap === new Set(s.filterKeys).size;
+    const sortMatch = q.sortKeys.length > 0 && q.sortKeys.every((k, i) => s.sortKeys[i]?.key === k.key);
+    const score = (exact ? 10 : overlap) + (sortMatch ? 3 : 0) + (s.inLoop ? 1 : 0);
+    if (score > 0 && (!best || score > best.score)) best = { s, score };
+  }
+  return best?.s;
+}
+function redactUri(uri) {
+  return uri.replace(/\/\/([^:@/]+):([^@/]*)@/, "//$1:****@");
+}
+function redactText(text, uri) {
+  const m = /\/\/([^:@/]+):([^@/]*)@/.exec(uri);
+  let out = text.split(uri).join(redactUri(uri));
+  if (m && m[2]) {
+    out = out.split(m[2]).join("****");
+    try {
+      out = out.split(decodeURIComponent(m[2])).join("****");
+    } catch {
+    }
+  }
+  return out;
+}
+
+// src/live/correlate.ts
+var THRESHOLDS = { big: 1e5, huge: 1e6, scanMin: 1e4, tiny: 1e3, criticalMs: 1e3 };
+var fmt = (n) => n >= 1e6 ? `${(n / 1e6).toFixed(n >= 1e7 ? 0 : 1)}M` : n >= 1e3 ? `${(n / 1e3).toFixed(n >= 1e4 ? 0 : 1)}k` : String(Math.round(n));
+var unit = (adapter) => adapter === "mongodb" ? "docs" : "rows";
+var fp = (...parts) => createHash("sha1").update(parts.join("|")).digest("hex").slice(0, 16);
+function change(f, to, ev) {
+  if (to === f.severity) return { ...f, evidence: ev };
+  return { ...f, severity: to, evidence: { ...ev, severityChange: { from: f.severity, to } } };
+}
+function correlate(findings, shapes, data) {
+  const shapeById = new Map(shapes.map((s) => [s.id, s]));
+  const u = unit(data.adapter);
+  const rowsOf = (t) => t ? data.tables.get(t)?.rows : void 0;
+  const tableIndexes = (t) => data.indexes.filter((i) => i.table === t);
+  const planText = (p) => `${p.text}${p.docsExamined != null ? ` \xB7 ${fmt(p.docsExamined)} ${u} examined` : ""}${p.ms != null ? ` \xB7 ${p.ms}ms` : ""}`;
+  const handled = /* @__PURE__ */ new Set();
+  const out = findings.map((f) => {
+    const shape = f.shapeId ? shapeById.get(f.shapeId) : void 0;
+    if (!shape) return f;
+    const table = data.shapeTables.get(shape.id);
+    if (!table) return f;
+    const rows = rowsOf(table);
+    const plan = data.plans.get(shape.id);
+    const base = {
+      source: plan ? "explain" : "stats",
+      collection: table,
+      rows,
+      plan: plan ? planText(plan) : void 0,
+      index: plan?.indexUsed,
+      docsExamined: plan?.docsExamined,
+      ms: plan?.ms,
+      note: `${table}: ${rows != null ? `${fmt(rows)} ${u}` : "size unknown"}${plan ? ` \xB7 ${planText(plan)}` : ""}`
+    };
+    switch (f.ruleId) {
+      case "QD001":
+      case "QD002":
+      case "QD003": {
+        if (plan?.fullScan && rows != null && rows >= THRESHOLDS.big) {
+          handled.add(shape.id);
+          const idx = suggestIndex(data.adapter, table, shape.filterKeys, shape.sortKeys);
+          const g = change(f, "critical", { ...base, note: `Each iteration does a full scan of ${table} (${fmt(rows)} ${u}): N \xD7 ${fmt(rows)} ${u} read.` });
+          return idx ? { ...g, fix: `${f.fix} Until then, at least add an index: ${idx}` } : g;
+        }
+        if (plan?.indexUsed) return { ...f, evidence: { ...base, note: `${base.note}. The inner query uses an index, so each round-trip is cheap, but N round-trips remain.` } };
+        return { ...f, evidence: base };
+      }
+      case "MQ001":
+      case "SQ001": {
+        if (rows == null) return f;
+        handled.add(shape.id);
+        if (rows < THRESHOLDS.tiny) return change(f, "low", { ...base, note: `${table} has only ${fmt(rows)} ${u}: harmless today, but it will grow with the table.` });
+        if (rows >= THRESHOLDS.huge) return change(f, "critical", { ...base, note: `Reads all ${fmt(rows)} ${u} of ${table} on every call.` });
+        return { ...f, evidence: { ...base, note: `Reads all ${fmt(rows)} ${u} of ${table} on every call.` } };
+      }
+      case "MQ005": {
+        handled.add(shape.id);
+        const covered = tableIndexes(table).find((i) => indexCovers(i, shape.filterKeys, shape.sortKeys));
+        if (covered) return change(f, "low", { ...base, source: "indexes", index: covered.name, note: `Index ${covered.name} already serves this filter and sort; adding a limit is still recommended.` });
+        const idx = suggestIndex(data.adapter, table, shape.filterKeys, shape.sortKeys);
+        return { ...f, evidence: { ...base, note: `No index serves this sort on ${table}${rows != null ? ` (${fmt(rows)} ${u})` : ""}.` }, fix: idx ? `Add .limit(n) and create: ${idx}` : f.fix };
+      }
+      case "SQ004":
+      case "MQ004":
+      case "SQ005":
+      case "SQ003":
+      case "MQ002":
+        if (plan?.fullScan) handled.add(shape.id);
+        return { ...f, evidence: base };
+      default:
+        return f;
+    }
+  });
+  const add = (ruleId, x) => {
+    const rule = RULE_MAP.get(ruleId);
+    out.push({ ruleId, title: rule.title, fix: x.fix ?? rule.fix, confidence: x.confidence ?? "high", lang: x.lang ?? "db", ...x });
+  };
+  const dbLoc = (table) => `db://${data.database}${table ? "/" + table : ""}`;
+  const seenPlan = /* @__PURE__ */ new Set();
+  for (const s of shapes) {
+    const plan = data.plans.get(s.id);
+    const table = data.shapeTables.get(s.id);
+    if (!plan || !table || handled.has(s.id)) continue;
+    const rows = rowsOf(table) ?? plan.estRows ?? 0;
+    const key = `${table}|${[...s.filterKeys].sort().join(",")}|${s.sortKeys.map((k) => k.key + k.dir).join(",")}|${s.file}`;
+    if (seenPlan.has(key)) continue;
+    seenPlan.add(key);
+    const idx = suggestIndex(data.adapter, table, s.filterKeys, s.sortKeys);
+    const snippet = s.sql ?? `${table}.${s.method}(${s.filterKeys.length ? `{ ${s.filterKeys.join(", ")} }` : ""})${s.sortKeys.length ? `.sort({ ${s.sortKeys.map((k) => `${k.key}: ${k.dir}`).join(", ")} })` : ""}`;
+    const ev = { source: "explain", collection: table, rows, plan: planText(plan), index: plan.indexUsed, docsExamined: plan.docsExamined, ms: plan.ms, note: "" };
+    if (plan.fullScan && rows >= THRESHOLDS.scanMin) {
+      add("LV001", {
+        severity: rows >= THRESHOLDS.huge ? "critical" : "high",
+        db: s.db,
+        file: s.file,
+        line: s.line,
+        column: 1,
+        snippet,
+        message: `Full ${data.adapter === "mongodb" ? "collection" : "table"} scan of ${table} (${fmt(rows)} ${u})${s.filterKeys.length ? ` filtering on ${s.filterKeys.join(", ")}` : ""}${s.inLoop ? ", inside a loop" : ""}.`,
+        fix: idx ? `Create an index: ${idx}` : void 0,
+        evidence: { ...ev, note: `${table}: ${fmt(rows)} ${u} \xB7 ${planText(plan)}` },
+        fingerprint: fp("LV001", s.file, table, key),
+        shapeId: s.id
+      });
+    } else if (plan.inMemorySort && s.sortKeys.length && rows >= THRESHOLDS.scanMin) {
+      add("LV002", {
+        severity: "medium",
+        db: s.db,
+        file: s.file,
+        line: s.line,
+        column: 1,
+        snippet,
+        message: `Sorts ${table} in memory on ${s.sortKeys.map((k) => k.key).join(", ")} (${fmt(rows)} ${u}).`,
+        fix: idx ? `Create an index: ${idx}` : void 0,
+        evidence: { ...ev, note: `${table}: ${fmt(rows)} ${u} \xB7 ${planText(plan)}` },
+        fingerprint: fp("LV002", s.file, table, key),
+        shapeId: s.id
+      });
+    }
+  }
+  for (const q of data.slow) {
+    const shape = matchSlowQuery(q, shapes, data.shapeTables);
+    const idx = q.table ? suggestIndex(data.adapter, q.table, q.filterKeys, q.sortKeys) : void 0;
+    const covered = q.table ? tableIndexes(q.table).some((i) => indexCovers(i, q.filterKeys, q.sortKeys)) : false;
+    add("LV003", {
+      severity: q.meanMs >= THRESHOLDS.criticalMs ? "critical" : "high",
+      db: data.adapter === "mongodb" ? "mongodb" : "sql",
+      file: shape?.file ?? dbLoc(q.table),
+      line: shape?.line ?? 0,
+      column: shape ? 1 : 0,
+      lang: shape ? void 0 : "db",
+      snippet: q.text.slice(0, 240),
+      message: `Averages ${Math.round(q.meanMs)}ms over ${q.calls} call(s)${q.table ? ` on ${q.table}` : ""}${q.plan ? ` (${q.plan})` : ""}${shape ? "" : ". No matching call found in the code."}`,
+      fix: idx && !covered ? `Likely missing index: ${idx}` : void 0,
+      evidence: { source: "profiler", collection: q.table, ms: Math.round(q.meanMs), plan: q.plan, docsExamined: q.docsExamined, note: `${q.calls} call(s), mean ${Math.round(q.meanMs)}ms${q.docsExamined != null ? `, ${fmt(q.docsExamined)} ${u} examined` : ""}` },
+      fingerprint: fp("LV003", q.table, q.filterKeys.join(","), q.sortKeys.map((k) => k.key).join(",")),
+      shapeId: shape?.id,
+      confidence: shape ? "high" : "medium"
+    });
+  }
+  for (const i of data.indexes) {
+    if (i.usage !== 0 || i.primary || i.unique || i.name === "_id_") continue;
+    const drop = data.adapter === "mongodb" ? `db.${i.table}.dropIndex("${i.name}")` : `DROP INDEX CONCURRENTLY "${i.name}";`;
+    add("LV004", {
+      severity: "low",
+      db: data.adapter === "mongodb" ? "mongodb" : "sql",
+      file: dbLoc(i.table),
+      line: 0,
+      column: 0,
+      snippet: i.definition ?? `${i.name} (${i.keys.map((k) => k.key).join(", ")})`,
+      message: `Index ${i.name} on ${i.table} has not been used since statistics were reset.`,
+      fix: `Confirm on every replica over a full business cycle, then: ${drop}`,
+      evidence: { source: "indexes", collection: i.table, index: i.name, note: `0 uses recorded` },
+      fingerprint: fp("LV004", i.table, i.name)
+    });
+  }
+  for (const k of data.fks) {
+    const indexed = tableIndexes(k.table).some((i) => i.keys[0]?.key === k.column);
+    if (indexed) continue;
+    const users = shapes.filter((s2) => data.shapeTables.get(s2.id) === k.table && s2.filterKeys.includes(k.column));
+    if (!users.length) continue;
+    const s = users.find((x) => x.inLoop) ?? users[0];
+    add("LV005", {
+      severity: "medium",
+      db: "sql",
+      file: s.file,
+      line: s.line,
+      column: 1,
+      snippet: s.sql ?? `${k.table}.${k.column} \u2192 ${k.refTable}`,
+      message: `${k.table}.${k.column} references ${k.refTable} but has no index; ${users.length} quer${users.length === 1 ? "y filters" : "ies filter"} on it.`,
+      fix: `CREATE INDEX CONCURRENTLY ON "${k.table}" ("${k.column}");`,
+      evidence: { source: "indexes", collection: k.table, rows: rowsOf(k.table), note: `no index starts with ${k.column}` },
+      fingerprint: fp("LV005", k.table, k.column),
+      shapeId: s.id
+    });
+  }
+  return out;
+}
+
+// src/live/mongo.ts
+var keysOf = (spec) => Object.entries(spec ?? {}).map(([key, v]) => ({ key, dir: Number(v) === -1 ? -1 : 1 }));
+function filterFields(filter) {
+  const out = /* @__PURE__ */ new Set();
+  const walk = (f) => {
+    if (!f || typeof f !== "object") return;
+    for (const [k, v] of Object.entries(f)) {
+      if (k === "$and" || k === "$or" || k === "$nor") (Array.isArray(v) ? v : []).forEach(walk);
+      else if (!k.startsWith("$")) out.add(k);
+    }
+  };
+  walk(filter);
+  return [...out];
+}
+function summarisePlan(plan, table) {
+  const stages = [];
+  let fullScan = false;
+  let inMemorySort = false;
+  let indexUsed;
+  const walk = (n) => {
+    if (!n || typeof n !== "object") return;
+    const node = n.queryPlan ?? n;
+    const stage = node.stage;
+    if (stage) {
+      stages.push(stage === "IXSCAN" && node.indexName ? `IXSCAN ${node.indexName}` : stage);
+      if (stage === "COLLSCAN") fullScan = true;
+      if (stage === "SORT") inMemorySort = true;
+      if ((stage === "IXSCAN" || stage === "COUNT_SCAN" || stage === "DISTINCT_SCAN") && node.indexName) indexUsed ??= node.indexName;
+      if (stage === "IDHACK" || stage === "EXPRESS_IXSCAN" || stage === "EXPRESS_CLUSTERED_IXSCAN") indexUsed ??= "_id_";
+    }
+    walk(node.inputStage);
+    (node.inputStages ?? []).forEach(walk);
+  };
+  walk(plan);
+  return { table, fullScan, inMemorySort, indexUsed, text: stages.reverse().join(" \u2192 ") || "unknown" };
+}
+var MongoAdapter = class {
+  // eslint-disable-line @typescript-eslint/no-explicit-any
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  name = "mongodb";
+  database = "";
+  client;
+  // eslint-disable-line @typescript-eslint/no-explicit-any
+  db;
+  async connect() {
+    let mod;
+    try {
+      mod = await import("mongodb");
+    } catch {
+      throw new Error('The "mongodb" driver is not installed. Run: npm i -D mongodb');
+    }
+    this.client = new mod.MongoClient(this.opts.uri, {
+      appName: "querydig",
+      readPreference: "secondaryPreferred",
+      serverSelectionTimeoutMS: 8e3,
+      connectTimeoutMS: 8e3,
+      retryWrites: false
+    });
+    await this.client.connect();
+    const fromUri = this.client.options?.dbName ?? void 0;
+    const name = this.opts.db ?? (fromUri && fromUri !== "test" ? fromUri : void 0);
+    if (!name) throw new Error("No database name in the URI. Add it to the path (mongodb://host/mydb) or pass --db <name>.");
+    this.database = name;
+    this.db = this.client.db(name);
+  }
+  get t() {
+    return this.opts.timeoutMs;
+  }
+  async tables() {
+    const cols = await this.db.listCollections({ type: "collection" }, { nameOnly: true }).toArray();
+    const names = cols.map((c) => c.name).filter((n) => !n.startsWith("system."));
+    const out = [];
+    for (const name of names) {
+      try {
+        out.push({ name, rows: await this.db.collection(name).estimatedDocumentCount({ maxTimeMS: this.t }) });
+      } catch {
+        out.push({ name, rows: 0 });
+      }
+    }
+    return out;
+  }
+  async indexes(tables) {
+    const out = [];
+    for (const table of tables) {
+      const coll = this.db.collection(table);
+      let list = [];
+      try {
+        list = await coll.listIndexes().toArray();
+      } catch {
+        continue;
+      }
+      const usage = /* @__PURE__ */ new Map();
+      try {
+        const stats = await coll.aggregate([{ $indexStats: {} }], { maxTimeMS: this.t }).toArray();
+        for (const s of stats) usage.set(s.name, (usage.get(s.name) ?? 0) + Number(s.accesses?.ops ?? 0));
+      } catch {
+      }
+      for (const i of list) {
+        out.push({
+          table,
+          name: i.name,
+          keys: keysOf(i.key),
+          unique: !!i.unique,
+          primary: i.name === "_id_",
+          usage: usage.size ? usage.get(i.name) ?? 0 : void 0,
+          definition: `${i.name} ${JSON.stringify(i.key)}`
+        });
+      }
+    }
+    return out;
+  }
+  async foreignKeys() {
+    return [];
+  }
+  async explain(shape, table) {
+    if (!["read", "readMany", "count"].includes(shape.kind)) return null;
+    const filter = Object.fromEntries(shape.filterKeys.map((k) => [k, null]));
+    const sort = Object.fromEntries(shape.sortKeys.map((k) => [k.key, k.dir]));
+    const verbosity = this.opts.explainExecute ? "executionStats" : "queryPlanner";
+    const cursor = this.db.collection(table).find(filter, { sort: shape.sortKeys.length ? sort : void 0, limit: shape.hasLimit ? 1 : void 0, maxTimeMS: this.t });
+    const res = await cursor.explain(verbosity);
+    const qp = res.queryPlanner ?? res.stages?.[0]?.$cursor?.queryPlanner;
+    const sum = summarisePlan(qp?.winningPlan, table);
+    const es = res.executionStats;
+    return { ...sum, docsExamined: es?.totalDocsExamined, ms: es?.executionTimeMillis };
+  }
+  async slowQueries(slowMs) {
+    let level = 0;
+    try {
+      const p = await this.db.command({ profile: -1 });
+      level = Number(p.was ?? 0);
+    } catch {
+      return [];
+    }
+    const prof = this.db.collection("system.profile");
+    let rows = [];
+    try {
+      rows = await prof.aggregate([
+        { $match: { millis: { $gte: slowMs }, op: { $in: ["query", "command", "getmore", "update", "remove"] }, appName: { $ne: "querydig" }, ns: { $not: /\.system\./ } } },
+        { $group: { _id: { ns: "$ns", h: { $ifNull: ["$queryHash", "$planCacheShapeHash"] } }, calls: { $sum: 1 }, ms: { $avg: "$millis" }, ex: { $avg: "$docsExamined" }, cmd: { $first: "$command" }, plan: { $first: "$planSummary" } } },
+        { $sort: { ms: -1 } },
+        { $limit: 50 }
+      ], { maxTimeMS: this.t }).toArray();
+    } catch {
+      return [];
+    }
+    if (!rows.length && level === 0) return [];
+    return rows.map((r) => {
+      const ns = r._id.ns ?? "";
+      const table = ns.includes(".") ? ns.slice(ns.indexOf(".") + 1) : void 0;
+      const cmd = r.cmd ?? {};
+      const filter = cmd.filter ?? cmd.q ?? cmd.query ?? cmd.pipeline?.[0]?.$match;
+      return {
+        table,
+        filterKeys: filterFields(filter),
+        sortKeys: keysOf(cmd.sort),
+        meanMs: Number(r.ms),
+        calls: Number(r.calls),
+        text: JSON.stringify({ [Object.keys(cmd)[0] ?? "op"]: table, filter: filter ?? {}, ...cmd.sort ? { sort: cmd.sort } : {} }),
+        plan: r.plan,
+        docsExamined: r.ex != null ? Math.round(r.ex) : void 0
+      };
+    });
+  }
+  async warnings() {
+    const w = [];
+    try {
+      const p = await this.db.command({ profile: -1 });
+      if (Number(p.was ?? 0) === 0) w.push(`Profiling is off on ${this.database}, so slow queries (LV003) can't be read. Enable with db.setProfilingLevel(1, { slowms: 100 }) on a replica.`);
+    } catch {
+    }
+    try {
+      const s = await this.db.command({ connectionStatus: 1, showPrivileges: true });
+      const users = s.authInfo?.authenticatedUsers ?? [];
+      const privs = s.authInfo?.authenticatedUserPrivileges ?? [];
+      const writes = privs.some((p) => (p.actions ?? []).some((a) => ["insert", "update", "remove", "dropCollection", "createIndex"].includes(a)));
+      if (!users.length) w.push('Connected without authentication. querydig only sends read commands, but prefer a user with the built-in "read" role.');
+      else if (writes) w.push('The connected user can write. querydig only sends read commands, but a user with the built-in "read" role is safer.');
+    } catch {
+    }
+    return w;
+  }
+  async close() {
+    await this.client?.close().catch(() => void 0);
+  }
+};
+
+// src/live/postgres.ts
+var SCHEMA_FILTER = `n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_toast%'`;
+var ident = (s) => `"${s.replace(/"/g, '""')}"`;
+function summarisePgPlan(root, table) {
+  const stages = [];
+  let fullScan = false;
+  let inMemorySort = false;
+  let indexUsed;
+  const walk = (n) => {
+    if (!n) return;
+    const t = n["Node Type"];
+    const rel = n["Relation Name"];
+    stages.push(t === "Seq Scan" && rel ? `Seq Scan on ${rel}` : n["Index Name"] ? `${t} ${n["Index Name"]}` : t);
+    if (t === "Seq Scan" && (!rel || rel === table)) fullScan = true;
+    if (t === "Sort" || t === "Incremental Sort") inMemorySort = true;
+    if (n["Index Name"]) indexUsed ??= n["Index Name"];
+    (n.Plans ?? []).forEach(walk);
+  };
+  walk(root);
+  return {
+    table,
+    fullScan,
+    inMemorySort,
+    indexUsed,
+    text: stages.join(" \u2192 ") || "unknown",
+    estRows: root?.["Plan Rows"],
+    ms: root?.["Actual Total Time"] != null ? Math.round(root["Actual Total Time"]) : void 0,
+    docsExamined: void 0
+  };
+}
+var PostgresAdapter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  name = "postgres";
+  database = "";
+  client;
+  // eslint-disable-line @typescript-eslint/no-explicit-any
+  version = 0;
+  columns = /* @__PURE__ */ new Map();
+  async connect() {
+    let pg;
+    try {
+      pg = (await import("pg")).default;
+    } catch {
+      throw new Error('The "pg" driver is not installed. Run: npm i -D pg');
+    }
+    this.client = new pg.Client({ connectionString: this.opts.uri, application_name: "querydig", connectionTimeoutMillis: 8e3, statement_timeout: this.opts.timeoutMs });
+    await this.client.connect();
+    await this.client.query("SET default_transaction_read_only = on");
+    await this.client.query(`SET statement_timeout = ${Math.max(1e3, Math.floor(this.opts.timeoutMs))}`);
+    const r = await this.client.query(`SELECT current_database() AS db, current_setting('server_version_num')::int AS v`);
+    this.database = r.rows[0].db;
+    this.version = r.rows[0].v;
+  }
+  async q(sql, params = []) {
+    return (await this.client.query(sql, params)).rows;
+  }
+  async tables() {
+    const rows = await this.q(`
+      SELECT c.relname AS name, c.reltuples::bigint AS reltuples, COALESCE(s.n_live_tup, 0)::bigint AS live, pg_total_relation_size(c.oid)::bigint AS size
+      FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+      LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
+      WHERE c.relkind IN ('r', 'p') AND ${SCHEMA_FILTER}`);
+    const cols = await this.q(`
+      SELECT c.relname AS t, a.attname AS col FROM pg_attribute a
+      JOIN pg_class c ON c.oid = a.attrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE a.attnum > 0 AND NOT a.attisdropped AND c.relkind IN ('r', 'p') AND ${SCHEMA_FILTER}`);
+    for (const c of cols) (this.columns.get(c.t) ?? this.columns.set(c.t, /* @__PURE__ */ new Set()).get(c.t)).add(c.col);
+    return rows.map((r) => ({ name: r.name, rows: Math.max(Number(r.reltuples), Number(r.live), 0), sizeBytes: Number(r.size) }));
+  }
+  async indexes() {
+    const rows = await this.q(`
+      SELECT t.relname AS tbl, i.relname AS idx, ix.indisunique AS uniq, ix.indisprimary AS pk, s.idx_scan AS scans,
+             pg_get_indexdef(ix.indexrelid) AS def,
+             ARRAY(SELECT a.attname FROM unnest(ix.indkey) WITH ORDINALITY k(attnum, ord)
+                   JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum ORDER BY k.ord)::text[] AS cols,
+             ARRAY(SELECT (o::int & 1) FROM unnest(ix.indoption) AS o)::int[] AS desc_flags
+      FROM pg_index ix
+      JOIN pg_class t ON t.oid = ix.indrelid JOIN pg_class i ON i.oid = ix.indexrelid
+      JOIN pg_namespace n ON n.oid = t.relnamespace
+      LEFT JOIN pg_stat_user_indexes s ON s.indexrelid = ix.indexrelid
+      WHERE ${SCHEMA_FILTER}`);
+    return rows.map((r) => ({
+      table: r.tbl,
+      name: r.idx,
+      unique: r.uniq,
+      primary: r.pk,
+      usage: r.scans == null ? void 0 : Number(r.scans),
+      definition: r.def,
+      keys: r.cols.map((key, i) => ({ key, dir: Number(r.desc_flags[i]) === 1 ? -1 : 1 }))
+    }));
+  }
+  async foreignKeys() {
+    const rows = await this.q(`
+      SELECT cl.relname AS tbl, a.attname AS col, rt.relname AS ref
+      FROM pg_constraint c
+      JOIN pg_class cl ON cl.oid = c.conrelid JOIN pg_class rt ON rt.oid = c.confrelid
+      JOIN pg_namespace n ON n.oid = cl.relnamespace
+      JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = c.conkey[1]
+      WHERE c.contype = 'f' AND array_length(c.conkey, 1) = 1 AND ${SCHEMA_FILTER}`);
+    return rows.map((r) => ({ table: r.tbl, column: r.col, refTable: r.ref }));
+  }
+  /** SQL to explain for a shape, or null when it can't be explained safely. */
+  explainSql(shape, table) {
+    if (shape.sql) {
+      const sql = shape.sql.trim().replace(/;\s*$/, "");
+      if (!/^\s*(select|with)\b/i.test(sql) || /\?/.test(sql) || /;/.test(sql)) return null;
+      return { sql, generic: /\$\d/.test(sql) };
+    }
+    if (!["read", "readMany", "count"].includes(shape.kind)) return null;
+    const cols = this.columns.get(table);
+    const filter = shape.filterKeys.filter((k) => cols?.has(k));
+    const sort = shape.sortKeys.filter((k) => cols?.has(k.key));
+    if (filter.length !== shape.filterKeys.length) return null;
+    const where = filter.length ? ` WHERE ${filter.map((k, i) => `${ident(k)} = $${i + 1}`).join(" AND ")}` : "";
+    const order = sort.length ? ` ORDER BY ${sort.map((k) => `${ident(k.key)}${k.dir === -1 ? " DESC" : ""}`).join(", ")}` : "";
+    return { sql: `SELECT 1 FROM ${ident(table)}${where}${order}${shape.hasLimit ? " LIMIT 1" : ""}`, generic: filter.length > 0 };
+  }
+  async explain(shape, table) {
+    const e = this.explainSql(shape, table);
+    if (!e) return null;
+    if (e.generic && this.version < 16e4) return null;
+    const analyze = this.opts.explainExecute && !e.generic;
+    const opts = ["FORMAT JSON", e.generic ? "GENERIC_PLAN" : "", analyze ? "ANALYZE" : ""].filter(Boolean).join(", ");
+    const rows = await this.q(`EXPLAIN (${opts}) ${e.sql}`);
+    const plan = rows[0]?.["QUERY PLAN"]?.[0]?.Plan;
+    return summarisePgPlan(plan, table);
+  }
+  async slowQueries(slowMs) {
+    const ext = await this.q(`SELECT 1 FROM pg_extension WHERE extname = 'pg_stat_statements'`);
+    if (!ext.length) return [];
+    let rows = [];
+    try {
+      rows = await this.q(`
+        SELECT query, calls, mean_exec_time AS mean FROM pg_stat_statements
+        WHERE dbid = (SELECT oid FROM pg_database WHERE datname = current_database())
+          AND mean_exec_time >= $1 AND query !~* '(pg_catalog|information_schema|pg_class|pg_stat|pg_index|pg_attribute|pg_constraint|pg_extension|pg_roles|pg_database|^\\s*(explain|set|show|begin|commit|rollback)\\b)'
+        ORDER BY total_exec_time DESC LIMIT 50`, [slowMs]);
+    } catch {
+      return [];
+    }
+    return rows.map((r) => {
+      const sh = sqlShape(r.query);
+      return { table: sh.table, filterKeys: sh.filterKeys, sortKeys: sh.sortKeys, meanMs: Number(r.mean), calls: Number(r.calls), text: String(r.query).replace(/\s+/g, " ").trim() };
+    });
+  }
+  async warnings() {
+    const w = [];
+    try {
+      const ext = await this.q(`SELECT 1 FROM pg_extension WHERE extname = 'pg_stat_statements'`);
+      if (!ext.length) w.push("pg_stat_statements is not installed, so slow queries (LV003) can't be read. Enable it with CREATE EXTENSION pg_stat_statements.");
+      const r = await this.q(`SELECT rolsuper FROM pg_roles WHERE rolname = current_user`);
+      const writes = await this.q(`SELECT count(*)::int AS n FROM information_schema.table_privileges WHERE grantee = current_user AND privilege_type IN ('INSERT', 'UPDATE', 'DELETE')`);
+      if (r[0]?.rolsuper) w.push("Connected as a superuser. querydig runs every statement in a read-only transaction, but a role with pg_read_all_stats and SELECT is safer.");
+      else if (writes[0]?.n > 0) w.push("The connected role can write. querydig runs every statement in a read-only transaction, but a read-only role is safer.");
+      if (this.version < 16e4) w.push(`PostgreSQL ${Math.floor(this.version / 1e4)} can't plan parameterized queries; upgrade to 16+ for full explain coverage.`);
+    } catch {
+    }
+    return w;
+  }
+  async close() {
+    await this.client?.end().catch(() => void 0);
+  }
+};
+
+// src/live/index.ts
+function adapterFor(opts) {
+  if (/^mongodb(\+srv)?:\/\//i.test(opts.uri)) return new MongoAdapter(opts);
+  if (/^postgres(ql)?:\/\//i.test(opts.uri)) return new PostgresAdapter(opts);
+  throw new Error("Unsupported --uri. Use mongodb://, mongodb+srv://, postgres:// or postgresql://");
+}
+async function pool(items, n, fn) {
+  const out = [];
+  let i = 0;
+  await Promise.all(Array.from({ length: Math.min(n, items.length) }, async () => {
+    while (i < items.length) {
+      const idx = i++;
+      out[idx] = await fn(items[idx]);
+    }
+  }));
+  return out;
+}
+async function collectLive(shapes, opts, adapter = adapterFor(opts)) {
+  try {
+    await adapter.connect();
+    const tableList = await adapter.tables();
+    const tables = new Map(tableList.map((t) => [t.name, t]));
+    const relevantDb = adapter.name === "mongodb" ? "mongodb" : "sql";
+    const shapeTables = /* @__PURE__ */ new Map();
+    for (const s of shapes) {
+      if (s.db !== relevantDb && s.db !== "unknown") continue;
+      const t = resolveTable(s.collection, tables.keys());
+      if (t) shapeTables.set(s.id, t);
+    }
+    const used = [...new Set(shapeTables.values())];
+    const indexes = await adapter.indexes(adapter.name === "mongodb" ? used.length ? used : [...tables.keys()] : [...tables.keys()]);
+    const fks = await adapter.foreignKeys().catch(() => []);
+    const groups = /* @__PURE__ */ new Map();
+    for (const s of shapes) {
+      const t = shapeTables.get(s.id);
+      if (!t) continue;
+      const key = `${t}|${[...s.filterKeys].sort().join(",")}|${s.sortKeys.map((k) => k.key + k.dir).join(",")}|${s.kind}|${s.hasLimit}|${s.sql ?? ""}`;
+      (groups.get(key) ?? groups.set(key, []).get(key)).push(s);
+    }
+    const plans = /* @__PURE__ */ new Map();
+    const work = [...groups.values()].slice(0, opts.maxExplain);
+    let explained = 0;
+    await pool(work, adapter.name === "postgres" ? 1 : 4, async (group) => {
+      const s = group[0];
+      try {
+        const p = await adapter.explain(s, shapeTables.get(s.id));
+        if (p) {
+          explained++;
+          for (const g of group) plans.set(g.id, p);
+        }
+      } catch {
+      }
+    });
+    const slow = await adapter.slowQueries(opts.slowMs).catch(() => []);
+    const warnings = await adapter.warnings().catch(() => []);
+    if (groups.size > opts.maxExplain) warnings.push(`Explained ${opts.maxExplain} of ${groups.size} query shapes (raise with --max-explain).`);
+    if (!shapeTables.size && shapes.length) warnings.push(`None of the ${shapes.length} queries in the code matched a ${adapter.name === "mongodb" ? "collection" : "table"} in ${adapter.database}. Is this the right database?`);
+    return { adapter: adapter.name, database: adapter.database, tables, indexes, plans, shapeTables, slow, fks, explained, warnings };
+  } catch (e) {
+    throw new Error(redactText(e.message, opts.uri));
+  } finally {
+    await adapter.close();
+  }
+}
+async function runLive(findings, shapes, opts) {
+  const adapterName = /^mongodb/i.test(opts.uri) ? "mongodb" : "postgres";
+  try {
+    const data = await collectLive(shapes, opts);
+    return {
+      findings: correlate(findings, shapes, data),
+      summary: { adapter: data.adapter, database: data.database, tables: data.tables.size, explained: data.explained, slowQueries: data.slow.length, warnings: data.warnings }
+    };
+  } catch (e) {
+    return { findings, summary: { adapter: adapterName, database: "", tables: 0, explained: 0, slowQueries: 0, warnings: [], error: `${e.message} (${redactUri(opts.uri)})` } };
+  }
+}
+export {
+  adapterFor,
+  collectLive,
+  correlate,
+  redactUri,
+  runLive
+};