wip

Author: wanguardd

module/move/unilang/spec.md

@@ -511,6 +511,26 @@ The unilang framework **must** provide control over debug output and verbosity l
     - Runtime configuration
 *   **Thread Safety**: Verbosity control **must** be thread-safe and respect per-instance settings in multi-threaded environments.
 
+#### 9.5. Help System Formatting
+
+The help system **must** provide clear, readable output that is optimized for human consumption and easy scanning.
+
+*   **Multi-line Format**: Command help output **must** use a multi-line format that separates different types of information visually:
+    - Command header line with name and version
+    - Description section with proper spacing
+    - Arguments section with clear visual hierarchy
+*   **Argument Display**: Each argument **must** be displayed with:
+    - Argument name on its own line or prominently displayed
+    - Type and requirement status clearly indicated
+    - Description text separated from technical details
+    - Optional and multiple indicators separated from core information
+*   **Readability Principles**: Help text **must** follow these formatting principles:
+    - No single line should contain more than 80 characters when possible
+    - Technical information (Kind, validation rules) should be visually distinct from user-facing descriptions
+    - Redundant words like "Hint:" should be eliminated when the context is clear
+    - Visual hierarchy should guide the eye from most important to least important information
+*   **Consistent Spacing**: The help system **must** use consistent indentation and spacing to create visual groupings and improve readability.
+
 ---
 ## Part II: Internal Design (Design Recommendations)
 *This part of the specification describes the recommended internal architecture and implementation strategies. These are best-practice starting points, and the development team has the flexibility to modify them as needed.*

module/move/unilang/src/help.rs

@@ -83,21 +83,49 @@ impl< 'a > HelpGenerator< 'a >
       writeln!( &mut help, "\nArguments:" ).unwrap();
       for arg in &command.arguments
       {
-        let mut arg_info = String::new();
-        write!( &mut arg_info, "{} (Kind: {}) - Hint: {}", arg.name, arg.kind, arg.hint ).unwrap();
-        if arg.attributes.optional
-        {
-          write!( &mut arg_info, ", Optional" ).unwrap();
+        // Improved formatting: Multi-line, clear hierarchy, eliminate redundant text
+        
+        // Argument name on its own line
+        write!( &mut help, "{}", arg.name ).unwrap();
+        
+        // Type and status indicators on separate line with clear formatting
+        write!( &mut help, " (Type: {})", arg.kind ).unwrap();
+        
+        // Add status indicators
+        let mut status_parts = Vec::new();
+        if arg.attributes.optional {
+          status_parts.push("Optional");
         }
-        if arg.attributes.multiple
-        {
-          write!( &mut arg_info, ", Multiple" ).unwrap();
+        if arg.attributes.multiple {
+          status_parts.push("Multiple");
         }
-        if !arg.validation_rules.is_empty()
-        {
-          write!( &mut arg_info, ", Rules: [{}]", arg.validation_rules.iter().map(|r| format!("{r:?}")).collect::<Vec<_>>().join( ", " ) ).unwrap();
+        if !status_parts.is_empty() {
+          write!( &mut help, " - {}", status_parts.join(", ") ).unwrap();
         }
-        writeln!( &mut help, "{arg_info}" ).unwrap();
+        writeln!( &mut help ).unwrap();
+        
+        // Description and hint on separate lines with indentation for readability
+        if !arg.description.is_empty() {
+          writeln!( &mut help, "  {}", arg.description ).unwrap();
+          // If hint is different from description, show it too
+          if !arg.hint.is_empty() && arg.hint != arg.description {
+            writeln!( &mut help, "  ({})", arg.hint ).unwrap();
+          }
+        } else if !arg.hint.is_empty() {
+          writeln!( &mut help, "  {}", arg.hint ).unwrap();
+        }
+        
+        // Validation rules on separate line if present
+        if !arg.validation_rules.is_empty() {
+          writeln!( 
+            &mut help, 
+            "  Rules: [{}]", 
+            arg.validation_rules.iter().map(|r| format!("{r:?}")).collect::<Vec<_>>().join( ", " ) 
+          ).unwrap();
+        }
+        
+        // Empty line between arguments for better separation
+        writeln!( &mut help ).unwrap();
       }
     }
 

module/move/unilang/tests/help_formatting_test.rs

@@ -0,0 +1,260 @@
+//! Tests for help system formatting improvements
+//!
+//! This module tests that help output follows improved formatting principles
+//! for better readability and user experience.
+//!
+//! Bug Coverage: Prevents regression where help output is cramped, hard to read,
+//! or contains redundant information that makes it difficult for users to quickly
+//! understand command usage.
+
+use unilang::prelude::*;
+
+#[test]
+fn test_help_formatting_is_readable()
+{
+  // This test ensures help output follows the improved formatting specification
+  
+  // Create a command with multiple arguments to test formatting
+  let mut registry = CommandRegistry::new();
+  
+  let test_cmd = CommandDefinition {
+    name: "run_file".to_string(),
+    namespace: String::new(),
+    description: "Execute prompts from structured or plain text files".to_string(),
+    hint: "Run prompts from a file (text, YAML, JSON, or TOML)".to_string(),
+    arguments: vec![
+      ArgumentDefinition {
+        name: "file".to_string(),
+        description: "Path to prompt file".to_string(),
+        kind: Kind::File,
+        hint: "Path to prompt file".to_string(),
+        attributes: ArgumentAttributes {
+          optional: false,
+          ..Default::default()
+        },
+        validation_rules: vec![],
+        aliases: vec![],
+        tags: vec!["automation".to_string(), "file".to_string()],
+      },
+      ArgumentDefinition {
+        name: "working_dir".to_string(),
+        description: "Directory to run commands in".to_string(),
+        kind: Kind::Directory,
+        hint: "Directory to run commands in".to_string(),
+        attributes: ArgumentAttributes {
+          optional: true,
+          ..Default::default()
+        },
+        validation_rules: vec![],
+        aliases: vec![],
+        tags: vec![],
+      },
+      ArgumentDefinition {
+        name: "simple".to_string(),
+        description: "Simple mode without session management".to_string(),
+        kind: Kind::Boolean,
+        hint: "Simple mode without session management".to_string(),
+        attributes: ArgumentAttributes {
+          optional: true,
+          ..Default::default()
+        },
+        validation_rules: vec![],
+        aliases: vec![],
+        tags: vec![],
+      },
+    ],
+    routine_link: None,
+    status: "stable".to_string(),
+    version: "0.1.0".to_string(),
+    tags: vec!["automation".to_string(), "file".to_string()],
+    aliases: vec![],
+    permissions: vec![],
+    idempotent: true,
+    deprecation_message: String::new(),
+    http_method_hint: String::new(),
+    examples: vec![],
+  };
+  
+  registry.register(test_cmd);
+  
+  let help_gen = HelpGenerator::new(&registry);
+  let help_output = help_gen.command("run_file").expect("Command should exist");
+  
+  // Test formatting requirements from specification section 9.5
+  
+  // 1. Should not have overly long lines (no single line over 100 chars for readability)
+  for line in help_output.lines() {
+    assert!(
+      line.len() <= 100,
+      "Help line too long ({}): '{}'", line.len(), line
+    );
+  }
+  
+  // 2. Should not have redundant "Hint:" prefix when context is clear in arguments section
+  let lines = help_output.lines().collect::<Vec<_>>();
+  let in_arguments_section = lines.iter().any(|line| line.contains("Arguments:"));
+  if in_arguments_section {
+    // Find lines in arguments section (after "Arguments:" line)
+    let mut found_arguments_section = false;
+    for line in &lines {
+      if line.contains("Arguments:") {
+        found_arguments_section = true;
+        continue;
+      }
+      if found_arguments_section && !line.trim().is_empty() {
+        // Arguments section lines should not have redundant "Hint:" when description is clear
+        if line.contains(" - Hint: ") {
+          // Check if the hint is identical or very similar to what comes before "Hint:"
+          let parts: Vec<&str> = line.split(" - Hint: ").collect();
+          if parts.len() == 2 {
+            let before_hint = parts[0];
+            let hint_text = parts[1].split(',').next().unwrap_or("");
+            
+            // If the hint is redundant with information already present, fail the test
+            if before_hint.contains(hint_text) {
+              panic!("Redundant hint text found: '{}' already contains '{}'", before_hint, hint_text);
+            }
+          }
+        }
+      }
+    }
+  }
+  
+  // 3. Should have proper visual hierarchy
+  assert!(help_output.contains("Usage:"), "Should have Usage header");
+  assert!(help_output.contains("Arguments:"), "Should have Arguments section");
+  assert!(help_output.contains("Status:"), "Should have Status information");
+  
+  // 4. Arguments should be clearly separated and readable
+  // This test will initially fail with current formatting, then pass after improvement
+  let argument_lines = lines.iter()
+    .skip_while(|line| !line.contains("Arguments:"))
+    .skip(1) // Skip "Arguments:" line itself
+    .take_while(|line| !line.trim().is_empty() && !line.starts_with("Status"))
+    .collect::<Vec<_>>();
+  
+  // Each argument should be well-formatted
+  for arg_line in argument_lines {
+    // Verify improved formatting - should NOT have the old cramped format
+    // Old bad: "file (Kind: File) - Hint: Path to prompt file"
+    // New good: "file (Type: File)" followed by indented description
+    
+    // Should not contain the old cramped patterns
+    assert!(
+      !arg_line.contains("(Kind:"),
+      "Found old 'Kind:' format, should use 'Type:': '{}'", arg_line
+    );
+    assert!(
+      !(arg_line.contains("- Hint:") && arg_line.len() > 60),
+      "Found old cramped 'Hint:' format: '{}'", arg_line
+    );
+    
+    // Should use improved patterns
+    if arg_line.contains("(Type:") {
+      // Main argument lines should be reasonably short
+      assert!(
+        arg_line.len() <= 80,
+        "Argument header line too long: '{}'", arg_line
+      );
+    }
+  }
+}
+
+#[test]
+fn test_help_formatting_visual_hierarchy()
+{
+  // This test verifies that help output has clear visual hierarchy
+  
+  let mut registry = CommandRegistry::new();
+  
+  let test_cmd = CommandDefinition {
+    name: "test_command".to_string(),
+    namespace: String::new(),
+    description: "A test command for formatting verification".to_string(),
+    hint: "Tests help formatting".to_string(),
+    arguments: vec![
+      ArgumentDefinition {
+        name: "required_arg".to_string(),
+        description: "A required argument".to_string(),
+        kind: Kind::String,
+        hint: "Required string input".to_string(),
+        attributes: ArgumentAttributes {
+          optional: false,
+          ..Default::default()
+        },
+        validation_rules: vec![],
+        aliases: vec![],
+        tags: vec![],
+      },
+    ],
+    routine_link: None,
+    status: "stable".to_string(),
+    version: "1.0.0".to_string(),
+    tags: vec![],
+    aliases: vec![],
+    permissions: vec![],
+    idempotent: true,
+    deprecation_message: String::new(),
+    http_method_hint: String::new(),
+    examples: vec![],
+  };
+  
+  registry.register(test_cmd);
+  
+  let help_gen = HelpGenerator::new(&registry);
+  let help_output = help_gen.command("test_command").expect("Command should exist");
+  
+  // Verify section headers are properly spaced
+  let lines: Vec<&str> = help_output.lines().collect();
+  
+  // Find the Arguments section
+  let args_index = lines.iter().position(|line| line.contains("Arguments:"))
+    .expect("Should have Arguments section");
+  
+  // There should be proper spacing around sections
+  if args_index > 0 && args_index < lines.len() - 1 {
+    // Check that there's visual separation (empty line or clear distinction)
+    let line_before = lines[args_index - 1];
+    let _line_after = if args_index + 1 < lines.len() { lines[args_index + 1] } else { "" };
+    
+    // Arguments section should be well-separated from other content
+    assert!(
+      line_before.trim().is_empty() || !line_before.starts_with("  "),
+      "Arguments section should be properly separated from previous content"
+    );
+  }
+}
+
+#[test]
+fn test_documentation_of_improved_formatting_requirements()
+{
+  // This test documents the expected improvements to help formatting
+  
+  // These are the formatting principles that should be followed
+  const MAX_LINE_LENGTH: usize = 80;
+  let requires_multiline_format = true;
+  let eliminates_redundant_hints = true;
+  let provides_visual_hierarchy = true;
+  
+  // Verify that formatting requirements are understood
+  assert_eq!(MAX_LINE_LENGTH, 80, "Lines should not exceed 80 characters when possible");
+  assert!(requires_multiline_format, "Help should use multi-line format for clarity");
+  assert!(eliminates_redundant_hints, "Redundant hint text should be eliminated");
+  assert!(provides_visual_hierarchy, "Help should have clear visual hierarchy");
+  
+  // Document the problem with current formatting
+  let current_bad_example = "file (Kind: File) - Hint: Path to prompt file, Optional";
+  assert!(current_bad_example.len() > 50, "Current format crams too much info on one line");
+  
+  // Document what improved formatting should look like
+  let improved_format_example = vec![
+    "file",
+    "  Type: File",
+    "  Path to prompt file",
+  ];
+  
+  // Improved format separates concerns and is more readable
+  for line in improved_format_example {
+    assert!(line.len() <= MAX_LINE_LENGTH, "Improved format should have reasonable line lengths");
+  }
+}

module/move/unilang/tests/inc/phase2/help_generation_test.rs

@@ -104,8 +104,10 @@ fn test_cli_specific_command_help_add()
     .and( predicate::str::contains( "Adds two numbers." ) ) // Modified this line
     .and( predicate::str::contains( "Status: stable" ) )
     .and( predicate::str::contains( "Arguments:" ) )
-    .and( predicate::str::contains( "a (Kind: Integer) - Hint: First number." ) ) // Modified this line
-    .and( predicate::str::contains( "b (Kind: Integer) - Hint: Second number." ) ), // Modified this line
+    .and( predicate::str::contains( "a (Type: Integer)" ) ) // Updated for new format
+    .and( predicate::str::contains( "First number." ) ) // Description on separate line
+    .and( predicate::str::contains( "b (Type: Integer)" ) ) // Updated for new format
+    .and( predicate::str::contains( "Second number." ) ), // Description on separate line
   )
   .stderr( "" );
 }

module/move/unilang/tests/inc/phase3/data_model_features_test.rs

@@ -62,7 +62,9 @@ fn test_argument_hint_in_help()
   cmd
   .assert()
   .success()
-  .stdout( predicate::str::contains( "arg1 (Kind: String) - Hint: The first argument to echo." ) )
+  // Updated to match improved formatting: argument name with type, description on separate line
+  .stdout( predicate::str::contains( "arg1 (Type: String)" ) )
+  .stdout( predicate::str::contains( "The first argument to echo." ) )
   .stderr( "" );
 }