fix: H1a G3 advanced usage shows all valid forms; complete near-miss matrix (ADR-0042)

The /runda DA pass found G3 over-corrected: advanced-mode `create`/`drop`
showed SQL forms only, hiding the DSL fallback forms that are valid input
in advanced mode (verified: `create table Foo with pk`, `drop column …`
parse and dispatch). Per the user decision, the advanced usage block now
shows every form valid in the mode, SQL-primary first, then the DSL
fallback forms — a usage hint must never hide working input. Simple mode
unchanged (DSL forms only).

Matrix completion (closing the residual coverage tail):
- arg-less app commands (help/rebuild/new/load/undo/redo/export/import)
  audited + locked — all reject trailing junk with "expected end of
  input" + usage.
- committed multi-forms (add index/constraint/1:n relationship, drop
  index/constraint/relationship, show table, change column, create index,
  alter table add/drop) audited + locked in
  near_miss_matrix_committed_multiforms — each renders its own
  form-specific missing-keyword message + usage.

Also from the DA pass:
- G2 distinct+all detector empirically verified unique to projection
  start (no misfire at count( / union / union all / select distinct).
- stale `chumsky` comment removed (app.rs import handler).
- ADR-0042 Implementation-outcome section records G1–G4, the
  user-confirmed G3 decision, and the now-complete matrix coverage.

Full suite green (lib 1578 / it 387 / typing_surface_matrix 192); clippy clean.
This commit is contained in:
claude@clouddev1
2026-06-05 18:46:57 +00:00
parent 649fdcb38e
commit 1d4923b15b
4 changed files with 178 additions and 39 deletions
@@ -223,6 +223,55 @@ on any §2 wording change (expected; reviewed via `cargo insta`),
but the two substring suites above must stay green without edits to
their assertions.
## Implementation outcome (2026-06-05)
The baseline capture (§Implementation notes step 1) triaged four
gaps; all four are fixed test-first, locked by the near-miss matrix
in `tests/it/parse_error_pedagogy.rs`:
- **G1** — the bare `1` cardinality literal opening `add 1:n
relationship …` rendered cryptically. Render it as
`` `1:n relationship` `` in `format_expectation` (error wording
only; completion still offers the literal `1`).
- **G2** — bare `select` dumped the 14-item expression first-set.
Collapse it to "a projection: `*`, a column, or an expression"
in `format_walker_error`, detected by the `distinct`+`all`
quantifier pair being *jointly* expectable — a signature unique
to a projection start (empirically verified not to misfire at
`count(`, `union`, `union all`, `select distinct`, or mid-list).
Render-only; the completion/hint layer still expands the full
set.
- **G3** — the usage block was mode-blind (`render_usage_block`
resolved shared entry words to the first-registered Simple node).
`usage_key(s)_for_input` gain mode-aware `_in_mode` variants.
**Decision (user-confirmed, after the DA pass).** In advanced
mode the DSL forms remain *valid input* via fallback — verified:
`create table Foo with pk`, `drop column from table T: c`,
`drop relationship r`, `add column …` all parse and dispatch in
advanced mode. So the advanced usage block shows **every form
valid in the mode, mode-primary (SQL) first, then the DSL
fallback forms** — a usage hint must never hide input that works.
(An initial implementation that showed SQL-only was flagged by
the DA pass as hiding `create table … with pk` / `drop column …`
and corrected.) Simple mode shows DSL forms only — the SQL-only
forms hit the "this is SQL" rail and are unreachable.
- **G4** — `with` borrowed `select`'s usage; it gains its own
`parse.usage.with` CTE template.
Coverage: the matrix covers, in both modes, every entry word's bare
/ missing-clause / wrong-token near-misses, the app-lifecycle
trailing-junk cases, **and** the committed *multi-form* variants
(`add index` / `add constraint` / `add 1:n relationship`, `drop
index` / `drop constraint` / `drop relationship`, `show table`,
`change column …`, `create index`, `alter table … add` / `… drop`).
The committed forms were audited 2026-06-05 and each renders its own
form-specific missing-keyword message + usage (e.g. `add index` →
"expected `on` or `as`"; `drop constraint` → "expected `not`,
`unique`, `default`, or `check`"), regression-locked in
`near_miss_matrix_committed_multiforms`.
## Out of scope
1. **Advanced-SQL engine-error sanitisation** — ADR-0019 §OOS-2.