grepfruit 3.1.2 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c2c091bc89ae552d6393fd2314bc30fa6f858b426d7690145aa54d6f2c9ef7f
-  data.tar.gz: 5920dfde71947661dc0ec33318dcb6679f9b899c03bd42d6b61654503435dfbf
+  metadata.gz: 505fa3f2e5b4b5ffc41a795f0305e6a37f913b7fe66036018d4f4438dc6c9b40
+  data.tar.gz: 3f89449fd5ab9d2851aadac1ec432606aeaae73b4673bd0d4e62cd96b4bdc83f
 SHA512:
-  metadata.gz: 1dd7f640198928a13d1e118771a6c47986c753a5e997b8fc53fce5ac2b9b8135ce30986eb9a6d5141600f7985a461c59c24b41c611c8a55f2d7050bb6d0e2d4f
-  data.tar.gz: ae7d0e5a09554f03accf9f144a0e9448044728e53a22228ac9dd8cf343a75814cc831ef28a58b75e64af35d3aa50e801945e440d9c607fdfd82e11d889e66996
+  metadata.gz: 2e2ff1bdec53492186f6ff37670e82b62ee72ff84435c68167bd7ef7ae460ee23221dbc1d0682205207acc579660675ea4504b6722498e51520465fb9ac79cbe
+  data.tar.gz: 4dac4064e07aafd907523d6223dfa789eae14428a5e92b4edcb82ef206391e179e469f76db56d972bbc01815be0c58f3c574353832eb45bfbb942d89b21a052e

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## v3.2.0
+
+- Added programmatic API for use in Ruby applications
+- Added --count option to display only the count of matches
+- Added support for Ruby 4
+
+## v3.1.3
+
+- Fixed race condition in worker shutdown
+
 ## v3.1.2
 
 - Corrected usage of `dry-cli` gem for flag handling

data/README.md

@@ -1,16 +1,14 @@
-# Grepfruit: Enhanced File Pattern Search Tool
+# Grepfruit: Text Search Tool
 
 [![Gem Version](https://badge.fury.io/rb/grepfruit.svg)](http://badge.fury.io/rb/grepfruit)
-[![Github Actions badge](https://github.com/brownboxdev/grepfruit/actions/workflows/ci.yml/badge.svg)](https://github.com/brownboxdev/grepfruit/actions/workflows/ci.yml)
+[![Downloads](https://img.shields.io/gem/dt/grepfruit.svg)](https://rubygems.org/gems/grepfruit)
+[![Github Actions badge](https://github.com/enjaku4/grepfruit/actions/workflows/ci.yml/badge.svg)](https://github.com/enjaku4/grepfruit/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/enjaku4/grepfruit.svg)](LICENSE)
 
-Grepfruit is a Ruby gem for searching files within a directory for specified regular expression patterns, with exclusion and inclusion options and JSON-formatted or colorized output for enhanced readability. Originally designed for CI/CD pipelines to search for `TODO` comments in Ruby on Rails applications, Grepfruit provides more user-friendly output than the standard `grep` command while maintaining the flexibility for diverse search scenarios.
+Grepfruit is a tool for searching regex patterns in files, with a CLI designed for CI/CD pipelines and a programmatic API for Ruby applications.
 
-**Key Features:**
-
-- Parallel search using Ractors
-- JSON output format for programmatic integration
-- Colorized output for improved readability
-- CI/CD pipeline friendly exit codes
+<img width="933" height="221" alt="Screenshot 2025-10-15 at 13 28 06" src="https://github.com/user-attachments/assets/cad09b17-9b79-4377-8cf9-365108a96a5a" />
+<img width="709" height="586" alt="Screenshot 2025-10-15 at 13 29 01" src="https://github.com/user-attachments/assets/36664522-1eee-40bf-8f58-a2503668e1a4" />
 
 ## Table of Contents
 
@@ -20,6 +18,7 @@ Grepfruit is a Ruby gem for searching files within a directory for specified reg
   - [Command Line Options](#command-line-options)
   - [Usage Examples](#usage-examples)
   - [Exit Status](#exit-status)
+  - [Programmatic API](#programmatic-api)
 
 **Community Resources:**
   - [Getting Help and Contributing](#getting-help-and-contributing)
@@ -30,7 +29,7 @@ Grepfruit is a Ruby gem for searching files within a directory for specified reg
 
 Install the gem:
 
-```bash
+```shell
 gem install grepfruit
 ```
 
@@ -59,6 +58,7 @@ If no PATH is specified, Grepfruit searches the current directory.
 | `-i, --include x,y,z` | Comma-separated list of file patterns to include (only these files will be searched) |
 | `-t, --truncate N` | Truncate search result output to N characters |
 | `-j, --jobs N` | Number of parallel workers (default: number of CPU cores) |
+| `-c, --count` | Show only match counts, not match details |
 | `--search-hidden` | Include hidden files and directories in search |
 | `--json` | Output results in JSON format |
 
@@ -156,9 +156,18 @@ This outputs a JSON response containing search metadata, summary statistics, and
 }
 ```
 
+### Count Only Mode
+
+Show only match counts without displaying the actual matches:
+
+```bash
+grepfruit search -r 'TODO' --count
+grepfruit search -r 'FIXME|TODO' -c -e 'vendor,node_modules'
+```
+
 ### Parallel Processing
 
-Control the number of parallel workers:
+Grepfruit uses ractors for true parallel processing across CPU cores. Control the number of parallel workers:
 
 ```bash
 grepfruit search -r 'TODO' -j 8  # Use 8 parallel workers
@@ -172,16 +181,57 @@ Grepfruit returns meaningful exit codes for CI/CD integration:
 - **Exit code 0**: No matches found (ideal for quality gates - code is clean)
 - **Exit code 1**: Pattern matches were found (CI should fail - issues detected)
 
+## Programmatic API
+
+Use Grepfruit directly in Ruby applications:
+
+```rb
+result = Grepfruit.search(
+  regex: /TODO|FIXME/,
+  path: "app",
+  exclude: ["tmp", "vendor"],
+  include: ["*.rb"],
+  truncate: 80,
+  search_hidden: false,
+  jobs: 4,
+  count: false
+)
+```
+
+Returns a hash (note: when `count: true`, the `matches` key is omitted):
+
+```rb
+{
+  search: {
+    pattern: /TODO|FIXME/,
+    directory: "/path/to/app",
+    exclusions: ["tmp", "vendor"],
+    inclusions: ["*.rb"]
+  },
+  summary: {
+    files_checked: 42,
+    files_with_matches: 8,
+    total_matches: 23
+  },
+  matches: [
+    { file: "models/user.rb", line: 15, content: "# TODO: add validation" },
+    # ...
+  ]
+}
+```
+
+All keyword arguments correspond to their CLI flag counterparts.
+
 ## Getting Help and Contributing
 
 ### Getting Help
-Have a question or need assistance? Open a discussion in our [discussions section](https://github.com/brownboxdev/grepfruit/discussions) for:
+Have a question or need assistance? Open a discussion in our [discussions section](https://github.com/enjaku4/grepfruit/discussions) for:
 - Usage questions
 - Implementation guidance
 - Feature suggestions
 
 ### Reporting Issues
-Found a bug? Please [create an issue](https://github.com/brownboxdev/grepfruit/issues) with:
+Found a bug? Please [create an issue](https://github.com/enjaku4/grepfruit/issues) with:
 - A clear description of the problem
 - Steps to reproduce the issue
 - Your environment details (Ruby version, OS, etc.)
@@ -190,14 +240,14 @@ Found a bug? Please [create an issue](https://github.com/brownboxdev/grepfruit/i
 Ready to contribute? You can:
 - Fix bugs by submitting pull requests
 - Improve documentation
-- Add new features (please discuss first in our [discussions section](https://github.com/brownboxdev/grepfruit/discussions))
+- Add new features (please discuss first in our [discussions section](https://github.com/enjaku4/grepfruit/discussions))
 
-Before contributing, please read the [contributing guidelines](https://github.com/brownboxdev/grepfruit/blob/master/CONTRIBUTING.md)
+Before contributing, please read the [contributing guidelines](https://github.com/enjaku4/grepfruit/blob/master/CONTRIBUTING.md)
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://github.com/brownboxdev/grepfruit/blob/master/LICENSE.txt).
+The gem is available as open source under the terms of the [MIT License](https://github.com/enjaku4/grepfruit/blob/master/LICENSE.txt).
 
 ## Code of Conduct
 
-Everyone interacting in the Grepfruit project is expected to follow the [code of conduct](https://github.com/brownboxdev/grepfruit/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Grepfruit project is expected to follow the [code of conduct](https://github.com/enjaku4/grepfruit/blob/master/CODE_OF_CONDUCT.md).

data/grepfruit.gemspec

@@ -4,14 +4,19 @@ Gem::Specification.new do |spec|
   spec.name = "grepfruit"
   spec.version = Grepfruit::VERSION
   spec.authors = ["enjaku4"]
-  spec.homepage = "https://github.com/brownboxdev/grepfruit"
+  spec.email = ["contact@brownbox.dev"]
+  spec.homepage = "https://github.com/enjaku4/grepfruit"
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["documentation_uri"] = "#{spec.homepage}/blob/master/README.md"
+  spec.metadata["mailing_list_uri"] = "#{spec.homepage}/discussions"
   spec.metadata["rubygems_mfa_required"] = "true"
-  spec.summary = "A Ruby gem for searching text patterns in files with colorized output"
+  spec.summary = "Text search tool"
+  spec.description = "A tool for searching regex patterns in files with a CI/CD-friendly CLI and a programmatic Ruby API"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.2", "< 3.5"
+  spec.required_ruby_version = ">= 3.2", "< 4.1"
 
   spec.files = [
     "grepfruit.gemspec", "README.md", "CHANGELOG.md", "LICENSE.txt"

data/lib/grepfruit/cli.rb

@@ -16,35 +16,33 @@ module Grepfruit
       option :search_hidden, type: :flag, default: false, desc: "Search hidden files and directories"
       option :jobs, aliases: ["-j"], type: :integer, desc: "Number of parallel workers (default: all CPU cores, use 1 for sequential)"
       option :json, type: :flag, default: false, desc: "Output results in JSON format"
+      option :count, aliases: ["-c"], type: :flag, default: false, desc: "Show only counts, not match details"
 
       def call(path: ".", **options)
-        validate_options!(options)
+        error_exit("You must specify a regex pattern using the -r or --regex option.") unless options[:regex]
+        error_exit("Jobs must be at least 1") if options[:jobs] && options[:jobs].to_i < 1
+
+        begin
+          regex_pattern = Regexp.new(options[:regex])
+        rescue RegexpError => e
+          error_exit("Invalid regex pattern - #{e.message}")
+        end
 
-        Grepfruit::Search.new(
-          dir: path,
-          regex: create_regex(options[:regex]),
+        Grepfruit::CliSearch.new(
+          path: path,
+          regex: regex_pattern,
           exclude: options[:exclude] || [],
           include: options[:include] || [],
           truncate: options[:truncate]&.to_i,
           search_hidden: options[:search_hidden],
           jobs: options[:jobs]&.to_i,
-          json_output: options[:json]
-        ).run
+          json: options[:json],
+          count: options[:count]
+        ).execute
       end
 
       private
 
-      def validate_options!(options)
-        error_exit("You must specify a regex pattern using the -r or --regex option.") unless options[:regex]
-        error_exit("Number of jobs must be at least 1") if (jobs = options[:jobs]&.to_i) && jobs < 1
-      end
-
-      def create_regex(pattern)
-        Regexp.new(pattern)
-      rescue RegexpError => e
-        error_exit("Invalid regex pattern - #{e.message}")
-      end
-
       def error_exit(message)
         puts "Error: #{message}"
         exit 1

data/lib/grepfruit/cli_decorator.rb

@@ -0,0 +1,42 @@
+module Grepfruit
+  module CliDecorator
+    COLORS = { cyan: "\e[36m", red: "\e[31m", green: "\e[32m", reset: "\e[0m" }.freeze
+
+    private
+
+    def colorize(text, color) = "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+    def green(text) = colorize(text, :green)
+    def red(text) = colorize(text, :red)
+    def cyan(text) = colorize(text, :cyan)
+
+    def number_of_files(num) = "#{num} file#{'s' if num != 1}"
+    def number_of_matches(num) = "#{num} match#{'es' if num != 1}"
+
+    def display_results(results)
+      puts "" if results.total_files.positive?
+
+      if results.match_count.zero?
+        puts "#{number_of_files(results.total_files)} checked, #{green('no matches found')}"
+      else
+        unless count
+          puts "Matches:\n\n"
+          results.raw_matches.each do |line_info|
+            puts "#{cyan("#{line_info[0]}:#{line_info[1]}")}: #{processed_line(line_info[2])}"
+          end
+          puts ""
+        end
+
+        puts "#{number_of_files(results.total_files)} checked, #{red("#{number_of_matches(results.match_count)} found in #{number_of_files(results.total_files_with_matches)}")}"
+      end
+    end
+
+    def display_json_results(result_hash)
+      require "json"
+
+      result_hash[:search][:pattern] = result_hash[:search][:pattern].inspect
+      result_hash[:search][:timestamp] = Time.now.strftime("%Y-%m-%dT%H:%M:%S%z")
+
+      puts JSON.pretty_generate(result_hash)
+    end
+  end
+end

data/lib/grepfruit/cli_search.rb

@@ -0,0 +1,23 @@
+require_relative "cli_decorator"
+
+module Grepfruit
+  class CliSearch < Search
+    include Grepfruit::CliDecorator
+
+    def execute
+      puts "Error: Directory '#{path}' does not exist." and exit 1 unless File.exist?(path)
+
+      puts "Searching for #{regex.inspect} in #{path.inspect}..." unless json
+
+      results = execute_search
+
+      if json
+        display_json_results(build_result_hash(results))
+      else
+        display_results(results)
+      end
+
+      exit(results.match_count.positive? ? 1 : 0)
+    end
+  end
+end

data/lib/grepfruit/programmatic_search.rb

@@ -0,0 +1,9 @@
+module Grepfruit
+  class ProgrammaticSearch < Search
+    def execute
+      raise ArgumentError, "directory '#{path}' does not exist." unless File.exist?(path)
+
+      build_result_hash(execute_search)
+    end
+  end
+end

data/lib/grepfruit/ractor_compat.rb

@@ -0,0 +1,43 @@
+module Grepfruit
+  module RactorCompat
+    module_function
+
+    def send_work(worker, data)
+      worker.send(data)
+    end
+
+    if defined?(::Ractor::Port)
+      def create_worker(&)
+        port = Ractor::Port.new
+        worker = Ractor.new(port, &)
+        [worker, port]
+      end
+
+      def yield_result(port, data)
+        port << data
+      end
+
+      def select_ready(workers_and_ports)
+        ports = workers_and_ports.values
+        ready_port, result = Ractor.select(*ports)
+        worker = workers_and_ports.key(ready_port)
+        [worker, result]
+      end
+    else
+      def create_worker(&)
+        worker = Ractor.new(&)
+        [worker, nil]
+      end
+
+      def yield_result(_port, data)
+        Ractor.yield(data)
+      end
+
+      def select_ready(workers_and_ports)
+        workers = workers_and_ports.keys
+        ready_worker, result = Ractor.select(*workers)
+        [ready_worker, result]
+      end
+    end
+  end
+end

data/lib/grepfruit/search.rb

@@ -1,93 +1,122 @@
 require "find"
 require "etc"
+require_relative "ractor_compat"
 
 Warning[:experimental] = false
 
 module Grepfruit
   class Search
-    include Decorator
+    attr_reader :path, :regex, :exclusions, :inclusions, :excluded_paths, :excluded_lines, :included_paths, :truncate, :search_hidden, :jobs, :json, :count
 
-    attr_reader :dir, :regex, :excluded_paths, :excluded_lines, :included_paths, :truncate, :search_hidden, :jobs, :json_output
-
-    def initialize(dir:, regex:, exclude:, include:, truncate:, search_hidden:, jobs:, json_output: false)
-      @dir = File.expand_path(dir)
+    def initialize(path:, regex:, exclude:, include:, truncate:, search_hidden:, jobs:, json: false, count: false)
+      @path = File.expand_path(path)
       @regex = regex
+      @exclusions = exclude
+      @inclusions = include
       @excluded_lines, @excluded_paths = exclude.map { _1.split("/") }.partition { _1.last.include?(":") }
       @included_paths = include.map { _1.split("/") }
       @truncate = truncate
       @search_hidden = search_hidden
       @jobs = jobs || Etc.nprocessors
-      @json_output = json_output
+      @json = json
+      @count = count
     end
 
-    def run
-      puts "Searching for #{regex.inspect} in #{dir.inspect}...\n\n" unless json_output
+    private
 
-      display_final_results(execute_search)
-    end
+    def build_result_hash(results)
+      result_hash = {
+        search: {
+          pattern: regex,
+          directory: path,
+          exclusions: exclusions,
+          inclusions: inclusions
+        },
+        summary: {
+          files_checked: results.total_files,
+          files_with_matches: results.total_files_with_matches,
+          total_matches: results.match_count
+        }
+      }
+
+      unless count
+        result_hash[:matches] = results.raw_matches.map do |relative_path, line_num, line_content|
+          {
+            file: relative_path,
+            line: line_num,
+            content: processed_line(line_content)
+          }
+        end
+      end
 
-    private
+      result_hash
+    end
 
     def execute_search
       results = SearchResults.new
-      workers = Array.new(jobs) { create_persistent_worker }
+      workers_and_ports = Array.new(jobs) { create_persistent_worker }
       file_enumerator = create_file_enumerator
       active_workers = {}
 
-      workers.each do |worker|
-        assign_file_to_worker(worker, file_enumerator, active_workers, results)
+      workers_and_ports.each do |worker, port|
+        assign_file_to_worker(worker, port, file_enumerator, active_workers, results)
       end
 
       while active_workers.any?
-        ready_worker, worker_result = Ractor.select(*active_workers.keys)
-        active_workers.delete(ready_worker)
+        ready_worker, worker_result = RactorCompat.select_ready(active_workers)
+        port = active_workers.delete(ready_worker)
 
         results.increment_files_with_matches if process_worker_result(worker_result, results)
-        assign_file_to_worker(ready_worker, file_enumerator, active_workers, results)
+        assign_file_to_worker(ready_worker, port, file_enumerator, active_workers, results)
       end
 
-      shutdown_workers(workers)
+      shutdown_workers(workers_and_ports.map(&:first))
+
       results
     end
 
-    def display_final_results(results)
-      if json_output
-        display_json_results(results.raw_matches, results.total_files, results.total_files_with_matches)
-      else
-        display_results(results.all_lines, results.total_files, results.total_files_with_matches)
-      end
+    def process_worker_result(worker_result, results)
+      file_results, has_matches, match_count = worker_result
+
+      return false unless has_matches
+
+      results.add_match_count(match_count)
+      results.add_raw_matches(file_results)
+
+      true
     end
 
     def create_persistent_worker
-      Ractor.new do
+      RactorCompat.create_worker do |port|
         loop do
           work = Ractor.receive
           break if work == :quit
 
-          file_path, pattern, exc_lines, base_dir = work
-          file_results, has_matches = [], false
+          file_path, pattern, exc_lines, base_path, count = work
+          file_results, has_matches, match_count = [], false, 0
+          relative_path = file_path.delete_prefix("#{base_path}/")
 
           File.foreach(file_path).with_index do |line, line_num|
             next unless line.valid_encoding? && line.match?(pattern)
 
-            relative_path = file_path.delete_prefix("#{base_dir}/")
             next if exc_lines.any? { "#{relative_path}:#{line_num + 1}".end_with?(_1.join("/")) }
 
-            file_results << [relative_path, line_num + 1, line]
+            file_results << [relative_path, line_num + 1, line] unless count
             has_matches = true
+            match_count += 1
           end
 
-          Ractor.yield([file_results, has_matches])
+          RactorCompat.yield_result(port, [file_results, has_matches, match_count])
         end
       end
     end
 
-    def assign_file_to_worker(worker, file_enumerator, active_workers, results)
+    def assign_file_to_worker(worker, port, file_enumerator, active_workers, results)
       file_path = get_next_file(file_enumerator)
       return unless file_path
 
-      worker.send([file_path, regex, excluded_lines, dir])
-      active_workers[worker] = file_path
+      RactorCompat.send_work(worker, [file_path, regex, excluded_lines, path, count])
+      active_workers[worker] = port
       results.total_files += 1
     end
 
@@ -99,50 +128,26 @@ module Grepfruit
 
     def shutdown_workers(workers)
       workers.each { |worker| worker.send(:quit) }
-      workers.each(&:close_outgoing)
     end
 
     def create_file_enumerator
       Enumerator.new do |yielder|
-        Find.find(dir) do |path|
-          Find.prune if excluded_path?(path)
-
-          next unless File.file?(path)
-
-          yielder << path
-        end
-      rescue Errno::ENOENT
-        puts "Error: Directory '#{dir}' does not exist."
-        exit 1
-      end
-    end
+        Find.find(path) do |file_path|
+          Find.prune if excluded_path?(file_path)
 
-    def process_worker_result(worker_result, results)
-      file_results, has_matches = worker_result
-
-      if has_matches
-        results.add_raw_matches(file_results) if json_output
+          next unless File.file?(file_path)
 
-        unless json_output
-          colored_lines = file_results.map do |relative_path, line_num, line_content|
-            "#{cyan("#{relative_path}:#{line_num}")}: #{processed_line(line_content)}"
-          end
-          results.add_lines(colored_lines)
-          print red("M")
+          yielder << file_path
         end
-      else
-        print green(".") unless json_output
       end
-
-      has_matches
     end
 
-    def excluded_path?(path)
-      rel_path = path.delete_prefix("#{dir}/")
+    def excluded_path?(file_path)
+      rel_path = file_path.delete_prefix("#{path}/")
 
-      (File.file?(path) && included_paths.any? && !matches_pattern?(included_paths, rel_path)) ||
+      (File.file?(file_path) && included_paths.any? && !matches_pattern?(included_paths, rel_path)) ||
         matches_pattern?(excluded_paths, rel_path) ||
-        (!search_hidden && File.basename(path).start_with?("."))
+        (!search_hidden && File.basename(file_path).start_with?("."))
     end
 
     def matches_pattern?(pattern_list, path)
@@ -151,5 +156,10 @@ module Grepfruit
         File.fnmatch?(pattern, path, File::FNM_PATHNAME) || File.fnmatch?(pattern, File.basename(path))
       end
     end
+
+    def processed_line(line)
+      stripped = line.strip
+      truncate && stripped.length > truncate ? "#{stripped[0...truncate]}..." : stripped
+    end
   end
 end

data/lib/grepfruit/search_results.rb

@@ -1,21 +1,21 @@
 module Grepfruit
   class SearchResults
-    attr_reader :all_lines, :raw_matches, :total_files_with_matches
+    attr_reader :raw_matches, :total_files_with_matches, :match_count
     attr_accessor :total_files
 
     def initialize
-      @all_lines = []
       @raw_matches = []
       @total_files = 0
       @total_files_with_matches = 0
+      @match_count = 0
     end
 
     def increment_files_with_matches
       @total_files_with_matches += 1
     end
 
-    def add_lines(lines)
-      @all_lines.concat(lines)
+    def add_match_count(count)
+      @match_count += count
     end
 
     def add_raw_matches(matches)

data/lib/grepfruit/version.rb

@@ -1,3 +1,3 @@
 module Grepfruit
-  VERSION = "3.1.2".freeze
+  VERSION = "3.2.0".freeze
 end

data/lib/grepfruit.rb

@@ -1,9 +1,31 @@
 require_relative "grepfruit/version"
-require_relative "grepfruit/decorator"
 require_relative "grepfruit/search_results"
 require_relative "grepfruit/search"
+require_relative "grepfruit/programmatic_search"
 require_relative "grepfruit/cli"
+require_relative "grepfruit/cli_search"
 
 module Grepfruit
-  class Error < StandardError; end
+  def self.search(regex:, path: ".", exclude: [], include: [], truncate: nil, search_hidden: false, jobs: nil, count: false)
+    raise ArgumentError, "regex is required" unless regex.is_a?(Regexp)
+    raise ArgumentError, "path must be a string" unless path.is_a?(String)
+    raise ArgumentError, "exclude must be an array" unless exclude.is_a?(Array)
+    raise ArgumentError, "include must be an array" unless include.is_a?(Array)
+    raise ArgumentError, "truncate must be a positive integer" if truncate && (!truncate.is_a?(Integer) || truncate <= 0)
+    raise ArgumentError, "search_hidden must be a boolean" unless [true, false].include?(search_hidden)
+    raise ArgumentError, "count must be a boolean" unless [true, false].include?(count)
+    raise ArgumentError, "jobs must be at least 1" if jobs && (!jobs.is_a?(Integer) || jobs < 1)
+
+    ProgrammaticSearch.new(
+      path: path,
+      regex: regex,
+      exclude: exclude,
+      include: include,
+      truncate: truncate,
+      search_hidden: search_hidden,
+      jobs: jobs,
+      json: false,
+      count: count
+    ).execute
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grepfruit
 version: !ruby/object:Gem::Version
-  version: 3.1.2
+  version: 3.2.0
 platform: ruby
 authors:
 - enjaku4
@@ -23,6 +23,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+description: A tool for searching regex patterns in files with a CI/CD-friendly CLI
+  and a programmatic Ruby API
+email:
+- contact@brownbox.dev
 executables:
 - grepfruit
 extensions: []
@@ -35,17 +39,23 @@ files:
 - grepfruit.gemspec
 - lib/grepfruit.rb
 - lib/grepfruit/cli.rb
-- lib/grepfruit/decorator.rb
+- lib/grepfruit/cli_decorator.rb
+- lib/grepfruit/cli_search.rb
+- lib/grepfruit/programmatic_search.rb
+- lib/grepfruit/ractor_compat.rb
 - lib/grepfruit/search.rb
 - lib/grepfruit/search_results.rb
 - lib/grepfruit/version.rb
-homepage: https://github.com/brownboxdev/grepfruit
+homepage: https://github.com/enjaku4/grepfruit
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/brownboxdev/grepfruit
-  source_code_uri: https://github.com/brownboxdev/grepfruit
-  changelog_uri: https://github.com/brownboxdev/grepfruit/blob/master/CHANGELOG.md
+  homepage_uri: https://github.com/enjaku4/grepfruit
+  source_code_uri: https://github.com/enjaku4/grepfruit
+  changelog_uri: https://github.com/enjaku4/grepfruit/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/enjaku4/grepfruit/issues
+  documentation_uri: https://github.com/enjaku4/grepfruit/blob/master/README.md
+  mailing_list_uri: https://github.com/enjaku4/grepfruit/discussions
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -57,14 +67,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.2'
   - - "<"
     - !ruby/object:Gem::Version
-      version: '3.5'
+      version: '4.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.0
 specification_version: 4
-summary: A Ruby gem for searching text patterns in files with colorized output
+summary: Text search tool
 test_files: []

data/lib/grepfruit/decorator.rb

@@ -1,73 +0,0 @@
-module Grepfruit
-  module Decorator
-    COLORS = { cyan: "\e[36m", red: "\e[31m", green: "\e[32m", reset: "\e[0m" }.freeze
-
-    private
-
-    def colorize(text, color) = "#{COLORS[color]}#{text}#{COLORS[:reset]}"
-    def green(text) = colorize(text, :green)
-    def red(text) = colorize(text, :red)
-    def cyan(text) = colorize(text, :cyan)
-
-    def number_of_files(num) = "#{num} file#{'s' if num != 1}"
-    def number_of_matches(num) = "#{num} match#{'es' if num != 1}"
-
-    def relative_path(path)
-      path.delete_prefix("#{dir}/")
-    end
-
-    def processed_line(line)
-      stripped = line.strip
-      truncate && stripped.length > truncate ? "#{stripped[0...truncate]}..." : stripped
-    end
-
-    def display_results(lines, files, files_with_matches)
-      puts "\n\n" if files.positive?
-
-      if lines.empty?
-        puts "#{number_of_files(files)} checked, #{green('no matches found')}"
-        exit(0)
-      else
-        puts "Matches:\n\n#{lines.join("\n")}\n\n"
-        puts "#{number_of_files(files)} checked, #{red("#{number_of_matches(lines.size)} found in #{number_of_files(files_with_matches)}")}"
-        exit(1)
-      end
-    end
-
-    def display_json_results(raw_matches, total_files, files_with_matches)
-      require "json"
-
-      search_info = {
-        pattern: regex.inspect,
-        directory: dir,
-        exclusions: (excluded_paths + excluded_lines).map { |path_parts| path_parts.join("/") },
-        inclusions: included_paths.map { |path_parts| path_parts.join("/") },
-        timestamp: Time.now.strftime("%Y-%m-%dT%H:%M:%S%z")
-      }
-
-      summary = {
-        files_checked: total_files,
-        files_with_matches: files_with_matches,
-        total_matches: raw_matches.size
-      }
-
-      matches = raw_matches.map do |relative_path, line_num, line_content|
-        {
-          file: relative_path,
-          line: line_num,
-          content: line_content.strip
-        }
-      end
-
-      result = {
-        search: search_info,
-        summary: summary,
-        matches: matches
-      }
-
-      puts JSON.pretty_generate(result)
-
-      exit(raw_matches.empty? ? 0 : 1)
-    end
-  end
-end