stud-finder 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65ca1119e7b7a29b14a47547161d99ce047ca0bf5f49325e7393c01bc7fc56a6
-  data.tar.gz: 54674df0b9f1409062d37c85f364323d6edd4e76fbbcecfa31cb3257902cdb87
+  metadata.gz: d5c4ae36f3971b4c2aa32bc157c76eea4223b401764e2f895f541d4532f5ed8d
+  data.tar.gz: '0180283bc3f6c389e7c4b68ce42819e8d5bd5ec08684031249b4deb7915e7b62'
 SHA512:
-  metadata.gz: 62f1e83fbe670e67b91d5640e120f19ab5a307f8cc887ea12bdf2103e80e6dd00f32fd4cc3415df195b4bb82a0ba3a6929f569957b011b00a2061121563c6ce6
-  data.tar.gz: 6f29ee2b1a9e575b49f3fb1978071059e1eb203b8a33ded65a973cd7924b8915e6d44a07e4b8ec9226cdb324d5bbdaa6b71ab266511d00314aaf4c7509cb42d7
+  metadata.gz: 9bc2be78efee09c43411250904494503d23b9080e70bbd962cc043dc92073fc94c2903eef4cbe8dd828cb35fd4a5ce70758a815c5ed110a8bfb7250dcf37fc32
+  data.tar.gz: 6a808490d99422741999eb3d559c813b1c7e7646a8195bb4d6cc87541fdf21d4420f914e345acb68522d79ee72510101f1f4fb96549d01080b4f105e0318f347

data/CHANGELOG.md

@@ -5,6 +5,13 @@ 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

data/lib/stud_finder/cli.rb

@@ -18,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'
@@ -74,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?
@@ -122,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)

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.6.0'
+  VERSION = '0.7.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stud-finder
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  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