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

The six advanced SQL DML/query forms (SELECT, WITH, SQL_INSERT, SQL_UPDATE,
SQL_DELETE, EXPLAIN_SQL) carried help_id: None, so `help select`/`help with`
resolved to nothing and `help insert` showed only the simple form. Give each
its own distinct help_id (data.select, data.sql_insert, …) with a hand-curated
help.data.* page. Distinct strings keep the dedup invariant intact, and
note_help_topic needs no change — `help insert` now shows the simple block and
the sql_insert block (like `help create` already did), and the advanced-only
forms resolve.

note_help now groups the list by CommandCategory: app-lifecycle commands first
(unlabelled), then "Simple-mode commands:" and "Advanced-mode (SQL) commands:"
sections — replacing the old single "DSL data commands (in simple mode):"
header, which used the banned "DSL" term and mis-labelled the advanced SQL
forms it already contained.

Four new help_command tests (red→green). Recorded as ADR-0024 Amendment 1;
CHANGELOG updated.
This commit is contained in:
claude@clouddev1
2026-06-22 19:01:27 +00:00
parent e88fa79f09
commit 3ad4affef2
9 changed files with 223 additions and 41 deletions
+35 -17
View File
@@ -3047,34 +3047,52 @@ impl App {
/// output panel.
///
/// Assembled from the command REGISTRY (ADR-0024 §help_id):
/// the framing (`help.intro`, `help.dsl_section`,
/// `help.types_reference`) comes from the catalog, and each
/// command's body is the catalog entry named by its
/// `help_id`. A newly-registered command appears here
/// automatically — no edit to this function or a hand-kept
/// the framing (`help.intro`, `help.simple_section`,
/// `help.advanced_section`, `help.types_reference`) comes from
/// the catalog, and each command's body is the catalog entry
/// named by its `help_id`. A newly-registered command appears
/// here automatically — no edit to this function or a hand-kept
/// list. Each catalog line becomes its own `OutputLine` so
/// the scroll-position math (one logical line = one display
/// row) stays accurate per the renderer's invariant.
///
/// Issue #36: the commands group by mode. App-lifecycle commands
/// (`help_id` in the `app.*` namespace) work in either mode and
/// list first, unlabelled, under the intro. The rest split by
/// [`CommandCategory`] into a simple-mode group and an
/// advanced-mode (SQL) group — replacing the old single "DSL data
/// commands (in simple mode)" header, which both used the banned
/// "DSL" term and wrongly claimed simple mode for the advanced SQL
/// forms the section already contained.
fn note_help(&mut self) {
use crate::dsl::grammar::REGISTRY;
use crate::dsl::grammar::{CommandCategory, REGISTRY};
let mut lines: Vec<String> = Vec::new();
lines.push(crate::t!("help.intro"));
// REGISTRY is ordered app-commands first; emit the
// "DSL data commands" sub-header at the first command
// whose help_id leaves the `app.` namespace.
let mut dsl_header_done = false;
for (command, _category) in REGISTRY {
let mut simple: Vec<String> = Vec::new();
let mut advanced: Vec<String> = Vec::new();
for (command, category) in REGISTRY {
let Some(help_id) = command.help_id else {
continue;
};
if !dsl_header_done && !help_id.starts_with("app.") {
lines.push(crate::t!("help.dsl_section"));
dsl_header_done = true;
let body = crate::friendly::translate(&format!("help.{help_id}"), &[]);
let block: Vec<String> = body.lines().map(str::to_string).collect();
if help_id.starts_with("app.") {
lines.extend(block);
} else if matches!(category, CommandCategory::Advanced) {
advanced.extend(block);
} else {
simple.extend(block);
}
let key = format!("help.{help_id}");
let body = crate::friendly::translate(&key, &[]);
lines.extend(body.lines().map(str::to_string));
}
if !simple.is_empty() {
lines.push(crate::t!("help.simple_section"));
lines.extend(simple);
}
if !advanced.is_empty() {
lines.push(crate::t!("help.advanced_section"));
lines.extend(advanced);
}
lines.extend(
crate::t!("help.types_reference")