pgexplain 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- 5a1be66: - **New rule `PGX_MEMOIZE_EVICTIONS`**: flags a thrashing Memoize cache (evictions outpacing hits, or cache overflows) with a `work_mem` / `hash_mem_multiplier` remediation. The parser now normalizes Memoize cache counters (`Cache Hits/Misses/Evictions/Overflows`).
+  - **Studio component tests**: React Testing Library + happy-dom cover FindingCard, the side-by-side DiffPanel, and toasts; the web test project runs in CI via `pnpm test`.
+  - **Fix `PGX_CARTESIAN_PRODUCT` false positive**: the rule now looks through Memoize/Materialize to the real inner scan, so `Nested Loop → Memoize → Index Scan (parameterized)` is no longer misreported as a cross join.
+- 5a1be66: New analysis capabilities:
+
+  - **New rule `PGX_LIMIT_LARGE_OFFSET`**: flags OFFSET-style pagination where the plan generates and discards a large row prefix; recommends keyset pagination. Tunable via `limitDiscardRows`.
+  - **New check `PGX_STALE_STATISTICS`** (run path only): flags tables in the plan that were never analyzed or churned past `staleStatsModRatio` (default 20%) since their last ANALYZE — the usual root cause behind row misestimates.
+  - **New command `pg-explain locks`**: live lock-contention snapshot (who is blocked, by whom, for how long) with cancel/terminate remediation; `--fail-on-blocked` exits 1 for scripting; terminal and JSON output.
+  - **Studio: side-by-side plan diff** — the diff view now renders both plan trees with slower/faster/added/removed nodes highlighted.
+  - **Studio: shareable run URLs** — every stored run gets a `#run=<id>` deep link plus a copy-link button.
+  - Shell completion now includes the `locks` and `studio` subcommands.
+
+### Patch Changes
+
+- 5a1be66: Studio & DX quality pass:
+
+  - Studio: toast notifications — export failures and settings saves are no longer silent
+  - Studio: keyboard shortcuts (⌘/Ctrl+K focus editor, ⇧⌘/Ctrl+F format SQL, `?` help overlay) and ARIA tablist/landmark roles
+  - Studio: collapsible sidebar and history filter box
+  - Library: export `severityAtLeast` for CI-gate scripting; README library examples expanded
+  - Tests: snapshot coverage for all five render formats, command-flow tests for `analyze`/`diff` exit codes, and a new `web` vitest project covering studio helpers
+  - Dev: `pnpm dev:studio` runs core rebuild + API restart + Vite HMR in one terminal
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

package/README.md

@@ -24,6 +24,31 @@ The same philosophy applies to operational errors: auth failures, timeouts, unre
 
 ---
 
+## Features
+
+**Advisor & analysis**
+- **18 plan-anti-pattern rules** (`PGX_*`) — cartesian products, large seq scans, disk-spilling sorts/hashes, thrashing Memoize caches, misestimates, lossy bitmaps, OFFSET pagination, low cache-hit ratio, JIT/trigger overhead, and more.
+- **`PGX_STALE_STATISTICS`** — on the `run` path, flags tables that were never analyzed or have churned since their last `ANALYZE`, explaining the usual root cause behind misestimates.
+- **Lock advisor** — static warnings for risky DDL/DML (table rewrites, missing `CONCURRENTLY`, unbounded `FOR UPDATE`, …) plus a **live lock-contention** snapshot (who is blocked, by whom).
+- Every finding ships **what / why / fix**, with copy-pasteable SQL/shell commands and a Postgres docs link.
+- Config file (`.pgexplainrc[.json]` or `package.json#pgExplain`) to tune thresholds and enable/disable/re-sever individual rules.
+
+**CLI**
+- `pg-explain [FILE]` — analyze a plan from a file, `< stdin`, or a whole directory (batch mode).
+- `pg-explain run` — connect, `EXPLAIN` safely (rolled back, read-only unless `--force`), analyze.
+- `pg-explain diff` — compare two plans and gate CI on regressions or new findings.
+- `pg-explain locks` — snapshot live lock contention from the terminal; `--fail-on-blocked` for scripting.
+- `pg-explain studio` — launch the local web UI.
+- 5 output formats (terminal, markdown, HTML, JSON, plain text), stable exit codes for scripting, shell completion.
+
+**Studio (local web UI)** — see screenshots below.
+- Run a query or paste a plan; interactive **plan graph** (heat-colored by time/rows/cost/buffers) with per-node detail, or a text tree view.
+- **History** of every run, **side-by-side plan diff** between any two, and **shareable `#run=` links**.
+- **Stats** by node type / table / index, table catalog with autocomplete, **Settings** to tune thresholds live.
+- Keyboard shortcuts (`⌘/Ctrl+Enter` run, `⌘/Ctrl+K` focus editor, `⇧⌘/Ctrl+F` format, `?` for help), light/dark theme, collapsible sidebar with history search.
+
+---
+
 ## Install
 
 ```sh
@@ -85,16 +110,63 @@ just works — the PostgreSQL driver and the UI are only loaded on demand.
   rollback-wrapped, read-only; non-`SELECT` refused unless forced).
 - **Findings** as plain-language cards (what / why / fix + copy-paste commands + docs links).
 - **Lock advisor** — static warnings (rewrites, missing `CONCURRENTLY`, unindexed `UPDATE/DELETE`,
-  unbounded `FOR UPDATE`, …) plus a **🔒 Live locks** view of current blocking chains.
-- Interactive **plan tree** (heat-colored by self-time), **bottlenecks**, raw JSON.
-- **History** of every run (SQLite under `~/.pgexplain`), **Compare** any two runs (structured
-  diff), and **Export** to Markdown / HTML / JSON.
-- **Saved connections** and a **Settings** page to tune advisor thresholds (applied live).
+  unbounded `FOR UPDATE`, …) plus a **live locks** view of current blocking chains.
+- Interactive **plan graph** (heat-colored by time/rows/cost/buffers, click a node for full detail)
+  or a plain-text tree, **Stats** by node type/table/index, table catalog with autocomplete.
+- **History** of every run (SQLite under `~/.pgexplain`), a **side-by-side diff** between any two
+  runs with regressed/improved/added/removed nodes highlighted, and **shareable `#run=` links**.
+- **Export** to Markdown / HTML / JSON, and a **Settings** page to tune advisor thresholds live.
+- Light/dark theme, keyboard shortcuts (`?` for the full list), collapsible sidebar with history search.
 
 Flags: `pg-explain studio [--port 5177] [--host 127.0.0.1] [--no-open] [--unsafe-host]`.
 Binding a non-loopback host requires `--unsafe-host` (the studio can reach arbitrary databases,
 so exposing it is an SSRF/credential risk). Set `PGEXPLAIN_DATA_DIR` to relocate the local store.
 
+<table>
+<tr>
+<td width="50%">
+
+**Findings** — what / why / fix, with copy-pasteable SQL
+<img src="docs/screenshots/findings-light.png" alt="Studio findings tab showing plain-language diagnostics with remediation SQL">
+
+</td>
+<td width="50%">
+
+**Plan graph** — heat-colored, click a node for full detail
+<img src="docs/screenshots/plan-graph.png" alt="Studio interactive plan graph with a node detail panel open">
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+**Side-by-side diff** — before/after plans with regressions highlighted
+<img src="docs/screenshots/diff-side-by-side.png" alt="Studio diff view comparing two runs with a side-by-side plan tree">
+
+</td>
+<td width="50%">
+
+**Stats** — self-time rolled up by node type, table, and index
+<img src="docs/screenshots/stats-tab.png" alt="Studio stats tab with self-time breakdowns">
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+**Dark mode**
+<img src="docs/screenshots/plan-graph-dark.png" alt="Studio in dark mode showing the plan graph">
+
+</td>
+<td width="50%">
+
+**Keyboard shortcuts** (press `?`)
+<img src="docs/screenshots/keyboard-shortcuts.png" alt="Studio keyboard shortcuts overlay">
+
+</td>
+</tr>
+</table>
+
 ---
 
 ## Example output
@@ -177,6 +249,8 @@ Total execution time: 321.0 ms
 | `pg-explain [FILE]` | **Analyze** a plan from a file, `< stdin`, or every plan in a directory (batch mode). This is the default command. |
 | `pg-explain run` | **Connect** to PostgreSQL, run `EXPLAIN` safely, and analyze the result. Needs the optional `pg` driver. |
 | `pg-explain diff <before> <after>` | **Compare** two plan JSON files and report regressions. Designed as a CI gate. |
+| `pg-explain locks` | Snapshot **live lock contention**: who is blocked and by whom (`pg_blocking_pids`), with a cancel/terminate remediation. `--fail-on-blocked` exits 1 for scripting. Needs the optional `pg` driver. |
+| `pg-explain studio` | Launch the local **web UI** (history, plan graph, diff, live locks). |
 | `pg-explain completion <bash\|zsh\|fish>` | Print a shell **completion** script for the given shell. |
 
 Run `pg-explain --help`, `pg-explain run --help`, or `pg-explain diff --help` for the full flag list.
@@ -239,7 +313,7 @@ Shared output flags: `--tldr` (summary + findings, no plan tree), `--redact` (st
 
 ## The advisor
 
-The advisor ships **16 rules**, each identified by a stable, greppable `PGX_*` code (the rule id is the diagnostic code, and the config key). They run in roughly most-actionable-first order:
+The advisor ships **18 rules**, each identified by a stable, greppable `PGX_*` code (the rule id is the diagnostic code, and the config key). They run in roughly most-actionable-first order:
 
 | Code | Flags when… |
 | --- | --- |
@@ -247,8 +321,10 @@ The advisor ships **16 rules**, each identified by a stable, greppable `PGX_*` c
 | `PGX_SEQ_SCAN_LARGE` | A sequential scan reads a large table that an index could narrow. |
 | `PGX_NESTED_LOOP_LARGE_OUTER` | A nested loop is driven by a large outer side (re-probes inner repeatedly). |
 | `PGX_HIGH_FILTER_DISCARD` | A node reads many rows then discards most of them via a filter. |
+| `PGX_LIMIT_LARGE_OFFSET` | A `LIMIT` discards a large generated prefix (OFFSET pagination — use keyset). |
 | `PGX_SORT_SPILL_DISK` | A sort spilled to disk instead of staying in `work_mem`. |
 | `PGX_HASH_SPILL_DISK` | A hash join's build side spilled to disk (multiple batches). |
+| `PGX_MEMOIZE_EVICTIONS` | A Memoize cache is thrashing (evictions outpace hits, or entries overflow `work_mem`). |
 | `PGX_CORRELATED_SUBPLAN` | A correlated subplan is re-executed once per outer row. |
 | `PGX_ROW_MISESTIMATE` | Estimated vs actual row counts diverge sharply (stale/missing stats). |
 | `PGX_FILTER_COULD_BE_INDEX_COND` | A residual filter could be pushed into an index condition. |
@@ -262,6 +338,8 @@ The advisor ships **16 rules**, each identified by a stable, greppable `PGX_*` c
 
 Every finding includes the *what / why / fix* triad shown in the example above. Rules can be tuned or disabled per project (see [Config](#config-file)).
 
+One additional check runs only on the `run` path (it needs a live connection, not just a plan): `PGX_STALE_STATISTICS` flags tables in the plan that were never analyzed or have churned past `staleStatsModRatio` (default 20%) since their last ANALYZE — the most common root cause behind `PGX_ROW_MISESTIMATE`. It is configured like any other rule.
+
 > pgexplain also has an **operational error catalog** of stable `PGX_*` codes — auth failures, unreachable hosts, SSL problems, timeouts, malformed/empty input, missing driver, and more — each with a title, cause, remediation, and Postgres docs link.
 
 ---
@@ -345,6 +423,24 @@ console.log(markdown);
 
 `analyze(input, options?)` parses the EXPLAIN JSON, optionally redacts literals, computes metrics, and runs the advisor. `render(result, options?)` emits any supported format. Other exports include `runAdvisor`, `parseExplainJson`, `computeMetrics`, `DEFAULT_CONFIG`, `FORMATS`, `JSON_SCHEMA_VERSION`, `ExitCode`, and the full type set.
 
+For finer control — e.g. custom thresholds or gating a deploy script on severity:
+
+```ts
+import { analyze, DEFAULT_CONFIG, severityAtLeast } from "pgexplain";
+
+const result = analyze(explainJson, {
+  config: {
+    ...DEFAULT_CONFIG,
+    thresholds: { ...DEFAULT_CONFIG.thresholds, seqScanRows: 10_000 },
+    rules: { PGX_LOW_CACHE_HIT: { enabled: false } },
+  },
+});
+
+if (result.worstSeverity && severityAtLeast(result.worstSeverity, "warn")) {
+  process.exit(1); // same behaviour as `pg-explain --fail-on warn`
+}
+```
+
 ---
 
 ## Exit codes

package/dist/cli.js

@@ -9,7 +9,7 @@ import { spawn } from 'child_process';
 
 // package.json
 var package_default = {
-  version: "0.2.0"};
+  version: "0.3.0"};
 
 // src/diagnostics/diagnostic.ts
 var AppError = class extends Error {
@@ -23,6 +23,9 @@ var AppError = class extends Error {
     if (cause !== void 0) this.cause = cause;
   }
 };
+function finding(code, severity, parts) {
+  return { code, domain: "plan", severity, ...parts };
+}
 var SEVERITY_RANK = { error: 0, warn: 1, info: 2 };
 function bySeverity(a, b) {
   return SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
@@ -430,7 +433,9 @@ var DEFAULT_THRESHOLDS = {
   correlatedLoops: 1e3,
   jitPct: 25,
   triggerPct: 10,
-  lowCacheHitRatio: 0.9
+  lowCacheHitRatio: 0.9,
+  limitDiscardRows: 1e4,
+  staleStatsModRatio: 0.2
 };
 var DEFAULT_CONFIG = {
   thresholds: { ...DEFAULT_THRESHOLDS },
@@ -894,6 +899,10 @@ function normalizeNode(raw, nextId) {
     diskUsage: num(raw, "Disk Usage"),
     exactHeapBlocks: num(raw, "Exact Heap Blocks"),
     lossyHeapBlocks: num(raw, "Lossy Heap Blocks"),
+    cacheHits: num(raw, "Cache Hits"),
+    cacheMisses: num(raw, "Cache Misses"),
+    cacheEvictions: num(raw, "Cache Evictions"),
+    cacheOverflows: num(raw, "Cache Overflows"),
     sharedHitBlocks: num(raw, "Shared Hit Blocks"),
     sharedReadBlocks: num(raw, "Shared Read Blocks"),
     sharedDirtiedBlocks: num(raw, "Shared Dirtied Blocks"),
@@ -1241,8 +1250,11 @@ var cartesianProduct = {
   check(node, ctx) {
     if (node.nodeType !== "Nested Loop") return [];
     if (node.joinFilter) return [];
-    const inner = node.children[1];
+    let inner = node.children[1];
     if (!inner) return [];
+    while ((inner.nodeType === "Memoize" || inner.nodeType === "Materialize") && inner.children[0]) {
+      inner = inner.children[0];
+    }
     if (inner.indexCond || inner.recheckCond) return [];
     const outer = node.children[0];
     if (!outer) return [];
@@ -1561,6 +1573,47 @@ var indexOnlyHeapFetches = {
   }
 };
 
+// src/advisor/rules/limit-large-offset.ts
+var limitLargeOffset = {
+  id: "PGX_LIMIT_LARGE_OFFSET",
+  title: "LIMIT discards a large prefix (OFFSET pagination)",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Limit") return [];
+    const child = outerChild(node);
+    const emitted = node.metrics.totalRows;
+    const produced = child?.metrics.totalRows;
+    if (emitted === void 0 || produced === void 0) return [];
+    const discarded = produced - emitted;
+    if (discarded < ctx.thresholds.limitDiscardRows) return [];
+    const rel = child?.relationName ?? "the input";
+    return [
+      makeFinding(limitLargeOffset, ctx, node, {
+        title: `LIMIT discarded ${fmtInt(discarded)} rows before returning ${fmtInt(emitted)}`,
+        detail: `The plan produced ${fmtInt(produced)} rows from ${rel} but the Limit node returned only ${fmtInt(emitted)} \u2014 ${fmtInt(discarded)} rows were generated just to be skipped.`,
+        cause: "OFFSET-style pagination makes Postgres compute and discard every row before the requested page, so deep pages get progressively slower (page N costs O(N)).",
+        remediation: {
+          summary: "Switch to keyset (seek) pagination: filter on the last-seen sort key instead of skipping rows, and keep an index on the sort key so each page is a direct index seek.",
+          steps: [
+            "Order by a unique (or tie-broken) key, e.g. ORDER BY created_at, id.",
+            "Pass the last row's key from the previous page instead of an OFFSET.",
+            "Index the sort key so the WHERE clause seeks directly to the page start."
+          ],
+          commands: [
+            {
+              label: "Keyset pagination instead of OFFSET",
+              sql: "SELECT \u2026 FROM t WHERE (created_at, id) > ($last_created_at, $last_id) ORDER BY created_at, id LIMIT 50;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/queries-limit.html`,
+        meta: { discarded: Math.round(discarded), emitted: Math.round(emitted) }
+      })
+    ];
+  }
+};
+
 // src/advisor/rules/low-cache-hit.ts
 var MIN_READ_BLOCKS = 1e3;
 var lowCacheHit = {
@@ -1607,6 +1660,46 @@ var lowCacheHit = {
   }
 };
 
+// src/advisor/rules/memoize-evictions.ts
+var memoizeEvictions = {
+  id: "PGX_MEMOIZE_EVICTIONS",
+  title: "Memoize cache is thrashing",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Memoize") return [];
+    const hits = node.cacheHits ?? 0;
+    const evictions = node.cacheEvictions ?? 0;
+    const overflows = node.cacheOverflows ?? 0;
+    const thrashing = evictions > hits;
+    if (!thrashing && overflows === 0) return [];
+    return [
+      makeFinding(memoizeEvictions, ctx, node, {
+        title: overflows > 0 ? `Memoize cache overflowed ${fmtInt(overflows)} time(s)` : `Memoize evicted ${fmtInt(evictions)} entries against ${fmtInt(hits)} hits`,
+        detail: `The Memoize cache recorded ${fmtInt(hits)} hits, ${fmtInt(node.cacheMisses ?? 0)} misses, ${fmtInt(evictions)} evictions, and ${fmtInt(overflows)} overflows \u2014 entries are being thrown away before they can be reused.`,
+        cause: "The distinct key values do not fit in the memory Memoize is allowed (derived from work_mem \xD7 hash_mem_multiplier), so the cache churns and the node degenerates into a slower re-executing inner side.",
+        remediation: {
+          summary: "Give the session more cache memory (work_mem / hash_mem_multiplier) so the key space fits, or reduce the number of distinct keys flowing into the Memoize.",
+          steps: [
+            "Estimate the distinct keys: the planner sizes the cache from ndistinct of the join key.",
+            "Raise work_mem (or hash_mem_multiplier on PG 15+) for this workload and re-run.",
+            "If the key space is genuinely huge, an index on the inner side may beat Memoize \u2014 compare with enable_memoize = off."
+          ],
+          commands: [
+            { label: "More cache memory for this session", sql: "SET work_mem = '64MB';" },
+            {
+              label: "Compare the plan without Memoize",
+              sql: "SET enable_memoize = off; EXPLAIN ANALYZE <query>;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html`,
+        meta: { hits, evictions, overflows }
+      })
+    ];
+  }
+};
+
 // src/advisor/rules/nested-loop-large-outer.ts
 var nestedLoopLargeOuter = {
   id: "PGX_NESTED_LOOP_LARGE_OUTER",
@@ -1989,8 +2082,10 @@ var ALL_RULES = [
   seqScanLarge,
   nestedLoopLargeOuter,
   highFilterDiscard,
+  limitLargeOffset,
   sortSpillDisk,
   hashSpillDisk,
+  memoizeEvictions,
   correlatedSubplan,
   rowMisestimate,
   filterCouldBeIndexCond,
@@ -2018,7 +2113,7 @@ function runAdvisor(tree, config = DEFAULT_CONFIG) {
     if (rule.requiresAnalyze && !tree.hasAnalyze) continue;
     if (rule.requiresBuffers && !tree.hasBuffers) continue;
     for (const node of nodes) {
-      for (const finding of rule.check(node, ctx)) diagnostics.push(finding);
+      for (const finding2 of rule.check(node, ctx)) diagnostics.push(finding2);
     }
   }
   diagnostics.sort(bySeverity);
@@ -2807,7 +2902,7 @@ function gateTrips(result, failOn) {
 }
 
 // src/commands/completion.ts
-var SUBCOMMANDS = "run diff completion";
+var SUBCOMMANDS = "run diff locks studio completion";
 var FLAGS = "--format --output --tldr --redact --ascii --color --no-color --fail-on --strict --config --statement --quiet --verbose --debug --help --version";
 var FORMATS2 = "terminal markdown json html text";
 var BASH = `# pg-explain bash completion
@@ -3274,6 +3369,25 @@ async function runExplain(opts) {
 function msInt(ms) {
   return Math.max(0, Math.floor(ms));
 }
+async function queryReadOnly(connection, sql, params = [], timeoutMs = 1e4) {
+  const ca = connection.sslrootcert ? await readFile(connection.sslrootcert, "utf8").catch(() => void 0) : void 0;
+  const client = await newClient(buildClientConfig(connection, ca));
+  try {
+    await client.connect();
+  } catch (err) {
+    throw mapConnectError(err);
+  }
+  try {
+    await client.query(`SET statement_timeout = ${msInt(timeoutMs)}`);
+    const res = await client.query({ text: sql, values: params });
+    return res.rows;
+  } catch (err) {
+    throw mapQueryError(err);
+  } finally {
+    await client.end().catch(() => {
+    });
+  }
+}
 async function explainScript(connection, units, opts) {
   const ca = connection.sslrootcert ? await readFile(connection.sslrootcert, "utf8").catch(() => void 0) : void 0;
   const client = await newClient(buildClientConfig(connection, ca));
@@ -3406,6 +3520,180 @@ function mapQueryError(err) {
   }
 }
 
+// src/locks/live.ts
+var SQL = `
+SELECT a.pid,
+       a.usename                                        AS "user",
+       a.state,
+       a.wait_event_type                                AS "waitEventType",
+       a.wait_event                                     AS "waitEvent",
+       EXTRACT(EPOCH FROM (now() - a.query_start))      AS "ageSeconds",
+       a.query,
+       pg_blocking_pids(a.pid)                          AS "blockedBy"
+FROM pg_stat_activity a
+WHERE a.backend_type = 'client backend' AND a.pid <> pg_backend_pid()
+ORDER BY cardinality(pg_blocking_pids(a.pid)) DESC, a.query_start NULLS LAST;
+`;
+async function liveLocks(connection, capturedAt) {
+  const rows = await queryReadOnly(connection, SQL);
+  const sessions = rows.map((r) => ({
+    pid: r.pid,
+    user: r.user,
+    state: r.state,
+    waitEventType: r.waitEventType,
+    waitEvent: r.waitEvent,
+    ageSeconds: r.ageSeconds == null ? null : Number(r.ageSeconds),
+    query: r.query,
+    blockedBy: r.blockedBy ?? []
+  }));
+  return { sessions, blocked: sessions.filter((s) => s.blockedBy.length > 0), capturedAt };
+}
+
+// src/commands/locks.ts
+async function runLocks(args) {
+  const snapshot = await liveLocks(args.connection, Date.now());
+  configureColor(args.format === "terminal" ? args.color : "never");
+  const text = args.format === "json" ? `${JSON.stringify(snapshot, null, 2)}
+` : renderLocks(snapshot);
+  if (args.output) await writeFile(args.output, text);
+  else process.stdout.write(text);
+  return args.failOnBlocked && snapshot.blocked.length > 0 ? 1 /* CiGate */ : 0 /* Success */;
+}
+function renderLocks(live) {
+  const c = colors();
+  const out = [
+    c.bold("Live locks"),
+    c.dim(`${live.sessions.length} client session(s) \xB7 ${live.blocked.length} blocked`),
+    ""
+  ];
+  if (live.blocked.length === 0) {
+    out.push("No lock contention right now \u2014 nothing is waiting on another session.");
+    return `${out.join("\n")}
+`;
+  }
+  for (const s of live.blocked) {
+    const age = s.ageSeconds != null ? ` \xB7 waiting ${s.ageSeconds.toFixed(0)}s` : "";
+    const wait = s.waitEvent ? ` \xB7 ${s.waitEventType ?? "?"}/${s.waitEvent}` : "";
+    out.push(
+      `${c.yellow("\u26A0")} pid ${c.bold(String(s.pid))} (${s.user ?? "?"}) blocked by pid ${s.blockedBy.join(", ")}${age}${wait}`
+    );
+    if (s.query) out.push(c.dim(`  ${s.query.replace(/\s+/g, " ").slice(0, 200)}`));
+    out.push(
+      c.dim(
+        `  inspect the blocker; cancel with SELECT pg_cancel_backend(${s.blockedBy[0]}); or terminate with pg_terminate_backend(\u2026).`
+      ),
+      ""
+    );
+  }
+  return `${out.join("\n")}
+`;
+}
+
+// src/server/schema.ts
+var SQL2 = `
+SELECT c.relname                                    AS relation,
+       c.reltuples::bigint                          AS "estRows",
+       pg_total_relation_size(c.oid)                AS "totalBytes",
+       pg_relation_size(c.oid)                      AS "tableBytes",
+       (SELECT array_agg(ir.relname::text ORDER BY ir.relname)
+          FROM pg_index i JOIN pg_class ir ON ir.oid = i.indexrelid
+         WHERE i.indrelid = c.oid)                  AS indexes,
+       s.last_vacuum                                AS "lastVacuum",
+       s.last_autovacuum                            AS "lastAutovacuum",
+       s.last_analyze                               AS "lastAnalyze",
+       s.last_autoanalyze                           AS "lastAutoanalyze",
+       s.n_mod_since_analyze                        AS "modSinceAnalyze",
+       s.n_live_tup                                 AS "liveTup"
+FROM pg_class c
+LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
+WHERE c.relkind IN ('r', 'p') AND c.relname = ANY($1);
+`;
+var toNum = (v) => v == null ? null : Number(v);
+async function relationStats(connection, relations) {
+  const names = [...new Set(relations.filter(Boolean))];
+  if (names.length === 0) return [];
+  const rows = await queryReadOnly(connection, SQL2, [names]);
+  return rows.map((r) => ({
+    relation: r.relation,
+    estRows: toNum(r.estRows),
+    totalBytes: toNum(r.totalBytes),
+    tableBytes: toNum(r.tableBytes),
+    indexes: r.indexes ?? [],
+    lastVacuum: r.lastVacuum,
+    lastAutovacuum: r.lastAutovacuum,
+    lastAnalyze: r.lastAnalyze,
+    lastAutoanalyze: r.lastAutoanalyze,
+    modSinceAnalyze: toNum(r.modSinceAnalyze),
+    liveTup: toNum(r.liveTup)
+  }));
+}
+
+// src/diagnostics/stale-stats.ts
+var RULE_ID = "PGX_STALE_STATISTICS";
+var DOCS4 = "https://www.postgresql.org/docs/current/routine-vacuuming.html#VACUUM-FOR-STATISTICS";
+var MIN_ROWS = 1e3;
+function staleStatsFindings(stats, config) {
+  if (config.rules[RULE_ID]?.enabled === false) return [];
+  const severity = config.rules[RULE_ID]?.severity ?? "warn";
+  const ratioLimit = config.thresholds.staleStatsModRatio;
+  const out = [];
+  for (const s of stats) {
+    const rows = s.liveTup ?? s.estRows ?? 0;
+    if (rows < MIN_ROWS) continue;
+    const neverAnalyzed = !s.lastAnalyze && !s.lastAutoanalyze;
+    const modRatio = s.modSinceAnalyze != null && rows > 0 ? s.modSinceAnalyze / rows : 0;
+    if (!neverAnalyzed && modRatio < ratioLimit) continue;
+    out.push(
+      finding(RULE_ID, severity, {
+        title: neverAnalyzed ? `Table ${s.relation} has never been analyzed` : `Planner statistics on ${s.relation} are stale`,
+        detail: neverAnalyzed ? `${s.relation} (~${Math.round(rows).toLocaleString()} rows) has no planner statistics \u2014 pg_stat_user_tables shows no manual or auto ANALYZE.` : `${s.modSinceAnalyze?.toLocaleString()} rows of ${s.relation} changed since its last ANALYZE (${(modRatio * 100).toFixed(0)}% of ~${Math.round(rows).toLocaleString()} live rows).`,
+        cause: "The planner chooses plans from per-table statistics. When they are missing or stale, row estimates drift, which cascades into bad join orders, wrong scan types, and misestimates like PGX_ROW_MISESTIMATE.",
+        remediation: {
+          summary: `Run ANALYZE on ${s.relation}, and if it keeps going stale, lower its autovacuum analyze threshold.`,
+          steps: [
+            "ANALYZE the table now to refresh statistics.",
+            "If the table churns heavily, tune per-table autovacuum settings so auto-analyze keeps up."
+          ],
+          commands: [
+            { label: "Refresh statistics", sql: `ANALYZE ${s.relation};` },
+            {
+              label: "Analyze more eagerly on churny tables",
+              sql: `ALTER TABLE ${s.relation} SET (autovacuum_analyze_scale_factor = 0.02);`
+            }
+          ]
+        },
+        docsUrl: DOCS4,
+        meta: {
+          relation: s.relation,
+          modSinceAnalyze: s.modSinceAnalyze ?? 0,
+          liveTup: s.liveTup ?? 0
+        }
+      })
+    );
+  }
+  return out;
+}
+async function checkStaleStats(connection, result, config) {
+  try {
+    const relations = [
+      ...new Set(
+        flatten(result.tree.root).map((n) => n.relationName).filter((r) => !!r)
+      )
+    ];
+    if (!relations.length) return;
+    appendFindings(result, staleStatsFindings(await relationStats(connection, relations), config));
+  } catch {
+  }
+}
+function appendFindings(result, extra) {
+  if (!extra.length) return;
+  result.diagnostics = [...result.diagnostics, ...extra].sort(bySeverity);
+  result.worstSeverity = result.diagnostics.reduce(
+    (worst, d) => worst === null ? d.severity : maxSeverity(worst, d.severity),
+    null
+  );
+}
+
 // src/sql/extract.ts
 var DML = /* @__PURE__ */ new Set(["SELECT", "INSERT", "UPDATE", "DELETE", "MERGE", "VALUES", "TABLE", "WITH"]);
 function classifyStatement(sql) {
@@ -3707,6 +3995,7 @@ async function runRun(args) {
       redact: args.redact,
       sql: single.sql
     });
+    await checkStaleStats(args.connection, analysis2, args.config);
     return emit(analysis2, args);
   }
   const analysis = await analyzeScript(args.connection, sql, {
@@ -4079,6 +4368,66 @@ var diffCmd = defineCommand({
     }
   }
 });
+var locksCmd = defineCommand({
+  meta: {
+    name: "locks",
+    description: "Snapshot live lock contention: who is blocked, and by whom."
+  },
+  args: {
+    dsn: {
+      type: "string",
+      description: "Connection string (or use --host/--port/\u2026 or PG* env vars)"
+    },
+    host: { type: "string", description: "Server host" },
+    port: { type: "string", description: "Server port" },
+    dbname: { type: "string", alias: "d", description: "Database name" },
+    user: { type: "string", alias: "U", description: "Role name" },
+    sslmode: { type: "string", description: "disable | require | verify-ca | verify-full" },
+    sslrootcert: { type: "string", description: "Path to a CA certificate (PEM)" },
+    "connect-timeout": {
+      type: "string",
+      default: "10s",
+      description: "Connection timeout (e.g. 30s)"
+    },
+    format: { type: "string", default: "terminal", alias: "f", description: "terminal | json" },
+    output: { type: "string", alias: "o", description: "Write to a file instead of stdout" },
+    color: { type: "string", default: "auto", description: "auto | always | never" },
+    "no-color": { type: "boolean", description: "Disable color" },
+    "fail-on-blocked": {
+      type: "boolean",
+      description: "Exit 1 if any session is currently blocked"
+    },
+    quiet: { type: "boolean", alias: "q", description: "Suppress non-error logs" },
+    debug: { type: "boolean", description: "Print stack traces on internal errors" }
+  },
+  async run({ args }) {
+    try {
+      applyGlobalFlags(args);
+      if (!["terminal", "json"].includes(args.format)) {
+        throw usageError(`Unknown locks --format '${args.format}'`, "Use terminal or json.");
+      }
+      const connection = {
+        connectTimeoutMs: parseDurationMs(args["connect-timeout"])
+      };
+      if (args.dsn) connection.dsn = args.dsn;
+      if (args.host) connection.host = args.host;
+      if (args.port) connection.port = Number(args.port);
+      if (args.dbname) connection.database = args.dbname;
+      if (args.user) connection.user = args.user;
+      if (args.sslmode) connection.sslmode = args.sslmode;
+      if (args.sslrootcert) connection.sslrootcert = args.sslrootcert;
+      process.exitCode = await runLocks({
+        connection,
+        format: args.format,
+        output: args.output,
+        color: args["no-color"] ? "never" : args.color,
+        failOnBlocked: !!args["fail-on-blocked"]
+      });
+    } catch (err) {
+      process.exitCode = handleFatal(err);
+    }
+  }
+});
 var studioCmd = defineCommand({
   meta: { name: "studio", description: "Launch the local pgexplain Studio web app." },
   args: {
@@ -4152,7 +4501,7 @@ var argv = process.argv.slice(2);
 if (argv[0] === "completion") {
   process.exitCode = runCompletion(argv[1]);
 } else {
-  const started = argv[0] === "run" ? runMain(runCmd, { rawArgs: argv.slice(1) }) : argv[0] === "diff" ? runMain(diffCmd, { rawArgs: argv.slice(1) }) : argv[0] === "studio" ? runMain(studioCmd, { rawArgs: argv.slice(1) }) : runMain(main, { rawArgs: argv });
+  const started = argv[0] === "run" ? runMain(runCmd, { rawArgs: argv.slice(1) }) : argv[0] === "diff" ? runMain(diffCmd, { rawArgs: argv.slice(1) }) : argv[0] === "locks" ? runMain(locksCmd, { rawArgs: argv.slice(1) }) : argv[0] === "studio" ? runMain(studioCmd, { rawArgs: argv.slice(1) }) : runMain(main, { rawArgs: argv });
   started.catch((err) => {
     process.exitCode = handleFatal(err);
   });