spectracer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c55000e91497b314c04f6a3139416b257e63af8c16deb7c1d7ddbb657e4d2443
+  data.tar.gz: '028a4517c2bfc6fe8d0f3fa1341fb1f00b79852cc13999d38cc176edf3f4b92d'
+SHA512:
+  metadata.gz: 5622bd3c3c4cd2a056711798b435b928a0bc927bd74c358a4afe6764903983682c68e0ce958a0ba3d5e793644a4ae206c19ead323ab7f1456df0eaf7c9546b9f
+  data.tar.gz: 46661f6f0882c81122d401a68424b927dd57bc3154628cf838fb33bf6ac642c34f8563cbbf1b594617c61193a79478d4e1c2a5df800f08ebd765495d5869c993

data/AGENTS.md

@@ -0,0 +1,93 @@
+# Spectracer - Agent Instructions
+
+## Overview
+
+Spectracer is a Ruby gem that traces RSpec/Minitest dependencies and determines which specs to run based on git changes. It integrates with Buildkite CI for parallel test optimization.
+
+## Commands
+
+### Testing
+```bash
+bundle exec rspec                    # Run all tests
+bundle exec rspec spec/core/         # Run specific directory
+```
+
+### Linting
+```bash
+bundle exec standardrb               # Check style
+bundle exec standardrb --fix         # Auto-fix issues
+```
+
+### Full CI Check
+```bash
+bundle exec rake                     # Runs spec + standardrb
+```
+
+### Build Gem
+```bash
+bundle exec rake build               # Build .gem file
+bundle exec rake install             # Install locally
+```
+
+## Architecture
+
+```
+lib/spectracer/
+├── core/                    # Pure business logic (no I/O)
+│   ├── paths.rb             # Path computation from env
+│   └── spec_selector.rb     # Spec selection algorithm
+├── io/                      # I/O adapters (mockable)
+│   ├── command_runner.rb    # Shell command wrapper
+│   ├── config_loader.rb     # YAML config loading
+│   ├── dependency_store.rb  # Gzip JSON read/write
+│   └── git_adapter.rb       # Git gem wrapper
+├── providers/               # Data providers
+│   ├── git_changed_files.rb # Changed file detection
+│   └── repository.rb        # Repo root detection
+├── orchestrators/           # Coordinate components
+│   ├── dependency_collector.rb
+│   ├── dependency_tracer.rb
+│   └── spec_run_determiner.rb
+├── integrations/            # Test framework hooks
+│   ├── minitest.rb
+│   ├── railtie.rb
+│   └── rspec.rb
+├── tasks/
+│   └── spectracer.rake
+├── logger.rb
+└── version.rb
+```
+
+## Code Conventions
+
+- All classes use dependency injection for testability
+- Core classes are pure functions (no side effects)
+- I/O classes wrap external dependencies and are mockable
+- Use `frozen_string_literal: true` in all files
+- Follow StandardRB style (double quotes, no trailing commas)
+- RBS type signatures in `sig/spectracer.rbs`
+
+## Key Design Decisions
+
+1. **No ENV at require-time**: All environment variables read at runtime via injected `env` parameter
+2. **Dependency injection**: All collaborators passed via `initialize` with sensible defaults
+3. **Pure core logic**: `SpecSelector` has no I/O, fully testable with plain data
+4. **Git gem over shelling out**: Uses `ruby-git` gem for git operations
+
+## Testing Patterns
+
+- Unit tests mock collaborators using `instance_double`
+- Integration tests use real git operations
+- Test files mirror source structure: `lib/spectracer/core/paths.rb` → `spec/core/paths_spec.rb`
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `WITH_SPECTRACER_TRACING` | Enable dependency tracing (`"true"`) |
+| `WITH_SPECTRACER_DEBUG` | Enable debug logging (`"true"`) |
+| `SPECTRACER_TMP_DIRECTORY` | Override output directory |
+| `BUILDKITE_BUILD_ID` | Buildkite build identifier |
+| `BUILDKITE_JOB_ID` | Buildkite job identifier |
+| `BUILDKITE_BRANCH` | Current branch name |
+| `BUILDKITE_PIPELINE_DEFAULT_BRANCH` | Default branch (e.g., `main`) |

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [1.0.0] - 2026-01-31
+
+### Added
+
+- Intelligent test selection based on git changes
+- RSpec and Minitest integration via TracePoint
+- Dependency tracing with gzip-compressed JSON storage
+- Buildkite CI integration for parallel test optimization
+- Git adapter for changed file detection
+- Configurable via `.spectracer.yml`
+
+### Changed
+
+- Switch TracePoint from `:line` to `:call` events for dramatically improved performance
+- Renamed gem from `spectacle` to `spectracer`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Mitch Smith
+
+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,177 @@
+# Spectracer
+
+> spectracer (noun): something exhibited to view as unusual, notable, or entertaining
+
+Spectracer is a Ruby gem that intelligently determines which specs to run based on the files you've changed. By tracing dependencies during test execution, Spectracer builds a map of which source files are used by which specs, then uses this data to run only the relevant tests.
+
+## Features
+
+- **Dependency tracing** - Automatically tracks which files each spec depends on
+- **Smart test selection** - Only runs specs affected by your changes
+- **CI integration** - Built for Buildkite with parallel job support
+- **Framework support** - Works with both RSpec and Minitest
+- **Rails compatible** - Includes Railtie for automatic setup
+
+## Installation
+
+Add Spectracer to your Gemfile:
+
+```ruby
+group :development, :test do
+  gem "spectracer", github: "mitchbne/spectracer", branch: "main"
+end
+```
+
+Then run:
+
+```bash
+bundle install
+bundle exec rake spectracer:install
+```
+
+This creates a `.spectracer.yml` configuration file in your project root.
+
+## How It Works
+
+Spectracer operates in three phases:
+
+### 1. Tracing Phase
+
+Run your full test suite with tracing enabled:
+
+```bash
+WITH_SPECTRACER_TRACING=true bundle exec rspec
+```
+
+This uses Ruby's TracePoint to record which files each spec touches, outputting a gzipped JSON file mapping specs to their dependencies.
+
+### 2. Collection Phase
+
+After running specs across parallel jobs, collect all tracing artifacts:
+
+```bash
+bundle exec rake spectracer:collect_dependencies
+```
+
+This combines individual trace files into a single inverse dependency map: for each source file, which specs depend on it.
+
+### 3. Selection Phase
+
+When running tests on a branch, determine which specs to run:
+
+```bash
+SPECS=$(bundle exec rake spectracer:spec_determiner)
+bundle exec rspec $SPECS
+```
+
+## Configuration
+
+Create a `.spectracer.yml` file in your project root:
+
+```yaml
+defaults:
+  all_specs: "spec/**/*_spec.rb"
+  no_specs: ""
+
+on_empty_spec_set: "{{all_specs}}"
+
+globs_matcher:
+  "Gemfile": "{{all_specs}}"
+  "Gemfile.lock": "{{all_specs}}"
+  "db/schema.rb": "spec/models/**/*_spec.rb"
+  "config/routes.rb": "spec/routing/**/*_spec.rb"
+  "app/views/**/*": "spec/views/**/*_spec.rb,spec/features/**/*_spec.rb"
+```
+
+### Configuration Options
+
+| Option | Description |
+|--------|-------------|
+| `defaults` | Named patterns that can be referenced in other options |
+| `on_empty_spec_set` | Pattern to run when no specs are affected by changes |
+| `globs_matcher` | Map of file globs to spec patterns to run when matched |
+
+## Buildkite Integration
+
+Example `pipeline.yml`:
+
+```yaml
+steps:
+  # Step 1: Run full suite with tracing (weekly/nightly)
+  - label: ":rspec: Full Suite with Tracing"
+    command: |
+      WITH_SPECTRACER_TRACING=true bundle exec rspec --format progress
+    artifact_paths:
+      - "tmp/spectracer/**/*"
+    branches: main
+
+  # Step 2: Collect dependencies
+  - label: ":package: Collect Dependencies"
+    command: |
+      buildkite-agent artifact download "tmp/spectracer/**/*" .
+      bundle exec rake spectracer:collect_dependencies
+    artifact_paths:
+      - "tmp/spectracer/dependencies.json.gz"
+    depends_on: "full-suite"
+
+  # Step 3: Run affected specs on feature branches
+  - label: ":rspec: Affected Specs"
+    command: |
+      buildkite-agent artifact download "tmp/spectracer/dependencies.json.gz" .
+      SPECS=$(bundle exec rake spectracer:spec_determiner)
+      bundle exec rspec $SPECS
+    branches: "!main"
+```
+
+## RSpec Integration
+
+Spectracer automatically configures RSpec when required. No additional setup needed:
+
+```ruby
+# Gemfile
+gem "spectracer"
+
+# That's it! Tracing is enabled via WITH_SPECTRACER_TRACING=true
+```
+
+## Minitest Integration
+
+Spectracer also supports Minitest:
+
+```ruby
+# test/test_helper.rb
+require "spectracer"
+
+# Tracing is automatically enabled when WITH_SPECTRACER_TRACING=true
+```
+
+## Debug Mode
+
+Enable debug logging to see what Spectracer is doing:
+
+```bash
+WITH_SPECTRACER_DEBUG=true bundle exec rake spectracer:spec_determiner
+```
+
+## Development
+
+After checking out the repo:
+
+```bash
+bin/setup                    # Install dependencies
+bundle exec rake             # Run tests + linting
+bundle exec rspec            # Run tests only
+bundle exec standardrb       # Run linting only
+```
+
+## Architecture
+
+See [docs/architecture.md](docs/architecture.md) for detailed architecture documentation.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mitchbne/spectracer.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/spectacle.default.yml

@@ -0,0 +1,15 @@
+# This file was generated by the 'spectracer:install' Rake task.
+# You can modify this file to customize the behavior of Spectracer.
+defaults:
+  all_specs_glob: "spec/**/*_spec.rb"
+  no_specs_glob: "{}"
+
+# When no spec files are detected to run, Spectracer will run the specs defined in the 'on_empty_spec_set' key.
+on_empty_spec_set: "{{no_specs_glob}}"
+
+# If a file changes and it matches the glob, the corresponding pattern will be added to the list of spec files to run.
+# These will take precedence over the 'on_empty_spec_set' key.
+globs_matcher:
+  "Gemfile": "{{all_specs_glob}}"
+  "Gemfile.lock": "{{all_specs_glob}}"
+  "config/**": "{{all_specs_glob}}"

data/lib/spectracer/core/paths.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Spectracer
+  module Core
+    class Paths
+      DEFAULT_OUTPUT_DIR = "tmp/spectracer"
+
+      def initialize(env: ENV)
+        @env = env
+      end
+
+      def build_id
+        @env["BUILDKITE_BUILD_ID"] || "local"
+      end
+
+      def job_id
+        @env["BUILDKITE_JOB_ID"] || "local"
+      end
+
+      def output_directory
+        @env["SPECTRACER_TMP_DIRECTORY"] || DEFAULT_OUTPUT_DIR
+      end
+
+      def spec_artifact_output_file
+        File.join(output_directory, "tracing_output", build_id, "#{job_id}.json.gz")
+      end
+
+      def spec_artifacts_download_glob
+        File.join(output_directory, "tracing_output", build_id, "*.json.gz")
+      end
+
+      def collected_dependencies_file
+        File.join(output_directory, "dependencies.json.gz")
+      end
+
+      def normalize(file_path, repo_root:)
+        relative = file_path.sub(/\A#{Regexp.escape(repo_root)}/, ".")
+        relative.start_with?("./") ? relative : "./#{relative}"
+      end
+
+      def strip_dot_prefix(path)
+        path.sub(%r{\A\./}, "")
+      end
+    end
+  end
+end

data/lib/spectracer/core/spec_selector.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Spectracer
+  module Core
+    class SpecSelector
+      def call(changed_files:, inverse_deps:, globs:, on_empty:)
+        spec_set = Set.new
+
+        changed_files.each do |file|
+          spec_set.add(file) if file.end_with?("_spec.rb")
+
+          file_key = file.start_with?("./") ? file : "./#{file}"
+          if (specs = inverse_deps[file_key])
+            spec_set.merge(specs)
+          end
+
+          globs.each do |glob, pattern|
+            normalized_glob = glob.sub(%r{\A\./}, "")
+            spec_set.add(pattern) if File.fnmatch?(normalized_glob, file)
+          end
+        end
+
+        files = spec_set.to_a.sort
+        files.empty? ? on_empty : files.join(",")
+      end
+    end
+  end
+end

data/lib/spectracer/integrations/minitest.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Spectracer
+  module Integrations
+    module Minitest
+      class << self
+        attr_accessor :tracer
+
+        def install!
+          return unless defined?(::Minitest)
+          return unless ENV["WITH_SPECTRACER_TRACING"] == "true"
+
+          logger = Spectracer::Logger.new(
+            enabled: ENV["WITH_SPECTRACER_DEBUG"] == "true",
+            level: :debug
+          )
+
+          self.tracer = Spectracer::Orchestrators::DependencyTracer.new(logger: logger)
+
+          ::Minitest.singleton_class.prepend(RunPatch)
+        end
+      end
+
+      module RunPatch
+        def run(args = [])
+          result = super
+          Spectracer::Integrations::Minitest.tracer&.write_output!
+          result
+        end
+      end
+
+      module TestCasePlugin
+        def before_setup
+          super
+          tracer = Spectracer::Integrations::Minitest.tracer
+          return unless tracer
+
+          file_path = method(name).source_location&.first
+          tracer.current_spec_file = file_path if file_path
+        end
+
+        def run
+          tracer = Spectracer::Integrations::Minitest.tracer
+          return super unless tracer
+
+          tracer.with_tracing { super }
+        end
+      end
+    end
+  end
+end
+
+if defined?(::Minitest::Test) && ENV["WITH_SPECTRACER_TRACING"] == "true"
+  ::Minitest::Test.prepend(Spectracer::Integrations::Minitest::TestCasePlugin)
+end

data/lib/spectracer/integrations/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Spectracer
+  module Integrations
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load "spectracer/tasks/spectracer.rake"
+      end
+    end
+  end
+end

data/lib/spectracer/integrations/rspec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Spectracer
+  module Integrations
+    module RSpec
+      def self.install!
+        return unless defined?(::RSpec) && ::RSpec.respond_to?(:configure)
+        return unless ENV["WITH_SPECTRACER_TRACING"] == "true"
+
+        logger = Spectracer::Logger.new(
+          enabled: ENV["WITH_SPECTRACER_DEBUG"] == "true",
+          level: :debug
+        )
+
+        tracer = Spectracer::Orchestrators::DependencyTracer.new(logger: logger)
+
+        ::RSpec.configure do |config|
+          config.around(:example) do |example|
+            tracer.current_spec_file = example.file_path
+            tracer.with_tracing { example.run }
+          end
+
+          config.after(:suite) do
+            tracer.write_output!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spectracer/io/command_runner.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Spectracer
+  module IO
+    class CommandRunner
+      def initialize(logger: nil)
+        @logger = logger
+      end
+
+      def run(command)
+        @logger&.debug("Running command: '#{command}'")
+
+        stdout, stderr, status = Open3.capture3(command)
+
+        unless status.success?
+          @logger&.warn("Command failed with status #{status.exitstatus}: #{stderr}")
+        end
+
+        stdout.chomp
+      end
+    end
+  end
+end

data/lib/spectracer/io/config_loader.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Spectracer
+  module IO
+    class ConfigLoader
+      FILE_PATH = ".spectracer.yml"
+      DEFAULT_FILE_PATH = File.expand_path("../../spectracer.default.yml", __dir__)
+
+      def initialize(logger: nil)
+        @logger = logger
+      end
+
+      def load
+        raw_config = load_raw_config
+        return default_config if raw_config.nil?
+
+        parse_config(raw_config)
+      rescue => e
+        @logger&.error("Error loading configuration: #{e.message}")
+        default_config
+      end
+
+      private
+
+      def load_raw_config
+        if File.exist?(FILE_PATH)
+          YAML.safe_load_file(FILE_PATH)
+        else
+          @logger&.debug("No configuration file found at #{FILE_PATH.inspect}. Using defaults.")
+          YAML.safe_load_file(DEFAULT_FILE_PATH)
+        end
+      end
+
+      def parse_config(raw)
+        defaults = raw.fetch("defaults", {})
+        on_empty = raw.fetch("on_empty_spec_set", "")
+        globs_matcher = raw.fetch("globs_matcher", {})
+
+        {
+          on_empty_spec_set: resolve_templates(on_empty, defaults),
+          globs: globs_matcher.transform_values { |v| resolve_templates(v, defaults) }
+        }
+      end
+
+      def resolve_templates(template, defaults)
+        template.gsub(/\{\{(.*?)\}\}/) { defaults[$1] || "" }
+      end
+
+      def default_config
+        {on_empty_spec_set: "", globs: {}}
+      end
+    end
+  end
+end

data/lib/spectracer/io/dependency_store.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "zlib"
+
+module Spectracer
+  module IO
+    class DependencyStore
+      def initialize(logger: nil)
+        @logger = logger
+      end
+
+      def read(file_path)
+        return {} unless File.exist?(file_path)
+
+        case File.extname(file_path)
+        when ".gz"
+          read_gzipped_json(file_path)
+        when ".json"
+          read_json(file_path)
+        else
+          @logger&.warn("Unknown file format: #{file_path}")
+          {}
+        end
+      rescue JSON::ParserError => e
+        @logger&.error("Failed to parse JSON file '#{file_path}': #{e.message}")
+        {}
+      end
+
+      def write(data, file_path)
+        FileUtils.mkdir_p(File.dirname(file_path))
+
+        @logger&.debug("Writing to #{file_path}")
+        @logger&.debug(JSON.pretty_generate(data))
+
+        File.open(file_path, "wb") do |f|
+          Zlib::GzipWriter.wrap(f) do |gz|
+            gz.write(data.to_json)
+          end
+        end
+      end
+
+      def glob(pattern)
+        Dir.glob(pattern)
+      end
+
+      private
+
+      def read_gzipped_json(file_path)
+        Zlib::GzipReader.open(file_path) do |gz|
+          JSON.parse(gz.read)
+        end
+      end
+
+      def read_json(file_path)
+        JSON.parse(File.read(file_path))
+      end
+    end
+  end
+end