From 28e75961aa07224547fe36a1108c8aeb0fbb7e72 Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Sun, 7 Jun 2026 12:31:16 +0000 Subject: [PATCH] docs: reconcile requirements tracking with verified code state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- CLAUDE.md | 7 +- docs/requirements.md | 206 +++++++++++++++++++++++++++++++------------ 2 files changed, 155 insertions(+), 58 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 33aa4f1..c32a9c0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -73,8 +73,11 @@ Current decisions at a glance (each backed by an ADR): - **Sharing:** `export` command produces a zip without the `.db`; no hosted publishing (ADR-0007). - **Testing:** four-tier strategy from `cargo test` units up to - PTY-based end-to-end (ADR-0008). Tiers 1–3 are active; Tier 4 - is wired only for the listed critical flows. + PTY-based end-to-end (ADR-0008). Tiers 1–3 are active; **Tier 4 + is not yet wired** — ADR-0008 specifies the PTY harness and the + four critical flows, but no PTY deps or tests exist yet + (verified 2026-06-07; corrects an earlier "wired only for the + listed critical flows" claim). Tracked as `requirements.md` TT4. - **DSL syntax conventions:** required clauses use keyword grammar (`with pk`, `to table` optional, `from..to`, `set`, `where`); `--` flags are reserved for opt-in choices; one diff --git a/docs/requirements.md b/docs/requirements.md index fd5eab4..707593e 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -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`), 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` 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 []` family of commands for - redisplaying schema info on demand. *(Progress: `show table - ` and `show data ` implemented; - `show tables`, `show relationships`, etc. pending.)* +- [/] **V5** `show []` family of commands for + redisplaying schema info on demand. + *(Partial, verified 2026-06-07: `show table ` and + `show data
` 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 - `-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 ` + 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