diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b7d4b5..1b5ed22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added +- Pressing **F1** while the cursor sits inside a clause now adds a short + "About this clause" explanation beneath the command hint — covering + referential actions (`on delete`/`on update`), one-to-many and + many-to-many relationships, primary keys, unique and check constraints, + and foreign keys. The example shown matches whichever mode you're in. - `help` now covers the advanced-mode SQL commands: `help select`, `help with`, and the SQL forms of `insert` / `update` / `delete` / `explain` show their own syntax, and the full command list is grouped into "Simple-mode commands" and diff --git a/docs/adr/draft-clause-concept-hints.md b/docs/adr/draft-clause-concept-hints.md new file mode 100644 index 0000000..810e6b3 --- /dev/null +++ b/docs/adr/draft-clause-concept-hints.md @@ -0,0 +1,462 @@ +# ADR-XXXX: Clause-concept hints — a `hint.concept.*` layer surfaced by cursor position (issue #37) + +## Status + +Draft — **implemented 2026-06-23** on branch `feat/clause-concept-hints` +(pending merge). Number assigned at merge-to-`main` per ADR-0000 +"Numbering discipline" (drafted under `draft-clause-concept-hints.md` / +`ADR-XXXX`; README index entry added at merge). Extends **ADR-0053** +(contextual `hint`, D3/D4) additively; does not supersede it. Closes the +deferred extension tracked as Gitea issue **#37**. + +Implementation: `Node::Concept { topic, inner }` (`dsl/grammar/mod.rs`) + +the span-recording driver arm (`dsl/walker/driver.rs`) + +`WalkContext::concept_spans` / `ConceptSpan` (`dsl/walker/context.rs`); +the `concept_topic_at_cursor` resolver (`dsl/walker/mod.rs`); 10 +`Node::Concept` wrappers across `shared.rs` / `ddl.rs` / +`sql_create_table.rs` (one shared `REFERENTIAL_CLAUSES`, two extracted +cardinality sub-`Seq`s); the mode-keyed `emit_tier3_block` + +`note_hint_for_input` layering (`app.rs`); the seven `hint.concept.*` +blocks + `hint.block.concept_heading` (`strings/en-US.yaml`) with +`keys.rs` declarations; and the test set (14 resolver unit tests, 3 +comprehensiveness gates incl. the recursive `Node::Concept` visitor, 3 F1 +integration tests, the `hint_block_with_concept` snapshot). Suite green +across all tiers; `fmt`/`clippy` clean. + +Revised after a `/runda` review (2026-06-22) that grounded the mechanism +against the code and caught two design gaps: the clause mapping (D4) +covered only the advanced-SQL constraint grammar and missed the +simple-mode constraint suffix (ADR-0029); and the single-`example` +content model collided with ADR-0053 D6's mode-correct-example rule for +topics reachable in both modes. Both are resolved here — D4 now maps both +grammars, and D5 adopts **mode-keyed examples** (user decision, +2026-06-22). + +References ADR-0053 (the three-tier `hint` model + the `hint.cmd.*` / +`hint.err.*` corpus), ADR-0024 (the unified grammar/walker, `HintMode`- +per-node, `MatchedPath` spans), ADR-0022 (ambient tier-2 typing +assistance), ADR-0013/0045 (the relationship + `m:n` grammar), ADR-0035 +(advanced-mode `CREATE TABLE` constraint grammar). + +## Context + +ADR-0053 delivers tier-3 teaching hints at **per-form** granularity: one +`hint.cmd.