rbgrep 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13fc98cb1e9f142256df88ad75264dfba4f3133cd86782f69562e9e4f3b73f9d
+  data.tar.gz: 95f53537ba8c4fb6f885be383e1b78782309c751cd3313e24ab612dbb9f6e7ba
+SHA512:
+  metadata.gz: 7085f872add33bf241d0e043f95b70806ef9a09085929831b416fbab78f2deda61b19bcfe4d2721c3687a76b379b4ecc5226058caf69480e15d2dae4fa2158b2
+  data.tar.gz: 58f543d9979226be7e4c134047b0aafc11739df7c1ad7a03a8e78103667a2b4714a2ab8c9817b7d11631f9364b65e33ca2367746caaab37293d4ddb6338692ee

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yusuke Endoh
+
+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,72 @@
+# rbgrep
+
+A mostly grep-compatible search tool for Ruby codebases.
+
+By default, `rbgrep` takes the same flags as `grep` and prints the same
+kind of output: a filename heading, then `NN:` hit lines. Add
+**`--context`** and each hit in a `.rb` file is shown together with the
+method definition and class that enclose it, located with the
+[Prism](https://github.com/ruby/prism) parser.
+
+## Installation
+
+```
+gem install rbgrep
+```
+
+## Usage
+
+```
+rbgrep [-rn -w -i -E -F -A/-B/-C --include=GLOB] PATTERN [PATH...]
+```
+
+Plain search works like grep (including `\|` alternation in basic
+regexps, or `-E` for extended ones):
+
+```
+$ rbgrep -n 'def visible?' app/models/news.rb
+app/models/news.rb
+55:   def visible?(user=User.current)
+```
+
+With `--context`, the hit arrives with the code that gives it meaning —
+the enclosing method body and the class frame, with `--` marking elided
+stretches:
+
+```
+$ rbgrep -n --context 'def visible?' app/models/news.rb
+app/models/news.rb
+20- class News < ApplicationRecord
+--
+55:   def visible?(user=User.current)
+56-     !user.nil? && user.allowed_to?(:view_news, project)
+57-   end
+--
+105- end
+```
+
+A hit on a method definition shows the body (capped); a hit that merely
+references something shows a few surrounding lines. Files under `test/`
+and `spec/` directories, and non-Ruby files, print plain hits.
+
+`--head N` caps output by hits, returns each hit whole, and reports how
+many were cut — unlike `| head`, you always know whether there was more:
+
+```
+$ rbgrep -rn --head 3 'def initialize' lib
+...
+... 48 more hits (raise --head to see them)
+```
+
+When reading from a pipe, `rbgrep` behaves exactly like `grep` — no
+headings, no context — so `... | rbgrep -v foo` works as expected.
+
+## Use with coding agents
+
+`rbgrep` is designed to be handed to an AI coding agent as its search
+tool. [instruction.md](instruction.md) is a ready-made instruction sheet:
+tell your agent to read and follow it.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/exe/rbgrep

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/rbgrep"
+
+exit Rbgrep::CLI.run(ARGV)

data/instruction.md

@@ -0,0 +1,44 @@
+# rbgrep
+
+**Use `rbgrep` to search the repository you are working in — Ruby sources and templates alike.**
+If `rbgrep` is not installed, run `gem install rbgrep` first.
+
+The arguments are the same as grep's, and by default so is the output:
+a filename heading, then `NN:` hit lines. **Using `grep` / `rg` to search
+files in the repository is prohibited.**
+The following remain free:
+
+- narrowing **downstream of a pipe** (`... | grep -v foo`)
+- **reading files** (`cat` / `sed -n` / Read / `head` / `tail`)
+
+```
+rbgrep [-rn -w -i -E -F -A/-B/-C --include=GLOB] PATTERN [PATH...]
+```
+
+Search. Multi-term search is written the same way as in grep:
+
+```
+rbgrep -rn 'Payment\|payment_method' app lib
+rbgrep -rnE 'Payment|PaymentMethod' app lib
+```
+
+Add **`--context`** to see where hits sit: each hit in a `.rb` file is then
+shown together with its **enclosing method definition and class** as `NN-`
+context lines (`--` marks elided stretches). **Reach for it whenever a hit
+is in a file you haven't read yet** — it usually saves a follow-up read.
+Plain output is for counting and locating.
+
+```
+rbgrep --head N PATTERN [PATH...]
+```
+
+**Piping `rbgrep` output into `| head` is prohibited. Use `--head N` instead.**
+`--head` caps by hits, returns each hit whole, and when results are cut it
+says so, so you know whether to raise N.
+
+**Warm-up (once, before you start)**: to get used to the `--context` output,
+pick one small Ruby file (any file under `lib/` will do) and search it:
+
+```
+rbgrep -n --context 'def ' path/to/that/file.rb
+```

data/lib/rbgrep/cli.rb

@@ -0,0 +1,235 @@
+module Rbgrep
+  # The command line: parse grep-shaped arguments, search, print.
+  class CLI
+    def self.run(argv, stdout: $stdout, stdin: $stdin)
+      new(stdout: stdout, stdin: stdin).run(argv)
+    end
+
+    def initialize(stdout: $stdout, stdin: $stdin)
+      @out = stdout
+      @in = stdin
+    end
+
+    def run(argv)
+      o = parse(argv)
+      if o[:patterns].empty?
+        warn "usage: rbgrep [options] PATTERN [FILE...]"
+        return 1
+      end
+      regexp = Pattern.build(o[:patterns], fixed: o[:fixed], extended: o[:ere],
+                                           word: o[:word], ignore_case: o[:ignore_case])
+      return filter_stdin(regexp, o) if o[:paths].empty? && !@in.tty?
+
+      search_files(regexp, o)
+    end
+
+    private
+
+    def parse(argv)
+      o = {
+        patterns: [], paths: [], recursive: false, line_numbers: false,
+        ignore_case: false, word: false, invert: false, fixed: false,
+        list: false, count: false, quiet: false, no_filename: nil,
+        before: 0, after: 0, include: [], exclude: [], exclude_dir: [],
+        max: nil, ere: false, context: false, head: nil,
+      }
+      argv = argv.dup
+      until argv.empty?
+        a = argv.shift
+        case a
+        when "--" then o[:paths].concat(argv); break
+        when /\A--include=(.+)/ then o[:include] << $1
+        when "--include" then o[:include] << argv.shift
+        when /\A--exclude=(.+)/ then o[:exclude] << $1
+        when "--exclude" then o[:exclude] << argv.shift
+        when /\A--exclude-dir=(.+)/ then o[:exclude_dir] << $1
+        when "--exclude-dir" then o[:exclude_dir] << argv.shift
+        when "--color", "--colour", /\A--colou?r=./ then nil # output is never colored
+        when "--no-filename" then o[:no_filename] = true
+        when "--with-filename" then o[:no_filename] = false
+        when "--line-number" then o[:line_numbers] = true
+        when "--recursive" then o[:recursive] = true
+        when "--invert-match" then o[:invert] = true
+        when "--files-with-matches" then o[:list] = true
+        when "--count" then o[:count] = true
+        when "--word-regexp" then o[:word] = true
+        when "--ignore-case" then o[:ignore_case] = true
+        when "--fixed-strings" then o[:fixed] = true
+        when "--extended-regexp" then o[:ere] = true
+        when "--context" then o[:context] = true
+        when /\A--head=(\d+)\z/ then o[:head] = $1.to_i
+        when "--head" then o[:head] = argv.shift.to_i
+        when /\A-([A-Za-z]+)(\d*)\z/
+          letters = $1
+          trailing = $2
+          until letters.empty?
+            c = letters.slice!(0)
+            case c
+            when "r", "R" then o[:recursive] = true
+            when "n" then o[:line_numbers] = true
+            when "i" then o[:ignore_case] = true
+            when "w" then o[:word] = true
+            when "v" then o[:invert] = true
+            when "l" then o[:list] = true
+            when "c" then o[:count] = true
+            when "q" then o[:quiet] = true
+            when "h" then o[:no_filename] = true
+            when "H" then o[:no_filename] = false
+            when "F" then o[:fixed] = true
+            when "E", "P" then o[:ere] = true
+            when "s", "a", "o" then nil # -o is approximated as a normal match
+            when "e" then o[:patterns] << (letters.empty? ? argv.shift : letters.slice!(0..-1))
+            when "A", "B", "C", "m"
+              n = letters.empty? ? (trailing.empty? ? argv.shift : trailing) : letters.slice!(0..-1)
+              trailing = ""
+              n = n.to_i
+              case c
+              when "A" then o[:after] = n
+              when "B" then o[:before] = n
+              when "C" then o[:after] = o[:before] = n
+              when "m" then o[:max] = n
+              end
+            end
+          end
+        else
+          o[:patterns].empty? ? o[:patterns] << a : o[:paths] << a
+        end
+      end
+      o
+    end
+
+    # piped input: behave exactly like grep — no headings, no context
+    def filter_stdin(regexp, o)
+      hits = 0
+      @in.each_line do |line|
+        next unless regexp.match?(line) ^ o[:invert]
+
+        hits += 1
+        break if o[:max] && hits > o[:max]
+
+        @out.print line unless o[:count] || o[:quiet]
+      end
+      @out.puts hits if o[:count]
+      hits > 0 ? 0 : 1
+    end
+
+    def collect_files(paths, o)
+      out = []
+      paths = ["."] if paths.empty?
+      paths.each do |p|
+        if File.directory?(p)
+          Dir.glob(File.join(p, "**", "*")).each do |f|
+            next unless File.file?(f)
+            next if o[:exclude_dir].any? { |g| f.split("/").any? { |seg| File.fnmatch?(g, seg) } }
+
+            out << f
+          end
+        elsif File.file?(p)
+          out << p
+        end
+      end
+      out = out.select { |f| o[:include].any? { |g| File.fnmatch?(g, File.basename(f)) } } if o[:include].any?
+      out = out.reject { |f| o[:exclude].any? { |g| File.fnmatch?(g, File.basename(f)) } } if o[:exclude].any?
+      out.reject { |f| f.include?("/.git/") }
+    end
+
+    def search_files(regexp, o)
+      files = collect_files(o[:paths], o)
+
+      results = []
+      total = 0
+      found = false
+      files.each do |path|
+        body = begin
+          File.read(path, encoding: "UTF-8")
+        rescue StandardError
+          next
+        end
+        next unless body.valid_encoding?
+
+        lines = body.lines
+        hits = lines.each_index.select { |i| regexp.match?(lines[i]) ^ o[:invert] }.map { |i| i + 1 }
+        next if hits.empty?
+
+        found = true
+        total += hits.size
+        results << [path, body, lines, hits]
+      end
+
+      truncated = nil
+      if o[:head]
+        left = o[:head]
+        capped = []
+        results.each do |path, body, lines, hits|
+          break if left <= 0
+
+          take = hits.first(left)
+          left -= take.size
+          capped << [path, body, lines, take]
+        end
+        truncated = total - o[:head]
+        truncated = nil unless truncated > 0
+        results = capped
+      end
+
+      return found ? 0 : 1 if o[:quiet]
+      return list_output(results) || (found ? 0 : 1) if o[:list]
+      return count_output(results, files, o) || (found ? 0 : 1) if o[:count]
+
+      text_output(results, o, truncated)
+      found ? 0 : 1
+    end
+
+    def list_output(results)
+      results.each { |path, _, _, _| @out.puts path }
+      nil
+    end
+
+    def count_output(results, files, o)
+      show_name = o[:no_filename].nil? ? (files.size > 1 || o[:recursive]) : !o[:no_filename]
+      results.each do |path, _, _, hits|
+        @out.puts show_name ? "#{path}:#{hits.size}" : hits.size.to_s
+      end
+      nil
+    end
+
+    # a filename heading, then "NN:" hits and "NN-" context, "--" for elisions
+    def text_output(results, o, truncated)
+      first = true
+      results.each do |path, body, lines, hits|
+        keep = select_lines(path, body, lines, hits, o)
+        shown = keep.keys.select { |l| l >= 1 && l <= lines.size }.sort
+        bare = shown.all? { |l| keep[l] == :hit }
+        @out.puts "" unless first
+        first = false
+        @out.puts path
+        prev = 0
+        shown.each do |ln|
+          @out.puts "--" if !bare && prev > 0 && ln > prev + 1
+          @out.puts "#{ln}#{keep[ln] == :hit ? ':' : '-'} #{lines[ln - 1].to_s.chomp}"
+          prev = ln
+        end
+      end
+      @out.puts "... #{truncated} more hits (raise --head to see them)" if truncated
+    end
+
+    def select_lines(path, body, lines, hits, o)
+      if o[:context] && windowable?(path, o)
+        parsed = Prism.parse(body)
+        return Window.select(parsed.value, hits, o[:before], o[:after]) if parsed.success?
+      end
+      ctx = [o[:before], o[:after]].max
+      keep = {}
+      hits.each do |ln|
+        keep[ln] = :hit
+        ((ln - ctx)..(ln + ctx)).each { |i| keep[i] ||= :ctx if i >= 1 && i <= lines.size }
+      end
+      keep
+    end
+
+    # windows are for Ruby source; tests and non-.rb files print plain hits
+    def windowable?(path, o)
+      path.end_with?(".rb") && !o[:invert] && path !~ %r{(\A|/)(test|spec)/}
+    end
+  end
+end

data/lib/rbgrep/pattern.rb

@@ -0,0 +1,30 @@
+module Rbgrep
+  # Builds the Regexp for a search the way grep would read it.
+  module Pattern
+    module_function
+
+    # grep's basic regexps spell alternation "\|" and grouping "\(...\)";
+    # translate to Ruby: escaped metacharacters active, bare ones literal.
+    def from_bre(pattern)
+      out = +""
+      i = 0
+      while i < pattern.length
+        if pattern[i] == "\\" && i + 1 < pattern.length && "|(){}+?".include?(pattern[i + 1])
+          out << pattern[i + 1]
+          i += 2
+        else
+          out << "\\" if "|(){}+?".include?(pattern[i])
+          out << pattern[i]
+          i += 1
+        end
+      end
+      out
+    end
+
+    def build(patterns, fixed: false, extended: false, word: false, ignore_case: false)
+      src = patterns.map { |p| fixed ? Regexp.escape(p) : (extended ? p : from_bre(p)) }.join("|")
+      src = "\\b(?:#{src})\\b" if word
+      Regexp.new(src, ignore_case ? Regexp::IGNORECASE : nil)
+    end
+  end
+end

data/lib/rbgrep/version.rb

@@ -0,0 +1,3 @@
+module Rbgrep
+  VERSION = "0.1.0"
+end

data/lib/rbgrep/window.rb

@@ -0,0 +1,57 @@
+module Rbgrep
+  # Line selection for --context: show each hit together with the enclosing
+  # method definition and class/module frame.
+  module Window
+    BODY_CAP = 10   # body lines shown when the hit is the `def` line itself
+    REF_MARGIN = 3  # lines around a hit inside a body (a mere reference)
+    EDGE_SLACK = 4  # show this many lines rather than eliding them at a def edge
+    FRAME_NODES = [Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+
+    module_function
+
+    # Nodes enclosing the line, outermost first.
+    def ancestors(node, lineno, acc = [])
+      return acc unless node.is_a?(Prism::Node)
+
+      loc = node.location
+      return acc unless loc.start_line <= lineno && lineno <= loc.end_line
+
+      acc << node
+      node.compact_child_nodes.each { |c| ancestors(c, lineno, acc) }
+      acc
+    end
+
+    # => { lineno => :hit | :body | :frame | :ctx }
+    def select(ast, hits, before, after)
+      cap_b = [BODY_CAP, before].max
+      cap_a = [BODY_CAP, after].max
+      ctx_b = [REF_MARGIN, before].max
+      ctx_a = [REF_MARGIN, after].max
+      keep = {}
+      hits.each do |ln|
+        keep[ln] = :hit
+        ((ln - before)..(ln + after)).each { |i| keep[i] ||= :ctx if i >= 1 }
+        stack = ancestors(ast, ln)
+        if (defn = stack.find { |n| n.is_a?(Prism::DefNode) })
+          keep[defn.location.start_line] ||= :frame
+          keep[defn.location.end_line] ||= :frame
+          b, a = defn.location.start_line == ln ? [cap_b, cap_a] : [ctx_b, ctx_a]
+          lo = [defn.location.start_line, ln - b].max
+          hi = [defn.location.end_line, ln + a].min
+          lo = defn.location.start_line if lo - defn.location.start_line <= EDGE_SLACK
+          hi = defn.location.end_line if defn.location.end_line - hi <= EDGE_SLACK
+          (lo..hi).each { |i| keep[i] ||= :body }
+        else
+          ((ln - ctx_b)..(ln + ctx_a)).each { |i| keep[i] ||= :body if i >= 1 }
+        end
+        stack.each do |n|
+          next unless FRAME_NODES.any? { |k| n.is_a?(k) }
+
+          keep[n.location.start_line] ||= :frame
+          keep[n.location.end_line] ||= :frame
+        end
+      end
+      keep
+    end
+  end
+end

data/lib/rbgrep.rb

@@ -0,0 +1,9 @@
+require "prism"
+
+require_relative "rbgrep/version"
+require_relative "rbgrep/pattern"
+require_relative "rbgrep/window"
+require_relative "rbgrep/cli"
+
+module Rbgrep
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: rbgrep
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+  - Yusuke Endoh
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+  - !ruby/object:Gem::Dependency
+    name: prism
+    requirement: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "0.24"
+    type: :runtime
+    prerelease: false
+    version_requirements: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "0.24"
+description: |
+    rbgrep is a mostly grep-compatible search tool for Ruby codebases.
+    By default it behaves like grep. With --context, each hit in a Ruby
+    file is shown together with the method definition and class that
+    enclose it, located with the Prism parser.
+email:
+  - y.endoh@gmail.com
+executables:
+  - rbgrep
+extensions: []
+extra_rdoc_files: []
+files:
+  - LICENSE.txt
+  - README.md
+  - exe/rbgrep
+  - instruction.md
+  - lib/rbgrep.rb
+  - lib/rbgrep/cli.rb
+  - lib/rbgrep/pattern.rb
+  - lib/rbgrep/version.rb
+  - lib/rbgrep/window.rb
+homepage: "https://github.com/mame/rbgrep"
+licenses:
+  - MIT
+metadata:
+  homepage_uri: "https://github.com/mame/rbgrep"
+  source_code_uri: "https://github.com/mame/rbgrep"
+rdoc_options: []
+require_paths:
+  - lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+    -
+      - ">="
+      - !ruby/object:Gem::Version
+        version: "3.2"
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+    -
+      - ">="
+      - !ruby/object:Gem::Version
+        version: "0"
+requirements: []
+rubygems_version: 4.1.0.dev
+specification_version: 4
+summary: "grep for Ruby codebases: grep-compatible search, syntax-aware context"
+test_files: []