churn_vs_complexity 1.5.2 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 843cae8dad7f09344cbea477eb73ae3d9d57945df8a5955d93d6dfc820b5a8e1
-  data.tar.gz: 5066b98af73acde0f18b233fd12efe6858bb9977c4a9d553970c6ad859db98a9
+  metadata.gz: 7e7255f75c51831cad9a608e92dad4757febaa1572e88de868b41160bcd772c5
+  data.tar.gz: a22de6d66cf13646d53151b24c437b4fe3eff1bd4b1ec806ea5288bf7dc47cde
 SHA512:
-  metadata.gz: 7af6d2c460fd9bb2cb78751d8a7f5cdd3ada48e9026e61ccbd3ef74a22c738bcfea4185984ffea2476a5d4b726f902c881edabf2baefa211884bfb129b59f80c
-  data.tar.gz: c3cf5e4dfd7bea34298fac9d7e2db1b7ffe58ad16acab25e9217dae0f84b43e2da7d89f147027f1ebb3fd52115538aba81a1f05bca5a0f7e13f0ad5d3a7b9aef
+  metadata.gz: f405fc54741656b79ab93f5d6dd42864cdf0087df8ec3bb70d0f9409d88ef4eca3667953ac6e86fa6119ddec3f8191553fdb334d49472d149d986cf7265d70f2
+  data.tar.gz: f39face62b2f4a97235b265b167ffead22c682f4963b535365023e26bb6ae4448fa9ee425c0cfc02b5e76195ae902a7e315b9f57629ecdb33f4a7c0488a95376

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [1.6.0] - 2026-02-19
+
+### Added
+- Python support for complexity calculation
+- Go support for complexity calculation (via gocognit)
+- New `--triage` mode: per-file risk assessment based on churn and complexity
+- New `--hotspots` mode: ranked list of files by risk score
+- New `--gate` mode: pass/fail quality gate with `--max-gamma` threshold (exit 0/1)
+- New `--focus start|end` mode: capture complexity snapshots before and after coding sessions
+- New `--diff REF` mode: compare codebase health between a reference commit and HEAD
+- New `--json` output format for all modes
+- New `--markdown` output format
+- Risk classifier and risk annotator modules
+- Gamma score module
+
+### Fixed
+- Improved CLI help text with grouped sections (Languages, Modes, Output formats, Modifiers)
+
 ## [1.5.2] - 2024-10-21
 
 - Fixed bug where delta mode validations would fail when the commit was a non-sha value.

data/CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`churn_vs_complexity` is a Ruby gem that analyzes code quality by correlating file churn (how often files change) with complexity scores. It supports Ruby (via Flog), JavaScript/TypeScript (via ESLint), and Java (via PMD). Requires Ruby >= 3.3.
+
+## Commands
+
+```bash
+# Run tests (TLDR framework)
+bundle exec rake          # default task runs tldr
+bundle exec tldr          # direct
+
+# Run a single test file
+bundle exec tldr test/churn_vs_complexity/engine_test.rb
+
+# Run a single test by name
+bundle exec tldr --name test_something test/path/to_test.rb
+
+# Lint
+bundle exec rubocop
+bundle exec rubocop -a    # auto-fix safe offenses
+
+# Build/install gem
+bundle exec rake build
+bundle exec rake install
+```
+
+## Architecture
+
+Three operating modes, each with its own Config/Checker/Serializer pipeline:
+
+- **Normal** (`Normal::Config` → `Engine` → `ConcurrentCalculator`): Analyzes a folder, computing churn + complexity per file. Outputs CSV, HTML graph, or text summary.
+- **Timetravel** (`Timetravel::Config` → `Traveller`): Samples quality scores across historical commits at N-day intervals. Uses forked processes with git worktrees for isolation.
+- **Delta** (`Delta::Config` → `MultiChecker` → `Checker`): Analyzes complexity of files changed in specific commits. Uses threads with git worktrees.
+
+Entry point: `CLI::run!` → `CLI::Parser` → `CLI::Main.run!` → mode-specific Config → checker.
+
+### Key interfaces
+
+- **Complexity calculators**: `folder_based?`, `calculate(folder:)` or `calculate(files:)`
+- **Churn calculators**: `calculate(folder:, file:, since:)`, `date_of_latest_commit(folder:)`
+- **Serializers**: `serialize(result)`
+- **File selectors**: `select_files(folder)` → `{ included: [...], explicitly_excluded: [...] }`
+
+### Concurrency model
+
+- Normal: threads (nprocessors) for per-file churn calculation
+- Timetravel: forked child processes with IO.pipe for IPC
+- Delta: threads (2x nprocessors) for concurrent commit analysis
+
+## Code Style
+
+RuboCop config (`.rubocop.yml`):
+- Max line length: 120
+- Trailing commas enforced on multiline (arrays, hashes, arguments)
+- `NewCops: enable`
+- No class/module documentation required (`Style::Documentation` disabled)

data/lib/churn_vs_complexity/churn.rb

@@ -17,7 +17,7 @@ module ChurnVsComplexity
         def calculate(folder:, file:, since:)
           git_dir = File.join(folder, '.git')
           earliest_date = [date_of_first_commit(folder:), since].max
-          formatted_date = earliest_date.strftime('%Y-%m-%d')
+          formatted_date = earliest_date.strftime('%Y-%m-%dT00:00:00')
           cmd = %(git --git-dir #{git_dir} --work-tree #{folder} log --format="%H" --follow --since="#{formatted_date}" -- #{file} | wc -l)
           `(#{cmd}) 2>/dev/null`.to_i
         end

data/lib/churn_vs_complexity/cli/main.rb

@@ -26,16 +26,24 @@ module ChurnVsComplexity
           raise ValidationError, 'No options selected. Use --help for usage information.' if options.empty?
           raise ValidationError, 'No language selected. Use --help for usage information.' if options[:language].nil?
 
+          return if MODES_WITHOUT_SERIALIZER.include?(options[:mode])
           return unless options[:serializer].nil?
 
           raise ValidationError, 'No serializer selected. Use --help for usage information.'
         end
 
+        MODES_WITHOUT_SERIALIZER = %i[triage hotspots gate focus diff].freeze
+
         def config(options)
           config_class =
             case options[:mode]
             when :timetravel then Timetravel::Config
             when :delta then Delta::Config
+            when :triage then Triage::Config
+            when :hotspots then Hotspots::Config
+            when :gate then Gate::Config
+            when :focus then Focus::Config
+            when :diff then Diff::Config
             else Normal::Config
             end
           config_class.new(**options)

data/lib/churn_vs_complexity/cli/parser.rb

@@ -8,7 +8,10 @@ module ChurnVsComplexity
       def self.create
         options = { excluded: [] }
         parser = OptionParser.new do |opts|
-          opts.banner = 'Usage: churn_vs_complexity [options] folder'
+          opts.banner = 'Usage: churn_vs_complexity [options] folder|file...'
+
+          opts.separator ''
+          opts.separator 'Languages:'
 
           opts.on('--java', 'Check complexity of java classes') do
             options[:language] = :java
@@ -23,6 +26,57 @@ module ChurnVsComplexity
             options[:language] = :javascript
           end
 
+          opts.on('--python', 'Check complexity of python files') do
+            options[:language] = :python
+          end
+
+          opts.on('--go', 'Check complexity of go files') do
+            options[:language] = :go
+          end
+
+          opts.separator ''
+          opts.separator 'Modes (mutually exclusive):'
+
+          opts.on('--timetravel N',
+                  'Calculate summary for all commits at intervals of N days throughout project history or from the date specified with --since',) do |value|
+            options[:mode] = :timetravel
+            options[:jump_days] = value.to_i
+          end
+
+          opts.on('--triage',
+                  'Assess risk of files based on churn and complexity. Accepts file paths or a folder as arguments.',) do
+            options[:mode] = :triage
+          end
+
+          opts.on('--hotspots', 'Generate ranked list of files by risk') do
+            options[:mode] = :hotspots
+          end
+
+          opts.on('--gate',
+                  'Pass/fail quality check against gamma threshold (exits 0 on pass, 1 on fail)',) do
+            options[:mode] = :gate
+          end
+
+          opts.on('--focus start|end',
+                  'Capture complexity snapshot before (start) and after (end) a coding session',) do |value|
+            options[:mode] = :focus
+            options[:subcommand] = value.to_sym
+          end
+
+          opts.on('--diff REF', 'Compare codebase health between REF and HEAD') do |value|
+            options[:mode] = :diff
+            options[:reference] = value
+          end
+
+          opts.on('--delta SHA',
+                  'Identify changes between the specified commit (SHA) and the previous commit and annotate changed files with complexity score. SHA can be a full or short commit hash, or the value HEAD. Can be used multiple times to specify multiple commits.',) do |value|
+            options[:mode] = :delta
+            (options[:commits] ||= []) << value
+          end
+
+          opts.separator ''
+          opts.separator 'Output formats:'
+
           opts.on('--csv', 'Format output as CSV') do
             options[:serializer] = :csv
           end
@@ -35,6 +89,17 @@ module ChurnVsComplexity
             options[:serializer] = :summary
           end
 
+          opts.on('--json', 'Format output as JSON') do
+            options[:serializer] = :json
+          end
+
+          opts.on('--markdown', 'Format output as Markdown') do
+            options[:serializer] = :markdown
+          end
+
+          opts.separator ''
+          opts.separator 'Modifiers:'
+
           opts.on('--excluded PATTERN',
                   'Exclude file paths including this string. Can be used multiple times.',) do |value|
             options[:excluded] << value
@@ -57,16 +122,8 @@ module ChurnVsComplexity
             options[:relative_period] = :year
           end
 
-          opts.on('--timetravel N',
-                  'Calculate summary for all commits at intervals of N days throughout project history or from the date specified with --since',) do |value|
-            options[:mode] = :timetravel
-            options[:jump_days] = value.to_i
-          end
-
-          opts.on('--delta SHA',
-                  'Identify changes between the specified commit (SHA) and the previous commit and annotate changed files with complexity score. SHA can be a full or short commit hash, or the value HEAD. Can be used multiple times to specify multiple commits.',) do |value|
-            options[:mode] = :delta
-            (options[:commits] ||= []) << value
+          opts.on('--max-gamma N', Float, 'Maximum gamma score threshold for gate mode (default: 25)') do |value|
+            options[:max_gamma] = value
           end
 
           opts.on('--dry-run', 'Echo the chosen options from the CLI') do

data/lib/churn_vs_complexity/cli.rb

@@ -12,7 +12,9 @@ module ChurnVsComplexity
         # First argument that is not an option is the folder
         folder = ARGV.first
 
-        puts Main.run!(options, folder)
+        result = Main.run!(options, folder)
+        puts result
+        exit 1 if result.respond_to?(:passed?) && !result.passed?
       end
     end
   end

data/lib/churn_vs_complexity/complexity/go_calculator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module ChurnVsComplexity
+  module Complexity
+    module GoCalculator
+      class << self
+        attr_writer :command_runner
+
+        def folder_based? = false
+
+        def calculate(files:)
+          json_output = run_gocognit(files)
+          parse_gocognit_output(json_output, files:)
+        end
+
+        def parse_gocognit_output(json_output, files:)
+          stats = JSON.parse(json_output) || []
+          scores = stats.group_by { |s| s.dig('Pos', 'Filename') }
+                        .transform_values { |funcs| funcs.sum { |f| f['Complexity'] } }
+          files.to_h { |file| [file, scores[file] || 0] }
+        end
+
+        def check_dependencies!
+          command_runner.call('gocognit --help 2>&1')
+        rescue Errno::ENOENT
+          raise Error, 'Needs gocognit installed (go install github.com/uudashr/gocognit/cmd/gocognit@latest)'
+        end
+
+        private
+
+        def command_runner
+          @command_runner || Open3.method(:capture2)
+        end
+
+        def run_gocognit(files)
+          files_arg = files.map { |f| "'#{f}'" }.join(' ')
+          stdout, status = command_runner.call("gocognit -json #{files_arg}")
+          raise Error, "gocognit failed (exit #{status.exitstatus}). Is it installed?" unless status.success?
+
+          stdout
+        end
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/complexity/python_calculator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module ChurnVsComplexity
+  module Complexity
+    module PythonCalculator
+      class << self
+        attr_writer :command_runner
+
+        def folder_based? = false
+
+        def calculate(files:)
+          json_output = run_radon(files)
+          parse_radon_output(json_output, files:)
+        end
+
+        def parse_radon_output(json_output, files:)
+          data = JSON.parse(json_output)
+          files.to_h do |file|
+            blocks = data[file] || []
+            total = blocks.sum { |b| b['complexity'] }
+            [file, total]
+          end
+        end
+
+        def check_dependencies!
+          command_runner.call('radon --version 2>&1')
+        rescue Errno::ENOENT
+          raise Error, 'Needs radon installed (pip install radon)'
+        end
+
+        private
+
+        def command_runner
+          @command_runner || Open3.method(:capture2)
+        end
+
+        def run_radon(files)
+          files_arg = files.map { |f| "'#{f}'" }.join(' ')
+          stdout, status = command_runner.call("radon cc #{files_arg} -j")
+          raise Error, "radon failed (exit #{status.exitstatus}). Is it installed?" unless status.success?
+
+          stdout
+        end
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/complexity.rb

@@ -3,6 +3,8 @@
 require_relative 'complexity/pmd'
 require_relative 'complexity/flog_calculator'
 require_relative 'complexity/eslint_calculator'
+require_relative 'complexity/python_calculator'
+require_relative 'complexity/go_calculator'
 
 module ChurnVsComplexity
   module Complexity

data/lib/churn_vs_complexity/complexity_validator.rb

@@ -8,6 +8,10 @@ module ChurnVsComplexity
         Complexity::PMD.check_dependencies!
       when :javascript
         Complexity::ESLintCalculator.check_dependencies!
+      when :python
+        Complexity::PythonCalculator.check_dependencies!
+      when :go
+        Complexity::GoCalculator.check_dependencies!
       end
     end
   end

data/lib/churn_vs_complexity/delta/config.rb

@@ -38,10 +38,10 @@ module ChurnVsComplexity
       end
 
       def validate_commit!(commit)
-        return if commit == 'HEAD' || commit.match?(/\A[0-9a-f]{40}\z/i) || commit.match?(/\A[0-9a-f]{8}\z/i)
+        return if commit == 'HEAD' || commit.match?(/\A[0-9a-f]{40}\z/i) || commit.match?(/\A[0-9a-f]{7,12}\z/i)
 
         raise ValidationError,
-              "Invalid commit: #{commit}. It must be a valid 40-character SHA-1 hash or an 8-character shortened form."
+              "Invalid commit: #{commit}. It must be a valid 40-character SHA-1 hash or a 7-12 character shortened form."
       end
 
       def serializer = Serializer.resolve(@serializer)

data/lib/churn_vs_complexity/delta.rb

@@ -34,6 +34,10 @@ module ChurnVsComplexity
           FileSelector::Ruby.predefined(included:, excluded:)
         when :javascript
           FileSelector::JavaScript.predefined(included:, excluded:)
+        when :python
+          FileSelector::Python.predefined(included:, excluded:)
+        when :go
+          FileSelector::Go.predefined(included:, excluded:)
         end
       end
 
@@ -45,6 +49,10 @@ module ChurnVsComplexity
           Complexity::FlogCalculator
         when :javascript
           Complexity::ESLintCalculator
+        when :python
+          Complexity::PythonCalculator
+        when :go
+          Complexity::GoCalculator
         end
       end
     end

data/lib/churn_vs_complexity/diff/checker.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module Diff
+    class Checker
+      def initialize(engine_builder:, serializer:, reference:)
+        @engine_builder = engine_builder
+        @serializer = serializer
+        @reference = reference
+      end
+
+      def check(folder:)
+        worktree = setup_worktree(folder:)
+
+        begin
+          before_result = @engine_builder.call.check(folder: worktree.folder)
+          after_result = @engine_builder.call.check(folder:)
+          serialize_results(before_result, after_result)
+        ensure
+          cleanup_worktree(worktree)
+        end
+      end
+
+      private
+
+      def setup_worktree(folder:)
+        git_strategy = GitStrategy.new(folder:)
+        worktree_number = "diff_#{Thread.current.object_id}"
+        worktree = Timetravel::Worktree.new(root_folder: folder, git_strategy:, number: worktree_number)
+        worktree.prepare
+        worktree.checkout(@reference)
+        worktree
+      end
+
+      def cleanup_worktree(worktree)
+        worktree.remove
+      rescue StandardError
+        FileUtils.rm_rf(worktree.folder) if worktree&.folder
+      end
+
+      def serialize_results(before_result, after_result)
+        @serializer.serialize(reference: @reference, before: before_result, after: after_result)
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/diff/config.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module Diff
+    class Config
+      def initialize(
+        language:,
+        reference:,
+        serializer: :json,
+        since: nil,
+        excluded: [],
+        complexity_validator: ComplexityValidator,
+        since_validator: Normal::SinceValidator,
+        **options
+      )
+        @language = language
+        @reference = reference
+        @serializer = serializer
+        @since = since
+        @excluded = excluded
+        @complexity_validator = complexity_validator
+        @since_validator = since_validator
+        @options = options
+      end
+
+      def validate!
+        LanguageValidator.validate!(@language)
+        @since_validator.validate!(since: @since, relative_period: nil)
+        @complexity_validator.validate!(@language)
+      end
+
+      def checker
+        Checker.new(
+          engine_builder: method(:build_engine),
+          serializer: diff_serializer,
+          reference: @reference,
+        )
+      end
+
+      private
+
+      def build_engine
+        Normal::Config.new(language: @language, serializer: :none, since: @since, excluded: @excluded).checker
+      end
+
+      def diff_serializer
+        case @serializer
+        when :json then Serializer::Json
+        end
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/diff/serializer.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ChurnVsComplexity
+  module Diff
+    module Serializer
+      module Json
+        def self.serialize(reference:, before:, after:)
+          before_gammas = gammas_from(before)
+          after_gammas = gammas_from(after)
+          degraded, improved, unchanged_count = classify_changes(before_gammas, after_gammas)
+
+          JSON.generate(
+            reference:, current: 'HEAD',
+            overall: overall_summary(before_gammas.values, after_gammas.values),
+            degraded:, improved:, unchanged: unchanged_count,
+          )
+        end
+
+        def self.gammas_from(result)
+          result[:values_by_file].transform_values { |v| GammaScore.calculate(v[0], v[1]).round(2) }
+        end
+
+        def self.overall_summary(before_scores, after_scores)
+          before_mean = mean(before_scores)
+          after_mean = mean(after_scores)
+          { mean_gamma_before: before_mean, mean_gamma_after: after_mean,
+            direction: direction(before_mean, after_mean), }
+        end
+
+        def self.classify_changes(before_gammas, after_gammas)
+          all_files = (before_gammas.keys + after_gammas.keys).uniq
+          grouped = all_files.group_by { |f| classify_file(before_gammas[f], after_gammas[f]) }
+
+          [
+            entries_for(grouped[:degraded], before_gammas, after_gammas),
+            entries_for(grouped[:improved], before_gammas, after_gammas),
+            (grouped[:unchanged] || []).size,
+          ]
+        end
+
+        def self.entries_for(files, before_gammas, after_gammas)
+          (files || []).map { |f| file_entry(f, before_gammas[f], after_gammas[f]) }
+        end
+
+        def self.classify_file(old_g, new_g)
+          return :unchanged if old_g.nil? || new_g.nil? || (old_g - new_g).abs < 0.01
+          return :degraded if new_g > old_g
+
+          :improved
+        end
+
+        def self.file_entry(file, old_g, new_g)
+          pct = old_g.positive? ? (((new_g - old_g) / old_g) * 100).round(0) : 0
+          sign = pct.positive? ? '+' : ''
+          { file:, gamma_before: old_g, gamma_after: new_g, change: "#{sign}#{pct}%" }
+        end
+
+        def self.mean(scores)
+          return 0.0 if scores.empty?
+
+          (scores.sum.to_f / scores.size).round(2)
+        end
+
+        def self.direction(before, after)
+          diff = after - before
+          return 'unchanged' if diff.abs < 0.5
+
+          diff.positive? ? 'degraded' : 'improved'
+        end
+
+        private_class_method :gammas_from, :overall_summary, :classify_changes,
+                             :classify_file, :entries_for, :file_entry, :mean, :direction
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/diff.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'diff/config'
+require_relative 'diff/checker'
+require_relative 'diff/serializer'
+
+module ChurnVsComplexity
+  module Diff
+  end
+end

data/lib/churn_vs_complexity/file_selector.rb

@@ -10,6 +10,10 @@ module ChurnVsComplexity
         ['.rb']
       when :javascript
         ['.js', '.jsx', '.ts', '.tsx']
+      when :python
+        ['.py']
+      when :go
+        ['.go']
       else
         raise Error, "Unsupported language: #{language}"
       end
@@ -104,5 +108,27 @@ module ChurnVsComplexity
                        convert_to_absolute_path: true,)
       end
     end
+
+    module Python
+      DEFAULT_EXCLUDES = %w[venv .venv env .env __pycache__ .tox site-packages].freeze
+
+      def self.excluding(excluded)
+        Excluding.new(FileSelector.extensions(:python), DEFAULT_EXCLUDES + excluded)
+      end
+
+      def self.predefined(included:, excluded:)
+        Predefined.new(included:, extensions: FileSelector.extensions(:python), excluded: DEFAULT_EXCLUDES + excluded)
+      end
+    end
+
+    module Go
+      def self.excluding(excluded)
+        Excluding.new(FileSelector.extensions(:go), excluded)
+      end
+
+      def self.predefined(included:, excluded:)
+        Predefined.new(included:, extensions: FileSelector.extensions(:go), excluded:)
+      end
+    end
   end
 end