diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 0000000..39862d1 --- /dev/null +++ b/docs/requirements.md @@ -0,0 +1,326 @@ +# RDBMS Playground — Requirements (Phase 1) + +This document is the **consolidated Phase 1 requirements +checklist** for RDBMS Playground. It captures everything the +project has committed to so far, derived from the design +conversation and the ADRs in `docs/adr/`. + +**Purpose.** Phase 5 verification at every milestone measures +delivered work against this checklist. An item not on this list +was not promised; an item silently dropped without confirmation +is a process failure. + +**Scope.** The list is intentionally coarse — each item is a +unit of "satisfied / not satisfied" judgement. When an item is +taken up for implementation, it is decomposed further in a +backlog (initially in this repo, later in GitHub issues once the +repo is pushed). + +## Status legend + +- `[ ]` — open, not yet implemented +- `[x]` — satisfied (implemented + tested) +- `[~]` — deferred, awaiting an ADR or further design before any + implementation +- `[-]` — explicitly out of scope (rationale at the bottom) + +## Test baseline + +No test suite exists yet — the repo currently contains only +docs. The baseline is therefore "0 passing, 0 failing, 0 +skipped." Subsequent phases establish the suite and measure +against it. + +--- + +## Distribution and install + +- [ ] **D1** Cross-platform binaries: Linux, macOS, Windows on + x86_64 and aarch64. +- [ ] **D2** Single static binary, no runtime dependencies. +- [ ] **D3** Released via prebuilt binaries plus Homebrew, Scoop, + `winget`, and `cargo binstall`. + +## TUI shell + +- [ ] **S1** Three-region layout: items list (left), output + panel (right), input field (bottom). +- [ ] **S2** Items list shows tables and per-table indexes; + designed to extend to additional element kinds (relations, + views, etc.) without restructuring. +- [ ] **S3** Output panel renders a visualization of the + currently selected item and supports multiple tabs. +- [ ] **S4** Hint area below the input field; keyboard-toggleable + for inspecting hints about the current input or last error. +- [ ] **S5** Mode label and distinct border style on the input + field communicate the current input mode at all times. + +## Input field + +- [ ] **I1** Multi-line entry that auto-expands; Ctrl-Enter (or + equivalent) submits, plain Enter inserts a newline. +- [ ] **I2** Persistent navigable input history (project-scoped, + with a global rolling history also available). +- [ ] **I3** Tab completion for app commands, DSL keywords, table + names, column names, and SQL keywords. +- [ ] **I4** Syntax highlighting for both the DSL and SQL. +- [ ] **I5** In-flight query/command cancellation (Ctrl-C in the + output area or input field). + +## Input modes (per ADR-0003) + +- [ ] **M1** Simple mode is the default. It accepts DSL data + commands and the canonical app-level commands; raw SQL is + rejected with a friendly hint. +- [ ] **M2** Advanced mode accepts SQL plus the canonical + app-level commands without any sigil. +- [ ] **M3** Prefixing a single line with `:` in simple mode is a + one-shot advanced escape (with the prompt label updated). The + `mode simple` / `mode advanced` command switches modes + persistently. + +## App-level commands (per ADR-0003) + +- [ ] **A1** All canonical app-level commands implemented and + available in both modes: `save`, `save as`, `load`, `new`, + `export`, `import`, `seed`, `replay`, `undo`, `redo`, `mode`, + `help`, `hint`, `quit`. + +## DSL data commands + +- [ ] **C1** Table operations: create / drop / rename. +- [ ] **C2** Column operations: add / drop / rename / change + type, including the rebuild-table dance behind the scenes + where SQLite ALTER cannot do it directly. +- [ ] **C3** Schema constraints: primary key (single and + compound), foreign key with `ON DELETE` / `ON UPDATE` referential + actions, indexes, `NOT NULL`, `UNIQUE`, `CHECK`, `DEFAULT`. +- [ ] **C4** Convenience: `create m:n relationship from to + ` produces an auto-named junction table the user can rename; + pulls primary keys and FK definitions automatically. +- [ ] **C5** Data operations: insert / update / delete via DSL. + +## SQL handling + +- [ ] **Q1** SQL parsed via `sqlparser-rs`; supported subset is + defined (specifics deferred to a future ADR). +- [ ] **Q2** Non-standard syntax rejected with a clear message + pointing at the supported subset. +- [ ] **Q3** User-facing simplified types map transparently to + SQLite STRICT types in generated DDL. +- [~] **Q4** Supported SQL subset specification — design and ADR + pending. Q1 cannot be marked satisfied without it. + +## Database backend (per ADR-0002) + +- [ ] **B1** SQLite via `rusqlite`; all tables created `STRICT`; + `PRAGMA foreign_keys = ON` per connection. +- [ ] **B2** Schema evolution uses the rebuild-table technique + internally where SQLite `ALTER TABLE` cannot. +- [ ] **B3** Query timeout and cancellation supported (no + cartesian-join-of-doom can hang the app). + +## Type system (per ADR-0005) + +- [ ] **T1** All ten user-facing types implemented: `text`, + `int`, `real`, `decimal`, `bool`, `date`, `datetime`, `blob`, + `serial`, `shortid`. +- [ ] **T2** `shortid` generation: base58, 10–12 characters, + omits ambiguous characters; generated client-side at insert. +- [ ] **T3** Compound primary keys handled end-to-end (DSL, + storage, display, FK reference). + +## Visualizations + +- [ ] **V1** Single-element views render in the output pane: a + selected table as its structure (columns, types, keys, + constraints); a selected relationship as two tables joined by + a line. +- [ ] **V2** SQL query results render as a dynamic table view in + the output pane, with multiple result tabs supported. +- [~] **V3** Full ER-diagram export (whole-database graph, viewed + outside the TUI) — low priority; design and ADR pending. + +## Project lifecycle (per ADR-0004) + +- [ ] **P1** An auto-named temporary project is created on + startup unless a project is specified, and stored in a + platform-standard path + (e.g. `~/.rdbms-playground/projects/temp-`). +- [ ] **P2** `save` elevates a temp project to a named project at + a chosen location. +- [ ] **P3** Project is always saved as changes occur — there is + no manual dirty state. +- [ ] **P4** `load` opens a picker listing temp projects with + timestamps, with the option to browse to an arbitrary location. +- [ ] **P5** `playground.db` is a derived artifact: rebuilt + silently when missing, rebuilt with confirmation and a change + summary when present (per ADR-0004). + +## Project file format (per ADR-0004) + +- [ ] **F1** `project.yaml` with `version` field carries schema, + relationships, and project metadata; `data/.csv` carries + table data (UTF-8, header row, RFC 4180). +- [ ] **F2** A `.gitignore` template (excluding `playground.db`) + is created in each new project. +- [ ] **F3** Project file format includes a registered-migrator + mechanism so older `version` values load cleanly as the format + evolves. (Exercised once `version` increments past 1; the + mechanism itself is built in v1.) + +## Undo and replay (per ADR-0006) + +- [ ] **U1** Auto-snapshot before destructive operations into a + ring buffer (initial size N=10, tunable). +- [ ] **U2** `undo` restores the most recent snapshot; `redo` + re-applies; both prompt for confirmation showing the snapshot + timestamp and a summary of the changes that will be discarded. +- [ ] **U3** `history.log` records every successfully executed + command in append-only form. +- [ ] **U4** `replay` runs commands from a `history.log` or + `.commands` file. + +## Sharing and export (per ADR-0007) + +- [ ] **E1** `export` produces a zip excluding `playground.db`; + default filename `YYYYMMDD--export-NN.zip` with a + non-clobbering two-digit sequence. +- [ ] **E2** User documentation includes sharing recipes for + git, email, and direct file transfer. + +## Sample data / seeding + +- [ ] **SD1** `seed
[count]` generates plausible fake + data; junction tables are seeded with valid foreign-key + references drawn from existing parent rows. +- [~] **SD2** Detailed seeding rules (per-type generators, + locale, determinism, override hooks) — design and ADR pending. + +## Query analysis + +- [ ] **QA1** `EXPLAIN QUERY PLAN` is run on demand for queries; + output is rendered as an annotated tree highlighting full + scans, index use, and join order. +- [~] **QA2** Plan rendering specifics (tree layout, annotation + taxonomy, colour scheme) — design and ADR pending. + +## Hints, help, errors + +- [ ] **H1** Friendly error-rewriting layer translates SQLite + error messages into learner-friendly equivalents. +- [ ] **H2** `hint` provides contextual help for the current + input or the most recent error. +- [ ] **H3** `help` provides general reference and per-command + help. + +## CLI + +- [ ] **L1** Load a project via a positional CLI argument. +- [~] **L2** Submit a command alongside project load — deferred, + not v1. + +## Tutorials and lessons + +- [~] **TU1** Tutorial / lesson system — design and ADR pending + before any implementation. Out of v1 unless an ADR is written. + +## Testing (per ADR-0008) + +- [ ] **TT1** Tier 1: `cargo test` + `proptest` covering + pure-logic modules (parser, dispatcher, type mapping, project + I/O, snapshot ring buffer, replay log). +- [ ] **TT2** Tier 2: Ratatui `TestBackend` + `insta` snapshots + for representative views. +- [ ] **TT3** Tier 3: synthetic event-loop integration tests + covering the user-facing flows in this checklist. +- [ ] **TT4** Tier 4: PTY-based end-to-end for the four critical + flows named in ADR-0008 (cold launch → DDL → quit; save → + reopen; export → import → rebuild; undo after DROP). +- [ ] **TT5** CI runs all tiers on Linux, macOS, and Windows on + stable Rust. + +## Cross-cutting + +- [ ] **X1** Comprehensive logging via the project's logging + infrastructure per `CLAUDE.md` (decision points, parameter + values, fallback paths). +- [~] **X2** Language: English-only for v1; multi-language is an + open question to revisit later. +- [~] **X3** Accessibility: TUI screen-reader support is + best-effort and not a v1 commitment; revisit if user need + emerges. + +--- + +## Non-functional requirements + +NFRs are quality bars rather than discrete features. Where a +target is measurable, it is stated numerically; where it is +necessarily qualitative, the criterion is named and the bar is +"reviewer judgement against the criterion." + +- [ ] **NFR-1 Performance — startup.** Cold launch to first + rendered frame under 500ms on commodity hardware (developer + laptop, mid-range desktop). Measured in CI on the Linux runner + as a regression gate. +- [ ] **NFR-2 Performance — input latency.** Keystroke-to-render + latency under 16ms during normal editing; long-running queries + must execute off the UI thread so the interface remains + responsive (typing, scrolling, mode switching) while a query is + running. +- [ ] **NFR-3 Performance — resource footprint.** Idle memory + under 50MB on the smallest target platform; no busy-loops; CPU + near zero when waiting for input. +- [ ] **NFR-4 Visual quality — distinctive design.** Colour + palette and typography are deliberate and consistent across + views; layout uses Unicode box-drawing and symbols where they + add clarity; rendering avoids the generic flat-default look + that ships with most TUI frameworks. Criterion: a reviewer can + identify the app from a screenshot of any view. +- [ ] **NFR-5 Visual quality — colour use.** Colour conveys + information rather than decoration: mode indication, query + result types (numeric vs text vs null), error severity, + syntax highlighting categories. Foreground/background + combinations meet WCAG-AA contrast (4.5:1 for normal text) + even though we have not committed to broader accessibility. +- [ ] **NFR-6 Cross-platform parity.** Behaviour and visual + quality are equivalent across Linux, macOS, and Windows on + crossterm-supported terminals. Platform-specific divergence + (e.g. font fallbacks) is documented, not silently tolerated. +- [ ] **NFR-7 Light and dark background support.** The colour + scheme remains legible and visually coherent on both light and + dark terminal backgrounds. The mechanism (auto-detect via + terminal query, explicit user setting, or both) is an + implementation choice, but the outcome is non-negotiable: no + dark-on-dark or light-on-light readability failures on either + background. + +--- + +## Explicitly out of scope + +- [-] **N1** Hosted publishing platform — per ADR-0007. Sharing + is local-artifact based. +- [-] **N2** Real UUID column type — per ADR-0005. The `shortid` + type covers the pedagogical need at TUI-friendly width. +- [-] **N3** Cross-emulator visual regression coverage — per + ADR-0008. Crossterm abstracts terminals adequately; we revisit + only if a real regression surfaces. + +--- + +## Maintenance + +This document is updated whenever: + +- A new requirement is committed to (added as a new item with the + next free ID in its section). +- A deferred item is taken up (status moves from `[~]` to `[ ]`). +- An item is satisfied (status moves to `[x]`, with a reference + to the commit, PR, or test that demonstrates it). +- An item moves out of scope (status moves to `[-]` with a + rationale and a link to the decision). + +IDs are stable: once assigned, they are not reused. Removing a +requirement leaves a "withdrawn" entry referencing the decision.