feat: H3 help <command> per-command detail + general reference

HELP node takes an optional single-word topic (BarePath);
AppCommand::Help { topic }. note_help_topic renders the help
block(s) of every command sharing that entry word (so `help
create` covers both create forms), plus `help types` and a
friendly "no help for X" pointer for unknown topics. Full help
gains a detail-hint footer. Catalogued help.detail_hint /
help.unknown_topic; parse-error matrix updated (help now takes a
topic, so the near-miss is the multi-word case). 9 integration
tests in tests/it/help_command.rs. Mark H3 [x].
This commit is contained in:
claude@clouddev1
2026-06-07 13:32:18 +00:00
parent 8dec784080
commit 757711f2bf
12 changed files with 247 additions and 26 deletions
+15 -3
View File
@@ -80,6 +80,11 @@ const IMPORT_PATH_AND_TARGET: Node = Node::Seq(&[Node::BarePath, IMPORT_AS_TARGE
const EXPORT_PATH_OPT: Node = Node::Optional(&Node::BarePath);
const IMPORT_BODY_OPT: Node = Node::Optional(&IMPORT_PATH_AND_TARGET);
// `help [<topic>]` (H3): an optional single-word topic — a command
// entry word (`insert`, `create`, `show`, …) or `types`. Captured
// as a `BarePath` so any keyword-shaped word is accepted verbatim.
const HELP_TOPIC_OPT: Node = Node::Optional(&Node::BarePath);
// `mode <value>`: known keywords are surfaced as `Word` children
// so they appear in the walker's expected set (and feed the
// completion engine's keyword candidates). The trailing `Ident`
@@ -154,8 +159,15 @@ const fn build_quit(_path: &MatchedPath, _source: &str) -> Result<Command, Valid
Ok(Command::App(AppCommand::Quit))
}
const fn build_help(_path: &MatchedPath, _source: &str) -> Result<Command, ValidationError> {
Ok(Command::App(AppCommand::Help))
fn build_help(path: &MatchedPath, _source: &str) -> Result<Command, ValidationError> {
// Optional single-word topic (a command entry word, or
// `types`) captured as a `BarePath` — `help insert`,
// `help create`, `help show`. Multi-word commands share an
// entry word, so `help create` covers every create form.
let topic = path
.find(|i| matches!(i.kind, MatchedKind::BarePath))
.map(|i| i.text.clone());
Ok(Command::App(AppCommand::Help { topic }))
}
const fn build_rebuild(_path: &MatchedPath, _source: &str) -> Result<Command, ValidationError> {
@@ -255,7 +267,7 @@ pub static QUIT: CommandNode = CommandNode {
pub static HELP: CommandNode = CommandNode {
entry: Word::keyword("help"),
shape: EMPTY_SEQ,
shape: HELP_TOPIC_OPT,
ast_builder: build_help,
help_id: Some("app.help"),
usage_ids: &["parse.usage.help"],};