stud-finder 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77b17fc211c036ac76d6508d2d37177a0aff6331cb7be4101bb56c8c17e0c61f
-  data.tar.gz: d601cf1c93a7fa5d9bad190614f57375f2c02a4c4f07d00d6487f4d0ab7e4cf6
+  metadata.gz: faa8060a75346fc7a402adf203764c650d1596c2c6b3f4cb25571b3b21ecfa7a
+  data.tar.gz: 9c26eed3cb20c42d0155a730ba0ff70f9893a43493bf49d633aea4a0a2036a79
 SHA512:
-  metadata.gz: '03438058c1234cd7740190d78807102e39a7b75def36ce914f276d0be9d7cfadc277ee6f5b6a04b7eabc031c7473316b65b0e2d1309a8f98d9e3d96b0559f405'
-  data.tar.gz: 7f1f8bba0ed383a56dedd2f59efa10ff1f0c662b5b2649416efdd40bc4f66bc99424ca257cc321e3c32e6a77a49880bc93ee74bf2b078dbe29aeaa1f922c8081
+  metadata.gz: 863567f3e6dedd1808075bf9ae272cdb3f2e5b3b849b0eaa3b7b829a0db56873b757e6587d4fc82b6460fe6ab993407de24742fdde86d6bea6cb9809eb388ec0
+  data.tar.gz: a0a6d9b9fb0ad35bd88e22e26c24eb72957d22c46fd138e0e4c8b7da2bbcc885c5fb7f23bc58db547b826c754a478d72aa9b6cf0b3b04c81fa1801ef11fc903a

data/CHANGELOG.md

@@ -5,6 +5,27 @@ 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
+
+- BREAKING: Classification thresholds are now percentile-based, not score-value-based. `--trunk-threshold 85` and `--branch-threshold 50` now mean "top 15% and top 50% of files by composite score" — not "score value ≥ 0.85 / 0.50". This is a semantic change to the same flag values; the numbers you pass stay the same but their meaning inverts. Previously, trunk was unreachable at defaults (max observed composite score ~0.717 in real repos, zero trunks); now every repo of meaningful size produces some trunks and branches. Absolute floors (raw complexity ≥ 15, raw fan_in ≥ 25) still escalate to `branch` regardless of percentile.
+
 ## [0.3.0] - 2026-07-11
 
 ### Fixed
@@ -38,7 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial `stud-finder` cut: a CLI that ranks files by five risk signals: fan-in (blast radius), fan-out, cyclomatic complexity, git churn, and test coverage.
+- Initial RubyGems release: a CLI that ranks files by five risk signals: fan-in (blast radius), fan-out, cyclomatic complexity, git churn, and test coverage.
 - Temporal coupling analysis for identifying files that change together.
 - Diff mode for scoring only files changed in a pull request while preserving repo-relative scores.
 - Ruby and JavaScript/TypeScript support.

data/README.md

@@ -9,12 +9,12 @@ $ bundle exec bin/stud-finder ./my-rails-app
 
 Ruby
  rank  language    file                              score  evidence  class   new  age_days  escalation  ...
-   1   ruby        app/models/proficiency.rb         0.7304   1.0000  branch  false  842                 ...
-   2   ruby        app/services/payment_service.rb   0.6890   1.0000  branch  false  611                 ...
-   3   ruby        app/controllers/orders_ctlr.rb    0.5721   0.6667  branch  false  520                 ...
+   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   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`). Real runs on well-distributed repos typically top out around 0.70–0.75 composite score — 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`.
 
@@ -117,15 +117,19 @@ Result is clamped to `[0.0, 1.0]` and rounded to four decimal places.
 
 ## Classification
 
-Every row is labelled with a `class`:
+Files are classified into three tiers based on the **percentile rank of their composite score** within the repo:
 
-- **trunk** — composite score ≥ `trunk_threshold / 100` (default `trunk_threshold: 85`, so score ≥ 0.85). Load-bearing. High review bar.
-- **branch** — composite score ≥ `branch_threshold / 100` and below the trunk cutoff (default `branch_threshold: 50`, so 0.50 ≤ score < 0.85). Meaningful coupling.
-- **leaf** — score below the branch cutoff. Isolated. Move fast here.
+- **trunk** — top 15% by composite score (default `--trunk-threshold 85`). Load-bearing. High review bar, change with care.
+- **branch** — top 50% but below top 15% (default `--branch-threshold 50`). Meaningful coupling.
+- **leaf** — everything below the 50th percentile. Isolated. Move fast here.
 
-`--trunk-threshold` and `--branch-threshold` take integer values 1–99 that set the composite-score cutoff (a threshold of 85 means score ≥ 0.85). Classification is driven by the full composite, not by fan-in percentile — a file with modest fan-in but very high complexity + churn can still classify as `trunk`.
+This means every repo of meaningful size has trunks: a file at score 0.55 is trunk if the rest of the repo scores below it. The absolute floors below provide a safety net for tiny repos.
 
-Because `score` is a weighted sum of percentile-ranked signals, not itself a percentile, a threshold of 85 does not mean "top 15% of files." Well-distributed projects rarely have any file scoring above 0.85; in tighter distributions the cutoffs may need tuning per-project.
+**Absolute floors:** raw complexity ≥ 15 or raw fan-in ≥ 25 escalates a `leaf` to `branch` regardless of percentile. This ensures that structurally dangerous files in tiny repos (where percentile spread is minimal) still receive elevated attention.
+
+**Tiny repos:** In repos with very few files and uniform scores, the percentile spread may place all files at the same score_pct (0.0), resulting in 0 trunks. The absolute floor is the escape hatch for dangerous files in this case.
+
+Note: `--trunk-threshold 85` and `--branch-threshold 50` now mean "top 15% / top 50% of files by composite score" — not "score value ≥ 0.85 / 0.50". This is a BREAKING semantic change from 0.3.0. Trunk was previously unreachable at defaults (max observed composite score ~0.717 in real repos); this change restores the guarantee that some files are always classified trunk-tier relative to their codebase.
 
 ### Absolute floors
 
@@ -143,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`.
 
 ---
 
@@ -151,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.
 
@@ -163,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.
 
@@ -218,8 +223,8 @@ Each language gets its own ranking section in the output — Ruby and JS are not
 | `--weights WEIGHTS` | Custom weights as fractions, e.g. `fan_in:F,fan_out:O,complexity:C,churn:H,coverage:V[,interaction:I][,coupling:P]`. The five base keys (`fan_in`, `fan_out`, `complexity`, `churn`, `coverage`) are required. `interaction` and `coupling` are optional: when omitted, `interaction` defaults to `0.0` (custom weights opt-in) and `coupling` defaults to `0.05`. Each value must be in `[0.0, 1.0]`. When no coverage data is provided, `coverage` must be `0.0`. |
 | `--interaction-weight N` | Sugar flag for setting only the interaction weight. |
 | `--coupling-weight N` | Sugar flag for setting only the coupling weight. Bounds-checked `[0.0, 1.0]`. |
-| `--trunk-threshold N` | Composite-score threshold for trunk classification: score ≥ N/100 (integer 1–99, default: 85) |
-| `--branch-threshold N` | Composite-score threshold for branch classification: score ≥ N/100 (integer 1–99, default: 50) |
+| `--trunk-threshold N` | composite-score percentile cutoff for trunk classification; top (100-N)% of files by score (default: 85) |
+| `--branch-threshold N` | composite-score percentile cutoff for branch classification; top (100-N)% of files by score (default: 50) |
 | `--exclude PATTERN` | Exclude glob pattern (repeatable). `spec/` and `test/` excluded by default. |
 | `--top N` | Emit only the top N results |
 | `--diff-base REF` | Score the whole repo but emit only the files changed on `HEAD` vs the merge-base with `REF` (e.g. `origin/staging`). Ranks and scores stay relative to the full repo. Ideal for per-PR runs. |

data/SIGNALS.md

@@ -88,8 +88,8 @@ Ties receive the same rank. Edge cases: a codebase with only one file gets `0.0`
 Three pieces of output serve three purposes. Confusing them causes gate consumers to threshold the wrong number.
 
 - **`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 against configurable thresholds (defaults: `branch` at score ≥ 0.50, `trunk` at score ≥ 0.85). 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`.
+- **`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 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
 
@@ -209,11 +210,13 @@ module StudFinder
           @options[:rails_inference] = false
         end
         opts.on('--trunk-threshold N', Integer,
-                'score cutoff for trunk classification, integer 1-99 (default: 85)') do |value|
+                'score percentile cutoff for trunk classification, integer 1-99 ' \
+                '(default: 85 = top 15% of files by score)') do |value|
           @options[:trunk_threshold] = value
         end
         opts.on('--branch-threshold N', Integer,
-                'score cutoff for branch classification, integer 1-99 (default: 50)') do |value|
+                'score percentile cutoff for branch classification, integer 1-99 ' \
+                '(default: 50 = top 50% of files by score)') do |value|
           @options[:branch_threshold] = value
         end
         opts.on('--exclude PATTERN', 'Exclude glob pattern (repeatable)') do |value|
@@ -257,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
@@ -509,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
@@ -520,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/scorer.rb

@@ -52,9 +52,11 @@ module StudFinder
       }
       @warnings = insufficient_dispersion_warnings(pcts)
 
+      scores = @files.to_h { |file| [file, weighted_score(file, pcts)] }
+      score_pcts = Normalizer.percentile_rank(scores, @files)
+
       rows = @files.each_with_index.map do |file, index|
-        score = weighted_score(file, pcts)
-        [index, result_row(file, score, pcts)]
+        [index, result_row(file, scores.fetch(file), pcts, score_pcts.fetch(file))]
       end
 
       rows.sort_by { |index, row| [-row[:score], index] }
@@ -123,12 +125,12 @@ module StudFinder
       end
     end
 
-    def result_row(file, score, pcts)
+    def result_row(file, score, pcts, score_pct)
       fi = @fan_in.fetch(file, 0).to_i
       fo = @fan_out.fetch(file, 0).to_i
       rounded_score = score.round(4)
       complexity = @complexity.fetch(file, 0).to_i
-      floored_class, floor_escalation = floored_classification(classification(rounded_score), complexity, fi)
+      floored_class, floor_escalation = floored_classification(classification(score_pct), complexity, fi)
       {
         path: file,
         score: rounded_score,
@@ -242,9 +244,9 @@ module StudFinder
       end
     end
 
-    def classification(score)
-      return 'trunk' if score >= @trunk_threshold / 100.0
-      return 'branch' if score >= @branch_threshold / 100.0
+    def classification(score_pct)
+      return 'trunk' if score_pct >= @trunk_threshold / 100.0
+      return 'branch' if score_pct >= @branch_threshold / 100.0
 
       'leaf'
     end

data/lib/stud_finder/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StudFinder
-  VERSION = '0.3.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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - bazfer
-autorequire:
+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
@@ -180,7 +180,7 @@ metadata:
   changelog_uri: https://github.com/bazfer/stud-finder/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/bazfer/stud-finder/issues
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -195,8 +195,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.4.10
+signing_key: 
 specification_version: 4
 summary: Rank files by structural risk in Ruby and JavaScript/TypeScript codebases.
 test_files: []