Merge branch 'main' into teamy-positional-bug

Author: TeamDman

crates/figue/src/driver.rs

@@ -419,6 +419,72 @@ impl<T: Facet<'static>> Driver<T> {
                 return DriverOutcome::err(DriverError::Help { text: help });
             }
 
+            // Check if the only missing field is a subcommand with available variants
+            // (covers nested subcommands like `tracey query` missing a sub-subcommand)
+            let missing_subcommand_with_variants = !has_unknown
+                && missing_fields.len() == 1
+                && !missing_fields[0].available_subcommands.is_empty();
+
+            if missing_subcommand_with_variants {
+                let field = &missing_fields[0];
+
+                // Format the available subcommands list
+                let items: Vec<(String, Option<&str>)> = field
+                    .available_subcommands
+                    .iter()
+                    .map(|sub| (sub.name.clone(), sub.doc.as_deref()))
+                    .collect();
+
+                // Find max width for alignment
+                let max_width = items.iter().map(|(name, _)| name.len()).max().unwrap_or(0);
+                let mut cmds = String::new();
+                for (name, doc) in &items {
+                    use std::fmt::Write;
+                    write!(cmds, "  {name}").unwrap();
+                    let padding = max_width.saturating_sub(name.len());
+                    for _ in 0..padding {
+                        cmds.push(' ');
+                    }
+                    if let Some(doc) = doc {
+                        write!(cmds, "  {}", doc.trim()).unwrap();
+                    }
+                    cmds.push('\n');
+                }
+
+                let mut diagnostics = vec![Diagnostic {
+                    message: format!(
+                        "expected a subcommand\n\navailable subcommands:\n{}",
+                        cmds.trim_end()
+                    ),
+                    label: None,
+                    path: None,
+                    span: None,
+                    severity: Severity::Error,
+                }];
+
+                // Add help hint if the schema has a help field
+                if self.config.schema.special().help.is_some() {
+                    diagnostics.push(Diagnostic {
+                        message: "Run with --help for usage information.".to_string(),
+                        label: None,
+                        path: None,
+                        span: None,
+                        severity: Severity::Note,
+                    });
+                }
+
+                return DriverOutcome::err(DriverError::Failed {
+                    report: Box::new(DriverReport {
+                        diagnostics,
+                        layers,
+                        file_resolution,
+                        overrides,
+                        cli_args_source: cli_args_display.to_string(),
+                        source_name: "<cli>".to_string(),
+                    }),
+                });
+            }
+
             // Check if all missing fields are simple CLI arguments (not config fields)
             // Use the proper kind field to distinguish between CLI args and config fields
             let all_cli_missing = has_missing

crates/figue/src/missing.rs

@@ -42,6 +42,15 @@ pub enum MissingFieldKind {
     ConfigField,
 }
 
+/// A available subcommand name and its doc summary.
+#[derive(Debug, Clone)]
+pub struct AvailableSubcommand {
+    /// CLI name (kebab-case)
+    pub name: String,
+    /// Doc summary if available
+    pub doc: Option<String>,
+}
+
 /// Information about a missing required field.
 #[derive(Debug, Clone)]
 pub struct MissingFieldInfo {
@@ -61,6 +70,9 @@ pub struct MissingFieldInfo {
     pub env_aliases: Vec<String>,
     /// What kind of field this is - determines error formatting strategy
     pub kind: MissingFieldKind,
+    /// If this field is a subcommand, the available subcommands.
+    /// Non-empty only when the missing field is a subcommand field.
+    pub available_subcommands: Vec<AvailableSubcommand>,
 }
 
 /// Information about a corrected command with missing arguments for display.
@@ -189,6 +201,7 @@ pub fn collect_missing_fields(
                     env_var: None,
                     env_aliases: Vec::new(),
                     kind: MissingFieldKind::ConfigField,
+                    available_subcommands: Vec::new(),
                 });
             }
         } else {
@@ -230,6 +243,7 @@ fn collect_missing_in_arg_level(
                 env_var: None, // CLI args don't have env vars
                 env_aliases: Vec::new(),
                 kind: MissingFieldKind::CliArg,
+                available_subcommands: Vec::new(),
             });
         }
     }
@@ -243,6 +257,16 @@ fn collect_missing_in_arg_level(
             } else {
                 format!("{}.{}", path_prefix, subcommand_field)
             };
+
+            let available_subcommands: Vec<AvailableSubcommand> = arg_level
+                .subcommands()
+                .iter()
+                .map(|(_, sub)| AvailableSubcommand {
+                    name: sub.cli_name().to_string(),
+                    doc: sub.docs().summary().map(|s| s.to_string()),
+                })
+                .collect();
+
             missing.push(MissingFieldInfo {
                 field_name: subcommand_field.to_string(),
                 field_path,
@@ -252,6 +276,7 @@ fn collect_missing_in_arg_level(
                 env_var: None,
                 env_aliases: Vec::new(),
                 kind: MissingFieldKind::CliArg,
+                available_subcommands,
             });
         } else if let Some(ConfigValue::Enum(sourced)) = obj_map.get(subcommand_field) {
             // Subcommand is present - recursively check its arguments
@@ -411,6 +436,7 @@ fn collect_missing_in_config_value(
                                     env_var: None,
                                     env_aliases: field_schema.env_aliases().to_vec(),
                                     kind: MissingFieldKind::ConfigField,
+                                    available_subcommands: Vec::new(),
                                 });
                             }
                         }
@@ -493,6 +519,7 @@ fn check_missing_field(
             env_var,
             env_aliases: field_schema.env_aliases().to_vec(),
             kind: MissingFieldKind::ConfigField,
+            available_subcommands: Vec::new(),
         });
     }
 }

crates/figue/tests/integration/snapshots/main__integration__subcommand__missing_nested_subcommand_error.snap

@@ -1,11 +1,8 @@
 ---
 source: crates/figue/tests/integration/subcommand.rs
-expression: "$crate :: common :: strip_ansi(& err.to_string())"
+expression: "strip_ansi_escapes :: strip_str(& err.to_string())"
 ---
-Error: missing required argument
-   ╭─[ <suggestion>:1:4 ]
-   │
- 1 │ ci <action>
-   │    ────┬───  
-   │        ╰───── missing required argument
-───╯
+Error: expected a subcommand
+
+available subcommands:
+  generate  Generate CI workflow files from Rust code

crates/figue/tests/integration/snapshots/main__integration__subcommand_errors__nested_subcommand_not_provided.snap

@@ -0,0 +1,14 @@
+---
+source: crates/figue/tests/integration/subcommand_errors.rs
+expression: "strip_ansi_escapes :: strip_str(& err.to_string())"
+---
+Error: expected a subcommand
+
+available subcommands:
+  status     Coverage overview
+  uncovered  List rules without implementation references
+  untested   List rules without verification references
+  unmapped   Show unmapped code units
+  rule       Show details about a specific rule
+  config     Display current configuration
+  validate   Validate the spec and implementation

crates/figue/tests/integration/snapshots/main__integration__subcommand_errors__nested_subcommand_not_provided_with_builtins.snap

@@ -0,0 +1,11 @@
+---
+source: crates/figue/tests/integration/subcommand_errors.rs
+expression: "strip_ansi_escapes :: strip_str(& err.to_string())"
+---
+Error: expected a subcommand
+
+available subcommands:
+  clone  Clone a repository
+  push   Push changes
+  pull   Pull changes
+Note: Run with --help for usage information.

crates/figue/tests/integration/subcommand_errors.rs

@@ -408,3 +408,120 @@ fn test_subcommand_positional_looks_like_flag() {
     let err = figue::from_slice::<Cli>(&["create", "--help"]).unwrap_err();
     assert_diag_snapshot!(err);
 }
+
+// ============================================================================
+// Test Case 11: Nested subcommand not provided (lists available subcommands)
+// ============================================================================
+
+#[test]
+fn test_nested_subcommand_not_provided() {
+    #[derive(Facet, Debug)]
+    struct Cli {
+        #[facet(args::subcommand)]
+        command: Command,
+    }
+
+    #[derive(Facet, Debug)]
+    #[repr(u8)]
+    #[allow(dead_code)]
+    enum Command {
+        /// Query operations
+        Query(QueryArgs),
+        /// Serve the dashboard
+        Serve,
+    }
+
+    #[derive(Facet, Debug)]
+    struct QueryArgs {
+        #[facet(args::subcommand)]
+        action: QueryAction,
+    }
+
+    #[derive(Facet, Debug)]
+    #[repr(u8)]
+    #[allow(dead_code)]
+    enum QueryAction {
+        /// Coverage overview
+        Status,
+        /// List rules without implementation references
+        Uncovered,
+        /// List rules without verification references
+        Untested,
+        /// Show unmapped code units
+        Unmapped,
+        /// Show details about a specific rule
+        Rule(RuleArgs),
+        /// Display current configuration
+        Config,
+        /// Validate the spec and implementation
+        Validate,
+    }
+
+    #[derive(Facet, Debug)]
+    struct RuleArgs {
+        /// Rule ID to look up
+        #[facet(args::positional)]
+        rule_id: String,
+    }
+
+    // User types: "cli query" without specifying which query subcommand
+    // Should list the available subcommands for the query level
+    let err = figue::from_slice::<Cli>(&["query"]).unwrap_err();
+    assert_diag_snapshot!(err);
+}
+
+// ============================================================================
+// Test Case 12: Nested subcommand not provided (with FigueBuiltins)
+// ============================================================================
+
+#[test]
+fn test_nested_subcommand_not_provided_with_builtins() {
+    #[derive(Facet, Debug)]
+    struct Cli {
+        #[facet(args::subcommand)]
+        command: Command,
+
+        #[facet(flatten)]
+        builtins: args::FigueBuiltins,
+    }
+
+    #[derive(Facet, Debug)]
+    #[repr(u8)]
+    #[allow(dead_code)]
+    enum Command {
+        /// Repository operations
+        Repo(RepoArgs),
+        /// Build the project
+        Build,
+    }
+
+    #[derive(Facet, Debug)]
+    struct RepoArgs {
+        #[facet(args::subcommand)]
+        action: RepoAction,
+    }
+
+    #[derive(Facet, Debug)]
+    #[repr(u8)]
+    #[allow(dead_code)]
+    enum RepoAction {
+        /// Clone a repository
+        Clone(CloneArgs),
+        /// Push changes
+        Push,
+        /// Pull changes
+        Pull,
+    }
+
+    #[derive(Facet, Debug)]
+    struct CloneArgs {
+        /// Repository URL
+        #[facet(args::positional)]
+        url: String,
+    }
+
+    // User types: "cli repo" without specifying which repo action
+    // Should list clone, push, pull as available subcommands
+    let err = figue::from_slice::<Cli>(&["repo"]).unwrap_err();
+    assert_diag_snapshot!(err);
+}