stud-finder 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: faa8060a75346fc7a402adf203764c650d1596c2c6b3f4cb25571b3b21ecfa7a
-  data.tar.gz: 9c26eed3cb20c42d0155a730ba0ff70f9893a43493bf49d633aea4a0a2036a79
+  metadata.gz: 65ca1119e7b7a29b14a47547161d99ce047ca0bf5f49325e7393c01bc7fc56a6
+  data.tar.gz: 54674df0b9f1409062d37c85f364323d6edd4e76fbbcecfa31cb3257902cdb87
 SHA512:
-  metadata.gz: 863567f3e6dedd1808075bf9ae272cdb3f2e5b3b849b0eaa3b7b829a0db56873b757e6587d4fc82b6460fe6ab993407de24742fdde86d6bea6cb9809eb388ec0
-  data.tar.gz: a0a6d9b9fb0ad35bd88e22e26c24eb72957d22c46fd138e0e4c8b7da2bbcc885c5fb7f23bc58db547b826c754a478d72aa9b6cf0b3b04c81fa1801ef11fc903a
+  metadata.gz: 62f1e83fbe670e67b91d5640e120f19ab5a307f8cc887ea12bdf2103e80e6dd00f32fd4cc3415df195b4bb82a0ba3a6929f569957b011b00a2061121563c6ce6
+  data.tar.gz: 6f29ee2b1a9e575b49f3fb1978071059e1eb203b8a33ded65a973cd7924b8915e6d44a07e4b8ec9226cdb324d5bbdaa6b71ab266511d00314aaf4c7509cb42d7

data/CHANGELOG.md

@@ -5,7 +5,24 @@ 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.5.0] - Unreleased
+## [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
+
+- Auto-unshallow now emits a stderr progress line before fetching, so users aren't surprised by the silent clone mutation. `--no-auto-unshallow` still skips the whole attempt.
+
+### Fixed
+
+- Auto-unshallow no longer leaks the child `git fetch` process on timeout. `Open3.popen3` + explicit `TERM`/`KILL` reap replaces the prior `Open3.capture3` + `Timeout.timeout` pattern that unwound the parent stack while leaving the child orphaned.
+
+## [0.5.0] - 2026-07-12
 
 ### Changed
 
@@ -20,7 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `--no-auto-unshallow` flag: opt out of the automatic `git fetch --unshallow` on shallow clones. When set, Stud Finder behaves as before — shallow clone disables newness and emits only `shallow_clone_newness_disabled`.
 - `shallow_clone_unshallow_failed` warning code: fires when auto-unshallow was attempted but failed (network error, timeout, or non-zero exit). Appears alongside `shallow_clone_newness_disabled` so consumers can distinguish "unshallow was never tried" from "unshallow was tried and failed".
 
-## [0.4.0] - Unreleased
+## [0.4.0] - 2026-07-11
 
 ### Changed
 

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'
@@ -531,10 +532,14 @@ module StudFinder
     end
 
     def attempt_unshallow(files)
-      require 'timeout'
-      Timeout.timeout(45) do
-        _stdout, _stderr, status = Open3.capture3('git', 'fetch', '--unshallow', chdir: @repo_path)
-        raise 'unshallow failed' unless status.success?
+      progress('auto-unshallow: fetching full history to compute evidence (use --no-auto-unshallow to skip)')
+      Open3.popen3('git', '-C', @repo_path, 'fetch', '--unshallow') do |_stdin, _stdout, _stderr, wait_thread|
+        unless wait_thread.join(45)
+          Process.kill('TERM', wait_thread.pid)
+          Process.kill('KILL', wait_thread.pid) unless wait_thread.join(5)
+          raise 'unshallow timed out'
+        end
+        raise 'unshallow failed' unless wait_thread.value.success?
 
         Newness.new(repo_path: @repo_path, files: files, days: @options[:new_file_days],
                     min_commits: @options[:new_file_min_commits]).call
@@ -718,7 +723,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) }
       )
@@ -733,7 +738,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StudFinder
-  VERSION = '0.5.0'
+  VERSION = '0.6.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.0
+  version: 0.6.0
 platform: ruby
 authors:
 - bazfer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-12 00:00:00.000000000 Z
+date: 2026-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -171,6 +171,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