specguard-ruby 0.3.28 → 0.3.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58f8188803b68968be3289f01834d0f128f239b10d31162d34eeaaf55b6daefe
-  data.tar.gz: 273ce5b5eb675b12b302e23c3b24e025d81e60e77b77476ba9c7401fd7742600
+  metadata.gz: 887fc6d71732b1947cc48c34f27c68ac5b9b71c729f604cf95c41e508cc8d6af
+  data.tar.gz: e2f20dbc68a7324cc34381e204bc8ac0f5db262002d86ffc3bd24c8c2cfb3663
 SHA512:
-  metadata.gz: fcc5a85ecf595eeb62aae5446387ff74802579f97991c71b9b7a61014499c954d6fcc546171440dd3fde330b06ad11cc6fb2717b5f8f569aee884d51534c1f61
-  data.tar.gz: 52ed4889c3074cb474b9a192603414ba11644c753ad6dc2a3d946579663bf0432bcd533702f36568d9c81259a4eaf3e7735102a5374379fbabe0a6b4f24b76e5
+  metadata.gz: e3d18c2b2d19c8d25b0c5a9277847767996ff27be06f7f5802b052c7a4dab7f20e7244214a339fc0a4bc0343103572ad842bd381f95ccd6efa670422da445edc
+  data.tar.gz: 9a2b14e04e71e6e957134e29ad38f11fdaad0aede17893907a048d9e6414d93affb7844f4a99e630194f5095c0bc945e271800871f39f71f325ed8b4805492ae

data/README.md

@@ -49,8 +49,9 @@ bundle exec ruby -rminitest/specguard_plugin -e 'Minitest.extensions << "specgua
 Validates `# @intent:` annotations in changed (or all) `*_spec.rb` files against the OpenTestIntent
 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; separated
-from its `it` by one blank or ordinary comment line, which puts it out of the lookback's reach; or
-trailing on a `describe`/`context` group line, which no example's extraction can ever reach) — and
+from its `it` by one blank or ordinary comment line, which puts it out of the lookback's reach;
+directly above an `it` that carries its own trailing `@intent:`, which extraction prefers, so the
+comment is shadowed; or trailing on a `describe`/`context` group line, which no example's extraction can ever reach) — and
 **never** fails on a *missing* one (adoption is opt-in and gradual).
 
 ```bash
@@ -336,8 +337,8 @@ Every way the backend can fail — the binary is missing, will not execute, exit
 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" — or well-formed
 but unreachable: stacked above another comment-form `@intent:` line, so the one-line lookback
-never claims it, separated from its `it` by one blank or ordinary comment line, or trailing on a
-`describe`/`context` group line, which no example's extraction can ever reach — and nothing else.
+never claims it, separated from its `it` by one blank or ordinary comment line, shadowed by its
+`it`'s own trailing `@intent:`, or trailing on a `describe`/`context` group line, which no example's extraction can ever reach — and nothing else.
 
 ## The formatter — `SpecGuard::RSpecFormatter`
 

data/lib/specguard/rspec/cli.rb

@@ -126,9 +126,10 @@ module SpecGuard
       # "Lint, don't require": a missing annotation is never an error.
       EXIT_OK = 0
       # One or more annotations are malformed — or well-formed but
-      # unreachable (SPGD-900/SPGD-1510/SPGD-1554: stacked above another
-      # comment-form `@intent:` line so the one-line lookback never claims it,
-      # separated from its example by one blank/comment line, or trailing on
+      # unreachable (SPGD-900/SPGD-1510/SPGD-1554/SPGD-1560: stacked above
+      # another comment-form `@intent:` line so the one-line lookback never
+      # claims it, separated from its example by one blank/comment line,
+      # shadowed by its example's own trailing `@intent:`, or trailing on
       # an example-group line no example's extraction can reach — a dead
       # contract in every case, and still a failure). The only code produced by
       # inspecting content, and the only path that reaches it is a failed
@@ -168,13 +169,15 @@ module SpecGuard
 
         results = backend.check(selection.files)
 
-        # The structural pass (SPGD-900, SPGD-1510, SPGD-1554): annotations
+        # The structural pass (SPGD-900, SPGD-1510, SPGD-1554, SPGD-1560): 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,
         # comment-form runs separated from their example by one blank/comment
-        # line, and `@intent:` tokens trailing on an example-group line, which
-        # no extraction rule can ever reach. These are Linter::Results like any
+        # line, comment-form lines shadowed by their example's own trailing
+        # `@intent:` (extraction is own-line-first), and `@intent:` tokens
+        # trailing on an example-group line, which no extraction rule can ever
+        # reach. 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)
@@ -482,15 +485,15 @@ module SpecGuard
       #
       # The boundary is the set-difference the partition above already
       # supports: a file counts as covered when it yielded any line-scoped
-      # result (an annotation, valid or not — the SPGD-900/SPGD-1510/SPGD-1554
+      # result (an annotation, valid or not — the SPGD-900/SPGD-1510/SPGD-1554/SPGD-1560
       # unreachable findings are line-scoped too and require an annotation to
       # exist, so they cover their file) or when it could not be read at all
       # (KIND_READ → `unread`). An unread file is NOT a zero-annotation file:
       # it already gets its own summary clause and FAIL line, and calling it
       # annotation-free would be the same overstatement `summary_line` refuses
       # to make. Unreachable findings need an annotation to exist — a stacked
-      # comment-form pair, a separated comment-form run, or an `@intent:`
-      # token on a group line — impossible in a file with none, so `annotations ∪ unread` already covers every
+      # comment-form pair, a separated comment-form run, a shadowed comment-form
+      # run, or an `@intent:` token on a group line — impossible in a file with none, so `annotations ∪ unread` already covers every
       # non-bare file and no third subtraction is needed.
       #
       # It is a NOTE on stderr, never a warning and never an exit code: "lint,

data/lib/specguard/rspec/finding.rb

@@ -49,7 +49,7 @@ module SpecGuard
       KIND_SCHEMA = :schema
 
       # The annotation is well-formed in isolation but can never be EXTRACTED.
-      # Three shapes, all dead the moment they are written:
+      # Four shapes, all dead the moment they are written:
       #
       #   * a comment-form `@intent:` stacked above another comment-form
       #     `@intent:` line, so the one-line lookback (SPGD-12 §2 —
@@ -61,7 +61,10 @@ module SpecGuard
       #     it, and the example beneath it silently ingests unannotated;
       #   * a comment-form `@intent:` run separated from its example by ONE
       #     blank or ordinary comment line (SPGD-1554): the one-line lookback
-      #     reads only that interleave, so the whole run is out of reach.
+      #     reads only that interleave, so the whole run is out of reach;
+      #   * a comment-form `@intent:` directly above an example whose OWN line
+      #     also carries a trailing `@intent:` (SPGD-1560): extraction is
+      #     own-line-first, so the example's own annotation shadows the comment.
       #
       # Whichever shape, the contract is dead metadata: counted by the linter,
       # discarded by extraction. Produced by {Scanner}'s structural pass, not

data/lib/specguard/rspec/linter.rb

@@ -40,15 +40,17 @@ module SpecGuard
     # `Finding::KIND_UNREACHABLE` — an annotation that is well-formed in
     # isolation but can never be extracted, so the one-line lookback
     # (SPGD-12 §2) never claims it — is also reported as a failure, and
-    # therefore also exits 1. Three shapes reach this kind: a comment-form
+    # therefore also exits 1. Four shapes reach this kind: a comment-form
     # `@intent:` stacked above another comment-form `@intent:` line (SPGD-900),
     # an `@intent:` trailing on an example-group line, which is no
     # example's own and not comment-only (SPGD-1510), and a comment-form
     # `@intent:` run separated from its example by one blank or ordinary
-    # comment line (SPGD-1554). Nothing about any of them is malformed; the
+    # comment line (SPGD-1554), and a comment-form `@intent:` directly above an
+    # example whose own line carries a trailing `@intent:`, which own-line-first
+    # extraction prefers (SPGD-1560). Nothing about any of them is malformed; the
     # contract is dead metadata, counted by the linter and discarded by
     # extraction, and the structural pass that flags them (SPGD-900,
-    # SPGD-1510, SPGD-1554) reports it loudly rather than letting it pass as
+    # SPGD-1510, SPGD-1554, SPGD-1560) reports it loudly rather than letting it pass as
     # clean.
     module Linter
       # One annotation's verdict. `problem` is set when discovery could not

data/lib/specguard/rspec/scanner.rb

@@ -261,7 +261,7 @@ module SpecGuard
       # ({AnnotationLookup}, SPGD-12 §2) is positional: an annotation reaches
       # an example only through its own line (the trailing form, and only when
       # that line IS the example's) or through the comment-form line
-      # IMMEDIATELY ABOVE it. Three shapes fall outside both and are dead the
+      # IMMEDIATELY ABOVE it. Four shapes fall outside both and are dead the
       # moment they are written — silently discarded by extraction while this
       # pipeline counts them as valid annotations and the run exits 0:
       #
@@ -283,7 +283,15 @@ module SpecGuard
       #     the example, which is the interleave — so the annotation is out of
       #     reach and every line of the run is dead.
       #
-      # All three are reported loudly, not skipped — the same stance
+      #   * the SHADOWED annotation (SPGD-1560, ported from specguard-ts
+      #     SPGD-1556): a comment-form `@intent:` run directly above an example
+      #     whose OWN line also carries a trailing `@intent: {`. Extraction is
+      #     own-line-first ({AnnotationLookup::Index#intent_for} returns the
+      #     example's own annotation before it ever consults the line above),
+      #     so the comment is shadowed and its LAST line is dead. (Any earlier
+      #     lines of the run are the stacked arm's.)
+      #
+      # All four are reported loudly, not skipped — the same stance
       # {AnnotationScanner} takes for NO_PAYLOAD.
       #
       # A comment-form annotation line is a comment-only line
@@ -336,6 +344,12 @@ module SpecGuard
         "discarded at extraction. Move it directly above the example (or merge it into " \
         "the line that is)"
 
+      UNREACHABLE_SHADOWED_ANNOTATION =
+        "unreachable annotation: the example directly below carries its own trailing @intent:, " \
+        "and extraction is own-line-first (SPGD-12 §2), so this comment-form annotation is " \
+        "shadowed and silently discarded. Delete this comment, or merge it into the trailing " \
+        "payload"
+
       # 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:/
@@ -370,14 +384,18 @@ module SpecGuard
       # @return [Array<Finding>] the structural findings for one file, in line
       #   order: one per comment-form `@intent:` line in a stacked run (see
       #   {stacked_findings_in_text}), one per line of a separated run (see
-      #   {separated_findings_in_text}) plus one per group line carrying the
-      #   trailing form (see {group_line_findings_in_text}). The three passes
-      #   are disjoint by construction: the stacked pass needs an example
-      #   line directly after the run, the separated pass needs a blank or
-      #   comment-only line there (one slot cannot be both), and the group
-      #   pass reads only lines that are not comment-only — so the merge
-      #   cannot double-flag a line, and the sort restores the file-then-line
-      #   order {unreachable_findings} promises.
+      #   {separated_findings_in_text}), one per run whose example carries its own
+      #   trailing annotation (see {own_line_shadow_findings_in_text}) plus one
+      #   per group line carrying the trailing form (see
+      #   {group_line_findings_in_text}). The four passes are disjoint by
+      #   construction: the stacked pass flags all but the LAST line of a run
+      #   when an example directly follows, the shadow pass flags ONLY that last
+      #   line (and only when the example also carries `@intent: {`), the
+      #   separated pass needs a blank or comment-only line after the run (one
+      #   slot cannot be both that and an example), and the group pass reads
+      #   only lines that are not comment-only — so the merge cannot double-flag
+      #   a line, and the sort restores the file-then-line order
+      #   {unreachable_findings} promises.
       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,
@@ -386,6 +404,7 @@ module SpecGuard
 
         (stacked_findings_in_text(text, file: file) +
          separated_findings_in_text(text, file: file) +
+         own_line_shadow_findings_in_text(text, file: file) +
          group_line_findings_in_text(text, file: file)).sort_by(&:line)
       end
 
@@ -473,6 +492,44 @@ module SpecGuard
         findings
       end
 
+      # @param text [String] source of one file
+      # @param file [String] path to record on each Finding
+      # @return [Array<Finding>] one per maximal run of comment-form
+      #   `@intent:` lines whose following line is an example
+      #   ({EXAMPLE_LINE}) that ALSO carries a trailing `@intent: {`
+      #   ({INTENT_WITH_PAYLOAD}) — reported on the run's LAST line, the one
+      #   the lookback would otherwise claim. Extraction is own-line-first
+      #   (SPGD-12 §2), so the example's own annotation always wins and that
+      #   comment is dead. Earlier lines of a longer run are the stacked arm's
+      #   ({stacked_findings_in_text}); each dead line is flagged exactly once.
+      def own_line_shadow_findings_in_text(text, file:)
+        # Same UTF-8 contract as the stacked pass above.
+        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
+
+          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
+
+          example = lines[run_end]
+          next if example.nil?
+          next unless EXAMPLE_LINE.match?(example) && INTENT_WITH_PAYLOAD.match?(example)
+
+          findings << Finding.new(file: file, line: run_end, problem: UNREACHABLE_SHADOWED_ANNOTATION,
+                                  kind: Finding::KIND_UNREACHABLE)
+        end
+
+        findings
+      end
+
       # RSpec's example-group keywords, at the start of a line and optionally
       # `RSpec.`-prefixed. A line matching this hosts a GROUP, not an example
       # — and {AnnotationLookup}'s extraction can claim an annotation only

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.28"
+  VERSION = "0.3.29"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: specguard-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.28
+  version: 0.3.29
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json