stud-finder 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c203b1ef550bd6c05b1f07211cbad55d55520dcbf081ec59f24ab955c3a34d8
-  data.tar.gz: 10c285f7512708afda1af1a3c8f0b629eccdddc45aee9ac1cd2869c44af86f64
+  metadata.gz: faa8060a75346fc7a402adf203764c650d1596c2c6b3f4cb25571b3b21ecfa7a
+  data.tar.gz: 9c26eed3cb20c42d0155a730ba0ff70f9893a43493bf49d633aea4a0a2036a79
 SHA512:
-  metadata.gz: 2d68892673ccaed71bde8f223ae5d1098033aeee65ca89bb7b21c301edf7a3eb7a7745cd5e70df24bbdb779a70d6f44ddbe4ccab324ff4731fba47f8c3a01cef
-  data.tar.gz: 704e0964915bbe5dce1628d082e5eccb6e1376bdd9919ace07251000892432373f94e61d1f2cebb91442feda1cef50358aeda31c2e30ed95e5414529ce5479ce
+  metadata.gz: 863567f3e6dedd1808075bf9ae272cdb3f2e5b3b849b0eaa3b7b829a0db56873b757e6587d4fc82b6460fe6ab993407de24742fdde86d6bea6cb9809eb388ec0
+  data.tar.gz: a0a6d9b9fb0ad35bd88e22e26c24eb72957d22c46fd138e0e4c8b7da2bbcc885c5fb7f23bc58db547b826c754a478d72aa9b6cf0b3b04c81fa1801ef11fc903a

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - Unreleased
+
+### Changed
+
+- BREAKING: Evidence formula changed — coverage is now a bonus, not a required third signal. The new formula is `max(history_only, with_coverage)` where `history_only = (age + commits) / 2`. Mature files without a coverage report now produce `evidence: 1.0` instead of the old ceiling of `0.6667`. Files with coverage data can only equal or exceed the history-only baseline, never fall below it.
+
+### Fixed
+
+- Shallow-clone evidence null in CI: when Stud Finder detects a depth-1 clone (GitHub Actions default), it now automatically runs `git fetch --unshallow` (45 second timeout) before computing newness metadata. Repos that used the default `actions/checkout` without `fetch-depth: 0` now get real evidence values instead of `null` on every row.
+
+### Added
+
+- `--no-auto-unshallow` flag: opt out of the automatic `git fetch --unshallow` on shallow clones. When set, Stud Finder behaves as before — shallow clone disables newness and emits only `shallow_clone_newness_disabled`.
+- `shallow_clone_unshallow_failed` warning code: fires when auto-unshallow was attempted but failed (network error, timeout, or non-zero exit). Appears alongside `shallow_clone_newness_disabled` so consumers can distinguish "unshallow was never tried" from "unshallow was tried and failed".
+
 ## [0.4.0] - Unreleased
 
 ### Changed

data/README.md

@@ -11,10 +11,10 @@ Ruby
  rank  language    file                              score  evidence  class   new  age_days  escalation  ...
    1   ruby        app/models/proficiency.rb         0.7304   1.0000  trunk   false  842                 ...
    2   ruby        app/services/payment_service.rb   0.6890   1.0000  trunk   false  611                 ...
-   3   ruby        app/controllers/orders_ctlr.rb    0.5721   0.6667  branch  false  520                 ...
+   3   ruby        app/controllers/orders_ctlr.rb    0.5721   1.0000  branch  false  520                 ...
 ```
 
-*Scores and evidence are illustrative. Row 3 has no coverage data (evidence capped at `0.6667 = (1.0 + 1.0 + 0.0) / 3`); rows 1–2 have full coverage (evidence `1.0000`). The `class` column reflects percentile rank of composite score within the repo — see Classification.*
+*Scores and evidence are illustrative. Row 3 has full history but no coverage data (evidence `1.0000` — coverage is a bonus, not a requirement); rows 1–2 have full coverage (evidence `1.0000`). The `class` column reflects percentile rank of composite score within the repo — see Classification.*
 
 The full table adds `fan_in`, `fan_out`, `instability`, `complexity`, `churn_commits`, `churn_lines`, `churn_pct`, `loc`, `loc_pct`, `max_coupling`, `max_coupling_partner`, `coupling_partners`, `coupling_pct`, and `coverage`. Use `--output json` for machine-readable output including a `warnings` section and full `meta`.
 
@@ -147,7 +147,7 @@ A file is considered new when its first commit is within `--new-file-days` days
 
 A stronger rule runs first: if a new file depends on a structurally `trunk` file through its fan-out edges, it escalates to `trunk` with `escalation=trunk_adjacent`. This highlights new code consuming critical interfaces, where contract-violation risk is highest. Use `--no-newness` to disable both newness rules.
 
-**CI usage:** newness rules require full git history. In GitHub Actions, set `fetch-depth: 0` before running Stud Finder. If Stud Finder detects a shallow clone, it auto-disables both newness rules and emits `shallow_clone_newness_disabled` in `warnings` so classifications match `--no-newness` instead of misclassifying mature files as new.
+**CI usage:** newness rules require full git history. In GitHub Actions, set `fetch-depth: 0` before running Stud Finder. If Stud Finder detects a shallow clone it automatically runs `git fetch --unshallow` (45 second timeout) to recover full history before computing metadata. If the fetch fails (network error, timeout, offline runner), Stud Finder falls back to disabled newness and emits both `shallow_clone_newness_disabled` and `shallow_clone_unshallow_failed` in `warnings`. Pass `--no-auto-unshallow` to skip the fetch attempt entirely — on shallow clones only `shallow_clone_newness_disabled` fires and classifications match `--no-newness`.
 
 ---
 
@@ -155,9 +155,9 @@ A stronger rule runs first: if a new file depends on a structurally `trunk` file
 
 Every row carries an `evidence` value (0.0–1.0) alongside `score`. Score is the weighted signal composite. Evidence is a metadata confidence: how much history + coverage-data backing does that score have?
 
-Evidence combines file age, commit count, and whether coverage data was explicitly provided. A high score with low evidence means "structural signals concentrated risk here, but we're not certain because the file is young or the history is thin." A high score with high evidence is a strong claim.
+Evidence combines file age and commit count as its base, with coverage data as a bonus signal. The formula is `max(history_only, with_coverage)`, where `history_only = (age + commits) / 2` and `with_coverage = (age + commits + 1.0) / 3`. A mature file with full history always reaches `1.0` regardless of whether a coverage report is present — coverage can only raise evidence above the history baseline, never suppress it. A high score with low evidence means "structural signals concentrated risk here, but we're not certain because the file is young or the history is thin." A high score with high evidence is a strong claim.
 
-In shallow clones (git fetch-depth < full history), evidence is `null` on every row because file-metadata history is unavailable. The `shallow_clone_newness_disabled` warning also fires. See the CI note above.
+In shallow clones where auto-unshallow fails (or `--no-auto-unshallow` is set), evidence is `null` on every row because file-metadata history is unavailable. See the CI note above.
 
 **Gate consumers should threshold `class` for verdicts and `evidence` for confidence, not raw `score` alone.** Output is sorted by `(class_rank, score)` so trunks group above branches above leaves, and `--top N` no longer drops newness-escalated `trunk_adjacent` files behind high-score branches.
 
@@ -167,7 +167,8 @@ In shallow clones (git fetch-depth < full history), evidence is `null` on every
 
 `analysis.warnings` (available in JSON output) surfaces conditions the run detected that a consumer should know about:
 
-- **`shallow_clone_newness_disabled`** — shallow git clone detected; newness rules auto-disabled.
+- **`shallow_clone_newness_disabled`** — shallow git clone detected; newness rules auto-disabled (auto-unshallow also failed, or `--no-auto-unshallow` was passed).
+- **`shallow_clone_unshallow_failed`** — `git fetch --unshallow` was attempted but failed (network error or timeout); evidence is unavailable. Use `fetch-depth: 0` in CI or pass `--no-auto-unshallow` to suppress the attempt.
 - **`insufficient_dispersion_<signal>`** — every file in the codebase has the same non-zero raw value for `<signal>`, so its percentile-ranked contribution collapsed to `0.0`. The score is unchanged; the warning flags that the signal is silently uninformative rather than genuinely absent. One per affected signal: `fan_in`, `fan_out`, `complexity`, `churn`, `coverage`, `interaction`, `coupling`.
 - Language-specific warnings such as `js_depcruise_no_config` when the JS pipeline had to fall back.
 

data/SIGNALS.md

@@ -89,7 +89,7 @@ Three pieces of output serve three purposes. Confusing them causes gate consumer
 
 - **`score`** (0.0–1.0, four decimals) — the weighted composite. This is **evidence about the file's structural risk**, nothing more. Higher score means the signals concentrated more risk on this file.
 - **`class`** (`leaf` / `branch` / `trunk`) — the decision label. Driven by the composite-score PERCENTILE across the codebase against configurable thresholds (defaults: `branch` at top 50%, `trunk` at top 15%). This guarantees that some files are always trunk-tier relative to their repo — a file scoring 0.55 can be trunk if the rest of the codebase scores below it. This is what a gate should threshold on for verdicts.
-- **`evidence`** (0.0–1.0) — a metadata confidence value based on file age, commit count, and whether coverage data was explicitly provided. A high score with low evidence means "structural signals concentrated risk here, but we're not certain because the file is young or the history is thin." Gates should threshold `evidence` for confidence, not raw `score`.
+- **`evidence`** (0.0–1.0) — a metadata confidence value based on file age, commit count, and optionally coverage presence. The formula is `max(history_only, with_coverage)`, where `history_only = (age + commits) / 2` and `with_coverage = (age + commits + 1.0) / 3` (only included when coverage data is present). Coverage is a bonus: a mature file with full history always reaches `1.0` even without a coverage report. A high score with low evidence means "structural signals concentrated risk here, but we're not certain because the file is young or the history is thin." Gates should threshold `evidence` for confidence, not raw `score`.
 
 ### Absolute floors
 

data/lib/stud_finder/cli.rb

@@ -63,6 +63,7 @@ module StudFinder
       newness: true,
       new_file_days: StudFinder::Newness::DEFAULT_DAYS,
       new_file_min_commits: StudFinder::Newness::DEFAULT_MIN_COMMITS,
+      auto_unshallow: true,
       cli_warnings: []
     }.freeze
 
@@ -259,6 +260,9 @@ module StudFinder
         opts.on('--no-newness', 'Disable new-file classification rules') do
           @options[:newness] = false
         end
+        opts.on('--no-auto-unshallow', 'Disable automatic git fetch --unshallow on shallow clones') do
+          @options[:auto_unshallow] = false
+        end
         opts.on('--verbose', 'Print suppressed per-file warnings to stderr') do
           @options[:verbose] = true
         end
@@ -511,8 +515,12 @@ module StudFinder
 
     def apply_newness(files, edges, rows, coverage_result = nil)
       metadata = if @options[:newness] && Newness.shallow_repository?(@repo_path)
-                   @options[:cli_warnings] << Newness::SHALLOW_CLONE_WARNING
-                   Newness.disabled_metadata(files)
+                   if @options[:auto_unshallow]
+                     attempt_unshallow(files)
+                   else
+                     @options[:cli_warnings] << Newness::SHALLOW_CLONE_WARNING
+                     Newness.disabled_metadata(files)
+                   end
                  elsif @options[:newness]
                    Newness.new(repo_path: @repo_path, files: files, days: @options[:new_file_days],
                                min_commits: @options[:new_file_min_commits]).call
@@ -522,6 +530,21 @@ module StudFinder
       Newness.apply(rows: rows, edges: edges, metadata: metadata, coverage: coverage_result)
     end
 
+    def attempt_unshallow(files)
+      require 'timeout'
+      Timeout.timeout(45) do
+        _stdout, _stderr, status = Open3.capture3('git', 'fetch', '--unshallow', chdir: @repo_path)
+        raise 'unshallow failed' unless status.success?
+
+        Newness.new(repo_path: @repo_path, files: files, days: @options[:new_file_days],
+                    min_commits: @options[:new_file_min_commits]).call
+      end
+    rescue StandardError
+      @options[:cli_warnings] << Newness::SHALLOW_CLONE_WARNING
+      @options[:cli_warnings] << Newness::UNSHALLOW_FAILED_WARNING
+      Newness.disabled_metadata(files)
+    end
+
     def loc_percentiles_by_language(files, loc, language_by_file)
       files.group_by { |file| language_by_file.fetch(file) }.values.reduce({}) do |pct, language_files|
         pct.merge(Normalizer.percentile_rank(loc, language_files))

data/lib/stud_finder/newness.rb

@@ -14,6 +14,10 @@ module StudFinder
       code: 'shallow_clone_newness_disabled',
       message: 'shallow git clone detected; newness rules disabled (use fetch-depth: 0 in CI for full newness behavior)'
     }.freeze
+    UNSHALLOW_FAILED_WARNING = {
+      code: 'shallow_clone_unshallow_failed',
+      message: 'auto-unshallow failed; evidence unavailable (use fetch-depth: 0 in CI or pass --no-auto-unshallow)'
+    }.freeze
 
     History = Struct.new(:first_commit_epoch, :total_commits, keyword_init: true)
 
@@ -104,9 +108,11 @@ module StudFinder
 
       age_component = [metadata.fetch(:age_days, 0) / 30.0, 1.0].min
       commits_component = [metadata.fetch(:total_commits, 0) / 3.0, 1.0].min
-      coverage_component = explicit_coverage ? 1.0 : 0.0
 
-      ((age_component + commits_component + coverage_component) / 3.0).round(4)
+      history_only = (age_component + commits_component) / 2.0
+      with_coverage = ((age_component + commits_component + 1.0) / 3.0) if explicit_coverage
+
+      [history_only, with_coverage].compact.max.round(4)
     end
 
     def self.git_shallow_file?(repo_path)

data/lib/stud_finder/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StudFinder
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stud-finder
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - bazfer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-11 00:00:00.000000000 Z
+date: 2026-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv