From c305dc728265ecd47b241458301bf08e56fd0539 Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Sat, 6 Jun 2026 07:44:55 +0000 Subject: [PATCH] docs: mark H1a done via the ADR-0042 systematic pass MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit requirements.md H1a → [x]: the per-command near-miss matrix (entry words, missing clauses, committed multi-forms, both modes) plus the gap fixes (G1 `1:n relationship`, G2 select projection gloss, G3 mode-aware usage showing all valid forms, G4 `with` CTE template, CROSS JOIN ON teaching message) close the systematic pass. The advanced-SQL items the survey flagged (INSERT…SELECT count, RETURNING scope) were verified already present. One low-priority residual is deferred by decision (submit-time expression first-set at non-projection positions). ADR-0042: record the pre-existing `SELECT *` arity caveat (INSERT…SELECT with a star projection isn't expanded for pre-flight arity; engine catches it at execution — adjacent to ADR-0019 §OOS-2). --- ...2-h1a-parse-error-pedagogy-grammar-tree.md | 8 +++++- docs/requirements.md | 25 +++++++++++++++---- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/adr/0042-h1a-parse-error-pedagogy-grammar-tree.md b/docs/adr/0042-h1a-parse-error-pedagogy-grammar-tree.md index 366e630..927f34e 100644 --- a/docs/adr/0042-h1a-parse-error-pedagogy-grammar-tree.md +++ b/docs/adr/0042-h1a-parse-error-pedagogy-grammar-tree.md @@ -266,7 +266,13 @@ Verifying each against the running app **reversed two of three**: - **INSERT…SELECT column-count** is *already handled* — a count mismatch fires `verdict = Error` with "the column list names N column(s) but M value(s) are given" (walker test - `insert_select_arity_mismatch_fires`). Not a gap. + `insert_select_arity_mismatch_fires`). It is a structural + list-vs-list check, so it fires even without a schema. Not a gap. + *Caveat (pre-existing, not addressed here):* a `SELECT *` + projection is not expanded for arity, so `insert into T (one_col) + select * from Multi` is not pre-caught — the engine rejects it at + execution. Star-expansion for pre-flight arity would be a separate + enhancement (and brushes ADR-0019 §OOS-2 engine-error territory). - **RETURNING scope** is *already handled* — at a bare `returning` position completion offers the table's columns; `returning ` fires the `unknown_column` diagnostic. Not a gap. diff --git a/docs/requirements.md b/docs/requirements.md index 938eae2..fd5eab4 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -557,14 +557,14 @@ since ADR-0027.) migration sweep of all other user-facing strings, advanced-mode SQL-error sanitization (§OOS-2), and `messages` persistence (§OOS-3, awaits the settings ADR).)* -- [ ] **H1a** Strong syntax-help in parse errors. When the user +- [x] **H1a** Strong syntax-help in parse errors. When the user types something near-correct (e.g. `insert into T ('Oli')` — forgotten `values`; or `update T set x=1` — missing WHERE), the error should *name the missing keyword or clause* rather than just point at the unexpected character. This is a 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 + targets parser errors. *(Done via the **ADR-0042** systematic + pass, 2026-06-06.)* Built piecemeal first (e.g. `values` becoming optional in 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 @@ -589,8 +589,23 @@ since ADR-0027.) `col`…"* message at typing time, counted against the user-fillable columns, with `serial`/`shortid` auto-fill named; new keys `diagnostic.insert_arity_mismatch_form_b_simple` / - `diagnostic.insert_arity_mismatch_all_auto`). A systematic pass is - still pending. + `diagnostic.insert_arity_mismatch_all_auto`). The **ADR-0042 + systematic pass** then closed it: a per-command near-miss matrix + (`tests/it/parse_error_pedagogy.rs`) locks every entry word's + bare / missing-clause / wrong-token cases plus the committed + multi-forms, in both modes; friendlier labels landed (`add` → + `1:n relationship`; bare `select` → "a projection: …"); the + usage block became mode-aware (advanced shows the SQL forms + plus the still-valid DSL fallback forms, SQL-first); `with` + got its own CTE template; and `cross join … on` now teaches + that a CROSS JOIN takes no ON clause. The advanced-SQL + diagnostics that the survey thought missing (INSERT…SELECT + count, RETURNING column scope) were verified already present. + One low-priority residual is deferred by decision: at *submit* + time a non-projection expression position (bare `where `, + `returning `) still shows the raw expression first-set — + typing-time completion already offers the right candidates + 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