stud-finder 0.1.0 → 0.3.0

data/lib/stud_finder/scorer.rb

@@ -1,29 +1,40 @@
 # frozen_string_literal: true
 
+require_relative 'dispersion_warnings'
 require_relative 'normalizer'
 
 module StudFinder
+  # rubocop:disable Metrics/ClassLength
   class Scorer
-    DEFAULT_WEIGHTS = { fan_in: 0.25, fan_out: 0.10, complexity: 0.25, churn: 0.25, coverage: 0.15 }.freeze
-    RENORMALIZED_KEYS = %i[fan_in fan_out complexity churn].freeze
+    DEFAULT_WEIGHTS = {
+      fan_in: 0.19, fan_out: 0.095, complexity: 0.2375, churn: 0.2375, coverage: 0.095,
+      interaction: 0.095, coupling: 0.05
+    }.freeze
+    BASE_WEIGHT_KEYS = %i[fan_in fan_out complexity churn].freeze
+    WEIGHT_KEYS = %i[fan_in fan_out complexity churn coverage interaction coupling].freeze
+    COMPLEXITY_FLOOR = 15
+    FAN_IN_FLOOR = 25
 
     class ValidationError < StandardError; end
 
-    attr_reader :normalized_weights
+    attr_reader :normalized_weights, :warnings
 
-    def initialize(files:, fan_in:, fan_out:, complexity:, churn:, churn_lines: nil, coverage: nil,
-                   weights: DEFAULT_WEIGHTS, branch_threshold: 50, trunk_threshold: 85, coupling: nil)
+    def initialize(files:, fan_in:, fan_out:, complexity:, churn:, churn_lines: nil, loc: nil, loc_pct: nil,
+                   coverage: nil, weights: DEFAULT_WEIGHTS, branch_threshold: 50, trunk_threshold: 85, coupling: nil)
       @files = files
       @fan_in = fan_in
       @fan_out = fan_out
       @complexity = complexity
       @churn = churn
       @churn_lines = churn_lines || churn
+      @loc = loc || @files.to_h { |file| [file, 0] }
+      @loc_pct = loc_pct
       @coverage = coverage
       @weights = weights
       @branch_threshold = branch_threshold
       @trunk_threshold = trunk_threshold
       @coupling = coupling
+      @warnings = []
       validate!
       @normalized_weights = normalize_weights
     end
@@ -34,9 +45,12 @@ module StudFinder
         fan_out: Normalizer.percentile_rank(@fan_out, @files),
         complexity: Normalizer.percentile_rank(@complexity, @files),
         churn: composite_churn_pct,
+        loc: @loc_pct || Normalizer.percentile_rank(@loc, @files),
         instability: instability_pct,
-        coupling: coupling_pct
+        coupling: coupling_pct,
+        coverage: coverage_risk_pct
       }
+      @warnings = insufficient_dispersion_warnings(pcts)
 
       rows = @files.each_with_index.map do |file, index|
         score = weighted_score(file, pcts)
@@ -58,34 +72,32 @@ module StudFinder
     end
 
     def normalize_weights
-      active_total = RENORMALIZED_KEYS.sum { |key| @weights.fetch(key, 0.0) }
-      if !coverage_available? && active_total <= 0.0
+      active_keys = BASE_WEIGHT_KEYS.dup
+      active_keys += %i[coverage interaction] if coverage_available?
+      active_keys << :coupling if coupling_available?
+
+      active_total = active_keys.sum { |key| @weights.fetch(key, 0.0) }
+      if active_total <= 0.0
         raise ValidationError,
               'Error: active weights must be greater than 0.0.'
       end
 
-      @active_weights = if active_total > 0.0
-                          RENORMALIZED_KEYS.to_h { |key| [key, @weights.fetch(key, 0.0) / active_total] }
-                                           .merge(coverage: nil)
-                        else
-                          RENORMALIZED_KEYS.to_h { |key| [key, 0.0] }.merge(coverage: nil)
-                        end
-
-      return @weights if coverage_available?
-
-      @active_weights
+      WEIGHT_KEYS.to_h do |key|
+        [key, active_keys.include?(key) ? @weights.fetch(key, 0.0) / active_total : nil]
+      end
     end
 
     def weighted_score(file, pcts)
-      return active_weights_score(file, pcts) unless coverage_available?
+      score = structural_score(@normalized_weights, file, pcts)
+      score += @normalized_weights[:coverage] * pcts[:coverage].fetch(file) if coverage_available?
+      score += interaction_score(file, pcts) if coverage_available?
+      score += @normalized_weights[:coupling] * pcts[:coupling].fetch(file) if coupling_available?
 
-      file_coverage = @coverage.fetch(file, 0.0)
-      structural_score(@normalized_weights, file, pcts) +
-        (@normalized_weights[:coverage] * (1.0 - file_coverage))
+      score.clamp(0.0, 1.0)
     end
 
-    def active_weights_score(file, pcts)
-      structural_score(@active_weights, file, pcts)
+    def interaction_score(file, pcts)
+      @normalized_weights.fetch(:interaction, 0.0) * pcts[:fan_in].fetch(file) * pcts[:coverage].fetch(file)
     end
 
     def structural_score(weights, file, pcts)
@@ -98,32 +110,45 @@ module StudFinder
     def composite_churn_pct
       count_pct = Normalizer.percentile_rank(@churn, @files)
       line_pct = Normalizer.percentile_rank(@churn_lines, @files)
+      @churn_signal_raw = @files.to_h do |file|
+        [file, ((0.5 * count_pct.fetch(file)) + (0.5 * line_pct.fetch(file))).round(10)]
+      end
 
+      Normalizer.percentile_rank(@churn_signal_raw, @files)
+    end
+
+    def churn_dispersion_raw_source
       @files.to_h do |file|
-        [file, (0.5 * count_pct.fetch(file)) + (0.5 * line_pct.fetch(file))]
+        [file, @churn.fetch(file, 0).to_f.abs + @churn_lines.fetch(file, 0).to_f.abs]
       end
     end
 
     def result_row(file, score, pcts)
       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)
       {
         path: file,
-        score: score.round(4),
-        classification: classification(pcts[:fan_in].fetch(file)),
+        score: rounded_score,
+        classification: floored_class,
+        escalation: floor_escalation,
         fan_in: fi,
         fan_in_pct: pcts[:fan_in].fetch(file).round(4),
         fan_out: fo,
         fan_out_pct: pcts[:fan_out].fetch(file).round(4),
         instability: instability(fi, fo),
         instability_pct: pcts[:instability].fetch(file).round(4),
-        complexity: @complexity.fetch(file, 0).to_i,
+        complexity: complexity,
         complexity_pct: pcts[:complexity].fetch(file).round(4),
         churn_commits: @churn.fetch(file, 0).to_i,
         churn_lines: @churn_lines.fetch(file, 0).to_i,
         churn_pct: pcts[:churn].fetch(file).round(4),
+        loc: @loc.fetch(file, 0).to_i,
+        loc_pct: pcts[:loc].fetch(file).round(4),
         **coupling_fields(file, pcts),
-        coverage: coverage_available? ? @coverage.fetch(file, 0.0).round(4) : nil
+        coverage: coverage_value(file)
       }
     end
 
@@ -150,22 +175,91 @@ module StudFinder
     end
 
     def coupling_pct
-      values = @files.to_h do |file|
+      Normalizer.percentile_rank(coupling_values, @files)
+    end
+
+    def coupling_values
+      @files.to_h do |file|
         partner = @coupling&.fetch(file, nil)
         [file, partner ? partner.fetch(:max_coupling, 0.0).to_f : 0.0]
       end
-      Normalizer.percentile_rank(values, @files)
+    end
+
+    def coverage_risk_pct
+      return {} unless coverage_available?
+
+      Normalizer.percentile_rank(coverage_risk_values, @files)
+    end
+
+    def coverage_risk_values
+      return {} unless coverage_available?
+
+      @files.to_h { |file| [file, 1.0 - @coverage.fetch(file, 0.0)] }
+    end
+
+    def interaction_values(pcts)
+      return {} unless coverage_available?
+
+      @files.to_h { |file| [file, pcts[:fan_in].fetch(file) * pcts[:coverage].fetch(file)] }
+    end
+
+    def insufficient_dispersion_warnings(pcts)
+      raw_sources = {
+        fan_in: @fan_in,
+        fan_out: @fan_out,
+        complexity: @complexity,
+        churn: churn_dispersion_raw_source
+      }
+      if coverage_available?
+        raw_sources[:coverage] = coverage_risk_values
+        raw_sources[:interaction] = interaction_values(pcts)
+        pcts = pcts.merge(interaction: Normalizer.percentile_rank(raw_sources[:interaction], @files))
+      end
+      raw_sources[:coupling] = coupling_values if coupling_available?
+
+      DispersionWarnings.build(files: @files, pcts: pcts, raw_sources: raw_sources)
+    end
+
+    def coverage_value(file)
+      return nil unless coverage_available?
+      return '—' unless @coverage.key?(file)
+
+      @coverage.fetch(file).round(4)
     end
 
     def coverage_available?
       !@coverage.nil?
     end
 
-    def classification(fan_in_pct)
-      return 'trunk' if fan_in_pct >= @trunk_threshold / 100.0
-      return 'branch' if fan_in_pct >= @branch_threshold / 100.0
+    def coupling_available?
+      return false if @coupling.nil? || @coupling.empty?
+
+      @files.any? do |file|
+        partner = @coupling.fetch(file, nil)
+        partner.respond_to?(:fetch) && partner.fetch(:max_coupling, 0.0).to_f.positive?
+      rescue ArgumentError, TypeError
+        false
+      end
+    end
+
+    def classification(score)
+      return 'trunk' if score >= @trunk_threshold / 100.0
+      return 'branch' if score >= @branch_threshold / 100.0
 
       'leaf'
     end
+
+    def floored_classification(classification, complexity, fan_in)
+      return [classification, ''] unless classification == 'leaf'
+
+      if complexity >= COMPLEXITY_FLOOR
+        %w[branch complexity_floor]
+      elsif fan_in >= FAN_IN_FLOOR
+        %w[branch fan_in_floor]
+      else
+        [classification, '']
+      end
+    end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/stud_finder/temporal_coupling.rb

@@ -8,22 +8,23 @@ module StudFinder
 
     SHA_PATTERN = /\A[0-9a-f]{40}\z/
 
-    def initialize(repo_path:, files:, days:, min_co_changes: 5, coupling_threshold: 0.30)
+    def initialize(repo_path:, files:, days:, min_co_changes: 5, coupling_threshold: 0.30, max_commit_files: 50)
       @repo_path = File.expand_path(repo_path)
       @file_set = files.to_h { |f| [f, true] }
       @days = days
       @min_co_changes = min_co_changes
       @coupling_threshold = coupling_threshold
+      @max_commit_files = max_commit_files
     end
 
     def call
       stdout, _err, status = git_log
       return Result.new(pairs: {}, warnings: ['git_error']) unless status.success?
 
-      commits = parse_commits(stdout)
+      commits, skipped_bulk_commits = parse_commits(stdout)
       co_matrix = build_co_change_matrix(commits)
       own_changes = build_own_changes(commits)
-      Result.new(pairs: build_pairs(co_matrix, own_changes), warnings: [])
+      Result.new(pairs: build_pairs(co_matrix, own_changes), warnings: warnings(skipped_bulk_commits))
     rescue Errno::ENOENT
       Result.new(pairs: {}, warnings: ['git_not_found'])
     end
@@ -44,10 +45,11 @@ module StudFinder
     def parse_commits(stdout)
       commits = []
       current = nil
+      skipped_bulk_commits = 0
       stdout.each_line do |raw|
         line = raw.chomp
         if SHA_PATTERN.match?(line)
-          commits << current if current&.any?
+          skipped_bulk_commits += append_commit(commits, current)
           current = []
         elsif !line.empty? && current
           relative = normalize_path(line)
@@ -56,8 +58,17 @@ module StudFinder
           current << relative if @file_set[relative] && !current.include?(relative)
         end
       end
-      commits << current if current&.any?
-      commits
+      skipped_bulk_commits += append_commit(commits, current)
+      [commits, skipped_bulk_commits]
+    end
+
+    def append_commit(commits, files)
+      return 0 unless files&.any?
+
+      return 1 if @max_commit_files.positive? && files.length > @max_commit_files
+
+      commits << files
+      0
     end
 
     def build_co_change_matrix(commits)
@@ -97,8 +108,24 @@ module StudFinder
     end
 
     def normalize_path(path)
+      path = renamed_path(path)
       absolute = File.expand_path(path, @repo_path)
       absolute.start_with?("#{@repo_path}/") ? absolute.delete_prefix("#{@repo_path}/") : path
     end
+
+    def renamed_path(path)
+      return path unless path.include?(' => ')
+
+      path.sub(/\{[^{}]* => ([^{}]*)\}/, '\\1').then do |renamed|
+        renamed == path ? path.split(' => ', 2).last : renamed
+      end
+    end
+
+    def warnings(skipped_bulk_commits)
+      return [] if skipped_bulk_commits.zero?
+
+      [{ code: 'temporal_coupling_bulk_commits_skipped', count: skipped_bulk_commits,
+         max_commit_files: @max_commit_files }]
+    end
   end
 end

data/lib/stud_finder/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stud-finder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - bazfer
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -145,9 +145,8 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
-- PRODUCT.md
 - README.md
-- VISION.md
+- SIGNALS.md
 - bin/stud-finder
 - lib/stud-finder.rb
 - lib/stud_finder.rb
@@ -159,12 +158,16 @@ files:
 - lib/stud_finder/coverage/lcov.rb
 - lib/stud_finder/coverage/resultset.rb
 - lib/stud_finder/diff.rb
+- lib/stud_finder/dispersion_warnings.rb
 - lib/stud_finder/edges.rb
 - lib/stud_finder/fan_in.rb
 - lib/stud_finder/file_collector.rb
 - lib/stud_finder/js_complexity.rb
 - lib/stud_finder/js_fan_in.rb
+- lib/stud_finder/loc_counter.rb
+- lib/stud_finder/newness.rb
 - lib/stud_finder/normalizer.rb
+- lib/stud_finder/rails_inference.rb
 - lib/stud_finder/scorer.rb
 - lib/stud_finder/temporal_coupling.rb
 - lib/stud_finder/version.rb
@@ -177,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
@@ -192,8 +195,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Rank files by structural risk in Ruby and JavaScript/TypeScript codebases.
 test_files: []

data/PRODUCT.md

@@ -1,172 +0,0 @@
-# stud-finder
-
-**Find the files that will hurt you before they do.**
-
----
-
-## The Problem
-
-Every codebase has load-bearing walls. Files that dozens of other files depend on. Files that change every sprint. Files whose complexity means one wrong edit cascades into a day of debugging.
-
-Most teams discover these files the hard way — after the incident.
-
-stud-finder surfaces them before you touch them.
-
----
-
-## What It Does
-
-stud-finder analyzes a codebase and produces a ranked list of every file, scored by structural risk. Run it before a sprint, before a refactor, before a code review. Know which files deserve extra attention before anyone writes a line.
-
-```
-$ stud-finder ./my-rails-app
-
-FILE                              SCORE  LABEL   FAN_IN  COMPLEXITY  CHURN_COMMITS  CHURN_LINES  CHURN_PCT  COVERAGE
-app/models/user.rb                0.91   trunk   0.97    0.42        0.88           0.91         0.89       0.14
-app/services/payment_service.rb   0.84   trunk   0.78    0.91        0.71           0.68         0.69       0.22
-app/controllers/orders_controller 0.73   branch  0.61    0.65        0.74           0.77         0.75       0.31
-...
-```
-
-Three labels, one decision framework:
-
-- **Trunk** — load-bearing. Change with care. High review bar.
-- **Branch** — meaningful coupling. Worth a second look.
-- **Leaf** — isolated. Lower risk. Move fast here.
-
----
-
-## The Five Signals
-
-Each file is scored on up to five independently measured signals, each grounded in decades of software engineering research. M7 introduced scored `fan_out`, so the composite now considers both incoming blast radius and outgoing coupling burden.
-
-### 1. Fan-in — Blast Radius
-
-*"How many files depend on this one?"*
-
-Rooted in Robert Martin's **afferent coupling (Ca)** metric (1994) and graph theory in-degree analysis. A file with fan_in 60 means 60 other files break if it breaks. The Stable Dependencies Principle says: high-coupling files must be treated as infrastructure.
-
-stud-finder builds the dependency graph via static analysis — Zeitwerk constant mapping for Rails, falling back to AST scanning. No runtime instrumentation required.
-
-**Weight: 25% of total score**
-
-### 2. Fan-out — Coupling Burden
-
-*"How many files does this one depend on?"*
-
-Rooted in Robert Martin's **efferent coupling (Ce)** metric. A high `fan_out` file has more direct dependencies to understand, coordinate, and mock in tests. In M7, fan-out moved from an informational column into the scored model.
-
-**Weight: 10% of total score**
-
-### 3. Complexity — Cognitive Load
-
-*"How hard is this file to reason about?"*
-
-Cyclomatic complexity, measured as the **maximum across any single method** in the file. A file with one function of complexity 12 is riskier than a file with ten functions of complexity 3 each — the hardest function determines how deep you have to go.
-
-Computed via RuboCop's static analysis engine. No manual annotation.
-
-**Weight: 25% of total score**
-
-### 4. Churn — Change Velocity
-
-*"How often is this file being touched, and how much?"*
-
-A composite signal: 50% commit frequency + 50% lines changed, both percentile-ranked across the full codebase. A file touched in 40 commits but only for small fixes is different from a file touched in 40 commits with major rewrites each time.
-
-Computed from git history over a configurable window (default: 180 days). Language-agnostic.
-
-**Weight: 25% of total score**
-
-### 5. Coverage — Safety Net
-
-*"If this file breaks, will tests catch it?"*
-
-Low coverage on a high-risk file is compounded danger — no blast-radius detection, no complexity safety net, no test catch. Coverage is measured as an inverse (0% coverage = maximum penalty), and files absent from the coverage report are handled via coverage fallback rather than penalized falsely.
-
-Supports Cobertura XML (RSpec + SimpleCov), LCOV (Jest, lcov), and SimpleCov JSON resultsets. Auto-detected by file extension.
-
-**Weight: 15% of total score** (optional — runs as 4-factor model when no coverage report provided)
-
----
-
-## The Score
-
-Each signal is percentile-ranked across the full codebase — so scores are always relative to the project itself, not an external benchmark. A file at the 90th percentile of fan_in has more incoming dependencies than 90% of its peers.
-
-The composite score (0.0–1.0) weights the signals and produces the ranked output. Classification thresholds are configurable.
-
-**4-factor formula (no coverage):**
-```
-score = 0.2941 × fan_in_pct + 0.1176 × fan_out_pct + 0.2941 × complexity_pct + 0.2941 × churn_pct
-```
-
-**5-factor formula (with coverage):**
-```
-score = 0.25 × fan_in_pct + 0.10 × fan_out_pct + 0.25 × complexity_pct + 0.25 × churn_pct + 0.15 × (1 − coverage)
-```
-
----
-
-## Use Cases
-
-**Pre-sprint risk assessment** — before planning, run stud-finder against the files your team is about to touch. Trunk files get more review time budgeted.
-
-**Refactor prioritization** — you have ten candidates for cleanup. stud-finder tells you which ones have the highest blast radius if the refactor goes wrong.
-
-**Onboarding** — new engineer joining the team. Here's the trunk map. These are the files you ask before changing.
-
-**PR review triage** — reviewer bandwidth is finite. Direct it at the files that matter.
-
-**Architecture health monitoring** — run stud-finder weekly. Watch if trunk is growing or shrinking. Trunk growth is a coupling smell.
-
----
-
-## Technical Foundation
-
-- **Language:** Ruby gem, zero runtime instrumentation
-- **Static analysis:** RuboCop (complexity), Zeitwerk + custom AST (fan_in), git log (churn)
-- **Coverage formats:** Cobertura XML, LCOV, SimpleCov JSON — auto-detected
-- **Output formats:** table (default), JSON, CSV, Markdown
-- **Configuration:** CLI flags for weights, thresholds, excludes, churn window
-- **Requires:** Ruby, RuboCop, git. Nothing else for Ruby analysis.
-
----
-
-## Roadmap
-
-**M1–M3 — Complete**
-Initial composite score (Ruby + JS/TS). `--diff-base` / `--only` filter for per-PR output. Per-PR CircleCI integration — stud-finder runs on every PR, posts ranked artifact and PR comment. Non-blocking.
-
-**M4 — Complete: fan-out, instability, `stud-finder edges`**
-Fan-out (efferent coupling) and instability (`fan_out / (fan_in + fan_out)`) added to every row in the core output. New `stud-finder edges FILE` subcommand emits the actual dependency edge list for a specific file — dependents and dependencies, both sorted by risk score. Shifts the output from "this file scores high" to "here are the specific files in the blast radius."
-
-**M5 — Sentry integration**
-Connect to the Sentry REST API. Parse production stack traces, aggregate error frequency by source file. A runtime signal: not structural approximation but observed failure in production. `--sentry-token`, `--sentry-org`, `--sentry-project` flags. Percentile-ranked and added to the composite score.
-
-**M6 — Temporal coupling**
-Co-change frequency from git history: file pairs that change together more often than expected by chance. Surfaces hidden coupling that static analysis cannot see — implicit contracts, shared state, callback side effects. Observed behavior, not structural approximation.
-
-**Pinned — Producer-consumer dependency mapping**
-Explicitly surfacing which components consume data produced by other components, flagging pairs with high temporal coupling but low static coupling as candidates for explicit contract documentation.
-
-**M7 — Complete: scored fan-out + rankings**
-Scored fan-out introduced as the fifth risk signal with a 10% default weight.
-
-**M7 follow-up — Merge-to-staging S3 timeline (lowest priority)**
-Full stud-finder run on each merge to the mainline branch → JSON → S3, keyed by timestamp + commit SHA. Durable risk-over-time feed for trend analysis.
-
-**Future — Toward a validated risk estimator**
-Calibrated weights back-tested against bug history. Historical bug density as a direct input metric. Change-scope awareness (per-PR risk = file-risk × change-magnitude × change-type). Test quality beyond line coverage. See `VISION.md` for the full analysis.
-
----
-
-## Why stud-finder?
-
-In construction, a stud finder locates the load-bearing structure inside a wall before you drill. You don't guess — you know exactly where the structure is.
-
-Same principle. Before you refactor, before you sprint, before you review — know where the load-bearing code is.
-
----
-
-*Built by Artífice. Ruby gem. Open to collaboration.*