feat(formatter): add --check flag for CI validation

This commit introduces a new `--check` flag to the `format` command, designed specifically for use in CI/CD pipelines and other automated environments.

When run with `--check`, the formatter will:

- Exit with a success code (`0`) if all files are correctly formatted.
- Exit with a failure code (`1`) if any file needs formatting changes.
- Produce no output to `stdout`, relying solely on the exit code for status.

This provides a clean and efficient way to enforce code style without cluttering CI logs with diffs.

To support this, the internal formatting pipeline has been refactored to use a `FormatMode` enum (`Format`,
`Check`, `DryRun`) instead of a simple boolean for dry runs. Argument conflicts have also been added to ensure
that `--check`, `--dry-run`, and `--stdin-input` are mutually exclusive.

Signed-off-by: azjezz <[email protected]>

Author: azjezz

src/commands/args/reporting.rs

@@ -277,7 +277,7 @@ impl ReportingArgs {
                     }
                 }
 
-                let changed = utils::apply_update(&change_log, file, fixed_content, self.dry_run)?;
+                let changed = utils::apply_update(&change_log, file, fixed_content, self.dry_run, false)?;
                 progress_bar.inc(1);
                 Ok(changed)
             })

src/commands/format.rs

@@ -15,6 +15,7 @@ use crate::config::Configuration;
 use crate::database;
 use crate::error::Error;
 use crate::pipeline::format::FormatContext;
+use crate::pipeline::format::FormatMode;
 use crate::pipeline::format::run_format_pipeline;
 
 /// Represents the `format` command, which is responsible for formatting source files
@@ -35,11 +36,37 @@ pub struct FormatCommand {
     #[arg(help = "Format specific files or directories, overriding the source configuration")]
     pub path: Vec<PathBuf>,
 
-    /// Perform a dry run to check if files are already formatted.
-    #[arg(long, short = 'd', help = "Check if the source files are already formatted without making changes")]
+    /// Perform a dry run, printing a diff without modifying files.
+    ///
+    /// This will calculate and print a diff of any changes that would be made.
+    /// No files will be modified on disk.
+    #[arg(
+        long,
+        short = 'd',
+        help = "Print a diff of changes without modifying files",
+        conflicts_with_all = ["check", "stdin_input"],
+    )]
     pub dry_run: bool,
 
-    #[arg(long, short = 'i', help = "Read input from STDIN, format it, and write to STDOUT")]
+    /// Check if the source files are formatted.
+    ///
+    /// This flag is ideal for CI environments. The command will exit with a
+    /// success code (`0`) if all files are formatted, and a failure code (`1`)
+    /// if any files would be changed. No output is printed to `stdout`.
+    #[arg(
+        long,
+        short = 'c',
+        help = "Check if files are formatted, exiting with a non-zero status code on changes",
+        conflicts_with_all = ["dry_run", "stdin_input"],
+    )]
+    pub check: bool,
+
+    #[arg(
+        long,
+        short = 'i',
+        help = "Read input from STDIN, format it, and write to STDOUT",
+        conflicts_with_all = ["dry_run", "check", "path"],
+    )]
     pub stdin_input: bool,
 }
 
@@ -84,7 +111,13 @@ pub fn execute(command: FormatCommand, mut configuration: Configuration) -> Resu
     let shared_context = FormatContext {
         php_version: configuration.php_version,
         settings: configuration.formatter.settings,
-        dry_run: command.dry_run,
+        mode: if command.dry_run {
+            FormatMode::DryRun
+        } else if command.check {
+            FormatMode::Check
+        } else {
+            FormatMode::Format
+        },
         change_log: change_log.clone(),
     };
 
@@ -98,7 +131,7 @@ pub fn execute(command: FormatCommand, mut configuration: Configuration) -> Resu
         return Ok(ExitCode::SUCCESS);
     }
 
-    Ok(if command.dry_run {
+    Ok(if command.dry_run || command.check {
         tracing::info!("Found {} file(s) that need formatting.", changed_count);
         ExitCode::FAILURE
     } else {

src/pipeline/format.rs

@@ -24,15 +24,25 @@ impl StatelessReducer<bool, usize> for FormatReducer {
     }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FormatMode {
+    /// Apply formatting changes to files.
+    Format,
+    /// Check if files are formatted without making changes.
+    Check,
+    /// Print a diff of changes without modifying files.
+    DryRun,
+}
+
 /// Shared, read-only context provided to each parallel formatting task.
 #[derive(Clone)]
 pub struct FormatContext {
     /// The target PHP version for formatting rules.
     pub php_version: PHPVersion,
     /// The configured settings for the formatter.
     pub settings: FormatSettings,
-    /// If `true`, the pipeline will only check for changes and not modify files.
-    pub dry_run: bool,
+    /// The mode of operation: format, check, or dry-run.
+    pub mode: FormatMode,
     /// A thread-safe log for recording formatting changes.
     pub change_log: ChangeLog,
 }
@@ -69,7 +79,13 @@ pub fn run_format_pipeline(
             let formatter = Formatter::new(&interner, context.php_version, context.settings);
             let formatted_content = formatter.format(&file, &program);
 
-            utils::apply_update(&context.change_log, &file, formatted_content, context.dry_run)
+            utils::apply_update(
+                &context.change_log,
+                &file,
+                formatted_content,
+                matches!(context.mode, FormatMode::DryRun),
+                matches!(context.mode, FormatMode::Check),
+            )
         },
     )
 }

src/utils/mod.rs

@@ -33,11 +33,16 @@ pub fn apply_update(
     file: &File,
     modified_contents: String,
     dry_run: bool,
+    check: bool,
 ) -> Result<bool, Error> {
     if file.contents == modified_contents {
         return Ok(false);
     }
 
+    if check {
+        return Ok(true);
+    }
+
     if dry_run {
         let patch = diffy::create_patch(&file.contents, modified_contents.as_str());