specguard-ruby 0.3.20 → 0.3.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c002b753148e4a915e801813a1c0ad88e94f5ac20cb8f39e42e8cf5a760aaf75
-  data.tar.gz: 97b24f72b61a48e3bbd27b8c95bc9ae8f26abd2e5028ef8ae525fe9f404995c0
+  metadata.gz: bd0ffc9c5541eedd7981fab7f1c213c1cc2196c57465933a7d2ebcf02caf3d57
+  data.tar.gz: 0cc713e7625792a198fec8988f9f7f54e15fa364793cefc91dc029e3f5ba8e21
 SHA512:
-  metadata.gz: 5e8c6b4fdc40bef297cb50af6fd86f6bcd38326c099e9d778305dcd0a8a4e44a4104269c37acbdbd44a7d37b4a5d44b84d404a80955b6866b0262cf2f3448543
-  data.tar.gz: c262a4876a218d3e264ffe9ea1fafdf2afa7cf16e60996cacbcad21e569830d60981ba9ed6c9abccbbe5ef0607ec6d99a80c98e482101ca8f62f187f0fb457b6
+  metadata.gz: 616d5a1bf1568db6f3b94227273f69df69a31a6a4f6ea9af762300fc063f29ec57b5a50e95f396e1c4af221ea6917cf06c78755d916b20618c379f9630697ddb
+  data.tar.gz: 8c3c74d0a97ab9728ff1d02f42fb8d0bf089c4f023051139fd7f405746918c9448923e976ef1865a6b52cfaba825e53e94a562f5e76e738415fef9c176ecfaab

data/README.md

@@ -95,7 +95,14 @@ genuinely bad ref. A selection that comes up empty stays exit `0` and says WHY
 on stderr — the exit contract is unchanged; only the WHY is truthful now.
 
 Files are **positional** (`specguard-lint spec/order_spec.rb`); there is no `--source` flag —
-that belongs to `validate-intent`, not to this one.
+that belongs to `validate-intent`, not to this one. Named paths must be **files**: a directory
+named as a positional argument is a usage error (exit `2`, `<path> is a directory; name files or
+run without paths`). The `validate-intent` binary would expand it as `DIR/**`, but its report
+carries only findings, so a clean file in that subtree appears nowhere and the linter could not
+honestly say what it checked — the run would contradict itself, counting one selected file beside
+several annotations and naming the directory as carrying none. Name the files, or pass no paths
+at all and let the walker select them. A path that does *not* exist is not refused here: it
+reaches the binary and comes back as a read finding, which is where a typo belongs.
 
 The linter is a thin CLI over the [`validate-intent`](https://github.com/yatfa-ai/open-test-intent)
 binary — the protocol's own reference implementation, which decides whether an annotation is valid
@@ -316,7 +323,9 @@ provenance line says which kind of "could not check" it was, in its own words:
 The gem's arguments are paths; the binary's are glob patterns. A path that matches nothing —
 missing, or not a regular file — reaches the gem as the same answer the binary gives both shapes
 (`no-match`), which the CLI re-words as `could not read file: no file at this path` and folds into
-the `read` kind. The binary's own UTF-8 refusal prose (`input is not well-formed UTF-8
+the `read` kind. A **directory** is not one of those shapes: the client refuses it up front (see
+"Files are positional" above), so it never reaches the binary and never becomes a read finding.
+The binary's own UTF-8 refusal prose (`input is not well-formed UTF-8
 (PROTOCOL.md §1.1 requires it)`) and parse-failure prose are passed through unaltered.
 
 Every way the backend can fail — the binary is missing, will not execute, exits with something that
@@ -695,6 +704,28 @@ The held-back lines are **counted and reported**, exactly as `--from-line`'s and
 the blank ones are — a summary that quietly narrowed what it was summarising
 would be worse than no summary.
 
+A number you typed that the file **does not have** is the same rule pointed the
+other way, and it gets its own clause rather than being left to the held-back
+count. On a file that stops short of what the spec named:
+
+```bash
+bundle exec specguard-ingest --list --lines 3,7,12-15,33-40 log/test_results.jsonl
+```
+
+```
+line 3: branch main, commit_sha 41f2c9b8…, ci_run_id 17442, 12 examples, 8.4s
+…
+specguard-ingest: listed 6 lines from log/test_results.jsonl; 26 lines not selected by --lines; --lines named 33-40, which the file does not have; nothing was delivered
+```
+
+A range that is only **half** answered says so on the same terms — the clause
+names the portion past the end of the file, in the shorthand you typed, because
+what you act on is the numbers you wrote. A line the file *does* have and that
+is blank is a blank line and is reported as one; only numbers past the end of
+the file reach this clause, so no line is ever named under two causes. The
+clause is additive: a file that is at once short, blank-bearing and
+selected-away states each cause and drops none of them.
+
 A spec is read strictly, and a bad one is a `2` rather than a fallback to the
 whole file — which is the one outcome a selector exists to prevent. `--lines 0`,
 `--lines 5-2`, `--lines abc`, `--lines 12-`, an empty spec and an empty entry
@@ -802,7 +833,7 @@ bundle exec specguard-ingest --json log/test_results.jsonl
   "file": "log/test_results.jsonl",
   "summary": { "lines": 3, "attempted": 3, "accepted": 2, "refused": 1,
                "undelivered": 0, "unparseable": 0, "blank": 0, "skipped": 0,
-               "selector": null },
+               "absent": null, "selector": null },
   "lines": [
     { "number": 1, "status": "accepted", "code": 202, "reasons": [],
       "test_run_id": "41f2c9b8", "ci_run_id": "17442" },
@@ -830,6 +861,7 @@ bundle exec specguard-ingest --json log/test_results.jsonl
 | `summary.attempted` | how many of those were offered to the endpoint — always `0` under `--list`, and `lines` minus the unparseable ones otherwise |
 | `summary.accepted` / `refused` / `undelivered` / `unparseable` | the same four counts the text summary line states, computed once for both renderers so they cannot disagree |
 | `summary.blank` / `skipped` | the two ways a line of the file is not a row here, counted rather than dropped |
+| `summary.absent` | the `--lines` numbers the file does not have, in the shorthand you typed them — a number or an `N-M` range per entry — or `null` when the selector was fully satisfied; never `[]`, on `selector`'s terms |
 | `summary.selector` | `"--lines"`, `"--from-line"`, or `null` when nothing was held back |
 | `lines[]` | one entry per row, in the file's order |
 | `foldings[]` | folding, **observed**: the lines that went out with one `ci_run_id` and came back with one `test_run_id`. The same statement the text report makes as a sentence |

data/lib/specguard/rspec/cli.rb

@@ -248,6 +248,28 @@ module SpecGuard
                   "(named files are checked as given, --changed derives them from the diff)"
           end
 
+          # SPGD-1303: a directory named as an explicit path is refused, not
+          # expanded. The shared `validate-intent` binary learned to expand a
+          # bare directory as `DIR/**` (oti SPGD-1299), so one argument stopped
+          # meaning one file — and the client's document carries only FINDINGS,
+          # so a clean file in that subtree appears nowhere and "checked N spec
+          # files" can never count what was actually validated. The observed
+          # result was a run whose header said `checked 1 spec file`, whose
+          # summary said `checked 3 @intent annotations`, and whose
+          # zero-annotation note claimed the directory carried none — three
+          # mutually contradicting sentences, and at its sharpest an exit-0
+          # false green. Honest accounting is impossible here without an oti
+          # wire-contract change, so refusal is the only coherent client-side
+          # state. Same sentence as the ts client's `discover.ts` explicit arm.
+          # `File.directory?` follows symlinks, so a symlinked directory is the
+          # same class; a nonexistent path is NOT a directory and still reaches
+          # the binary, where the no-match finding belongs.
+          options[:files].each do |path|
+            next unless File.directory?(path)
+
+            raise UsageError, "#{path} is a directory; name files or run without paths"
+          end
+
           return FileSelector::Selection.new(files: options[:files], mode: :explicit)
         end
 

data/lib/specguard/rspec/ingest_cli.rb

@@ -349,7 +349,19 @@ module SpecGuard
       # the summary can say. The blanks and the skips are counted rather than
       # dropped because a summary that quietly narrows what it is summarising is
       # the failure this project keeps finding.
-      Source = Struct.new(:path, :lines, :blank, :skipped, :selector, keyword_init: true)
+      #
+      # `absent` is the same discipline applied one layer later, to the lines
+      # that were *typed* rather than to the lines that were read. A `--lines`
+      # entry can name a line past the end of the file, and such a number is not
+      # held back — there was nothing there to hold — so `skipped` cannot carry
+      # it and the file's own counts cannot state it. It is derived from the
+      # file's length in {#read_source} and rendered in the shorthand it was
+      # typed in, because the user acts on what they typed. Empty when the
+      # selector was fully satisfied, and empty under `--from-line`, whose
+      # past-the-end case is already a suffix that selected nothing.
+      #
+      # @return [Array<String>] `absent`, each entry a number or an `N-M` range
+      Source = Struct.new(:path, :lines, :blank, :skipped, :absent, :selector, keyword_init: true)
 
       # What the command line asked for. A struct rather than a bare path,
       # because `--from-line` is the second half of the same question — which
@@ -550,6 +562,7 @@ module SpecGuard
 
         parts << blank_clause(source) if source.blank.positive?
         parts << skipped_clause(source) if source.skipped.positive?
+        parts << absent_clause(source) if source.absent.any?
         parts << "nothing was delivered"
 
         parts.join("; ")
@@ -655,6 +668,12 @@ module SpecGuard
         lines = []
         blank = 0
         skipped = 0
+        # The file's length, counted rather than inferred: `with_index` is
+        # already running and discards its last `number`, and a counter that
+        # starts at 0 says "no lines" about an empty file where a nil would say
+        # "not known". It is what {#absent_entries} measures the typed numbers
+        # against.
+        length = 0
 
         # Numbered from the file, not from the payloads: a blank line still
         # advances the count, so line 12 in this report is line 12 in an editor.
@@ -670,6 +689,8 @@ module SpecGuard
         # the file still delivers. Swallowing it here would lose a line silently
         # and letting it raise would report a bug in this tool.
         File.foreach(path).with_index(1) do |text, number|
+          length = number
+
           if held_back?(number, options)
             skipped += 1
           elsif text.valid_encoding? && text.strip.empty?
@@ -680,6 +701,7 @@ module SpecGuard
         end
 
         Source.new(path: path, lines: lines, blank: blank, skipped: skipped,
+                   absent: absent_entries(options, length),
                    selector: options.line_set ? :line_set : :from_line)
       rescue SystemCallError, IOError => e
         raise UsageError, "could not read #{path}: #{e.message}"
@@ -695,6 +717,39 @@ module SpecGuard
         number < options.from_line
       end
 
+      # The typed numbers the file does not have, in the shorthand they were
+      # typed in.
+      #
+      # Computed over line NUMBERS rather than over entries, which is what makes
+      # a half-satisfied range the same fact as a wholly unsatisfied one: a
+      # range running past the end of the file has named lines that were typed
+      # and delivered nothing, exactly as a lone out-of-range number has. Each
+      # entry contributes only the portion above the file's length, so the
+      # clause names the unanswered part rather than the entry that was half
+      # honoured, and a range stays a range rather than becoming a list of
+      # numbers the user would have to read back into what they wrote.
+      #
+      # `--from-line` contributes nothing: it is a suffix, and a suffix past the
+      # end of the file already says so through the lines it held back.
+      #
+      # A line the file HAS and that is blank is not here and must never be —
+      # `blank` already says "you named a line that exists and holds nothing",
+      # and stating both would be one line reported under two causes. The
+      # comparison is against the file's length alone, which is what keeps that
+      # true rather than merely usually true.
+      #
+      # @return [Array<String>]
+      def absent_entries(options, length)
+        return [] unless options.line_set
+
+        options.line_set.filter_map do |range|
+          first = [range.first, length + 1].max
+          next if first > range.last
+
+          first == range.last ? first.to_s : "#{first}-#{range.last}"
+        end.uniq
+      end
+
       # The per-line report on stdout — it is the product — with the diagnostics
       # about this tool's own situation on stderr, which is the split
       # `specguard-lint` already makes. `--json` moves the product and leaves the
@@ -748,10 +803,14 @@ module SpecGuard
       # is empty". A `--from-line` past the end of the file, a `--lines` that
       # names only lines the file does not have, and a genuinely empty file are
       # the same silence otherwise, and only two of them are the user's mistake.
+      # The third clause is what tells the second of those from the first: a
+      # held-back count alone is the file's own length read back, which a reader
+      # can mistake for a selector that did something.
       def empty_detail(source)
         parts = []
         parts << "#{source.blank} blank line#{'s' unless source.blank == 1}" if source.blank.positive?
         parts << skipped_clause(source) if source.skipped.positive?
+        parts << absent_clause(source) if source.absent.any?
 
         parts.empty? ? "" : " (#{parts.join('; ')})"
       end
@@ -768,6 +827,16 @@ module SpecGuard
         "#{count} earlier line#{'s' unless count == 1} skipped by --from-line"
       end
 
+      # The typed numbers the file does not have, named rather than counted.
+      # {#skipped_clause}'s counterpart for the other direction: that one says
+      # how much of the FILE the selector held back, and this one says how much
+      # of the SELECTOR the file could not answer. A count would be the wrong
+      # shape here — the reader's next action is editing the numbers they typed,
+      # so the clause hands those numbers back in the form they wrote them.
+      def absent_clause(source)
+        "--lines named #{source.absent.join(', ')}, which the file does not have"
+      end
+
       def blank_clause(source)
         "#{source.blank} blank line#{'s' unless source.blank == 1} skipped"
       end
@@ -806,6 +875,7 @@ module SpecGuard
         parts << "#{counts[:unparseable]} could not be parsed" if counts[:unparseable]
         parts << blank_clause(source) if source.blank.positive?
         parts << skipped_clause(source) if source.skipped.positive?
+        parts << absent_clause(source) if source.absent.any?
 
         parts.join("; ")
       end

data/lib/specguard/rspec/ingest_reporter.rb

@@ -105,7 +105,8 @@ module SpecGuard
       STATUS_LISTED = "listed"
       STATUS_UNPARSEABLE = "unparseable"
 
-      # @param source [IngestCLI::Source] the file, its blanks and its skips
+      # @param source [IngestCLI::Source] the file, its blanks, its skips and
+      #   the typed lines it does not have
       # @param results [Array<IngestCLI::LineResult>] one per line delivered,
       #   in the file's order
       # @param counts [Hash{Symbol=>Integer}] status counts, computed once by
@@ -167,6 +168,15 @@ module SpecGuard
       # here. They are stated always, and for the reason {IngestCLI::Source}
       # counts rather than drops them: a summary that quietly narrows what it is
       # summarising is the failure this command is arranged against.
+      #
+      # `absent` is that same rule pointed the other way — at the numbers that
+      # were typed rather than at the lines that were read. A `--lines` entry
+      # naming past the end of the file is held back by nothing and read as
+      # nothing, so `skipped` (which counts lines of <file>) structurally cannot
+      # carry it, and without this key a satisfied selector and a phantom one
+      # render the identical document. It is `null` rather than `[]` where the
+      # selector was fully satisfied, on {#selector}'s terms: a fact that does
+      # not apply is absent, never a fabricated empty.
       def self.summary(source, lines:, counts:, attempted:)
         {
           "lines" => lines,
@@ -177,10 +187,21 @@ module SpecGuard
           "unparseable" => counts.fetch(:unparseable, 0),
           "blank" => source.blank,
           "skipped" => source.skipped,
+          "absent" => absent(source),
           "selector" => selector(source)
         }
       end
 
+      # The typed line numbers the file does not have, in the shorthand they
+      # were typed in and computed by {IngestCLI} once for both renderers — the
+      # discipline the counts above are held to, applied to the one fact the
+      # text summary and this document could otherwise disagree about.
+      #
+      # @return [Array<String>, nil]
+      def self.absent(source)
+        source.absent.empty? ? nil : source.absent
+      end
+
       # Every line that reached the endpoint, which is every line except the
       # ones that were never a run.
       def self.attempted(counts)
@@ -275,7 +296,8 @@ module SpecGuard
         Array(values).filter_map { |value| value.scrub("") if value.is_a?(String) }
       end
 
-      private_class_method :document, :summary, :attempted, :selector, :delivered, :listed, :folded, :reasons
+      private_class_method :document, :summary, :attempted, :absent, :selector, :delivered, :listed, :folded,
+                           :reasons
     end
   end
 end

data/lib/specguard/rspec/scanner.rb

@@ -45,13 +45,27 @@ module SpecGuard
       #   that matters more — a missing file does not stop either tool checking
       #   the good files named beside it.
       #
-      #   A path that exists and is NOT A REGULAR FILE lands in the same rescue
-      #   and is the same ratified difference one step further out: this rescue
-      #   has an errno and reports it (`Is a directory @ io_fread - <path>`),
-      #   while the binary's glob filters non-regular matches away and answers
-      #   exactly as it does for a name matching nothing. Ruby tells the two
-      #   apart and the backend cannot — asserted under "a path that is not a
-      #   regular file" in that same spec.
+      #   A path that EXISTS and is not a regular file is the same ratified
+      #   difference one step further out. The binary's arguments are glob
+      #   PATTERNS whose matches are filtered to regular files, so such a path
+      #   folds into the answer a name matching nothing gets — the backend has
+      #   nothing else to say about it. This linter does no globbing and hands
+      #   the path to `File.read` as given, so what comes back is whatever
+      #   reading THAT path does, and never what a nonexistent path gets: the
+      #   path is there to be opened, so the failure it does or does not produce
+      #   is a fact about the path rather than about a pattern. Ruby tells the
+      #   two apart and the backend cannot — asserted under "a path that is not
+      #   a regular file" in that same spec, whose subject is a path that
+      #   exists, is not a regular file, and is not a directory.
+      #
+      #   A DIRECTORY is NOT an example of this difference, on either side.
+      #   `CLI#select` refuses one named as an explicit path (SPGD-1303) and
+      #   `--changed` derives its list from git, so a directory is settled
+      #   before this rescue is reached and never reaches the backend either.
+      #   What the shared binary makes of a bare directory argument has moved
+      #   upstream more than once and is deliberately not restated here: the
+      #   difference above is a property of the two sides' path semantics, and
+      #   nothing about a directory is needed to state it.
       def scan_file(path)
         begin
           text = File.read(path, encoding: "UTF-8")

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.20"
+  VERSION = "0.3.22"
 end

metadata

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