alkaid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ef727b8066a385651c5f821819905bec5bcd24b167c080994ccd7e0672564a9
+  data.tar.gz: a6e3dc037e5e0eb6421e9f73d59fc72a935b400baf568b0c7149be2301ad6271
+SHA512:
+  metadata.gz: 0c06a4ee2bf56f663536a97d5210758cbb7ecfc6702ea0e55f4c0330ca6105a67b09ca4b082ccfe0fcc2ca2550bc3066ee830c88da555e1b331209579439f6b5
+  data.tar.gz: b1167dba94c0d9c37d0a342017c146bf8af666d790a57d7f2eea1af280c632d15a52b705a64e9c9f7d91b037f58ce1397593911f7eab1a51d8565dbe032f3e7a

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - 2026-09-15
+
+- Add deterministic recursive file walking with duck-typed ignore rules
+- Add serial and process-parallel literal and regular-expression search
+- Add binary, UTF-8, glob, size, cancellation, and progress handling
+- Add Ruby 3.1-compatible regular-expression timeouts and byte offsets
+- Support regular-expression matches spanning multiple lines

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,71 @@
+# Alkaid
+
+Alkaid is a pure Ruby file walker and parallel content search library. It
+streams deterministic, byte-accurate matches without depending on an editor,
+Git implementation, or fuzzy matcher.
+
+## Installation
+
+```ruby
+gem "alkaid"
+```
+
+## Usage
+
+```ruby
+require "alkaid"
+
+search = Alkaid::Search.new(
+  Dir.pwd,
+  pattern: "TODO",
+  include: ["**/*.rb"],
+  workers: 4
+)
+
+search.run do |match|
+  puts "#{match.path}:#{match.line_number}:#{match.byte_offset}"
+end
+```
+
+`byte_offset` is the match's zero-based offset in the file. `ranges` contains
+zero-based byte ranges in `line`, which retains its original line ending.
+For a match spanning lines, `line` contains the complete lines touched by the
+match and `line_number` identifies the first one.
+Results are ordered by relative path and byte offset even when worker processes
+are enabled.
+
+Pass any ignore object that implements `ignored?(path, directory:)`. Alkaid
+does not parse ignore files and does not depend on a Git library:
+
+```ruby
+ignore = MyIgnoreMatcher.new
+files = Alkaid::Walker.new(Dir.pwd, ignore: ignore).to_a
+search = Alkaid::Search.new(Dir.pwd, pattern: /error/i, ignore: ignore)
+```
+
+Literal and regular-expression searches support case folding, whole-word
+matching, include/exclude globs, file-size limits, result limits, cancellation,
+and optional symlink or hidden-file traversal. Binary and invalid UTF-8 files
+are skipped.
+
+```ruby
+search.cancel
+progress = search.progress
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rbs -I sig validate
+BUDGET=1 bundle exec rake bench
+gem build --strict alkaid.gemspec
+```
+
+Use `FILES=100000 BYTES=10000 bundle exec rake bench` to exercise the full
+100,000-file, approximately 1 GB design workload.
+
+## License
+
+Alkaid is available under the MIT License.

data/docs/adr/000-template.md

@@ -0,0 +1,17 @@
+# ADR NNN: Implementation decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the concrete implementation question and its compatibility, data,
+runtime, or component constraints.
+
+## Decision
+
+Describe the durable boundary or architecture choice.
+
+## Consequences
+
+Describe the important positive and negative trade-offs and when to revisit it.

data/docs/adr/001-duck-typed-ignore-rules.md

@@ -0,0 +1,22 @@
+# ADR 001: Keep ignore rules outside Alkaid
+
+- Status: Accepted
+- Date: 2026-09-15
+
+## Context
+
+File search needs to skip ignored paths, but interpreting Git ignore files is a
+Git responsibility. Depending on one Git implementation would couple general
+filesystem search to an unrelated component and release cycle.
+
+## Decision
+
+Accept ignore matchers through the single `ignored?(path, directory:)`
+operation. Alkaid owns traversal and invokes the supplied matcher with paths
+relative to the search root.
+
+## Consequences
+
+Callers may use any ignore implementation and Alkaid has no runtime gem
+dependencies. Callers that need Git-compatible rules must construct and pass a
+matcher themselves.

data/docs/adr/README.md

@@ -0,0 +1,3 @@
+# Architecture decision records
+
+These records document Alkaid's durable boundaries.

data/lib/alkaid/match_data_compat.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+unless MatchData.method_defined?(:byteoffset) && MatchData.method_defined?(:bytebegin)
+  class MatchData
+    unless method_defined?(:byteoffset)
+      def byteoffset(index)
+        first, last = offset(index)
+        first && [string[0...first].bytesize, string[0...last].bytesize]
+      end
+    end
+
+    unless method_defined?(:bytebegin)
+      def bytebegin(index) = byteoffset(index)&.first
+      def byteend(index) = byteoffset(index)&.last
+    end
+  end
+end

data/lib/alkaid/regexp_compat.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+unless Regexp.respond_to?(:timeout)
+  require "timeout"
+
+  class Regexp
+    TimeoutError = Class.new(StandardError) unless const_defined?(:TimeoutError, false)
+    TIMEOUTS = ObjectSpace::WeakMap.new unless const_defined?(:TIMEOUTS, false)
+  end
+
+  unless Regexp.method_defined?(:timeout)
+    class Regexp
+      def timeout = TIMEOUTS[self]
+    end
+
+    Regexp.singleton_class.prepend(Module.new do
+      def new(*arguments, timeout: nil)
+        if timeout
+          raise TypeError, "timeout must be numeric" unless timeout.is_a?(Numeric)
+
+          timeout = timeout.to_f
+          timeout = nil if timeout.nan?
+          raise ArgumentError, "invalid timeout" if timeout && !timeout.positive?
+        end
+        expression = super(*arguments)
+        Regexp::TIMEOUTS[expression] = timeout
+        expression
+      end
+    end)
+  end
+
+  module Alkaid
+    def self.with_regexp_timeout(expression)
+      timeout = expression.timeout
+      timeout && timeout.finite? ? Timeout.timeout(timeout, Regexp::TimeoutError) { yield } : yield
+    end
+  end
+else
+  module Alkaid
+    def self.with_regexp_timeout(_expression) = yield
+  end
+end

data/lib/alkaid/search.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "thread"
+require_relative "search_worker"
+require_relative "search_pool"
+
+module Alkaid
+  class Search
+    DEFAULT_MAX_FILE_SIZE = 16 * 1024 * 1024
+
+    def initialize(root, pattern:, regexp: false, ignore_case: false, whole_word: false,
+      include: [], exclude: [], ignore: nil, workers: 4, max_file_size: DEFAULT_MAX_FILE_SIZE,
+      max_matches: nil, follow_symlinks: false, hidden: false, max_depth: nil,
+      extensions: nil, paths: nil, cancelled: nil)
+      validate_options(pattern, include, exclude, ignore, workers, max_file_size, max_matches, extensions, paths,
+        cancelled, regexp, ignore_case, whole_word, follow_symlinks, hidden)
+      @root = File.realpath(root)
+      raise ArgumentError, "root must be a directory" unless File.directory?(@root)
+
+      @expression, @timeout = expression(pattern, regexp, ignore_case, whole_word)
+      @include = include.map(&:dup).map(&:freeze).freeze
+      @exclude = exclude.map(&:dup).map(&:freeze).freeze
+      @workers = workers
+      @max_file_size = [max_file_size || SearchWorker::MAX_FILE_BYTES, SearchWorker::MAX_FILE_BYTES].min
+      @max_matches = max_matches
+      @extensions = extensions&.map { |extension| (extension.start_with?(".") ? extension.dup : ".#{extension}").freeze }&.freeze
+      @paths = paths&.map(&:dup)&.map(&:freeze)&.freeze
+      @external_cancelled = cancelled
+      @walker = Walker.new(@root, ignore: ignore, follow_symlinks: follow_symlinks, hidden: hidden,
+        max_depth: max_depth, cancelled: method(:cancelled?))
+      @mutex = Mutex.new
+      @progress = Progress.new(files_scanned: 0, bytes_scanned: 0, matches: 0)
+      @cancelled = false
+      @running = false
+    end
+
+    def run
+      started = false
+      begin_run
+      started = true
+      files = search_paths
+      return [] if files.empty?
+
+      results = []
+      receive = receiver(results) { |match| yield match if block_given? }
+      if @workers > 1 && files.length > 1
+        parallel(files, [@workers, files.length].min, &receive)
+      else
+        SearchWorker.scan(@root, files, @expression, @max_file_size, @max_matches,
+          cancelled: method(:cancelled?), &receive)
+      end
+      SearchWorker.check_cancelled(method(:cancelled?))
+      results
+    rescue SearchWorker::Cancelled
+      []
+    ensure
+      @mutex.synchronize { @running = false } if started
+    end
+
+    def cancel
+      @mutex.synchronize { @cancelled = true }
+      nil
+    end
+
+    def progress = @mutex.synchronize { @progress }
+
+    private
+
+    def validate_options(pattern, includes, excludes, ignore, workers, max_file_size, max_matches, extensions, paths,
+      cancelled, *flags)
+      raise ArgumentError, "pattern must be a String or Regexp" unless pattern.is_a?(String) || pattern.is_a?(Regexp)
+      raise ArgumentError, "pattern must use a valid encoding" if pattern.is_a?(String) && !pattern.valid_encoding?
+      raise ArgumentError, "search flags must be boolean" unless flags.all? { |value| value == true || value == false }
+      raise ArgumentError, "workers must be between 1 and 32" unless workers.is_a?(Integer) && workers.between?(1, 32)
+      if max_file_size && (!max_file_size.is_a?(Integer) || max_file_size.negative?)
+        raise ArgumentError, "max_file_size must be nonnegative"
+      end
+      if max_matches && (!max_matches.is_a?(Integer) || !max_matches.positive?)
+        raise ArgumentError, "max_matches must be positive"
+      end
+      raise ArgumentError, "ignore must respond to ignored?" if ignore && !ignore.respond_to?(:ignored?)
+      raise ArgumentError, "cancelled must respond to call" if cancelled && !cancelled.respond_to?(:call)
+
+      {include: includes, exclude: excludes, extensions: extensions, paths: paths}.each do |name, values|
+        next if values.nil?
+        unless values.is_a?(Array) && values.all? { |value| value.is_a?(String) && value.valid_encoding? && !value.include?("\0") }
+          raise ArgumentError, "#{name} must contain valid strings"
+        end
+      end
+    end
+
+    def expression(pattern, regexp, ignore_case, whole_word)
+      source = pattern.is_a?(Regexp) || regexp ? pattern.to_s : Regexp.escape(pattern)
+      source = pattern.source if pattern.is_a?(Regexp)
+      source = "\\b(?:#{source})\\b" if whole_word
+      options = pattern.is_a?(Regexp) ? pattern.options : 0
+      options |= Regexp::IGNORECASE if ignore_case
+      timeout = pattern.respond_to?(:timeout) ? pattern.timeout : nil
+      timeout ||= 0.25
+      [Regexp.new(source, options, timeout: timeout), timeout]
+    end
+
+    def begin_run
+      @mutex.synchronize do
+        raise Error, "search is already running" if @running
+
+        @running = true
+        @cancelled = false
+        @progress = Progress.new(files_scanned: 0, bytes_scanned: 0, matches: 0)
+      end
+    end
+
+    def cancelled? = @cancelled || @external_cancelled&.call
+
+    def search_paths
+      files = []
+      (@paths || @walker.each).each do |relative|
+        SearchWorker.check_cancelled(method(:cancelled?))
+        validate_path(relative)
+        next if @extensions && !@paths && !@extensions.include?(File.extname(relative))
+        next unless selected?(relative)
+
+        files << relative
+      end
+      SearchWorker.check_cancelled(method(:cancelled?))
+      files.sort!.uniq!
+      files
+    end
+
+    def validate_path(relative)
+      unless relative.is_a?(String) && relative.valid_encoding? && !relative.include?("\0")
+        raise ArgumentError, "invalid search path"
+      end
+      normalized = File::ALT_SEPARATOR ? relative.tr(File::ALT_SEPARATOR, "/") : relative
+      pieces = normalized.split("/", -1)
+      if normalized.match?(/\A(?:\/|[A-Za-z]:\/)/) || pieces.any? { |piece| piece.empty? || piece == "." || piece == ".." }
+        raise ArgumentError, "invalid search path"
+      end
+
+      absolute = File.expand_path(relative, @root)
+      raise ArgumentError, "path outside root" unless inside_root?(absolute)
+    end
+
+    def selected?(path)
+      (@include.empty? || @include.any? { |pattern| glob?(pattern, path) }) &&
+        @exclude.none? { |pattern| glob?(pattern, path) }
+    end
+
+    def glob?(pattern, path)
+      File.fnmatch?(pattern, path, File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH)
+    end
+
+    def inside_root?(path)
+      path == @root || path.start_with?(@root.end_with?(File::SEPARATOR) ? @root : @root + File::SEPARATOR)
+    end
+
+    def receiver(results)
+      path = number = offset = raw = line = nil
+      lambda do |message|
+        SearchWorker.validate_message(message)
+        case message[0]
+        when :line
+          _, path, number, offset, raw = message
+          validate_path(path)
+          line = raw.freeze
+        when :matches
+          unless path && message[1].all? { |_column, first, last| last <= line.bytesize }
+            raise IOError, "invalid search worker response"
+          end
+          message[1].each do |_column, first, last|
+            match = Match.new(path: path.freeze, line_number: number, byte_offset: offset + first,
+              line: line, ranges: [first...last].freeze)
+            results << match
+            update_progress(matches: 1)
+            yield match
+          end
+        when :progress
+          update_progress(files_scanned: message[1], bytes_scanned: message[2])
+        when :error
+          raise IOError, "search worker: #{message[1]}"
+        when :done
+          nil
+        else
+          raise IOError, "invalid search worker response"
+        end
+      end
+    end
+
+    def update_progress(files_scanned: 0, bytes_scanned: 0, matches: 0)
+      @mutex.synchronize do
+        @progress = Progress.new(files_scanned: @progress.files_scanned + files_scanned,
+          bytes_scanned: @progress.bytes_scanned + bytes_scanned, matches: @progress.matches + matches)
+      end
+    end
+
+    def parallel(files, count)
+      progress = ->(scanned, bytes) { update_progress(files_scanned: scanned, bytes_scanned: bytes) }
+      SearchPool.new(@root, @expression, @timeout, @max_file_size, @max_matches, method(:cancelled?)).run(files, count,
+        progress: progress) do |message|
+        yield message
+      end
+    end
+  end
+end

data/lib/alkaid/search_pool.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "thread"
+require_relative "search_worker"
+
+module Alkaid
+  class SearchPool
+    BATCH_FILES = SearchWorker::MATCH_BATCH
+    Child = Struct.new(:pid, :input, :output, :queue, :lock, :ready, :writer, :reader, :waiter)
+    private_constant :Child
+
+    def initialize(root, expression, timeout, max_size, limit, cancelled)
+      @root = root
+      @expression = expression
+      @timeout = timeout
+      @max_size = max_size
+      @limit = limit
+      @cancelled = cancelled
+    end
+
+    def run(files, count, progress:)
+      children = []
+      errors = []
+      batches = file_batches(files, count)
+      paths = Array.new(count) { [] }
+      batch_sizes = Array.new(count) { [] }
+      batches.each_with_index do |batch, index|
+        owner = index % count
+        paths[owner].concat(batch)
+        batch_sizes[owner] << batch.length
+      end
+      count.times do |index|
+        SearchWorker.check_cancelled(@cancelled)
+        children << start_child(paths[index], batch_sizes[index], progress)
+      end
+
+      remaining = @limit
+      active = Array.new(count, true)
+      batches.each_index do |index|
+        owner = index % count
+        next unless active[owner]
+
+        status, remaining = drain(children[owner], :batch, remaining, errors) { |message| yield message }
+        raise errors.first if status == :limit && !errors.empty?
+        return if status == :limit
+        active[owner] = false if status == :failed
+      end
+      children.each_with_index do |child, index|
+        next unless active[index]
+
+        status, remaining = drain(child, :done, remaining, errors) { |message| yield message }
+        raise errors.first if status == :limit && !errors.empty?
+        return if status == :limit
+      end
+      raise errors.first unless errors.empty?
+    ensure
+      children&.each { |child| stop_child(child) }
+    end
+
+    private
+
+    def file_batches(files, workers)
+      size = [[files.length / workers, 1].max, BATCH_FILES].min
+      files.each_slice(size).to_a
+    end
+
+    def drain(child, boundary, remaining, errors)
+      loop do
+        message = next_message(child)
+        if message.is_a?(Exception)
+          errors << message
+          return [:failed, remaining]
+        end
+        if message[0] == :error
+          errors << IOError.new("search worker: #{message[1]}")
+          return [:failed, remaining]
+        end
+        return [:complete, remaining] if message[0] == boundary
+        if [:batch, :done].include?(message[0]) || boundary == :done
+          errors << IOError.new("invalid search worker sequence")
+          return [:failed, remaining]
+        end
+        if message[0] == :matches && remaining
+          message[1] = message[1].first(remaining)
+          remaining -= message[1].length
+        end
+        yield message
+        return [:limit, remaining] if remaining == 0
+      end
+    end
+
+    def next_message(child)
+      loop do
+        SearchWorker.check_cancelled(@cancelled)
+        child.lock.synchronize do
+          begin
+            return child.queue.pop(true)
+          rescue ThreadError
+            child.ready.wait(child.lock, 0.005)
+          end
+        end
+      end
+    end
+
+    def start_child(files, batch_sizes, progress)
+      child_input, input = IO.pipe
+      output, child_output = IO.pipe
+      child = Child.new(nil, input, output, SizedQueue.new(2), Mutex.new, ConditionVariable.new)
+      config = [@root, files, @expression.source, @expression.options, @max_size, @limit, @timeout, batch_sizes]
+      child.pid = Process.spawn({"RUBYOPT" => nil, "RUBYLIB" => nil}, RbConfig.ruby, "--disable-gems",
+        File.expand_path("search_worker/runner.rb", __dir__), in: child_input, out: child_output, err: File::NULL)
+      child.waiter = Process.detach(child.pid)
+      child_input.close
+      child_output.close
+      child.writer = Thread.new do
+        SearchWorker.write_frame(input, config)
+      rescue StandardError => error
+        enqueue(child, error)
+      ensure
+        input.close unless input.closed?
+      end
+      child.reader = Thread.new do
+        loop do
+          message = SearchWorker.read_frame(output)
+          SearchWorker.validate_message(message)
+          if message[0] == :progress
+            progress.call(message[1], message[2])
+            next
+          end
+          break unless enqueue(child, message)
+          break if message[0] == :done
+        end
+      rescue StandardError => error
+        enqueue(child, error)
+      end
+      child
+    rescue Exception
+      stop_child(child) if child
+      [child_input, child_output, input, output].compact.each { |io| io.close unless io.closed? }
+      raise
+    end
+
+    def stop_child(child)
+      child.queue.close
+      [child.input, child.output].compact.each { |io| io.close unless io.closed? }
+      [child.writer, child.reader].compact.each do |thread|
+        thread.kill unless thread.join(0.2)
+        thread.join(0.1)
+      end
+      if child.waiter && !child.waiter.join(0)
+        signal(child, "TERM")
+        unless child.waiter.join(0.2)
+          signal(child, "KILL")
+          child.waiter.join
+        end
+      elsif child.pid && !child.waiter
+        signal(child, "KILL")
+        Process.waitpid(child.pid)
+      end
+    end
+
+    def enqueue(child, message)
+      child.queue.push(message)
+      child.lock.synchronize { child.ready.signal }
+      true
+    rescue ClosedQueueError
+      false
+    end
+
+    def signal(child, name)
+      Process.kill(name, child.pid)
+    rescue Errno::ESRCH, Errno::EINVAL, Errno::ECHILD
+      nil
+    end
+  end
+
+  private_constant :SearchPool
+end

data/lib/alkaid/search_worker/cancelled.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+class Alkaid::SearchWorker::Cancelled < StandardError; end

data/lib/alkaid/search_worker/protocol.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Alkaid::SearchWorker
+  module_function
+
+  def write_frame(io, value)
+    bytes = Marshal.dump(value)
+    raise IOError, "search frame exceeds safety limit" if bytes.bytesize > MAX_FRAME_BYTES
+
+    io.write([bytes.bytesize].pack("N"))
+    io.write(bytes)
+    io.flush
+  end
+
+  def read_frame(io)
+    header = io.read(4)
+    raise EOFError, "search worker ended before completion" unless header && header.bytesize == 4
+
+    size = header.unpack1("N")
+    raise IOError, "invalid search frame size" unless size.between?(1, MAX_FRAME_BYTES)
+
+    bytes = io.read(size)
+    raise EOFError, "truncated search frame" unless bytes && bytes.bytesize == size
+
+    # The peer is always this gem's own child process, never an external source.
+    Marshal.load(bytes)
+  rescue TypeError, ArgumentError => error
+    raise IOError, "invalid search frame: #{error.message}"
+  end
+
+  def validate_config(value)
+    unless value.is_a?(Array) && value.length == 8
+      raise IOError, "invalid search worker configuration"
+    end
+
+    root, paths, source, options, max_size, limit, timeout, batch_sizes = value
+    valid_root = root.is_a?(String) && root.valid_encoding? && !root.include?("\0") && File.directory?(root)
+    valid_paths = paths.is_a?(Array) && paths.all? { |path| valid_path?(path) }
+    valid_source = source.is_a?(String) && source.valid_encoding?
+    valid_options = options.is_a?(Integer) && options >= 0
+    valid_size = max_size.is_a?(Integer) && max_size.between?(0, MAX_FILE_BYTES)
+    valid_limit = limit.nil? || (limit.is_a?(Integer) && limit.positive?)
+    valid_timeout = timeout.is_a?(Numeric) && timeout.positive?
+    valid_batches = batch_sizes.is_a?(Array) && batch_sizes.all? do |size|
+      size.is_a?(Integer) && size.between?(1, MATCH_BATCH)
+    end && batch_sizes.sum == paths.length
+    unless valid_root && valid_paths && valid_source && valid_options && valid_size && valid_limit && valid_timeout && valid_batches
+      raise IOError, "invalid search worker configuration"
+    end
+
+    value
+  end
+
+  def validate_message(value)
+    raise IOError, "invalid search worker response" unless value.is_a?(Array)
+
+    valid = case value[0]
+    when :line
+      value.length == 5 && valid_path?(value[1]) && positive_integer?(value[2]) &&
+        nonnegative_integer?(value[3]) && value[4].is_a?(String) && value[4].valid_encoding?
+    when :matches
+      value.length == 2 && value[1].is_a?(Array) && value[1].length <= MATCH_BATCH &&
+        value[1].all? do |entry|
+          entry.is_a?(Array) && entry.length == 3 && positive_integer?(entry[0]) &&
+            nonnegative_integer?(entry[1]) && nonnegative_integer?(entry[2]) && entry[1] <= entry[2]
+        end
+    when :progress
+      value.length == 3 && nonnegative_integer?(value[1]) && nonnegative_integer?(value[2])
+    when :batch
+      value.length == 1
+    when :error
+      value.length == 2 && value[1].is_a?(String) && value[1].valid_encoding? && value[1].bytesize <= 4096
+    when :done
+      value.length == 1
+    else
+      false
+    end
+    raise IOError, "invalid search worker response" unless valid
+
+    value
+  end
+
+  def valid_path?(path)
+    return false unless path.is_a?(String) && path.valid_encoding? && !path.include?("\0")
+
+    normalized = File::ALT_SEPARATOR ? path.tr(File::ALT_SEPARATOR, "/") : path
+    pieces = normalized.split("/", -1)
+    !normalized.match?(/\A(?:\/|[A-Za-z]:\/)/) && pieces.none? { |piece| piece.empty? || piece == "." || piece == ".." }
+  end
+
+  def positive_integer?(value) = value.is_a?(Integer) && value.positive?
+  def nonnegative_integer?(value) = value.is_a?(Integer) && value >= 0
+end

data/lib/alkaid/search_worker/runner.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "../../alkaid"
+
+Alkaid.const_get(:SearchWorker, false).run

data/lib/alkaid/search_worker.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "strscan"
+require_relative "regexp_compat"
+require_relative "match_data_compat"
+
+module Alkaid
+  module SearchWorker
+    MAX_FILE_BYTES = 64 << 20
+    MAX_FRAME_BYTES = MAX_FILE_BYTES + (64 << 10)
+    READ_BYTES = 64 << 10
+    MATCH_BATCH = 128
+
+    module_function
+
+    def check_cancelled(callback)
+      raise Cancelled if callback&.call
+    end
+
+    def scan(root, paths, expression, max_size, limit, cancelled: nil, batch_sizes: nil)
+      total = 0
+      files_scanned = bytes_scanned = 0
+      cursor = 0
+      batches = batch_sizes ? batch_sizes.map { |size| paths.slice(cursor, size).tap { cursor += size } } : [paths]
+      batches.each do |batch|
+        limited = false
+        batch.each do |relative|
+          check_cancelled(cancelled)
+          read = read_source(root, relative, max_size, cancelled)
+          next unless read
+
+          source, bytes = read
+          files_scanned += 1
+          bytes_scanned += bytes
+          next unless source
+
+          line_scanner = StringScanner.new(source)
+          line_start = 0
+          line_end = next_line_end(line_scanner, line_start)
+          line_number = 1
+          group = nil
+          matches = []
+          each_match(source, expression, cancelled) do |match|
+            first, last = match.byteoffset(0)
+            while line_end < source.bytesize && first >= line_end
+              line_start = line_end
+              line_end = next_line_end(line_scanner, line_start)
+              line_number += 1
+            end
+            if first == source.bytesize && !source.empty? && source.end_with?("\n")
+              line_start = line_end = source.bytesize
+              line_number += 1
+            end
+
+            number = line_number
+            offset = line_start
+            target = last > first ? last - 1 : first
+            while line_end < source.bytesize && target >= line_end
+              line_start = line_end
+              line_end = next_line_end(line_scanner, line_start)
+              line_number += 1
+            end
+            current_group = [number, offset, line_end]
+            unless group == current_group
+              yield [:matches, matches] unless matches.empty?
+              matches = []
+              yield [:line, relative, number, offset, source.byteslice(offset, line_end - offset)]
+              group = current_group
+            end
+
+            relative_first = first - offset
+            column = source.byteslice(offset, relative_first).length + 1
+            matches << [column, relative_first, last - offset]
+            total += 1
+            if matches.length == MATCH_BATCH || (limit && total >= limit)
+              yield [:matches, matches]
+              matches = []
+            end
+            if limit && total >= limit
+              limited = true
+              break
+            end
+          end
+          yield [:matches, matches] unless matches.empty?
+          break if limited
+        end
+        unless files_scanned.zero?
+          yield [:progress, files_scanned, bytes_scanned]
+          files_scanned = bytes_scanned = 0
+        end
+        yield [:batch] if batch_sizes
+        return if limited
+      end
+    end
+
+    def read_source(root, relative, max_size, cancelled)
+      absolute = File.expand_path(relative, root)
+      prefix = root.end_with?(File::SEPARATOR) ? root : root + File::SEPARATOR
+      raise ArgumentError, "path outside root" unless absolute.start_with?(prefix)
+
+      real = File.realpath(absolute)
+      raise ArgumentError, "path outside root" unless real == root || real.start_with?(prefix)
+
+      flags = File::RDONLY
+      # Windows defines NONBLOCK as 1, which aliases WRONLY in File.open.
+      windows = RUBY_PLATFORM.match?(/mswin|mingw/)
+      flags |= File::NONBLOCK unless windows
+      flags |= File::NOFOLLOW if defined?(File::NOFOLLOW) && !windows
+      File.open(real, flags) do |file|
+        file.binmode
+        return unless file.stat.file? && file.size <= max_size
+
+        source = +"".b
+        while (chunk = file.read([READ_BYTES, max_size - source.bytesize + 1].min))
+          check_cancelled(cancelled)
+          source << chunk
+          return [nil, source.bytesize] if source.bytesize > max_size || chunk.include?("\0")
+        end
+        source.force_encoding(Encoding::UTF_8)
+        [source.valid_encoding? ? source : nil, source.bytesize]
+      end
+    rescue Errno::ENOENT, Errno::EACCES, Errno::EISDIR, Errno::ELOOP
+      nil
+    end
+
+    def run
+      STDIN.binmode
+      STDOUT.binmode
+      root, paths, source, options, max_size, limit, timeout, batch_sizes = validate_config(read_frame(STDIN))
+      expression = Regexp.new(source, options, timeout: timeout)
+      scan(root, paths, expression, max_size, limit, batch_sizes: batch_sizes) do |message|
+        write_frame(STDOUT, message)
+      end
+      write_frame(STDOUT, [:done])
+    rescue StandardError => error
+      message = "#{error.class}: #{error.message}".encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      write_frame(STDOUT, [:error, message.byteslice(0, 4093).scrub])
+      write_frame(STDOUT, [:done])
+    end
+
+    def each_match(source, expression, cancelled)
+      position = 0
+      loop do
+        check_cancelled(cancelled)
+        match = Alkaid.with_regexp_timeout(expression) { expression.match(source, position) }
+        break unless match
+
+        yield match
+        ending = match.end(0)
+        break if match.begin(0) == ending && ending == source.length
+
+        position = ending + (match.begin(0) == ending ? 1 : 0)
+      end
+    end
+
+    def next_line_end(scanner, offset)
+      scanner.pos = offset
+      scanner.skip_until(/\n/) ? scanner.pos : scanner.string.bytesize
+    end
+  end
+end
+
+require_relative "search_worker/protocol"
+require_relative "search_worker/cancelled"
+Alkaid.send(:private_constant, :SearchWorker)

data/lib/alkaid/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Alkaid
+  VERSION = "0.1.0"
+end

data/lib/alkaid/walker.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Alkaid
+  class Walker
+    include Enumerable
+
+    attr_reader :root
+
+    def initialize(root, ignore: nil, follow_symlinks: false, hidden: false, max_depth: nil, cancelled: nil)
+      @root = File.realpath(root)
+      raise ArgumentError, "root must be a directory" unless File.directory?(@root)
+      raise ArgumentError, "ignore must respond to ignored?" if ignore && !ignore.respond_to?(:ignored?)
+      raise ArgumentError, "cancelled must respond to call" if cancelled && !cancelled.respond_to?(:call)
+      unless [follow_symlinks, hidden].all? { |value| value == true || value == false }
+        raise ArgumentError, "traversal flags must be boolean"
+      end
+      unless max_depth.nil? || (max_depth.is_a?(Integer) && max_depth >= 0)
+        raise ArgumentError, "max_depth must be nonnegative"
+      end
+
+      @ignore = ignore
+      @follow_symlinks = follow_symlinks
+      @hidden = hidden
+      @max_depth = max_depth
+      @cancelled = cancelled
+    end
+
+    def each(&block)
+      return enum_for(__method__) unless block
+
+      walk("", Set.new, &block)
+      self
+    end
+
+    private
+
+    def walk(directory, visited, &block)
+      return if @cancelled&.call
+
+      absolute_directory = absolute(directory)
+      stat = File.stat(absolute_directory)
+      return unless visited.add?([stat.dev, stat.ino])
+
+      Dir.children(absolute_directory).sort.each do |name|
+        return if @cancelled&.call
+        next if name == ".git" || (!@hidden && name.start_with?("."))
+
+        relative = directory.empty? ? name : File.join(directory, name)
+        normalized = File::ALT_SEPARATOR ? relative.tr(File::ALT_SEPARATOR, "/") : relative
+        depth = normalized.count("/") + 1
+        next if @max_depth && depth > @max_depth
+
+        visit(relative, normalized, depth, visited, &block)
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+        next
+      end
+    rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+      nil
+    end
+
+    def visit(relative, normalized, depth, visited, &block)
+      path = absolute(relative)
+      entry = File.lstat(path)
+      if entry.symlink?
+        return unless @follow_symlinks
+        return unless inside_root?(File.realpath(path))
+
+        entry = File.stat(path)
+      end
+
+      return if @ignore&.ignored?(normalized, directory: entry.directory?)
+
+      if entry.directory?
+        walk(relative, visited, &block) unless @max_depth && depth >= @max_depth
+      elsif entry.file?
+        yield normalized
+      end
+    end
+
+    def absolute(relative) = relative.empty? ? root : File.join(root, relative)
+
+    def inside_root?(path)
+      path == root || path.start_with?(root.end_with?(File::SEPARATOR) ? root : root + File::SEPARATOR)
+    end
+  end
+end

data/lib/alkaid.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "alkaid/version"
+
+module Alkaid
+  class Error < StandardError; end
+
+  module Value
+    module_function
+
+    def define(*members)
+      return Data.define(*members) if defined?(Data)
+
+      Struct.new(*members) do
+        members.each { |member| undef_method("#{member}=") }
+
+        def initialize(*values, **keywords)
+          if keywords.empty?
+            raise ArgumentError, "wrong number of arguments" unless values.length == self.class.members.length
+
+            super(*values)
+          else
+            raise ArgumentError, "cannot mix positional and keyword arguments" unless values.empty?
+
+            missing = self.class.members - keywords.keys
+            unknown = keywords.keys - self.class.members
+            raise ArgumentError, "missing keyword: #{missing.first.inspect}" unless missing.empty?
+            raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+            super(*self.class.members.map { |member| keywords.fetch(member) })
+          end
+          freeze
+        end
+
+        def with(**changes)
+          return self if changes.empty?
+
+          unknown = changes.keys - self.class.members
+          raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+          self.class.new(**to_h.merge(changes))
+        end
+      end
+    end
+  end
+
+  Match = Value.define(:path, :line_number, :byte_offset, :line, :ranges)
+  Progress = Value.define(:files_scanned, :bytes_scanned, :matches)
+  private_constant :Value
+end
+
+require_relative "alkaid/regexp_compat"
+require_relative "alkaid/match_data_compat"
+require_relative "alkaid/walker"
+require_relative "alkaid/search"

data/sig/alkaid.rbs

@@ -0,0 +1,52 @@
+module Alkaid
+  VERSION: String
+
+  interface _IgnoreMatcher
+    def ignored?: (String path, ?directory: bool) -> bool
+  end
+
+  class Error < StandardError
+  end
+
+  class Match
+    attr_reader path: String
+    attr_reader line_number: Integer
+    attr_reader byte_offset: Integer
+    attr_reader line: String
+    attr_reader ranges: Array[::Range[Integer]]
+    def self.new: (String path, Integer line_number, Integer byte_offset, String line, Array[::Range[Integer]] ranges) -> Match
+                | (path: String, line_number: Integer, byte_offset: Integer, line: String, ranges: Array[::Range[Integer]]) -> Match
+    def with: (?path: String, ?line_number: Integer, ?byte_offset: Integer, ?line: String, ?ranges: Array[::Range[Integer]]) -> Match
+  end
+
+  class Progress
+    attr_reader files_scanned: Integer
+    attr_reader bytes_scanned: Integer
+    attr_reader matches: Integer
+    def self.new: (Integer files_scanned, Integer bytes_scanned, Integer matches) -> Progress
+                | (files_scanned: Integer, bytes_scanned: Integer, matches: Integer) -> Progress
+    def with: (?files_scanned: Integer, ?bytes_scanned: Integer, ?matches: Integer) -> Progress
+  end
+
+  class Walker
+    include Enumerable[String]
+    attr_reader root: String
+    def initialize: (String root, ?ignore: _IgnoreMatcher?, ?follow_symlinks: bool, ?hidden: bool,
+      ?max_depth: Integer?, ?cancelled: ^() -> bool) -> void
+    def each: () -> Enumerator[String, self]
+            | () { (String) -> untyped } -> self
+  end
+
+  class Search
+    DEFAULT_MAX_FILE_SIZE: Integer
+    def initialize: (String root, pattern: String | Regexp, ?regexp: bool, ?ignore_case: bool,
+      ?whole_word: bool, ?include: Array[String], ?exclude: Array[String], ?ignore: _IgnoreMatcher?,
+      ?workers: Integer, ?max_file_size: Integer?, ?max_matches: Integer?, ?follow_symlinks: bool,
+      ?hidden: bool, ?max_depth: Integer?, ?extensions: Array[String]?, ?paths: Array[String]?,
+      ?cancelled: ^() -> bool) -> void
+    def run: () -> Array[Match]
+           | () { (Match) -> untyped } -> Array[Match]
+    def cancel: () -> nil
+    def progress: () -> Progress
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: alkaid
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/adr/000-template.md
+- docs/adr/001-duck-typed-ignore-rules.md
+- docs/adr/README.md
+- lib/alkaid.rb
+- lib/alkaid/match_data_compat.rb
+- lib/alkaid/regexp_compat.rb
+- lib/alkaid/search.rb
+- lib/alkaid/search_pool.rb
+- lib/alkaid/search_worker.rb
+- lib/alkaid/search_worker/cancelled.rb
+- lib/alkaid/search_worker/protocol.rb
+- lib/alkaid/search_worker/runner.rb
+- lib/alkaid/version.rb
+- lib/alkaid/walker.rb
+- sig/alkaid.rbs
+homepage: https://github.com/noxdea/alkaid
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/noxdea/alkaid
+  changelog_uri: https://github.com/noxdea/alkaid/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Pure Ruby file walking and parallel content search
+test_files: []