stud-finder 0.1.0

data/lib/stud_finder/js_fan_in.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'set'
+require 'timeout'
+
+module StudFinder
+  class JsFanIn
+    Result = Struct.new(:counts, :fan_out_counts, :edges, :warnings, keyword_init: true)
+
+    TOOL_MISSING = 'js_tools_missing'
+    TIMEOUT = 'js_depcruise_timeout'
+
+    def initialize(repo_path:, files:, js_timeout: 60, stderr: $stderr)
+      @repo_path = File.expand_path(repo_path)
+      @files = files
+      @js_timeout = js_timeout
+      @stderr = stderr
+    end
+
+    def call
+      return missing_tools unless node_available?
+
+      depcruise = depcruise_binary
+      return missing_tools unless depcruise
+
+      stdout, _stderr, status = run_depcruise(depcruise)
+      return missing_tools unless status.success?
+
+      counts, fan_out_counts, edges = parse(stdout)
+      Result.new(counts: counts, fan_out_counts: fan_out_counts, edges: edges, warnings: [])
+    rescue Timeout::Error
+      warn(TIMEOUT)
+      Result.new(counts: zero_counts, fan_out_counts: zero_counts, edges: empty_edges, warnings: [TIMEOUT])
+    rescue JSON::ParserError, KeyError, TypeError
+      missing_tools
+    end
+
+    private
+
+    def node_available?
+      _stdout, _stderr, status = Open3.capture3('node', '--version')
+      status.success?
+    rescue Errno::ENOENT
+      false
+    end
+
+    def depcruise_binary
+      local = File.join(@repo_path, 'node_modules/.bin/depcruise')
+      return local if File.executable?(local)
+
+      ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |dir|
+        candidate = File.join(dir, 'depcruise')
+        return 'depcruise' if File.file?(candidate) && File.executable?(candidate)
+      end
+
+      nil
+    end
+
+    def run_depcruise(depcruise)
+      Timeout.timeout(@js_timeout) do
+        Open3.capture3(depcruise, '--output-type', 'json', '.', chdir: @repo_path)
+      end
+    end
+
+    def parse(stdout)
+      payload = JSON.parse(stdout)
+      file_set = @files.to_h { |file| [file, true] }
+      counts = zero_counts
+      fan_out_counts = zero_counts
+      dependents = @files.to_h { |file| [file, []] }
+      dependencies = @files.to_h { |file| [file, []] }
+      seen_edges = Set.new
+
+      Array(payload.fetch('modules')).each do |mod|
+        source = normalize_path(mod.fetch('source'))
+        next unless file_set[source]
+
+        Array(mod['dependencies']).each do |dependency|
+          target = normalize_path(dependency['resolved'].to_s)
+          next unless file_set[target]
+          next if target == source
+          next unless seen_edges.add?([source, target])
+
+          counts[target] += 1
+          fan_out_counts[source] += 1
+          dependents[target] << source
+          dependencies[source] << target
+        end
+      end
+
+      edges = @files.to_h do |file|
+        [file, { dependents: dependents[file], dependencies: dependencies[file] }]
+      end
+
+      [counts, fan_out_counts, edges]
+    end
+
+    def normalize_path(path)
+      path.delete_prefix('./')
+    end
+
+    def missing_tools
+      warn(TOOL_MISSING)
+      Result.new(counts: zero_counts, fan_out_counts: zero_counts, edges: empty_edges, warnings: [TOOL_MISSING])
+    end
+
+    def zero_counts
+      @files.to_h { |file| [file, 0] }
+    end
+
+    def empty_edges
+      @files.to_h { |file| [file, { dependents: [], dependencies: [] }] }
+    end
+
+    def warn(code)
+      @stderr.puts "Warning: #{code}"
+    end
+  end
+end

data/lib/stud_finder/normalizer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module StudFinder
+  module Normalizer
+    module_function
+
+    def percentile_rank(raw_counts, files)
+      return {} if files.empty?
+
+      values = files.map { |file| raw_counts.fetch(file, 0).to_f }
+      return files.to_h { |file| [file, 0.0] } if files.length == 1 || values.uniq.length == 1
+
+      denominator = files.length - 1
+      sorted_values = values.sort
+
+      files.to_h do |file|
+        raw = raw_counts.fetch(file, 0).to_f
+        [file, lower_bound(sorted_values, raw).to_f / denominator]
+      end
+    end
+
+    def lower_bound(sorted_values, raw)
+      low = 0
+      high = sorted_values.length
+
+      while low < high
+        mid = (low + high) / 2
+        if sorted_values[mid] < raw
+          low = mid + 1
+        else
+          high = mid
+        end
+      end
+
+      low
+    end
+  end
+end

data/lib/stud_finder/scorer.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative 'normalizer'
+
+module StudFinder
+  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
+
+    class ValidationError < StandardError; end
+
+    attr_reader :normalized_weights
+
+    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)
+      @files = files
+      @fan_in = fan_in
+      @fan_out = fan_out
+      @complexity = complexity
+      @churn = churn
+      @churn_lines = churn_lines || churn
+      @coverage = coverage
+      @weights = weights
+      @branch_threshold = branch_threshold
+      @trunk_threshold = trunk_threshold
+      @coupling = coupling
+      validate!
+      @normalized_weights = normalize_weights
+    end
+
+    def call
+      pcts = {
+        fan_in: Normalizer.percentile_rank(@fan_in, @files),
+        fan_out: Normalizer.percentile_rank(@fan_out, @files),
+        complexity: Normalizer.percentile_rank(@complexity, @files),
+        churn: composite_churn_pct,
+        instability: instability_pct,
+        coupling: coupling_pct
+      }
+
+      rows = @files.each_with_index.map do |file, index|
+        score = weighted_score(file, pcts)
+        [index, result_row(file, score, pcts)]
+      end
+
+      rows.sort_by { |index, row| [-row[:score], index] }
+          .map.with_index(1) do |(_index, row), rank|
+        row.merge(rank: rank)
+      end
+    end
+
+    private
+
+    def validate!
+      return if @branch_threshold < @trunk_threshold
+
+      raise ValidationError, 'Error: branch-threshold must be strictly less than trunk-threshold.'
+    end
+
+    def normalize_weights
+      active_total = RENORMALIZED_KEYS.sum { |key| @weights.fetch(key, 0.0) }
+      if !coverage_available? && 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
+    end
+
+    def weighted_score(file, pcts)
+      return active_weights_score(file, pcts) unless coverage_available?
+
+      file_coverage = @coverage.fetch(file, 0.0)
+      structural_score(@normalized_weights, file, pcts) +
+        (@normalized_weights[:coverage] * (1.0 - file_coverage))
+    end
+
+    def active_weights_score(file, pcts)
+      structural_score(@active_weights, file, pcts)
+    end
+
+    def structural_score(weights, file, pcts)
+      (weights[:fan_in] * pcts[:fan_in].fetch(file)) +
+        (weights[:fan_out] * pcts[:fan_out].fetch(file)) +
+        (weights[:complexity] * pcts[:complexity].fetch(file)) +
+        (weights[:churn] * pcts[:churn].fetch(file))
+    end
+
+    def composite_churn_pct
+      count_pct = Normalizer.percentile_rank(@churn, @files)
+      line_pct = Normalizer.percentile_rank(@churn_lines, @files)
+
+      @files.to_h do |file|
+        [file, (0.5 * count_pct.fetch(file)) + (0.5 * line_pct.fetch(file))]
+      end
+    end
+
+    def result_row(file, score, pcts)
+      fi = @fan_in.fetch(file, 0).to_i
+      fo = @fan_out.fetch(file, 0).to_i
+      {
+        path: file,
+        score: score.round(4),
+        classification: classification(pcts[:fan_in].fetch(file)),
+        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_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),
+        **coupling_fields(file, pcts),
+        coverage: coverage_available? ? @coverage.fetch(file, 0.0).round(4) : nil
+      }
+    end
+
+    def coupling_fields(file, pcts)
+      partner = @coupling&.fetch(file, nil)
+      {
+        max_coupling: partner ? partner.fetch(:max_coupling, 0.0).to_f.round(4) : 0.0,
+        max_coupling_partner: partner ? partner.fetch(:max_coupling_partner, nil).to_s : '',
+        coupling_partners: partner ? partner.fetch(:partners, 0).to_i : 0,
+        coupling_pct: pcts[:coupling].fetch(file, 0.0).round(4)
+      }
+    end
+
+    def instability(fan_in, fan_out)
+      total = fan_in + fan_out
+      return 0.0 if total.zero?
+
+      (fan_out.to_f / total).round(4)
+    end
+
+    def instability_pct
+      values = @files.to_h { |file| [file, instability(@fan_in.fetch(file, 0).to_i, @fan_out.fetch(file, 0).to_i)] }
+      Normalizer.percentile_rank(values, @files)
+    end
+
+    def coupling_pct
+      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_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
+
+      'leaf'
+    end
+  end
+end

data/lib/stud_finder/temporal_coupling.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module StudFinder
+  class TemporalCoupling
+    Result = Struct.new(:pairs, :warnings, keyword_init: true)
+
+    SHA_PATTERN = /\A[0-9a-f]{40}\z/
+
+    def initialize(repo_path:, files:, days:, min_co_changes: 5, coupling_threshold: 0.30)
+      @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
+    end
+
+    def call
+      stdout, _err, status = git_log
+      return Result.new(pairs: {}, warnings: ['git_error']) unless status.success?
+
+      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: [])
+    rescue Errno::ENOENT
+      Result.new(pairs: {}, warnings: ['git_not_found'])
+    end
+
+    private
+
+    def git_log
+      Open3.capture3(
+        'git', '-C', @repo_path, 'log',
+        "--since=#{@days} days ago",
+        '--diff-filter=ACDMR',
+        '--name-only',
+        '--relative',
+        '--format=%H'
+      )
+    end
+
+    def parse_commits(stdout)
+      commits = []
+      current = nil
+      stdout.each_line do |raw|
+        line = raw.chomp
+        if SHA_PATTERN.match?(line)
+          commits << current if current&.any?
+          current = []
+        elsif !line.empty? && current
+          relative = normalize_path(line)
+          # Guard against the same path appearing twice in one commit's --name-only
+          # output: a dup would inflate own_changes and create a spurious self-pair.
+          current << relative if @file_set[relative] && !current.include?(relative)
+        end
+      end
+      commits << current if current&.any?
+      commits
+    end
+
+    def build_co_change_matrix(commits)
+      matrix = Hash.new { |h, k| h[k] = Hash.new(0) }
+      commits.each do |files|
+        files.combination(2).each do |a, b|
+          a, b = b, a if a > b
+          matrix[a][b] += 1
+        end
+      end
+      matrix
+    end
+
+    def build_own_changes(commits)
+      counts = Hash.new(0)
+      commits.each { |files| files.each { |f| counts[f] += 1 } }
+      counts
+    end
+
+    def build_pairs(co_matrix, own_changes)
+      pairs = Hash.new { |h, k| h[k] = [] }
+      co_matrix.each do |a, partners|
+        partners.each do |b, count|
+          next if count < @min_co_changes
+
+          min_own = [own_changes[a], own_changes[b]].min
+          next if min_own.zero?
+
+          coupling = (count.to_f / min_own).round(4)
+          next if coupling < @coupling_threshold
+
+          pairs[a] << { path: b, coupling: coupling, co_changes: count, own_changes: own_changes[b] }
+          pairs[b] << { path: a, coupling: coupling, co_changes: count, own_changes: own_changes[a] }
+        end
+      end
+      pairs.transform_values { |p| p.sort_by { |e| -e[:coupling] } }
+    end
+
+    def normalize_path(path)
+      absolute = File.expand_path(path, @repo_path)
+      absolute.start_with?("#{@repo_path}/") ? absolute.delete_prefix("#{@repo_path}/") : path
+    end
+  end
+end

data/lib/stud_finder/version.rb

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

data/lib/stud_finder.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'stud_finder/version'
+require_relative 'stud_finder/file_collector'
+require_relative 'stud_finder/fan_in'
+require_relative 'stud_finder/js_fan_in'
+require_relative 'stud_finder/js_complexity'
+require_relative 'stud_finder/normalizer'
+require_relative 'stud_finder/coverage/cobertura'
+require_relative 'stud_finder/coverage/detector'
+require_relative 'stud_finder/coverage/lcov'
+require_relative 'stud_finder/coverage/resultset'
+require_relative 'stud_finder/scorer'
+require_relative 'stud_finder/cli'

metadata

@@ -0,0 +1,199 @@
+--- !ruby/object:Gem::Specification
+name: stud-finder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- bazfer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-07-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-ast
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: A code risk scoring CLI for Ruby and JS/TS projects. Ranks every file
+  by five signals — fan-in (blast radius), fan-out, cyclomatic complexity, git churn,
+  and test coverage — with temporal coupling analysis and a diff mode for scoring
+  only the files changed in a PR. Table, JSON, CSV, and Markdown output.
+email:
+- bazfer@gmail.com
+executables:
+- stud-finder
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- PRODUCT.md
+- README.md
+- VISION.md
+- bin/stud-finder
+- lib/stud-finder.rb
+- lib/stud_finder.rb
+- lib/stud_finder/churn.rb
+- lib/stud_finder/cli.rb
+- lib/stud_finder/complexity.rb
+- lib/stud_finder/coverage/cobertura.rb
+- lib/stud_finder/coverage/detector.rb
+- lib/stud_finder/coverage/lcov.rb
+- lib/stud_finder/coverage/resultset.rb
+- lib/stud_finder/diff.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/normalizer.rb
+- lib/stud_finder/scorer.rb
+- lib/stud_finder/temporal_coupling.rb
+- lib/stud_finder/version.rb
+homepage: https://github.com/bazfer/stud-finder
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bazfer/stud-finder
+  source_code_uri: https://github.com/bazfer/stud-finder
+  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: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Rank files by structural risk in Ruby and JavaScript/TypeScript codebases.
+test_files: []