rspec-ai-formatter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78649016754440db1ab8030edcf686c32a35871bb8d967d3b2423e6677c6d68c
+  data.tar.gz: 3d82c9e6e41523f4e914d6a66815755cbe7e59d5313feadc938fcbe6ec785904
+SHA512:
+  metadata.gz: 1b0d8fc0ef7a083fa584db00e2f11ad5dd0bb2a5456a7addca0ab10aac6ef6bd514ca39b24f208b82d5dcfda027ab20b2b9617a8a94fbe57acd1bcc33f76874c
+  data.tar.gz: e03b3ac07503f063d3b3c9aa8c9ed3591dfb1fc85471aaa75b9d5c89c0c482762122d6187efe893c2e8ca5964ba90f202697d26ee032e22e5332363026f62763

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sk
+
+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,302 @@
+# RSpec AI Formatter
+
+AI-friendly RSpec formatter optimized for minimal token usage in LLM contexts.
+
+## Why?
+
+Standard RSpec formatters waste tokens on visual noise:
+- **Progress formatter**: Dots and asterisks (`.F*`) with no file context
+- **Documentation formatter**: Hierarchical descriptions with indentation whitespace
+- **Both**: Failures dumped at end with redundant stack traces
+
+**AI Formatter**: One line per test, structured NDJSON, references to detailed logs.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+group :test do
+  gem 'rspec-ai-formatter', require: false
+end
+```
+
+## Usage
+
+### Basic
+
+```bash
+# Via CLI helper
+rspec-ai
+
+# Via RSpec directly
+rspec --format RSpec::AiFormatter::Formatter
+
+# With custom log directory
+rspec-ai --ai-logs-dir logs/test -- spec/
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RSPEC_AI_LOGS` | Directory for failure logs | `tmp/rspec_logs` |
+| `RSPEC_AI_CLEAN` | Clean logs before run | `0` |
+| `RSPEC_AI_FULL` | Enable full output (default is minimal) | `0` |
+| `RSPEC_AI_SIGNATURES` | Enable error signature hashing | `0` |
+| `RSPEC_AI_DEDUP` | Deduplicate identical errors | `0` |
+
+### Output Modes
+
+**Minimal mode (default)** — optimized for AI and CI:
+
+```bash
+bundle exec rspec --format RSpec::AiFormatter::Formatter
+```
+
+Output: `start`, failures, skips, `done`. Passing tests omitted.
+
+```json
+{"t":"start","total":100}
+{"t":"test","id":"spec/api_spec.rb:10","s":"fail","e":{"type":"Error","msg":"timeout","loc":"spec/api_spec.rb:12"}}
+{"t":"test","id":"spec/user_spec.rb:5","s":"skip","skip":"pending"}
+{"t":"done","passed":98,"failed":1,"skipped":1,"total":100,"time":1234}
+```
+
+**Full mode** — with all details:
+
+```bash
+RSPEC_AI_FULL=1 bundle exec rspec --format RSpec::AiFormatter::Formatter
+```
+
+Includes: test names, timestamps, timing for every test.
+
+| Mode | Passing tests | Failures | Skips | Events for 1000 tests |
+|------|---------------|----------|-------|----------------------|
+| Minimal (default) | Omitted | Full | Minimal | ~50 |
+| Full | Full event | Full | Full | ~1002 |
+
+**Use full mode when:**
+- Debugging individual test performance
+- You need to see all test names
+- Parsing requires timing data per test
+- Human-readable output is priority
+
+**Minimal mode removes:**
+- Passing tests (100% savings)
+- Test names (`n`) for skips
+- Timestamps (`ts`) on individual tests
+- Timing (`time`) for skips  
+- Timestamp from `done` event
+- Line end ranges in `id`
+- `./` prefix in file paths
+
+### Combined with Other Formatters
+
+```bash
+# AI format to file, progress to console
+rspec --format progress --format RSpec::AiFormatter::Formatter --out rspec.jsonl
+```
+
+### GitHub Actions
+
+The formatter auto-detects `GITHUB_ACTIONS=true` and emits workflow commands for inline PR annotations:
+
+```yaml
+- name: Run tests
+  env:
+    GITHUB_ACTIONS: true  # Usually already set by GitHub
+  run: bundle exec rspec --format RSpec::AiFormatter::Formatter
+```
+
+**Annotations appear on:**
+- Failed tests → `::error` with file/line
+- Skipped/pending tests → `::warning`
+
+**Example output:**
+```
+::error file=spec/models/user_spec.rb,line=42::expected false, got true
+::warning file=spec/api/client_spec.rb,line=15::Skipped: pending implementation
+```
+
+To disable annotations but keep NDJSON:
+```bash
+GITHUB_ACTIONS= bundle exec rspec --format RSpec::AiFormatter::Formatter
+```
+
+### Parallel Tests
+
+When using `parallel_tests`, each process writes its own output file. Merge them with `rspec-ai-merge`:
+
+```bash
+# Run tests in parallel, each with unique output file
+parallel_rspec --format RSpec::AiFormatter::Formatter --out tmp/parallel_{%}.jsonl -- spec/
+
+# Merge outputs
+rspec-ai-merge tmp/parallel_*.jsonl > combined.jsonl
+
+# With deduplication across all parallel runs
+rspec-ai-merge --dedup tmp/parallel_*.jsonl > combined.jsonl
+```
+
+**Merge options:**
+```bash
+rspec-ai-merge --help
+
+# Sort by timestamp (default)
+rspec-ai-merge --output combined.jsonl file1.jsonl file2.jsonl
+
+# Skip sorting, keep file order
+rspec-ai-merge --no-sort file1.jsonl file2.jsonl
+
+# Deduplicate errors across files
+rspec-ai-merge --dedup file1.jsonl file2.jsonl
+
+# Skip final summary
+rspec-ai-merge --no-summary file1.jsonl file2.jsonl
+```
+
+**Merged output includes:**
+- All test events sorted by timestamp
+- Combined `done` event with totals from all files
+- Deduplication summaries (if enabled)
+
+## Output Format
+
+### NDJSON Stream
+
+```json
+{"t":"start","suite":["spec/models/user_spec.rb"],"total":3,"ts":"2025-06-25T14:30:22.123Z"}
+{"t":"test","id":"spec/models/user_spec.rb:15-25","n":"User>valid?>requires email","s":"pass","time":12,"ts":"2025-06-25T14:30:22.135Z"}
+{"t":"test","id":"spec/models/user_spec.rb:27-40","n":"User>valid?>rejects invalid format","s":"fail","time":45,"e":{"type":"ExpectationNotMet","msg":"expected false, got true","loc":"spec/models/user_spec.rb:42","log":"tmp/rspec_logs/user_spec_27.log"},"ts":"2025-06-25T14:30:22.180Z"}
+{"t":"test","id":"spec/models/user_spec.rb:42-55","n":"User>valid?>accepts valid format","s":"skip","time":0,"skip":"pending implementation","ts":"2025-06-25T14:30:22.181Z"}
+{"t":"done","passed":1,"failed":1,"skipped":1,"total":3,"time":1247,"ts":"2025-06-25T14:30:23.370Z"}
+```
+
+### Log Files
+
+```
+tmp/rspec_logs/
+├── user_spec_27.log          # Per-failure details
+├── api_client_15.log
+└── index.json                # Machine-readable index
+```
+
+Example failure log:
+
+```
+================================================================================
+TEST: User > valid? > rejects invalid format
+LOCATION: spec/models/user_spec.rb:27
+STATUS: FAIL
+TIME: 45ms
+================================================================================
+
+ERROR: ExpectationNotMet
+MESSAGE:
+expected false, got true
+
+EXPECTED:
+false
+
+ACTUAL:
+true
+
+BACKTRACE:
+spec/models/user_spec.rb:42:in `block (3 levels) in <top (required)>'
+...
+```
+
+## Schema
+
+### Event Types
+
+| `t` | Description | Additional Fields |
+|-----|-------------|-------------------|
+| `start` | Suite started | `suite`, `total` |
+| `test` | Test completed | `id`, `n`, `s`, `time`, `e`/`skip` |
+| `done` | Suite finished | `passed`, `failed`, `skipped`, `total`, `time` |
+
+### Status Values
+
+| `s` | Meaning |
+|-----|---------|
+| `pass` | Test passed |
+| `fail` | Test failed (see `e` for details) |
+| `skip` | Test skipped/pending (see `skip` for reason) |
+
+### Error Object (`e`)
+
+| Field | Description |
+|-------|-------------|
+| `type` | Error class (shortened) |
+| `msg` | Truncated message (200 chars) |
+| `loc` | File:line of failure |
+| `log` | Path to full log file |
+| `sig` | MD5 signature of error (if dedup/signatures enabled) |
+| `diff` | Expected/actual diff (for expectations) |
+
+### Deduplication
+
+When `RSPEC_AI_DEDUP=1`, identical errors are collapsed:
+
+```json
+// First occurrence - full details
+{"t":"test","id":"spec/api_spec.rb:20","n":"GET /users returns 200","s":"fail","e":{"type":"TimeoutError","msg":"execution expired","loc":"spec/api_spec.rb:25","sig":"a3f9e2d1"}}
+
+// Duplicates - lightweight reference
+{"t":"dedup","sig":"a3f9e2d1","id":"spec/api_spec.rb:40","n":"GET /users with params","first":"spec/api_spec.rb:20"}
+{"t":"dedup","sig":"a3f9e2d1","id":"spec/api_spec.rb:60","n":"POST /users creates user","first":"spec/api_spec.rb:20"}
+
+// Summary at end
+{"t":"dedup_summary","sig":"a3f9e2d1","type":"TimeoutError","msg":"execution expired","count":3,"first":"spec/api_spec.rb:20","examples":["spec/api_spec.rb:20","spec/api_spec.rb:40","spec/api_spec.rb:60"]}
+```
+
+Useful when a shared setup/teardown failure cascades through many tests.
+
+## Token Efficiency
+
+| Scenario | Progress | Documentation | AI Formatter |
+|----------|----------|---------------|--------------|
+| 100 tests, all pass | ~200 | ~800 | ~150 |
+| 10 failures with traces | ~2000 | ~2500 | ~300 + files |
+| Parsing complexity | Hard | Hard | Trivial |
+
+## Features
+
+- ✅ **Streaming NDJSON**: Real-time output, parse-as-you-go
+- ✅ **Minimal mode**: Ultra-compact output for massive test suites (80% smaller)
+- ✅ **Location tracking**: File + line start-end for each test
+- ✅ **Failure isolation**: Full output to separate log files
+- ✅ **Error signatures**: Group similar failures by hash
+- ✅ **Error deduplication**: Collapse identical errors, show "and 4 more like this"
+- ✅ **Parallel test merging**: Merge outputs from parallel_tests runs
+- ✅ **Diff generation**: Smart expected/actual comparison
+- ✅ **Truncation**: Prevent token explosion on large outputs
+- ✅ **ANSI-free**: Clean text, no escape codes
+- ✅ **GitHub Actions**: Auto-detects and emits `::error`/`::warning` annotations
+
+## TODO
+
+### CI/CD Integration
+- [x] GitHub Actions workflow command integration — Auto-detect `GITHUB_ACTIONS` env and emit `::error` / `::warning` commands for inline PR annotations
+
+### Error Intelligence
+- [x] Error pattern deduplication across test runs — Group failures by signature hash, show "and 4 more like this"
+- [ ] Quick-fix hints integration with `did_you_mean` — Suggest typo corrections, similar method names
+- [ ] Error context snippets — Include 3-5 lines of source code around failure in log files
+
+### Performance & Insights
+- [ ] Performance baseline tracking — Compare to previous run, flag regressions >50%
+- [ ] Test selection metadata — Add tags, flakiness score, last failure date to each test event
+- [ ] Slowest tests report — Top N slowest tests in summary
+
+### Compatibility & Tooling
+- [ ] JUnit XML compatibility mode — Dual output for systems requiring XML
+- [x] Parallel test log merging — Clean merge of outputs from `parallel_tests` runs
+- [ ] Screenshot capture for system tests — Auto-capture Capybara screenshot path on failure
+- [ ] Custom output templates — User-defined NDJSON schema / field selection
+
+## License
+
+MIT

data/bin/rspec-ai

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# CLI helper for rspec-ai-formatter
+# Usage: rspec-ai [rspec-options] [--ai-logs-dir DIR]
+
+require 'optparse'
+
+# CLI wrapper for running RSpec with AI formatter
+# Handles option parsing and environment setup
+class RspecAiCli
+  def initialize(args)
+    @args = args
+    @log_dir = ENV['RSPEC_AI_LOGS'] || 'tmp/rspec_logs'
+    @rspec_args = []
+    @clean = false
+  end
+
+  def run
+    parse_options!
+    setup_environment
+    exec_rspec
+  end
+
+  private
+
+  def parse_options!
+    parser = OptionParser.new do |opts|
+      opts.banner = 'Usage: rspec-ai [options] [rspec options]'
+      opts.separator ''
+      opts.separator 'AI Formatter options:'
+
+      opts.on('--ai-logs-dir DIR', 'Directory for failure logs') do |dir|
+        @log_dir = dir
+      end
+
+      opts.on('--ai-clean', 'Clean log directory before run') do
+        @clean = true
+      end
+
+      opts.on('--ai-signatures', 'Enable error signature hashing') do
+        ENV['RSPEC_AI_SIGNATURES'] = '1'
+      end
+
+      opts.on('-h', '--help', 'Show this help') do
+        puts opts
+        puts
+        puts 'Environment variables:'
+        puts '  RSPEC_AI_LOGS      - Default log directory'
+        puts '  RSPEC_AI_CLEAN     - Clean logs before run (1/0)'
+        puts '  RSPEC_AI_SIGNATURES - Enable error signatures (1/0)'
+        exit
+      end
+
+      opts.separator ''
+      opts.separator 'All other options are passed to RSpec.'
+    end
+
+    # Split AI-specific options from RSpec options
+    ai_args = []
+    rspec_args = []
+
+    i = 0
+    while i < @args.length
+      arg = @args[i]
+
+      if arg.start_with?('--ai-')
+        ai_args << arg
+        if ['--ai-logs-dir'].include?(arg) && i + 1 < @args.length
+          ai_args << @args[i + 1]
+          i += 1
+        end
+      else
+        rspec_args << arg
+      end
+      i += 1
+    end
+
+    parser.parse!(ai_args)
+    @rspec_args = rspec_args
+  end
+
+  def setup_environment
+    ENV['RSPEC_AI_LOGS'] = @log_dir
+    ENV['RSPEC_AI_CLEAN'] = '1' if @clean
+
+    # Ensure the formatter is loaded
+    formatter_path = File.expand_path('../lib', __dir__)
+    ENV['RUBYOPT'] = "#{ENV.fetch('RUBYOPT', '')} -I#{formatter_path}"
+  end
+
+  def exec_rspec
+    cmd = ['rspec', '--format', 'RSpec::AiFormatter::Formatter']
+    cmd += @rspec_args
+
+    exec(*cmd)
+  end
+end
+
+RspecAiCli.new(ARGV).run

data/bin/rspec-ai-merge

@@ -0,0 +1,214 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Merge multiple RSpec AI formatter outputs from parallel test runs
+# Usage: rspec-ai-merge [options] file1.jsonl file2.jsonl ... > combined.jsonl
+
+require 'json'
+require 'optparse'
+
+# Merges multiple RSpec AI formatter JSONL outputs
+# Supports deduplication, sorting, and summary generation
+class RspecAiMerger
+  def initialize(args)
+    @files = []
+    @output = $stdout
+    @dedup = false
+    @sort = true
+    @summary = true
+    parse_options!(args)
+  end
+
+  def run
+    if @files.empty?
+      puts 'No input files specified. Use --help for usage.'
+      exit 1
+    end
+
+    missing = @files.reject { |f| File.exist?(f) }
+    unless missing.empty?
+      warn "Missing files: #{missing.join(', ')}"
+      exit 1
+    end
+
+    events = load_events
+    events = sort_events(events) if @sort
+    events = deduplicate(events) if @dedup
+
+    write_output(events)
+    write_summary(events) if @summary
+  end
+
+  private
+
+  def parse_options!(args)
+    parser = OptionParser.new do |opts|
+      opts.banner = 'Usage: rspec-ai-merge [options] file1.jsonl file2.jsonl ...'
+      opts.separator ''
+      opts.separator 'Merge multiple RSpec AI formatter outputs from parallel test runs'
+      opts.separator ''
+      opts.separator 'Options:'
+
+      opts.on('-o', '--output FILE', 'Output file (default: stdout)') do |f|
+        @output = File.open(f, 'w')
+      end
+
+      opts.on('-d', '--dedup', 'Deduplicate identical errors across files') do
+        @dedup = true
+      end
+
+      opts.on('--no-sort', 'Do not sort by timestamp') do
+        @sort = false
+      end
+
+      opts.on('--no-summary', 'Skip summary event') do
+        @summary = false
+      end
+
+      opts.on('-h', '--help', 'Show this help') do
+        puts opts
+        exit
+      end
+    end
+
+    parser.parse!(args)
+    @files = args
+  end
+
+  def load_events
+    events = []
+
+    @files.each do |file|
+      File.readlines(file).each do |line|
+        line = line.strip
+        next if line.empty?
+
+        begin
+          event = JSON.parse(line)
+          events << event
+        rescue JSON::ParserError
+          # Skip malformed lines
+          warn "Skipping malformed line in #{file}: #{line[0..50]}..."
+        end
+      end
+    end
+
+    events
+  end
+
+  def sort_events(events)
+    # Sort by timestamp if available, otherwise keep original order
+    events.sort_by do |e|
+      ts = e['ts']
+      if ts
+        # Parse ISO8601 timestamp
+        Time.parse(ts).to_f
+      else
+        0
+      end
+    rescue StandardError
+      0
+    end
+  end
+
+  def deduplicate(events)
+    signatures = {}
+    result = []
+
+    events.each do |event|
+      case event['t']
+      when 'test'
+        if event['s'] == 'fail' && event.dig('e', 'sig')
+          sig = event['e']['sig']
+          if signatures.key?(sig)
+            # Convert to dedup event
+            signatures[sig][:count] += 1
+            signatures[sig][:examples] << event['id']
+            result << {
+              't' => 'dedup',
+              'sig' => sig,
+              'id' => event['id'],
+              'n' => event['n'],
+              'first' => signatures[sig][:first],
+              'ts' => event['ts']
+            }
+          else
+            signatures[sig] = {
+              count: 1,
+              first: event['id'],
+              examples: [event['id']],
+              type: event.dig('e', 'type'),
+              msg: event.dig('e', 'msg')
+            }
+            result << event
+          end
+        else
+          result << event
+        end
+      when 'dedup'
+        # Already a dedup event, track it
+        sig = event['sig']
+        if signatures.key?(sig)
+          signatures[sig][:count] += 1
+          signatures[sig][:examples] << event['id']
+        end
+        result << event
+      when 'dedup_summary'
+        # Skip original dedup_summary, we'll generate a new one
+        next
+      else
+        result << event
+      end
+    end
+
+    # Add merged dedup summaries
+    signatures.each do |sig, data|
+      next if data[:count] <= 1
+
+      result << {
+        't' => 'dedup_summary',
+        'sig' => sig,
+        'type' => data[:type],
+        'msg' => data[:msg],
+        'count' => data[:count],
+        'first' => data[:first],
+        'examples' => data[:examples]
+      }
+    end
+
+    result
+  end
+
+  def write_output(events)
+    events.each do |event|
+      @output.puts(event.to_json)
+    end
+  end
+
+  def write_summary(events)
+    # Calculate totals from all 'done' events
+    dones = events.select { |e| e['t'] == 'done' }
+
+    return unless dones.any?
+
+    total_passed = dones.sum { |d| d['passed'] || 0 }
+    total_failed = dones.sum { |d| d['failed'] || 0 }
+    total_skipped = dones.sum { |d| d['skipped'] || 0 }
+    total_tests = dones.sum { |d| d['total'] || 0 }
+    total_time = dones.sum { |d| d['time'] || 0 }
+
+    # Remove original done events and add merged one
+    @output.puts({
+      't' => 'done',
+      'passed' => total_passed,
+      'failed' => total_failed,
+      'skipped' => total_skipped,
+      'total' => total_tests,
+      'time' => total_time,
+      'merged_from' => @files.length,
+      'ts' => Time.now.utc.iso8601(3)
+    }.to_json)
+  end
+end
+
+RspecAiMerger.new(ARGV).run

data/lib/rspec/ai_formatter/error_formatter.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RSpec
+  module AiFormatter
+    # Formats error details for output
+    module ErrorFormatter
+      def error_details(example, notification, log_path, sig = nil)
+        exception = notification.exception
+        return {} unless exception
+
+        details = {
+          type: error_class(exception),
+          msg: truncate(error_message(exception), 200),
+          loc: failure_location(example, exception)
+        }
+
+        details[:log] = log_path if log_path && @log_dir != File::NULL
+        details[:sig] = sig if sig
+
+        # Add diff for expectation failures
+        if exception.respond_to?(:expected) && exception.respond_to?(:actual)
+          details[:diff] = generate_diff(exception.expected, exception.actual)
+        end
+
+        details
+      end
+
+      def error_class(exception)
+        exception.class.name.split('::').last
+      rescue StandardError
+        'Error'
+      end
+
+      def error_message(exception)
+        msg = exception.message.to_s
+        # Clean up RSpec expectation messages
+        msg.gsub(/\e\[\d+m/, '') # Strip ANSI codes
+      rescue StandardError
+        'Unknown error'
+      end
+
+      def error_signature(exception)
+        # Create a hash of the error type + normalized message
+        # Useful for grouping similar failures
+        sig = "#{error_class(exception)}:#{error_message(exception)[0..50]}"
+        require 'digest'
+        Digest::MD5.hexdigest(sig)[0..7]
+      end
+
+      def failure_location(example, exception)
+        # Find the most relevant location in the test file
+        example_file = example.metadata[:file_path]
+
+        if exception.backtrace
+          # Find first line in the test file
+          test_line = exception.backtrace.find { |l| l.include?(example_file) }
+          return test_line.split(':')[0..1].join(':') if test_line
+        end
+
+        # Fallback to example location
+        "#{example_file}:#{example.metadata[:line_number]}"
+      end
+
+      def skip_reason(example)
+        result = example.execution_result
+        return nil unless result.respond_to?(:pending_message)
+
+        result.pending_message
+      end
+
+      private
+
+      def generate_diff(expected, actual)
+        # Simple diff generation
+        return nil if expected.nil? || actual.nil?
+
+        exp_str = inspect_value(expected)
+        act_str = inspect_value(actual)
+
+        return nil if exp_str == act_str
+
+        # Return truncated diff
+        {
+          expected: truncate(exp_str, 500),
+          actual: truncate(act_str, 500)
+        }
+      end
+
+      def inspect_value(value)
+        case value
+        when String
+          value
+        when Hash, Array
+          JSON.generate(value)
+        else
+          value.inspect
+        end
+      rescue StandardError
+        value.to_s
+      end
+    end
+  end
+end

data/lib/rspec/ai_formatter/formatter.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'time'
+require_relative 'log_writer'
+require_relative 'error_formatter'
+require_relative 'location_helper'
+require_relative 'output_helper'
+
+module RSpec
+  module AiFormatter
+    # AI-friendly formatter for RSpec
+    # Outputs compact NDJSON with references to detailed logs
+    class Formatter
+      include LogWriter
+      include ErrorFormatter
+      include LocationHelper
+      include OutputHelper
+
+      RSpec::Core::Formatters.register self,
+                                       :start,
+                                       :example_started,
+                                       :example_passed,
+                                       :example_failed,
+                                       :example_pending,
+                                       :dump_summary
+
+      def initialize(output, log_dir: nil)
+        @output = output
+        @log_dir = log_dir || ENV.fetch('RSPEC_AI_LOGS', 'tmp/rspec_logs')
+        @start_time = nil
+        @suite_start = nil
+        @failure_count = 0
+        @pending_count = 0
+        @passed_count = 0
+        @test_index = []
+        @deduplicate = ENV['RSPEC_AI_DEDUP'] == '1'
+        @minimal = ENV['RSPEC_AI_FULL'] != '1'
+        @error_signatures = {}
+      end
+
+      def start(notification)
+        @suite_start = Time.now
+
+        setup_log_directory
+
+        emit(
+          t: 'start',
+          total: notification.count,
+          ts: timestamp
+        )
+      end
+
+      def example_started(notification); end
+
+      def example_passed(notification)
+        @passed_count += 1
+        return if @minimal
+
+        ex = notification.example
+        emit(
+          t: 'test',
+          id: test_location(ex),
+          n: short_name(ex),
+          s: 'pass',
+          time: execution_time_ms(ex),
+          ts: timestamp
+        )
+      end
+
+      def example_failed(notification)
+        @failure_count += 1
+        ex = notification.example
+        exception = notification.exception
+        log_path = write_failure_log(ex, notification)
+
+        # Calculate signature for deduplication
+        sig = error_signature(exception) if @deduplicate || ENV['RSPEC_AI_SIGNATURES'] == '1'
+
+        if @deduplicate && sig && @error_signatures.key?(sig)
+          handle_duplicate_error(ex, sig)
+        else
+          handle_first_error(ex, notification, log_path, sig)
+        end
+      end
+
+      def example_pending(notification)
+        @pending_count += 1
+        ex = notification.example
+        reason = skip_reason(ex)
+
+        if @minimal
+          emit_minimal_test(ex, 'skip', skip: reason)
+        else
+          emit(
+            t: 'test',
+            id: test_location(ex),
+            n: short_name(ex),
+            s: 'skip',
+            time: execution_time_ms(ex),
+            skip: reason,
+            ts: timestamp
+          )
+        end
+      end
+
+      def dump_summary(notification)
+        total_time = ((Time.now - @suite_start) * 1000).round
+
+        emit_dedup_summaries if @deduplicate && duplicates_exist?
+
+        emit_summary(total_time, notification)
+        write_index_file
+      end
+
+      private
+
+      def handle_duplicate_error(example, sig)
+        @error_signatures[sig][:count] += 1
+        @error_signatures[sig][:examples] << test_location(example)
+
+        emit(
+          t: 'dedup',
+          sig: sig,
+          id: test_location(example),
+          n: short_name(example),
+          first: @error_signatures[sig][:first],
+          ts: timestamp
+        )
+      end
+
+      def handle_first_error(example, notification, log_path, sig)
+        # First occurrence of this error
+        if @deduplicate && sig
+          @error_signatures[sig] = {
+            count: 1,
+            first: test_location(example),
+            examples: [test_location(example)],
+            type: error_class(notification.exception),
+            msg: truncate(error_message(notification.exception), 100)
+          }
+        end
+
+        emit(
+          t: 'test',
+          id: test_location(example),
+          n: short_name(example),
+          s: 'fail',
+          time: execution_time_ms(example),
+          e: error_details(example, notification, log_path, sig),
+          ts: timestamp
+        )
+      end
+
+      def duplicates_exist?
+        @error_signatures.any? { |_, v| v[:count] > 1 }
+      end
+
+      def emit_dedup_summaries
+        @error_signatures.each do |sig, data|
+          next if data[:count] <= 1
+
+          emit(build_dedup_summary(sig, data))
+        end
+      end
+
+      def build_dedup_summary(sig, data)
+        if @minimal
+          { t: 'dedup_summary', sig: sig, count: data[:count], first: data[:first] }
+        else
+          {
+            t: 'dedup_summary',
+            sig: sig,
+            type: data[:type],
+            msg: data[:msg],
+            count: data[:count],
+            first: data[:first],
+            examples: data[:examples],
+            ts: timestamp
+          }
+        end
+      end
+
+      def emit_summary(total_time, notification)
+        summary = {
+          t: 'done',
+          passed: @passed_count,
+          failed: @failure_count,
+          skipped: @pending_count,
+          total: notification.example_count,
+          time: total_time
+        }
+        summary[:ts] = timestamp unless @minimal
+        emit(summary)
+      end
+    end
+  end
+end
+
+# Register with RSpec
+if defined?(RSpec::Core::Formatters)
+  RSpec::Core::Formatters.register(
+    RSpec::AiFormatter::Formatter,
+    :start,
+    :example_started,
+    :example_passed,
+    :example_failed,
+    :example_pending,
+    :dump_summary
+  )
+end

data/lib/rspec/ai_formatter/location_helper.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RSpec
+  module AiFormatter
+    # Handles location and naming for test examples
+    module LocationHelper
+      def test_location(example)
+        meta = example.metadata
+        file = meta[:file_path]
+        line = meta[:line_number]
+        # Try to get end line from source location
+        end_line = detect_end_line(example)
+
+        if end_line && end_line > line
+          "#{file}:#{line}-#{end_line}"
+        else
+          "#{file}:#{line}"
+        end
+      end
+
+      def minimal_location(example)
+        # Minimal format: no ./ prefix, no end line, just file:start_line
+        meta = example.metadata
+        file = meta[:file_path].to_s.sub(%r{^\./}, '')
+        line = meta[:line_number]
+        "#{file}:#{line}"
+      end
+
+      def short_name(example)
+        # Build hierarchical name from example groups
+        parts = example_groups(example).map(&:description)
+        parts << example.description
+
+        # Compact: skip empty descriptions, limit length
+        parts.reject(&:empty?).join(' > ').slice(0, 200)
+      end
+
+      private
+
+      def detect_end_line(example)
+        # Get block source location end if available
+        block = example.metadata[:block]
+        return nil unless block.respond_to?(:source_location)
+
+        loc = block.source_location
+        return nil unless loc.is_a?(Array) && loc.length >= 2
+
+        # Try to get end location from proc/method
+        if block.respond_to?(:source_location_end)
+          block.source_location_end&.last
+        else
+          # Fallback: estimate based on next example or simple heuristic
+          line = loc.last
+          # Rough estimate: typical test is 5-15 lines
+          line + 10
+        end
+      rescue StandardError
+        nil
+      end
+
+      def example_groups(example, groups = [])
+        group = example.example_group
+        while group && group != RSpec::Core::ExampleGroup
+          groups.unshift(group) unless group.description.empty?
+          group = group.superclass
+          break if group == RSpec::Core::ExampleGroup
+        end
+        groups
+      end
+    end
+  end
+end

data/lib/rspec/ai_formatter/log_writer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RSpec
+  module AiFormatter
+    # Handles writing failure logs to disk
+    module LogWriter
+      def write_failure_log(example, notification)
+        return nil if @log_dir == File::NULL
+
+        file = example.metadata[:file_path]
+        line = example.metadata[:line_number]
+        filename = "#{File.basename(file, '.rb')}_#{line}.log"
+        log_path = File.join(@log_dir, filename)
+
+        File.open(log_path, 'w') { |f| write_log_content(f, example, notification) }
+
+        @test_index << {
+          test: short_name(example),
+          location: "#{file}:#{line}",
+          log: log_path,
+          status: 'fail'
+        }
+
+        log_path
+      end
+
+      def write_index_file
+        return if @log_dir == File::NULL || @test_index.empty?
+
+        index_path = File.join(@log_dir, 'index.json')
+        File.write(index_path, JSON.pretty_generate(@test_index))
+      end
+
+      def setup_log_directory
+        return if @log_dir == File::NULL || @log_dir.nil?
+
+        FileUtils.mkdir_p(@log_dir)
+        return unless ENV['RSPEC_AI_CLEAN'] == '1'
+
+        FileUtils.rm_rf(Dir.glob(File.join(@log_dir, '*.log')))
+      end
+
+      private
+
+      def write_log_content(file, example, notification)
+        file.puts('=' * 80)
+        file.puts("TEST: #{short_name(example)}")
+        file.puts("LOCATION: #{example.metadata[:file_path]}:#{example.metadata[:line_number]}")
+        file.puts('STATUS: FAIL')
+        file.puts("TIME: #{execution_time_ms(example)}ms")
+        file.puts('=' * 80)
+        file.puts
+
+        write_exception_details(file, notification.exception)
+        file.puts
+        file.puts('=' * 80)
+        file.puts('FULL OUTPUT:')
+        file.puts('=' * 80)
+
+        return unless notification.respond_to?(:formatted_backtrace)
+
+        file.puts(notification.formatted_backtrace.join("\n"))
+      end
+
+      def write_exception_details(file, exception)
+        return unless exception
+
+        file.puts("ERROR: #{error_class(exception)}")
+        file.puts('MESSAGE:')
+        file.puts(error_message(exception))
+        file.puts
+
+        return unless exception.respond_to?(:expected) && exception.respond_to?(:actual)
+
+        file.puts('EXPECTED:')
+        file.puts(inspect_value(exception.expected))
+        file.puts
+        file.puts('ACTUAL:')
+        file.puts(inspect_value(exception.actual))
+        file.puts
+
+        file.puts('BACKTRACE:')
+        exception.backtrace&.first(20)&.each { |l| file.puts(l) }
+      end
+    end
+  end
+end

data/lib/rspec/ai_formatter/output_helper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RSpec
+  module AiFormatter
+    # Handles output formatting and utility methods
+    module OutputHelper
+      def emit(hash)
+        @output.puts(hash.to_json)
+      end
+
+      def emit_minimal_test(example, status, skip: nil)
+        hash = {
+          t: 'test',
+          id: minimal_location(example),
+          s: status
+        }
+        hash[:skip] = skip if skip
+        emit(hash)
+      end
+
+      def execution_time_ms(example)
+        result = example.execution_result
+        return nil unless result.respond_to?(:run_time)
+
+        (result.run_time * 1000).round
+      end
+
+      def timestamp
+        Time.now.utc.iso8601(3)
+      end
+
+      def truncate(str, max)
+        str = str.to_s
+        return str if str.length <= max
+
+        "#{str[0...max]}...[truncated #{str.length - max} chars]"
+      end
+    end
+  end
+end

data/lib/rspec/ai_formatter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'ai_formatter/formatter'
+
+module RSpec
+  module AiFormatter
+    VERSION = '0.1.0'
+
+    class Error < StandardError; end
+  end
+end

data/lib/rspec_ai_formatter.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ai_formatter'

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: rspec-ai-formatter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SK
+autorequire: rspec_ai_formatter
+bindir: bin
+cert_chain: []
+date: 2026-02-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+description: |
+  RSpec formatter optimized for AI agents and CI systems.
+  Outputs compact NDJSON with file references instead of verbose text.
+  Supports log splitting, error deduplication, and context-efficient reporting.
+email:
+- konstantin.suhov@gmail.com
+executables:
+- rspec-ai
+- rspec-ai-merge
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/rspec-ai
+- bin/rspec-ai-merge
+- lib/rspec/ai_formatter.rb
+- lib/rspec/ai_formatter/error_formatter.rb
+- lib/rspec/ai_formatter/formatter.rb
+- lib/rspec/ai_formatter/location_helper.rb
+- lib/rspec/ai_formatter/log_writer.rb
+- lib/rspec/ai_formatter/output_helper.rb
+- lib/rspec_ai_formatter.rb
+homepage: https://github.com/sciencejet/rspec-ai-formatter
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: AI-friendly RSpec formatter with minimal token usage
+test_files: []