specguard-ruby 0.3.27 → 0.3.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b3732299a2d530c1fc5621ea498170dd62bbfb544b5dbb3732b40db8c42485e
-  data.tar.gz: 7aeb4da4307f6a2aceebeace51a4a2ee7144bbc7119bf27d0075a1e1d8a6aa40
+  metadata.gz: 887fc6d71732b1947cc48c34f27c68ac5b9b71c729f604cf95c41e508cc8d6af
+  data.tar.gz: e2f20dbc68a7324cc34381e204bc8ac0f5db262002d86ffc3bd24c8c2cfb3663
 SHA512:
-  metadata.gz: de7f31eb5b14f44d922a5826c58b2e85970ec1113863802a78c120b840d22b1569b6ec2326763b0952c7040e7ce98564296721f675ccfdd72fc9fff117ad2e98
-  data.tar.gz: 98b801cde5eb671bb76830009f56a9b3578cc934e1814fa01a588df5f34f840fa27080abd0ec3403e5bbc5affec2b441c3d962c710c9aeb64072c16f484a17e2
+  metadata.gz: e3d18c2b2d19c8d25b0c5a9277847767996ff27be06f7f5802b052c7a4dab7f20e7244214a339fc0a4bc0343103572ad842bd381f95ccd6efa670422da445edc
+  data.tar.gz: 9a2b14e04e71e6e957134e29ad38f11fdaad0aede17893907a048d9e6414d93affb7844f4a99e630194f5095c0bc945e271800871f39f71f325ed8b4805492ae

data/README.md

@@ -48,8 +48,10 @@ 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, or trailing
-on a `describe`/`context` group line, which no example's extraction can ever reach) — and
+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;
+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
@@ -335,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, 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,10 +126,12 @@ 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: stacked above another comment-form
-      # `@intent:` line so the one-line lookback never claims it, or trailing
-      # on an example-group line no example's extraction can reach — a dead
-      # contract either way, and still a failure). The only code produced by
+      # 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
       # {Linter::Result}.
       EXIT_MALFORMED = 1
@@ -167,12 +169,15 @@ module SpecGuard
 
         results = backend.check(selection.files)
 
-        # The structural pass (SPGD-900, SPGD-1510): 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, and
-        # `@intent:` tokens trailing on an example-group line, which no
-        # extraction rule can ever reach. These are Linter::Results like any
+        # 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, 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)
@@ -480,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
+      # 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, 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.
-      # Two shapes, both 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 —
@@ -58,9 +58,15 @@ module SpecGuard
       #   * an `@intent:` trailing on an example-group line
       #     ({Scanner::GROUP_LINE} — SPGD-1510): a group line is no example's
       #     own and is not comment-only, so no extraction rule can ever reach
-      #     it, and the example beneath it silently ingests unannotated.
+      #     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;
+      #   * 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.
       #
-      # Either way the contract is dead metadata: counted by the linter,
+      # Whichever shape, 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 these defects are invisible to it.

data/lib/specguard/rspec/linter.rb

@@ -40,13 +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. Two 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),
-    # and an `@intent:` trailing on an example-group line, which is no
-    # example's own and not comment-only (SPGD-1510). Nothing about either 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) reports it loudly rather than letting it pass as
+    # 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), 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, 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. Two 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:
       #
@@ -276,8 +276,22 @@ module SpecGuard
       #     ever claim it — the example beneath it silently ingests as
       #     unannotated. A describe insertion that swallowed a newline is how
       #     the shape is born.
-      #
-      # Both are reported loudly, not skipped — the same stance
+      #   * the SEPARATED annotation (SPGD-1554, ported from specguard-ts
+      #     SPGD-1550): a comment-form `@intent:` run followed by exactly ONE
+      #     blank line or ordinary (non-`@intent:`) comment line and THEN an
+      #     example. The one-line lookback reads only the line directly above
+      #     the example, which is the interleave — so the annotation is out of
+      #     reach and every line of the run is dead.
+      #
+      #   * 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
@@ -323,6 +337,19 @@ module SpecGuard
         "claim it. Move it onto its example's `it` line, or to the comment line directly " \
         "above that `it`"
 
+      UNREACHABLE_SEPARATED_ANNOTATION =
+        "unreachable annotation: this @intent: is separated from its example by an " \
+        "intervening comment or blank line, and the one-line lookback (SPGD-12 §2) claims " \
+        "only the line directly above the example — so this annotation is silently " \
+        "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:/
@@ -337,18 +364,36 @@ module SpecGuard
       # spec/fixtures/): there is no lookback there to silently discard
       # anything, so there is nothing to report. The defects this pass exists
       # for are annotations an author believed were attached to a real
-      # example: stacked lines above it (SPGD-897), and the trailing form on
-      # a group line directly above it (SPGD-1510).
+      # example: stacked lines above it (SPGD-897), the trailing form on
+      # a group line directly above it (SPGD-1510), and a comment-form run
+      # separated from it by one blank/comment line (SPGD-1554).
       EXAMPLE_LINE = /\A\s*(?:it|specify)\b/
 
+      # A blank (whitespace-only) line — one of the two interleaves the
+      # separated pass reads. `\n` is whitespace, so a `text.lines` element
+      # that is only its newline matches.
+      BLANK_LINE = /\A\s*\z/
+
+      # A comment-only line (`#`-leading). The separated pass reads it as the
+      # interleave only when it carries no `@intent:` token (a comment-form
+      # `@intent:` line is part of the run itself, never an interleave).
+      COMMENT_ONLY_LINE = /\A\s*#/
+
       # @param text [String] source of one file
       # @param file [String] path to record on each Finding
       # @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}) plus one per group line carrying the
-      #   trailing form (see {group_line_findings_in_text}). The two passes
-      #   are disjoint by construction — one reads only comment-only lines,
-      #   the other only lines that are not — so the merge cannot double-flag
+      #   {stacked_findings_in_text}), one per line of a separated run (see
+      #   {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:)
@@ -358,6 +403,8 @@ module SpecGuard
         return [] unless text.valid_encoding?
 
         (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
 
@@ -399,6 +446,90 @@ 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 comment-form `@intent:` line of a
+      #   SEPARATED run — a maximal run of consecutive comment-form `@intent:`
+      #   lines whose following line (the interleave) is blank or a comment
+      #   without an `@intent:` token AND whose line after that is an example
+      #   ({EXAMPLE_LINE}). The one-line lookback reads only the interleave,
+      #   so NOTHING in the run is claimed: every line is flagged, the run's
+      #   last line included — the discriminating difference from
+      #   {stacked_findings_in_text}, which spares the last line. The window
+      #   is exactly one line: a second interleave, a code interleave, a
+      #   `describe` target or a run at end of file is not flagged.
+      def separated_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
+
+          run_start = i
+          i += 1 while i < lines.length && COMMENT_INTENT_LINE.match?(lines[i])
+          run_end = i # exclusive; lines[run_end] is the interleave candidate
+
+          between = lines[run_end]
+          example = lines[run_end + 1]
+          next if between.nil? || example.nil?
+          next unless BLANK_LINE.match?(between) ||
+                      (COMMENT_ONLY_LINE.match?(between) && !COMMENT_INTENT_LINE.match?(between))
+          next unless EXAMPLE_LINE.match?(example)
+
+          (run_start...run_end).each do |j|
+            findings << Finding.new(file: file, line: j + 1, problem: UNREACHABLE_SEPARATED_ANNOTATION,
+                                    kind: Finding::KIND_UNREACHABLE)
+          end
+        end
+
+        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
@@ -450,9 +581,9 @@ module SpecGuard
       # @return [Array<Finding>] one per example-group line carrying an
       #   `@intent:` token, for lines that define no example of their own
       #   ({EXAMPLE_ON_LINE}). Comment-only lines are left to
-      #   {stacked_findings_in_text}: a comment above a group is a different
-      #   shape, deliberately out of scope here (SPGD-1510 flags the group
-      #   line ITSELF).
+      #   {stacked_findings_in_text} and {separated_findings_in_text}: a
+      #   comment above a group is a different shape, deliberately out of
+      #   scope here (SPGD-1510 flags the group line ITSELF).
       def group_line_findings_in_text(text, file:)
         # Same UTF-8 contract as the stacked pass above.
         return [] unless text.valid_encoding?

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.27"
+  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.27
+  version: 0.3.29
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-27 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json