specguard-ruby 0.3.4 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43e3d2ff78fc5e1750d77197ff2ef15c9815040147c4e52c51dd71855261b5c1
-  data.tar.gz: e55c3f9bdcaa0a21f60fb8654ee8848a55c06b6ceb282ac523390dfbec07f12d
+  metadata.gz: a0b4156ddf8b2beed6ac009599c80e2be04d0ce213c44bd020bcf58c7bbb5bca
+  data.tar.gz: 21c4cad8aa165736d247e3092bb22480d3502525cb89d5e7e183f1bf69db69f2
 SHA512:
-  metadata.gz: e5603b3d5deaa9e5a8119c469a8a142f4bb9527b231866e4a3c57d7face3319fb70ece91d19c81f8cb9094d48363d887ab81175e2c9897148f730c8ac72ef4b5
-  data.tar.gz: e5a67e10d778c961e4cb8edf743db91861cbf350e15ff305370ad42d102e4d28aaf25c591617c47c73d090a77d18b3faf6cb529dd8570f18245e38402168e123
+  metadata.gz: 938b3a7dd2a6f20d75a1493346668ce07236a4db6e0d867d35166dc42c9efe1e76581550793ab475ca21c14ae0006cb5668f2755174f10c00c49de108a90ea63
+  data.tar.gz: 0b00056261a247ac2f3c31484a918fb371cc4abb05c2f0a2c2b932148633a1a57b3fa487a6d95d150e25066e23ca5952fcc575a6aaa03059224c3092b8b740e1

data/README.md

@@ -33,7 +33,9 @@ The plugin rides alongside Minitest's own reporters (the suite's output is uncha
 envelope per process with the same field names the RSpec formatter sends, and never fails the run:
 a refused or unreachable delivery costs one line on stderr and a line in the local sink. Without
 `SPECGUARD_API_KEY` nothing is sent — the run is appended to the local development record, exactly
-as the RSpec formatter behaves. For a deterministic CI attachment where plugin discovery must not
+as the RSpec formatter behaves. Parameterized tests — the `define_method("test_x_#{param}")` loop
+idiom — ship one row per instance, not one row per definition site, so each instance's outcome and
+duration are tracked on their own. For a deterministic CI attachment where plugin discovery must not
 be assumed, require it explicitly before the run:
 
 ```bash

data/lib/specguard/minitest/reporter.rb

@@ -10,6 +10,17 @@ require "fileutils"
 # minitest-only consumer's machine.
 require_relative "../rspec/configuration"
 
+# The annotation lookup is the third framework-free half: what counts as a
+# test's annotation is a property of the source line, not of the framework
+# that ran it, so the Minitest reporter asks the same {AnnotationLookup} the
+# RSpec formatter does rather than carrying a second extractor (whose header
+# already warns that a second extractor guarantees scanner and reporter
+# eventually disagree about what an annotation is). Requiring it pulls the
+# linter's chain — the same direction-safe require the formatter itself makes;
+# `specguard/rspec` does not require `rspec/core`, so a minitest-only machine
+# stays loadable.
+require_relative "../rspec/annotation_lookup"
+
 # The Minitest half of `specguard-ruby`. Everything the RSpec formatter knows
 # about the platform — the envelope's field names, the transport's
 # never-raise contract, the switch that a missing key is — is framework-free
@@ -18,7 +29,10 @@ require_relative "../rspec/configuration"
 # ship first, neither containing any RSpec). This adapter contributes only the
 # part that is genuinely Minitest's: turning `Minitest::Result` objects into
 # the same row shape the RSpec formatter emits, at the moment Minitest hands
-# them to a reporter.
+# them to a reporter — and attaching each test's annotation the same way the
+# formatter does, through the shared {SpecGuard::RSpec::AnnotationLookup} and
+# its one-line lookback (SPGD-12 §2), so a Minitest row carries the same
+# `status` / `intent` pair a RSpec row does.
 #
 # It is a duck-typed Minitest reporter (`start` / `record` / `report` /
 # `passed?`) rather than a subclass of `Minitest::AbstractReporter`, because
@@ -36,6 +50,12 @@ require_relative "../rspec/configuration"
 module SpecGuard
   module Minitest
     class Reporter
+      # `Ingest::Payload::STATUSES`, restated — the same call the RSpec
+      # formatter makes. The platform validates every row against this pair,
+      # so they are the contract and not a local naming choice.
+      STATUS_ANNOTATED = "annotated"
+      STATUS_UNANNOTATED = "unannotated"
+
       # Rows with no usable location are dropped rather than mangled: a row
       # whose file cannot be named fits no by-file aggregate on the platform
       # and would surface as noise. The RSpec formatter's `capture` makes the
@@ -49,14 +69,23 @@ module SpecGuard
         end
       end
 
+      # Internal, never on the wire: `record` stashes the result's own method
+      # name under this key so `uniquify_ids!` can re-identify colliding rows
+      # at delivery time, and `uniquify_ids!` strips it again before the
+      # payload is built. The underscore prefix exists so a leak onto the
+      # wire would be loud in any payload diff rather than plausible.
+      RESULT_NAME_KEY = "_specguard_result_name"
+
       def initialize(configuration: SpecGuard::RSpec.configuration,
                      transport: nil, output: $stderr,
+                     annotations: SpecGuard::RSpec::AnnotationLookup.new,
                      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
         @configuration = configuration
         # Injected for the specs; the real thing is built the same way the
         # RSpec formatter builds it, from the same configuration object.
         @transport = transport
         @output = output
+        @annotations = annotations
         @clock = clock
         @rows = []
         @started_at = nil
@@ -82,7 +111,12 @@ module SpecGuard
       # exit code.
       def record(result)
         row = row_for(result)
-        @rows << row if row
+        return unless row
+
+        # Stashed for `uniquify_ids!` (and stripped there) — the one
+        # unique-per-result token a Minitest row has. See that method.
+        row[RESULT_NAME_KEY] = result.name.to_s
+        @rows << row
       rescue ScriptError, StandardError
         nil
       end
@@ -93,6 +127,7 @@ module SpecGuard
       def report
         return if @rows.empty?
 
+        uniquify_ids!
         deliver(payload)
       rescue ScriptError, StandardError => e
         warn_once("could not ship test telemetry (#{e.class}: #{e.message}). The test run is unaffected.")
@@ -107,6 +142,35 @@ module SpecGuard
 
       private
 
+      # The definition site is NOT unique per result for a generated test:
+      # `define_method("test_x_#{param}")` in a loop (or any
+      # generate_tests-style helper) stamps every instance with the SAME
+      # `source_location` — the define_method call site — so N results share
+      # one id, and the platform's ingest upserts
+      # `unique_by %i[test_run_id example_id]` silently drops every repeat
+      # but the first, taking each dropped row's outcome and duration with
+      # it. `@rows` is complete here — every `record` has returned, and
+      # parallel mode records from its worker threads through this one shared
+      # reporter — so the collision is detectable exactly once, at delivery.
+      # Every member of a colliding group is re-identified as
+      # `"#{file}:#{line}##{method_name}"`: a method name is unique per
+      # class and deterministic, so the suffixed ids are stable across runs.
+      # ALL members take the suffix, never just later arrivals — parallel
+      # mode's arrival order is fork scheduling, so "the first row keeps the
+      # bare id" would make identity depend on it. Rows whose id no other
+      # row claims — every plain `def test_` suite among them — keep the id
+      # they always had, byte for byte.
+      def uniquify_ids!
+        counts = Hash.new(0)
+        @rows.each { |row| counts[row["id"]] += 1 }
+        @rows.each do |row|
+          name = row.delete(RESULT_NAME_KEY)
+          next unless counts[row["id"]] > 1 && !name.to_s.empty?
+
+          row["id"] = "#{row["id"]}##{name}"
+        end
+      end
+
       # The envelope, in the platform's own field names (`Ingest::Payload`:
       # commit_sha / branch / ci_run_id / duration_seconds / specs) — the same
       # rule the RSpec formatter states at its `#payload`: this gem's settings
@@ -175,15 +239,22 @@ module SpecGuard
 
         file = relative_path(file)
         name = "#{result.klass}##{result.name}"
+        line_number = line&.to_i
+        intent = annotation_for(file, line_number)
         {
           # Minitest has no RSpec-style rerun path or nested ids, so the
-          # definition site is the identity: stable across runs (which is
-          # what the platform's per-test identity needs) and unique per
-          # definition (which is what a row needs).
+          # definition site is the row's id — the run-local primary key for
+          # this one delivered payload, never a cross-run stable identity
+          # (cross-run matching remains name + file, the platform's own
+          # rule). A definition site is NOT unique per result:
+          # `define_method`-generated tests stamp every instance with the
+          # same location, so rows can collide on this id within a run, and
+          # `uniquify_ids!` is what re-identifies those rows at delivery
+          # time. Nothing here promises uniqueness it does not have.
           "id" => "#{file}:#{line}",
           "spec_file_path" => file,
           "file_path" => file,
-          "line_number" => line&.to_i,
+          "line_number" => line_number,
           "name" => name,
           "duration" => result.time,
           # The platform's three outcomes, mapped from Minitest's questions:
@@ -192,10 +263,37 @@ module SpecGuard
           # Minitest distinguishes assertion failures from exceptions, the
           # wire contract does not, and inventing a fourth outcome here would
           # be a lie the schema refuses.
-          "outcome" => outcome_for(result)
+          "outcome" => outcome_for(result),
+          # The RSpec formatter's rationale, restated: the key is written
+          # explicitly because a present key says "we looked", where an absent
+          # key is indistinguishable from "this producer does not report
+          # annotations" — and without it the platform refuses the whole run
+          # (`Ingest::Payload` requires `status` on EVERY row). `intent` is
+          # likewise explicit: null when unannotated, which is exactly what
+          # the platform demands of an unannotated row.
+          "status" => intent.nil? ? STATUS_UNANNOTATED : STATUS_ANNOTATED,
+          "intent" => intent
         }
       end
 
+      # The lookup, inside its own envelope. `record`'s rescue would drop the
+      # whole row — example, duration, outcome and all — to learn one row's
+      # annotation, which is the trade the RSpec formatter already refused:
+      # its annotation lookup runs inside a nested guard so a blow-up costs
+      # the row only its annotation. The lookup degrades verdicts it could
+      # not reach to nil itself (an unusable validator ships unannotated by
+      # design); this envelope is for what escapes it anyway — file reads the
+      # lookup does not expect, encoding faults, anything else — and it
+      # routes through {#warn_once}, so the operator hears about it exactly
+      # once however many rows are affected.
+      def annotation_for(file, line)
+        @annotations.intent_for(file: file, line: line)
+      rescue ScriptError, StandardError => e
+        warn_once("could not resolve annotations (#{e.class}: #{e.message}). " \
+                  "Rows continue unannotated. The test run is unaffected.")
+        nil
+      end
+
       def outcome_for(result)
         return "pending" if result.skipped?
         return "failed" unless result.passed?

data/lib/specguard/rspec/cli.rb

@@ -244,25 +244,28 @@ module SpecGuard
       def empty_reason(selection)
         case selection.mode
         when :changed then changed_empty_reason(selection)
-        else "no *_spec.rb found under #{Dir.pwd}"
+        else "no *_spec.rb or *_test.rb file found under #{Dir.pwd}"
         end
       end
 
       # Names the filter that actually emptied the selection. Saying "nothing in
-      # the diff matched *_spec.rb" when a spec file demonstrably changed —
+      # the diff matched" when a test file demonstrably changed —
       # just not under this directory — is worse than saying nothing: it reads
-      # as a conclusion and stops the reader looking.
+      # as a conclusion and stops the reader looking. Both naming conventions
+      # are named because either would have been selected; a Minitest-only
+      # repository must not be told the silence is about `*_spec.rb` files it
+      # does not have.
       def changed_empty_reason(selection)
         stats = selection.stats
         base = selection.base
 
-        return "nothing in the diff against #{base} matched *_spec.rb" if stats.nil?
+        return "nothing in the diff against #{base} matched a *_spec.rb or *_test.rb file" if stats.nil?
 
         if stats.changed.zero?
           "nothing changed against #{base}"
         elsif stats.spec_matches.zero?
           "#{stats.changed} file#{'s' unless stats.changed == 1} changed against #{base}, " \
-            "none matching *_spec.rb"
+            "none matching *_spec.rb or *_test.rb"
         else
           changed_excluded_reason(stats, base)
         end

data/lib/specguard/rspec/file_selector.rb

@@ -6,8 +6,15 @@ module SpecGuard
   module RSpec
     # Chooses which spec files the linter reads.
     #
-    # Two modes: every `*_spec.rb` under the working directory (the default), or
-    # only those in the current diff (`--changed`).
+    # Two modes: every Ruby test file under the working directory (the
+    # default), or only those in the current diff (`--changed`). Both modes
+    # recognize the two Ruby test-framework naming conventions — RSpec's
+    # `*_spec.rb` and Minitest's `*_test.rb` — so a suite is visible to the
+    # linter whichever framework wrote it. The default walk scopes Minitest
+    # files to `test/` (the directory both Rails and `minitest` own as the
+    # convention), while `--changed` filters on the file-name suffix alone: a
+    # diff names paths, not directories, and a changed test file is a test
+    # file wherever the author put it.
     #
     # == Why `--changed` is not `git diff --name-only`
     #
@@ -41,9 +48,10 @@ module SpecGuard
     # found no annotations" from "checked 0 files" — {Selection} carries the
     # count, the emptiness, and {Stats} explaining *which* filter emptied it, so
     # the CLI can say so on stderr, accurately. A confidently wrong reason is
-    # worse than a quiet one: a human who reads "nothing in the diff matched
-    # *_spec.rb" stops looking. The exit code is not the lever: the spec fixes 0
-    # for "no annotations".
+    # worse than a quiet one: a human who reads "nothing in the diff matched a
+    # test file" stops looking — and on a Minitest-only repository the silence
+    # must not be explained in RSpec vocabulary the tree does not use. The exit
+    # code is not the lever: the spec fixes 0 for "no annotations".
     #
     # == Scope: `--changed` selects changed specs **under `root`**
     #
@@ -74,7 +82,20 @@ module SpecGuard
     # clean checkout of a commit) that cannot arise; locally the loud empty
     # selection is what surfaces it.
     module FileSelector
-      DEFAULT_GLOB = "**/*_spec.rb"
+      # `test/**/*_test.rb` rather than `**/*_test.rb`: the `test/` directory
+      # is where both Rails and Minitest itself put Minitest files, and
+      # keeping the second convention scoped stops the walk from adopting
+      # unrelated `*_test.rb` files elsewhere in the tree (fixture generators,
+      # vendored code). `*_spec.rb` stays unscoped because `spec/` already has
+      # no competitor convention to fence against.
+      DEFAULT_GLOB = ["**/*_spec.rb", "test/**/*_test.rb"].freeze
+
+      # The `--changed` counterparts of {DEFAULT_GLOB}: git hands back paths,
+      # so the filter is a match over the whole path rather than a glob walk,
+      # and the suffix alone decides. Deliberately not directory-scoped — a
+      # changed Minitest file outside `test/` is still this client's business
+      # in the one mode that answers "what did this branch touch".
+      CHANGED_PATTERNS = ["*_spec.rb", "*_test.rb"].freeze
 
       # Ordered probes for the default branch when no explicit base is given.
       DEFAULT_BRANCH_REFS = %w[origin/HEAD origin/main origin/master main master].freeze
@@ -116,8 +137,9 @@ module SpecGuard
         changed ? select_changed(base: base, root: root) : select_all(root: root)
       end
 
-      # Every `*_spec.rb` under `root`, recursively. Hidden directories are not
-      # traversed (no `File::FNM_DOTMATCH`), so `.git` and friends are skipped.
+      # Every test file under `root`, recursively, in either naming
+      # convention. Hidden directories are not traversed (no
+      # `File::FNM_DOTMATCH`), so `.git` and friends are skipped.
       def select_all(root: Dir.pwd)
         files = Dir.glob(DEFAULT_GLOB, base: root).select { |f| File.file?(File.join(root, f)) }.sort
         Selection.new(files: files, mode: :all)
@@ -146,7 +168,7 @@ module SpecGuard
       # @return [[Array<String>, Stats]]
       def changed_files(base, root)
         names = diff_names(base, root)
-        specs = names.select { |name| File.fnmatch?("*_spec.rb", name) }
+        specs = names.select { |name| CHANGED_PATTERNS.any? { |pattern| File.fnmatch?(pattern, name) } }
 
         top = toplevel(root)
         prefix = directory_prefix(top.empty? ? root : top)

data/lib/specguard/version.rb

@@ -7,5 +7,5 @@
 # framework-scoped version constant a lie, so the number moved here and the
 # rspec module now points at it for back-compat.
 module SpecGuard
-  VERSION = "0.3.4"
+  VERSION = "0.3.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: specguard-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.6
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-31 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json