specguard-ruby 0.3.7 → 0.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5e2b2a3d9b1a8ac1a2ceb473dd6a20d138a556a020c01361322a94402fe041d
-  data.tar.gz: e6ad790808c23a15561ce0f4f9367ee8f7661bf81013d04cde941f8d8faa5ddb
+  metadata.gz: 6266c2bcd8775838ab93bbb3963cb007465575ee038f67490161fa64e10e982e
+  data.tar.gz: 7799e565338f59d3a76b4b19e19a0877dd172072e772e8cc81909f5d040d3ec7
 SHA512:
-  metadata.gz: 846b95f016d702722fb1e54cedab222b536950cf4c18223c877c9e9d1aa348a34a6ff2627b1b1d4391939f04dbdf3e11651e90e85eb326d98cf5b04436db4b1c
-  data.tar.gz: e1a4b80ec07dfc9c63c69c6289f8407b645518da6b95bef7b1c302b206c68060be5ce5f1fd7fc33e9a4880fac97558894b533a116607c3e43156b30f366b72f2
+  metadata.gz: 3e811640885a89c54dec7bd69702ca429b0f28f5bfdd7c76fd049d15621da4ce0b48323af914448236877f9bc40df78df642232cda89dbfef5a0adcd85612ed7
+  data.tar.gz: 28e11252d3051943734247a9878a50680ee719cff789a1ea53da11041574529ed5d9e3761c5445f33b84b0ae42994ae121d35895ec6c0f33fd2c8045163c329e

data/README.md

@@ -54,6 +54,22 @@ bundle exec specguard-lint --changed   # CI mode: only files in the current diff
 bundle exec specguard-lint             # one-off audit: every *_spec.rb
 ```
 
+`--changed` is the CI selection mode: it diffs against the **merge base with
+the default branch** (`origin/HEAD`, then `origin/main`/`origin/master`, then
+their local names) — never a bare working-tree-vs-index `git diff`, which is
+empty on a clean checkout. `--changed=<base>` overrides the base for pipelines
+that know better. In a **shallow** checkout — the default depth-1 `git clone`
+behind `actions/checkout@v4` — the merge base with the default branch is not
+in the clone's history, so the derived base is HEAD itself and the selection
+comes up empty: it still exits `0`, but its stderr note (and `--json`
+`selection.note`) names the checkout as **shallow** and the remedy — fetch the
+default branch (`fetch-depth: 0`) or pass `--changed=<base>` naming a base the
+checkout contains. An explicit `--changed=<base>` that is not in a shallow
+checkout's history is a usage error (exit `2`) naming that cause and the same
+remedy, not the bare "could not diff against" a full clone reports for a
+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.
 

data/lib/specguard/minitest/reporter.rb

@@ -69,13 +69,6 @@ module SpecGuard
         end
       end
 
-      # Internal, never on the wire: `record` stashes the result's own method
-      # name under this key so `uniquify_ids!` can re-identify colliding rows
-      # at delivery time, and `uniquify_ids!` strips it again before the
-      # payload is built. The underscore prefix exists so a leak onto the
-      # wire would be loud in any payload diff rather than plausible.
-      RESULT_NAME_KEY = "_specguard_result_name"
-
       def initialize(configuration: SpecGuard::RSpec.configuration,
                      transport: nil, output: $stderr,
                      annotations: SpecGuard::RSpec::AnnotationLookup.new,
@@ -113,9 +106,6 @@ module SpecGuard
         row = row_for(result)
         return unless row
 
-        # Stashed for `uniquify_ids!` (and stripped there) — the one
-        # unique-per-result token a Minitest row has. See that method.
-        row[RESULT_NAME_KEY] = result.name.to_s
         @rows << row
       rescue ScriptError, StandardError
         nil
@@ -153,21 +143,32 @@ module SpecGuard
       # parallel mode records from its worker threads through this one shared
       # reporter — so the collision is detectable exactly once, at delivery.
       # Every member of a colliding group is re-identified as
-      # `"#{file}:#{line}##{method_name}"`: a method name is unique per
-      # class and deterministic, so the suffixed ids are stable across runs.
-      # ALL members take the suffix, never just later arrivals — parallel
+      # `"#{file}:#{line}##{Klass#method_name}"`, suffixed with the row's own
+      # class-qualified wire `name` — not the bare method name, which stops
+      # distinguishing results the moment TWO classes share one `define_method`
+      # call site (Rails' declarative `test "desc"` helper is exactly that
+      # shape: one `define_method` inside activesupport, shared by every test
+      # class in the suite) and generate identically-named methods. The
+      # class-qualified name is unique per result and deterministic, so the
+      # suffixed ids are stable across runs. The token is read straight off
+      # the row rather than stashed at `record` time: `row["name"]` already IS
+      # `"#{result.klass}##{result.name}"`, so a sidecar would be a
+      # byte-identical copy of a value already on the wire — redundant state
+      # and one more thing that could leak. ALL members take the suffix,
+      # never just later arrivals — parallel
       # mode's arrival order is fork scheduling, so "the first row keeps the
       # bare id" would make identity depend on it. Rows whose id no other
       # row claims — every plain `def test_` suite among them — keep the id
-      # they always had, byte for byte.
+      # they always had, byte for byte. The id remains the run-local primary
+      # key for one delivered payload and never a cross-run stable identity:
+      # cross-run matching remains name + file, the platform's own rule.
       def uniquify_ids!
         counts = Hash.new(0)
         @rows.each { |row| counts[row["id"]] += 1 }
         @rows.each do |row|
-          name = row.delete(RESULT_NAME_KEY)
-          next unless counts[row["id"]] > 1 && !name.to_s.empty?
+          next unless counts[row["id"]] > 1
 
-          row["id"] = "#{row["id"]}##{name}"
+          row["id"] = "#{row["id"]}##{row["name"]}"
         end
       end
 

data/lib/specguard/rspec/file_selector.rb

@@ -43,6 +43,16 @@ module SpecGuard
     # There is no diff base that makes "what changed on this build" non-empty
     # there.
     #
+    # A **shallow** checkout — the depth-1 clone CI defaults to
+    # (`actions/checkout@v4`) — reaches the same thin base by a third road the
+    # ref-resolution above cannot see: every `DEFAULT_BRANCH_REFS` probe
+    # *resolves* (the fetched tip is in the clone), but the history behind it
+    # is not, so the merge base with the default branch is outside the clone
+    # and `merge-base` collapses onto HEAD. The notes below therefore consult
+    # `git rev-parse --is-shallow-repository` — lazily and memoized, only
+    # where the answer changes the message — and in a shallow clone say that,
+    # never "default-branch build".
+    #
     # That is why the load-bearing requirement is the **loud empty selection**,
     # not the base. The caller must never be unable to tell "checked 12 files,
     # found no annotations" from "checked 0 files" — {Selection} carries the
@@ -157,17 +167,21 @@ module SpecGuard
                 "and no HEAD commit); pass --changed=<base> explicitly"
         end
 
-        files, stats = changed_files(resolved, root)
+        # One memoized probe per run, shared by the two message branches that
+        # consult it (a failed diff, a thin base note).
+        is_shallow = shallow_probe(root)
+
+        files, stats = changed_files(resolved, root, is_shallow)
 
         Selection.new(files: files, mode: :changed, base: resolved,
-                      note: base_note(resolved, base_kind, root), stats: stats)
+                      note: base_note(resolved, base_kind, root, is_shallow), stats: stats)
       end
 
       # Resolves git's repo-root-relative output into paths relative to `root`,
       # dropping (and counting) everything the two scoping rules exclude.
       # @return [[Array<String>, Stats]]
-      def changed_files(base, root)
-        names = diff_names(base, root)
+      def changed_files(base, root, is_shallow)
+        names = diff_names(base, root, is_shallow)
         specs = names.select { |name| CHANGED_PATTERNS.any? { |pattern| File.fnmatch?(pattern, name) } }
 
         top = toplevel(root)
@@ -198,9 +212,23 @@ module SpecGuard
       # them, and they then fail to open. `-z` makes the output machine-readable:
       # NUL-separated and never `core.quotePath`-quoted, so a non-ASCII path
       # survives intact and a path containing a newline cannot split a record.
-      def diff_names(base, root)
+      def diff_names(base, root, is_shallow)
         out, ok = git(%W[diff -z --name-only --diff-filter=d #{base} --], root)
-        raise UsageError, "--changed could not diff against #{base.inspect}" unless ok
+        unless ok
+          if is_shallow.call
+            # SPGD-1035: in a shallow checkout the overwhelmingly likely cause
+            # is that <base> is simply not in the clone's history (git's own
+            # stderr says `fatal: bad object` / `unknown revision`), and the
+            # fix is a fetch — a cause the bare message never named, leaving
+            # "bad ref" and "shallow history" indistinguishable. Non-shallow
+            # failures keep the original message.
+            raise UsageError,
+                  "--changed could not diff against #{base.inspect}: this checkout is shallow and " \
+                  "#{base.inspect} is not in its history — fetch it (fetch-depth: 0, or " \
+                  "git fetch origin #{base}) or pass a base the checkout contains"
+          end
+          raise UsageError, "--changed could not diff against #{base.inspect}"
+        end
 
         out.split("\0").reject(&:empty?)
       end
@@ -241,20 +269,60 @@ module SpecGuard
       # `git diff HEAD`, i.e. the working-tree-vs-HEAD no-op this class exists
       # to avoid. Reporting the first when the second is true would be a
       # confidently wrong explanation.
-      def base_note(resolved, base_kind, root)
+      #
+      # SPGD-1035: a shallow (depth-limited) checkout reproduces both thin
+      # shapes with a third cause those two stories miss — the merge base with
+      # the default branch is not in the clone's history at all — so whenever
+      # the repo IS shallow the note tells that story and names the remedy
+      # (fetch the default branch, or pass a base the checkout contains),
+      # retiring the "default-branch build" guess for shallow repos in both
+      # shapes.
+      def base_note(resolved, base_kind, root, is_shallow)
+        shallow_remedy =
+          "fetch the default branch (fetch-depth: 0) or pass --changed=<base> naming a base this checkout contains"
         case base_kind
         when :head_fallback
+          if is_shallow.call
+            return "this checkout is a shallow (depth-limited) clone and no default-branch ref " \
+                   "(#{DEFAULT_BRANCH_REFS.join(', ')}) is in its history, so the diff base fell " \
+                   "back to HEAD; --changed can only select uncommitted changes here — #{shallow_remedy}"
+          end
+
           "no default-branch ref (#{DEFAULT_BRANCH_REFS.join(', ')}) could be found, so the diff base " \
             "fell back to HEAD; --changed can only select uncommitted changes here"
         when :merge_base
           head, ok = git(%w[rev-parse HEAD], root)
           return nil unless ok && head.strip == resolved
 
+          if is_shallow.call
+            return "this checkout is a shallow (depth-limited) clone, so the merge base with the " \
+                   "default branch is not in its history and the diff base is HEAD itself — only " \
+                   "uncommitted changes can be selected; #{shallow_remedy}"
+          end
+
           "the diff base is HEAD itself (this looks like a default-branch build), " \
             "so only uncommitted changes can be selected"
         end
       end
 
+      # Memoized per-run `git rev-parse --is-shallow-repository` probe.
+      # SPGD-1035: shallowness is consulted only in the branches where it
+      # changes the message (a derived base of HEAD, a failed diff), so the
+      # full-clone happy path makes zero new git invocations and the memo caps
+      # the probe at one per run. An unreadable answer (old git without the
+      # flag) reads as not shallow, keeping today's messages exactly.
+      # @return [Proc] zero-argument; true iff git reports a shallow repository
+      def shallow_probe(root)
+        cached = nil
+        lambda do
+          if cached.nil?
+            out, ok = git(%w[rev-parse --is-shallow-repository], root)
+            cached = ok && out.strip == "true"
+          end
+          cached
+        end
+      end
+
       def git_repository?(root)
         out, ok = git(%w[rev-parse --is-inside-work-tree], root)
         ok && out.strip == "true"

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

metadata

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