specguard-ruby 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d91e0fec640df334c1ee281f06852adb53172514aa6bc357346d0ba76c725fe
-  data.tar.gz: c2f3974d36260c4cdf33296e85f3a44879be617122ce3291a17538d2d7e4e68f
+  metadata.gz: 43e3d2ff78fc5e1750d77197ff2ef15c9815040147c4e52c51dd71855261b5c1
+  data.tar.gz: e55c3f9bdcaa0a21f60fb8654ee8848a55c06b6ceb282ac523390dfbec07f12d
 SHA512:
-  metadata.gz: '019c9e92094afec846e8184c39ce185c47eb564b6cd4b6ec9ed2198e1876865b02efd8b198ac2d161629840a8b188991fc4fd347265bc47b5a67b513d4498a60'
-  data.tar.gz: 411ea2d03fa8be62ec65f54a1341cd6ca8926dfdf481618b86d4551c111d84312efcc3d9dacfabe015bf9dee254a956e468137f6a4bef6468635302d673e4266
+  metadata.gz: e5603b3d5deaa9e5a8119c469a8a142f4bb9527b231866e4a3c57d7face3319fb70ece91d19c81f8cb9094d48363d887ab81175e2c9897148f730c8ac72ef4b5
+  data.tar.gz: e5a67e10d778c961e4cb8edf743db91861cbf350e15ff305370ad42d102e4d28aaf25c591617c47c73d090a77d18b3faf6cb529dd8570f18245e38402168e123

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/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,

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.4"
 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.4
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-29 00:00:00.000000000 Z
+date: 2026-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json