specguard-ruby 0.3.3 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d91e0fec640df334c1ee281f06852adb53172514aa6bc357346d0ba76c725fe
-  data.tar.gz: c2f3974d36260c4cdf33296e85f3a44879be617122ce3291a17538d2d7e4e68f
+  metadata.gz: 9a82ff31aaa51455637e6500a2f4cebda11b50dad52947bd36ce535ada84bc1b
+  data.tar.gz: 658887600bd0fec337a1d7ddd372b3c481fa761c95ff3c92c25f12fc6e0fcf91
 SHA512:
-  metadata.gz: '019c9e92094afec846e8184c39ce185c47eb564b6cd4b6ec9ed2198e1876865b02efd8b198ac2d161629840a8b188991fc4fd347265bc47b5a67b513d4498a60'
-  data.tar.gz: 411ea2d03fa8be62ec65f54a1341cd6ca8926dfdf481618b86d4551c111d84312efcc3d9dacfabe015bf9dee254a956e468137f6a4bef6468635302d673e4266
+  metadata.gz: 88589ddb1374aa792be0199049b7bb204b6479850831db80340344f4d624db96dc9b7c1c345d6c95c24bbb6728b4e711ab7a338899a7a815c09e6eb53f47c4b2
+  data.tar.gz: e11192524e6f248aa16d42c522664863a84894b85987f07ef5f54e5b9c2439bdb6146b0f3c693196d0fcc627f85923f24c5655ed330a9809926f1519802e1e0f

data/README.md

@@ -43,8 +43,9 @@ bundle exec ruby -rminitest/specguard_plugin -e 'Minitest.extensions << "specgua
 ## The linter — `specguard-lint`
 
 Validates `# @intent:` annotations in changed (or all) `*_spec.rb` files against the OpenTestIntent
-JSON Schema. Exits `1` on a malformed annotation; **never** fails on a *missing* one (adoption is
-opt-in and gradual).
+JSON Schema. Exits `1` on a malformed annotation — or a well-formed but unreachable one (stacked
+above another comment-form `@intent:` line, so the one-line lookback never claims it) — and
+**never** fails on a *missing* one (adoption is opt-in and gradual).
 
 ```bash
 bundle exec specguard-lint --changed   # CI mode: only files in the current diff
@@ -278,7 +279,9 @@ the `read` kind. The binary's own UTF-8 refusal prose (`input is not well-formed
 
 Every way the backend can fail — the binary is missing, will not execute, exits with something that
 is not a verdict, or emits output that is not a report — is **exit 2**, the linter's "could not do
-my job" code. It never becomes exit 1, which means "an annotation is malformed" and nothing else.
+my job" code. It never becomes exit 1, which means "an annotation is malformed" — or well-formed
+but unreachable: stacked above another comment-form `@intent:` line, so the one-line lookback
+never claims it — and nothing else.
 
 ## The formatter — `SpecGuard::RSpecFormatter`
 

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
@@ -51,12 +71,14 @@ module SpecGuard
 
       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
@@ -175,6 +197,8 @@ 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
@@ -183,7 +207,7 @@ module SpecGuard
           "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 +216,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

@@ -9,7 +9,7 @@ module SpecGuard
     # == The contract, and the reason it needs defending
     #
     #   0  every annotation checked is valid (including "there were none")
-    #   1  at least one annotation is malformed
+    #   1  at least one annotation is malformed or unreachable
     #   2  the linter could not do its job — misuse, or the tool itself broken
     #
     # Ruby does not give you this for free; it actively works against it.
@@ -102,9 +102,11 @@ module SpecGuard
       # Every annotation checked was valid — or there were none to check.
       # "Lint, don't require": a missing annotation is never an error.
       EXIT_OK = 0
-      # One or more annotations are malformed. The only code produced by
-      # inspecting content, and the only path that reaches it is a failed
-      # {Linter::Result}.
+      # One or more annotations are malformed — or well-formed but
+      # unreachable (SPGD-900: stacked above another comment-form `@intent:`
+      # line, so the one-line lookback never claims it, a dead contract that
+      # is still a failure). The only code produced by inspecting content,
+      # and the only path that reaches it is a failed {Linter::Result}.
       EXIT_MALFORMED = 1
       # The linter could not do its job: bad flags, `--changed` outside a git
       # repository, a validator that could not be resolved, or an unexpected
@@ -140,6 +142,14 @@ module SpecGuard
 
         results = backend.check(selection.files)
 
+        # The structural pass (SPGD-900): annotations that are valid in
+        # isolation but can never be extracted — stacked consecutive
+        # comment-form `@intent:` lines, where the one-line lookback
+        # (SPGD-12 §2) claims only the line just above the example. These are
+        # Linter::Results like any other, so both renderers and the exit code
+        # pick them up with no second path to keep in step.
+        results += unreachable_results(selection.files)
+
         # Computed once, here, and handed to whichever renderer runs. `--json`
         # is a second renderer over this list, not a second code path: the exit
         # code below is the same expression it always was, and the document's
@@ -162,6 +172,19 @@ module SpecGuard
 
       private
 
+      # {Scanner}'s structural findings are annotations, not file problems:
+      # each carries a real `file:line`, so they become failing line-scoped
+      # {Linter::Result}s exactly like a malformed payload would. A file the
+      # backend could not read contributes nothing here — the backend's own
+      # KIND_READ result already reports it, and this pass cannot be positional
+      # about a file it never saw.
+      def unreachable_results(paths)
+        Scanner.unreachable_findings(paths).map do |finding|
+          Linter::Result.new(file: finding.file, line: finding.line,
+                             kind: finding.kind, problem: finding.problem)
+        end
+      end
+
       # One line per run naming the implementation that produced the verdicts.
       # Since the SPGD-867 cutover there is exactly one implementation — the
       # resolved `validate-intent` binary — and the line says which one,
@@ -221,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/rspec/finding.rb

@@ -48,6 +48,17 @@ module SpecGuard
       # of ways an annotation can fail is written down in one place.
       KIND_SCHEMA = :schema
 
+      # The annotation is well-formed in isolation but can never be EXTRACTED:
+      # it is a comment-form `@intent:` on a line whose next line is also a
+      # comment-form `@intent:`, so the one-line lookback (SPGD-12 §2 —
+      # {AnnotationLookup} claims only the comment on the line immediately
+      # above an example) always skips it in favour of the lower line. The
+      # contract is dead metadata: counted by the linter, discarded by
+      # extraction. Produced by {Scanner}'s structural pass, not by
+      # {AnnotationScanner} — each annotation is scanned in isolation there,
+      # which is exactly why this defect is invisible to it.
+      KIND_UNREACHABLE = :unreachable
+
       def initialize(file:, line:, intent: nil, problem: nil, kind: nil)
         super
       end

data/lib/specguard/rspec/linter.rb

@@ -19,7 +19,8 @@ module SpecGuard
     #
     # == What counts as a failure
     #
-    # Three things reach the same verdict from different directions:
+    # Three things make an annotation malformed, reaching the same verdict
+    # from different directions:
     #
     #   * the payload could not be captured off the line at all
     #     (`Finding::KIND_EXTRACTION`) — a typo'd annotation;
@@ -35,6 +36,14 @@ module SpecGuard
     # valid UTF-8 — is also reported as a failure, and therefore also exits 1.
     # That matches `validate-intent`, which classifies it separately (its own
     # `read` kind) and still reports it as `FAIL` with exit 1.
+    #
+    # `Finding::KIND_UNREACHABLE` — an annotation that is well-formed in
+    # isolation but stacked above another comment-form `@intent:` line, so
+    # the one-line lookback (SPGD-12 §2) never claims it — is also reported
+    # as a failure, and therefore also exits 1. Nothing about it is
+    # malformed; the contract is dead metadata, counted by the linter and
+    # discarded by extraction, and the structural pass that flags it
+    # (SPGD-900) reports it loudly rather than letting it pass as clean.
     module Linter
       # One annotation's verdict. `problem` is set when discovery could not
       # produce an intent at all; `reasons` when the schema rejected one.

data/lib/specguard/rspec/scanner.rb

@@ -230,6 +230,107 @@ module SpecGuard
         Finding.new(file: file, line: line, kind: Finding::KIND_PARSE,
                     problem: "could not parse annotation: #{e.message}")
       end
+
+      # == The structural pass: annotations the extraction can never claim
+      #
+      # Everything above validates each annotation IN ISOLATION — one payload,
+      # one verdict. But the formatter's extraction contract
+      # ({AnnotationLookup}, SPGD-12 §2) is positional: only the comment-form
+      # annotation on the line IMMEDIATELY ABOVE an example is inheritable.
+      # So when two consecutive comment-form `@intent:` lines sit above one
+      # `it`, the UPPER line is unreachable — silently discarded by the
+      # one-line lookback — while this pipeline counts it as a valid
+      # annotation and the run exits 0. Measured (SPGD-897 audit): 16 such
+      # stacked pairs shipped through `specguard-lint` exit 0, every upper
+      # contract dead. Reported loudly, not skipped — the same stance
+      # {AnnotationScanner} takes for NO_PAYLOAD.
+      #
+      # A comment-form annotation line is a comment-only line
+      # ({AnnotationLookup::COMMENT_LINE}) carrying the `@intent:` token. The
+      # trailing same-line form never matches COMMENT_LINE, so it is never
+      # flagged and never makes a neighbour unreachable — its annotation
+      # belongs to its own example's line and the lookback is not involved.
+      #
+      # @param paths [Enumerable<String>]
+      # @return [Array<Finding>] one per unreachable comment-form annotation,
+      #   in file-then-line order. A file that cannot be read contributes
+      #   nothing here — {ValidatorBackend} already reports read failures, and
+      #   this pass has nothing positional to say about a file it never saw.
+      def unreachable_findings(paths)
+        paths.flat_map { |path| unreachable_findings_in_file(path) }
+      end
+
+      # @param path [String]
+      # @return [Array<Finding>]
+      def unreachable_findings_in_file(path)
+        begin
+          text = File.read(path, encoding: "UTF-8")
+        rescue SystemCallError, IOError
+          return []
+        end
+
+        unreachable_findings_in_text(text, file: path)
+      end
+
+      UNREACHABLE_ANNOTATION =
+        "unreachable annotation: the previous line is also a comment-form @intent:, " \
+        "so the one-line lookback claims only the line just above the example " \
+        "and this annotation is silently discarded at extraction (SPGD-12 §2)"
+
+      # A comment-only line carrying an `@intent:` token — the only form an
+      # example on the NEXT line may claim ({AnnotationLookup::COMMENT_LINE}).
+      COMMENT_INTENT_LINE = /\A\s*#.*@intent:/
+
+      # The line an annotation run may be claimed from: the first example
+      # keyword. The lookback rule is `example.metadata[:line_number] - 1`, so
+      # only the comment form on the line immediately above an example is
+      # inheritable — which makes an EXAMPLE the anchor of the whole rule.
+      #
+      # Anchoring on the example is what keeps this pass off annotation
+      # corpora with no examples at all (the recorded-binary fixtures in
+      # spec/fixtures/): there is no lookback there to silently discard
+      # anything, so there is nothing to report. The defect this pass exists
+      # for (SPGD-897) is stacked lines above a real example — an annotation
+      # the author believed was attached to the `it` under it.
+      EXAMPLE_LINE = /\A\s*(?:it|specify)\b/
+
+      # @param text [String] source of one file
+      # @param file [String] path to record on each Finding
+      # @return [Array<Finding>] one per comment-form `@intent:` line in a
+      #   stacked run — a maximal run of consecutive comment-form `@intent:`
+      #   lines immediately above an example — except the run's LAST line,
+      #   which is the one the one-line lookback claims. For the canonical
+      #   two-line stack above one `it`, that is the UPPER line.
+      def unreachable_findings_in_text(text, file:)
+        # A file that is not valid UTF-8 is reported once, loudly, by the
+        # backend as a read failure; nothing positional can be said about it,
+        # and `lines` below would raise on the invalid bytes.
+        return [] unless text.valid_encoding?
+
+        lines = text.lines
+        i = 0
+        findings = []
+
+        while i < lines.length
+          unless COMMENT_INTENT_LINE.match?(lines[i])
+            i += 1
+            next
+          end
+
+          run_start = i
+          i += 1 while i < lines.length && COMMENT_INTENT_LINE.match?(lines[i])
+          run_end = i # exclusive; lines[run_end] is the line after the run
+
+          if run_end < lines.length && EXAMPLE_LINE.match?(lines[run_end]) && run_start < run_end - 1
+            (run_start...(run_end - 1)).each do |j|
+              findings << Finding.new(file: file, line: j + 1, problem: UNREACHABLE_ANNOTATION,
+                                      kind: Finding::KIND_UNREACHABLE)
+            end
+          end
+        end
+
+        findings
+      end
     end
   end
 end

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.3"
+  VERSION = "0.3.5"
 end

metadata

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