stud-finder 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e14a94cc20570cd7eb6b592b62b0cbf7268d8be02f546a3f1f343146f6b3c6f
-  data.tar.gz: a49e0535ae4dc3f97958e2758773a04ceb7b486e7f7582a3048562dafbcfeaf4
+  metadata.gz: d5c4ae36f3971b4c2aa32bc157c76eea4223b401764e2f895f541d4532f5ed8d
+  data.tar.gz: '0180283bc3f6c389e7c4b68ce42819e8d5bd5ec08684031249b4deb7915e7b62'
 SHA512:
-  metadata.gz: d036d77feaec9b455cf6abe8d5f2578f25a91f7948bb91d7a97150d94b007c38fd4daa4b4ea0bce21c41168b31f3f70cb03779657af4c156a7c4225d17fa6020
-  data.tar.gz: ff082727ae14f9dbd27a0a11528a4f3223df541218ab58f4ac7420adae66b405eef05ae541c20da3ad3a97cd738c2104bc5b916ad1846ac6066f361576e2f3a2
+  metadata.gz: 9bc2be78efee09c43411250904494503d23b9080e70bbd962cc043dc92073fc94c2903eef4cbe8dd828cb35fd4a5ce70758a815c5ed110a8bfb7250dcf37fc32
+  data.tar.gz: 6a808490d99422741999eb3d559c813b1c7e7646a8195bb4d6cc87541fdf21d4420f914e345acb68522d79ee72510101f1f4fb96549d01080b4f105e0318f347

data/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.7.0] - Unreleased
+
+### Added
+
+- Added `stud-finder gate`, an observation-first markdown gate subcommand for JSON scan output. v1 includes hardcoded checks for touched trunks, high-score files with low/missing evidence, and new files escalated by trunk adjacency.
+- Added `--input FILE`/stdin input handling and an `--enforce` flag for gate failures. `--enforce` exists for CI experiments, but do not recommend it as a required merge gate until the Rec 3 rollout lands and teams have calibrated thresholds on real PRs.
+
+## [0.6.0] - Unreleased
+
+### Changed
+
+- BREAKING: JSON output now reports `meta.schema_version: 1`, an integer schema marker that will bump on future breaking JSON changes.
+- BREAKING: JSON `warnings` and `meta.warnings` are now normalized to objects shaped as `{code, message}`. Bare warning strings are no longer emitted.
+
 ## [0.5.1] - Unreleased
 
 ### Added

data/README.md

@@ -165,7 +165,7 @@ In shallow clones where auto-unshallow fails (or `--no-auto-unshallow` is set),
 
 ## Warnings
 
-`analysis.warnings` (available in JSON output) surfaces conditions the run detected that a consumer should know about:
+`analysis.warnings` (available in JSON output) surfaces conditions the run detected that a consumer should know about. Starting in schema version `1`, every warning is an object with `code` and human-readable `message` fields; bare warning strings are no longer emitted.
 
 - **`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.
@@ -245,7 +245,7 @@ Each language gets its own ranking section in the output — Ruby and JS are not
 
 - `table` — human-readable, aligned columns
 - `csv` — spreadsheet-friendly, pipe to a file
-- `json` — machine-readable with `meta`, `warnings`, `ruby`, `javascript` sections. `meta.formula` labels the active mode (`5-factor + coupling`, `5-factor`, `4-factor + coupling`, `4-factor`). `meta.weights` reports the normalized weights actually used (with `null` for signals that were unavailable).
+- `json` — machine-readable with `meta`, `warnings`, `ruby`, `javascript` sections. `meta.schema_version` is the integer JSON schema version (`1` as of Stud Finder 0.6.0). `meta.formula` labels the active mode (`5-factor + coupling`, `5-factor`, `4-factor + coupling`, `4-factor`). `meta.weights` reports the normalized weights actually used (with `null` for signals that were unavailable).
 - `markdown` — drop directly into a PR comment or issue
 
 ---

data/lib/stud_finder/cli.rb

@@ -9,6 +9,7 @@ require 'set'
 require 'time'
 require_relative 'churn'
 require_relative 'temporal_coupling'
+require_relative 'warnings'
 require_relative 'complexity'
 require_relative 'diff'
 require_relative 'coverage/detector'
@@ -17,6 +18,7 @@ require_relative 'fan_in'
 require_relative 'js_fan_in'
 require_relative 'js_complexity'
 require_relative 'file_collector'
+require_relative 'gate'
 require_relative 'loc_counter'
 require_relative 'newness'
 require_relative 'scorer'
@@ -73,32 +75,40 @@ module StudFinder
 
     class ValidationError < StandardError; end
 
-    def initialize(argv, stdout: $stdout, stderr: $stderr)
+    def initialize(argv, stdout: $stdout, stderr: $stderr, stdin: $stdin)
       @argv = argv.dup
       @stdout = stdout
       @stderr = stderr
+      @stdin = stdin
       @options = Marshal.load(Marshal.dump(DEFAULT_OPTIONS))
     end
 
-    def self.start(argv = ARGV, stdout: $stdout, stderr: $stderr)
-      new(argv, stdout: stdout, stderr: stderr).run
+    def self.start(argv = ARGV, stdout: $stdout, stderr: $stderr, stdin: $stdin)
+      new(argv, stdout: stdout, stderr: stderr, stdin: stdin).run
     end
 
     def run
       parser = option_parser
+      return run_gate if shift_subcommand?('gate')
+      return run_edges_subcommand(parser) if shift_subcommand?('edges')
 
-      if @argv[0] == 'edges'
-        @argv.shift
-        parser.parse!(@argv)
-        target = @argv.shift
-        path = @argv.shift || '.'
-        raise ValidationError, "Error: unexpected arguments: #{@argv.join(' ')}" unless @argv.empty?
+      run_scan(parser)
+    rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::InvalidArgument, ValidationError,
+           FileCollector::Error, Gate::Error, Churn::Error, Complexity::Error, Coverage::Cobertura::Error,
+           Coverage::Detector::Error, Coverage::Lcov::Error, Coverage::Resultset::Error, Diff::Error, Newness::Error,
+           Scorer::ValidationError => e
+      @stderr.puts e.message
+      1
+    end
 
-        @repo_path = File.expand_path(path)
-        validate_options!
-        return run_edges(target, path)
-      end
+    def shift_subcommand?(name)
+      return false unless @argv[0] == name
+
+      @argv.shift
+      true
+    end
 
+    def run_scan(parser)
       parser.parse!(@argv)
       path = @argv.shift || '.'
       raise ValidationError, "Error: unexpected arguments: #{@argv.join(' ')}" unless @argv.empty?
@@ -121,11 +131,41 @@ module StudFinder
       analysis = warn_if_no_scored_files(analysis)
       emit_results(@repo_path, result, analysis)
       0
-    rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::InvalidArgument, ValidationError,
-           FileCollector::Error, Churn::Error, Complexity::Error, Coverage::Cobertura::Error, Coverage::Detector::Error,
-           Coverage::Lcov::Error, Coverage::Resultset::Error, Diff::Error, Newness::Error, Scorer::ValidationError => e
-      @stderr.puts e.message
-      1
+    end
+
+    def run_edges_subcommand(parser)
+      parser.parse!(@argv)
+      target = @argv.shift
+      path = @argv.shift || '.'
+      raise ValidationError, "Error: unexpected arguments: #{@argv.join(' ')}" unless @argv.empty?
+
+      @repo_path = File.expand_path(path)
+      validate_options!
+      run_edges(target, path)
+    end
+
+    def run_gate
+      gate_options = { input: nil, enforce: false }
+      OptionParser.new do |opts|
+        opts.banner = 'Usage: stud-finder gate [--input FILE] [--enforce]'
+        opts.on('--input FILE', 'Read stud-finder JSON output from FILE') { |value| gate_options[:input] = value }
+        opts.on('--enforce', 'Exit non-zero when gate findings are present') { gate_options[:enforce] = true }
+      end.parse!(@argv)
+      raise ValidationError, "Error: unexpected arguments: #{@argv.join(' ')}" unless @argv.empty?
+
+      json = gate_input(gate_options[:input])
+      result = Gate.call(json)
+      @stdout.puts Gate.markdown(result, enforce: gate_options[:enforce])
+      gate_options[:enforce] && result.findings? ? 1 : 0
+    end
+
+    def gate_input(input_path)
+      return File.read(input_path) if input_path
+      return @stdin.read if !@stdin.respond_to?(:tty?) || !@stdin.tty?
+
+      raise ValidationError, 'Error: provide --input FILE or pipe JSON to stdin.'
+    rescue Errno::ENOENT
+      raise ValidationError, "Error: input file not found: #{input_path}"
     end
 
     def run_edges(target, path)
@@ -722,7 +762,7 @@ module StudFinder
     def emit_json(path, analysis, ruby_rows, javascript_rows)
       @stdout.puts JSON.generate(
         meta: json_meta(path, analysis),
-        warnings: analysis.warnings,
+        warnings: Warnings.normalize(analysis.warnings),
         ruby: ruby_rows.map { |row| json_file(row) },
         javascript: javascript_rows.map { |row| json_file(row) }
       )
@@ -737,7 +777,8 @@ module StudFinder
         files_skipped: analysis.ruby.skipped_files.length + analysis.javascript.skipped_files.length,
         formula: json_formula(analysis),
         weights: json_weights(analysis.ruby.weights || analysis.javascript.weights),
-        warnings: analysis.warnings
+        schema_version: 1,
+        warnings: Warnings.normalize(analysis.warnings)
       }
       meta[:filtered] = true if @options[:filter_set]
       meta[:diff_base] = @options[:diff_base] if @options[:diff_base]

data/lib/stud_finder/gate.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module StudFinder
+  class Gate
+    CHECKS = %w[trunk_touched low_evidence_high_score newness_trunk_adjacent].freeze
+    HIGH_SCORE_THRESHOLD = 0.75
+    LOW_EVIDENCE_THRESHOLD = 0.50
+
+    Finding = Struct.new(:path, :language, :score, :evidence, :classification, :reason, keyword_init: true)
+    Result = Struct.new(:checks, keyword_init: true) do
+      def finding_count
+        checks.values.sum(&:length)
+      end
+
+      def findings?
+        finding_count.positive?
+      end
+    end
+
+    class Error < StandardError; end
+
+    def self.call(json)
+      new(json).call
+    end
+
+    def initialize(json)
+      @payload = JSON.parse(json)
+    rescue JSON::ParserError => e
+      raise Error, "Error: invalid JSON input: #{e.message}"
+    end
+
+    def call
+      rows = Array(@payload.fetch('ruby', [])) + Array(@payload.fetch('javascript', []))
+      Result.new(
+        checks: {
+          'trunk_touched' => trunk_touched(rows),
+          'low_evidence_high_score' => low_evidence_high_score(rows),
+          'newness_trunk_adjacent' => newness_trunk_adjacent(rows)
+        }
+      )
+    end
+
+    def self.markdown(result, enforce: false)
+      (markdown_header(result, enforce: enforce) + markdown_summary(result) + markdown_details(result)).join("\n")
+    end
+
+    def self.markdown_header(result, enforce:)
+      [
+        '## Stud Finder gate',
+        '',
+        "**Mode:** #{enforce ? 'enforce' : 'observation'}",
+        "**Summary:** #{pluralize(result.finding_count, 'finding')} across #{CHECKS.length} checks.",
+        ''
+      ]
+    end
+    private_class_method :markdown_header
+
+    def self.markdown_summary(result)
+      CHECKS.map do |check|
+        findings = result.checks.fetch(check)
+        status = findings.empty? ? '✅' : '⚠️'
+        "- #{status} `#{check}` — #{pluralize(findings.length, 'finding')}"
+      end + ['']
+    end
+    private_class_method :markdown_summary
+
+    def self.markdown_details(result)
+      CHECKS.flat_map { |check| markdown_check_detail(check, result.checks.fetch(check)) }
+    end
+    private_class_method :markdown_details
+
+    def self.markdown_check_detail(check, findings)
+      [
+        "<details#{' open' if findings.any?}>",
+        "<summary><strong>#{check}</strong> — #{pluralize(findings.length, 'finding')}</summary>",
+        '',
+        *markdown_finding_rows(findings),
+        '',
+        '</details>',
+        ''
+      ]
+    end
+    private_class_method :markdown_check_detail
+
+    def self.markdown_finding_rows(findings)
+      return ['_No findings._'] if findings.empty?
+
+      ['| file | class | score | evidence | reason |', '| --- | --- | ---: | ---: | --- |'] +
+        findings.map { |finding| markdown_finding_row(finding) }
+    end
+    private_class_method :markdown_finding_rows
+
+    def self.markdown_finding_row(finding)
+      "| `#{escape_md(finding.path)}` | #{escape_md(finding.classification)} | " \
+        "#{format_number(finding.score)} | #{format_evidence(finding.evidence)} | #{escape_md(finding.reason)} |"
+    end
+    private_class_method :markdown_finding_row
+
+    def self.pluralize(count, noun)
+      "#{count} #{noun}#{'s' unless count == 1}"
+    end
+    private_class_method :pluralize
+
+    def self.escape_md(value)
+      value.to_s.gsub('|', '\\|')
+    end
+    private_class_method :escape_md
+
+    def self.format_number(value)
+      value.nil? ? '—' : format('%.4f', value.to_f)
+    end
+    private_class_method :format_number
+
+    def self.format_evidence(value)
+      value.nil? ? 'nil' : format_number(value)
+    end
+    private_class_method :format_evidence
+
+    private
+
+    def trunk_touched(rows)
+      rows.select { |row| row['class'] == 'trunk' }.map do |row|
+        finding(row, reason: 'Changed file is classified as trunk.')
+      end
+    end
+
+    def low_evidence_high_score(rows)
+      risky_rows = rows.select do |row|
+        row.fetch('score', 0).to_f >= HIGH_SCORE_THRESHOLD && low_evidence?(row['evidence'])
+      end
+      risky_rows.map do |row|
+        finding(row, reason: low_evidence_high_score_reason)
+      end
+    end
+
+    def low_evidence_high_score_reason
+      "Score is >= #{HIGH_SCORE_THRESHOLD} while evidence is nil or < #{LOW_EVIDENCE_THRESHOLD}."
+    end
+
+    def newness_trunk_adjacent(rows)
+      rows.select { |row| row['new_file'] && row['escalation'] == 'trunk_adjacent' }.map do |row|
+        finding(row, reason: 'New file is trunk-adjacent.')
+      end
+    end
+
+    def low_evidence?(value)
+      value.nil? || value.to_f < LOW_EVIDENCE_THRESHOLD
+    end
+
+    def finding(row, reason:)
+      Finding.new(
+        path: row.fetch('path'),
+        language: row['language'],
+        score: row['score'],
+        evidence: row['evidence'],
+        classification: row['class'],
+        reason: reason
+      )
+    end
+  end
+end

data/lib/stud_finder/version.rb

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

data/lib/stud_finder/warnings.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module StudFinder
+  module Warnings
+    MESSAGES = {
+      'coverage_flag_deprecated' => '--coverage is deprecated; use --ruby-coverage instead',
+      'coverage_unavailable' => 'coverage data was not provided; coverage and interaction signals are unavailable',
+      'coverage_partial' => 'coverage data did not include every scored file; missing files use uncovered risk',
+      'diff_filter_empty' => 'diff filter matched no changed files; output rows are empty',
+      'diff_no_scored_files' => 'diff matched no scored files; the PR may only touch unscorable files',
+      'fan_in_rails_inference_failed' => 'Rails inference failed; inferred Rails references may be incomplete',
+      'fan_in_reference_resolution_failed' => 'constant reference resolution failed; fan-in may be incomplete',
+      'files_skipped' => 'one or more files were skipped during analysis',
+      'git_error' => 'git command failed while computing temporal coupling; coupling is unavailable',
+      'git_not_found' => 'git was not found in PATH while computing temporal coupling; coupling is unavailable',
+      'js_depcruise_failed' => 'dependency-cruiser failed; JavaScript/TypeScript fan-in is unavailable',
+      'js_depcruise_no_config' => 'dependency-cruiser config failed; retried with --no-config, so ' \
+                                  'JavaScript/TypeScript fan-in may be undercounted',
+      'js_depcruise_timeout' => 'dependency-cruiser timed out; JavaScript/TypeScript fan-in is unavailable',
+      'js_eslint_failed' => 'ESLint failed for at least one batch; JavaScript/TypeScript complexity may be incomplete',
+      'js_eslint_malformed' => 'ESLint produced malformed JSON for at least one batch; JavaScript/TypeScript ' \
+                               'complexity may be incomplete',
+      'js_eslint_missing' => 'ESLint was not found; JavaScript/TypeScript complexity is unavailable',
+      'js_eslint_timeout' => 'ESLint timed out for at least one batch; JavaScript/TypeScript complexity may be ' \
+                             'incomplete',
+      'js_tools_missing' => 'Node.js or dependency-cruiser was not found; JavaScript/TypeScript fan-in is unavailable',
+      'js_ts_parser_missing' => 'TypeScript files were present but @typescript-eslint/parser was not found; ' \
+                                'TypeScript complexity may be incomplete',
+      'shallow_clone_newness_disabled' => 'shallow git clone detected; newness rules disabled (use fetch-depth: 0)',
+      'shallow_clone_unshallow_failed' => 'auto-unshallow failed; evidence unavailable (use full git history)',
+      'small_repo' => 'repo has fewer files than --min-files; results may be noisy',
+      'temporal_coupling_bulk_commits_skipped' => 'one or more bulk commits were skipped while computing temporal ' \
+                                                  'coupling',
+      'zero_churn_majority' => 'most files have zero churn in the selected window; churn may be less informative'
+    }.freeze
+
+    INSUFFICIENT_DISPERSION_MESSAGE = lambda do |signal|
+      "every file has the same non-zero raw #{signal} value, so its percentile-ranked contribution collapsed to 0.0"
+    end
+    private_constant :INSUFFICIENT_DISPERSION_MESSAGE
+
+    module_function
+
+    def normalize(items)
+      Array(items).map { |item| normalize_one(item) }.uniq { |warning| warning.fetch(:code) }
+    end
+
+    def normalize_one(item)
+      code, explicit_message = warning_parts(item)
+      { code: code, message: message_for(code, explicit_message, item) }
+    end
+
+    def message_for(code, explicit_message = nil, item = nil)
+      return explicit_message.to_s unless explicit_message.to_s.empty?
+
+      if code.start_with?('insufficient_dispersion_')
+        signal = code.delete_prefix('insufficient_dispersion_')
+        return INSUFFICIENT_DISPERSION_MESSAGE.call(signal)
+      end
+
+      if code == 'temporal_coupling_bulk_commits_skipped' && item.respond_to?(:fetch)
+        count = item.fetch(:count, nil) || item.fetch('count', nil)
+        max = item.fetch(:max_commit_files, nil) || item.fetch('max_commit_files', nil)
+        return "#{MESSAGES.fetch(code)} (#{count} skipped; max_commit_files=#{max})" if count && max
+      end
+
+      MESSAGES.fetch(code) { code.tr('_', ' ') }
+    end
+
+    def warning_parts(item)
+      if item.respond_to?(:fetch) && (item.key?(:code) || item.key?('code'))
+        code = item.fetch(:code, nil) || item.fetch('code')
+        message = item.fetch(:message, nil) || item.fetch('message', nil)
+        [code.to_s, message]
+      else
+        [item.to_s, nil]
+      end
+    end
+    private_class_method :warning_parts
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stud-finder
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.7.0
 platform: ruby
 authors:
 - bazfer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-13 00:00:00.000000000 Z
+date: 2026-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -162,6 +162,7 @@ files:
 - lib/stud_finder/edges.rb
 - lib/stud_finder/fan_in.rb
 - lib/stud_finder/file_collector.rb
+- lib/stud_finder/gate.rb
 - lib/stud_finder/js_complexity.rb
 - lib/stud_finder/js_fan_in.rb
 - lib/stud_finder/loc_counter.rb
@@ -171,6 +172,7 @@ files:
 - lib/stud_finder/scorer.rb
 - lib/stud_finder/temporal_coupling.rb
 - lib/stud_finder/version.rb
+- lib/stud_finder/warnings.rb
 homepage: https://github.com/bazfer/stud-finder
 licenses:
 - MIT