specguard-ruby 0.3.8 → 0.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df7e70603cb326ea7db7783c95263a418f42b2a2472c81af5013942e31e4a936
-  data.tar.gz: e586dcea9b754ec7f953c4cbf9c24f661fc410916551cca16e5cfc39a80941b9
+  metadata.gz: 6266c2bcd8775838ab93bbb3963cb007465575ee038f67490161fa64e10e982e
+  data.tar.gz: 7799e565338f59d3a76b4b19e19a0877dd172072e772e8cc81909f5d040d3ec7
 SHA512:
-  metadata.gz: 7e5ca1fac05f5891a127a59bf052b2c7840738880a6d2f94c0aaa608cfb5f967af5aec59910c340af09c19fae22a791d12941071ba826d93a8cf04c171380e4a
-  data.tar.gz: 5b91217eb10b3552f8c83a3890a3d2fc69e2740f0572f20f4980c9b372dd2d6e13a35575609b030947db53cd86f71a384b9d83c66adc6d04b311b5f422dbbe35
+  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/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.8"
+  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.8
+  version: 0.3.9
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json