jantimon / jantimon/web-performance-debugger
wpd 2.0: planned user value
- Dominant language
- TypeScript
- Stars
- 31
- Forks
- 1
- Avg merge
- 1h 18m
- Merged PRs (30d)
- 2
Description
Tracking issue for 2.0. 2.0 is a batch: every breaking change waits here and ships together, so users re-record baselines once. Non-breaking work keeps shipping as 1.x.
## What 2.0 adds for users
### 1. `--deep` on heavy production pages (the 512MB ceiling goes away)
Today a `--deep` trace of a heavy page can exceed what one JSON string holds (~512MB); wpd refuses, so heavy pages are limited to one iteration. 2.0 moves the deep event log out of the recording into an indexed SQLite sidecar (Node's built-in `node:sqlite`, no new dependency):
- Deep logs of 4-10GB become normal, so multi-iteration `--deep` on real landing pages works.
- Drills (`query get`, `query events`, stored blame) become indexed lookups, not a full-file parse.
- The main recording stays digest-sized on every capture mode; agents keep reading it whole.
- JSON stays compatible where promised, at the `query … --format json|toon` verbs. A streaming NDJSON export covers plain-text interop.
Status: **probed, design final.** Measured on Node 24 / SQLite 3.50.4: RSS stays flat at 84-125MB while writing a 4-10GB index, where the current one-string format throws at ~478k events; drills drop from seconds to sub-millisecond (point lookup 0.13ms vs 2.4s, range 46ms vs 11s). Full probe: [docs/dev/deep-log-storage.md](docs/dev/deep-log-storage.md); background: [docs/dev/trace-buffer.md](docs/dev/trace-buffer.md).
### 2. Small breaking cleanups riding the batch
- Rename the three `*Provenance` exported type names (`GroupSpansProvenance` and siblings). The word is gone from every doc and comment; the type names follow now that a breaking release ships anyway.
- Split usage errors onto exit code 2. Today exit 1 means a blown gate, a mistyped flag, and a missing file alike, so a caller gating on `assert` cannot tell a regression from a bad invocation. 2.0: **0** pass, **1** measured failure (gate fired, n/a FAIL, comparability refusal), **2** wrong invocation (unknown flag, missing argument, unreadable file). Contained in `src/cli.ts`'s error paths plus commander's `exitOverride`.
### 3. Considered and declined
- Renaming `routeLcp`/`routeCls`/`routeInpMs` to the ecosystem's soft-nav names (web-vitals v6, Lighthouse 13.4, PSI). The `route*` names say what is measured, not which API measured it, so they stay; a README note mapping the two names will do. Joins the batch only if the ecosystem names harden against us. Background: [docs/dev/navigation-and-lcp.md](docs/dev/navigation-and-lcp.md).
## What 2.0 is not
No new measurement semantics: the trust tiers, refusal behavior, and comparability gates carry over unchanged. How every number is verified: [docs/verification.md](docs/verification.md).
## Migration (known today)
- Old recordings refuse to open with a re-record message (the schema-epoch rule, [README: Stability and versioning](README.md#stability-and-versioning)); re-record stored baselines once after upgrading.
- CLI commands and flags: no removals planned.
- Raw-JSON consumers of the deep `events[]` array switch to the query verbs or the NDJSON export.
- Consumers importing the `*Provenance` type names update the imports; the shapes are unchanged.
- Scripts branching on exit `== 1` treat exit 2 as a usage error; scripts branching on `!= 0` are unaffected.
Contributor guide
Research direction
Start with docs/dev/deep-log-storage.md and docs/dev/trace-buffer.md to understand the proposed deep-log storage design, then inspect the CLI error paths in src/cli.ts and the commander's exitOverride handling. Review the migration notes and verification guidance before deciding which part to take; done means the selected 2.0 behavior, compatibility expectations, and relevant verification are complete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, sqlite, typescript
- Domain
- cli, databases, performance, release
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100