pgexplain 0.1.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
@@ -67,6 +92,81 @@ Point at a directory to analyze every plan in it (batch mode):
 pg-explain ./plans/
 ```
 
+Or launch the local **Studio** — a GUI for everything the CLI does:
+
+```sh
+pg-explain studio        # opens http://127.0.0.1:5177 in your browser
+```
+
+---
+
+## Studio (local web UI)
+
+`pg-explain studio` starts a local, single-user web app (binds `127.0.0.1`, no auth) that
+mirrors the CLI with a friendlier surface. It ships inside the package, so `npx pgexplain studio`
+just works — the PostgreSQL driver and the UI are only loaded on demand.
+
+- **Analyze** a pasted `EXPLAIN (FORMAT JSON)` plan, or **Run** a query (connect → EXPLAIN-only,
+  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 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
@@ -149,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.
@@ -180,12 +282,20 @@ Choose with `-f`/`--format` (default `terminal`); write to a file with `-o`/`--o
 | `terminal` | Color, severity heat, and proportional self-time bars for interactive use. |
 | `markdown` | The headline shareable deliverable — paste into a PR or ticket. |
 | `json` | Stable, machine-readable (`schemaVersion = 1`). |
-| `html` | Single self-contained file (no external assets). |
+| `html` | Single self-contained file (no external assets). Auto-opens in your browser when run interactively. |
 | `text` | Plain text, no escapes — good for logs. |
 
 `diff` supports `terminal`, `markdown`, and `json`.
 
-Shared output flags: `--tldr` (summary + findings, no plan tree), `--redact` (strip literal values so the report is safe to share), `--ascii` (ASCII tree glyphs), `--color auto|always|never` / `--no-color`, `--compact` (compact JSON), `--config <path>`, `-q/--quiet`, `--verbose`, `--debug`.
+When you run `-f html` in an interactive terminal, the report opens in your default browser automatically: with `-o report.html` that file is opened, otherwise a temp file is written and opened. Auto-open is off when output is piped/redirected or `CI` is set; use `--open` to force it (e.g. into a file in CI) and `--no-open` to disable it.
+
+```bash
+pg-explain plan.json -f html -o report.html   # writes the file and opens it
+pg-explain plan.json -f html                   # writes a temp file and opens it
+pg-explain plan.json -f html > report.html     # redirected → no open, HTML to stdout
+```
+
+Shared output flags: `--tldr` (summary + findings, no plan tree), `--redact` (strip literal values so the report is safe to share), `--open` / `--no-open` (HTML browser opening), `--ascii` (ASCII tree glyphs), `--color auto|always|never` / `--no-color`, `--compact` (compact JSON), `--config <path>`, `-q/--quiet`, `--verbose`, `--debug`.
 
 ---
 
@@ -203,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… |
 | --- | --- |
@@ -211,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. |
@@ -226,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.
 
 ---
@@ -309,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