specs_for 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49cbe4e021b76ac0fcf642d68e4047a591c1618b47e97360822d7a7fc8f691c0
+  data.tar.gz: e82d6767e86e83dc4e2b97a9de51121e497a64cf70744dad1e4ea4c256083391
+SHA512:
+  metadata.gz: 54b8e0df1127883a36f8b87c5ec57aa60e86a290f08fbddb413cf7061fd00a8ebffc9f090a2600a440afadf957f2bc5b30f38ba865e59105bf0211ee83d266be
+  data.tar.gz: 4e1409fce1fceba6b3763cce5c824c0fc298bf64cf0cae6cd784f27800ea984982f2abd71119db95875a51e914639f5f28ff20939eb42cea92d2a30f94be76c0

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-05-06
+
+### Updates:
+
+- improved command parser
+- support -c --changed files
+- add better/more CLI specs
+- add AI context
+
+## [1.0.0] - 2026-03-25
+
+### Added:
+
+- Initial release of the `specs-for` gem.
+- `bin/specs-for` CLI executable.
+- `SpecsFor::Finder` — maps source files to their spec file counterparts.
+- `SpecsFor::Runner` — parses CLI options, discovers git-changed files when no
+  explicit arguments are given, and executes RSpec.
+- RSpec test suite for `Finder` and `Runner`.
+- GitHub Actions CI workflow (runs RSpec on every push/PR to `main`).
+- GitHub Actions Release workflow (runs tests then publishes gem on version tag push).

data/CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+This file gives repository-specific guidance for working on `specs-for`.
+
+## Project Purpose
+
+`specs-for` is a Ruby gem that selects and runs RSpec files for provided input paths.
+
+Current behavior highlights:
+- Accepts one or more explicit file/directory arguments.
+- Supports `-` to read filenames from `STDIN`.
+- Supports `-c/--changed` to use files from `git status -s`.
+- Uses Git ignore rules when handling changed files (`git check-ignore`), so ignored files (for example `vendor/`) are not considered.
+- Does not run `rspec` when there is no effective input.
+
+## Useful Commands
+
+Setup:
+- `bin/setup`
+
+Run specs:
+- `bundle exec rspec`
+- `bundle exec rspec spec/specs_for_spec.rb`
+- `bundle exec rake`
+
+Run the CLI:
+- `bin/specs-for lib/specs_for.rb`
+- `git diff --name-only | bin/specs-for -`
+- `bin/specs-for -c` # only run specs on changed files
+
+## Repository Layout
+
+- `lib/specs_for.rb` - main CLI implementation
+- `lib/specs_for/version.rb` - gem version
+- `bin/specs-for` and `bin/specs_for` - executable entrypoints
+- `spec/specs_for_spec.rb` - primary behavior specs
+- `spec/spec_helper.rb` - RSpec configuration
+- `specs_for.gemspec` - gemspec
+
+## Coding Conventions For This Repo
+
+- Prefer small, focused changes and keep behavior backwards-compatible unless explicitly changing semantics.
+- Add or update specs for any behavior change in `lib/specs_for.rb`.
+- Keep CLI error paths explicit and testable (`SystemExit` with expected status).
+- Prefer Git as the source of truth for ignore behavior rather than re-implementing `.gitignore` parsing.
+- Keep output noise low in tests by stubbing `warn` when asserting error exits.
+
+## Notes For AI Assistants
+
+- This is a gem project, not a Rails app; avoid Rails-specific conventions unless intentionally introduced.
+- Respect existing command style (`bundle exec ...`, `bin/...` wrappers).
+- Do not assume optional tooling (`ag`, `pry`) is available; code already handles fallbacks.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alan Stebbens
+
+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,94 @@
+# SpecsFor
+
+This ruby gem is a CLI (Command Line Interface) tool for developers to easily
+find and run `rspec` on the named files or discovered changed files.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add 'specs_for'
+```
+
+If bundler is not being used to manage dependencies, install the gem by
+executing:
+
+```bash
+gem install specs_for
+```
+
+## Usage
+
+### Command line
+
+```bash
+# Run specs for specific files
+specs-for lib/my_class.rb app/models/user.rb
+
+# Run specs for all git-changed files
+specs-for -c
+
+# Run specs for changed files with an RSpec tag
+specs-for -c -I                    # --tag integration
+specs-for -c -T smoke              # --tag smoke
+
+# Read filenames from stdin
+git diff --name-only HEAD~1 | specs-for -
+
+# Show which spec files would run, without running them
+specs-for -s lib/my_class.rb
+
+# Dry-run: print the rspec command without executing it
+specs-for -n lib/my_class.rb
+```
+
+### Path mapping
+
+Source files are mapped to spec files by replacing the first `app/` or `lib/`
+segment with `spec/` and appending `_spec` before `.rb`. Component monorepo
+paths preserve the component prefix.
+
+| Source file                    | Spec file                            |
+| ------------------------------ | ------------------------------------ |
+| `lib/foo/bar.rb`               | `spec/foo/bar_spec.rb`               |
+| `app/models/user.rb`           | `spec/models/user_spec.rb`           |
+| `components/mycomp/lib/foo.rb` | `components/mycomp/spec/foo_spec.rb` |
+
+Spec files passed as arguments are forwarded to rspec unchanged.
+
+### Options
+
+| Flag      | Long form              | Description                             |
+| --------- | ---------------------- | --------------------------------------- |
+| `-c`      | `--changed`            | Use git-changed files (`git status -s`) |
+| `-e`      | `--exact`              | Match FILE exactly (no fuzzy search)    |
+| `-I`      | `--integration`        | Add `--tag integration`                 |
+| `-M`      | `--manual-integration` | Add `--tag manual_integration`          |
+| `-T NAME` | `--tag NAME`           | Add `--tag NAME`                        |
+| `-n`      | `--norun`              | Print command without running           |
+| `-s`      | `--show`               | Print spec paths without running rspec  |
+| `-v`      | `--verbose`            | Verbose output                          |
+| `-`       |                        | Read filenames from STDIN               |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/aks/specs_for.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/specs-for

@@ -0,0 +1 @@
+specs_for

data/bin/specs_for

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "specs_for"
+
+SpecsFor.new.run

data/lib/specs_for/finder.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+class SpecsFor
+  # Finder maps source files to their corresponding spec files.
+  class Finder
+    SPEC_SUFFIX = "_spec.rb"
+
+    # Default search paths for spec files, in priority order.
+    SPEC_DIRS = %w[spec test].freeze
+
+    attr_reader :spec_dirs
+
+    def initialize(spec_dirs: SPEC_DIRS)
+      @spec_dirs = Array(spec_dirs)
+    end
+
+    # Given a list of file paths, return the unique set of existing spec files
+    # that correspond to those paths.
+    #
+    # @param files [Array<String>] source (or spec) file paths
+    # @return [Array<String>] sorted list of discovered spec file paths
+    def find(files)
+      files.flat_map { |file| candidates_for(file) }
+           .uniq
+           .select { |f| File.exist?(f) }
+           .sort
+    end
+
+    # Compute candidate spec paths for a single file.
+    #
+    # @param file [String]
+    # @return [Array<String>]
+    def candidates_for(file)
+      return [file] if spec_file?(file)
+
+      spec_dirs.flat_map { |dir| spec_paths_in(file, dir) }
+    end
+
+    # Return true when +file+ already looks like a spec file.
+    def spec_file?(file)
+      file.end_with?(SPEC_SUFFIX)
+    end
+
+    private
+
+    # Build candidate spec paths by replacing a source prefix with +spec_dir+.
+    #
+    # Examples
+    #   spec_paths_in("lib/foo/bar.rb", "spec")
+    #   #=> ["spec/foo/bar_spec.rb", "spec/lib/foo/bar_spec.rb"]
+    def spec_paths_in(file, spec_dir)
+      paths = []
+
+      # Strip a leading source directory component (lib, app, src …) when
+      # present, and map into the spec directory.
+      parts = file.split(File::SEPARATOR)
+      if parts.length > 1 && source_dir?(parts.first)
+        inner = File.join(parts[1..])
+        paths << File.join(spec_dir, spec_name(inner))
+      end
+
+      # Always add a flat mapping: spec_dir/<basename>_spec.rb
+      paths << File.join(spec_dir, spec_name(File.basename(file)))
+
+      # And a full-path mapping keeping all path components.
+      paths << File.join(spec_dir, spec_name(file)) unless file.start_with?(spec_dir)
+
+      paths.uniq
+    end
+
+    # Convert a plain Ruby filename to its _spec.rb counterpart.
+    def spec_name(filename)
+      filename.sub(/\.rb\z/, SPEC_SUFFIX)
+    end
+
+    # Heuristic: treat common source directory names as "source dirs".
+    def source_dir?(name)
+      %w[lib app src].include?(name)
+    end
+  end
+end

data/lib/specs_for/runner.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "finder"
+
+class SpecsFor
+  # Runner parses CLI arguments, discovers spec files, and executes RSpec.
+  class Runner
+    attr_reader :files, :options
+
+    DEFAULT_OPTIONS = {
+      verbose:  false,
+      dry_run:  false,
+      rspec_options: [],
+    }.freeze
+
+    def initialize(argv = ARGV)
+      @argv    = argv.dup
+      @options = DEFAULT_OPTIONS.dup
+      @files   = []
+    end
+
+    # Entry-point: parse args, find specs, run rspec.
+    # Returns the exit status (Integer).
+    def run
+      parse_options
+      resolve_files
+      spec_files = find_spec_files
+
+      if spec_files.empty?
+        warn "specs-for: no spec files found"
+        return 1
+      end
+
+      execute_rspec(spec_files)
+    end
+
+    private
+
+    def parse_options
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: specs-for [options] [file ...]"
+
+        opts.on("-n", "--dry-run", "Print spec files without running RSpec") do
+          @options[:dry_run] = true
+        end
+
+        opts.on("-v", "--verbose", "Show extra output") do
+          @options[:verbose] = true
+        end
+
+        opts.on("--rspec-opts OPTS", "Extra options forwarded to RSpec") do |o|
+          @options[:rspec_options] = o.split
+        end
+
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit 0
+        end
+
+        opts.on_tail("--version", "Show version") do
+          require_relative "version"
+          puts SpecsFor::VERSION
+          exit 0
+        end
+      end
+
+      # Separate specs-for flags from positional file arguments.
+      @files = parser.parse!(@argv)
+    end
+
+    # When no explicit files are given, fall back to git-changed files.
+    def resolve_files
+      return unless @files.empty?
+
+      @files = git_changed_files
+      if @options[:verbose]
+        puts "specs-for: discovered #{@files.length} changed file(s) from git"
+      end
+    end
+
+    def find_spec_files
+      finder = Finder.new
+      specs  = finder.find(@files)
+      if @options[:verbose]
+        puts "specs-for: found spec files:"
+        specs.each { |s| puts "  #{s}" }
+      end
+      specs
+    end
+
+    def execute_rspec(spec_files)
+      cmd = ["rspec"] + @options[:rspec_options] + spec_files
+      if @options[:dry_run] || @options[:verbose]
+        puts "specs-for: #{cmd.join(' ')}"
+      end
+      return 0 if @options[:dry_run]
+
+      system(*cmd) ? 0 : 1
+    end
+
+    # Return files changed (added, modified) relative to HEAD using git.
+    def git_changed_files
+      staged   = `git diff --name-only --diff-filter=ACM HEAD 2>/dev/null`.split("\n")
+      unstaged = `git diff --name-only --diff-filter=ACM 2>/dev/null`.split("\n")
+      (staged + unstaged).uniq.select { |f| f.end_with?(".rb") }
+    end
+  end
+end

data/lib/specs_for/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class SpecsFor
+  RELEASES = [
+    ["0.1.0", "2026-03-25", "Initial release"],
+    ["0.2.0", "2026-05-06", "Add support for tags and improved file search"]
+  ]
+  VERSION = RELEASES.last.first
+end

data/lib/specs_for.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require_relative "specs_for/version"
+require "open3"
+require "optparse"
+require "shellwords"
+
+# Finds and runs RSpec spec files corresponding to a given set of source files.
+# rubocop:disable Metrics/ClassLength
+class SpecsFor
+  PROG      = File.basename($PROGRAM_NAME)
+  VALID_TAG = /\A[a-zA-Z_][a-zA-Z0-9_:]*\z/
+
+  def initialize(files: [], specs: [], opts: nil)
+    @file_args = []
+    @files     = files
+    @specs     = specs
+    @opts      = opts
+  end
+
+  attr_reader :file_args, :files, :specs
+
+  def exact?;                opts[:exact];              end
+  def norun?;                opts[:norun];              end
+  def verbose?;              opts[:verbose];            end
+  def debug?;                opts[:debug];              end
+  def show?;                 opts[:show];               end
+  def tags;                  opts[:tags];               end
+  def run?;                  opts[:run];                end
+  def changed?;              opts[:changed];            end
+  def filenames_from_stdin?; opts[:filenames_from_stdin]; end
+
+  def parse_options(args = ARGV)
+    @opts = { tags: [] }
+    parser = OptionParser.new do |opt|
+      opt.banner = <<~BANNER
+        Usage: #{PROG} [options] [- | FILE ...]
+
+        Finds and runs RSpec specs for the given Ruby source files. Pass '-' to
+        read filenames from STDIN. Spec files are passed through unchanged; source
+        files are mapped to spec/ paths by replacing app/ or lib/ with spec/.
+
+        Uses 'ag' for file search when available, otherwise Dir[].
+        Prefixes rspec with 'asdf exec' when ruby is managed by asdf.
+
+        Examples:
+          #{PROG} lib/foo.rb               # run spec for one file
+          #{PROG} -c                       # run specs for git-changed files
+          #{PROG} -c -I                    # same, with --tag integration
+          git diff --name-only | #{PROG} - # pipe filenames from stdin
+
+        Options:
+      BANNER
+      opt.on('-h', '--help')                                              { warn opt; exit }
+      opt.on('-c', '--changed',              'Use git-changed files')
+      opt.on('-d', '--debug',                'Debug mode (opens pry if available)')
+      opt.on('-e', '--exact',                'Match FILE exactly')
+      opt.on('-I', '--integration',          'Add --tag integration')    { add_tag 'integration' }
+      opt.on('-M', '--manual-integration',   'Add --tag manual_integration') { add_tag 'manual_integration' }
+      opt.on('-n', '--norun',                'Show command, do not execute')
+      opt.on('-r', '--run',                  'Force run rspec (default unless -n or -s)')
+      opt.on('-s', '--show',                 'Print spec paths, do not run rspec')
+      opt.on('-TNAME', '--tag NAME',         'Add --tag NAME') { |name| add_tag name }
+      opt.on('-v', '--verbose',              'Be verbose')
+    end
+    parser.parse!(args, into: @opts)
+    @opts[:filenames_from_stdin] = true if args.delete('-')
+    @file_args = args
+    if file_args.empty? && !filenames_from_stdin? && !changed?
+      warn "Error: at least one FILE argument is required. Use '-' to read filenames from STDIN."
+      warn parser
+      exit 1
+    end
+    @opts[:run] = true if !@opts[:norun] && !@opts[:show] && @opts[:run].nil?
+    if @opts[:debug]
+      begin
+        require 'pry'
+      rescue LoadError
+        warn "debug: pry not available, continuing without it"
+        @opts[:debug] = false
+      end
+    end
+  end
+
+  def opts
+    parse_options unless @opts
+    @opts
+  end
+
+  def run(args = ARGV)
+    parse_options(args)
+    collect_file_names
+    if file_args.empty?
+      return if changed?
+      warn "Error: no input filenames provided. Pass FILE args or pipe at least one filename to '-'."
+      exit 1
+    end
+    collect_files
+    collect_specs
+    run? ? run_specs : show_specs
+  end
+
+  # Parses a `git status -s` output block and returns the relevant filenames.
+  def filter_git_status(status_output)
+    status_output.each_line(chomp: true).filter_map do |line|
+      # git status -s uses a fixed two-char XY status field followed by a space
+      status = line[0, 2].strip
+      rest   = line[3..]
+      next if rest.nil? || rest.empty?
+
+      case status
+      when 'M', 'A', '??' then rest
+      when 'R'            then rest.split(' -> ', 2).last  # "old -> new", take new name
+      when 'D'            then nil                         # deleted — skip
+      end
+    end
+  end
+
+  # Parses either a quoted path (allows spaces) or an unquoted path from the
+  # start of +str+, returning [filename, remainder] or nil if nothing matched.
+  def extract_filename(str)
+    match = str.match(/^\s*(?:"([^"]*)"|(\S+))\s*(.*)$/) if str
+    [match[1] || match[2], match[3]] if match
+  end
+
+  # Converts a source file path to its spec path and appends it to @specs if
+  # the spec file exists.  Handles app/**/*.rb, lib/**/*.rb, and the component
+  # monorepo layout components/NAME/app/**/*.rb / components/NAME/lib/**/*.rb,
+  # preserving the component prefix.
+  def collect_spec_for(file)
+    spec_file = file
+      .sub(%r{(?<=/|^)((?:components/\w+/)?)(?:app|lib)/}, '\1spec/')
+      .sub(/\.rb$/, '_spec.rb')
+    if File.exist?(spec_file)
+      @specs << spec_file
+      warn "==> Found spec for #{file}" if verbose?
+    elsif verbose?
+      warn "==> No spec file for #{file}"
+    end
+  end
+
+  def collect_specs
+    not_found = []
+    files.each do |file|
+      if file.end_with?('_spec.rb')
+        @specs << file
+      elsif file.match?(%r{(?:^|/)(?:components/\w+/)?(?:app|lib)/})
+        collect_spec_for(file)
+      elsif Dir.exist?(file)
+        # skip directories
+      else
+        not_found << file if verbose?
+      end
+    end
+    warn "==> No spec file for:\n  #{not_found.join("\n  ")}" if verbose? && not_found.any?
+    @specs = @specs.uniq.sort
+  end
+
+  def tag_opts
+    tag_argv.shelljoin.strip
+  end
+
+  def use_asdf?
+    ruby_path.include?('/.asdf/')
+  end
+
+  def rspec_command
+    argv = ['bundle', 'exec', 'rspec', *tag_argv, *specs]
+    argv.unshift('asdf', 'exec') if use_asdf?
+    argv
+  end
+
+  private
+
+  def add_tag(name)
+    unless name.match?(VALID_TAG)
+      warn "Invalid tag name ignored: #{name.inspect}"
+      return
+    end
+    @opts[:tags] << name unless @opts[:tags].include?(name)
+  end
+
+  def collect_file_names
+    file_args.concat(local_changed_filenames) if changed?
+    file_args.concat(read_filenames_from_stdin) if filenames_from_stdin?
+  end
+
+  def collect_files(args = file_args)
+    args.each do |file_arg|
+      if Dir.exist?(file_arg)
+        collect_files(Dir.children(file_arg).map { |f| File.join(file_arg, f) })
+      elsif File.exist?(file_arg)
+        @files << file_arg
+      else
+        found = find_file(file_arg)
+        if found.empty?
+          warn "==> Could not find: #{file_arg}"
+        else
+          show_files(found, 'Found file') if verbose?
+          @files.concat(found)
+        end
+      end
+    end
+  end
+
+  def find_file(file)
+    ag_present? ? find_file_with_ag(file) : find_file_with_dir(file)
+  end
+
+  def ag_present?
+    return @ag_present unless @ag_present.nil?
+    @ag_present = system('which', 'ag', out: IO::NULL, err: IO::NULL)
+  end
+
+  def build_file_pattern(file, mode:)
+    dir   = File.dirname(file)
+    base  = File.basename(file)
+    ext   = File.extname(base)
+    plain = file.count('/').zero?
+
+    pat =
+      if plain && exact?
+        mode == :regex ? base                  : "**/#{base}"
+      elsif plain
+        mode == :regex ? ".*#{base}"           : "**/*#{base}"
+      elsif exact?
+        mode == :regex ? "(?:^|/)#{dir}/#{base}$" : "**/#{dir}/#{base}"
+      else
+        mode == :regex ? ".*#{dir}/.*#{base}"  : "**/#{dir}/*#{base}"
+      end
+
+    return pat if ext
+
+    pat + (exact? ? (mode == :regex ? '\\.rb$'  : '.rb')
+                  : (mode == :regex ? '*\\.rb$' : '*.rb'))
+  end
+
+  def find_file_with_ag(file)
+    binding.pry if debug? # rubocop:disable Lint/Debugger
+    stdout, = Open3.capture2('ag', '-S', '-g', build_file_pattern(file, mode: :regex))
+    stdout.split("\n")
+  end
+
+  def find_file_with_dir(file)
+    binding.pry if debug? # rubocop:disable Lint/Debugger
+    Dir[build_file_pattern(file, mode: :glob)]
+  end
+
+  def show_files(files, label = nil)
+    if files.size == 1
+      warn "#{label} #{files.first}"
+    else
+      warn "#{label}s:"
+      warn "  #{files.sort.join("\n  ")}"
+    end
+  end
+
+  def show_specs
+    puts specs.join("\n")
+  end
+
+  def run_specs
+    argv = rspec_command
+    if norun?
+      warn "(norun) #{argv.shelljoin}"
+    else
+      warn "--> #{argv.shelljoin}"
+      system(*argv)
+    end
+  end
+
+  def tag_argv
+    tags.compact.flat_map { |tag| ['--tag', tag] }
+  end
+
+  def ruby_path
+    @ruby_path ||= Open3.capture2('which', 'ruby').first.chomp
+  end
+
+  def local_changed_filenames
+    stdout, = Open3.capture2('git', 'status', '-s')
+    filter_git_status(stdout).reject { |file| ignored_by_git?(file) }
+  end
+
+  def ignored_by_git?(file)
+    system('git', 'check-ignore', '-q', '--', file, out: IO::NULL, err: IO::NULL)
+  end
+
+  def read_filenames_from_stdin
+    $stdin.each_line.flat_map do |line|
+      filenames = []
+      loop do
+        result = extract_filename(line)
+        break unless result
+        filename, line = result
+        filenames << filename
+      end
+      filenames
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength

data/sig/specs_for.rbs

@@ -0,0 +1,31 @@
+class SpecsFor
+  VERSION: String
+  VALID_TAG: Regexp
+
+  attr_reader file_args: Array[String]
+  attr_reader files: Array[String]
+  attr_reader specs: Array[String]
+
+  def initialize: (?files: Array[String], ?specs: Array[String], ?opts: Hash[Symbol, untyped]?) -> void
+  def run: (?Array[String] args) -> void
+  def parse_options: (?Array[String] args) -> void
+  def opts: () -> Hash[Symbol, untyped]
+
+  def exact?: () -> bool?
+  def norun?: () -> bool?
+  def verbose?: () -> bool?
+  def debug?: () -> bool?
+  def show?: () -> bool?
+  def tags: () -> Array[String]
+  def run?: () -> bool?
+  def changed?: () -> bool?
+  def filenames_from_stdin?: () -> bool?
+
+  def filter_git_status: (String status_output) -> Array[String]
+  def extract_filename: (String? str) -> [String, String]?
+  def collect_spec_for: (String file) -> void
+  def collect_specs: () -> void
+  def tag_opts: () -> String
+  def use_asdf?: () -> bool
+  def rspec_command: () -> Array[String]
+end

metadata

@@ -0,0 +1,213 @@
+--- !ruby/object:Gem::Specification
+name: specs_for
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Alan Stebbens
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.19.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.19.0
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.3.1
+- !ruby/object:Gem::Dependency
+  name: fuubar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.43
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.43
+- !ruby/object:Gem::Dependency
+  name: yard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: A CLI tool that maps Ruby source files to their RSpec counterparts and
+  runs them. Supports git-changed files, stdin file lists, component monorepo layouts,
+  and RSpec tag filtering.
+email:
+- aks@stebbens.org
+executables:
+- specs-for
+- specs_for
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/specs-for
+- bin/specs_for
+- lib/specs_for.rb
+- lib/specs_for/finder.rb
+- lib/specs_for/runner.rb
+- lib/specs_for/version.rb
+- sig/specs_for.rbs
+homepage: https://github.com/aks/specs-for
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aks/specs-for
+  source_code_uri: https://github.com/aks/specs-for
+  changelog_uri: https://github.com/aks/specs-for/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.10
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Produce and run rspec on a set of given or discovered filenames
+test_files: []