diff --git a/docs/adr/0024-unified-grammar-tree-execution-plan.md b/docs/adr/0024-unified-grammar-tree-execution-plan.md index af71c70..7c2b29b 100644 --- a/docs/adr/0024-unified-grammar-tree-execution-plan.md +++ b/docs/adr/0024-unified-grammar-tree-execution-plan.md @@ -579,6 +579,22 @@ test suite still all-green; `cargo clippy --all-targets -- -D warnings` passes; `cargo build --release` binary not noticeably larger. +**Implementation note (2026-05-15) — "Phase F minimal".** +Phase F shipped as planned with one deliberate deviation: +`dsl/parser.rs` was *retained*, not deleted. The chumsky + +lexer pipeline is gone (chumsky dependency removed; `lexer.rs`, +`keyword.rs`, `ident_slot.rs`, `usage.rs` all deleted; the +`parse.token.*` catalog entries collapsed), but `parser.rs` +remains as the thin router: it owns the public `parse_command` +/ `parse_command_with_schema` entry points and the `ParseError` +type, whose `{message, position, at_eof, expected}` shape +completion, hint rendering, and the input-renderer overlay all +depend on. Deleting the file would only scatter that surface +across `walker` / `dsl/mod.rs` for no functional gain. The +differential scaffolding was never built as a live harness — +it materialised as hand-curated expectation tests. `parser.rs` +documents this in its own module doc comment. + ### Test discipline Three guarantees throughout migration: diff --git a/docs/adr/README.md b/docs/adr/README.md index b3dfada..10ab623 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -29,4 +29,4 @@ This directory contains the project's ADRs, recorded per - [ADR-0021 — Parser-as-source-of-truth for H1a (per-command usage in parse errors)](0021-parser-as-source-of-truth-for-h1a.md) - [ADR-0022 — Ambient typing assistance: colour, hint panel, completion (I3 + I4)](0022-ambient-typing-assistance.md) - [ADR-0023 — Unified declarative grammar tree](0023-unified-grammar-tree.md) — direction (superseded for execution detail by ADR-0024) -- [ADR-0024 — Unified grammar tree: execution plan](0024-unified-grammar-tree-execution-plan.md) — **Accepted**, the executable spec +- [ADR-0024 — Unified grammar tree: execution plan](0024-unified-grammar-tree-execution-plan.md) — **Accepted**, the executable spec — implemented (Phases A–F; Phase F shipped "minimal", `parser.rs` retained as the router — see the ADR's Phase F implementation note) diff --git a/docs/handoff/20260515-handoff-14.md b/docs/handoff/20260515-handoff-14.md index 8f4247c..0419a93 100644 --- a/docs/handoff/20260515-handoff-14.md +++ b/docs/handoff/20260515-handoff-14.md @@ -6,8 +6,10 @@ deferred items. Eight focused commits, each a deliberate decision the user signed off on. **Headline: the handoff-12 §2 catalogue is now empty of -actionable items.** What remains are two flagged observations -(§3) the user should rule on, plus the standing ADR roadmap. +actionable items, and ADR-0024 is confirmed fully +implemented.** The two items §3 originally flagged are both +resolved. The next session's work is the product roadmap in +`docs/requirements.md` (reconciled this session) — see §4. ## State at handoff @@ -138,45 +140,71 @@ long internal space runs in double-quoted (`"…"`) values — use a block scalar or keep runs short.** A catalog comment in `en-US.yaml` records this. -## §3. CRITICAL: two flagged items needing a user decision +## §3. Flagged items — both now resolved -**3.1 The `Ranker` type is vestigial.** `completion::Ranker` / +Both items this section originally flagged were ruled on by +the user after the main work: + +**3.1 The `Ranker` type — KEEP.** `completion::Ranker` / `candidates_at_cursor_with` have no production caller passing a -non-identity ranker. The user's stated ranker need (candidate -ordering) is met by declaration-order preservation, not the -ranker layer. So `Ranker`, `identity_ranker`, and the -`candidates_at_cursor_with` variant are unused scaffolding. Per -CLAUDE.md "don't remove without confirmation" they were left -in. **Decide: remove them, or keep for a future frequency- -ranking feature?** (handoff-12 §2.1 listed the ranker as -"scaffolding-only … future work" — this is the same item, now -confirmed genuinely unused.) +non-identity ranker (the candidate-ordering need is met by +declaration-order preservation). The user ruled: **keep it** — +it is intentional scaffolding for future frequency / content- +aware ranking (ADR-0024 §"out of scope" explicitly anticipates +this). No longer an open question. -**3.2 `CommandNode.hint_mode` is now genuinely dead.** The -per-command `hint_mode: Option` field predates the -node-attached HintMode work; HintMode is now per-*node* -(`Node::Hinted`), never per-command. The field is still -`#[allow(dead_code)]` and read by nothing. Removing it is a -safe mechanical edit across the 20 `CommandNode` declarations. -**Decide: remove it, or keep?** Not done this session (20-site -edit, separate from the HintMode mechanism change). +**3.2 `CommandNode.hint_mode` — REMOVED.** The per-command +`hint_mode` field predated the node-attached HintMode work and +was read by nothing. Removed (field + 20 `None` initialisers) +in commit `6d2b929`. -## §4. Open items — standing roadmap (unchanged) +## §4. What's next — the standing roadmap -handoff-12 §2's actionable backlog is cleared. What remains is -the ADR roadmap in `CLAUDE.md` "Things deliberately deferred" -(complex WHERE expressions, SQL advanced mode, indexes, m:n -convenience, snapshot/replay/undo, tutorial system, etc.) and -handoff-13's two accepted items: +**handoff-12 §2's backlog is cleared, and ADR-0024 is +confirmed fully implemented** (audited this session — Phases +A–F done; Phase F shipped "minimal" with `parser.rs` retained +as the router, now recorded in an ADR-0024 implementation +note). There is no migration or carry-forward debt left. + +**The next session's work is the product roadmap, tracked in +`docs/requirements.md`** — reconciled this session against +what handoffs 10–14 actually built (test baseline refreshed to +1006; `U4` replay marked satisfied; `A1` / `H1a` / `H3` +progress notes corrected). `requirements.md` is now the +trustworthy "what's open" tracker — read it, not the +(coarser) `CLAUDE.md` "Things deliberately deferred" list. + +Notable open clusters in `requirements.md` (prioritisation is +a **user product decision** — do not pick unilaterally): + +- **Indexes** (`C3` partial) — `add index` / `drop index`, + then `EXPLAIN QUERY PLAN` rendering (`QA1`). Self-contained. +- **Complex WHERE expressions** (`C5a`, `[~]`) — AND/OR / + comparison / LIKE in UPDATE/DELETE/show-data filters. Needs + an ADR. The bridge from DSL toward real SQL. +- **SQL in advanced mode** (`Q1`/`Q4`, `[~]`) — `sqlparser-rs` + + a defined subset. Needs an ADR. +- **Snapshot / undo** (`U1`/`U2`) — designed in ADR-0006, not + built. (`replay`, `U4`, is now done.) +- **m:n convenience** (`C4`), **modify relationship** (`C3a`, + `[~]`), **table rename** (`C1`). +- **Friendly error layer** (`H1`) — partial; full SQL→English + translation pending. **Syntax-help in parse errors** + (`H1a`) — piecemeal so far. +- **Session log + Markdown export** (`V4`, `[~]`), + **multi-line input** (`I1`), **readline shortcuts** + (`I1b`), **seeding** (`SD1`), **CI** (`TT5`), + **tutorial system** (`TU1`, `[~]`). + +Two handoff-13 items the user already **accepted** (not work, +just recorded): - **Partial entry words classify as `DefiniteErrorAt`** - (handoff-13 §3) — the user accepted this; the matrix test - `app_commands::partial_entry_word_classifies_as_definite_error_but_completes` - documents it. + (handoff-13 §3) — documented by the matrix test + `app_commands::partial_entry_word_classifies_as_definite_error_but_completes`. - **Matrix scope** (handoff-13 §4) — cursor coverage is "meaningful transitions" not every byte offset; assertion (5) - is parse-layer not a live dispatch differential. User - accepted both. + is parse-layer, not a live dispatch differential. ## §5. Architectural delta (vs. handoff-13) @@ -217,6 +245,17 @@ handoff-13's two accepted items: `help.intro` / `help.dsl_section` / `help.types_reference`, `help.{app,ddl,data}.*` (×20). +### Post-handoff cleanup (this section's work) + +After the eight items above, three follow-ups landed: + +- `CommandNode.hint_mode` field removed (commit `6d2b929`) — + see §3.2. +- ADR-0024 amended with a "Phase F minimal" implementation + note (`parser.rs` retained as the router); `docs/adr/README.md` + index line updated to match. +- `docs/requirements.md` reconciled — see §4. + ## §6. How to take over 1. **Read this file, then handoff-13, then 12** for the chain. @@ -224,12 +263,14 @@ handoff-13's two accepted items: escalated every ambiguous fork (HintMode mechanism, the `Box::leak` arena's true cost, the Form C restructure twice) rather than deciding unilaterally. -3. **Run `cargo test`** — 1006 passing, 0 failing, 1 ignored. -4. **Run `cargo clippy --all-targets -- -D warnings`** — clean. -5. **Resolve §3** — the two flagged dead-code items — with the - user. -6. Then the standing ADR roadmap (§4) is the next structural - work; pick per the user's priorities. +3. **Read `docs/requirements.md`** — reconciled this session; + it is the authoritative "what's open" tracker (§4). +4. **Run `cargo test`** — 1006 passing, 0 failing, 1 ignored. +5. **Run `cargo clippy --all-targets -- -D warnings`** — clean. +6. **Pick the next work from §4 / `requirements.md`** — but + prioritisation is a user product decision; ask, don't + assume. handoff-12's backlog and ADR-0024 are both fully + done — there is no carry-forward debt. ### Note on the typing-surface matrix diff --git a/docs/requirements.md b/docs/requirements.md index d81565e..843ca11 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -26,9 +26,12 @@ repo is pushed). ## Test baseline -After B2/C2 (column drop / rename / change-type): **449 -passing, 0 failing, 0 skipped** (`cargo test`). Clippy clean -with the nursery lint group enabled. +After ADR-0024 full implementation + the handoff-14 cleanup +pass: **1006 passing, 0 failing, 1 ignored** (`cargo test` — +the one ignored test is a long-standing `` ```ignore `` +doc-test in `src/friendly/mod.rs`). Clippy clean with the +nursery lint group enabled. (Earlier reference point, after +B2/C2: 449 passing.) --- @@ -101,11 +104,12 @@ with the nursery lint group enabled. 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` (basic - listing), `save`, `save as`, `load`, `new`, `rebuild`, - `export`, `import` all implemented (Iterations 4 + 5). `seed` - in the seeding iteration; `replay` / `undo` / `redo` in the - U-series; `hint` with H2.)* + *(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.)* ## DSL data commands @@ -301,8 +305,12 @@ with the nursery lint group enabled. - [x] **U3** `history.log` records every successfully executed command in append-only form (Iteration 2). Format: `|ok|` per ADR-0015 §5. -- [ ] **U4** `replay` runs commands from a `history.log` or - `.commands` file. +- [x] **U4** `replay` runs commands from a `history.log` or + `.commands` file. *(Implemented via ADR-0024 Phase E: + `runtime::run_replay` parses each non-blank, non-`#`-comment + line with the schema-aware parser and dispatches it through + the normal pipeline; stops at the first error, no rollback; + nested replay refused. Covered by `tests/replay_command.rs`.)* ## Sharing and export (per ADR-0007) @@ -350,14 +358,21 @@ with the nursery lint group enabled. separate effort from H1 (which targets database errors); it targets parser errors. Pending — multiple targeted fixes shipping piecemeal so far (e.g. `values` becoming optional in - INSERT removes one such case). + INSERT removes one such case; ADR-0024's typed value slots + give per-column-type rejection wording; `insert into T (col)` + with no `values` clause now flags "looks like Form A — add + `values (...)`"). A systematic pass is still pending. - [ ] **H2** `hint` provides contextual help for the current input or the most recent error. - [ ] **H3** `help` provides general reference and per-command help. - *(Progress: `help` app-level command lists currently-supported - commands + DSL grammar reference + types, kept in sync with - what's wired up. Per-command detail is the missing piece.)* + *(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.)* ## CLI