specguard-ruby 0.3.8 → 0.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df7e70603cb326ea7db7783c95263a418f42b2a2472c81af5013942e31e4a936
-  data.tar.gz: e586dcea9b754ec7f953c4cbf9c24f661fc410916551cca16e5cfc39a80941b9
+  metadata.gz: c7d1dfb3eb7af542eee8c1202dae06dd0d9c3981f5415d12875037c9a9067944
+  data.tar.gz: 9d785e02b70ea9e06b0d0cf55ce31cbb1d67c841ea36fb0b7f3c7217a8f20304
 SHA512:
-  metadata.gz: 7e5ca1fac05f5891a127a59bf052b2c7840738880a6d2f94c0aaa608cfb5f967af5aec59910c340af09c19fae22a791d12941071ba826d93a8cf04c171380e4a
-  data.tar.gz: 5b91217eb10b3552f8c83a3890a3d2fc69e2740f0572f20f4980c9b372dd2d6e13a35575609b030947db53cd86f71a384b9d83c66adc6d04b311b5f422dbbe35
+  metadata.gz: 3d5ae9e309ae02ea33679223f712d04edf7c9e06aab22f011fde61484f2f3c8d2c992b02b792caceeb934b63136734840cdd01d0dbe62619b695dd09c3ceb238
+  data.tar.gz: 3d3f373483219a5cdbeecdf639065bd99cb90dd648acf4bd75174ae9eba6adefcfc94a6458577480bb526dc636d88b139a4742cda3c12269a320bd5e7f994a3f

data/README.md

@@ -54,6 +54,31 @@ 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. Selection also takes in **untracked** files: a brand-new
+spec that has not been `git add`ed is part of what the branch changed, whether
+or not the change is committed yet. One `git ls-files --others
+--exclude-standard` call per run is unioned with the diff — `.gitignore`d
+paths (scratch directories, vendored code, build output) never enter the
+selection — and untracked files obey the same scoping as diffed ones, so an
+untracked spec outside the current directory is counted as outside, not
+checked. When the untracked leg contributed, the `checked N spec files changed
+since <base>` line says `including M untracked`.
+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/cli.rb

@@ -228,14 +228,23 @@ module SpecGuard
       # `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.
+      #
+      # The `--changed` count names its provenance: files can reach the
+      # selection through the untracked leg (`file_selector.rb`), and "changed
+      # since <base>" alone over-claims for a file the diff never saw. When
+      # the untracked leg contributed, the line says how many — the same
+      # `stats.untracked` the selection carries, so the clause can only ever
+      # name files this run actually checked.
       def report_selection(selection, json:)
         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}"
+                       "#{" under #{Dir.pwd}" if selection.mode == :all}" \
+                       "#{" including #{untracked} untracked" if untracked.positive?}"
         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
@@ -77,10 +87,32 @@ module SpecGuard
     # quotes and all, which no longer names a file — an accented spec file would
     # be silently dropped and then misreported as "nothing changed".
     #
-    # Known limitation: `git diff` cannot see **untracked** files, so a brand
-    # new spec file that has not been `git add`ed is not selected. In CI (a
-    # clean checkout of a commit) that cannot arise; locally the loud empty
-    # selection is what surfaces it.
+    # == Untracked files are selected too
+    #
+    # `git diff` cannot see a file that has never been `git add`ed — but "what
+    # this branch changed, whether or not the change is committed yet" covers a
+    # never-added file, and a mode that silently skipped it would ride the
+    # branch's newest spec past the gate: in the mixed shape every real working
+    # tree has (a tracked edit somewhere, the new spec still untracked), the
+    # selection was non-empty without the new file, so the loud-empty machinery
+    # never fired and the defect shipped behind a checked-count reporting
+    # success.
+    #
+    # So the `--changed` name set is a union: the diff's paths plus ONE
+    # `git ls-files --others --exclude-standard -z` call per selection, run at
+    # the toplevel so its repo-root-relative output flows through the same
+    # scoping as the diff's (from a subdirectory `ls-files` emits
+    # cwd-relative paths, which would defeat it). `--exclude-standard` is the
+    # boundary: `.gitignore`d paths — scratch directories, vendored code, build
+    # output — never enter the selection. The two legs are disjoint by
+    # construction (an untracked path is never a diff path), so the union
+    # cannot double-count; {Stats.untracked} says how many of the selected
+    # files arrived via the untracked leg, and the empty-reason ladder's
+    # "nothing changed against <base>" can now only fire when the working tree
+    # is genuinely clean. That `ls-files` call is the untracked leg's entire
+    # added cost, and it is scoped to this mode — the "zero new git
+    # invocations on the full-clone happy path" property SPGD-1035 established
+    # belongs to the lazy shallow probe alone, not to `--changed` as a whole.
     module FileSelector
       # `test/**/*_test.rb` rather than `**/*_test.rb`: the `test/` directory
       # is where both Rails and Minitest itself put Minitest files, and
@@ -102,9 +134,13 @@ module SpecGuard
 
       # Why an empty `--changed` selection is empty. Every count is a filter
       # this class applied, in the order it applied them, so the CLI can name
-      # the real cause instead of guessing at the last one.
-      Stats = Data.define(:changed, :spec_matches, :outside_root, :unreadable) do
-        def initialize(changed: 0, spec_matches: 0, outside_root: 0, unreadable: 0)
+      # the real cause instead of guessing at the last one. The exception is
+      # `untracked`, which filters nothing: it counts the selected files that
+      # arrived via the untracked leg, so the report can say where a file the
+      # diff never saw came from (an untracked spec outside `root` is counted
+      # in `outside_root`, not here — this names files the run checked).
+      Stats = Data.define(:changed, :spec_matches, :outside_root, :unreadable, :untracked) do
+        def initialize(changed: 0, spec_matches: 0, outside_root: 0, unreadable: 0, untracked: 0)
           super
         end
       end
@@ -157,27 +193,42 @@ 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.
+      # dropping (and counting) everything the two scoping rules exclude. The
+      # name set is the union of the diff leg and the untracked leg; each name
+      # is tagged with its leg so {Stats.untracked} can attribute the selected
+      # files the diff never saw. The legs are disjoint by construction (an
+      # untracked path is never a diff path), so the plain union cannot
+      # double-count and needs no dedup.
       # @return [[Array<String>, Stats]]
-      def changed_files(base, root)
-        names = diff_names(base, root)
-        specs = names.select { |name| CHANGED_PATTERNS.any? { |pattern| File.fnmatch?(pattern, name) } }
+      def changed_files(base, root, is_shallow)
+        names = diff_names(base, root, is_shallow).map { |name| [name, false] }
 
         top = toplevel(root)
+        names += untracked_names(top.empty? ? root : top).map { |name| [name, true] }
+
+        specs = names.select { |(name, _)|
+          CHANGED_PATTERNS.any? { |pattern| File.fnmatch?(pattern, name) }
+        }
+
         prefix = directory_prefix(top.empty? ? root : top)
         root_prefix = directory_prefix(real_path(root))
 
         files = []
         outside = 0
         unreadable = 0
-        specs.each do |name|
+        untracked = 0
+        specs.each do |(name, was_untracked)|
           absolute = prefix + name
           relative = strip_prefix(absolute, root_prefix)
           if relative.nil?
@@ -186,25 +237,60 @@ module SpecGuard
             unreadable += 1
           else
             files << relative
+            untracked += 1 if was_untracked
           end
         end
 
         [files.sort,
          Stats.new(changed: names.length, spec_matches: specs.length,
-                   outside_root: outside, unreadable: unreadable)]
+                   outside_root: outside, unreadable: unreadable, untracked: untracked)]
       end
 
       # `--diff-filter=d` drops deleted paths — `git diff --name-only` lists
       # 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
 
+      # The untracked leg of `--changed`: every file git does not track, minus
+      # what `--exclude-standard` excludes (`.gitignore`, `.git/info/exclude`,
+      # the global excludes file). Run at the toplevel, where `ls-files` emits
+      # repo-root-relative paths — from a subdirectory it emits cwd-relative
+      # ones, which would break the root-scoping the diff leg's output goes
+      # through. `-z` for the same reason as {diff_names}: NUL-separated and
+      # never `core.quotePath`-quoted. Without `--directory` git lists the
+      # files inside an untracked directory rather than the directory itself,
+      # which is what the suffix filter wants. `ls-files` reads the working
+      # tree and the index only — no history — so the leg works in a shallow
+      # clone where the diff base barely exists. A failure degrades to an
+      # empty leg rather than failing the run: the repository was already
+      # verified, the tracked diff above remains the primary evidence, and a
+      # half-readable working tree must not kill a gate that would otherwise
+      # check every tracked spec.
+      def untracked_names(chdir)
+        out, ok = git(%w[ls-files --others --exclude-standard -z], chdir)
+        ok ? out.split("\0").reject(&:empty?) : []
+      end
+
       # The repository's top level — what `git diff`'s paths are relative to.
       # Empty when git cannot say, in which case the caller falls back to `root`
       # (the top level *is* root for the common case of running from there).
@@ -241,20 +327,63 @@ 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
+      # probe makes zero new git invocations of its own on the full-clone
+      # happy path, and the memo caps it at one per run. (That zero is the
+      # probe's, not the mode's: the untracked leg adds its one `ls-files`
+      # call to every `--changed` selection, whatever the clone's depth.) 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.10"
 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.10
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json