feat(cli): add recursive traversal (#98)

Author: maksym-arutyunyan

.github/workflows/workflow.yaml

@@ -138,7 +138,8 @@ jobs:
       - name: Run KeepSorted
         shell: bash
         run: |
-          # keepsorted works only with file paths; filter tracked files first.
+          # keepsorted can walk directories with --recursive, but we filter tracked files
+          # explicitly to avoid processing examples or tests during validation.
           git ls-files -z \
             | grep -vzE '^tests/|^e2e-tests/|^README.md$' \
             | xargs -0 -n1 ./target/release/keepsorted \

CHANGELOG.md

@@ -11,8 +11,8 @@ format and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
  - `--diff-command` option to delegate diff generation to an external tool
  - Buildifier-style exit codes with `4` indicating failed check mode
 
-### Changed
- - Removed `--recursive` flag; use shell tools to process directories
+### Added
+ - `--recursive` (`-r`) flag to process directories recursively
 
 ### Fixed
 - Show a usage error when an unknown feature is specified

README.md

@@ -25,15 +25,14 @@ cargo install keepsorted
 - `keepsorted --check <path>` verifies sorting without modifying files.
 - `keepsorted --diff <path>` shows a diff of required changes.
 - `keepsorted --fix <path>` updates files in place.
-- keepsorted only processes a single file at a time. Directory traversal and filtering are left to shell tools like `git ls-files` so that you can easily include or exclude paths. See [Architecture](docs/architecture.md) for details.
+- By default `keepsorted` processes a single file. Use `--recursive` (`-r`) to walk a directory and format every supported file. For complex include/exclude rules, combine `keepsorted` with shell tools like `git ls-files`. See [Architecture](docs/architecture.md) for details.
 
 Run `keepsorted --check` in CI after filtering tracked files with
 `git ls-files` to prevent unsorted changes.
 
 ### Pre-commit hook
 
-keepsorted only accepts explicit file paths. To scan all tracked files except
-the test directories, save this script as `.git/hooks/pre-commit`:
+keepsorted requires explicit paths unless you enable `--recursive`. To scan all tracked files except the test directories, save this script as `.git/hooks/pre-commit`:
 
 ```shell
 #!/bin/sh

docs/architecture.md

@@ -60,7 +60,7 @@ Each file under `src/strategies/` provides a `process` function that sorts lines
 
 ### CLI (`src/main.rs`)
 
-`main.rs` implements the command-line interface using `clap`. It parses arguments, selects the formatting mode (check, diff or fix) and passes a single file to `handle_file`. Directory traversal is intentionally left to external scripts so that the binary stays simple and composable. There is deliberately no `-r` or `--recursive` option; use tools like `git ls-files` if you need to process multiple files. The helper `handle_file` runs the crate API on each file and applies the chosen mode.
+`main.rs` implements the command-line interface using `clap`. It parses arguments, selects the formatting mode (check, diff or fix) and processes files via `handle_file`. The CLI now supports a basic `-r`/`--recursive` flag to walk the provided directory and run `keepsorted` on every supported file it finds. This is convenient for simple use cases where users want to sort all files under the current directory. For more advanced setups that require ignoring particular paths, callers can still generate the file list themselves with tools like `find` or `git ls-files` and pass each path explicitly. The helper `handle_file` runs the crate API on each file and applies the chosen mode.
 
 When `--mode diff` is used, the CLI can delegate diff generation to an external
 program by passing `--diff-command <command>`. The option is parsed and executed
@@ -96,7 +96,7 @@ Rust unit tests inside `tests/` verify the behaviour of individual strategies fo
 
 To stay focused and composable, `keepsorted` does **not** aim to:
 
-- Perform recursive directory traversal (use external tools like `find`, `git ls-files`, or CI filters)
+- Handle advanced directory traversal or ignore rules automatically
 - Act as a full-fledged parser for every supported file type
 - Handle ignore files or exclude paths automatically
 - Automatically detect project structure or configuration files

e2e-tests/directory_error.bats

@@ -7,6 +7,7 @@ Arguments:
 
 Options:
   -p, --path <PATH>             File to process (conflicts with positional path)
+  -r, --recursive               Process directories recursively
   -f, --features <FEATURE>      Enable experimental features [possible values: gitignore, codeowners, rust_derive_alphabetical, rust_derive_canonical]
       --check                   alias for '--mode check'
       --diff                    alias for '--mode diff'

e2e-tests/files/help.txt

@@ -19,6 +19,9 @@ Options:
   -p, --path <PATH>
           File to process (conflicts with positional path)
 
+  -r, --recursive
+          Process directories recursively
+
   -f, --features <FEATURE>
           Enable experimental features
 

e2e-tests/files/help_long.txt

@@ -0,0 +1,13 @@
+#!/usr/bin/env bats
+
+load './helpers.bash'
+
+@test "process directory recursively" {
+  mkdir "$TEST_TMPDIR/dir"
+  cp "$FILES_DIR/generic/1_in.txt" "$TEST_TMPDIR/dir/file.txt"
+
+  run_keepsorted --mode fix --recursive "$TEST_TMPDIR/dir"
+  [ "$status" -eq "$EXIT_SUCCESS" ]
+  diff "$FILES_DIR/generic/1_out.txt" "$TEST_TMPDIR/dir/file.txt"
+}
+

e2e-tests/recursive.bats

@@ -25,7 +25,8 @@ clippy_status=$?
 cargo fmt --all -- --check
 fmt_status=$?
 
-# keepsorted accepts only explicit file paths, so filter tracked files first.
+# keepsorted can walk directories with --recursive, but we filter tracked files
+# explicitly to avoid processing examples or tests during validation.
 git ls-files -z \
   | grep -vzE '^tests/|^e2e-tests/|^README.md$' \
   | xargs -0 -n1 ./target/release/keepsorted \

run-all.sh

@@ -1,7 +1,7 @@
 use clap::{arg, command, Parser, ValueEnum};
 use keepsorted::process_file;
 use std::io;
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use std::process::{self, Command};
 
 /// Exit code used when the command is invoked incorrectly.
@@ -110,6 +110,10 @@ struct Args {
     )]
     positional_path: Option<String>,
 
+    /// Recursively traverse directories for files
+    #[arg(short = 'r', long, help = "Process directories recursively")]
+    recursive: bool,
+
     #[arg(
         short = 'f',
         long,
@@ -190,12 +194,29 @@ fn main() {
     let mut exit_code = 0;
 
     if path.is_dir() {
-        eprintln!(
-            "{}: read {}: is a directory",
-            env!("CARGO_PKG_NAME"),
-            path.display()
-        );
-        process::exit(EXIT_USAGE_ERROR);
+        if !args.recursive {
+            eprintln!(
+                "{}: read {}: is a directory",
+                env!("CARGO_PKG_NAME"),
+                path.display()
+            );
+            process::exit(EXIT_USAGE_ERROR);
+        }
+        let mut files = Vec::new();
+        if let Err(e) = collect_files(path, &mut files) {
+            eprintln!(
+                "{}: failed to read directory {}: {}",
+                env!("CARGO_PKG_NAME"),
+                path.display(),
+                e
+            );
+            process::exit(EXIT_RUNTIME_ERROR);
+        }
+        for file in files {
+            if !handle_file(&file, &features, mode, args.diff_command.as_deref()) {
+                exit_code = EXIT_CHECK_FAILED;
+            }
+        }
     } else if !handle_file(path, &features, mode, args.diff_command.as_deref()) {
         exit_code = EXIT_CHECK_FAILED;
     }
@@ -335,3 +356,16 @@ fn handle_file(path: &Path, features: &[Feature], mode: Mode, diff_command: Opti
         }
     }
 }
+
+fn collect_files(dir: &Path, out: &mut Vec<PathBuf>) -> io::Result<()> {
+    for entry in std::fs::read_dir(dir)? {
+        let entry = entry?;
+        let path = entry.path();
+        if path.is_dir() {
+            collect_files(&path, out)?;
+        } else if path.is_file() {
+            out.push(path);
+        }
+    }
+    Ok(())
+}