Add --diff option ruff format (#7937)

**Summary** `ruff format --diff` is similar to `ruff format --check`,
but we don't only error with the list of file that would be formatted,
but also show a diff between the unformatted input and the formatted
output.

```console
$ ruff format --diff scratch.py scratch.pyi scratch.ipynb
warning: `ruff format` is not yet stable, and subject to change in future versions.
--- scratch.ipynb
+++ scratch.ipynb
@@ -1,3 +1,4 @@
 import numpy
-maths = (numpy.arange(100)**2).sum()
-stats= numpy.asarray([1,2,3,4]).median()
+
+maths = (numpy.arange(100) ** 2).sum()
+stats = numpy.asarray([1, 2, 3, 4]).median()
--- scratch.py
+++ scratch.py
@@ -1,3 +1,3 @@
 x = 1
-y=2
+y = 2
 z = 3
2 files would be reformatted, 1 file left unchanged
```

With `--diff`, the summary message gets printed to stderr to allow e.g.
`ruff format --diff . > format.patch`.

At the moment, jupyter notebooks are formatted as code diffs, while
everything else is a real diff that could be applied. This means that
the diffs containing jupyter notebooks are not real diffs and can't be
applied. We could change this to json diffs, but they are hard to read.
We could also split the diff option into a human diff option, where we
deviate from the machine readable diff constraints, and a proper machine
readable, appliable diff output that you can pipe into other tools.

To make the tests work, the results (and errors, if any) are sorted
before printing them. Previously, the print order was random, i.e. two
identical runs could have different output.

Open question: Should this go into the markdown docs? Or will this be
subsumed by the integration of the formatter into `ruff check`?

**Test plan** Fixtures for the change and no change cases, including a
jupyter notebook and for file input and stdin.

Fixes #7231

---------

Co-authored-by: Micha Reiser <micha@reiser.io>

crates/ruff_cli/src/commands/format_stdin.rs

@@ -3,6 +3,8 @@ use std::path::Path;
 
 use anyhow::Result;
 use log::error;
+use ruff_linter::fs;
+use similar::TextDiff;
 
 use ruff_linter::source_kind::SourceKind;
 use ruff_python_ast::{PySourceType, SourceType};
@@ -10,7 +12,9 @@ use ruff_workspace::resolver::{match_exclusion, python_file_at_path};
 use ruff_workspace::FormatterSettings;
 
 use crate::args::{CliOverrides, FormatArguments};
-use crate::commands::format::{format_source, FormatCommandError, FormatMode, FormatResult};
+use crate::commands::format::{
+    format_source, FormatCommandError, FormatMode, FormatResult, FormattedSource,
+};
 use crate::resolve::resolve;
 use crate::stdin::read_from_stdin;
 use crate::ExitStatus;
@@ -23,11 +27,7 @@ pub(crate) fn format_stdin(cli: &FormatArguments, overrides: &CliOverrides) -> R
         overrides,
         cli.stdin_filename.as_deref(),
     )?;
-    let mode = if cli.check {
-        FormatMode::Check
-    } else {
-        FormatMode::Write
-    };
+    let mode = FormatMode::from_cli(cli);
 
     if let Some(filename) = cli.stdin_filename.as_deref() {
         if !python_file_at_path(filename, &pyproject_config, overrides)? {
@@ -58,7 +58,7 @@ pub(crate) fn format_stdin(cli: &FormatArguments, overrides: &CliOverrides) -> R
     ) {
         Ok(result) => match mode {
             FormatMode::Write => Ok(ExitStatus::Success),
-            FormatMode::Check => {
+            FormatMode::Check | FormatMode::Diff => {
                 if result.is_formatted() {
                     Ok(ExitStatus::Failure)
                 } else {
@@ -93,15 +93,37 @@ fn format_source_code(
     };
 
     // Format the source.
-    let formatted = format_source(source_kind, source_type, path, settings)?;
+    let formatted = format_source(&source_kind, source_type, path, settings)?;
 
-    // Write to stdout regardless of whether the source was formatted.
-    if mode.is_write() {
-        let mut writer = stdout().lock();
-        formatted
-            .source_kind()
-            .write(&mut writer)
-            .map_err(|err| FormatCommandError::Write(path.map(Path::to_path_buf), err))?;
+    match &formatted {
+        FormattedSource::Formatted(formatted) => match mode {
+            FormatMode::Write => {
+                let mut writer = stdout().lock();
+                formatted
+                    .write(&mut writer)
+                    .map_err(|err| FormatCommandError::Write(path.map(Path::to_path_buf), err))?;
+            }
+            FormatMode::Check => {}
+            FormatMode::Diff => {
+                let mut writer = stdout().lock();
+                let text_diff =
+                    TextDiff::from_lines(source_kind.source_code(), formatted.source_code());
+                let mut unified_diff = text_diff.unified_diff();
+                if let Some(path) = path {
+                    unified_diff.header(&fs::relativize_path(path), &fs::relativize_path(path));
+                }
+                unified_diff.to_writer(&mut writer).unwrap();
+            }
+        },
+        FormattedSource::Unchanged => {
+            // Write to stdout regardless of whether the source was formatted
+            if mode.is_write() {
+                let mut writer = stdout().lock();
+                source_kind
+                    .write(&mut writer)
+                    .map_err(|err| FormatCommandError::Write(path.map(Path::to_path_buf), err))?;
+            }
+        }
     }
 
     Ok(FormatResult::from(formatted))