stud-finder 0.1.0

data/lib/stud_finder/complexity.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'tempfile'
+
+module StudFinder
+  class Complexity
+    Result = Struct.new(:counts, :skipped_files, keyword_init: true)
+
+    class Error < StandardError; end
+
+    COMPLEXITY_COP = 'Metrics/CyclomaticComplexity'
+    COMPLEXITY_PATTERN = %r{\[(\d+)/0\]}
+    PARSE_ERROR_COPS = %w[Lint/Syntax].freeze
+    RUBOCOP_CONFIG = <<~YAML
+      AllCops:
+        DisabledByDefault: true
+      Metrics/CyclomaticComplexity:
+        Enabled: true
+        Max: 0
+    YAML
+
+    def initialize(repo_path:, files:, stderr: $stderr)
+      @repo_path = File.expand_path(repo_path)
+      @files = files
+      @stderr = stderr
+    end
+
+    def call
+      stdout, stderr, status = run_rubocop
+      raise Error, fatal_message(stderr) if status.exitstatus == 2
+      raise Error, fatal_message(stderr) unless [0, 1].include?(status.exitstatus)
+
+      parse(stdout)
+    rescue Errno::ENOENT
+      raise Error, 'Error: rubocop not found. Install it: gem install rubocop'
+    rescue JSON::ParserError => e
+      raise Error, "Error: failed to parse RuboCop JSON output: #{e.message}"
+    end
+
+    private
+
+    def run_rubocop
+      Tempfile.create(['stud-finder-rubocop', '.yml']) do |config|
+        config.write(RUBOCOP_CONFIG)
+        config.close
+
+        Open3.capture3(
+          'rubocop',
+          '--config', config.path,
+          '--format', 'json',
+          @repo_path
+        )
+      end
+    end
+
+    def parse(stdout)
+      payload = JSON.parse(stdout)
+      counts = @files.to_h { |file| [file, 0] }
+      skipped = []
+      file_set = counts.keys.to_h { |file| [file, true] }
+
+      Array(payload['files']).each do |entry|
+        relative = normalize_path(entry['path'].to_s)
+        next unless file_set[relative]
+
+        offenses = Array(entry['offenses'])
+        if parse_error?(offenses)
+          skipped << relative
+          counts.delete(relative)
+          @stderr.puts "Warning: skipping #{relative}; RuboCop could not parse file."
+          next
+        end
+
+        counts[relative] = offenses.map { |offense| complexity_score(offense) }.max || 0
+      end
+
+      Result.new(counts: counts, skipped_files: skipped)
+    end
+
+    def complexity_score(offense)
+      return 0 unless offense['cop_name'] == COMPLEXITY_COP
+
+      offense.fetch('message', '').match(COMPLEXITY_PATTERN)&.[](1).to_i
+    end
+
+    def parse_error?(offenses)
+      offenses.any? { |offense| PARSE_ERROR_COPS.include?(offense['cop_name']) || offense['fatal'] == true }
+    end
+
+    def normalize_path(path)
+      absolute = File.expand_path(path, @repo_path)
+      absolute.start_with?("#{@repo_path}/") ? absolute.delete_prefix("#{@repo_path}/") : path
+    end
+
+    def fatal_message(stderr)
+      message = stderr.to_s.strip
+      return 'Error: rubocop failed.' if message.empty?
+
+      "Error: rubocop failed: #{message}"
+    end
+  end
+end

data/lib/stud_finder/coverage/cobertura.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+
+module StudFinder
+  module Coverage
+    class Cobertura
+      class Error < StandardError; end
+
+      attr_reader :missing_files
+
+      def initialize(path:, files:, project_root: nil)
+        @path = path
+        @files = files
+        @project_root = project_root
+        @missing_files = []
+      end
+
+      def call
+        reported = parse_report
+        @missing_files = @files.reject { |file| reported.key?(file) }
+        @files.to_h { |file| [file, reported.fetch(file, 0.0)] }
+      end
+
+      private
+
+      def parse_report
+        document = REXML::Document.new(File.read(@path))
+        {}.tap do |coverage|
+          REXML::XPath.each(document, '/coverage/packages/package/classes/class') do |element|
+            filename = element.attributes['filename']
+            next if filename.nil? || filename.empty?
+
+            coverage[normalize_filename(filename)] = parse_line_rate(filename, element.attributes['line-rate'])
+          end
+        end
+      rescue REXML::ParseException => e
+        raise Error, "Error: malformed coverage XML: #{e.message.lines.first.strip}"
+      rescue Errno::ENOENT
+        raise Error, "Error: coverage file not found: #{@path}"
+      end
+
+      def normalize_filename(filename)
+        filename.delete_prefix('./')
+      end
+
+      def parse_line_rate(filename, raw_rate)
+        raise Error, "Error: missing line-rate for coverage file: #{filename}" if raw_rate.nil? || raw_rate.empty?
+
+        rate = Float(raw_rate)
+        return rate if rate.between?(0.0, 1.0)
+
+        raise Error, "Error: line-rate out of range for coverage file: #{filename}"
+      rescue ArgumentError
+        raise Error, "Error: invalid line-rate for coverage file: #{filename}"
+      end
+    end
+  end
+end

data/lib/stud_finder/coverage/detector.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'cobertura'
+require_relative 'lcov'
+require_relative 'resultset'
+
+module StudFinder
+  module Coverage
+    class Detector
+      class Error < StandardError; end
+
+      PARSERS = {
+        '.xml' => Cobertura,
+        '.info' => Lcov,
+        '.json' => Resultset
+      }.freeze
+
+      def self.for(path:, files:, project_root: nil)
+        parser = PARSERS[File.extname(path).downcase]
+        raise Error, "Error: unsupported coverage file type: #{path}" if parser.nil?
+
+        parser.new(path: path, files: files, project_root: project_root)
+      end
+    end
+  end
+end

data/lib/stud_finder/coverage/lcov.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module StudFinder
+  module Coverage
+    class Lcov
+      class Error < StandardError; end
+
+      attr_reader :missing_files
+
+      def initialize(path:, files:, project_root: nil)
+        @path = path
+        @files = files
+        @file_set = Set.new(files)
+        @project_root = File.expand_path(project_root) if project_root
+        @missing_files = []
+      end
+
+      def call
+        reported = parse_report
+        @missing_files = @files.reject { |file| reported.key?(file) }
+        @files.to_h { |file| [file, reported.fetch(file, 0.0)] }
+      end
+
+      private
+
+      def parse_report
+        records = File.read(@path).split(/^end_of_record\s*$/)
+        records.each_with_object({}) do |record, coverage|
+          filename = record[/^SF:(.+)$/, 1]
+          next if filename.nil? || filename.empty?
+
+          coverage[normalize_filename(filename)] = line_rate(record, filename)
+        end
+      rescue Errno::ENOENT
+        raise Error, "Error: coverage file not found: #{@path}"
+      end
+
+      def normalize_filename(filename)
+        expanded = File.expand_path(filename)
+        stripped = project_root_stripped(filename, expanded)
+        return stripped if stripped && @file_set.include?(stripped)
+
+        if filename.start_with?('/')
+          suffix_match(filename) || stripped || filename.delete_prefix('./')
+        else
+          stripped || filename.delete_prefix('./')
+        end
+      end
+
+      def project_root_stripped(filename, expanded)
+        if @project_root && filename.start_with?("#{@project_root}/")
+          filename.delete_prefix("#{@project_root}/")
+        elsif @project_root && expanded.start_with?("#{@project_root}/")
+          expanded.delete_prefix("#{@project_root}/")
+        end
+      end
+
+      def suffix_match(filename)
+        components = filename.split('/').reject(&:empty?)
+
+        components.length.downto(1) do |count|
+          suffix = components.last(count).join('/')
+          return suffix if @file_set.include?(suffix)
+        end
+
+        nil
+      end
+
+      def line_rate(record, filename)
+        found = integer_field(record, 'LF')
+        hit = integer_field(record, 'LH')
+
+        if found.nil? || hit.nil?
+          lines = record.scan(/^DA:\d+,(\d+)/).flatten.map(&:to_i)
+          found = lines.length
+          hit = lines.count(&:positive?)
+        end
+
+        return 0.0 if found.zero?
+        raise Error, "Error: line hits exceed lines found for coverage file: #{filename}" if hit > found
+
+        hit.to_f / found
+      end
+
+      def integer_field(record, field)
+        raw = record[/^#{field}:(\d+)$/, 1]
+        raw&.to_i
+      end
+    end
+  end
+end

data/lib/stud_finder/coverage/resultset.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'set'
+
+module StudFinder
+  module Coverage
+    class Resultset
+      class Error < StandardError; end
+
+      attr_reader :missing_files
+
+      def initialize(path:, files:, project_root: nil)
+        @path = path
+        @files = files
+        @file_set = Set.new(files)
+        @project_root = File.expand_path(project_root) if project_root
+        @missing_files = []
+      end
+
+      def call
+        reported = parse_report
+        @missing_files = @files.reject { |file| reported.key?(file) }
+        @files.to_h { |file| [file, reported.fetch(file, 0.0)] }
+      end
+
+      private
+
+      def parse_report
+        data = JSON.parse(File.read(@path))
+        merged = {}
+
+        coverage_payloads(data).each do |coverage|
+          coverage.each do |filename, details|
+            lines = details.is_a?(Hash) ? details['lines'] : details
+            next unless lines.is_a?(Array)
+
+            key = normalize_filename(filename)
+            merged[key] = merged.key?(key) ? merge_lines(merged[key], lines) : lines
+          end
+        end
+
+        merged.transform_values { |lines| line_rate(lines) }
+      rescue JSON::ParserError => e
+        raise Error, "Error: malformed coverage JSON: #{e.message.lines.first.strip}"
+      rescue Errno::ENOENT
+        raise Error, "Error: coverage file not found: #{@path}"
+      end
+
+      def merge_lines(previous_lines, new_lines)
+        max_length = [previous_lines.length, new_lines.length].max
+
+        (0...max_length).map do |index|
+          previous = previous_lines[index]
+          current = new_lines[index]
+
+          previous.nil? && current.nil? ? nil : [previous || 0, current || 0].max
+        end
+      end
+
+      def coverage_payloads(data)
+        if data['coverage'].is_a?(Hash)
+          [data['coverage']]
+        else
+          data.values.filter_map { |suite| suite['coverage'] if suite.is_a?(Hash) }
+        end
+      end
+
+      def normalize_filename(filename)
+        stripped = project_root_stripped(filename)
+        return stripped if stripped && @file_set.include?(stripped)
+
+        if filename.start_with?('/')
+          suffix_match(filename) || stripped || filename.delete_prefix('./')
+        else
+          stripped || filename.delete_prefix('./')
+        end
+      end
+
+      def project_root_stripped(filename)
+        filename.delete_prefix("#{@project_root}/") if @project_root && filename.start_with?("#{@project_root}/")
+      end
+
+      def suffix_match(filename)
+        components = filename.split('/').reject(&:empty?)
+
+        components.length.downto(1) do |count|
+          suffix = components.last(count).join('/')
+          return suffix if @file_set.include?(suffix)
+        end
+
+        nil
+      end
+
+      def line_rate(lines)
+        executable = lines.compact
+        return 0.0 if executable.empty?
+
+        executable.count(&:positive?).to_f / executable.length
+      end
+    end
+  end
+end

data/lib/stud_finder/diff.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module StudFinder
+  # Resolves the set of files changed on HEAD relative to the merge-base with a
+  # base ref (e.g. origin/staging), as repo-root-relative paths that match the
+  # form FileCollector emits. Used to filter output down to a PR's touched files
+  # WITHOUT narrowing the analysis population — scoring still runs against the
+  # full repo, so fan_in and percentiles stay correct.
+  class Diff
+    class Error < StandardError; end
+
+    def initialize(repo_path:, base_ref:)
+      @repo_path = File.expand_path(repo_path)
+      @base_ref = base_ref
+    end
+
+    def validate_ref!
+      verify_ref!
+    end
+
+    def changed_paths
+      verify_ref!
+      stdout, stderr, status = Open3.capture3(
+        'git', '-C', @repo_path, 'diff', '--name-only', '--diff-filter=d', "#{@base_ref}...HEAD"
+      )
+      raise Error, diff_error(stderr) unless status.success?
+
+      stdout.each_line.map(&:strip).reject(&:empty?)
+    rescue Errno::ENOENT
+      raise Error, 'Error: git not found in PATH.'
+    end
+
+    private
+
+    def verify_ref!
+      _stdout, _stderr, status = Open3.capture3(
+        'git', '-C', @repo_path, 'rev-parse', '--verify', '--quiet', "#{@base_ref}^{commit}"
+      )
+      return if status.success?
+
+      raise Error, "Error: diff base ref not found: #{@base_ref}"
+    end
+
+    def diff_error(stderr)
+      message = stderr.to_s.strip
+      return 'Error: git diff failed.' if message.empty?
+
+      "Error: git diff failed: #{message}"
+    end
+  end
+end

data/lib/stud_finder/edges.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module StudFinder
+  class Edges
+    MAX_ROWS = 50
+
+    CouplingConfig = Struct.new(:data, :churn_days, :min_commits, :threshold, keyword_init: true)
+
+    def initialize(target:, rows:, edges:, coupling: {}, churn_days: 180,
+                   coupling_min_commits: 5, coupling_threshold: 0.30,
+                   stdout: $stdout, stderr: $stderr)
+      @target = target
+      @rows = rows.to_h { |row| [row[:path], row] }
+      @edges = edges
+      @coupling = CouplingConfig.new(data: coupling, churn_days: churn_days,
+                                     min_commits: coupling_min_commits, threshold: coupling_threshold)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def call
+      if @target.nil? || @target.empty?
+        @stderr.puts 'Usage: stud-finder edges FILE [PATH]'
+        return 1
+      end
+
+      unless @edges.key?(@target)
+        @stderr.puts "Error: '#{@target}' was not found in the scored file set."
+        return 1
+      end
+
+      target_row = @rows[@target]
+      edge_data = @edges[@target]
+
+      emit_header(target_row)
+      emit_section('Dependents', edge_data[:dependents], '(files that depend on this file — blast radius)')
+      emit_section('Dependencies', edge_data[:dependencies], '(files this file depends on — fan-out)')
+      emit_coupling_section
+      @stdout.puts
+      @stdout.puts 'Edges are statically computed — dynamic references not counted.'
+      @stdout.puts "Temporal coupling from git history (#{@coupling.churn_days}-day window)."
+      0
+    end
+
+    private
+
+    def emit_header(row)
+      @stdout.puts
+      @stdout.puts "stud-finder edges — #{@target}"
+      @stdout.puts
+      if row
+        @stdout.puts format('  score: %<score>s  class: %<class>-6s  fan_in: %<fan_in>d  ' \
+                            'fan_out: %<fan_out>d  instability: %<instability>s',
+                            score: format_score(row[:score]), class: row[:classification],
+                            fan_in: row[:fan_in], fan_out: row[:fan_out],
+                            instability: format_score(row[:instability]))
+      end
+      @stdout.puts
+    end
+
+    def emit_section(title, paths, description)
+      scored, unscored = paths.partition { |p| @rows.key?(p) }
+      scored_rows = scored.map { |p| @rows[p] }.sort_by { |r| -r[:score] }.first(MAX_ROWS)
+
+      @stdout.puts "  ── #{title} (#{paths.length} files) #{description} ──"
+      @stdout.puts
+
+      if scored_rows.empty?
+        @stdout.puts '    (none in scored file set)'
+      else
+        @stdout.puts format('  %<rank>4s  %<path>-50s  %<score>6s  %<class>-6s  %<fan_in>6s  %<fan_out>6s  ' \
+                            '%<instability>11s',
+                            rank: 'rank', path: 'file', score: 'score', class: 'class',
+                            fan_in: 'fan_in', fan_out: 'fan_out', instability: 'instability')
+        scored_rows.each_with_index do |row, i|
+          @stdout.puts format('  %<rank>4d  %<path>-50s  %<score>6s  %<class>-6s  %<fan_in>6d  %<fan_out>6d  ' \
+                              '%<instability>11s',
+                              rank: i + 1, path: row[:path], score: format_score(row[:score]),
+                              class: row[:classification], fan_in: row[:fan_in], fan_out: row[:fan_out],
+                              instability: format_score(row[:instability]))
+        end
+        @stdout.puts "    ... and #{unscored.length} unscored (gems, generated files)" if unscored.any?
+      end
+      @stdout.puts
+    end
+
+    def emit_coupling_section
+      @stdout.puts format(
+        '  ── Temporal Coupling (%<days>d-day window, min %<min>d co-changes, threshold %<threshold>.2f) ──',
+        days: @coupling.churn_days, min: @coupling.min_commits, threshold: @coupling.threshold
+      )
+      @stdout.puts
+
+      partners = @coupling.data[@target] || []
+      if partners.empty?
+        @stdout.puts '    (none above threshold)'
+      else
+        @stdout.puts '   coupling  co_changes  file'
+        partners.each do |entry|
+          @stdout.puts format('  %<coupling>8s  %<co_changes>10d  %<path>s',
+                              coupling: format_score(entry[:coupling]),
+                              co_changes: entry[:co_changes],
+                              path: entry[:path])
+        end
+      end
+      @stdout.puts
+    end
+
+    def format_score(score)
+      format('%.4f', score)
+    end
+  end
+end