churn_vs_complexity 1.5.2 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 843cae8dad7f09344cbea477eb73ae3d9d57945df8a5955d93d6dfc820b5a8e1
-  data.tar.gz: 5066b98af73acde0f18b233fd12efe6858bb9977c4a9d553970c6ad859db98a9
+  metadata.gz: 6dfa844a5bcd2fe116001652410d39f802c64623be5ec588afcc6ed331b9aac9
+  data.tar.gz: 42c5d56c7b4c6640bd4040f7f5d8b35ea6acac0aae9285be4c6cb1aaf860f0fb
 SHA512:
-  metadata.gz: 7af6d2c460fd9bb2cb78751d8a7f5cdd3ada48e9026e61ccbd3ef74a22c738bcfea4185984ffea2476a5d4b726f902c881edabf2baefa211884bfb129b59f80c
-  data.tar.gz: c3cf5e4dfd7bea34298fac9d7e2db1b7ffe58ad16acab25e9217dae0f84b43e2da7d89f147027f1ebb3fd52115538aba81a1f05bca5a0f7e13f0ad5d3a7b9aef
+  metadata.gz: 0ad833af0897a784aa0499d277884e011e9be71142d343c441ef0a12b1185c27f18c09b0b7780a3f8493e3ef0399faff5f97b252f51fb4713f3dd98d11b666a7
+  data.tar.gz: 19cf09a9777aa06a4772fae21fee5a4043ba034efde9d2af13618461b20a602270879438c4aa626463c3ea14054bf1dc8a7b9a25cde09c9636439d9d567a30f3

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [1.6.1] - 2026-02-19
+
+### Changed
+- Updated gemspec summary and description to reflect all supported languages and modes
+- Updated README with current usage, all languages (Ruby, JS/TS, Java, Python, Go), all modes, and new examples
+- Added external dependency documentation for Python (radon) and Go (gocyclo)
+
+## [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/README.md

@@ -2,11 +2,11 @@
 
 # ChurnVsComplexity
 
-A tool to visualise code complexity in a project and help direct refactoring efforts.
+Correlates file churn (how often files change) with complexity scores to identify refactoring hotspots and track codebase health over time. Supports Ruby, JavaScript/TypeScript, Java, Python, and Go.
 
-Inspired by [Michael Feathers' article "Getting Empirical about Refactoring"](https://www.agileconnection.com/article/getting-empirical-about-refactoring) and the gem [turbulence](https://rubygems.org/gems/turbulence) by Chad Fowler and others.
+Modes include hotspots ranking, triage assessment, CI quality gate, diff comparison, focus sessions, and timetravel history.
 
-This gem currently supports analysis of Java, Ruby, JavaScript, and TypeScript repositories, but it can easily be extended.
+Inspired by [Michael Feathers' article "Getting Empirical about Refactoring"](https://www.agileconnection.com/article/getting-empirical-about-refactoring).
 
 ## Installation
 
@@ -26,30 +26,52 @@ Or install it yourself as:
 
 This gem depends on git for churn analysis.
 
-Complexity analysis for Java relies on [PMD](https://pmd.github.io). In order to use the `--java` flag, you must first install PMD manually, and the gem assumes it is available on the search path as `pmd`. On macOS, for example, you can install it using homebrew with `brew install pmd`.
+External tool dependencies per language:
 
-Complexity analysis for JavaScript and TypeScript relies on [ESLint](https://eslint.org). In order to use the `--js`, `--ts`, `--javascript`, or `--typescript` flag, you must have Node.js installed.
+- **Ruby**: None (uses [Flog](https://rubygems.org/gems/flog), bundled as a gem dependency).
+- **Java**: Requires [PMD](https://pmd.github.io) on the search path as `pmd`. On macOS: `brew install pmd`.
+- **JavaScript/TypeScript**: Requires [Node.js](https://nodejs.org) (uses ESLint internally).
+- **Python**: Requires [Radon](https://radon.readthedocs.io) on the search path as `radon`. Install with `pip install radon`.
+- **Go**: Requires [gocyclo](https://github.com/fzipp/gocyclo) on the search path. Install with `go install github.com/fzipp/gocyclo/cmd/gocyclo@latest`.
 
 ## Usage
 
-Execute the `churn_vs_complexity` with the applicable arguments. Output in the requested format will be directed to stdout.
+Execute `churn_vs_complexity` with the applicable arguments. Output in the requested format will be directed to stdout.
 
 ```
-Usage: churn_vs_complexity [options] folder
+Usage: churn_vs_complexity [options] folder|file...
+
+Languages:
         --java                       Check complexity of java classes
         --ruby                       Check complexity of ruby files
         --js, --ts, --javascript, --typescript
                                      Check complexity of javascript and typescript files
+        --python                     Check complexity of python files
+        --go                         Check complexity of go files
+
+Modes (mutually exclusive):
+        --timetravel N               Calculate summary for all commits at intervals of N days throughout project history or from the date specified with --since
+        --triage                     Assess risk of files based on churn and complexity. Accepts file paths or a folder as arguments.
+        --hotspots                   Generate ranked list of files by risk
+        --gate                       Pass/fail quality check against gamma threshold (exits 0 on pass, 1 on fail)
+        --focus start|end            Capture complexity snapshot before (start) and after (end) a coding session
+        --diff REF                   Compare codebase health between REF and HEAD
+        --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.
+
+Output formats:
         --csv                        Format output as CSV
         --graph                      Format output as HTML page with Churn vs Complexity graph
         --summary                    Output summary statistics (mean and median) for churn and complexity
+        --json                       Format output as JSON
+        --markdown                   Format output as Markdown
+
+Modifiers:
         --excluded PATTERN           Exclude file paths including this string. Can be used multiple times.
         --since YYYY-MM-DD           Normal mode: Calculate churn after this date. Timetravel mode: calculate summaries from this date
     -m, --month                      Calculate churn for the month leading up to the most recent commit
     -q, --quarter                    Calculate churn for the quarter leading up to the most recent commit
     -y, --year                       Calculate churn for the year leading up to the most recent commit
-        --timetravel N               Calculate summary for all commits at intervals of N days throughout project history or from the date specified with --since
-        --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.
+        --max-gamma N                Maximum gamma score threshold for gate mode (default: 25)
         --dry-run                    Echo the chosen options from the CLI
     -h, --help                       Display help
         --version                    Display version
@@ -67,15 +89,39 @@ Summaries in normal mode include a gamma score, which is an unnormalised harmoni
 Summary points in timetravel mode instead include an alpha score, which is the same harmonic mean of churn and complexity, where churn and complexity values are normalised to a 0-1 range to avoid either churn or complexity dominating the score. The summary points also include a beta score, which is the geometric mean of the normalised churn and complexity values.
 ## Examples
 
-`churn_vs_complexity --ruby --csv my_ruby_project > ~/Desktop/ruby-demo.csv`
+```bash
+# CSV churn vs complexity report for a Ruby project
+churn_vs_complexity --ruby --csv my_ruby_project > ~/Desktop/ruby-demo.csv
+
+# Interactive HTML graph for a Java project (excluding generated code)
+churn_vs_complexity --java --graph --excluded generated-sources --since 2023-01-01 my_java_project > ~/Desktop/java-demo.html
+
+# Monthly summary for a Python project
+churn_vs_complexity --python --summary -m my_python_project
+
+# Top refactoring hotspots ranked by risk
+churn_vs_complexity --ruby --hotspots -q my_ruby_project
 
-`churn_vs_complexity --java --graph --exclude generated-sources --exclude generated-test-sources --since 2023-01-01 my_java_project > ~/Desktop/java-demo.html`
+# CI quality gate (exits 1 if gamma exceeds threshold)
+churn_vs_complexity --ruby --gate --max-gamma 30 my_ruby_project
 
-`churn_vs_complexity --ruby --summary -m my_ruby_project >> ~/Desktop/monthly-report.txt`
+# Triage specific files before a code review
+churn_vs_complexity --go --triage src/server.go src/handler.go
 
-`churn_vs_complexity --java -m --since 2019-03-01 --timetravel 30 --graph my_java_project > ~/Desktop/timetravel-after-1st-march-2019.html`
+# Compare codebase health between a branch and HEAD
+churn_vs_complexity --ruby --diff origin/main --summary my_ruby_project
 
-`churn_vs_complexity --delta 1496402e81e68e86c5ac240559099fbe581a9a2g --delta 2845296758861773778d70d96328a5f2a1a9e933  --js --summary my_javascript_project > ~/Desktop/interesting-commits.txt`
+# Focus session: snapshot before and after a coding session
+churn_vs_complexity --ruby --focus start my_ruby_project
+# ... do some coding ...
+churn_vs_complexity --ruby --focus end my_ruby_project
+
+# Timetravel: track quality over time at 30-day intervals
+churn_vs_complexity --java -m --since 2019-03-01 --timetravel 30 --graph my_java_project > ~/Desktop/timetravel.html
+
+# Analyse complexity of specific commits
+churn_vs_complexity --js --delta HEAD --summary my_js_project
+```
 
 ## Development
 

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