torrust-linting 0.1.0

Linting utilities for Torrust projects
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

# Torrust Linting

[![Linting](https://github.com/torrust/torrust-linting/actions/workflows/linting.yml/badge.svg)](https://github.com/torrust/torrust-linting/actions/workflows/linting.yml)

A unified linting library and CLI for Torrust projects. Provides a single binary that runs all project linters consistently across the organization.

## Features

- **Multiple Linters**: Markdown, YAML, TOML, Rust (clippy + rustfmt), shell scripts, and spell checking
- **CLI Ready**: Pre-built CLI binary (`linter`) with subcommands for each linter
- **Library**: Use individual linter functions in your own Rust code or build a custom CLI
- **Extensible**: Easy to add new linters
- **Auto-install**: Automatically installs missing tools (npm-based, system package manager)

## Usage

### As a binary

Run the `linter` binary directly:

```sh
cargo run             # Run all linters (default)
cargo run -- markdown   # Run markdown linter
cargo run -- yaml       # Run YAML linter
cargo run -- toml       # Run TOML linter
cargo run -- cspell     # Run CSpell spell checker
cargo run -- clippy     # Run Rust clippy linter
cargo run -- rustfmt    # Run Rust formatter check
cargo run -- shellcheck # Run ShellCheck linter
cargo run -- all        # Run all linters
```

### As a library dependency

Add to your `Cargo.toml`:

```toml
[dependencies]
torrust-linting = "0.1.0"
```

#### Option 1: Use the complete CLI (easiest)

```rust
use anyhow::Result;

fn main() -> Result<()> {
    torrust_linting::run_cli()
}
```

#### Option 2: Custom CLI implementation

```rust
use anyhow::Result;
use clap::Parser;
use torrust_linting::{Cli, execute_command, init_tracing};

fn main() -> Result<()> {
    init_tracing();
    let cli = Cli::parse();
    execute_command(cli.command.as_ref())?;
    Ok(())
}
```

#### Option 3: Use individual linters programmatically

```rust
use anyhow::Result;
use torrust_linting::{run_rustfmt_linter, run_clippy_linter, run_all_linters};

fn main() -> Result<()> {
    run_rustfmt_linter()?;
    run_clippy_linter()?;
    // Or run everything at once:
    run_all_linters()?;
    Ok(())
}
```

See the [`examples/`](examples/) directory for more usage patterns.

## External tools required

Some linters delegate to external tools. The library will attempt to install missing tools automatically, but you can also install them manually:

| Linter      | Tool                        | Install                                          |
| ----------- | --------------------------- | ------------------------------------------------ |
| Markdown    | `markdownlint`              | `npm install -g markdownlint-cli`                |
| YAML        | `yamllint`                  | `apt install yamllint` / `pip3 install yamllint` |
| TOML        | `taplo`                     | `cargo install taplo-cli --locked`               |
| Spell check | `cspell`                    | `npm install -g cspell`                          |
| Shell       | `shellcheck`                | `apt install shellcheck`                         |
| Rust        | `cargo clippy`, `cargo fmt` | bundled with `rustup`                            |

## Configuration files expected in the project root

The linters read configuration from well-known files in the working directory:

| File                 | Used by      |
| -------------------- | ------------ |
| `.markdownlint.json` | markdownlint |
| `.yamllint-ci.yml`   | yamllint     |
| `.taplo.toml`        | taplo        |
| `cspell.json`        | cspell       |

## License

Copyright (c) 2026 Torrust. See [LICENSE](LICENSE).