Preserve root context in subcommand help; split MissingOption error

Fourth codex pass:

- dispatch: subcommand help now shows the full invocation context. The
  new `compose_help_schema` walks the root → subcommand path and
  produces a help-only schema named e.g. `git clone` with the root's
  global options merged into the subcommand's own. Users copying the
  usage line get a string that actually parses.

- error/parser: add Error::MissingOption for required options that
  were never typed. ParseResult::require now chooses the variant based
  on the name shape — dash-prefixed → MissingOption, else
  MissingArgument. Commands that make an option mandatory via
  `require::<T>("--num")` now get a diagnostic mentioning the option
  rather than a phantom positional.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: xerial

runi-cli/src/launcher/dispatch.rs

@@ -183,7 +183,8 @@ fn report_error(err: Error, root: &CommandSchema) -> i32 {
             0
         }
         Error::InSubcommand { path, source } => {
-            let schema = resolve_schema(root, &path).unwrap_or(root);
+            let composed = compose_help_schema(root, &path);
+            let schema = composed.as_ref().unwrap_or(root);
             match *source {
                 Error::HelpRequested => {
                     HelpPrinter::print(schema);
@@ -204,12 +205,24 @@ fn report_error(err: Error, root: &CommandSchema) -> i32 {
     }
 }
 
-fn resolve_schema<'a>(root: &'a CommandSchema, path: &[String]) -> Option<&'a CommandSchema> {
+/// Build a help-only schema that represents `root ... path` as a single
+/// command, so the usage line reads e.g. `git clone [OPTIONS] <url>` and
+/// includes the root's global options alongside the subcommand's own. The
+/// returned schema is only suitable for help printing — it is not used for
+/// parsing.
+fn compose_help_schema(root: &CommandSchema, path: &[String]) -> Option<CommandSchema> {
+    let mut options = root.options.clone();
     let mut schema = root;
+    let mut parts = vec![root.name.clone()];
     for name in path {
         schema = schema.subcommands.iter().find(|s| s.name == *name)?;
+        options.extend(schema.options.iter().cloned());
+        parts.push(name.clone());
     }
-    Some(schema)
+    let mut composed = schema.clone();
+    composed.name = parts.join(" ");
+    composed.options = options;
+    Some(composed)
 }
 
 fn env_args() -> Vec<String> {
@@ -449,6 +462,21 @@ mod tests {
         }
     }
 
+    #[test]
+    fn compose_help_schema_prefixes_root_name_and_options() {
+        let root = CommandSchema::new("git", "").flag("-v,--verbose", "Verbose");
+        let sub = CommandSchema::new("clone", "Clone a repo").argument("url", "URL");
+        let mut with_sub = root.clone();
+        with_sub.subcommands.push(sub);
+        let composed =
+            compose_help_schema(&with_sub, &["clone".to_string()]).expect("must resolve");
+        assert_eq!(composed.name, "git clone");
+        // Root's --verbose must appear alongside clone's own options.
+        assert!(composed.options.iter().any(|o| o.matches_long("verbose")));
+        // Clone's own positional must be preserved.
+        assert!(composed.arguments.iter().any(|a| a.name == "url"));
+    }
+
     #[test]
     fn invalid_value_error_is_informative() {
         let launcher = Launcher::<NeedsInt>::of();

runi-cli/src/launcher/error.rs

@@ -10,6 +10,10 @@ pub enum Error {
     },
     MissingValue(String),
     UnexpectedValue(String),
+    /// A required option was not provided at all (distinct from
+    /// `MissingValue`, which fires when the option name was typed without a
+    /// following value).
+    MissingOption(String),
     MissingArgument(String),
     MissingSubcommand {
         available: Vec<String>,
@@ -59,6 +63,7 @@ impl Error {
                 | Error::UnknownSubcommand { .. }
                 | Error::MissingValue(_)
                 | Error::UnexpectedValue(_)
+                | Error::MissingOption(_)
                 | Error::MissingArgument(_)
                 | Error::MissingSubcommand { .. }
                 | Error::ExtraArgument(_)
@@ -82,6 +87,7 @@ impl fmt::Display for Error {
             }
             Error::MissingValue(opt) => write!(f, "missing value for option: {opt}"),
             Error::UnexpectedValue(opt) => write!(f, "option {opt} does not take a value"),
+            Error::MissingOption(name) => write!(f, "missing required option: {name}"),
             Error::MissingArgument(name) => write!(f, "missing required argument: <{name}>"),
             Error::MissingSubcommand { available } => {
                 write!(f, "a subcommand is required")?;

runi-cli/src/launcher/parser.rs

@@ -64,9 +64,20 @@ impl ParseResult {
     }
 
     /// Like [`ParseResult::get`] but errors if the value is missing.
+    ///
+    /// The error variant depends on the name shape: dash-prefixed names
+    /// (e.g. `--num`, `-n`) become `MissingOption`, everything else becomes
+    /// `MissingArgument`. That way a command that marks an option as
+    /// required via `require::<T>("--num")` gets a diagnostic mentioning
+    /// the option, not a positional argument.
     pub fn require<T: FromArg>(&self, name: &str) -> Result<T> {
-        self.get::<T>(name)?
-            .ok_or_else(|| Error::MissingArgument(name.to_string()))
+        self.get::<T>(name)?.ok_or_else(|| {
+            if name.starts_with('-') {
+                Error::MissingOption(name.to_string())
+            } else {
+                Error::MissingArgument(name.to_string())
+            }
+        })
     }
 
     /// Get all values supplied for a repeatable option.
@@ -347,6 +358,23 @@ mod tests {
         assert!(matches!(err, Error::MissingArgument(ref n) if n == "file"));
     }
 
+    #[test]
+    fn require_on_missing_option_reports_missing_option() {
+        let schema = CommandSchema::new("app", "").option("--num", "");
+        let r = OptionParser::parse(&schema, &args(&[])).unwrap();
+        let err = r.require::<u32>("--num").unwrap_err();
+        assert!(matches!(err, Error::MissingOption(ref n) if n == "--num"));
+    }
+
+    #[test]
+    fn require_on_missing_positional_reports_missing_argument() {
+        // Mirror of the above: positional uses MissingArgument.
+        let schema = CommandSchema::new("app", "").optional_argument("file", "");
+        let r = OptionParser::parse(&schema, &args(&[])).unwrap();
+        let err = r.require::<String>("file").unwrap_err();
+        assert!(matches!(err, Error::MissingArgument(ref n) if n == "file"));
+    }
+
     #[test]
     fn optional_argument_absent_is_ok() {
         let schema = CommandSchema::new("app", "").optional_argument("out", "output");