specguard-ruby 0.3.24 → 0.3.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd1e42b8014d4627c1126b81fd4e419e000316e788f0115a24dbbf9041ad52b1
-  data.tar.gz: d74ca48cff5263d913f727a94d59b6bb6ffd477ff4a31bddcf7d83599b96f9c3
+  metadata.gz: 788caaa70678a741f5ddb2aa3379d033369905ee89a7164f37527f0c64ecf3a5
+  data.tar.gz: 8c03300935002043fd6097d3779057ed0dec439b13108bdc440ced0fee71af95
 SHA512:
-  metadata.gz: 79519698cb6c136909f09bd425548bdac0e3ab936145449e983937d2f9f97e9f1e30e7f3bcd9936e1c200b2c49358157d9b97469804f3b11a200538557dc78f3
-  data.tar.gz: c034dc9514a7cb085909a1bcdfb7c51e84dd67af457bbd73c26c4a4d31f21afae6c6893a7f42d2475dd350b80d0112879698ab5a912cf2dee5c83dfa7abc7c25
+  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`
 
@@ -877,7 +879,9 @@ command draws. Everything else stays **byte for byte, in the file's order**:
 
 The rewrite is **atomic**: a temporary file in the same directory, renamed over
 the original, so a failure mid-drain leaves the file exactly as it was — and
-nothing is written at all unless something was actually accepted.
+nothing is written at all unless something was actually accepted. The swap
+also keeps the queue file's permissions, and when the queue path is a symlink
+it rewrites the link's target rather than replacing the link.
 
 **The removal renumbers what it leaves.** The rewrite keeps the surviving lines
 byte for byte and in order, and packing them up from the top gives them new

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/ingest_cli.rb

@@ -1155,13 +1155,26 @@ module SpecGuard
       # The atomic swap: a temporary file in the SAME directory — `rename` is
       # only atomic within one filesystem — renamed over the original. A
       # failure at any point before the rename leaves the original untouched,
-      # and the `ensure` takes the temporary with it.
+      # and the `ensure` takes the temporary with it. The rename lands on the
+      # RESOLVED target (`File.realpath`), so a queue reached through a
+      # symlink is rewritten at the file the link points to and the link
+      # itself survives: `rename(2)` replaces the directory entry at the path
+      # given to it, and without this the swap would turn the link into a
+      # regular file while the real target kept every line just accepted —
+      # lines the next drain would then send again. The replacement is
+      # chmod'ed to the target's mode before the swap, because
+      # `File.binwrite` creates it under the umask's defaults and a queue
+      # restricted to 0600 would come back 0644 as a fresh inode. Ownership
+      # is deliberately NOT carried over: `chown` needs privilege, and in
+      # practice the drain runs as the queue's owner.
       def drain_write(path, content)
-        tmp = File.join(File.dirname(path),
-                        ".#{File.basename(path)}.drain-#{Process.pid}-#{rand(1 << 32).to_s(36)}.tmp")
+        target = File.realpath(path)
+        tmp = File.join(File.dirname(target),
+                        ".#{File.basename(target)}.drain-#{Process.pid}-#{rand(1 << 32).to_s(36)}.tmp")
         begin
           File.binwrite(tmp, content)
-          File.rename(tmp, path)
+          File.chmod(File.stat(target).mode & 0o7777, tmp)
+          File.rename(tmp, target)
         ensure
           File.unlink(tmp) if File.exist?(tmp)
         end

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