specguard-ruby 0.3.10 → 0.3.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7d1dfb3eb7af542eee8c1202dae06dd0d9c3981f5415d12875037c9a9067944
-  data.tar.gz: 9d785e02b70ea9e06b0d0cf55ce31cbb1d67c841ea36fb0b7f3c7217a8f20304
+  metadata.gz: a48430615dad6103c9c66ef9a7e78d5f4fabdcf460a2321d4f3b03bb0d096fe5
+  data.tar.gz: 68100f41f50db5a7bc0067a6afb79823498aeae6bf6ef0fff0b5d04ff4b3b672
 SHA512:
-  metadata.gz: 3d5ae9e309ae02ea33679223f712d04edf7c9e06aab22f011fde61484f2f3c8d2c992b02b792caceeb934b63136734840cdd01d0dbe62619b695dd09c3ceb238
-  data.tar.gz: 3d3f373483219a5cdbeecdf639065bd99cb90dd648acf4bd75174ae9eba6adefcfc94a6458577480bb526dc636d88b139a4742cda3c12269a320bd5e7f994a3f
+  metadata.gz: ffeaa97c7b965463b5efd30a3273101f029dca4a0de18d2af6dbcd6664dacdc42e49bda907ae02d8d33c3a7bd3b5c9716c47c1a0469122c438dd751f146ba6b0
+  data.tar.gz: 8745018c339d7073e30e720771a9e4cea8df251a9681e35d536c3015e9e0b5990c55ccba7b9807cb156fd2b69d13834cf62ef9899c9f5740629ee360445df92d

data/lib/specguard/rspec/cli.rb

@@ -156,7 +156,11 @@ module SpecGuard
         # `ok` is derived FROM it rather than recomputed from the findings, so
         # the two renderers cannot disagree about whether the run passed.
         code = results.any?(&:failed?) ? EXIT_MALFORMED : EXIT_OK
-        report_results(results, files: selection.count, json: options[:json], ok: code == EXIT_OK)
+        # The selection's file LIST rides along (the `files:` count stays what
+        # the document's summary consumes) because the coverage note is about
+        # which files were checked, not how many.
+        report_results(results, files: selection.count, selected_files: selection.files,
+                       json: options[:json], ok: code == EXIT_OK)
 
         code
       rescue UsageError, ValidatorError => e
@@ -225,9 +229,18 @@ module SpecGuard
       #
       # Under `--json` the count is not dropped, it MOVES: stdout carries one
       # document and nothing else, and this line's number is that document's
-      # `summary.files`. The warnings are diagnostics about the linter rather
-      # than findings, so they stay on stderr exactly as they are — a run that
-      # selected nothing is still loud, in both renderers.
+      # `summary.files`. The sentence branches by STREAM, not by content: the
+      # human renderer reads it on stdout, the json renderer on stderr, where
+      # diagnostics about the linter already live — the empty-selection
+      # warning is the precedent, SPGD-247 the doctrine. (SPGD-1134: this was
+      # an `elsif !json` suppression, which left a json run's selection
+      # unverifiable — the machine channel named neither its resolved base nor
+      # its untracked leg, so the bridge, which passes `--json`
+      # unconditionally, could only verify the diff ∪ untracked union by
+      # arithmetic on `summary.files`.) The warnings below are diagnostics
+      # about the linter rather than findings, so they stay on stderr exactly
+      # as they are — a run that selected nothing is still loud, in both
+      # renderers.
       #
       # The `--changed` count names its provenance: files can reach the
       # selection through the untracked leg (`file_selector.rb`), and "changed
@@ -239,15 +252,24 @@ module SpecGuard
         if selection.empty?
           @stderr.puts "specguard-lint: warning: selected 0 spec files — #{empty_reason(selection)}"
           @stderr.puts "specguard-lint: warning: #{selection.note}" if selection.note
-        elsif !json
-          untracked = selection.mode == :changed ? selection.stats&.untracked.to_i : 0
-          @stdout.puts "specguard-lint: checked #{selection.count} spec file#{'s' unless selection.count == 1}" \
-                       "#{" changed since #{selection.base}" if selection.mode == :changed}" \
-                       "#{" under #{Dir.pwd}" if selection.mode == :all}" \
-                       "#{" including #{untracked} untracked" if untracked.positive?}"
+        else
+          json ? @stderr.puts(selection_line(selection)) : @stdout.puts(selection_line(selection))
         end
       end
 
+      # The selection sentence, built at exactly one site and written by both
+      # renderers — only the stream differs. The human line is the contract
+      # of record; the json renderer printing the SAME bytes is what makes
+      # "the machine reads the provenance the human does" a property of the
+      # code rather than a promise two copies could drift apart on.
+      def selection_line(selection)
+        untracked = selection.mode == :changed ? selection.stats&.untracked.to_i : 0
+        "specguard-lint: checked #{selection.count} spec file#{'s' unless selection.count == 1}" \
+          "#{" changed since #{selection.base}" if selection.mode == :changed}" \
+          "#{" under #{Dir.pwd}" if selection.mode == :all}" \
+          "#{" including #{untracked} untracked" if untracked.positive?}"
+      end
+
       # `:explicit` is absent by construction — an explicit Selection is only
       # built from a non-empty file list, so it can never be empty.
       def empty_reason(selection)
@@ -337,9 +359,11 @@ module SpecGuard
       # statements about the same numbers, and a linter whose two renderers can
       # disagree about how much it checked is worse than one that only prints
       # prose: the disagreement is unfalsifiable from outside the process.
-      def report_results(results, files:, json:, ok:)
+      def report_results(results, files:, selected_files:, json:, ok:)
         annotations, unread = results.partition(&:line_scoped?)
 
+        report_zero_annotation_files(selected_files, annotations, unread)
+
         if json
           @stdout.puts JSONReporter.render(results, files: files, annotations: annotations.length, ok: ok)
           return
@@ -350,6 +374,43 @@ module SpecGuard
         @stdout.puts summary_line(annotations, unread)
       end
 
+      # The coverage note: which of the checked files were read and yielded no
+      # `@intent` annotation at all. Zero findings on stdout (or an empty
+      # `findings` list in the document) is otherwise ambiguous between
+      # "every checked file was annotated and valid" and "half the checked
+      # files carry nothing" — and the missing-annotation question is the most
+      # actionable one this tool touches, because the bridge agent reading
+      # `linter_stderr` has no other view into the repository's spec files.
+      #
+      # 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.
+      #
+      # 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.
+      # It is emitted before the json early-return so both renderers get it —
+      # stderr is renderer-indifferent (SPGD-247; the SPGD-1134 selection
+      # sentence is the landed precedent, and the bridge forwards stderr
+      # verbatim as `linter_stderr`). The prefix is deliberately not
+      # `specguard-lint: checked`, which the selection-sentence pin counts.
+      def report_zero_annotation_files(selected_files, annotations, unread)
+        bare = selected_files - annotations.map(&:file) - unread.map(&:file)
+        return if bare.empty?
+
+        verb = bare.length == 1 ? "carries" : "carry"
+        @stderr.puts "specguard-lint: note: #{bare.length} of #{selected_files.length} checked " \
+                     "spec file#{'s' unless selected_files.length == 1} #{verb} no @intent " \
+                     "annotations: #{bare.join(', ')}"
+      end
+
       # The summary line exists for one reason — so "checked nothing" can never
       # read as "all clean" — which makes overstating what was inspected its
       # own kind of lie. A file that could not be opened contributed no

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.10"
+  VERSION = "0.3.12"
 end

metadata

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