Pressing F1 while the cursor sits inside a recognized clause now adds an "About this clause" teaching block beneath the per-form command hint — for referential actions (on delete/on update), 1:n/m:n cardinality, primary key, unique, check, and foreign key (seven topics). The example shown is mode-correct for the mode you're in.
How
New transparent Node::Concept { topic, inner } grammar wrapper records each clause's byte-span into WalkContext::concept_spans — append-only, so it survives the clause being fully matched (unlike pending_hint_mode, which clears on match and therefore only knows the slot boundary).
concept_topic_at_cursor walks the full buffer and returns the innermost span containing the cursor (so on delete inside a references … on delete resolves to the narrower referential_actions). No use of the dormant WalkBound::Position.
Review (per ADR-0059: paste the /runda audit trail)
User forks: detection = "anywhere inside the clause" (not just the slot boundary); all four clause families in v1; mode-keyed examples (vs split blocks).
/runda caught two design gaps before any code was written, both fixed: the clause map originally missed the simple-mode constraint suffix (ADR-0029), and the single-example model collided with D6's mode-correct rule.
Comprehensiveness gate: a recursive Node::Concept visitor cross-checks grammar wrappers ↔ CONCEPT_TOPICS ↔ catalogue blocks, so a wrapper or block can't drift out of sync.
Tests
21 new (14 resolver unit, 3 comprehensiveness gates, 3 F1 integration, 1 snapshot). Full suite green across all tiers (1831 lib / 8 e2e_pty / 503 it / 200 typing; 0 failed, 1 ignored — unchanged from baseline); cargo fmt --check + clippy --all-targets -- -D warnings clean via nix develop.
This branch's ADR forward-references ADR-0059 (the working-method PR); merge order doesn't matter (0059 is already reserved). Whichever of the two PRs merges second hits a one-line README.md index conflict (the 0058 vs 0059 row) — resolve by keeping both in numeric order.
Implements **issue #37** — clause-concept hints, the deferred ADR-0053 extension. Closes #37.
## What
Pressing **F1** while the cursor sits *inside a recognized clause* now adds an "About this clause" teaching block beneath the per-form command hint — for referential actions (`on delete`/`on update`), `1:n`/`m:n` cardinality, primary key, unique, check, and foreign key (seven topics). The example shown is mode-correct for the mode you're in.
## How
- New transparent `Node::Concept { topic, inner }` grammar wrapper records each clause's byte-span into `WalkContext::concept_spans` — append-only, so it **survives the clause being fully matched** (unlike `pending_hint_mode`, which clears on match and therefore only knows the slot boundary).
- `concept_topic_at_cursor` walks the full buffer and returns the **innermost** span containing the cursor (so `on delete` inside a `references … on delete` resolves to the narrower `referential_actions`). No use of the dormant `WalkBound::Position`.
- Mode-keyed examples (`example.simple` / `example.advanced`) honour ADR-0053 D6's mode-correct-example rule.
Decision recorded in **ADR-0058**.
## Review (per ADR-0059: paste the /runda audit trail)
- **User forks:** detection = "anywhere inside the clause" (not just the slot boundary); **all four clause families** in v1; **mode-keyed examples** (vs split blocks).
- **/runda caught two design gaps before any code was written**, both fixed: the clause map originally missed the simple-mode constraint suffix (ADR-0029), and the single-`example` model collided with D6's mode-correct rule.
- **Comprehensiveness gate:** a recursive `Node::Concept` visitor cross-checks grammar wrappers ↔ `CONCEPT_TOPICS` ↔ catalogue blocks, so a wrapper or block can't drift out of sync.
## Tests
21 new (14 resolver unit, 3 comprehensiveness gates, 3 F1 integration, 1 snapshot). Full suite green across all tiers (**1831** lib / 8 e2e_pty / 503 it / 200 typing; 0 failed, 1 ignored — unchanged from baseline); `cargo fmt --check` + `clippy --all-targets -- -D warnings` clean via `nix develop`.
---
> This branch's ADR forward-references ADR-0059 (the working-method PR); merge order doesn't matter (0059 is already reserved). Whichever of the two PRs merges **second** hits a one-line `README.md` index conflict (the `0058` vs `0059` row) — resolve by keeping both in numeric order.
Add a hint.concept.* tier-3 layer surfaced when the cursor sits inside a
recognized clause (referential actions, 1:n/m:n cardinality, primary key,
unique, check, foreign key), layered beneath the per-form block. New
Node::Concept grammar wrapper records clause byte-spans; concept_topic_at_cursor
resolves the innermost containing span. Examples are mode-keyed so they stay
syntax-correct in both simple and advanced mode. Draft ADR (number at merge).
Rename the placeholder draft to its reserved number (0058, allocated
reserve-first via the new dev-workflow flow), drop the ADR-XXXX
placeholders, and add the README index row.
The Gitea "Update branch" button merged main into the PR branch server-side
(8ccecc4) — auto-resolving the README conflict by dropping the ADR-0059 index
row, and predating #43. The local merge (ec7a8ff) merged current main correctly
(both 0058 + 0059 rows; includes #43). This merge absorbs the stale remote
commit without changing content — the resulting tree is identical to the
correct local tip — so a normal (non-force) push now fast-forwards origin/feat.
oli
merged commit 6e28e58e45 into main2026-06-23 23:24:30 +01:00
oli
deleted branch feat/clause-concept-hints2026-06-23 23:24:30 +01:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Implements issue #37 — clause-concept hints, the deferred ADR-0053 extension. Closes #37.
What
Pressing F1 while the cursor sits inside a recognized clause now adds an "About this clause" teaching block beneath the per-form command hint — for referential actions (
on delete/on update),1:n/m:ncardinality, primary key, unique, check, and foreign key (seven topics). The example shown is mode-correct for the mode you're in.How
Node::Concept { topic, inner }grammar wrapper records each clause's byte-span intoWalkContext::concept_spans— append-only, so it survives the clause being fully matched (unlikepending_hint_mode, which clears on match and therefore only knows the slot boundary).concept_topic_at_cursorwalks the full buffer and returns the innermost span containing the cursor (soon deleteinside areferences … on deleteresolves to the narrowerreferential_actions). No use of the dormantWalkBound::Position.example.simple/example.advanced) honour ADR-0053 D6's mode-correct-example rule.Decision recorded in ADR-0058.
Review (per ADR-0059: paste the /runda audit trail)
examplemodel collided with D6's mode-correct rule.Node::Conceptvisitor cross-checks grammar wrappers ↔CONCEPT_TOPICS↔ catalogue blocks, so a wrapper or block can't drift out of sync.Tests
21 new (14 resolver unit, 3 comprehensiveness gates, 3 F1 integration, 1 snapshot). Full suite green across all tiers (1831 lib / 8 e2e_pty / 503 it / 200 typing; 0 failed, 1 ignored — unchanged from baseline);
cargo fmt --check+clippy --all-targets -- -D warningsclean vianix develop.