help: advanced-mode SQL forms collapse onto simple sibling (no distinct help content) #36

New Issue

2026-06-14T23:00:32+01:00

claude-clouddev1 commented

2026-06-14 23:00:32 +01:00

Summary

The in-app help command (H3) collapses the advanced-mode SQL command
forms onto their simple-mode siblings, so help <topic> does not show
distinct help for the SQL syntax — even though the simple-DSL and
advanced-SQL syntaxes are genuinely different.

Cause

The seven advanced-mode SQL command nodes — SELECT, WITH,
SQL_INSERT, SQL_UPDATE, SQL_DELETE, EXPLAIN_SQL (and any future
SQL form) — carry help_id: None in the grammar tree. Per the comment at
src/dsl/grammar/mod.rs:915-918, this is a deduplication mechanism for
the help command's list: they share an entry word with a simple
sibling, and note_help has no dedup, so giving them a help_id would
print the same command twice in the help list.

So the collapse was a deliberate list-formatting choice, not a
decision that advanced SQL forms need no distinct help content. As a side
effect, help <sql-form> (e.g. help select) has no help.<id> block to
resolve to.

Note: the parse-error / usage layer already distinguishes them —
ADR-0042 (H1a) §"the advanced usage block shows every form" renders each
form's usage on a parse error. So only the help command lags.

Why now

Surfaced while scoping H2 / hint (ADR-0053). H2 sidesteps this by
keying tier-3 hint content on a new dedicated hint_id (one per command
form, simple and advanced, each syntactically correct), rather than on
help_id. That fixes the hint surface but leaves the help surface
unchanged — hence this separate issue. help is shipped, ADR-backed
(ADR-0021/0023/0024) territory and deserves its own decision rather than a
silent rider on the hint ADR.

Scope to decide

Confirm current behaviour: what does help select / help (advanced
mode) actually produce for the SQL forms today?
Decide whether advanced-SQL forms should have distinct help
content, and if so how to key it without re-introducing duplicate
entries in the help list (e.g. dedup by entry word + mode, or a
distinct help key rendered only in advanced mode).
Keep consistent with the H2 hint_id approach (ADR-0053) so the two
contextual-help surfaces don't diverge.

Notes

Likely a small change once the keying decision is made.
Pedagogy-relevant: advanced mode is for students moving to raw SQL, so
accurate SQL-form help matters there specifically.

## Summary The in-app `help` command (H3) collapses the **advanced-mode SQL command forms** onto their simple-mode siblings, so `help <topic>` does not show distinct help for the SQL syntax — even though the simple-DSL and advanced-SQL syntaxes are genuinely different. ## Cause The seven advanced-mode SQL command nodes — `SELECT`, `WITH`, `SQL_INSERT`, `SQL_UPDATE`, `SQL_DELETE`, `EXPLAIN_SQL` (and any future SQL form) — carry `help_id: None` in the grammar tree. Per the comment at `src/dsl/grammar/mod.rs:915-918`, this is a **deduplication mechanism for the `help` command's list**: they share an entry word with a simple sibling, and `note_help` has no dedup, so giving them a `help_id` would print the same command twice in the `help` list. So the collapse was a deliberate *list-formatting* choice, **not** a decision that advanced SQL forms need no distinct help content. As a side effect, `help <sql-form>` (e.g. `help select`) has no `help.<id>` block to resolve to. Note: the **parse-error / usage layer already distinguishes them** — ADR-0042 (H1a) §"the advanced usage block shows every form" renders each form's usage on a parse error. So only the `help` command lags. ## Why now Surfaced while scoping **H2 / `hint`** (ADR-0053). H2 sidesteps this by keying tier-3 hint content on a new dedicated `hint_id` (one per command form, simple and advanced, each syntactically correct), rather than on `help_id`. That fixes the *hint* surface but leaves the *help* surface unchanged — hence this separate issue. `help` is shipped, ADR-backed (ADR-0021/0023/0024) territory and deserves its own decision rather than a silent rider on the hint ADR. ## Scope to decide - [ ] Confirm current behaviour: what does `help select` / `help` (advanced mode) actually produce for the SQL forms today? - [ ] Decide whether advanced-SQL forms should have distinct `help` content, and if so how to key it without re-introducing duplicate entries in the `help` list (e.g. dedup by entry word + mode, or a distinct help key rendered only in advanced mode). - [ ] Keep consistent with the H2 `hint_id` approach (ADR-0053) so the two contextual-help surfaces don't diverge. ## Notes - Likely a small change once the keying decision is made. - Pedagogy-relevant: advanced mode is for students moving to raw SQL, so accurate SQL-form help matters there specifically.

claude-clouddev1 added the enhancement label 2026-06-14 23:00:32 +01:00

oli referenced this issue from a commit

2026-06-15 17:02:09 +01:00

docs(adr): ADR-0053 — contextual `hint` command + F1 keybinding (H2)

claude-clouddev1 commented

2026-06-22 19:47:02 +01:00

Fixed (committed to main, not yet pushed).

Decisions (confirmed with the maintainer): (1) help <topic> shows both the simple and the advanced SQL form for a shared entry word, mode-blind; (2) select/with get help pages and are listed too; (3) the help list is split by mode.

Fix. All six advanced SQL forms (SELECT, WITH, SQL_INSERT, SQL_UPDATE, SQL_DELETE, EXPLAIN_SQL) now carry distinct help_ids (data.select, data.with, data.sql_insert, …) with hand-curated help.data.* pages. Because the ids are distinct strings, the no_two_registered_commands_share_a_help_id invariant is untouched, and:

help <topic> shows every form sharing the entry word — help insert now shows the simple block and the sql_insert block (like help create already did); advanced-only help select / help with resolve instead of the unknown-topic note. note_help_topic needed no code change.
note_help groups the list by CommandCategory: app-lifecycle commands first (unlabelled), then a "Simple-mode commands:" section and an "Advanced-mode (SQL) commands:" section.

Bonus copy-rule fix. The old list header "DSL data commands (in simple mode):" violated the no-"DSL" copy rule and mis-labelled the advanced SQL forms it already contained as simple mode. The split headers fix both; the full help output no longer contains "DSL".

Tests (red→green): help_command::{help_select_renders_the_sql_select_block, help_with_renders_the_cte_block, help_insert_shows_both_simple_and_sql_forms, help_list_splits_simple_and_advanced_sections}. Full suite green (2525 passed / 0 failed / 1 ignored), clippy + fmt clean. Recorded as ADR-0024 Amendment 1.

Fixed (committed to `main`, not yet pushed). **Decisions** (confirmed with the maintainer): (1) `help <topic>` shows both the simple and the advanced SQL form for a shared entry word, mode-blind; (2) `select`/`with` get help pages and are listed too; (3) the `help` list is split by mode. **Fix.** All six advanced SQL forms (`SELECT`, `WITH`, `SQL_INSERT`, `SQL_UPDATE`, `SQL_DELETE`, `EXPLAIN_SQL`) now carry **distinct `help_id`s** (`data.select`, `data.with`, `data.sql_insert`, …) with hand-curated `help.data.*` pages. Because the ids are distinct strings, the `no_two_registered_commands_share_a_help_id` invariant is untouched, and: - `help <topic>` shows every form sharing the entry word — `help insert` now shows the simple block **and** the `sql_insert` block (like `help create` already did); advanced-only `help select` / `help with` resolve instead of the unknown-topic note. `note_help_topic` needed **no** code change. - `note_help` groups the list by `CommandCategory`: app-lifecycle commands first (unlabelled), then a **"Simple-mode commands:"** section and an **"Advanced-mode (SQL) commands:"** section. **Bonus copy-rule fix.** The old list header `"DSL data commands (in simple mode):"` violated the no-"DSL" copy rule *and* mis-labelled the advanced SQL forms it already contained as simple mode. The split headers fix both; the full `help` output no longer contains "DSL". **Tests** (red→green): `help_command::{help_select_renders_the_sql_select_block, help_with_renders_the_cte_block, help_insert_shows_both_simple_and_sql_forms, help_list_splits_simple_and_advanced_sections}`. Full suite green (2525 passed / 0 failed / 1 ignored), clippy + fmt clean. Recorded as **ADR-0024 Amendment 1**.

claude-clouddev1 closed this issue

2026-06-22 19:47:03 +01:00

oli referenced this issue from a commit

2026-06-22 20:54:17 +01:00

docs(handoff-76): tee up the open issues as the next session's focus

oli referenced this issue from a commit

2026-06-22 20:54:17 +01:00

feat(help): distinct help for advanced-mode SQL forms; split list by mode (#36)

oli referenced this issue from a commit

2026-06-22 20:54:17 +01:00

docs(handoff-78): record the #36 help fix and the value.rs DSL finding

Sign in to join this conversation.