feat(cli): add minimal agent output mode

Author: JoviDeCroock

apps/oxfmt/src/cli/command.rs

@@ -23,6 +23,8 @@ pub struct FormatCommand {
     #[bpaf(external(mode))]
     pub mode: Mode,
     #[bpaf(external)]
+    pub output_options: OutputOptions,
+    #[bpaf(external)]
     pub config_options: ConfigOptions,
     #[bpaf(external)]
     pub ignore_options: IgnoreOptions,
@@ -128,6 +130,14 @@ fn output_mode() -> impl bpaf::Parser<OutputMode> {
     bpaf::construct!([write, check, list_different]).group_help("Output Options:")
 }
 
+/// Output options
+#[derive(Debug, Clone, Bpaf)]
+pub struct OutputOptions {
+    /// Reduce CLI output for agents: print only changed paths and one-line diagnostics
+    #[bpaf(long("minimal"), switch, hide)]
+    pub minimal: bool,
+}
+
 /// Migration Source
 #[cfg(feature = "napi")]
 #[derive(Debug, Clone)]
@@ -173,3 +183,16 @@ pub struct RuntimeOptions {
     #[bpaf(argument("INT"), hide_usage)]
     pub threads: Option<usize>,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{Mode, OutputMode, format_command};
+
+    #[test]
+    fn minimal_output_option() {
+        let command = format_command().run_inner(&["--minimal", "--check", "."]).unwrap();
+
+        assert!(command.output_options.minimal);
+        assert!(matches!(command.mode, Mode::Cli(OutputMode::Check)));
+    }
+}

apps/oxfmt/src/cli/reporter.rs

@@ -1,6 +1,6 @@
 use oxc_diagnostics::{
-    Error, GraphicalReportHandler,
-    reporter::{DiagnosticReporter, DiagnosticResult},
+    Error, GraphicalReportHandler, Severity,
+    reporter::{DiagnosticReporter, DiagnosticResult, Info},
 };
 
 // This reporter is used with stderr and displays diagnostics only in a graphical way.
@@ -36,3 +36,85 @@ impl DiagnosticReporter for DefaultReporter {
         Some(output)
     }
 }
+
+#[derive(Debug, Default)]
+pub struct MinimalReporter;
+
+impl DiagnosticReporter for MinimalReporter {
+    fn finish(&mut self, _result: &DiagnosticResult) -> Option<String> {
+        None
+    }
+
+    fn supports_minified_file_fallback(&self) -> bool {
+        false
+    }
+
+    fn render_error(&mut self, error: Error) -> Option<String> {
+        Some(format_minimal(&error))
+    }
+}
+
+fn format_minimal(diagnostic: &Error) -> String {
+    let Info { start, filename, .. } = Info::new(diagnostic);
+    let filename = if filename.is_empty() {
+        diagnostic
+            .source_code()
+            .and_then(miette::SourceCode::name)
+            .map_or_else(|| "<unknown>".to_string(), ToString::to_string)
+    } else {
+        filename
+    };
+    let severity = match diagnostic.severity() {
+        Some(Severity::Warning) => "warning",
+        Some(Severity::Advice) => "advice",
+        _ => "error",
+    };
+    let message = compact_message(&diagnostic.to_string());
+
+    if start.line == 0 {
+        format!("{filename}: {severity}: {message}\n")
+    } else {
+        format!("{filename}:{}:{}: {severity}: {message}\n", start.line, start.column)
+    }
+}
+
+fn compact_message(message: &str) -> String {
+    let mut compact = String::new();
+    for word in message.split_whitespace() {
+        if !compact.is_empty() {
+            compact.push(' ');
+        }
+        compact.push_str(word);
+    }
+    compact
+}
+
+#[cfg(test)]
+mod tests {
+    use oxc_diagnostics::{NamedSource, OxcDiagnostic, reporter::DiagnosticReporter};
+    use oxc_span::Span;
+
+    use super::MinimalReporter;
+
+    #[test]
+    fn minimal_reporter_with_label() {
+        let mut reporter = MinimalReporter;
+        let error = OxcDiagnostic::error("Unexpected token")
+            .with_label(Span::new(0, 1))
+            .with_source_code(NamedSource::new("file.js", "!"));
+
+        assert_eq!(reporter.render_error(error).unwrap(), "file.js:1:1: error: Unexpected token\n");
+    }
+
+    #[test]
+    fn minimal_reporter_without_label() {
+        let mut reporter = MinimalReporter;
+        let error = OxcDiagnostic::error("Failed to save file\npermission denied")
+            .with_source_code(NamedSource::new("file.js", ""));
+
+        assert_eq!(
+            reporter.render_error(error).unwrap(),
+            "file.js: error: Failed to save file permission denied\n"
+        );
+    }
+}

apps/oxfmt/src/cli/service.rs

@@ -22,14 +22,20 @@ pub struct FormatService {
     cwd: Box<Path>,
     format_mode: OutputMode,
     formatter: SourceFormatter,
+    minimal_output: bool,
 }
 
 impl FormatService {
-    pub fn new<T>(cwd: T, format_mode: OutputMode, formatter: SourceFormatter) -> Self
+    pub fn new<T>(
+        cwd: T,
+        format_mode: OutputMode,
+        formatter: SourceFormatter,
+        minimal_output: bool,
+    ) -> Self
     where
         T: Into<Box<Path>>,
     {
-        Self { cwd: cwd.into(), format_mode, formatter }
+        Self { cwd: cwd.into(), format_mode, formatter, minimal_output }
     }
 
     /// Process entries as they are received from the channel
@@ -40,7 +46,9 @@ impl FormatService {
         tx_success: &mpsc::Sender<SuccessResult>,
     ) {
         rx_entry.into_iter().par_bridge().for_each(|strategy| {
-            let start_time = matches!(self.format_mode, OutputMode::Check).then(Instant::now);
+            let start_time = (matches!(self.format_mode, OutputMode::Check)
+                && !self.minimal_output)
+                .then(Instant::now);
 
             let path: Arc<Path> = Arc::clone(strategy.path());
             let Ok(source_text) = utils::read_to_string(&path) else {
@@ -108,7 +116,7 @@ impl FormatService {
                         .cow_replace('\\', "/")
                         .to_string();
 
-                    if matches!(self.format_mode, OutputMode::Check) {
+                    if matches!(self.format_mode, OutputMode::Check) && !self.minimal_output {
                         let elapsed = start_time.unwrap().elapsed().as_millis();
                         SuccessResult::Changed(format!("{display_path} ({elapsed}ms)"))
                     } else {

apps/oxfmt/src/cli/walk_runner.rs

@@ -1,10 +1,10 @@
 use std::{env, io::BufWriter, path::PathBuf, sync::mpsc, time::Instant};
 
-use oxc_diagnostics::DiagnosticService;
+use oxc_diagnostics::{DiagnosticService, reporter::DiagnosticReporter};
 
 use super::{
     command::{FormatCommand, Mode, OutputMode},
-    reporter::DefaultReporter,
+    reporter::{DefaultReporter, MinimalReporter},
     resolve::resolve_ignore_paths,
     result::CliRunResult,
     service::{FormatService, SuccessResult},
@@ -69,13 +69,20 @@ impl WalkRunner {
         let start_time = Instant::now();
 
         let cwd = self.cwd;
-        let FormatCommand { paths, mode, config_options, ignore_options, runtime_options } =
-            self.options;
+        let FormatCommand {
+            paths,
+            mode,
+            output_options,
+            config_options,
+            ignore_options,
+            runtime_options,
+        } = self.options;
         // If `napi` feature is disabled, there is no other mode.
         #[cfg_attr(not(feature = "napi"), expect(irrefutable_let_patterns))]
         let Mode::Cli(format_mode) = mode else {
             unreachable!("`WalkRunner` should only be called with Mode::Cli");
         };
+        let minimal_output = output_options.minimal;
         let num_of_threads = rayon::current_num_threads();
 
         // Find and load root config file
@@ -140,10 +147,14 @@ impl WalkRunner {
         // Collect format results (changed paths or unchanged count)
         let (tx_success, rx_success) = mpsc::channel();
         // Diagnostic from formatting service
-        let (mut diagnostic_service, tx_error) =
-            DiagnosticService::new(Box::new(DefaultReporter::default()));
+        let reporter: Box<dyn DiagnosticReporter> = if minimal_output {
+            Box::new(MinimalReporter)
+        } else {
+            Box::new(DefaultReporter::default())
+        };
+        let (mut diagnostic_service, tx_error) = DiagnosticService::new(reporter);
 
-        if matches!(format_mode, OutputMode::Check) {
+        if matches!(format_mode, OutputMode::Check) && !minimal_output {
             utils::print_and_flush(stdout, "Checking formatting...\n");
             utils::print_and_flush(stdout, "\n");
         }
@@ -161,7 +172,8 @@ impl WalkRunner {
         // Spawn formatting service on a dedicated thread so it doesn't occupy the rayon pool.
         // It just blocks on `rx_entry` waiting for entries; `par_bridge()` inside still uses rayon.
         std::thread::spawn(move || {
-            let format_service = FormatService::new(cwd, format_mode, source_formatter);
+            let format_service =
+                FormatService::new(cwd, format_mode, source_formatter, minimal_output);
             format_service.run_streaming(rx_entry, &tx_error_for_format, &tx_success);
         });
 
@@ -206,7 +218,11 @@ impl WalkRunner {
         // Print sorted changed file paths to stdout
         if !changed_paths.is_empty() {
             changed_paths.sort_unstable();
-            utils::print_and_flush(stdout, &changed_paths.join("\n"));
+            if minimal_output {
+                utils::print_and_flush(stdout, &format!("{}\n", changed_paths.join("\n")));
+            } else {
+                utils::print_and_flush(stdout, &changed_paths.join("\n"));
+            }
         }
 
         // Then, output diagnostics errors to stderr
@@ -218,6 +234,10 @@ impl WalkRunner {
         // Count the processed files
         let total_target_files_count = changed_paths.len() + unchanged_count + error_count;
         let print_stats = |stdout, stderr| {
+            if minimal_output {
+                return;
+            }
+
             utils::print_and_flush(
                 stdout,
                 &format!(
@@ -239,24 +259,32 @@ impl WalkRunner {
         // Check if no files were found
         if total_target_files_count == 0 {
             if runtime_options.no_error_on_unmatched_pattern {
-                utils::print_and_flush(stderr, "No files found matching the given patterns.\n");
-                print_stats(stdout, stderr);
+                if !minimal_output {
+                    utils::print_and_flush(stderr, "No files found matching the given patterns.\n");
+                    print_stats(stdout, stderr);
+                }
                 return CliRunResult::None;
             }
 
-            utils::print_and_flush(
-                stderr,
-                "Expected at least one target file. All matched files may have been excluded by ignore rules.\n",
-            );
+            if minimal_output {
+                utils::print_and_flush(stderr, "No files found.\n");
+            } else {
+                utils::print_and_flush(
+                    stderr,
+                    "Expected at least one target file. All matched files may have been excluded by ignore rules.\n",
+                );
+            }
             return CliRunResult::NoFilesFound;
         }
 
         if 0 < error_count {
             // Each error is already printed in reporter
-            utils::print_and_flush(
-                stderr,
-                "Error occurred when checking code style in the above files.\n",
-            );
+            if !minimal_output {
+                utils::print_and_flush(
+                    stderr,
+                    "Error occurred when checking code style in the above files.\n",
+                );
+            }
             return CliRunResult::FormatFailed;
         }
 
@@ -266,19 +294,23 @@ impl WalkRunner {
             (OutputMode::ListDifferent, _) => CliRunResult::FormatMismatch,
             // `--check` outputs friendly summary
             (OutputMode::Check, 0) => {
-                utils::print_and_flush(stdout, "All matched files use the correct format.\n");
-                print_stats(stdout, stderr);
+                if !minimal_output {
+                    utils::print_and_flush(stdout, "All matched files use the correct format.\n");
+                    print_stats(stdout, stderr);
+                }
                 CliRunResult::FormatSucceeded
             }
             (OutputMode::Check, changed_count) => {
-                utils::print_and_flush(stdout, "\n\n");
-                utils::print_and_flush(
-                    stdout,
-                    &format!(
-                        "Format issues found in above {changed_count} files. Run without `--check` to fix.\n",
-                    ),
-                );
-                print_stats(stdout, stderr);
+                if !minimal_output {
+                    utils::print_and_flush(stdout, "\n\n");
+                    utils::print_and_flush(
+                        stdout,
+                        &format!(
+                            "Format issues found in above {changed_count} files. Run without `--check` to fix.\n",
+                        ),
+                    );
+                    print_stats(stdout, stderr);
+                }
                 CliRunResult::FormatMismatch
             }
             // Default (write) outputs only stats

apps/oxlint/src/command/lint.rs

@@ -253,9 +253,19 @@ pub struct WarningOptions {
 #[derive(Debug, Clone, Bpaf)]
 pub struct OutputOptions {
     /// Use a specific output format. Possible values:
-    /// `checkstyle`, `default`, `github`, `gitlab`, `json`, `junit`, `stylish`, `unix`
+    /// `checkstyle`, `default`, `github`, `gitlab`, `json`, `junit`, `minimal`, `stylish`, `unix`
     #[bpaf(long, short, fallback_with(default_output_format), hide_usage)]
     pub format: OutputFormat,
+
+    /// Reduce CLI output for agents. Alias for `--format minimal`.
+    #[bpaf(long("minimal"), switch, hide)]
+    pub minimal: bool,
+}
+
+impl OutputOptions {
+    pub fn effective_format(&self) -> OutputFormat {
+        if self.minimal { OutputFormat::Minimal } else { self.format }
+    }
 }
 
 #[expect(clippy::unnecessary_wraps)]
@@ -544,6 +554,7 @@ mod lint_options {
         assert!(!options.fix_options.fix);
         assert!(!options.list_rules);
         assert_eq!(options.output_options.format, OutputFormat::Default);
+        assert!(!options.output_options.minimal);
     }
 
     #[test]
@@ -604,7 +615,20 @@ mod lint_options {
     fn format() {
         let options = get_lint_options("-f json");
         assert_eq!(options.output_options.format, OutputFormat::Json);
+        assert!(!options.output_options.minimal);
         assert!(options.paths.is_empty());
+
+        let options = get_lint_options("-f minimal");
+        assert_eq!(options.output_options.format, OutputFormat::Minimal);
+        assert_eq!(options.output_options.effective_format(), OutputFormat::Minimal);
+    }
+
+    #[test]
+    fn minimal() {
+        let options = get_lint_options("--minimal");
+        assert_eq!(options.output_options.format, OutputFormat::Default);
+        assert!(options.output_options.minimal);
+        assert_eq!(options.output_options.effective_format(), OutputFormat::Minimal);
     }
 
     #[test]