watchcat 0.3.0 → 0.6.1

data/ext/watchcat/src/lib.rs

@@ -1,13 +1,10 @@
 use crossbeam_channel::{select, unbounded};
 use magnus::{
-    block::{block_given, yield_value},
-    class::object,
-    define_module, function, method,
+    function, method,
     scan_args::{get_kwargs, scan_args},
-    Error, Module, Object, Value,
+    Error, Module, Object, Value, Ruby
 };
 use notify::{Config, PollWatcher, RecommendedWatcher, RecursiveMode, Watcher};
-use notify_debouncer_mini::new_debouncer;
 use std::{path::Path, time::Duration, sync::{Arc, atomic::{AtomicBool, Ordering}}};
 
 mod event;
@@ -20,93 +17,135 @@ struct WatchcatWatcher {
     tx: crossbeam_channel::Sender<bool>,
     rx: crossbeam_channel::Receiver<bool>,
     terminated: Arc<AtomicBool>,
+    cmd_tx: crossbeam_channel::Sender<Command>,
+    cmd_rx: crossbeam_channel::Receiver<Command>,
 }
 
 #[derive(Debug)]
 enum WatcherEnum {
-    #[allow(dead_code)]
     Poll(PollWatcher),
-    #[allow(dead_code)]
     Recommended(RecommendedWatcher),
 }
 
+fn watcher_watch(w: &mut WatcherEnum, path: &Path, mode: RecursiveMode) -> notify::Result<()> {
+    match w {
+        WatcherEnum::Poll(x) => x.watch(path, mode),
+        WatcherEnum::Recommended(x) => x.watch(path, mode),
+    }
+}
+
+fn watcher_unwatch(w: &mut WatcherEnum, path: &Path) -> notify::Result<()> {
+    match w {
+        WatcherEnum::Poll(x) => x.unwatch(path),
+        WatcherEnum::Recommended(x) => x.unwatch(path),
+    }
+}
+
+// Carries a failure out of the GVL-released section without touching Ruby.
+// `magnus::Error` (and the `Ruby` handle needed to build one) must only be
+// used while the GVL is held, so the actual `magnus::Error` is constructed
+// after control returns from `call_without_gvl`.
+enum WatchFailure {
+    Arg(String),
+    Runtime(String),
+}
+
+enum Command {
+    Watch(Vec<String>, bool),   // paths, recursive
+    Unwatch(Vec<String>),       // paths
+}
+
 impl WatchcatWatcher {
     fn new() -> Self {
         let (tx_executor, rx_executor) = unbounded::<bool>();
+        let (cmd_tx, cmd_rx) = unbounded::<Command>();
         Self {
             tx: tx_executor,
             rx: rx_executor,
             terminated: Arc::new(AtomicBool::new(false)),
+            cmd_tx,
+            cmd_rx,
         }
     }
 
     fn close(&self) {
         self.terminated.store(true, Ordering::SeqCst);
-        self.tx.send(true).unwrap()
+        // See `add`/`unwatch`: `send` cannot fail while `self` retains `rx`,
+        // but `.unwrap()` would still turn a hypothetical failure into a
+        // Rust panic, and a panic crossing the FFI boundary aborts the whole
+        // process instead of raising in Ruby. Not worth the risk for a
+        // result we already know.
+        let _ = self.tx.send(true);
     }
 
     fn watch(&self, args: &[Value]) -> Result<bool, Error> {
-        if !block_given() {
-            return Err(Error::new(magnus::exception::arg_error(), "no block given"));
+        let ruby = unsafe { Ruby::get_unchecked() };
+        let ruby_ref = &ruby;
+        if !ruby_ref.block_given() {
+            return Err(Error::new(ruby_ref.exception_arg_error(), "no block given"));
         }
 
-        let (pathnames, recursive, force_polling, poll_interval, ignore_remove, debounce) = Self::parse_args(args)?;
+        let (pathnames, recursive, force_polling, poll_interval, ignore_remove, ignore_access, ignore_create, ignore_modify) = Self::parse_args(args)?;
         let mode = if recursive {
             RecursiveMode::Recursive
         } else {
             RecursiveMode::NonRecursive
         };
 
-        // Clone necessary data for the call_without_gvl
         let terminated = self.terminated.clone();
         let rx_clone = self.rx.clone();
+        let cmd_rx = self.cmd_rx.clone();
 
-        // Start the file watching with GVL released
-        if debounce >= 0 {
-            Self::watch_with_debounce_threaded(
-                pathnames, mode, ignore_remove, debounce, terminated, rx_clone
-            )
-        } else {
-            Self::watch_without_debounce_threaded(
-                pathnames, mode, force_polling, poll_interval, ignore_remove, terminated, rx_clone
-            )
-        }
+        Self::watch_threaded(
+            pathnames, mode, force_polling, poll_interval, ignore_remove, ignore_access, ignore_create, ignore_modify, terminated, rx_clone, cmd_rx, ruby_ref
+        )
     }
 
-    fn watch_without_debounce_threaded(
+    #[allow(clippy::too_many_arguments)]
+    fn watch_threaded(
         pathnames: Vec<String>,
         mode: RecursiveMode,
         force_polling: bool,
         poll_interval: u64,
         ignore_remove: bool,
+        ignore_access: bool,
+        ignore_create: bool,
+        ignore_modify: bool,
         terminated: Arc<AtomicBool>,
-        rx: crossbeam_channel::Receiver<bool>
+        rx: crossbeam_channel::Receiver<bool>,
+        cmd_rx: crossbeam_channel::Receiver<Command>,
+        ruby: &Ruby
     ) -> Result<bool, Error> {
-        call_without_gvl(move || {
+        // `ruby` (and any `magnus::Error`/`ExceptionClass` built from it) must only be
+        // touched while the GVL is held, so it is intentionally NOT captured by the
+        // `call_without_gvl` closure below. Failures are carried out as plain
+        // `WatchFailure` values and converted to a real `magnus::Error` afterwards,
+        // once control has returned here with the GVL held again.
+        let result: Result<bool, WatchFailure> = call_without_gvl(move || {
             let (tx, watcher_rx) = unbounded();
             // This variable is needed to keep `watcher` active.
-            let _watcher = match force_polling {
+            let mut _watcher = match force_polling {
                 true => {
                     let delay = Duration::from_millis(poll_interval);
                     let config = notify::Config::default().with_poll_interval(delay);
                     let mut watcher = PollWatcher::new(tx, config)
-                        .map_err(|e| Error::new(magnus::exception::arg_error(), e.to_string()))?;
+                        .map_err(|e| WatchFailure::Arg(e.to_string()))?;
                     for pathname in &pathnames {
                         let path = Path::new(pathname);
                         watcher
                             .watch(path, mode)
-                            .map_err(|e| Error::new(magnus::exception::arg_error(), e.to_string()))?;
+                            .map_err(|e| WatchFailure::Arg(e.to_string()))?;
                     }
                     WatcherEnum::Poll(watcher)
                 }
                 false => {
                     let mut watcher = RecommendedWatcher::new(tx, Config::default())
-                        .map_err(|e| Error::new(magnus::exception::arg_error(), e.to_string()))?;
+                        .map_err(|e| WatchFailure::Arg(e.to_string()))?;
                     for pathname in &pathnames {
                         let path = Path::new(pathname);
                         watcher
                             .watch(path, mode)
-                            .map_err(|e| Error::new(magnus::exception::arg_error(), e.to_string()))?;
+                            .map_err(|e| WatchFailure::Arg(e.to_string()))?;
                     }
                     WatcherEnum::Recommended(watcher)
                 }
@@ -121,6 +160,23 @@ impl WatchcatWatcher {
                     recv(rx) -> _res => {
                         break Ok(true);
                     }
+                    recv(cmd_rx) -> cmd => {
+                        if let Ok(cmd) = cmd {
+                            match cmd {
+                                Command::Watch(paths, recursive) => {
+                                    let m = if recursive { RecursiveMode::Recursive } else { RecursiveMode::NonRecursive };
+                                    for p in &paths {
+                                        let _ = watcher_watch(&mut _watcher, Path::new(p), m);
+                                    }
+                                }
+                                Command::Unwatch(paths) => {
+                                    for p in &paths {
+                                        let _ = watcher_unwatch(&mut _watcher, Path::new(p));
+                                    }
+                                }
+                            }
+                        }
+                    }
                     recv(watcher_rx) -> res => {
                         match res {
                             Ok(event) => {
@@ -136,102 +192,65 @@ impl WatchcatWatcher {
                                             continue;
                                         }
 
+                                        let macos_ambiguous_metadata_touch = cfg!(target_os = "macos")
+                                            && matches!(
+                                                event.kind,
+                                                notify::event::EventKind::Modify(
+                                                    notify::event::ModifyKind::Metadata(
+                                                        notify::event::MetadataKind::Any
+                                                    )
+                                                )
+                                            );
+                                        if ignore_access
+                                            && (matches!(
+                                                event.kind,
+                                                notify::event::EventKind::Access(_)
+                                            ) || macos_ambiguous_metadata_touch)
+                                        {
+                                            continue;
+                                        }
+                                        if ignore_create && matches!(event.kind, notify::event::EventKind::Create(_)) {
+                                            continue;
+                                        }
+                                        if ignore_modify && matches!(event.kind, notify::event::EventKind::Modify(_)) {
+                                            continue;
+                                        }
+
                                         // Yield to Ruby with GVL
-                                        let result = call_with_gvl(|_| {
-                                            yield_value::<(Vec<String>, Vec<String>, String), Value>(
+                                        let result: Result<Value, String> = call_with_gvl(|ruby| {
+                                            ruby.yield_value::<(Vec<String>, Vec<String>, String), Value>(
                                                 (WatchatEvent::convert_kind(&event.kind), paths, format!("{:?}", event.kind))
-                                            )
+                                            ).map_err(|e| e.to_string())
                                         });
 
-                                        if result.is_err() {
-                                            break Err(Error::new(magnus::exception::runtime_error(), "Error yielding to Ruby block"));
+                                        if let Err(msg) = result {
+                                            break Err(WatchFailure::Runtime(format!("Error yielding to Ruby block: {msg}")));
                                         }
                                     }
                                     Err(e) => {
-                                        break Err(Error::new(magnus::exception::runtime_error(), e.to_string()));
+                                        break Err(WatchFailure::Runtime(e.to_string()));
                                     }
                                 }
                             }
                             Err(e) => {
-                                break Err(Error::new(magnus::exception::runtime_error(), e.to_string()));
+                                break Err(WatchFailure::Runtime(e.to_string()));
                             }
                         }
                     }
                 }
             }
-        })
-    }
-
-    fn watch_with_debounce_threaded(
-        pathnames: Vec<String>,
-        mode: RecursiveMode,
-        ignore_remove: bool,
-        debounce: i64,
-        terminated: Arc<AtomicBool>,
-        rx: crossbeam_channel::Receiver<bool>
-    ) -> Result<bool, Error> {
-        call_without_gvl(move || {
-            let (tx, watcher_rx) = unbounded();
-            let mut debouncer = new_debouncer(Duration::from_millis(debounce.try_into().unwrap()), tx).unwrap();
-            for pathname in &pathnames {
-                let path = Path::new(pathname);
-                debouncer
-                    .watcher()
-                    .watch(path, mode)
-                    .map_err(|e| Error::new(magnus::exception::arg_error(), e.to_string()))?;
-            }
-
-            loop {
-                if terminated.load(Ordering::SeqCst) {
-                    break Ok(true);
-                }
-
-                select! {
-                    recv(rx) -> _res => {
-                        break Ok(true);
-                    }
-                    recv(watcher_rx) -> res => {
-                        match res {
-                            Ok(events) => {
-                                match events {
-                                    Ok(events) => {
-                                        for event in events.iter() {
-                                            if ignore_remove && !Path::new(&event.path).exists() {
-                                                continue;
-                                            }
-
-                                            // Yield to Ruby with GVL
-                                            let result = call_with_gvl(|_| {
-                                                yield_value::<(Vec<String>, Vec<String>, String), Value>(
-                                                    (vec![], vec![event.path.to_string_lossy().into_owned()], format!("{:?}", event.kind))
-                                                )
-                                            });
+        });
 
-                                            if result.is_err() {
-                                                return Err(Error::new(magnus::exception::runtime_error(), "Error yielding to Ruby block"));
-                                            }
-                                        }
-                                    }
-                                    Err(e) => {
-                                        break Err(Error::new(magnus::exception::runtime_error(), e.to_string()));
-                                    }
-                                }
-                            }
-                            Err(e) => {
-                                break Err(Error::new(magnus::exception::runtime_error(), e.to_string()));
-                            }
-                        }
-                    }
-                }
-            }
+        result.map_err(|err| match err {
+            WatchFailure::Arg(msg) => Error::new(ruby.exception_arg_error(), msg),
+            WatchFailure::Runtime(msg) => Error::new(ruby.exception_runtime_error(), msg),
         })
     }
 
     #[allow(clippy::let_unit_value, clippy::type_complexity)]
-    fn parse_args(args: &[Value]) -> Result<(Vec<String>, bool, bool, u64, bool, i64), Error> {
+    fn parse_args(args: &[Value]) -> Result<(Vec<String>, bool, bool, u64, bool, bool, bool, bool), Error> {
         type KwArgBool = Option<Option<bool>>;
         type KwArgU64 = Option<Option<u64>>;
-        type KwArgi64 = Option<Option<i64>>;
 
         let args = scan_args(args)?;
         let (paths,): (Vec<String>,) = args.required;
@@ -243,9 +262,9 @@ impl WatchcatWatcher {
         let kwargs = get_kwargs(
             args.keywords,
             &[],
-            &["recursive", "force_polling", "poll_interval", "ignore_remove", "debounce"],
+            &["recursive", "force_polling", "poll_interval", "ignore_remove", "ignore_access", "ignore_create", "ignore_modify"],
         )?;
-        let (recursive, force_polling, poll_interval, ignore_remove, debounce): (KwArgBool, KwArgBool, KwArgU64, KwArgBool, KwArgi64) =
+        let (recursive, force_polling, poll_interval, ignore_remove, ignore_access, ignore_create, ignore_modify): (KwArgBool, KwArgBool, KwArgU64, KwArgBool, KwArgBool, KwArgBool, KwArgBool) =
             kwargs.optional;
         let _: () = kwargs.required;
         let _: () = kwargs.splat;
@@ -256,19 +275,76 @@ impl WatchcatWatcher {
             force_polling.flatten().unwrap_or(false),
             poll_interval.flatten().unwrap_or(200),
             ignore_remove.flatten().unwrap_or(false),
-            debounce.flatten().unwrap_or(-1),
+            ignore_access.flatten().unwrap_or(false),
+            ignore_create.flatten().unwrap_or(false),
+            ignore_modify.flatten().unwrap_or(false),
         ))
     }
+
+    fn add(&self, args: &[Value]) -> Result<bool, Error> {
+        let (paths, recursive) = Self::parse_add_args(args)?;
+        // `send` only fails when every receiver is disconnected, but `self`
+        // holds `cmd_rx` for the whole lifetime of this object, so it cannot
+        // fail here. If the watch loop has already stopped, the command is
+        // simply buffered and never applied (a harmless no-op).
+        let _ = self.cmd_tx.send(Command::Watch(paths, recursive));
+        Ok(true)
+    }
+
+    fn unwatch(&self, args: &[Value]) -> Result<bool, Error> {
+        let paths = Self::parse_unwatch_args(args)?;
+        // See `add`: `send` cannot fail while `self` retains `cmd_rx`.
+        let _ = self.cmd_tx.send(Command::Unwatch(paths));
+        Ok(true)
+    }
+
+    #[allow(clippy::let_unit_value)]
+    fn parse_add_args(args: &[Value]) -> Result<(Vec<String>, bool), Error> {
+        type KwArgBool = Option<Option<bool>>;
+
+        let args = scan_args(args)?;
+        let (paths,): (Vec<String>,) = args.required;
+        let _: () = args.optional;
+        let _: () = args.splat;
+        let _: () = args.trailing;
+        let _: () = args.block;
+
+        let kwargs = get_kwargs(args.keywords, &[], &["recursive"])?;
+        let (recursive,): (KwArgBool,) = kwargs.optional;
+        let _: () = kwargs.required;
+        let _: () = kwargs.splat;
+
+        Ok((paths, recursive.flatten().unwrap_or(true)))
+    }
+
+    #[allow(clippy::let_unit_value)]
+    fn parse_unwatch_args(args: &[Value]) -> Result<Vec<String>, Error> {
+        let args = scan_args(args)?;
+        let (paths,): (Vec<String>,) = args.required;
+        let _: () = args.optional;
+        let _: () = args.splat;
+        let _: () = args.trailing;
+        let _: () = args.block;
+
+        let kwargs = get_kwargs::<&str, (), (), ()>(args.keywords, &[], &[])?;
+        let _: () = kwargs.optional;
+        let _: () = kwargs.required;
+        let _: () = kwargs.splat;
+
+        Ok(paths)
+    }
 }
 
 #[magnus::init]
-fn init() -> Result<(), Error> {
-    let module = define_module("Watchcat")?;
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Watchcat")?;
 
-    let watcher_class = module.define_class("Watcher", object())?;
+    let watcher_class = module.define_class("Watcher", ruby.class_object())?;
     watcher_class.define_singleton_method("new", function!(WatchcatWatcher::new, 0))?;
     watcher_class.define_method("watch", method!(WatchcatWatcher::watch, -1))?;
     watcher_class.define_method("close", method!(WatchcatWatcher::close, 0))?;
+    watcher_class.define_method("add", method!(WatchcatWatcher::add, -1))?;
+    watcher_class.define_method("unwatch", method!(WatchcatWatcher::unwatch, -1))?;
 
     Ok(())
 }

data/lib/watchcat/cli/action_executor.rb

@@ -0,0 +1,44 @@
+module Watchcat
+  module CLI
+    class ActionExecutor
+      def initialize(file_path, event)
+        @file_path = file_path
+        @event = event
+        @file_dir = File.dirname(file_path)
+        @file_name = File.basename(file_path)
+        @file_ext = File.extname(file_path)
+        @file_base = File.basename(file_path, @file_ext)
+      end
+
+      def execute(action)
+        execute_command(action)
+      rescue => e
+        puts "Error executing action #{action}: #{e.message}"
+      end
+
+      private
+
+      def execute_command(action)
+        command = substitute_variables(action["command"])
+        puts "Executing: #{command}"
+
+        success = system(command)
+        unless success
+          puts "Command failed with exit code: #{$?.exitstatus}"
+        end
+      end
+
+      def substitute_variables(template)
+        return template unless template.is_a?(String)
+
+        template
+          .gsub("{{file_path}}", @file_path)
+          .gsub("{{file_dir}}", @file_dir)
+          .gsub("{{file_name}}", @file_name)
+          .gsub("{{file_base}}", @file_base)
+          .gsub("{{file_ext}}", @file_ext)
+          .gsub("{{event_type}}", @event.kind.event_type)
+      end
+    end
+  end
+end

data/lib/watchcat/cli/config.rb

@@ -0,0 +1,76 @@
+require "psych"
+
+module Watchcat
+  module CLI
+    class Config
+      attr_reader :watches
+
+      def initialize(data)
+        @watches = parse_watches(data["watches"] || [])
+      end
+
+      def self.load(file_path)
+        unless File.exist?(file_path)
+          raise Error, "Configuration file not found: #{file_path}"
+        end
+
+        begin
+          data = Psych.load_file(file_path)
+          new(data)
+        rescue Psych::SyntaxError => e
+          raise Error, "Invalid YAML syntax in #{file_path}: #{e.message}"
+        end
+      end
+
+      def self.generate_template(file_path)
+        template = <<~YAML
+          # Watchcat Configuration File
+
+          watches:
+            - path: "./src"
+              recursive: true
+              debounce: 300
+              filters:
+                ignore_access: true
+              patterns:
+                - "*.js"
+                - "*.ts"
+                - "*.css"
+              actions:
+                - command: "echo 'File changed: {{file_path}}'"
+
+            - path: "./docs"
+              recursive: true
+              filters:
+                ignore_access: true
+              patterns:
+                - "*.md"
+              actions:
+                - command: "echo 'Documentation updated: {{file_name}}'"
+        YAML
+
+        if File.exist?(file_path)
+          raise Error, "File already exists: #{file_path}. Won't overwrite."
+        end
+
+        File.write(file_path, template)
+        puts "Config template generated at #{file_path}"
+      end
+
+      private
+
+      def parse_watches(watches_data)
+        watches_data.map do |watch_config|
+          {
+            path: watch_config["path"],
+            recursive: watch_config.fetch("recursive", true),
+            patterns: watch_config["patterns"] || [],
+            actions: watch_config["actions"] || [],
+            debounce: watch_config.fetch("debounce", -1),
+            filters: watch_config["filters"]&.transform_keys(&:to_sym) || {},
+          }
+        end
+      end
+    end
+  end
+end

data/lib/watchcat/cli/watcher.rb

@@ -0,0 +1,83 @@
+module Watchcat
+  module CLI
+    class Watcher
+      def initialize(config)
+        @config = config
+        @watchers = []
+      end
+
+      def start
+        puts "Starting Watchcat file watcher..."
+
+        @config.watches.each do |watch_config|
+          start_watching_path(watch_config)
+        end
+
+        puts "Watchcat is now watching for file changes. Press Ctrl+C to stop."
+
+        # Keep the main thread alive
+        begin
+          sleep
+        rescue Interrupt
+          puts "\nStopping Watchcat..."
+          stop
+        end
+      end
+
+      def stop
+        @watchers.each(&:stop)
+        @watchers.clear
+      end
+
+      private
+
+      def start_watching_path(watch_config)
+        path = watch_config[:path]
+
+        unless File.exist?(path)
+          puts "Warning: Path does not exist: #{path}"
+          return
+        end
+
+        puts "Watching: #{path} (recursive: #{watch_config[:recursive]}, debounce: #{watch_config[:debounce]}ms)"
+
+        watcher = Watchcat.watch(
+          path,
+          recursive: watch_config[:recursive],
+          filters: watch_config[:filters],
+          debounce: watch_config[:debounce],
+        ) do |event|
+          handle_file_event(event, watch_config)
+        end
+
+        @watchers << watcher
+      end
+
+      def handle_file_event(event, watch_config)
+        event.paths.each do |file_path|
+          next unless should_process_file?(file_path, watch_config[:patterns])
+
+          puts "File changed: #{file_path}"
+          execute_actions(file_path, event, watch_config[:actions])
+        end
+      end
+
+      def should_process_file?(file_path, patterns)
+        return true if patterns.empty?
+
+        patterns.any? do |pattern|
+          File.fnmatch?(pattern, File.basename(file_path)) ||
+            File.fnmatch?(pattern, file_path)
+        end
+      end
+
+      def execute_actions(file_path, event, actions)
+        executor = ActionExecutor.new(file_path, event)
+
+        actions.each do |action|
+          executor.execute(action)
+        end
+      end
+    end
+  end
+end

data/lib/watchcat/cli.rb

@@ -0,0 +1,52 @@
+require "optparse"
+require_relative "cli/watcher"
+require_relative "cli/config"
+require_relative "cli/action_executor"
+
+module Watchcat
+  module CLI
+    class Error < StandardError; end
+    class << self
+      def start(argv)
+        options = parse(argv)
+
+        if options[:init]
+          Config.generate_template(options[:init])
+          return
+        end
+
+        config = Config.load(options[:config])
+        watcher = Watcher.new(config)
+        watcher.start
+      rescue => e
+        raise Error, "Failed to start Watchcat: #{e.message}"
+      end
+
+      def parse(argv)
+        options = { config: 'watchcat.yml' }
+        OptionParser.new do |opts|
+          opts.banner = "Usage: watchcat [options]"
+
+          opts.on("-C", "--config PATH", "Path to the config file. Default is 'watchcat.yml'.") do |v|
+            options[:config] = v
+          end
+
+          opts.on("--init PATH", "Generate a template config file at the specified path") do |v|
+            options[:init] = v
+          end
+
+          opts.on("-h", "--help", "Show this help message") do
+            puts opts
+            exit
+          end
+        end.parse!(argv)
+
+        if !options[:init] && options[:config].nil?
+          raise OptionParser::MissingArgument.new("-C")
+        end
+
+        options
+      end
+    end
+  end
+end