feat: add CSpell linter integration

- Add packages/linting/src/linters/cspell.rs following markdown.rs pattern
- Integrate CSpell command into CLI with 'spell' alias
- Update copilot instructions to include CSpell in linter list
- Add comprehensive spelling guide in docs/contributing/spelling.md
- Configure cspell.json to ignore data/ and build/ folders
- Add project-specific terms (torrust, clippy, reqwest) to dictionary
- Auto-install CSpell via npm if not present
- Include helpful error messages and fix instructions

Author: josecelano

.github/copilot-instructions.md

@@ -78,7 +78,7 @@ These principles should guide all development decisions, code reviews, and featu
 ## 🧪 Build & Test
 
 - **Lint**: `cargo run --bin linter all` (comprehensive - tests stable & nightly toolchains)
-  - Individual linters: `cargo run --bin linter {markdown|yaml|toml|clippy|rustfmt|shellcheck}`
+  - Individual linters: `cargo run --bin linter {markdown|yaml|toml|cspell|clippy|rustfmt|shellcheck}`
   - Alternative: `./scripts/lint.sh` (wrapper that calls the Rust binary)
 - **Dependencies**: `cargo machete` (mandatory before commits - no unused dependencies)
 - **Build**: `cargo build`

cspell.json

@@ -13,6 +13,8 @@
     ],
     "ignorePaths": [
         "target",
+        "data",
+        "build",
         "/project-words.txt"
     ]
 }

docs/contributing/spelling.md

@@ -0,0 +1,230 @@
+# Spelling Guide
+
+This document explains how we handle spelling in the Torrust Tracker Deploy project using CSpell.
+
+## 🎯 Overview
+
+We use [CSpell](https://cspell.org/) for spell checking across all project files including documentation, comments, and code identifiers. This helps maintain consistency and professionalism in our codebase.
+
+## 📋 Configuration
+
+### CSpell Configuration
+
+Our spell checking is configured through `cspell.json` in the project root:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
+  "version": "0.2",
+  "dictionaryDefinitions": [
+    {
+      "name": "project-words",
+      "path": "./project-words.txt",
+      "addWords": true
+    }
+  ],
+  "dictionaries": ["project-words"],
+  "ignorePaths": ["target", "/project-words.txt"]
+}
+```
+
+### Project Dictionary
+
+The `project-words.txt` file contains:
+
+- Technical terms specific to our domain
+- Proper nouns (company names, product names)
+- Acronyms and abbreviations
+- Valid identifiers that aren't in standard dictionaries
+
+## 🚀 Running Spell Checks
+
+### Via Linting System
+
+```bash
+# Run CSpell individually
+cargo run --bin linter cspell
+
+# Run all linters including CSpell
+cargo run --bin linter all
+```
+
+### Direct CSpell Commands
+
+```bash
+# Check all files
+cspell .
+
+# Check with suggestions and context
+cspell . --no-progress --show-suggestions --show-context
+
+# Check specific files
+cspell "src/**/*.rs" "docs/**/*.md"
+
+# Get list of unknown words
+cspell --words-only --unique .
+```
+
+## 🔧 Fixing Spelling Issues
+
+### 1. Fix Actual Misspellings
+
+For genuine spelling errors, fix them directly in the source files.
+
+### 2. Add Valid Terms to Dictionary
+
+For legitimate technical terms, proper nouns, or domain-specific vocabulary:
+
+```bash
+# Add words to project-words.txt (one per line, sorted alphabetically)
+echo "kubernetes" >> project-words.txt
+echo "dockerfile" >> project-words.txt
+sort -u project-words.txt -o project-words.txt
+```
+
+### 3. Handle Special Cases
+
+#### Code Identifiers
+
+Valid variable names, function names, and identifiers should be added to the dictionary:
+
+```text
+# Examples in project-words.txt
+ansible
+containerd
+rustfmt
+shellcheck
+torrust
+```
+
+#### Tokens and Keys
+
+For security tokens, API keys, and similar strings, there are several approaches:
+
+1. **Add to Dictionary (Recommended)**:
+
+   ```text
+   # In project-words.txt - for test/fixture tokens only
+   AAAAB
+   EAAAADAQABAAABAQC
+   ```
+
+2. **Use CSpell Ignore Comments**:
+
+   ```rust
+   // cspell:disable-next-line
+   const API_TOKEN: &str = "abc123def456ghi789";
+
+   /* cspell:disable */
+   const COMPLEX_TOKEN: &str = "very-long-generated-token-here";
+   /* cspell:enable */
+   ```
+
+3. **Configuration Patterns**:
+
+   ```json
+   {
+     "ignoreRegExpList": ["/auth_token: .*/g", "/api[_-]key: .*/gi"]
+   }
+   ```
+
+## 📝 Best Practices
+
+### Do Add to Dictionary
+
+- ✅ Technical terms: `kubernetes`, `dockerfile`, `ansible`
+- ✅ Project names: `torrust`, `opentofu`
+- ✅ Tool names: `rustfmt`, `shellcheck`, `yamllint`
+- ✅ Domain concepts: `provisioning`, `infra`
+- ✅ Test fixture data (non-sensitive)
+
+### Don't Add to Dictionary
+
+- ❌ Actual misspellings
+- ❌ Typos in variable names
+- ❌ Real secrets or production tokens
+- ❌ Random strings that could mask real errors
+
+### Guidelines for Adding Words
+
+1. **Be Conservative**: Only add words you're confident are correct
+2. **Use Lowercase**: Add words in lowercase unless they're proper nouns
+3. **Check Alternatives**: Consider if there's a standard spelling first
+4. **Document Context**: Add comments in `project-words.txt` for unusual terms
+
+Example `project-words.txt` structure:
+
+```text
+# Infrastructure and DevOps
+ansible
+containerd
+dockerfile
+kubernetes
+multipass
+opentofu
+
+# Project-specific terms
+torrust
+rustfmt
+shellcheck
+
+# Test fixtures (non-sensitive)
+testkey
+mocksecret
+```
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+1. **Too Many False Positives**
+
+   - Review and clean up the project dictionary
+   - Use more specific ignore patterns
+   - Consider CSpell ignore comments for edge cases
+
+2. **Missing Technical Terms**
+
+   - Add them to `project-words.txt`
+   - Keep them lowercase unless proper nouns
+   - Sort alphabetically for maintainability
+
+3. **Generated or Binary Content**
+   - Add paths to `ignorePaths` in `cspell.json`
+   - Use glob patterns to exclude file types
+
+### Getting Help
+
+- Check CSpell suggestions: `cspell --show-suggestions <file>`
+- View CSpell documentation: [https://cspell.org/docs/](https://cspell.org/docs/)
+- Review existing patterns in `cspell.json`
+
+## 🧪 Integration with Development Workflow
+
+### Pre-commit Checks
+
+CSpell is included in the mandatory pre-commit checks:
+
+```bash
+cargo run --bin linter all  # Includes CSpell
+```
+
+### CI/CD Integration
+
+The spell checker runs automatically in CI/CD pipelines as part of the linting process.
+
+### IDE Integration
+
+Consider installing CSpell extensions for your IDE:
+
+- VS Code: "Code Spell Checker" extension
+- Other IDEs: Check CSpell documentation for integration options
+
+## 🎯 Goals
+
+- **Consistency**: Maintain professional spelling across all project content
+- **Quality**: Catch typos early in the development process
+- **Maintainability**: Keep a clean, well-organized project dictionary
+- **Developer Experience**: Provide clear guidance for handling spelling issues
+
+By following these guidelines, we ensure that our codebase maintains high quality while accommodating the technical nature of our domain vocabulary.

packages/linting/src/cli.rs

@@ -3,8 +3,8 @@ use clap::{CommandFactory, Parser, Subcommand};
 use tracing::{error, info, Level};
 
 use crate::linters::{
-    run_clippy_linter, run_markdown_linter, run_rustfmt_linter, run_shellcheck_linter,
-    run_toml_linter, run_yaml_linter,
+    run_clippy_linter, run_cspell_linter, run_markdown_linter, run_rustfmt_linter,
+    run_shellcheck_linter, run_toml_linter, run_yaml_linter,
 };
 
 /// Initialize tracing with default configuration
@@ -54,6 +54,10 @@ pub enum Commands {
     /// Run TOML linter using Taplo
     Toml,
 
+    /// Run `CSpell` spell checker
+    #[command(alias = "spell")]
+    Cspell,
+
     /// Run Rust clippy linter
     Clippy,
 
@@ -106,6 +110,15 @@ pub fn run_all_linters() -> Result<()> {
         }
     }
 
+    // Run CSpell spell checker
+    match run_cspell_linter() {
+        Ok(()) => {}
+        Err(e) => {
+            error!("Spell checking failed: {e}");
+            failed = true;
+        }
+    }
+
     // Run Rust clippy linter
     match run_clippy_linter() {
         Ok(()) => {}
@@ -157,6 +170,9 @@ pub fn execute_command(command: Option<&Commands>) -> Result<()> {
         Some(Commands::Toml) => {
             run_toml_linter()?;
         }
+        Some(Commands::Cspell) => {
+            run_cspell_linter()?;
+        }
         Some(Commands::Clippy) => {
             run_clippy_linter()?;
         }
@@ -187,6 +203,7 @@ pub fn print_usage_examples() {
     println!("  cargo run --bin linter markdown   # Run markdown linter");
     println!("  cargo run --bin linter yaml       # Run YAML linter");
     println!("  cargo run --bin linter toml       # Run TOML linter");
+    println!("  cargo run --bin linter cspell     # Run CSpell spell checker");
     println!("  cargo run --bin linter clippy     # Run Rust clippy linter");
     println!("  cargo run --bin linter rustfmt    # Run Rust formatter check");
     println!("  cargo run --bin linter shellcheck # Run ShellCheck linter");

packages/linting/src/linters/cspell.rs

@@ -0,0 +1,53 @@
+use anyhow::Result;
+use std::process::Command;
+use tracing::{error, info};
+
+use crate::utils::{install_npm_tool, is_command_available};
+
+/// Run the `CSpell` spell checker linter
+///
+/// # Errors
+///
+/// Returns an error if `CSpell` is not available, cannot be installed,
+/// or if the spell checking fails.
+pub fn run_cspell_linter() -> Result<()> {
+    // Check if cspell is installed
+    if !is_command_available("cspell") {
+        install_npm_tool("cspell")?;
+    }
+
+    // Run the spell checker
+    info!(target: "cspell", "Running spell check on all files...");
+
+    // Run cspell on the entire project (it will use cspell.json configuration)
+    let mut cmd = Command::new("cspell");
+    cmd.args([".", "--no-progress", "--show-context"]);
+
+    let output = cmd.output()?;
+
+    if output.status.success() {
+        info!(target: "cspell", "All files passed spell checking!");
+        Ok(())
+    } else {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        let stdout = String::from_utf8_lossy(&output.stdout);
+
+        // Print the output from cspell (it usually goes to stdout)
+        if !stdout.is_empty() {
+            println!("{stdout}");
+        }
+        if !stderr.is_empty() {
+            eprintln!("{stderr}");
+        }
+
+        println!();
+        println!("💡 To fix spelling issues:");
+        println!("  1. Fix actual misspellings in the files");
+        println!("  2. Add technical terms/proper nouns to project-words.txt");
+        println!("  3. Use cspell suggestions: cspell --show-suggestions <file>");
+        println!();
+
+        error!(target: "cspell", "Spell checking failed. Please fix the issues above.");
+        Err(anyhow::anyhow!("Spell checking failed"))
+    }
+}

packages/linting/src/linters/mod.rs

@@ -1,11 +1,13 @@
 pub mod clippy;
+pub mod cspell;
 pub mod markdown;
 pub mod rustfmt;
 pub mod shellcheck;
 pub mod toml;
 pub mod yaml;
 
 pub use clippy::*;
+pub use cspell::*;
 pub use markdown::*;
 pub use rustfmt::*;
 pub use shellcheck::*;

project-words.txt

@@ -3,6 +3,7 @@ architecting
 autorestart
 buildx
 childlogdir
+clippy
 cloneable
 cloudinit
 connrefused
@@ -61,6 +62,7 @@ Pulumi
 pytest
 RAII
 Repomix
+reqwest
 resolv
 rpcinterface
 runcmd
@@ -96,6 +98,8 @@ thiserror
 tlsv
 tmpfiles
 tmpfs
+torrust
+Torrust
 usermod
 usize
 utmp