# Tusks

Tusks allows you to define CLIs easily and idiomatically through a Rust module and function structure.

If You just want a quick example head over to the [Comprehensive Example](#comprehensive-example) section.

## Table of Contents

- [Motivation](#motivation)
- [Installation](#installation)
- [Core Concepts](#core-concepts)
- [Relationship with Clap](#relationship-with-clap)
- [Features and Examples](#features-and-examples)
  - [1. Simple Root Module Definition](#1-simple-root-module-definition)
  - [2. Nested Modules (Subcommands)](#2-nested-modules-subcommands)
  - [3. Root Parameters with Parameters Struct](#3-root-parameters-with-parameters-struct)
  - [4. Module-Level Parameters](#4-module-level-parameters)
  - [5. External Modules](#5-external-modules)
  - [6. Return Values and Exit Codes](#6-return-values-and-exit-codes)
  - [7. Various Argument Types](#7-various-argument-types)
  - [8. Custom Value Parsers](#8-custom-value-parsers)
  - [9. Tasks Mode (Ruby Rake-Style)](#9-tasks-mode-ruby-rake-style)
  - [10. Command Attributes for Documentation](#10-command-attributes-for-documentation)
  - [11. Default Functions for Modules](#11-default-functions-for-modules)
  - [12. Async Commands](#12-async-commands)
  - [13. Shell Completions](#13-shell-completions)
- [Comprehensive Example](#comprehensive-example)
- [License](#license)
- [Contributions](#contributions)
- [Trivia](#trivia)

## Motivation

Creating complex CLI applications with nested commands and shared parameters can quickly become unwieldy. Tusks solves this problem by providing a declarative syntax for CLI structures that:

- **Naturally maps hierarchical command structures**
- **Automatically manages parameter chaining** across multiple levels
- **Uses Clap** under the hood but eliminates boilerplate code
- **Supports modular organization** through external modules
- **Guarantees type safety** through Rust/Clap's type system

Instead of manually managing Clap subcommands and creating match statements, you simply define modules and functions – Tusks takes care of the rest.

> **Want to see it in action?** Check out the [comprehensive example](#comprehensive-example) at the end of this document.

## Installation

```toml
[dependencies]
tusks = "3"
```

## Core Concepts

Tusks is based on four main concepts:

1. **Modules as Commands/Subcommands**: Rust modules automatically become CLI commands. Modules serve to hierarchically group functions as subcommands.
2. **Functions as Commands/Subcommands**: Public functions in modules become executable CLI commands/subcommands. Function arguments are automatically translated into CLI parameters.
3. **Parameters Struct for Command Arguments**: The `Parameters` struct defines arguments at the module level that apply to the respective command/subcommand. These arguments are automatically available to all underlying subcommands.
4. **External Modules**: External modules, i.e., modules in other files, can be easily integrated into the current CLI structure, even recursively!

The CLI is started with `cli::exec_cli()`, which parses the command line arguments and executes the corresponding commands. The function always returns `Option<u8>`, which can be used as an exit code.

## Relationship with Clap

Tusks is a high-level wrapper around [Clap](https://docs.rs/clap/). It generates Clap derive code internally, which means **most Clap attributes work directly in tusks** without any special handling.

### What passes through unchanged

The following attributes are forwarded 1:1 to the generated Clap code:

**`#[arg(...)]` on function parameters and Parameters struct fields:**

All Clap arg attributes work, including: `short`, `long`, `help`, `long_help`, `default_value`, `default_value_t`, `value_parser`, `value_name`, `value_hint`, `value_delimiter`, `num_args`, `env`, `conflicts_with`, `requires`, `required`, `action`, `hide`, `global`, `exclusive`, `overrides_with`, `value_enum`, and any other `Arg` builder method.

**`#[command(...)]` on modules and functions:**

All Clap command attributes work, including: `about`, `long_about`, `version`, `author`, `name`, `alias`, `visible_alias`, `arg_required_else_help`, `propagate_version`, `subcommand_required`, `hide`, `after_help`, `before_help`, `styles`, and any other `Command` builder method.

### Type handling

Clap's automatic type handling works the same way in tusks:

| Type | Behavior |
|------|----------|
| `String`, `u32`, `f64`, ... | Positional argument (parsed via `FromStr`) |
| `bool` | Flag (use `#[arg(long)]` or `#[arg(short)]`) |
| `Option<T>` | Optional argument |
| `Vec<T>` | Multi-value argument |

### ValueEnum support

Enums with `#[derive(Clone, clap::ValueEnum)]` can be defined inside tusks modules and used as argument types. Clap automatically validates the input and shows possible values in help output:

```rust
#[tusks(root)]
pub mod cli {
    #[derive(Clone, ::tusks::clap::ValueEnum)]
    pub enum Color {
        Auto,
        Always,
        Never,
    }

    pub fn paint(
        #[arg(long, default_value = "auto")]
        color: Color,
        message: String,
    ) {
        println!("{:?}: {}", color, message);
    }
}
```

```bash
$ my-cli paint --color always "hello"
Always: hello

$ my-cli paint --color invalid "hello"
error: invalid value 'invalid' for '--color <COLOR>'
  [possible values: auto, always, never]
```

### Global arguments

Use `#[arg(global = true)]` on a Parameters field to make it available in all subcommands, regardless of where it is placed on the command line:

```rust
#[tusks(root)]
pub mod cli {
    pub struct Parameters<'a> {
        #[arg(long, global = true)]
        pub verbose: &'a bool,
    }

    pub mod deploy {
        pub fn run(params: &Parameters) {
            if *params.super_.verbose {
                println!("verbose deploy");
            }
        }
    }
}
```

```bash
# Both work:
$ my-cli --verbose deploy run
$ my-cli deploy run --verbose
```

### What tusks adds on top of Clap

| Feature | Description |
|---------|-------------|
| Module → Subcommand mapping | Rust modules automatically become CLI subcommands |
| `Parameters` struct with `super_` chaining | Hierarchical parameter sharing across levels |
| External modules (`pub use ... as ...`) | Split CLI across files with automatic parameter chaining |
| `#[default]` functions | Default action when module invoked without subcommand |
| `#[skip]` attribute | Exclude public items from CLI |
| Tasks mode (`#[tusks(root, tasks)]`) | Rake-style flat `module.command` syntax |
| `Result<T, E>` return types | Error auto-printed to stderr, exit code 1 |
| Doc comments as help text | `///` on functions appears in `--help` |
| Async support (`features = ["async"]`) | `async fn` commands with tokio runtime |
| Shell completions (`features = ["completions"]`) | `--completions <SHELL>` flag |

### What does NOT work (or differs from Clap)

- **`#[derive(Args)]` / `#[group()]`**: Tusks uses `Parameters` instead of reusable `Args` structs. You cannot define argument groups.
- **`#[command(flatten)]` for user types**: Only used internally for external modules. You cannot flatten arbitrary `Args` structs.
- **Doc comment splitting**: In Clap, a blank line in `///` comments splits `about` and `long_about`. In tusks, use explicit `#[command(about = "...", long_about = "...")]` for reliable multi-line help.

## Features and Examples

### 1. Simple Root Module Definition

The `#[tusks(root)]` attribute marks a module as the CLI entry point. The CLI is started with `cli::exec_cli()`.

```rust
use tusks::tusks;

#[tusks(root)]
#[command(
    about = "My CLI tool",
    version = "1.0.0"
)]
pub mod cli {
    /// A simple command
    pub fn hello(name: String) {
        println!("Hello, {}!", name);
    }
}

fn main() -> std::process::ExitCode {
    // exec_cli() starts the CLI and returns Option<u8>
    std::process::ExitCode::from(cli::exec_cli().unwrap_or(0) as u8)
}
```

**Usage:**
```bash
$ my-cli hello Alice
Hello, Alice!
```

#### Visibility and #[skip]

Only **public** (`pub`) modules and functions are used for CLI construction. Private functions are automatically ignored:

```rust
#[tusks(root)]
pub mod cli {
    /// This command is available
    pub fn public_command() {
        println!("This is a CLI command");
    }
    
    /// This function is NOT available (not pub)
    fn private_helper() {
        println!("This is not a CLI command");
    }
}
```

With the `#[skip]` attribute, you can also exclude public functions from CLI parsing:

```rust
#[tusks(root)]
pub mod cli {
    /// CLI command
    pub fn deploy(target: String) {
        let config = load_config();
        // ... deployment logic ...
    }
    
    /// Helper function - not available as CLI command
    #[skip]
    pub fn load_config() -> Config {
        // This function is public (for other modules),
        // but not a CLI command
        Config::from_file("config.toml")
    }
}
```

The `#[skip]` attribute also works for modules:

```rust
#[tusks(root)]
pub mod cli {
    /// Available subcommand
    pub mod deploy { /* ... */ }
    
    /// Not available as subcommand
    #[skip]
    pub mod internal_utils { /* ... */ }
}
```

### 2. Nested Modules (Subcommands)

Modules automatically become subcommands and serve to hierarchically group functions.

```rust
#[tusks(root)]
pub mod cli {
    #[command(about = "Database operations")]
    pub mod database {
        /// Migrate database
        pub fn migrate(version: String) {
            println!("Migrating database to version {}", version);
        }
        
        /// Backup database
        pub fn backup(path: String) {
            println!("Backing up database to {}", path);
        }
    }
    
    #[command(about = "Deployment operations")]
    pub mod deploy {
        /// Deploy to staging
        pub fn staging() {
            println!("Deploying to staging environment");
        }
        
        /// Deploy to production
        pub fn production() {
            println!("Deploying to production environment");
        }
    }
}
```

**Usage:**
```bash
$ my-cli database migrate v2.0
Migrating database to version v2.0

$ my-cli deploy production
Deploying to production environment

$ my-cli --help
My CLI tool

Usage: my-cli <COMMAND>

Commands:
  database  Database operations
  deploy    Deployment operations
  help      Print this message or the help of the given subcommand(s)
```

Modules can be nested arbitrarily deep:

```rust
#[tusks(root)]
pub mod cli {
    pub mod cloud {
        pub mod aws {
            pub mod s3 {
                /// Upload file to S3
                pub fn upload(file: String, bucket: String) {
                    println!("Uploading {} to bucket {}", file, bucket);
                }
            }
        }
    }
}
```

**Usage:**
```bash
$ my-cli cloud aws s3 upload file.txt my-bucket
Uploading file.txt to bucket my-bucket
```

With a `Parameters` struct, you can define common parameters that are available to all commands.

```rust
#[tusks(root)]
pub mod cli {
    pub struct Parameters<'a> {
        #[arg(long)]
        pub verbose: &'a bool,
        
        #[arg(long)]
        pub config: &'a Option<String>,
    }

    /// Command with access to root parameters
    pub fn deploy(params: &Parameters, target: String) {
        if *params.verbose {
            println!("Deploying to {} with config {:?}", 
                     target, params.config);
        }
    }
}
```

**Usage:**
```bash
$ my-cli --verbose --config prod.toml deploy production
Deploying to production with config Some("prod.toml")
```

#### Important Notes on Parameters

- **Optional**: The `Parameters` struct is completely optional. You only need it if you want to define parameters at the current module level or access parent parameters.

- **Lifetime required**: If you define a `Parameters` struct, it must always have the lifetime `<'a>`:
  ```rust
  pub struct Parameters<'a> {  // <'a> is mandatory
      #[arg(long)]
      pub my_param: &'a String,
  }
  ```

- **Automatic `super_` field**: Tusks automatically adds a `super_` field that references the parent Parameters struct. You must **not** define this field yourself:
  ```rust
  pub struct Parameters<'a> {
      #[arg(long)]
      pub my_param: &'a String,
      // NOT: pub super_: &'a ParentParameters<'a>  ❌
  }
  ```

- **Implicit Parameters structs**: Even if you don't define a `Parameters` struct at a level, it exists in the background. This means that `super_.super_` always works to access parameters two levels up:
  ```rust
  pub mod level1 {
      // No Parameters struct defined here
      
      pub mod level2 {
          pub struct Parameters<'a> {
              #[arg(long)]
              pub level2_param: &'a String,
          }
          
          pub fn command(params: &Parameters) {
              // super_.super_ still works!
              println!("{}", params.super_.super_.root_param);
          }
      }
  }
  ```

- **Parameters as function argument**: The `Parameters` struct may only be specified as the **first argument** of a function and is optional. If you don't need it, you can omit it:
  ```rust
  // With Parameters (must be first argument)
  pub fn command1(params: &Parameters, name: String) { }
  
  // Without Parameters
  pub fn command2(name: String, age: u32) { }
  
  // WRONG: Parameters not in first position ❌
  pub fn command3(name: String, params: &Parameters) { }
  ```

### 3. Root Parameters with Parameters Struct

With a `Parameters` struct, you can define common parameters that are available to all commands.

```rust
#[tusks(root)]
pub mod cli {
    pub struct Parameters<'a> {
        #[arg(long)]
        pub verbose: &'a bool,
        
        #[arg(long)]
        pub config: &'a Option<String>,
    }

    /// Command with access to root parameters
    pub fn deploy(params: &Parameters, target: String) {
        if *params.verbose {
            println!("Deploying to {} with config {:?}", 
                     target, params.config);
        }
    }
}
```

**Usage:**
```bash
$ my-cli --verbose --config prod.toml deploy production
Deploying to production with config Some("prod.toml")
```

Modules automatically become subcommands with their own parameters.

```rust
#[tusks(root)]
pub mod cli {
    pub struct Parameters<'a> {
        #[arg(long)]
        pub verbose: &'a bool,
    }

    #[command(about = "Database operations")]
    pub mod database {
        pub struct Parameters<'a> {
            #[arg(long)]
            pub connection: &'a String,
        }

        /// Migrate database
        pub fn migrate(params: &Parameters) {
            println!("Migrating database: {}", params.connection);
            
            // Access parent parameters via super_
            if *params.super_.verbose {
                println!("Verbose mode enabled");
            }
        }
    }
}
```

**Usage:**
```bash
$ my-cli --verbose database --connection "localhost:5432" migrate
Migrating database: localhost:5432
Verbose mode enabled
```

### 4. Module-Level Parameters

Each module can define its own `Parameters` struct to define specific arguments for the respective subcommand. These parameters are automatically available to all underlying subcommands.

```rust
#[tusks(root)]
pub mod cli {
    pub struct Parameters<'a> {
        #[arg(long)]
        pub verbose: &'a bool,
    }

    #[command(about = "Database operations")]
    pub mod database {
        pub struct Parameters<'a> {
            #[arg(long)]
            pub connection: &'a String,
        }

        /// Migrate database
        pub fn migrate(params: &Parameters) {
            println!("Migrating database: {}", params.connection);
            
            // Access parent parameters via super_
            if *params.super_.verbose {
                println!("Verbose mode enabled");
            }
        }
    }
}
```

**Usage:**
```bash
$ my-cli --verbose database --connection "localhost:5432" migrate
Migrating database: localhost:5432
Verbose mode enabled
```

Parameters can be passed through an arbitrary number of levels.

```rust
#[tusks(root)]
pub mod cli {
    pub struct Parameters<'a> {
        #[arg(long)]
        pub env: &'a String,
    }

    pub mod services {
        pub struct Parameters<'a> {
            #[arg(long)]
            pub region: &'a String,
        }

        pub mod kubernetes {
            pub struct Parameters<'a> {
                #[arg(long)]
                pub namespace: &'a String,
            }

            /// Deploy to k8s
            pub fn deploy(params: &Parameters, image: String) {
                // Access all levels:
                println!("Environment: {}", params.super_.super_.env);
                println!("Region: {}", params.super_.region);
                println!("Namespace: {}", params.namespace);
                println!("Image: {}", image);
            }
        }
    }
}
```

**Usage:**
```bash
$ my-cli --env production services --region eu-west-1 kubernetes --namespace default deploy my-app:v1.0
Environment: production
Region: eu-west-1
Namespace: default
Image: my-app:v1.0
```

### 5. External Modules

External modules allow distributing CLI structures across multiple files. This is particularly useful for organizing large CLIs and promoting code reusability.

An external module differs from the root module in that it does **not** have the `root` flag in the `#[tusks()]` attribute. Instead, it must include a `parent_` reference to its parent module to enable parameter chaining.

**src/main.rs:**
```rust
#[tusks(root)]  // Root module with 'root' flag
pub mod cli {
    pub struct Parameters<'a> {
        #[arg(long)]
        pub verbose: &'a bool,
    }

    /// Git operations
    #[command(about = "Git commands")]
    pub use crate::git::cli as git;
}
```

**src/git.rs:**
```rust
use tusks::tusks;

#[tusks()]  // External module WITHOUT 'root' flag
pub mod cli {
    // Parent reference is required for parameter chaining
    pub use crate::cli as parent_;

    pub struct Parameters<'a> {
        #[arg(long)]
        pub branch: &'a String,
    }

    /// Commit changes
    pub fn commit(params: &Parameters, message: String) {
        println!("Committing on branch {}: {}", 
                 params.branch, message);
        
        // Access root parameters via super_
        if *params.super_.verbose {
            println!("Verbose output enabled");
        }
    }
}
```

**Usage:**
```bash
$ my-cli --verbose git --branch main commit "Fix bug"
Committing on branch main: Fix bug
Verbose output enabled
```

#### Important Notes on External Modules

- **Parent reference required**: External modules must always contain a `parent_` reference to their parent module. The alias `parent_` must be used.
  ```rust
  pub use crate::cli as parent_;  // Required!
  ```
  This reference also enables parameter chaining via `super_`.

- **No `root` flag**: External modules use `#[tusks()]` **without** the `root` flag. Only the main module (the entry point for the CLI) uses `#[tusks(root)]`.

- **Customize subcommand names**: The name of the subcommand is determined by the name used during import:
  
  ```rust
  // Subcommand is named "cli" (name of imported module)
  pub use crate::git::cli;
  
  // Subcommand is named "git" (with alias)
  pub use crate::git::cli as git;
  
  // Subcommand is named "vcs" (with different alias)
  pub use crate::git::cli as vcs;
  
  // Customize subcommand name via attribute, alias is ignored
  #[command(name = "version-control")]
  pub use crate::git::cli as git;
  ```

- **Arbitrary nesting**: External modules can themselves include external modules:
  
  **src/git.rs:**
  ```rust
  #[tusks()]
  pub mod cli {
      pub use crate::cli as parent_;
      
      // Git includes the advanced module
      #[command(about = "Advanced git operations")]
      pub use crate::git_advanced::cli as advanced;
  }
  ```
  
  **src/git_advanced.rs:**
  ```rust
  #[tusks()]
  pub mod cli {
      // Reference to git module
      pub use crate::git::cli as parent_;
      
      pub fn rebase(/* ... */) { }
  }
  ```
  
  **Invocation:**
  ```bash
  $ my-cli git advanced rebase
  ```

### 6. Return Values and Exit Codes

Commands can return values that are used as exit codes. Allowed return types are `()`, `u8`, `Option<u8>`, and `Result<T, E>` (where T is one of those). The return value is always returned by `cli::exec_cli()` as `Option<u8>`.

```rust
#[tusks(root)]
pub mod cli {
    pub fn success() {
        println!("Operation completed successfully");
    }
    
    /// Command with u8 return value
    pub fn check_health() -> u8 {
        println!("Running health checks...");
        
        if all_systems_ok() {
            println!("✓ All systems operational");
            0  // Success
        } else {
            println!("✗ System degraded");
            1  // Error
        }
    }
    
    /// Command with Option<u8> return value
    pub fn validate(file: String) -> Option<u8> {
        println!("Validating {}...", file);
        
        match check_file(&file) {
            Ok(_) => {
                println!("✓ Valid");
                Some(0)  // Success
            }
            Err(e) if e.is_warning() => {
                println!("⚠ Warnings found");
                Some(2)  // Warning
            }
            Err(_) => {
                println!("✗ Invalid");
                None
            }
        }
    }
}

    /// Command with Result return - errors are printed to stderr
    pub fn deploy(version: String) -> Result<(), String> {
        if version.starts_with("v") {
            println!("Deploying {}...", version);
            Ok(())
        } else {
            Err(format!("invalid version '{}' (must start with 'v')", version))
        }
    }
}

fn main() -> std::process::ExitCode {
    // exec_cli() returns the return value of the executed command
    // In this case, explicitly returns 0 if no return value exists
    std::process::ExitCode::from(cli::exec_cli().unwrap_or(0) as u8)
}
```

**Usage:**
```bash
$ my-cli check-health
Running health checks...
✗ System degraded
$ echo $?
1

$ my-cli validate config.toml
Validating config.toml...
✓ Valid
$ echo $?
0

# Result return - success
$ my-cli deploy v1.0
Deploying v1.0...
$ echo $?
0

# Result return - error is printed to stderr, exits with code 1
$ my-cli deploy invalid
Error: invalid version 'invalid' (must start with 'v')
$ echo $?
1
```

### 7. Various Argument Types

Tusks supports all Clap argument types.

```rust
#[tusks(root)]
pub mod cli {
    /// Complex command with various argument types
    pub fn build(
        #[arg(short, long)]
        target: String,
        
        #[arg(long)]
        features: Vec<String>,
        
        #[arg(long)]
        release: bool,
        
        #[arg(long)]
        jobs: Option<u32>,
    ) {
        println!("Building target: {}", target);
        println!("Features: {:?}", features);
        println!("Release mode: {}", release);
        println!("Jobs: {:?}", jobs.unwrap_or(4));
    }
}
```

**Usage:**
```bash
$ my-cli build --target x86_64-linux --features async --features logging --release --jobs 8
Building target: x86_64-linux
Features: ["async", "logging"]
Release mode: true
Jobs: 8
```

### 8. Custom Value Parsers

Clap's value parsers can be used to add custom validation.

```rust
#[tusks(root)]
pub mod cli {
    #[skip]  // This function is not a command
    pub fn parse_port(s: &str) -> Result<u16, String> {
        s.parse::<u16>()
            .map_err(|_| "Port must be between 0 and 65535".into())
    }

    /// Start server
    pub fn serve(
        #[arg(value_parser = crate::cli::parse_port)]
        port: u16
    ) {
        println!("Starting server on port {}", port);
    }
}
```

**Usage:**
```bash
$ my-cli serve 8080
Starting server on port 8080

$ my-cli serve invalid
error: invalid value 'invalid' for '<PORT>': Port must be between 0 and 65535
```

### 9. Tasks Mode (Ruby Rake-Style)

Tasks mode provides a simplified, flat CLI syntax in the style of Ruby Rake. Instead of nested subcommands, tasks can be invoked with a separator (default `.`).

#### Activation

Tasks mode is simply activated through the `tasks` attribute:

```rust
#[tusks(root, tasks)]
#[command(about = "Task management tool")]
pub mod tasks {
    #[command(about = "Git operations")]
    pub mod git {
        /// Clone a repository
        pub fn clone(url: String, path: Option<String>) {
            println!("Cloning {} to {:?}", url, path);
        }

        /// Commit changes
        pub fn commit(message: String) {
            println!("Committing: {}", message);
        }
    }

    #[command(about = "Docker operations")]
    pub mod docker {
        /// Build Docker image
        pub fn build(context: String, tag: Option<String>) {
            println!("Building from {} with tag {:?}", context, tag);
        }
    }
}
```

#### Display Task List

Without arguments, the CLI automatically shows all available tasks in a grouped overview:

```bash
$ tasks
Task management tool

  git
    git.clone ..... Clone a repository
    git.commit .... Commit changes

  docker
    docker.build .. Build Docker image
```

#### Flat Task Syntax

Tasks can be invoked directly via their full path:

```bash
# Rake-style (with separator)
$ tasks git.clone https://github.com/user/repo

# Equivalent to traditional subcommand syntax
$ tasks git clone https://github.com/user/repo
```

Both variants are fully interchangeable. The subcommand structure is preserved, so you can still use module-specific parameters:

```bash
$ tasks --root-param value git --git-option xyz clone https://...
```

#### Help for Tasks

Help can be accessed in multiple ways:

```bash
# With 'h' prefix
$ tasks h git.clone

# With '-h' flag
$ tasks git.clone -h

# Traditional
$ tasks git clone --help
```

All three variants display the same help:
```
Clone a repository

Usage: tasks git clone <URL> [PATH]

Arguments:
  <URL>   Repository URL
  [PATH]  Target path

Options:
  -h, --help  Print help
```

#### Configuring Task Grouping

The task overview display can be configured to control how tasks are organized and presented:

```rust
#[tusks(root, tasks(max_groupsize=5, max_depth=20, separator=".", use_colors=true))]
pub mod tasks {
    // ...
}
```

**Parameters:**

- **`separator`** (default: `"."`) - Character(s) used to separate module levels in command names
  ```bash
  # With separator="."
  $ tasks git.clone url
  
  # With separator=":"
  $ tasks git:clone url
  ```

- **`use_colors`** (default: `true`)
  If `true` (which is the default) the overview over all tasks is colored

> [!NOTE]
> The following part of this section is proably quite technical and not that
> important. If the task overview is fine for your needs, it is advised to skip
> it.

- **`max_groupsize`** (default: `5`) - Threshold for creating subgroups in the task overview
  
  *This parameter only affects the task overview output, not command execution.*
  
  When a group contains **more than** `max_groupsize` **visible** tasks, they are organized into subgroups based on their module hierarchy. Hidden tasks (marked with `#[hidden]`) are excluded from this count.
  
  **Example with `max_groupsize=5`:**
  ```bash
  # Scenario: 4 visible tasks (+ 2 hidden tasks)
  # 4 ≤ 5, so no grouping occurs - all tasks shown at root level
  
  Application Commands
  
    docker.build .. Build Docker image
    docker.run .... Run Docker container
    git.clone ..... Clone a repository
    git.commit .... Commit changes
  ```
  
  ```bash
  # Scenario: 6 visible tasks (+ 2 hidden tasks)
  # 6 > 5, so grouping by first module level occurs
  
  Application Commands
  
    docker

      docker.build .. Build Docker image
      docker.run .... Run Docker container
      docker.stop ... Stop Docker container
  
    git

      git.clone ..... Clone a repository
      git.commit .... Commit changes
      git.push ...... Push changes
  ```

- **`max_depth`** (default: `20`) - Maximum nesting depth for hierarchical grouping
  
  *This parameter only affects the task overview output, not command execution.*
  
  Controls how many levels deep the grouping can go. Each level corresponds to one module in the path hierarchy.
  
  **Example with `max_depth=1`:**
  ```bash
  # Deep module structure with 8 visible tasks
  # docker.container.list, docker.container.logs, docker.image.build, docker.image.pull, etc.
  # With max_depth=1, only first level grouping is allowed
  
  Application Commands
  
    docker

      docker.container.list .. List containers
      docker.container.logs .. Show container logs
      docker.image.build ..... Build an image
      docker.image.pull ...... Pull an image
  ```
  
  ```bash
  # Same structure with max_depth=2 and max_groupsize=3
  # Second level grouping is allowed, creating subgroups
  
  Application Commands
  
    docker.container

      docker.container.list .. List containers
      docker.container.logs .. Show container logs
  
    docker.image

      docker.image.build ..... Build an image
      docker.image.pull ...... Pull an image
  ```

**Interaction between `max_groupsize` and `max_depth`:**

Both parameters work together to control grouping behavior. **Both conditions must be met** for grouping to occur:

1. The number of visible tasks must **exceed** `max_groupsize` (threshold condition)
2. The current depth must be **less than** `max_depth` (depth limit)

**`max_depth` takes precedence** - once the depth limit is reached, no further grouping occurs regardless of group size.

**Example showing the interaction:**

```bash
# Configuration: max_groupsize=3, max_depth=2
# Module structure with 12 visible tasks:
# docker.container.alpine.create, docker.container.alpine.run, docker.container.alpine.stop
# docker.container.ubuntu.create, docker.container.ubuntu.run, docker.container.ubuntu.stop
# docker.image.alpine.build, docker.image.alpine.pull
# docker.image.ubuntu.build, docker.image.ubuntu.pull, docker.image.ubuntu.push, docker.image.ubuntu.tag

Application Commands

  docker.container
    # Depth 2 reached - no further grouping even though each subgroup has >3 tasks
    docker.container.alpine.create
    docker.container.alpine.run
    docker.container.alpine.stop
    docker.container.ubuntu.create
    docker.container.ubuntu.run
    docker.container.ubuntu.stop

  docker.image
    # Depth 2 reached - no further grouping
    docker.image.alpine.build
    docker.image.alpine.pull
    docker.image.ubuntu.build
    docker.image.ubuntu.pull
    docker.image.ubuntu.push
    docker.image.ubuntu.tag
```

```bash
# Same structure with max_groupsize=3, max_depth=3
# Now depth 3 is allowed, enabling finer grouping

Application Commands

  docker.container.alpine

    docker.container.alpine.create
    docker.container.alpine.run
    docker.container.alpine.stop

  docker.container.ubuntu

    docker.container.ubuntu.create
    docker.container.ubuntu.run
    docker.container.ubuntu.stop

  docker.image.alpine

    docker.image.alpine.build
    docker.image.alpine.pull

  docker.image.ubuntu

    docker.image.ubuntu.build
    docker.image.ubuntu.pull
    docker.image.ubuntu.push
    docker.image.ubuntu.tag
```

**How the Grouping Algorithm Works:**

1. **Check depth limit**: If `max_depth` is 0, stop grouping immediately
2. **Count visible tasks**: If visible tasks ≤ `max_groupsize`, no grouping occurs - all tasks are displayed directly
3. **Group by module prefix**: Tasks are grouped by their next module level (e.g., all `git.*` tasks together)
4. **Recursive grouping**: Each group is evaluated recursively with `max_depth - 1`
5. **Single-task optimization**: Groups containing only one visible task are automatically flattened into their parent group

**Tip:** Start with the default values. Decrease `max_groupsize` for more granular grouping, or decrease `max_depth` to prevent overly nested displays with deeply nested module structures.

#### Complete Example

```rust
use tusks::tusks;

#[tusks(root, tasks(separator=".", max_groupsize=5, max_depth=10))]
#[command(
    about = "DevOps toolkit",
    version = "1.0.0"
)]
pub mod tasks {
    pub mod deploy {
        /// Deploy to staging
        pub fn staging(version: String) {
            println!("Deploying {} to staging", version);
        }

        /// Deploy to production
        pub fn production(version: String) {
            println!("Deploying {} to production", version);
        }
    }

    pub mod test {
        /// Run unit tests
        pub fn unit() {
            println!("Running unit tests");
        }

        /// Run integration tests
        pub fn integration() {
            println!("Running integration tests");
        }
    }
}

fn main() -> std::process::ExitCode {
    std::process::ExitCode::from(tasks::exec_cli().unwrap_or(0) as u8)
}
```

**Usage:**
```bash
# Task overview
$ tasks
DevOps toolkit

  deploy
    deploy.staging      Deploy to staging
    deploy.production   Deploy to production

  test
    test.unit          Run unit tests
    test.integration   Run integration tests

# Execute tasks (both syntaxes work)
$ tasks deploy.staging v1.2.3
$ tasks deploy staging v1.2.3

# Display help
$ tasks h deploy.production
$ tasks deploy.production -h
```

### 10. Command Attributes for Documentation

Use `#[command()]` attributes to define CLI documentation. This is a standard Clap feature and is mentioned here only as a common use case.

```rust
#[tusks(root)]
#[command(
    about = "Project management CLI",
    long_about = "A comprehensive tool for managing development projects",
    version = "2.0.0",
    author = "Your Team <team@example.com>"
)]
pub mod cli {
    /// Initialize new project
    #[command(
        about = "Create a new project",
        long_about = "Initialize a new project with default structure and configuration"
    )]
    pub fn init(
        #[arg(help = "Project name")]
        name: String,
        
        #[arg(long, help = "Project template to use")]
        template: Option<String>,
    ) {
        println!("Initializing project: {}", name);
    }
}
```

**Usage:**
```bash
$ my-cli --help
Project management CLI

A comprehensive tool for managing development projects

Usage: my-cli [OPTIONS] <COMMAND>

Commands:
  init  Create a new project
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
```

### 11. Default Functions for Modules

With the `#[default]` attribute, you can define a function that is executed when a module is invoked without a specific subcommand.

```rust
#[tusks(root)]
pub mod cli {
    #[command(about = "Git operations")]
    pub mod git {
        pub struct Parameters<'a> {
            #[arg(long)]
            pub repository: &'a Option<String>,
        }
        
        /// Default action when just "git" is called
        #[default]
        pub fn status(params: &Parameters) {
            println!("Git status for {:?}", params.repository);
            // Shows status
        }
        
        /// Push changes
        pub fn push(branch: String) {
            println!("Pushing to {}", branch);
        }
        
        /// Pull changes
        pub fn pull(branch: String) {
            println!("Pulling from {}", branch);
        }
    }
}
```

**Usage:**
```bash
# Without subcommand - executes the default function
$ my-cli git --repository myrepo
Git status for Some("myrepo")

# Equivalent to
$ my-cli git status --repository myrepo
```

#### Restrictions for Default Functions

- **Only Parameters allowed**: Default functions may have at most the `Parameters` struct of the current level as an argument. Additional parameters are not permitted:
  ```rust
  #[default]
  pub fn default_action(params: &Parameters) { }  // ✓ Allowed
  
  #[default]
  pub fn default_action() { }  // ✓ Allowed (without Parameters)
  
  #[default]
  pub fn default_action(params: &Parameters, name: String) { }  // ❌ Not allowed
  ```

- **Exception: Allow External Subcommands**: If `allow_external_subcommands = true` is set for the module, the default function may additionally receive a `Vec<String>` argument containing all arguments of the external subcommand:
  ```rust
  #[command(about = "Command runner", allow_external_subcommands = true)]
  pub mod run {
      pub struct Parameters<'a> {
          #[arg(long)]
          pub verbose: &'a bool,
      }
      
      #[default]
      pub fn execute(params: &Parameters, args: Vec<String>) {
          println!("Running external command with args: {:?}", args);
          if *params.verbose {
              println!("Verbose mode enabled");
          }
          // Executes external command with args
      }
      
      /// Built-in command
      pub fn builtin() {
          println!("This is a built-in command");
      }
  }
  ```
  
  **Usage:**
  ```bash
  # External subcommand (not defined) - default function with args
  $ my-cli run --verbose custom-script --arg1 --arg2
  Running external command with args: ["custom-script", "--arg1", "--arg2"]
  Verbose mode enabled
  
  # Built-in subcommand
  $ my-cli run builtin
  This is a built-in command
  ```

### 12. Async Commands

Tusks supports async command functions. Enable the `async` feature to use them:

```toml
[dependencies]
tusks = { version = "2.1", features = ["async"] }
```

With the feature enabled, you can write async functions as commands:

```rust
use tusks::tusks;

#[tusks(root)]
#[command(about = "Async CLI")]
pub mod cli {
    /// Fetch data from a URL
    pub async fn fetch(url: String) {
        let data = do_async_fetch(&url).await;
        println!("Fetched {} bytes from {}", data.len(), url);
    }

    /// Sync commands work alongside async ones
    pub fn version() {
        println!("v1.0.0");
    }

    #[command(about = "Database commands")]
    pub mod db {
        /// Async works in nested modules too
        pub async fn migrate(version: String) {
            run_migrations(&version).await;
            println!("Migrated to {}", version);
        }
    }
}

fn main() -> std::process::ExitCode {
    // exec_cli() automatically creates a tokio runtime when needed
    std::process::ExitCode::from(cli::exec_cli().unwrap_or(0) as u8)
}
```

**Usage:**
```bash
$ my-cli fetch https://example.com
Fetched 1256 bytes from https://example.com

$ my-cli db migrate v2.0
Migrated to v2.0
```

#### How it works

- `exec_cli()` automatically creates a tokio runtime and uses `block_on` to drive the async dispatch
- The generated `handle_matches` function becomes `async fn` when the feature is enabled
- Sync functions work normally inside async context — no changes needed
- All return types (`()`, `u8`, `Option<u8>`) work the same with async
- Without the `async` feature, using `async fn` produces a clear compile error

### 13. Shell Completions

Enable the `completions` feature to add shell completion generation:

```toml
[dependencies]
tusks = { version = "3", features = ["completions"] }
```

This adds a hidden `--completions <SHELL>` flag to your CLI that outputs a completion script:

```bash
# Generate and install completions
$ my-cli --completions bash > ~/.local/share/bash-completion/completions/my-cli
$ my-cli --completions zsh > ~/.zfunc/_my-cli
$ my-cli --completions fish > ~/.config/fish/completions/my-cli.fish
```

Supported shells: `bash`, `zsh`, `fish`, `elvish`, `powershell`.

## Comprehensive Example

Here's a complete example demonstrating most of Tusks' features in a single application:

**src/main.rs:**
```rust
use tusks::tusks;

#[tusks(root)]
#[command(
    about = "DevOps automation toolkit",
    long_about = "A comprehensive CLI for managing deployments, databases, and CI/CD pipelines",
    version = "1.0.0",
    author = "DevOps Team <devops@example.com>"
)]
pub mod cli {
    // Top-level command: Quick health check
    /// Perform a quick system health check
    pub fn health() -> u8 {
        println!("Running system health checks...");
        
        // Simulate health check
        let healthy = check_system_health();
        
        if healthy {
            println!("✓ All systems operational");
            0  // Success exit code
        } else {
            println!("✗ System issues detected");
            1  // Error exit code
        }
    }

    // Submodule with multiple commands
    #[command(about = "Database operations")]
    pub mod database {
        // Default command when just "database" is called
        #[default]
        /// Show database status (default action)
        pub fn status(
            #[arg(long, help = "Database connection string")]
            connection: String,
        ) {
            println!("Database status for: {}", connection);
            println!("Connection pool: 10/50");
            println!("Active queries: 3");
        }

        /// Migrate database to latest version
        pub fn migrate(
            #[arg(long, help = "Database connection string")]
            connection: String,
            #[arg(help = "Target migration version")]
            version: String,
            #[arg(long, help = "Perform dry-run without applying changes")]
            dry_run: bool,
        ) -> Option<u8> {
            println!("Migrating database to version: {}", version);
            println!("Connection: {}", connection);
            
            if dry_run {
                println!("⚠ Dry-run mode - no changes applied");
                return Some(0);
            }
            
            // Simulate migration
            let success = perform_migration(&version);
            
            if success {
                println!("✓ Migration completed successfully");
                Some(0)
            } else {
                println!("✗ Migration failed");
                None
            }
        }

        // Nested submodule
        #[command(about = "Advanced database operations")]
        pub mod advanced {
            /// Optimize database tables
            pub fn optimize(
                #[arg(long, help = "Database connection string")]
                connection: String,
            ) -> u8 {
                println!("Optimizing database: {}", connection);
                println!("✓ Optimization completed");
                0
            }
        }
    }

    // External module for deployment operations
    #[command(about = "Deployment commands")]
    pub use crate::deploy::cli as deploy;

    // Helper function with custom value parser
    #[skip]
    pub fn parse_port(s: &str) -> Result<u16, String> {
        let port: u16 = s.parse()
            .map_err(|_| format!("'{}' is not a valid port number", s))?;
        
        if port < 1024 {
            return Err("Port must be 1024 or higher".to_string());
        }
        
        Ok(port)
    }

    // Helper function (not a command)
    #[skip]
    fn check_system_health() -> bool {
        // Simulate health check
        true
    }

    #[skip]
    fn perform_migration(_version: &str) -> bool {
        // Simulate migration
        true
    }
}

fn main() -> std::process::ExitCode {
    // Execute the CLI and use the return value as exit code
    std::process::ExitCode::from(cli::exec_cli().unwrap_or(0) as u8)
}
```

**src/deploy.rs:**
```rust
use tusks::tusks;

#[tusks()]  // External module
pub mod cli {
    // Reference to parent module for parameter chaining
    pub use crate::cli as parent_;

    /// Deploy application to target environment
    pub fn start(
        #[arg(help = "Application version to deploy")]
        version: String,
        #[arg(long, help = "Target environment")]
        environment: String,
        #[arg(long, help = "Server port", value_parser = crate::cli::parse_port)]
        port: Option<u16>,
    ) -> u8 {
        let port = port.unwrap_or(8080);
        
        println!("Deploying version {} to {}", version, environment);
        println!("Server will listen on port: {}", port);
        println!("✓ Deployment initiated");
        0
    }

    /// Rollback to previous version
    pub fn rollback(
        #[arg(long, help = "Target environment")]
        environment: String,
    ) {
        println!("Rolling back deployment in {}", environment);
        println!("✓ Rollback completed");
    }
}
```

**Usage examples:**

```bash
# Top-level command
$ my-cli health
Running system health checks...
✓ All systems operational

# Default command (status is called automatically)
$ my-cli database --connection "postgres://localhost/mydb"
Database status for: postgres://localhost/mydb
Connection pool: 10/50
Active queries: 3

# Explicit subcommand
$ my-cli database status --connection "postgres://localhost/mydb"
Database status for: postgres://localhost/mydb
Connection pool: 10/50
Active queries: 3

# Migration with various argument types
$ my-cli database migrate --connection "postgres://localhost/mydb" v2.0 --dry-run
Migrating database to version: v2.0
Connection: postgres://localhost/mydb
⚠ Dry-run mode - no changes applied

# Nested submodule command
$ my-cli database advanced optimize --connection "postgres://localhost/mydb"
Optimizing database: postgres://localhost/mydb
✓ Optimization completed

# External module with custom value parser
$ my-cli deploy start v1.5.0 --environment production --port 8080
Deploying version v1.5.0 to production
Server will listen on port: 8080
✓ Deployment initiated

# Custom parser validation
$ my-cli deploy start v1.4.0 --environment staging --port 80
error: invalid value '80' for '--port <PORT>': Port must be 1024 or higher

# Rollback command
$ my-cli deploy rollback --environment production
Rolling back deployment in production
✓ Rollback completed
```

**Note:** This example demonstrates how arguments can be defined directly in function signatures. You can also define module-level parameters using a `Parameters` struct which would then be available to all commands within that module and automatically passed down to nested submodules. The parameters would be specified before the subcommand name:

```bash
# Example if database module had Parameters with --connection and --verbose:
$ my-cli database --connection "..." --verbose migrate v2.0
$ my-cli database --connection "..." status
```

For more details on how to define and use module-level parameters, see [Module-Level Parameters](#4-module-level-parameters).

### Equivalent with Raw Clap Syntax

Here's what the same CLI structure would look like using Clap's derive API directly (abbreviated for brevity):

```rust
#[derive(Parser)]
#[command(
    about = "DevOps automation toolkit",
    long_about = "A comprehensive CLI for managing deployments, databases, and CI/CD pipelines",
    version = "1.0.0",
    author = "DevOps Team <devops@example.com>"
)]
struct Cli {
    #[command(subcommand)]
    command: Option<Commands>,
}

#[derive(Subcommand)]
enum Commands {
    /// Perform a quick system health check
    Health,
    
    /// Database operations
    Database {
        #[command(subcommand)]
        command: Option<DatabaseCommands>,
    },
    
    /// Deployment commands
    Deploy {
        #[command(subcommand)]
        command: DeployCommands,
    },
}

#[derive(Subcommand)]
enum DatabaseCommands {
    /// Show database status
    Status {
        #[arg(long, help = "Database connection string")]
        connection: String,
    },
    
    /// Migrate database to latest version
    Migrate {
        #[arg(long, help = "Database connection string")]
        connection: String,
        version: String,
        #[arg(long)]
        dry_run: bool,
    },
    
    /// Advanced database operations
    Advanced {
        #[command(subcommand)]
        command: AdvancedCommands,
    },
}

#[derive(Subcommand)]
enum AdvancedCommands {
    /// Optimize database tables
    Optimize {
        #[arg(long, help = "Database connection string")]
        connection: String,
    },
}

#[derive(Subcommand)]
enum DeployCommands {
    /// Deploy application
    Start {
        version: String,
        #[arg(long, help = "Target environment")]
        environment: String,
        #[arg(long, value_parser = parse_port)]
        port: Option<u16>,
    },
    
    /// Rollback to previous version
    Rollback {
        #[arg(long, help = "Target environment")]
        environment: String,
    },
}

fn main() -> std::process::ExitCode {
    let cli = Cli::parse();
    
    // Manual dispatch logic
    let exit_code = match cli.command {
        Some(Commands::Health) => {
            health()
        }
        Some(Commands::Database { command }) => {
            match command {
                Some(DatabaseCommands::Status { connection }) | None => {
                    // Default command logic needed here
                    database_status(&connection);
                    0
                }
                Some(DatabaseCommands::Migrate { connection, version, dry_run }) => {
                    database_migrate(&connection, &version, dry_run)
                        .unwrap_or(1)
                }
                Some(DatabaseCommands::Advanced { command }) => {
                    match command {
                        AdvancedCommands::Optimize { connection } => {
                            database_advanced_optimize(&connection)
                        }
                    }
                }
            }
        }
        Some(Commands::Deploy { command }) => {
            match command {
                DeployCommands::Start { version, environment, port } => {
                    deploy_start(&version, &environment, port)
                }
                DeployCommands::Rollback { environment } => {
                    deploy_rollback(&environment);
                    0
                }
            }
        }
        None => {
            // Show help when no command is provided
            Cli::parse_from(&["cli", "--help"]);
            0
        }
    };
    
    std::process::ExitCode::from(exit_code)
}

// All the handler functions need to be manually implemented
fn health() -> u8 {
    // Implementation
    0
}

fn database_status(connection: &str) {
    // Implementation
}

fn database_migrate(connection: &str, version: &str, dry_run: bool) -> Option<u8> {
    // Implementation
    Some(0)
}

fn database_advanced_optimize(connection: &str) -> u8 {
    // Implementation
    0
}

fn deploy_start(version: &str, environment: &str, port: Option<u16>) -> u8 {
    // Implementation
    0
}

fn deploy_rollback(environment: &str) {
    // Implementation
}
```

As you can see, Tusks eliminates:
- Manual enum definitions for every command level
- Repetitive match/dispatch logic
- Manual parameter passing through the hierarchy
- Boilerplate for default command handling

## License

MIT

## Contributions

Contributions are welcome! Please create an issue or pull request on GitHub.

I'm still learning Rust. I always have an open ear for suggestions on best practices, code style, etc.

I will try to respond to contributions, but as I work full-time with a wife and child, this will not always be possible in a timely manner.

## Trivia

This project originally came about because I've wanted to learn and use Rust for a long time, and also because I was looking for a replacement for Ruby Rake and Python Invoke that is idiomatic, future-oriented, and easy to use. The use of these tools is also always limited by the environment you're in. Often, the versions of interpreters and packages differ across various server environments. A compiled Rust application is much more flexible in this regard. However, there are also disadvantages. The effort and barrier to creating and extending a compiled application is higher than with a simple Python script. And of course, the appropriate toolchain must be available on the system where you develop. But Rust makes it quite easy with cargo.

During development, I worked extensively with various AIs. Otherwise, this would not have been possible within a week with my existing basic knowledge, especially not for a project that relies so heavily on source code parsing and generation, i.e., the creation of macros. In some places, I performed some refactoring. In other places, I only superficially adapted or reviewed the code. Little code was actually written 100% by myself. This is an interesting experience for me, and you can certainly view it critically. However, I think I still learned a lot, and I'm actually quite satisfied with the code quality. If I had actually done everything myself, it would probably have turned out significantly worse (or simply not finished). But one should always keep in mind that I'm a Rust beginner. The way to write code in Rust, to structure it, the patterns used - all of this is definitely very different in many ways from many programming languages I've used before. Accordingly, this is a beginner's project.

## Development

### Workspace Structure

Tusks is organized as a Cargo workspace with five crates:

| Crate | Purpose |
|-------|---------|
| `tusks` | User-facing crate that re-exports the macro, clap, and tasks module |
| `tusks-macro` | Proc-macro entry point (`#[tusks]` attribute) |
| `tusks-lib` | Core library: parsing module ASTs and generating clap code |
| `tusks-tasks` | Runtime library for task-mode: grouping, formatting, and printing task lists |
| `tusks-test` | Integration tests and example binaries (not published) |
| `tusks-test-async` | Async feature tests (excluded from workspace, tested separately) |

### Architecture

The macro follows a three-phase pipeline:

1. **Parse** (`tusks-lib/src/parsing/`) — Convert `syn::ItemMod` into a `TusksModule` tree, validate return types, default functions, and Parameters structs.
2. **Supplement** (`tusks-lib/src/codegen/parameters/`) — Create missing `Parameters` structs, add `super_` fields for parent access, add lifetime markers.
3. **Generate** (`tusks-lib/src/codegen/cli/` and `codegen/handle_matches/`) — Emit the `__internal_tusks_module` containing clap `Cli` struct, `Commands` enum, and `handle_matches()` dispatch function.

### Building and Testing

```bash
# Build everything
cargo build --workspace

# Run all tests (unit + integration, excludes doctests)
cargo test --workspace --lib --tests

# Run all tests including doctests
cargo test --workspace

# Run only unit tests for a specific crate
cargo test -p tusks-tasks
cargo test -p tusks-lib --lib

# Run a specific integration test suite
cargo test -p tusks-test --test arg
cargo test -p tusks-test --test tasks

# Run compile-fail tests (verifies error messages for invalid macro input)
cargo test -p tusks-test --test compile_fail

# Run async feature tests (separate from workspace due to feature unification)
cd tusks-test-async && cargo test

# Format and lint
cargo fmt
cargo clippy
```

### Test Overview

The project has ~450 tests across multiple levels:

**Unit tests** (in source files via `#[cfg(test)]`):

| Location | Tests | What is tested |
|----------|-------|----------------|
| `tusks-tasks/src/task_list/models.rs` | 15 | Task sorting, collection operations, visibility filtering |
| `tusks-tasks/src/task_list/init.rs` | 14 | Command extraction, grouping algorithm, collapsing, hidden tasks |
| `tusks-tasks/src/list/conversion.rs` | 7 | TaskList-to-List conversion, separators, group headers |
| `tusks-tasks/src/list/print.rs` | 4 | Alignment calculation, unicode width handling |
| `tusks-tasks/src/list/models.rs` | 1 | RenderConfig defaults |
| `tusks-lib/src/parsing/attribute/parse.rs` | 20 | `#[tusks(...)]` and `tasks(...)` attribute parsing |
| `tusks-lib/src/parsing/tusk.rs` | 28 | Return type validation, default function argument rules, type checks |
| `tusks-lib/src/parsing/parameters.rs` | 9 | Parameters struct validation (public, references, reserved fields) |

**Integration tests** (`tusks-test/tests/`):

| File | Tests | What is tested |
|------|-------|----------------|
| `basic.rs` | 13 | Simple commands, flags, help, version |
| `arg.rs` | 52 | All argument types, edge cases (unicode, overflow, boundaries) |
| `parameters.rs` | 26 | Parameter chaining across module levels |
| `nested-modules.rs` | 31 | Deep nesting, help at every level, error paths |
| `external-modules.rs` | 36 | External module integration, parameter passing |
| `default-functions.rs` | 32 | Default command behavior, external subcommands |
| `return-values.rs` | 39 | Exit codes, custom return values |
| `command_attribute.rs` | 39 | Help text, about/long_about propagation |
| `tasks-mode.rs` | 32 | Flat task syntax, traditional syntax, task list |
| `tasks.rs` | 18 | Task list formatting, alignment, color disabling, sorting |
| `integration_tests.rs` | 32 | Deeply nested parameter chains, external modules |

**Compile-fail tests** (`tusks-test/tests/compile-fail/`):

These use `trybuild` to verify that invalid macro input produces clear compiler errors:

| File | What it verifies |
|------|-----------------|
| `invalid_return_type.rs` | `-> String` is rejected with helpful message |
| `i32_return_type.rs` | `-> i32` is rejected (only `()`, `u8`, `Option<u8>` allowed) |
| `duplicate_default.rs` | Two `#[default]` functions in one module are rejected |
| `private_parameters.rs` | Non-`pub` Parameters struct is rejected |
| `non_reference_parameter_field.rs` | `String` field (not `&String`) is rejected |
| `super_field_in_parameters.rs` | Manual `super_` field is rejected (auto-generated) |
| `unknown_tusks_attribute.rs` | `#[tusks(nonexistent)]` is rejected |
| `async_without_feature.rs` | `async fn` without `async` feature is rejected |

**Async tests** (`tusks-test-async/tests/`, run separately with `cd tusks-test-async && cargo test`):

| File | Tests | What is tested |
|------|-------|----------------|
| `async_basic.rs` | 8 | Async commands, mixed sync/async, nested async, return types |
