oli/rdbms-playground
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: reconcile requirements tracking with verified code state

Browse Source 
Audit of all 35 [ ] items vs source found ~46% mis-marked. Add a
[/] partial marker; promote 7 shipped-but-open items to [x]
(S1/S4/S5/I1a/I3/I4/C1) and 9 substantially-built ones to [/]
with gap notes (S3/A1/V1/V2/V5/T3/H3/DOC1/X1). Fix CLAUDE.md's
false "Tier 4 is wired" claim — no PTY tests exist.
This commit is contained in:
claude@clouddev1
2026-06-07 12:31:16 +00:00
parent ca158e8b25
commit 28e75961aa
2 changed files with 155 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/requirements.md
+150 -56
View File
@@ -18,12 +18,28 @@ repo is pushed).
## Status legend
- `[ ]` — open, not yet implemented
- `[ ]` — open, not yet started
- `[/]` — partial / in progress: some of it is built and tested,
but named gaps remain. The entry states what works and what is
still missing. (Distinct from `[ ]`, which is genuinely
untouched, and from `[~]`, which is *deliberately* deferred
pending an ADR rather than half-built.)
- `[x]` — satisfied (implemented + tested)
- `[~]` — deferred, awaiting an ADR or further design before any
implementation
- `[-]` — explicitly out of scope (rationale at the bottom)
> **Reconciliation note (2026-06-07).** A full audit of every
> `[ ]` item against the source found ~46 % of them mis-marked —
> overwhelmingly *under*-claimed (e.g. tab completion `I3` and
> syntax highlighting `I4` were shipped but marked "not yet
> implemented"). The binary legend was the root cause: a
> shipped feature, a half-built one, and an untouched one all
> wore the same `[ ]`. The `[/]` marker above was added to fix
> this, and the audited items were re-marked. When you implement
> against an item, move it `[ ]` → `[/]` → `[x]` rather than
> jumping straight to `[x]`, and keep the gap note current.
## Test baseline
After ADR-0022 Amendment 6 (the curated SQL function-name list —
@@ -54,20 +70,34 @@ since ADR-0027.)
## TUI shell
- [ ] **S1** Three-region layout: items list (left), output
- [x] **S1** Three-region layout: items list (left), output
panel (right), input field (bottom).
*(Verified 2026-06-07: `ui.rs:26-58` lays out a horizontal
split — items panel left, right column subdivided into output
panel / input field / hint panel; rendered every frame.)*
- [x] **S2** Items list shows tables and per-table indexes;
designed to extend to additional element kinds (relations,
views, etc.) without restructuring.
*(ADR-0025: the items panel renders a nested list — each
table with its index names indented beneath it. The nested
model is the extension point for future element kinds.)*
- [ ] **S3** Output panel renders a visualization of the
- [/] **S3** Output panel renders a visualization of the
currently selected item and supports multiple tabs.
- [ ] **S4** Hint area below the input field; keyboard-toggleable
*(Partial, verified 2026-06-07: single-element structure
visualisation renders (`output_render.rs:82-180`); **multiple
tabs are not implemented** — the output is one line buffer, no
tab abstraction. Same multi-tab gap as V2.)*
- [x] **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
*(Verified 2026-06-07: `ui.rs:1088-1110` `render_hint_panel` /
`resolve_hint_lines` — a dynamic 1–`MAX_HINT_ROWS` panel below
the input showing ambient hints, candidates, or the last error.)*
- [x] **S5** Mode label and distinct border style on the input
field communicate the current input mode at all times.
*(Verified 2026-06-07: `ui.rs:896-934` `render_input_panel` —
a coloured, bold mode label plus a mode-distinct border colour
(`border` vs `border_advanced`), tracking the three-way
`EffectiveMode` incl. the one-shot `:` state.)*
- [x] **S6** Input-field validity indicator: a debounced
`[ERR]` / `[WRN]` marker at the right edge of the input row,
summarising — before submit — whether the current command
@@ -89,12 +119,17 @@ since ADR-0027.)
- [ ] **I1** Multi-line entry that auto-expands; Ctrl-Enter (or
equivalent) submits, plain Enter inserts a newline.
- [ ] **I1a** In-line cursor editing in the input field: Left /
- [x] **I1a** In-line cursor editing in the input field: Left /
Right arrows move the cursor by character (UTF-8 boundaries
honoured), Home / End jump to the extremes, Delete removes the
character at the cursor, Backspace removes the character
before. Insertion happens at the cursor position. *(Implemented;
multi-line editing per I1 still pending.)*
before. Insertion happens at the cursor position.
*(Verified 2026-06-07: `app.rs:973-1005` `cursor_left` /
`cursor_right` (with `is_char_boundary` checks), Home/End,
Delete, Backspace, `insert_at_cursor`. This is single-line
cursor editing and is complete on its own terms; the separate
**multi-line** entry goal is tracked under I1, which is
genuinely not started.)*
- [ ] **I1b** Readline-style cursor shortcuts: Ctrl-A / Ctrl-E
as aliases for Home / End for users on keyboards without those
keys (and for ergonomics in command-driven workflows). Likely
@@ -106,15 +141,33 @@ since ADR-0027.)
navigable history is hydrated from the tail of
`history.log` up to the same in-memory cap (Iter 6). Global
rolling history is out of scope per OOS-6 / N4.)*
- [ ] **I3** Tab completion for app commands, DSL keywords, table
- [x] **I3** Tab completion for app commands, DSL keywords, table
names, column names, and SQL keywords.
*(Refinement 2026-05-30, issue #15: SQL expression slots
(`sql_expr_ident`) now also offer a curated set of SQL function
*(Verified 2026-06-07 — this was mis-marked `[ ]` despite being
shipped: `src/completion.rs` is 2852 lines with ~100 tests;
`app.rs:898` binds Tab → `completion_tab_forward` (and
BackTab → `_backward`) with forward/backward cycling through a
candidate memo and a colour-coded candidate line in the hint
panel (`ui.rs:1125` `render_candidate_line`). All five
candidate categories work — app commands (via REGISTRY), DSL
keywords (walker `Expectation`), table names + column names
(`SchemaCache`), and SQL keywords/functions in advanced mode.
Refinement 2026-05-30, issue #15: SQL expression slots
(`sql_expr_ident`) also offer a curated set of SQL function
names — `KNOWN_SQL_FUNCTIONS` in `src/dsl/sql_functions.rs`,
surfaced as a new `CandidateKind::Function` — ADR-0022 Amendment 6.
The broad tab-completion goal stays open.)*
- [ ] **I4** Syntax highlighting for both the DSL and SQL.
*(Refinement 2026-05-29, issue #8: column data types now carry a
surfaced as `CandidateKind::Function` (ADR-0022 Amendment 6).
The original "broad tab-completion" goal is met; any further
polish is incremental, not a missing core.)*
- [x] **I4** Syntax highlighting for both the DSL and SQL.
*(Verified 2026-06-07 — mis-marked `[ ]` despite being shipped:
`input_render.rs:64-113` lexes the input to styled byte-range
runs (`lex_to_runs_in_mode`) and renders them per-mode (DSL in
simple, SQL in advanced), with nine token classes in `theme.rs`
(`tok_keyword`, `tok_identifier`, `tok_string`, `tok_punct`,
`tok_flag`, `tok_error`, `tok_function`, `tok_type`) and
diagnostics overlaid (error/warning spans). Both surfaces are
highlighted; the core goal is met.
Refinement 2026-05-29, issue #8: column data types now carry a
dedicated `HighlightClass::Type` / `tok_type` colour, distinct from
identifiers and clause keywords — ADR-0022 Amendment 4; a further
refinement 2026-05-30, issue #15: SQL function-name candidates carry
@@ -172,24 +225,27 @@ since ADR-0027.)
## App-level commands (per ADR-0003)
- [ ] **A1** All canonical app-level commands implemented and
- [/] **A1** All canonical app-level commands implemented and
available in both modes: `save`, `save as`, `load`, `new`,
`rebuild`, `export`, `import`, `seed`, `replay`, `undo`,
`redo`, `mode`, `help`, `hint`, `quit`.
*(Progress: `quit`/`q`, `mode simple|advanced`, `help`,
`save`, `save as`, `load`, `new`, `rebuild`, `export`,
`import`, `replay` all implemented (Iterations 4 + 5;
`replay` via ADR-0024 Phase E — see U4). `seed` in the
seeding iteration; `undo` / `redo` in the U-series; `hint`
with H2.)*
*(Partial, verified 2026-06-07: 13 of 15 implemented and
available in both modes — `quit`/`q`, `mode simple|advanced`,
`help`, `save`, `save as`, `load`, `new`, `rebuild`, `export`,
`import`, `replay`, `undo`, `redo` (REGISTRY in
`grammar/app.rs:249-333`). **Missing: `seed`** (tracked as SD1)
**and `hint`** (tracked as H2) — neither is registered. A1
closes when SD1 + H2 land.)*
## DSL data commands
- [ ] **C1** Table operations: create / drop / rename.
*(Progress: create + drop done; **rename done on the advanced
surface** — `ALTER TABLE … RENAME TO`, ADR-0035 §6 / 4h. A simple-mode
rename-table verb is deliberately not provided — table rename is
advanced-mode only.)*
- [x] **C1** Table operations: create / drop / rename.
*(Verified 2026-06-07: create + drop done; **rename done on the
advanced surface** — `ALTER TABLE … RENAME TO`, ADR-0035 §6 / 4h
(`do_rename_table`, `db.rs:4821`). A simple-mode rename-table
verb is **deliberately** not provided — table rename is
advanced-mode only — so the requirement is satisfied as
designed, not partial.)*
- [x] **C2** Column operations: add / drop / rename / change
type. `drop column` and `rename column` use SQLite native
ALTER TABLE (3.35+ / 3.25+); `change column` routes through
@@ -343,29 +399,42 @@ since ADR-0027.)
*(Implemented per ADR-0014; auto-fills omitted shortid
columns and validates user-supplied values against the same
alphabet and length range.)*
- [ ] **T3** Compound primary keys handled end-to-end (DSL,
- [/] **T3** Compound primary keys handled end-to-end (DSL,
storage, display, FK reference).
*(Progress: DSL grammar (`with pk a(int),b(int)`), storage, and
table-info description are all present; the FK iteration
references single-column PKs only — compound-key FK references
remain pending.)*
*(Partial, verified 2026-06-07: compound-PK **declaration**
(`with pk a(int),b(int)`), **storage** (`primary_key:
Vec<String>`), and **display** are present and tested.
**Missing: a FK that *references* a compound PK** —
`db.rs:6822-6836` enforces a single `parent_column: String`;
a bare `REFERENCES parent` on a compound-PK table is refused as
ambiguous, and multi-column FK target syntax is not in the
grammar. This is the one open end-to-end leg of T3.)*
## Visualizations
- [ ] **V1** Single-element views render in the output pane: a
- [/] **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.
*(Progress: a basic structure view (column rows with SQLite
type names) is rendered after each successful DDL; pretty
rendering, selection nav, and relationship line-art pending —
see V4 for the broader direction.)*
- [ ] **V2** SQL query results render as a dynamic table view in
*(Partial, verified 2026-06-07: the **table-structure** half is
done — `output_render.rs:82-180` renders columns / types /
constraints / indexes in a box-drawing table, with relationship
metadata as `References:` / `Referenced by:` prose
(`A.col → B.col`). The **relationship-as-line-art** half — two
tables drawn side by side with a connecting line — is **not
implemented** (deferred per `output_render.rs` §5 OOS-1, ADR
pending). This is the relationship-visualisation piece that has
been repeatedly pushed away; it is the substantive open part of
V1. Selection-nav and the broader journal direction live in V4.)*
- [/] **V2** SQL query results render as a dynamic table view in
the output pane, with multiple result tabs supported.
*(Progress: a basic aligned-column data view is rendered for
`show data` and after every write (ADR-0014). Pretty
box-drawing tables with truncation/scroll handling, plus
multi-tab support, remain in V4 territory.)*
*(Partial, verified 2026-06-07: the **table view** is done —
`output_render.rs:38-72` `render_data_table` renders a
box-drawing frame with aligned columns (numeric right, text
left) and NULL/control-char sanitisation, for `show data` and
after every write (ADR-0014). **Missing: multiple result tabs**
— the output is a single `VecDeque<OutputLine>` with no tab
abstraction (same gap as S3). Multi-tab sits in V4 territory.)*
- [~] **V3** Full ER-diagram export (whole-database graph, viewed
outside the TUI) — low priority; design and ADR pending.
- [~] **V4** Output panel as a *scrollable per-session log* with
@@ -381,10 +450,13 @@ since ADR-0027.)
buffer is in, with new output snapping the view to the most
recent. The full V4 scope — smart structure rendering, log
styling, Markdown export, scroll indicator — remains pending.)*
- [ ] **V5** `show <kind> [<name>]` family of commands for
redisplaying schema info on demand. *(Progress: `show table
<name>` and `show data <Table>` implemented;
`show tables`, `show relationships`, etc. pending.)*
- [/] **V5** `show <kind> [<name>]` family of commands for
redisplaying schema info on demand.
*(Partial, verified 2026-06-07: `show table <name>` and
`show data <Table>` implemented (`grammar/data.rs`). **Missing
the "all items" variants** — `show tables`, `show
relationships`, `show indexes` — none are registered. V5 closes
when the plural/list forms land.)*
- [x] **V6** Copy the output panel to the system clipboard
(issue #11, ADR-0041). `copy` / `copy all` copy the whole
panel; `copy last` copies the most recent command's output.
@@ -608,15 +680,17 @@ since ADR-0027.)
there, so the payoff is small.
- [ ] **H2** `hint` provides contextual help for the current
input or the most recent error.
- [ ] **H3** `help` provides general reference and per-command
- [/] **H3** `help` provides general reference and per-command
help.
*(Progress: the `help` command lists currently-supported
commands + DSL grammar reference + types. As of ADR-0024
§help_id it is assembled by iterating the command REGISTRY
and translating each `CommandNode.help_id`, so a new command
appears automatically. A general reference and `help
<command>`-style detailed per-command help are still the
missing pieces.)*
*(Partial, verified 2026-06-07: the `help` command
(`app.rs:2370` `note_help`) lists all currently-supported
commands by iterating the REGISTRY + translating each
`CommandNode.help_id`, plus an intro and a types reference, so a
new command appears automatically. **Missing:** `help <command>`
per-command detail — the HELP node's shape is `EMPTY_SEQ`, so it
takes no argument — and a fuller "general reference". These two
are the remaining pieces; the `help_id` hook is already there
to build per-command detail on.)*
## CLI
@@ -651,7 +725,7 @@ since ADR-0027.)
## Documentation
- [ ] **DOC1** User- and student-facing reference
- [/] **DOC1** User- and student-facing reference
documentation under `docs/`: the DSL command surface,
the type system, and the boundaries of simple mode.
`docs/simple-mode-limitations.md` is the first piece —
@@ -659,6 +733,11 @@ since ADR-0027.)
reference. Distinct from in-app `help` (`H3`), the
interactive tutorial system (`TU1`), and the sharing
recipes under `E2`.
*(Partial, verified 2026-06-07: `docs/simple-mode-limitations.md`
exists (~55 lines, covers the WHERE-expression and
table-creation boundaries). **Missing:** a DSL
command-surface reference and a standalone type-system
reference under `docs/`.)*
## Testing (per ADR-0008)
@@ -672,14 +751,29 @@ since ADR-0027.)
- [~] **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).
*(Verified 2026-06-07: **nothing is wired** — no
`portable-pty` / `expectrl` / `vt100` dependencies, no PTY test
files; ADR-0008 §Tier-4 is a specification only. The Tier-3
`tests/it/*_e2e.rs` files are synthetic event-loop tests, not
PTY. Correcting a stale `CLAUDE.md` line that read "Tier 4 is
wired only for the listed critical flows" — it was not wired at
all. Genuinely deferred.)*
- [ ] **TT5** CI runs all tiers on Linux, macOS, and Windows on
stable Rust.
## Cross-cutting
- [ ] **X1** Comprehensive logging via the project's logging
- [/] **X1** Comprehensive logging via the project's logging
infrastructure per `CLAUDE.md` (decision points, parameter
values, fallback paths).
*(Partial, verified 2026-06-07: the logging **harness** is
wired — `src/logging.rs` sets up file-backed `tracing` with an
env filter — but instrumentation is **sparse**: ~25 `tracing::`
call sites across the tree, concentrated in `runtime.rs` and
`undo.rs` and mostly error/warning on failure paths. The
decision-point / parameter-value / fallback-path coverage the
`CLAUDE.md` "log liberally" standard calls for — especially in
`db.rs`, the parser, and the executors — is largely absent.)*
- [~] **X2** Language: English-only for v1; multi-language is an
open question to revisit later.
- [~] **X3** Accessibility: TUI screen-reader support is