feat: add diff command (#54)

Author: freedom3219

Cargo.lock

@@ -41,6 +41,7 @@ uuid = { version = "1.18.1", features = ["v4"] }
 memchr = "2"
 globset = "0.4"
 regex = "1"
+similar = "2"
 
 [dev-dependencies]
 assert_cmd = "2.0.17"

Cargo.toml

@@ -140,6 +140,12 @@ storify grep -i "pattern" path/to/file    # case-insensitive
 storify grep -n "pattern" path/to/file    # show line numbers
 storify grep -R "pattern" path/           # recursive
 
+# Diff two files (unified diff)
+storify diff left/file right/file          # unified diff with 3 lines context
+storify diff -U 1 left/file right/file     # set context lines
+storify diff -w left/file right/file       # ignore trailing whitespace
+storify diff --size-limit 1 -f left right  # size guard and force
+
 # Find objects by name/regex/type
 storify find path/ --name '**/*.log'     # glob on full path
 storify find path/ --regex '.*\\.(csv|parquet)$'  # regex on full path
@@ -186,6 +192,7 @@ storify stat path/to/file --raw    # raw key=value format
 | `tree` | View directory structure as a tree | `-d <DEPTH>`, `--dirs-only` |
 | `du` | Show disk usage | `-s` (summary) |
 | `stat` | Show object metadata | `--json`, `--raw` |
+| `diff` | Compare two files (unified diff) | `-U <N>` (context), `-w` (ignore-space), `--size-limit <MB>`, `-f` (force) |
 
 ### Config Commands
 

README.md

@@ -7,8 +7,8 @@ use super::{
     context::CliContext,
     prompts::Prompt,
     storage::{
-        self, CatArgs, CpArgs, DuArgs, GetArgs, GrepArgs, HeadArgs, LsArgs, MkdirArgs, MvArgs,
-        PutArgs, RmArgs, StatArgs, TailArgs, TreeArgs,
+        self, CatArgs, CpArgs, DiffArgs, DuArgs, GetArgs, GrepArgs, HeadArgs, LsArgs, MkdirArgs,
+        MvArgs, PutArgs, RmArgs, StatArgs, TailArgs, TreeArgs,
     },
 };
 
@@ -87,6 +87,8 @@ pub enum Command {
     Find(super::storage::FindArgs),
     /// View directory structure as a tree
     Tree(TreeArgs),
+    /// Diff two files and print unified diff
+    Diff(DiffArgs),
 }
 
 #[derive(Subcommand, Debug, Clone)]

src/cli/entry.rs

@@ -250,6 +250,33 @@ pub struct TreeArgs {
     pub dirs_only: bool,
 }
 
+#[derive(ClapArgs, Debug, Clone)]
+pub struct DiffArgs {
+    /// The left file path
+    #[arg(value_name = "LEFT", value_parser = parse_validated_path)]
+    pub left: String,
+
+    /// The right file path
+    #[arg(value_name = "RIGHT", value_parser = parse_validated_path)]
+    pub right: String,
+
+    /// Number of context lines to show around changes
+    #[arg(short = 'U', long = "context", default_value_t = 3)]
+    pub context: usize,
+
+    /// Ignore whitespace differences
+    #[arg(short = 'w', long = "ignore-space")]
+    pub ignore_space: bool,
+
+    /// Limit total size of compared files in MB (0 disables)
+    #[arg(short = 's', long = "size-limit", default_value_t = 10)]
+    pub size_limit_mb: u64,
+
+    /// Bypass size-limit check
+    #[arg(short = 'f', long)]
+    pub force: bool,
+}
+
 pub async fn execute(command: &Command, ctx: &CliContext) -> Result<()> {
     let config = ctx.storage_config()?;
     let client = StorageClient::new(config.clone()).await?;
@@ -379,6 +406,18 @@ pub async fn execute(command: &Command, ctx: &CliContext) -> Result<()> {
                 .print_tree(&tree_args.path, tree_args.depth, tree_args.dirs_only)
                 .await?;
         }
+        Command::Diff(diff_args) => {
+            client
+                .diff_files(
+                    &diff_args.left,
+                    &diff_args.right,
+                    diff_args.context,
+                    diff_args.ignore_space,
+                    diff_args.size_limit_mb,
+                    diff_args.force,
+                )
+                .await?;
+        }
         Command::Config(_) => {
             unreachable!("Config commands are handled separately")
         }

src/cli/storage.rs

@@ -93,6 +93,13 @@ pub enum Error {
     #[snafu(display("Failed to find under '{path}': {source}"))]
     FindFailed { path: String, source: Box<Error> },
 
+    #[snafu(display("Failed to diff '{src_path}' and '{dest_path}': {source}"))]
+    DiffFailed {
+        src_path: String,
+        dest_path: String,
+        source: Box<Error>,
+    },
+
     #[snafu(display("Invalid argument: {message}"))]
     InvalidArgument { message: String },
 

src/error.rs

@@ -11,6 +11,7 @@ pub use self::utils::OutputFormat;
 use self::operations::cat::OpenDalFileReader;
 use self::operations::copy::OpenDalCopier;
 use self::operations::delete::OpenDalDeleter;
+use self::operations::diff::OpenDalDiffer;
 use self::operations::download::OpenDalDownloader;
 use self::operations::find::OpenDalFinder;
 use self::operations::grep::OpenDalGreper;
@@ -23,8 +24,8 @@ use self::operations::tree::OpenDalTreer;
 use self::operations::upload::OpenDalUploader;
 use self::operations::usage::OpenDalUsageCalculator;
 use self::operations::{
-    Cater, Copier, Deleter, Downloader, Greper, Header, Lister, Mkdirer, Mover, Stater, Tailer,
-    Treer, Uploader, UsageCalculator,
+    Cater, Copier, Deleter, Differ, Downloader, Greper, Header, Lister, Mkdirer, Mover, Stater,
+    Tailer, Treer, Uploader, UsageCalculator,
 };
 use crate::storage::utils::error::IntoStorifyError;
 use crate::wrap_err;
@@ -673,4 +674,80 @@ impl StorageClient {
                 },
             })
     }
+
+    pub async fn diff_files(
+        &self,
+        left: &str,
+        right: &str,
+        context: usize,
+        ignore_space: bool,
+        size_limit_mb: u64,
+        force: bool,
+    ) -> Result<()> {
+        // Validate both paths are files
+        let left_meta = self.operator.stat(left).await.map_err(|e| {
+            if e.kind() == opendal::ErrorKind::NotFound {
+                Error::PathNotFound {
+                    path: std::path::PathBuf::from(left),
+                }
+            } else {
+                Error::InvalidArgument {
+                    message: format!("Failed to stat '{}': {}", left, e),
+                }
+            }
+        })?;
+        let right_meta = self.operator.stat(right).await.map_err(|e| {
+            if e.kind() == opendal::ErrorKind::NotFound {
+                Error::PathNotFound {
+                    path: std::path::PathBuf::from(right),
+                }
+            } else {
+                Error::InvalidArgument {
+                    message: format!("Failed to stat '{}': {}", right, e),
+                }
+            }
+        })?;
+
+        if !left_meta.mode().is_file() || !right_meta.mode().is_file() {
+            return Err(Error::InvalidArgument {
+                message: "diff only supports files; directories are not supported".to_string(),
+            });
+        }
+
+        // Short-circuit: identical paths (after existence/type validation)
+        if left == right {
+            return Ok(());
+        }
+
+        // Short-circuit when ETag and size match (content-identical for many providers)
+        if left_meta.content_length() == right_meta.content_length() {
+            let le = left_meta.etag();
+            let re = right_meta.etag();
+            match (le, re) {
+                (Some(le), Some(re)) if le == re => return Ok(()),
+                _ => {}
+            }
+        }
+
+        // Size check (sum of both files)
+        let total_mb =
+            (left_meta.content_length() + right_meta.content_length()).div_ceil(1024 * 1024);
+        if size_limit_mb > 0 && total_mb > size_limit_mb && !force {
+            return Err(Error::InvalidArgument {
+                message: format!(
+                    "Files too large ({}MB > {}MB). Use --force to override",
+                    total_mb, size_limit_mb
+                ),
+            });
+        }
+
+        let differ = OpenDalDiffer::new(self.operator.clone());
+        wrap_err!(
+            differ.diff(left, right, context, ignore_space).await,
+            DiffFailed {
+                src_path: left.to_string(),
+                dest_path: right.to_string()
+            }
+        )
+    }
 }

src/storage.rs

@@ -0,0 +1,87 @@
+use crate::error::{Error, Result};
+use opendal::Operator;
+use similar::TextDiff;
+use std::path::PathBuf;
+
+/// Trait for diffing two files and printing a unified diff
+pub trait Differ {
+    /// Diff two files and print the unified diff to stdout
+    async fn diff(&self, left: &str, right: &str, context: usize, ignore_space: bool)
+    -> Result<()>;
+}
+
+pub struct OpenDalDiffer {
+    operator: Operator,
+}
+
+impl OpenDalDiffer {
+    pub fn new(operator: Operator) -> Self {
+        Self { operator }
+    }
+
+    async fn read_text(&self, path: &str, ignore_space: bool) -> Result<String> {
+        let data = self.operator.read(path).await.map_err(|e| {
+            if e.kind() == opendal::ErrorKind::NotFound {
+                Error::PathNotFound {
+                    path: PathBuf::from(path),
+                }
+            } else {
+                Error::DiffFailed {
+                    src_path: path.to_string(),
+                    dest_path: path.to_string(),
+                    source: Box::new(e.into()),
+                }
+            }
+        })?;
+
+        let mut s = String::from_utf8(data.to_vec()).map_err(|_| Error::InvalidArgument {
+            message: format!("Non-UTF8 or binary file not supported: {}", path),
+        })?;
+
+        if ignore_space {
+            // Trim trailing spaces/tabs for each line with minimal allocations.
+            // Use an output String with reserved capacity.
+            let mut out = String::with_capacity(s.len());
+            let mut lines = s.split_inclusive('\n');
+            for line in lines.by_ref() {
+                if let Some(stripped) = line.strip_suffix('\n') {
+                    out.push_str(stripped.trim_end_matches([' ', '\t']));
+                    out.push('\n');
+                } else {
+                    out.push_str(line.trim_end_matches([' ', '\t']));
+                }
+            }
+            s = out;
+        }
+        Ok(s)
+    }
+}
+
+impl Differ for OpenDalDiffer {
+    async fn diff(
+        &self,
+        left: &str,
+        right: &str,
+        context: usize,
+        ignore_space: bool,
+    ) -> Result<()> {
+        let left_text = self.read_text(left, ignore_space).await?;
+        let right_text = self.read_text(right, ignore_space).await?;
+
+        // Produce unified diff via `similar`
+        let diff = TextDiff::from_lines(&left_text, &right_text);
+        let unified = diff
+            .unified_diff()
+            .context_radius(context)
+            .header(left, right)
+            .to_string();
+
+        // If no differences, print nothing
+        if unified.trim().is_empty() {
+            return Ok(());
+        }
+
+        println!("{}", unified);
+        Ok(())
+    }
+}

src/storage/operations/diff.rs

@@ -2,6 +2,7 @@
 pub mod cat;
 pub mod copy;
 pub mod delete;
+pub mod diff;
 pub mod download;
 pub mod find;
 pub mod grep;
@@ -19,6 +20,7 @@ pub mod usage;
 pub use cat::Cater;
 pub use copy::Copier;
 pub use delete::Deleter;
+pub use diff::Differ;
 pub use download::Downloader;
 pub use grep::Greper;
 pub use head::Header;

src/storage/operations/mod.rs

@@ -29,6 +29,7 @@ fn main() -> Result<()> {
     operations::usage::tests(&client, &mut tests);
     operations::stat::tests(&client, &mut tests);
     operations::tree::tests(&client, &mut tests);
+    operations::diff::tests(&client, &mut tests);
 
     let _ = tracing_subscriber::fmt()
         .pretty()