specguard-ruby 0.3.25 → 0.3.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 406d8e0f3f1d7df09e15238b5873d058c56f790a57abc2756c410071c804e24b
-  data.tar.gz: 35d3af2251ea0b454284702142d2c9eb3d91665ceb0ffa4ee5f419b7fd041f49
+  metadata.gz: 788caaa70678a741f5ddb2aa3379d033369905ee89a7164f37527f0c64ecf3a5
+  data.tar.gz: 8c03300935002043fd6097d3779057ed0dec439b13108bdc440ced0fee71af95
 SHA512:
-  metadata.gz: 3674ff375d6f9b74fff339763fadf9d8852fb130e9456260f1d1258c070d31d1f7bee1bf72b3e9eede768bb0873e5583349fd49b7fa400eb0c7f1d913e147fed
-  data.tar.gz: 7fb0ad96d1a6dfb38378fa2d0df55c9fad1b8a8f8a19e5e5721a183a512af1c420d98c86f8827489b1ad95254fdfde9a6bb378e28c3fbe4a8bae163c70544f9c
+  metadata.gz: 138c404bb1691827932705550d146c5d34c908ef5c3581ef6f1aa6d210de46f8ba0ef349f81486bab4340ead74588858031012732f26a46e7df691ce4fce78ce
+  data.tar.gz: 26e5764b84b90f120caea35853e9205b1e1142bf3f3709b761f164acc7f294b2cda5aa6dcc6f89354e03f7bc750a6d3268050f1ef25961db606b6b1584e4bff8

data/README.md

@@ -48,7 +48,8 @@ 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) — and
+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
 **never** fails on a *missing* one (adoption is opt-in and gradual).
 
 ```bash
@@ -334,7 +335,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 — and nothing else.
+never claims it, 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: 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}.
+      # 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
+      # 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
@@ -165,12 +167,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
+        # 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. 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.
+        # (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
+        # 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`
@@ -476,15 +480,16 @@ 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 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 a stacked annotation — impossible in a file with none —
-      # so `annotations ∪ unread` already covers every non-bare file and no
-      # third subtraction is needed.
+      # result (an annotation, valid or not — the SPGD-900/SPGD-1510
+      # 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
+      # non-bare file and no third subtraction is needed.
       #
       # It is a NOTE on stderr, never a warning and never an exit code: "lint,
       # don't require" (SPGD-12 §1) keeps a missing annotation a non-error.

data/lib/specguard/rspec/finding.rb

@@ -48,15 +48,22 @@ 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.
+      # The annotation is well-formed in isolation but can never be EXTRACTED.
+      # Two shapes, both 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 —
+      #     {AnnotationLookup} claims only the comment on the line immediately
+      #     above an example) always skips it in favour of the lower line;
+      #   * 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.
+      #
+      # Either way 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.
       KIND_UNREACHABLE = :unreachable
 
       def initialize(file:, line:, intent: nil, problem: nil, kind: nil)

data/lib/specguard/rspec/linter.rb

@@ -38,12 +38,16 @@ module SpecGuard
     # `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
+    # 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
+    # `@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 it
-    # (SPGD-900) reports it loudly rather than letting it pass as clean.
+    # discarded by extraction, and the structural pass that flags them
+    # (SPGD-900, SPGD-1510) 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

@@ -258,25 +258,41 @@ module SpecGuard
       #
       # 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
+      # ({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
+      # moment they are written — silently discarded by extraction while this
+      # pipeline counts them as valid annotations and the run exits 0:
+      #
+      #   * the STACKED pair (SPGD-897, found in the audit): two consecutive
+      #     comment-form `@intent:` lines above one `it` — the UPPER line is
+      #     never claimed, because the one-line lookback takes only the line
+      #     just above the example. Measured: 16 such stacked pairs shipped
+      #     through `specguard-lint` exit 0, every upper contract dead.
+      #   * the GROUP line (SPGD-1510, cost SPGD-1475 a full rework round): an
+      #     `@intent:` trailing on a `describe`/`context`/… line. The line is
+      #     no example's own, and it is not comment-only, so no lookback can
+      #     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
       # {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.
+      # trailing same-line form is claimed ONLY when the line itself defines
+      # an example ({EXAMPLE_LINE}); there the annotation belongs to its own
+      # example's line and the lookback is not involved. On any other line the
+      # trailing form is dead too — an example-group line carrying it is now
+      # flagged by {GROUP_LINE}'s pass below, with the one-liner exemption
+      # ({EXAMPLE_ON_LINE}) keeping `describe "x" do it("y") { } end` claims
+      # intact.
       #
       # @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
+      # @return [Array<Finding>] one per unreachable 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)
@@ -300,6 +316,13 @@ module SpecGuard
         "so the one-line lookback claims only the line just above the example " \
         "and this annotation is silently discarded at extraction (SPGD-12 §2)"
 
+      UNREACHABLE_GROUP_ANNOTATION =
+        "unreachable annotation: this @intent: sits trailing on an example-group line " \
+        "(describe/context/...), and annotations attach to examples, never to groups — " \
+        "extraction (SPGD-12 §2) is one-line and example-anchored, so no example can ever " \
+        "claim it. Move it onto its example's `it` line, or to the comment line directly " \
+        "above that `it`"
+
       # 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:/
@@ -312,11 +335,32 @@ module SpecGuard
       # 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.
+      # 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_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>] 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.
+      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?
+
+        (stacked_findings_in_text(text, file: file) +
+         group_line_findings_in_text(text, file: file)).sort_by(&:line)
+      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 in a
@@ -324,7 +368,7 @@ module SpecGuard
       #   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:)
+      def stacked_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.
@@ -354,6 +398,83 @@ module SpecGuard
 
         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
+      # from an example's own line or the comment-only line above it, so an
+      # `@intent:` written here is unreachable wherever it sits on the line.
+      GROUP_LINE =
+        /\A\s*(?:RSpec\.)?(?:describe|context|feature|shared_examples|shared_examples_for|shared_context|example_group)\b/
+
+      # A token WITH its payload opener: what the rest of the pipeline treats
+      # as an annotation on a group line. The `{` is load-bearing — a bare
+      # `@intent:` token is a {AnnotationScanner::NO_PAYLOAD} extraction
+      # failure the main pipeline already reports loudly, and (because
+      # extraction is marker-based, SPGD-8 §7) the token is ALSO found inside
+      # quoted strings: this repo's own suite carries
+      # `describe "unreachable stacked @intent: annotations"`, which is prose,
+      # not an annotation, and must not read as one. A line matching this is
+      # one the scanner captured a payload from (or began capturing one),
+      # which is the population this pass has standing to judge. The naive
+      # search inherits the scanner's string-literal limitation in the exotic
+      # direction only: a group line whose prose embeds `@intent: {` reads as
+      # annotated (a flag the pipeline independently agrees with, since
+      # extraction captures that literal too), never the reverse.
+      INTENT_WITH_PAYLOAD = /@intent:\s*\{/
+
+      # The one-liner exemption: a group line that ALSO defines an example on
+      # the same line is that example's own line, so its trailing annotation
+      # is claimed by the example and must not be flagged:
+      #
+      #   describe "one" do it("x") { } end # @intent: { ... }
+      #
+      # Two guards keep prose from reading as an example call. The match runs
+      # against the code BEFORE the `@intent:` token — the payload is English
+      # an author wrote about a behavior ("...when it's given one"), and
+      # reading `it'` there as a call exempted the exact group-line shape
+      # this pass exists to flag. And the call must sit after a block opener
+      # (`do`, `{`, `;`), because the description string is part of the code
+      # side too: `describe "the cost of rendering it" do` ends in the word
+      # `it`, and `it"` is not a call. What this heuristic still cannot see:
+      # a description string containing the literal sequence `do it` /
+      # `do specify` (or `{ it`), as in `describe "how to do it right" do`,
+      # still reads as a call and is wrongly exempted — a missed flag, and
+      # only ever a missed flag: prose can turn the exemption ON, never a
+      # real example OFF. The one-line example's own payload is never
+      # consulted, so a payload can never exempt anything.
+      EXAMPLE_ON_LINE = /(?:\bdo\b|\{|;)\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 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).
+      def group_line_findings_in_text(text, file:)
+        # Same UTF-8 contract as the stacked pass above.
+        return [] unless text.valid_encoding?
+
+        text.lines.each_with_index.filter_map do |line, idx|
+          # Comment-only lines belong to the stacked pass; this pass reads the
+          # group line ITSELF. (A `#`-leading line could never match
+          # GROUP_LINE anyway — the guard states the division, not a filter.)
+          next if line.lstrip.start_with?("#")
+          next unless GROUP_LINE.match?(line)
+          next unless INTENT_WITH_PAYLOAD.match?(line)
+          # The exemption sees the code before the token; the payload and
+          # anything after it are prose and must never read as an example
+          # call. The token is guaranteed present (INTENT_WITH_PAYLOAD just
+          # matched), so `split` always yields the code side.
+          code = line.split("@intent:", 2).first
+          next if EXAMPLE_ON_LINE.match?(code)
+
+          Finding.new(file: file, line: idx + 1, problem: UNREACHABLE_GROUP_ANNOTATION,
+                      kind: Finding::KIND_UNREACHABLE)
+        end
+      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.25"
+  VERSION = "0.3.26"
 end

metadata

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