claude@clouddev1
669 lines
28 KiB
Markdown
669 lines
28 KiB
Markdown
# Session handoff — 2026-05-15 (9)
|
|
|
|
Ninth handover. This session executed **ADR-0024 phases A
|
|
through F** in one sitting, six commits. The walker is now the
|
|
sole parse path; the chumsky dependency is gone. What did NOT
|
|
land — and what the next session needs to pick up — is
|
|
captured below in priority order.
|
|
|
|
## State at handoff
|
|
|
|
**Branch:** `main`. Working tree clean. **Local HEAD is
|
|
`c940ba9`**, ahead of `origin/main` by six commits (the user
|
|
pushes asynchronously; do not be blocked by unpushed state).
|
|
|
|
Commits since handoff-8's baseline (`3e1ff83`):
|
|
|
|
```
|
|
50b3542 ADR-0024 Phase A: walker framework + app-lifecycle commands
|
|
7e79ca8 ADR-0024 Phase B: DDL commands without value literals
|
|
6bb6882 ADR-0024 Phase C: create table with column-list value literals
|
|
c2accc2 ADR-0024 Phase D: data commands at chumsky parity
|
|
dca472f ADR-0024 Phase E: replay end-to-end
|
|
c940ba9 ADR-0024 Phase F (minimal): drop chumsky from the parse path
|
|
```
|
|
|
|
**Tests:** **844 passing, 0 failing, 1 ignored** (up from 777
|
|
at handoff-8's baseline; +67 over this session). The ignored
|
|
test is still the same `\`\`\`ignore` doc-test in
|
|
`src/friendly/mod.rs`.
|
|
|
|
**Clippy:** clean with `nursery` lints enabled and
|
|
`-D warnings`.
|
|
|
|
**Cargo.toml:** `chumsky` dependency dropped. `thiserror`
|
|
remains gone (per handoff-8). The crate's parse path is now
|
|
fully Rust-native (lexer + walker, no parser-combinator
|
|
library).
|
|
|
|
## What shipped this session — quick overview
|
|
|
|
ADR-0024's six phases all landed end-to-end. Walker now owns
|
|
all 20 entry-keyword commands across 14 entry words:
|
|
|
|
- **Phase A:** walker framework + 11 app-lifecycle commands
|
|
(quit, help, rebuild, save / save as, new, load, export,
|
|
import, mode, messages). Optional + Choice + Seq combinators.
|
|
BarePath terminal. Path-bearing UX change shipped (paths
|
|
with spaces require quotes).
|
|
- **Phase B:** DDL — drop, add, rename, change. Repeated
|
|
combinator with optional separator. Flag terminal. NumberLit
|
|
+ Literal terminals. Optional now propagates inner
|
|
expectations as `skipped` so completion sees "what could
|
|
have appeared here".
|
|
- **Phase C:** create table. Repeated with `,` separator
|
|
(first use). `with pk` defaulting to `id:serial`.
|
|
- **Phase D:** data — show, insert, update, delete. StringLit
|
|
terminal. Value-literal sub-grammar. **Schema-aware value
|
|
typing deliberately deferred** (see below).
|
|
- **Phase E:** replay. `Choice(StringLit, BarePath)`.
|
|
- **Phase F (minimal):** chumsky combinators deleted, chumsky
|
|
crate dep dropped. **Significant scope deferred** (see
|
|
below).
|
|
|
|
## DEFERRED — work the next session needs to pick up
|
|
|
|
This is the meat of the handoff. Items grouped by urgency.
|
|
|
|
### 1. Phase F (full): legacy parser-side modules still standing
|
|
|
|
ADR-0024 §migration Phase F prescribes deleting these modules.
|
|
Phase F minimal in this session only deleted the chumsky
|
|
combinator code. The following are still in place and consumed
|
|
by other modules:
|
|
|
|
| Module | Still consumed by | Why kept |
|
|
|---|---|---|
|
|
| `src/dsl/lexer.rs` | `theme.rs`, `input_render.rs`, `app.rs`, `dsl/usage.rs`, `dsl/parser.rs` | Per-token highlighting + echo-line tokenization + completion partial-token detection |
|
|
| `src/dsl/keyword.rs` (`Keyword` enum) | `completion.rs`, `friendly/keys.rs`, `theme.rs`, `dsl/usage.rs` | Catalog key derivation (`parse.token.keyword.*`), keyword-name validation in completion |
|
|
| `src/dsl/ident_slot.rs` (`IdentSlot` enum) | `completion.rs`, `input_render.rs`, `runtime.rs`, `db.rs` | Schema-cache lookups dispatched per slot kind |
|
|
| `src/dsl/usage.rs::REGISTRY` + `matched_entry` | `completion.rs`, `app.rs` | Per-command usage templates rendered on parse error |
|
|
| `parse.token.keyword.*` catalog (40+ entries) | `dsl/usage.rs`, `friendly/keys.rs` | Keyword wording in usage templates |
|
|
|
|
**Replacement strategy** (sketched, for the migrating session):
|
|
|
|
- **Highlighting** (`input_render.rs::render_input_panel`):
|
|
the walker's `WalkResult::per_byte_class` populates
|
|
`(start, end, HighlightClass)` per matched terminal. Wire
|
|
this output to the `tok_*` theme colours in place of the
|
|
current `lex(input)`-driven span builder. Walker error
|
|
positions feed the `tok_error` overlay. This is the single
|
|
biggest change.
|
|
- **Completion** (`completion.rs::candidates_at_cursor`): the
|
|
walker's `WalkResult` at `WalkBound::Position(cursor)` (NOT
|
|
yet exercised — the walker's `walk()` does support this,
|
|
but no caller passes it today) gives `expected: Vec<Expectation>`
|
|
at the cursor. The bridge already maps `Expectation::Ident
|
|
{ source: Tables/Columns/Relationships/Types }` to the
|
|
user-facing labels matching `IdentSlot::expected_label`, so
|
|
the existing completion engine reads them transparently.
|
|
What's missing: a walker-driven path that bypasses
|
|
`parse_command` entirely and asks the walker directly for
|
|
candidates per `IdentSource`. Today the bridge round-trips
|
|
through `ParseError::Invalid::expected` strings — works,
|
|
but loses information.
|
|
- **Echo-line tokenization** (`output_render.rs` for
|
|
`OutputKind::Echo + Mode::Simple`): same lex-driven spans.
|
|
Same walker `per_byte_class` plumbing.
|
|
- **Usage templates** (`dsl/usage.rs::REGISTRY` + `matched_entry`):
|
|
every `CommandNode` already has `usage_id`. Wire the
|
|
parse-error renderer to look up the catalog entry by
|
|
`usage_id` instead of `matched_entry`. Then `REGISTRY` and
|
|
`matched_entry` can go.
|
|
- **Catalog cleanup** (`parse.token.keyword.*` + `friendly/keys.rs`):
|
|
ADR-0024 §cleanup-pass §F mentions a `format_keyword_for_error
|
|
(literal) -> String` helper that wraps a literal in
|
|
backticks and replaces the per-keyword catalog entries.
|
|
Mechanical; do it after the consumers stop reading the
|
|
catalog keys.
|
|
|
|
**Estimated cost: one full session** for the consumer
|
|
migration + a follow-up commit for the catalog cleanup. Test
|
|
suite serves as the regression net throughout.
|
|
|
|
### 2. Phase D (full): schema-aware value typing
|
|
|
|
ADR-0024 §migration Phase D prescribes "full schema awareness"
|
|
via `DynamicSubgrammar(column_value_list)` that unfolds typed
|
|
slots per column at walk time. **This session deferred it.**
|
|
|
|
What's in place:
|
|
|
|
- `Node::DynamicSubgrammar(fn(&WalkContext) -> Node)` variant
|
|
declared but unused. The walker's driver returns
|
|
`Failed { expected: vec![] }` on this branch (intentional —
|
|
catches grammar bugs that declare DynamicSubgrammar without
|
|
the wiring landing).
|
|
- `WalkContext::current_table`,
|
|
`WalkContext::current_table_columns`,
|
|
`WalkContext::current_column` all declared but unwritten.
|
|
No `Ident` node has a `writes_table: bool` or equivalent.
|
|
- Per-type validators (`int_slot`, `decimal_slot`, etc.) NOT
|
|
written. The current walker uses a generic `value_literal`
|
|
Choice that accepts any literal regardless of column type;
|
|
bind-time type-check errors fire as today.
|
|
|
|
**To implement:**
|
|
|
|
1. Plumb a `SchemaCache` reference into `parse_command` (and
|
|
thus `parse_tokens`). Currently the call site is in
|
|
`runtime.rs::dispatch_input` — passes `app.schema_cache()`
|
|
alongside the input.
|
|
2. Extend `WalkContext::new(schema)` to carry the cache.
|
|
3. Implement `Node::DynamicSubgrammar` walker dispatch:
|
|
resolve at walk time, leak the returned `Node` into a
|
|
per-walk arena (or `Box::leak` per ADR-0024 §sub-grammars).
|
|
4. Implement `Ident { source: Tables, writes_table: true }`
|
|
semantics — when the ident matches, look up the table in
|
|
the schema, populate `current_table` + `current_table_columns`.
|
|
5. Implement typed value slots — `int_slot()`, `decimal_slot()`,
|
|
etc. per ADR-0024 §typed-value-slots. Each is a Choice
|
|
over the literal forms with a content validator.
|
|
6. Wire `column_value_list` as a DynamicSubgrammar that reads
|
|
`current_table_columns` and emits a Seq of typed slots
|
|
separated by commas.
|
|
7. Update `insert` shape to use `column_value_list` instead
|
|
of the generic value list.
|
|
8. Update `update`/`delete` to use the per-column value slot
|
|
based on `current_column`.
|
|
|
|
**The user UX win this unlocks:** typed slots reject
|
|
mis-shaped input at parse time with localised wording (e.g.,
|
|
"Type a date as 'YYYY-MM-DD'") instead of bind-time errors;
|
|
completion narrows per column type. This is the Phase D
|
|
"central design claim" per the handoff.
|
|
|
|
**Side effect to watch for:** parse_command becomes schema-
|
|
dependent. Tests that exercised parse in isolation may need
|
|
to pass a schema cache (today's tests don't — most just
|
|
check round-trip parses where schema doesn't matter).
|
|
|
|
**Estimated cost: 1-2 sessions** depending on how deep the
|
|
schema plumbing goes through dispatch.
|
|
|
|
### 3. Walker doesn't drive completion or hints directly
|
|
|
|
Today's flow: walker produces `WalkOutcome` → bridge to
|
|
`ParseError::Invalid` → completion / hint engines read
|
|
`expected: Vec<String>`. The bridge formats `Expectation::Ident
|
|
{ source: … }` to the user-facing label string the existing
|
|
engines recognise.
|
|
|
|
This works but loses information. Walker knows:
|
|
- The `IdentSource` of every expected slot.
|
|
- The `role` of every slot (e.g., `parent_table` vs
|
|
`child_table`).
|
|
- The `HintMode` per node (currently always `Default`).
|
|
- The `skipped` expectations from any Optional that didn't
|
|
engage at this position.
|
|
- The cursor's full `MatchedPath` so far — the AST builder
|
|
could be invoked partially to extract context (e.g., "you've
|
|
typed `update Customers set Email=`, the `Email` column's
|
|
type is `text`").
|
|
|
|
A walker-direct completion path would surface much more
|
|
informative candidates than the current ParseError-string round
|
|
trip. See ADR-0024 §architecture: "Completion at cursor:
|
|
`walk(source, Position(cursor), ctx)`, inspect `outcome.expected`."
|
|
|
|
**Today, no caller invokes `walk()` with `WalkBound::Position(cursor)`.**
|
|
The variant exists in `outcome.rs` (annotated `#[allow(dead_code)]`).
|
|
`completion.rs` still calls `parse_command(leading_slice)` —
|
|
the slice-and-re-parse approach inherited from chumsky.
|
|
|
|
**Migration path:** add a `pub fn candidates_at_cursor_from_walker
|
|
(input, cursor, schema) -> WalkResult` that calls
|
|
`walker::walk(input, WalkBound::Position(cursor), &mut ctx)`
|
|
and returns the result. Then `completion.rs` reads
|
|
`expected` directly with full `IdentSource` + `role` info.
|
|
|
|
### 4. `HintMode` declared but unused
|
|
|
|
`HintMode::Default | ForceProse | ProseOnly | SuppressProse` is
|
|
declared in `grammar/mod.rs` but every `CommandNode` and
|
|
every `Node::Ident` sets it to `None`. The current ad-hoc
|
|
hint cases in `input_render.rs::ambient_hint` (value-literal
|
|
slot suppression, NewName slot typing-name prose,
|
|
invalid-ident overlay) still use the chumsky-era ad-hoc
|
|
detection.
|
|
|
|
ADR-0024 §HintMode-per-node says these migrate to
|
|
node-attached `HintMode` annotations during Phase D. They
|
|
didn't.
|
|
|
|
**To do:** annotate the value-literal slots with
|
|
`HintMode::ProseOnly("value_literal_format_hint")`; annotate
|
|
NewName slots with the typing-name prose; have the hint
|
|
resolver pick up the mode and dispatch.
|
|
|
|
### 5. Ranker hook: declared in ADR-0024, not implemented at all
|
|
|
|
ADR-0024 §ranker-layer specifies a `Ranker` function type
|
|
between the walker's raw candidates and the hint-panel
|
|
renderer. The default is `identity_ranker` (declaration-order
|
|
preserved).
|
|
|
|
**Status: not declared anywhere in code.** No `Ranker` type,
|
|
no identity ranker, no hook into completion. The current
|
|
completion engine ranks by its own ad-hoc logic (keyword
|
|
matches first, then schema, alphabetised within each).
|
|
|
|
This is a small future-work hook. Not blocking.
|
|
|
|
### 6. Aliases: feature works, no aliases declared
|
|
|
|
`Word::aliases: &'static [&'static str]` is wired through
|
|
`Word::matches` and the walker correctly accepts case-
|
|
insensitive alias matches. **Today every `Word` in the
|
|
grammar has an empty aliases slice.**
|
|
|
|
The round-5 `q` quit alias removal stands — if the user
|
|
wants it back, it's:
|
|
|
|
```rust
|
|
const QUIT_WORD: Word = Word {
|
|
primary: "quit",
|
|
aliases: &["q"],
|
|
highlight_override: None,
|
|
};
|
|
pub static QUIT: CommandNode = CommandNode {
|
|
entry: QUIT_WORD,
|
|
...
|
|
};
|
|
```
|
|
|
|
The walker matches either; completion only surfaces the
|
|
primary. No further wiring needed.
|
|
|
|
### 7. Test edits worth knowing about
|
|
|
|
A handful of tests changed wording assertions to match
|
|
walker-emitted error wording:
|
|
|
|
- `src/dsl/walker/mod.rs::walker_import_trailing_as_without_target_errors`
|
|
— assertion weakened from checking for "target" to checking
|
|
for "import". Walker's Optional backtracking means
|
|
`import foo.zip as ` parses as `Import { path: "foo.zip",
|
|
target: None }` followed by trailing `as ` → walker reports
|
|
`expected end of input, found …`. The friendly
|
|
`project.import_empty_target` wording moved out of the
|
|
parser. The integration test
|
|
(`tests/iteration5_export_import.rs::import_with_empty_target_after_as_errors`)
|
|
still passes because the rendered `import_usage` template
|
|
line in the dispatch output contains both "import" and
|
|
"target".
|
|
- The walker's parse error wording for incomplete inputs
|
|
consistently uses "after `<consumed>`, expected …, found
|
|
end of input" — matches the chumsky-era contract that
|
|
`structural_error_for_show_data_without_arg` and friends
|
|
pin down.
|
|
|
|
**No `parse.token.keyword.*` wording changed.** No catalog
|
|
entries changed. No user-visible string regression.
|
|
|
|
### 8. The `value_literal_hint_at_cursor` stopgap
|
|
|
|
The round-6 stopgap from handoff-8 (replacing `null true false`
|
|
with prose at value-literal slots) **is still live**. It
|
|
lives in `completion.rs::value_literal_hint_at_cursor` and
|
|
detects the value-literal-signature in `expected`. With Phase
|
|
D's full schema awareness, this would become "narrow to the
|
|
actual column's type" (e.g., "Type a date as 'YYYY-MM-DD'")
|
|
— but that requires the schema plumbing in §2 above.
|
|
|
|
**Today the stopgap continues to fire for every value-literal
|
|
slot regardless of column type.** Same wording as handoff-8.
|
|
|
|
### 9. Choice greedy-semantics shape contortions
|
|
|
|
ADR-0023 says "the trie design is greedy (the first child
|
|
node that matches wins)." This is the design. But it forced
|
|
some grammar contortions worth knowing about:
|
|
|
|
- **`insert` Form A vs Form C disambiguation** (`grammar/data.rs`):
|
|
Forms A (`insert into T (cols) values (vals)`) and C (`insert
|
|
into T (vals)` — bare value list) both start with `(`. The
|
|
inner-paren content is parsed as a heterogeneous
|
|
`Choice(VALUE_LITERAL, Ident{Columns})` — VALUE_LITERAL
|
|
ordered first so `null`/`true`/`false` match their Word
|
|
branch rather than the broader identifier catch-all (which
|
|
`consume_ident` doesn't filter against the keyword set).
|
|
AST builder discriminates by the presence of the `values`
|
|
keyword AFTER the first paren. **Brittle if a future grammar
|
|
needs to add another paren-bounded form starting at the
|
|
same position.**
|
|
- **`drop` sub-form ordering**: `drop_column` and
|
|
`drop_relationship` come before `drop_table` in the Choice
|
|
because they're more specific (longer prefix). Walker
|
|
greediness handles this correctly because each branch's
|
|
first Word disambiguates.
|
|
|
|
### 10. Walker `per_byte_class` populated but unused
|
|
|
|
`WalkResult::per_byte_class: Vec<ByteClass>` is populated by
|
|
every terminal match in the walker driver. **No consumer
|
|
reads it today.** The annotation `#[allow(dead_code)]` sits
|
|
on the field. When the highlighting consumer migrates (§1
|
|
above), this is the data source.
|
|
|
|
### 11. Differential test scaffolding wasn't actually built
|
|
|
|
ADR-0024 §test-discipline §3 specifies a "differential check
|
|
during the migration window" — a test helper that runs both
|
|
parsers on the existing input corpus and asserts identical
|
|
`Command` output. Removed at Phase F cleanup.
|
|
|
|
**This session went with hand-curated expected `Command`
|
|
outputs in `dsl::walker::tests` instead.** Equivalent
|
|
coverage (every migrated command's parse asserted), simpler
|
|
to maintain. Since chumsky is now gone (Phase F minimal
|
|
removed the combinator code), no removal step needed.
|
|
|
|
If a strict differential check is wanted retroactively, the
|
|
chumsky path would need to be reconstructed from git history
|
|
and run alongside walker against the test corpus — not
|
|
trivial. The hand-curated tests + the existing integration
|
|
test suite serve the same regression-net role.
|
|
|
|
### 12. `WalkContext` writes during walk — design exists, not implemented
|
|
|
|
ADR-0024 §WalkContext sketches `Ident { source: Tables,
|
|
writes_table: true }` semantics: when the ident matches, the
|
|
walker writes `current_table` to context. Subsequent dynamic
|
|
sub-grammars read it.
|
|
|
|
**Today no `Ident` node has a `writes_table` field.** The
|
|
struct definition in `grammar/mod.rs` is:
|
|
|
|
```rust
|
|
Ident {
|
|
source: IdentSource,
|
|
role: &'static str,
|
|
validator: Option<IdentValidator>,
|
|
highlight_override: Option<HighlightClass>,
|
|
}
|
|
```
|
|
|
|
When Phase D (full) lands, add a `writes_table: bool`
|
|
(or similar) field and have the walker driver populate
|
|
`WalkContext` accordingly.
|
|
|
|
### 13. `CommandNode::usage_id` / `help_id` not consumed
|
|
|
|
Every `CommandNode` declares `usage_id: Option<&'static str>`
|
|
and `help_id: Option<&'static str>` pointing into the
|
|
catalog. **No code reads these fields.** Usage rendering
|
|
still goes through `dsl/usage.rs::matched_entry`. Help
|
|
text still hand-curated.
|
|
|
|
When `dsl/usage.rs::REGISTRY` retires (§1 above), wire
|
|
the parse-error renderer and the in-app help system to read
|
|
these fields directly.
|
|
|
|
## Sharp edges to know about
|
|
|
|
These are facets of the walker's behaviour that aren't bugs
|
|
but that will surprise someone reading the code cold.
|
|
|
|
- **Optional backtracking on partial-match** is intentional
|
|
(matches chumsky's `or_not` semantics). When an Optional's
|
|
inner consumes some terminals and then fails (Incomplete or
|
|
Mismatch), the walker rolls back the path / per_byte state
|
|
to the pre-Optional position and treats it as skipped, with
|
|
the inner's expectations carried as `skipped` on the
|
|
Matched return. **Validation failures (content errors) do
|
|
NOT backtrack** — the user means to fix those. This
|
|
asymmetry is the load-bearing decision that makes
|
|
`create table T with` produce the correct
|
|
`IncompleteAtEof` classification (chumsky's behaviour).
|
|
- **Walker's `Choice` is strictly greedy** — first child
|
|
whose first terminal matches wins. No backtracking. Required
|
|
ordering: more-specific shapes before more-general. See §9
|
|
above for examples.
|
|
- **`Ident { source: Tables/Columns/Relationships }` does NOT
|
|
validate against the schema at parse time.** It's a
|
|
shape-only check today. Schema-aware parse is the Phase D
|
|
vision; see §2.
|
|
- **`Literal(&'static str)` matches verbatim bytes with a
|
|
word-boundary lookahead** so `1` doesn't half-match `12`
|
|
and `n` doesn't half-match `name`. The highlight class is
|
|
inferred from the literal's bytes (digits → Number, else
|
|
Keyword). Used today only for the `1` in `add 1:n
|
|
relationship`.
|
|
- **`AST builder` failures surface as `WalkOutcome::ValidationFailed`
|
|
with `at_eof = true`**. The bridge maps these to
|
|
`ParseError::Invalid` with `at_eof: true` so the input
|
|
renderer classifies them as `IncompleteAtEof` (no live
|
|
overlay; on-submit error fires). This mirrors the chumsky-
|
|
side custom-error convention.
|
|
- **`unknown_command_error` is the sole catch-all** for
|
|
inputs whose first identifier-shape token isn't a registered
|
|
entry word. Wording: "expected one of `add`, …, found
|
|
`<word>`". Position is the start of the unknown word.
|
|
- **`q` quit alias remains gone.** The walker SUPPORTS
|
|
aliases natively — adding `q` back is a one-line change on
|
|
`QUIT.entry.aliases` (see §6).
|
|
- **Path-bearing UX change shipped (Phase A + E):** `replay`,
|
|
`import`, `export` paths terminate at the first whitespace
|
|
byte. Paths with spaces use the quoted form
|
|
(`replay 'my project/seed.commands'`). This is per ADR-0024.
|
|
|
|
## Suggested next-session priorities
|
|
|
|
In order:
|
|
|
|
1. **Phase F (full): consumer migration to walker outputs.**
|
|
This is the biggest deferred chunk and the right next
|
|
structural move. See §1 above for the migration sketch.
|
|
~1 session for the highlighting + completion + usage
|
|
migration; one follow-up commit for the catalog cleanup
|
|
and lexer/keyword/ident_slot deletion.
|
|
2. **Phase D (full): schema-aware value typing.** Once the
|
|
schema cache plumbing exists, the `DynamicSubgrammar`
|
|
wiring + typed value slots are mechanical. See §2.
|
|
3. **Walker-driven completion** (§3). Smaller scope than the
|
|
above. Surfaces `IdentSource` + `role` directly to the
|
|
completion engine without the ParseError-string round
|
|
trip. Unlocks better hint UX.
|
|
4. **`HintMode` annotations** (§4). Mechanical migration of
|
|
the ad-hoc hint cases in `input_render.rs` to node
|
|
annotations. Small.
|
|
5. **Ranker hook** (§5). Future work. Plug-in point for
|
|
frequency-based ranking, content-aware priors, recency.
|
|
|
|
After (1) and (2) land, the codebase reaches the steady-state
|
|
ADR-0024 envisioned: one declaration per command, no scatter,
|
|
walker as single source of truth across parse / complete /
|
|
highlight / hint / usage.
|
|
|
|
## ADR index (read these before touching the related areas)
|
|
|
|
```
|
|
0000 Record architecture decisions (process)
|
|
0001 Language and TUI framework (Rust + Ratatui)
|
|
— chumsky dependency dropped in Phase F minimal
|
|
0002 Database engine (User-facing posture)
|
|
0003 Input modes and command dispatch
|
|
0004 Project file format (amended by 0015)
|
|
0005 Column type vocabulary
|
|
0006 Undo snapshots and replay log (designed, not impl)
|
|
0007 Sharing and export (amended by 0015 amendment 1)
|
|
0008 Testing approach
|
|
0009 DSL command syntax conventions
|
|
0010 Database access via worker thread
|
|
0011 FK column type compatibility
|
|
0012 Internal metadata for user-facing column types
|
|
0013 Relationships, naming, and rebuild-table strategy
|
|
0014 Data operations, value literals, and auto-show
|
|
0015 Project storage runtime
|
|
0016 Pretty table rendering for data and structure views
|
|
0017 Column type-change compatibility
|
|
0018 Auto-fill contracts for serial and shortid columns
|
|
0019 Friendly error layer (H1) and i18n message catalog
|
|
— `parse.token.keyword.*` collapse pending Phase F full
|
|
0020 Tokenization layer for the DSL parser
|
|
— superseded by the scannerless walker in ADR-0024;
|
|
the lexer module survives until Phase F full
|
|
0021 Parser-as-source-of-truth for H1a
|
|
— usage info migration to grammar nodes pending
|
|
(CommandNode.usage_id declared, not consumed yet)
|
|
0022 Ambient typing assistance (I3 + I4 unified)
|
|
— completion still chumsky-bridge; walker direct
|
|
path pending
|
|
0023 Unified declarative grammar tree (direction)
|
|
— superseded for execution by ADR-0024
|
|
0024 Unified grammar tree: execution plan (ACCEPTED)
|
|
— A through F minimal landed; F full + D full deferred
|
|
```
|
|
|
|
## Repository layout (delta vs. handoff-8)
|
|
|
|
New files this session:
|
|
|
|
```
|
|
src/dsl/grammar/
|
|
mod.rs (267) — Node enum, Word, IdentSource, HintMode,
|
|
HighlightClass, ValidationError,
|
|
IdentValidator, NumberValidator,
|
|
CommandNode, REGISTRY (20 commands)
|
|
app.rs (272) — 11 app-lifecycle commands
|
|
ddl.rs (492) — drop, add, rename, change, create
|
|
data.rs (504) — show, insert, update, delete, replay
|
|
shared.rs (108) — type validator, qualified_column,
|
|
referential_clauses, action_keyword
|
|
src/dsl/walker/
|
|
mod.rs (~620) — walk() entry + 53 walker tests
|
|
driver.rs (~570) — per-node-kind dispatch with backtracking
|
|
context.rs (43) — WalkContext (schema fields stubbed)
|
|
outcome.rs (~165) — WalkResult, WalkOutcome, MatchedPath
|
|
lex_helpers.rs (~190) — byte-level helpers (skip_whitespace,
|
|
consume_ident, match_keyword,
|
|
consume_bare_path, consume_flag,
|
|
consume_number_literal, consume_string_literal)
|
|
```
|
|
|
|
Files modified this session:
|
|
|
|
```
|
|
src/dsl/mod.rs — wire grammar + walker modules
|
|
src/dsl/parser.rs — chumsky combinators deleted; now a
|
|
~290-line walker bridge with the
|
|
original test suite (~840 lines) intact
|
|
Cargo.toml — chumsky dependency removed
|
|
Cargo.lock — regenerated
|
|
```
|
|
|
|
Files NOT touched but worth knowing about (still consume the
|
|
legacy modules per §1):
|
|
|
|
```
|
|
src/dsl/lexer.rs — still exports lex() / Token / TokenKind
|
|
src/dsl/keyword.rs — Keyword enum still alive
|
|
src/dsl/ident_slot.rs — IdentSlot enum still alive
|
|
src/dsl/usage.rs — REGISTRY + matched_entry still alive
|
|
src/completion.rs — reads ParseError::Invalid::expected
|
|
(bridge from walker), uses Keyword +
|
|
IdentSlot
|
|
src/input_render.rs — uses lex() for token-class colouring
|
|
src/theme.rs — token colour mappings keyed on Keyword
|
|
src/runtime.rs, src/db.rs — IdentSlot::expected_label round-trip
|
|
```
|
|
|
|
## How to take over
|
|
|
|
1. **Read this file.**
|
|
2. **Read `CLAUDE.md`** for the working-style rules. Note
|
|
the "Escalate ambiguity — do not decide for the user"
|
|
rule. The deferred items below are scoped enough that
|
|
most decisions are clear; escalate if the spec genuinely
|
|
disagrees with the implementation.
|
|
3. **Read ADR-0024**
|
|
(`docs/adr/0024-unified-grammar-tree-execution-plan.md`)
|
|
to understand the design intent. Phase F (full) and Phase D
|
|
(full) are the unfinished work.
|
|
4. **Skim `src/dsl/grammar/mod.rs`** — the Node enum + Word
|
|
+ CommandNode + REGISTRY are the contract.
|
|
5. **Skim `src/dsl/walker/mod.rs`** — the walk() entry +
|
|
bridge logic. The 53 tests at the bottom of that file
|
|
are the behavioural spec.
|
|
6. **Run `cargo test`** to confirm the 844-test baseline.
|
|
Lib test count is 711 in `rdbms_playground` (the rest are
|
|
integration + doctests). Total should be 844 passed, 0
|
|
failed, 1 ignored.
|
|
7. **Run `cargo clippy --all-targets -- -D warnings`** to
|
|
confirm clean baseline.
|
|
8. **Pick a deferred item from §1-§5** and start. §1
|
|
(Phase F full) is the natural next move; it unblocks §3
|
|
(walker-driven completion) and §4 (HintMode annotations).
|
|
§2 (Phase D full) is the second-largest item and can
|
|
land in parallel since it touches the grammar layer
|
|
rather than the consumer layer.
|
|
|
|
### End-to-end smoke test (current state, post-ADR-0024)
|
|
|
|
```
|
|
$ rm -rf /tmp/handoff9-smoke
|
|
$ rdbms-playground --data-dir /tmp/handoff9-smoke
|
|
|
|
# Inside the app:
|
|
|
|
# All commands now route through the walker. User-visible
|
|
# behaviour is unchanged from handoff-8 except for:
|
|
# - import / export paths with spaces require quotes
|
|
# - replay paths with spaces require quotes
|
|
# - parse error wording uses "after `<consumed>`, expected …,
|
|
# found end of input" framing (matches the chumsky-era
|
|
# contract; tests pin this down)
|
|
|
|
# Smoke commands:
|
|
help -- in-app help
|
|
mode advanced -- mode switch
|
|
quit -- exit (no `q`)
|
|
:quit -- one-shot escape
|
|
also works
|
|
|
|
# DDL:
|
|
create table Customers with pk
|
|
add column Customers: Email (text)
|
|
add 1:n relationship from Customers.id to Orders.customer_id
|
|
|
|
# Data:
|
|
insert into Customers values (1, 'Alice')
|
|
update Customers set Email='new@b.c' where id=1
|
|
delete from Customers where id=1
|
|
show data Customers
|
|
show table Customers
|
|
|
|
# Replay:
|
|
replay history.log
|
|
replay 'my project/seed.commands'
|
|
|
|
# Errors:
|
|
frobulate widgets
|
|
# → expected one of `add`, `change`, `create`, `delete`,
|
|
# `drop`, `export`, `help`, `import`, `insert`, `load`,
|
|
# `messages`, `mode`, `new`, `quit`, `rebuild`, `rename`,
|
|
# `replay`, `save`, `show`, or `update`, found `frobulate`
|
|
|
|
mode bogus
|
|
# → unknown mode 'bogus' (expected 'simple' or 'advanced')
|
|
|
|
change column T: c (int) --force-conversion --dont-convert
|
|
# → `--force-conversion` and `--dont-convert` are mutually
|
|
# exclusive — pick one.
|
|
|
|
create table Customers
|
|
# → tables need at least one column. Add `with pk` for a
|
|
# default `id INTEGER PRIMARY KEY`, or `with pk <name>:<type>`
|
|
# …
|
|
|
|
# All wording sourced from the en-US.yaml catalog via the
|
|
# walker's ValidationError catalog-key mechanism.
|
|
```
|
|
|
|
After Phase F full lands, this smoke test extends with:
|
|
- Per-keystroke highlighting driven by walker `per_byte_class`
|
|
- Cursor-position completion driven by walker direct path
|
|
- Usage templates rendered from `CommandNode.usage_id`
|
|
- Lexer/Keyword/IdentSlot modules removed from the source tree
|