stud-finder 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e14a94cc20570cd7eb6b592b62b0cbf7268d8be02f546a3f1f343146f6b3c6f
-  data.tar.gz: a49e0535ae4dc3f97958e2758773a04ceb7b486e7f7582a3048562dafbcfeaf4
+  metadata.gz: 65ca1119e7b7a29b14a47547161d99ce047ca0bf5f49325e7393c01bc7fc56a6
+  data.tar.gz: 54674df0b9f1409062d37c85f364323d6edd4e76fbbcecfa31cb3257902cdb87
 SHA512:
-  metadata.gz: d036d77feaec9b455cf6abe8d5f2578f25a91f7948bb91d7a97150d94b007c38fd4daa4b4ea0bce21c41168b31f3f70cb03779657af4c156a7c4225d17fa6020
-  data.tar.gz: ff082727ae14f9dbd27a0a11528a4f3223df541218ab58f4ac7420adae66b405eef05ae541c20da3ad3a97cd738c2104bc5b916ad1846ac6066f361576e2f3a2
+  metadata.gz: 62f1e83fbe670e67b91d5640e120f19ab5a307f8cc887ea12bdf2103e80e6dd00f32fd4cc3415df195b4bb82a0ba3a6929f569957b011b00a2061121563c6ce6
+  data.tar.gz: 6f29ee2b1a9e575b49f3fb1978071059e1eb203b8a33ded65a973cd7924b8915e6d44a07e4b8ec9226cdb324d5bbdaa6b71ab266511d00314aaf4c7509cb42d7

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.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'
@@ -722,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) }
       )
@@ -737,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.1'
+  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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stud-finder
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - bazfer
@@ -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