specguard-ruby 0.3.26 → 0.3.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 788caaa70678a741f5ddb2aa3379d033369905ee89a7164f37527f0c64ecf3a5
-  data.tar.gz: 8c03300935002043fd6097d3779057ed0dec439b13108bdc440ced0fee71af95
+  metadata.gz: 58f8188803b68968be3289f01834d0f128f239b10d31162d34eeaaf55b6daefe
+  data.tar.gz: 273ce5b5eb675b12b302e23c3b24e025d81e60e77b77476ba9c7401fd7742600
 SHA512:
-  metadata.gz: 138c404bb1691827932705550d146c5d34c908ef5c3581ef6f1aa6d210de46f8ba0ef349f81486bab4340ead74588858031012732f26a46e7df691ce4fce78ce
-  data.tar.gz: 26e5764b84b90f120caea35853e9205b1e1142bf3f3709b761f164acc7f294b2cda5aa6dcc6f89354e03f7bc750a6d3268050f1ef25961db606b6b1584e4bff8
+  metadata.gz: fcc5a85ecf595eeb62aae5446387ff74802579f97991c71b9b7a61014499c954d6fcc546171440dd3fde330b06ad11cc6fb2717b5f8f569aee884d51534c1f61
+  data.tar.gz: 52ed4889c3074cb474b9a192603414ba11644c753ad6dc2a3d946579663bf0432bcd533702f36568d9c81259a4eaf3e7735102a5374379fbabe0a6b4f24b76e5

data/README.md

@@ -48,8 +48,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, 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; 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 +336,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, 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,11 @@ 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: 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
+      # 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 +168,13 @@ 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): 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
         # 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 +482,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
       # 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, 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:
+      # Three 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,12 @@ 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.
       #
-      # 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,15 @@ 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. Three 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). 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
     # 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. Three 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,14 @@ 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.
+      #
+      # All three 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 +329,13 @@ 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)"
+
       # 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,20 +350,34 @@ 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
-      #   a line, and the sort restores the file-then-line order
-      #   {unreachable_findings} promises.
+      #   {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.
       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,
@@ -358,6 +385,7 @@ module SpecGuard
         return [] unless text.valid_encoding?
 
         (stacked_findings_in_text(text, file: file) +
+         separated_findings_in_text(text, file: file) +
          group_line_findings_in_text(text, file: file)).sort_by(&:line)
       end
 
@@ -399,6 +427,52 @@ 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
+
       # 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 +524,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.26"
+  VERSION = "0.3.28"
 end

metadata

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