rsconstruct 0.9.148

Rust based fast build system
# Shell Completions

RSConstruct generates shell completion scripts that provide tab-completion for commands, subcommands, flags, and argument values.

## Generating Completions

```bash
# Generate for the default shell (configured in rsconstruct.toml)
rsconstruct complete

# Generate for a specific shell
rsconstruct complete bash
rsconstruct complete zsh
rsconstruct complete fish
```

To install, source the output in your shell profile:

```bash
# Bash (~/.bashrc)
eval "$(rsconstruct complete bash)"

# Zsh (~/.zshrc)
eval "$(rsconstruct complete zsh)"

# Fish (~/.config/fish/config.fish)
rsconstruct complete fish | source
```

## Configuration

The default shell(s) for `rsconstruct complete` (with no argument) are configured in `rsconstruct.toml`:

```toml
[completions]
shells = ["bash"]
```

## What Gets Completed

### Commands and subcommands

All top-level commands (`build`, `processor`, `analyzer`, `tool`, etc.) and their subcommands complete automatically via clap, in every shell.

### Processor type names (pnames)

Arguments that take a processor type name complete with the full names from the plugin registry (`processor.checker.ruff`, `processor.generator.cc_single_file`, ...):

- `rsconstruct processor add <TAB>`
- `rsconstruct processor defconfig <TAB>`
- `rsconstruct processor info <TAB>`

These arguments carry `#[arg(value_parser = crate::registries::processor_name_parser())]`, a `PossibleValuesParser` built from the registry when the completion script is generated, so clap embeds the list in the script itself. The bash and zsh scripts complete them; the fish script that clap generates carries possible values only for options, not positionals, so pnames do not complete there. Because the list is a `value_parser`, an unknown pname is also rejected at parse time with the list of valid ones.

### Processor instance names (inames)

Arguments that take a processor instance name complete with the section headers declared in the current directory's `rsconstruct.toml` (`processor.checker.ruff`, `processor.checker.ruff.core`, ...):

- `rsconstruct processor config <TAB>`
- `rsconstruct processor delete <TAB>`
- `rsconstruct processor disable <TAB>`
- `rsconstruct processor enable <TAB>`
- `rsconstruct processor files <TAB>`
- `rsconstruct build --processor <TAB>` / `rsconstruct build -p <TAB>`
- `rsconstruct build --exclude-processor <TAB>` / `rsconstruct build -x <TAB>`
- `rsconstruct watch --processor <TAB>` / `rsconstruct watch -p <TAB>`
- `rsconstruct watch --exclude-processor <TAB>` / `rsconstruct watch -x <TAB>`

`build`/`watch` `-p` and `-x` complete inames, not pnames: you can only build a processor that the project declares. Instance names are extracted from every `[processor.…]` heading in `rsconstruct.toml` at tab-completion time by a shell helper (`_rsconstruct_inames`) that the generated script carries; sub-tables that are config fields (`[processor.generator.tags.field_types]`) come out too, and the build rejects them with a clear message. Requires a `rsconstruct.toml` in the current directory. **Bash only** — zsh and fish get clap's default completion for these arguments.

### Analyzer type names (pnames)

- `rsconstruct analyzer add <TAB>`
- `rsconstruct analyzer defconfig <TAB>`

These carry `#[arg(value_parser = crate::registries::analyzer_name_parser())]`, a `PossibleValuesParser` over every registered analyzer (as listed by `rsconstruct analyzer list`), with the same per-shell behaviour as processor pnames.

### Analyzer instance names (inames)

- `rsconstruct analyzer delete <TAB>`
- `rsconstruct analyzer disable <TAB>`
- `rsconstruct analyzer enable <TAB>`

Instance names are read from the `[analyzer.NAME]` and `[analyzer.NAME.SUB]` headings in `rsconstruct.toml` at tab-completion time by the `_rsconstruct_analyzer_inames` helper. Bash only.

`analyzer config <INAME>` and `analyzer clean --analyzer <INAME>` have no completion of their values: their arguments are plain strings without a `value_parser` and are not injection targets.

### Flags and options

All `--flags` and `-f` short flags complete in all shells via clap's built-in generation, as do the values of `value_enum` options (`--color`, `-O`, `-I`, `-P`, `--stop-after`, `graph show --format`, ...).

## Implementation

Completions are generated by `clap_complete` in `src/cli.rs` (`generate_completion_script`). Two mechanisms provide argument-value completions:

### 1. clap `value_parser`

For a set of values that is known when the script is generated, the field carries `#[arg(value_parser = ...)]` and clap embeds the values in the script. The processor and analyzer registries are built by `inventory` at runtime, so their parsers are constructed from the registry rather than written as a literal list:

```rust
/// Show default configuration for a processor type by pname (no config needed)
Defconfig {
    #[arg(value_parser = crate::registries::processor_name_parser())]
    pname: String,
},
```

`processor_name_parser()` (`src/registries/processor.rs`) and `analyzer_name_parser()` (`src/registries/analyzer.rs`) return a `clap::builder::PossibleValuesParser` over every registered name.

### 2. Bash post-processing (instance names)

Instance names cannot be known when the script is generated — they live in whichever `rsconstruct.toml` the user is in when they press TAB. `inject_bash_processor_completions()` in `src/cli.rs` post-processes the generated bash script: it prepends the `_rsconstruct_inames` and `_rsconstruct_analyzer_inames` helper functions, then patches the `COMPREPLY` line of these case sections so that a positional (anything not starting with `-`) completes from the helper instead of the static `opts`:

- `rsconstruct__subcmd__processor__subcmd__config)`
- `rsconstruct__subcmd__processor__subcmd__delete)`
- `rsconstruct__subcmd__processor__subcmd__disable)`
- `rsconstruct__subcmd__processor__subcmd__enable)`
- `rsconstruct__subcmd__processor__subcmd__files)`
- `rsconstruct__subcmd__analyzer__subcmd__delete)`
- `rsconstruct__subcmd__analyzer__subcmd__disable)`
- `rsconstruct__subcmd__analyzer__subcmd__enable)`

It also replaces the `compgen -f` (file-name) completion that clap emits for the `--processor`/`-p` and `--exclude-processor`/`-x` option values with `_rsconstruct_inames`, wherever those options occur (`build` and `watch`).

`processor defconfig` is not an injection target: it is handled by its `value_parser`.

The function errors if any injection point is missing from the script — clap-complete owns the script format (the labels were once `rsconstruct__processor__files` and are now `rsconstruct__subcmd__processor__subcmd__files`), so a miss means its output changed and the labels or needles must be updated. The unit test `bash_iname_injection_matches_clap_complete_output` round-trips the real generated script, so a format change fails `cargo test` instead of surfacing when a user sources their completions.

This only works for bash. Other shells get the base clap completions without instance-name injection.

## Adding Completions for New Arguments

- **Set known at generation time** (processor or analyzer pnames, other registry-backed names): use `#[arg(value_parser = ...)]` with a `PossibleValuesParser` built from the registry. Works in bash and zsh; fish only for options.
- **Enum types**: use `#[arg(value_enum)]` on a clap-derived enum. Works in all shells.
- **Instance names from `rsconstruct.toml`**: add the case label (`rsconstruct__subcmd__<cmd>__subcmd__<sub>)`) to the target list in `inject_bash_processor_completions()`. Bash only.