@cli
Feature: CLI docstring example validation
  As a documentation maintainer
  I want to ensure CLI docstring examples respect positional argument order
  So that published documentation accurately reflects the command signature

  Scenario: Validator detects positional arguments before options
    Given I have a CLI command with positional arguments and options
    When I validate the command's docstring examples
    Then the validation should pass for examples with positional args before options

  Scenario: Validator rejects options before positional arguments
    Given I have a CLI command with options placed before positional arguments
    When I validate the bad command's docstring examples
    Then the validation should fail for examples with options before positional args

  Scenario: Validator handles commands without examples
    Given I have a CLI command without docstring examples
    When I validate the command's docstring examples
    Then the validation should pass for commands without examples

  Scenario: Validator parses example lines with shlex
    Given I have a CLI command with quoted arguments in examples
    When I validate the command's docstring examples
    Then the validation should correctly parse quoted arguments

  Scenario: Validator reports clear error messages
    Given I have a CLI command with invalid docstring examples
    When I validate the invalid command's docstring examples
    Then the error message should identify the command and example line
    And the error message should explain the positional argument order requirement

  Scenario: Validator handles multi-word command names correctly
    Given I have a multi-word CLI command with positional arguments and options
    When I validate the multi-word command's docstring examples
    Then the validation should pass for multi-word commands with correct argument order

  Scenario: Validator scans all commands in a directory
    Given I have a directory with CLI command modules
    When I validate all commands in the directory
    Then the validate all commands result should be True