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
+74
View File
@@ -115,6 +115,80 @@ fn help_create_covers_every_form_sharing_the_entry_word() {
);
}
// ----- issue #36: advanced-mode SQL forms get distinct help content -----
#[test]
fn help_select_renders_the_sql_select_block() {
// `select` is advanced-only (no simple sibling) and used to have
// `help_id: None`, so `help select` produced the unknown-topic note.
// It now carries its own help page.
let out = output_for("help select");
let joined = out.join("\n").to_lowercase();
assert!(
joined.contains("select") && joined.contains("from"),
"help select shows the SQL select form: {out:?}",
);
assert!(
!out.iter().any(|l| l.contains("No help for")),
"help select resolves to content, not the unknown-topic note: {out:?}",
);
}
#[test]
fn help_with_renders_the_cte_block() {
let out = output_for("help with");
let joined = out.join("\n").to_lowercase();
assert!(
joined.contains("with") && joined.contains("as ("),
"help with shows the CTE form: {out:?}",
);
assert!(
!out.iter().any(|l| l.contains("No help for")),
"help with resolves to content: {out:?}",
);
}
#[test]
fn help_insert_shows_both_simple_and_sql_forms() {
// `help insert` now covers the simple form AND the advanced SQL form
// (two clearly-labelled blocks, like `help create` already does).
let out = output_for("help insert");
let joined = out.join("\n").to_lowercase();
assert!(
joined.contains("insert into"),
"simple insert form shown: {out:?}",
);
assert!(
joined.contains("advanced"),
"advanced SQL insert form shown alongside the simple one: {out:?}",
);
}
#[test]
fn help_list_splits_simple_and_advanced_sections() {
let out = output_for("help");
let joined = out.join("\n");
assert!(
out.iter().any(|l| l.contains("Simple-mode commands")),
"simple-mode section header present: {out:?}",
);
assert!(
out.iter()
.any(|l| l.contains("Advanced-mode") && l.contains("SQL")),
"advanced-mode (SQL) section header present: {out:?}",
);
// Copy rule: never say "DSL" in user-facing text (the old header did).
assert!(
!joined.contains("DSL"),
"help output must not contain 'DSL': {out:?}",
);
// The advanced query commands are now discoverable in the list.
assert!(
joined.to_lowercase().contains("select"),
"select is listed in help: {out:?}",
);
}
#[test]
fn help_types_renders_the_type_reference() {
let out = output_for("help types");