churn_vs_complexity 1.4.0 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7484ff3a1c015738808226a78087017f6b7aff5ce42d15879023f32df5648717
-  data.tar.gz: ad3bdeff5ba32e9d7f414b45173d8928b1c463313557202b96aaf5fdcf059109
+  metadata.gz: 843cae8dad7f09344cbea477eb73ae3d9d57945df8a5955d93d6dfc820b5a8e1
+  data.tar.gz: 5066b98af73acde0f18b233fd12efe6858bb9977c4a9d553970c6ad859db98a9
 SHA512:
-  metadata.gz: a56e26296acfff22e755c414cab9ee36923e4ccd7181d67691f55feb8f99b5aa738f5d2b7645006f25c632efa346fb535d7fe04923443dedf607772ce1a21323
-  data.tar.gz: f406ee696facf7708e792b67ed8b463f1554365b3939deb4bde40c9fab88dfe891997f611727559a283103c5b7234f71d78d5fe108731628cb3fd8a782a73ce5
+  metadata.gz: 7af6d2c460fd9bb2cb78751d8a7f5cdd3ada48e9026e61ccbd3ef74a22c738bcfea4185984ffea2476a5d4b726f902c881edabf2baefa211884bfb129b59f80c
+  data.tar.gz: c3cf5e4dfd7bea34298fac9d7e2db1b7ffe58ad16acab25e9217dae0f84b43e2da7d89f147027f1ebb3fd52115538aba81a1f05bca5a0f7e13f0ad5d3a7b9aef

data/.rubocop.yml

@@ -9,6 +9,9 @@ Layout/LineLength:
 Style/Documentation:
   Enabled: false
 
+Style/ModuleFunction:
+  Enabled: false
+
 Style/TrailingCommaInArrayLiteral:
   Enabled: true
   EnforcedStyleForMultiline: consistent_comma

data/CHANGELOG.md

@@ -1,25 +1,40 @@
-## [1.0.0] - 2024-06-07
+## [1.5.2] - 2024-10-21
 
-- Initial release
+- Fixed bug where delta mode validations would fail when the commit was a non-sha value.
+- Allow HEAD as specified commit in delta mode
 
-## [1.1.0] - 2024-09-20
+## [1.5.1] - 2024-10-15
 
-- Introduce `--summary` flag to output summary statistics for churn and complexity
-- Introduce `--month`, `--quarter`, and `--year` short-hand flags to calculate churn for different time periods relative to the most recent commit
+- Fix bug where worktree checkout silently failed
 
-## [1.2.0] - 2024-09-20
 
-- Fix bug in CLI where new flags and `--since` would not be recognized
-- Improve selection of observations included in the output
-- Fixed calculation of churn that would never be zero
+## [1.5.0] - 2024-10-14
+
+- Added delta mode to annotate changes in individual commits with complexity
+- Moving PMD cache to the OS temp directory
+
+## [1.4.0] - 2024-10-10
+
+- Added timetravel mode to visualise code quality over time
+- Added alpha, beta, and gamma scores to summaries
+- Fixed broken Ruby complexity calculation
 
 ## [1.3.0] - 2024-09-26
 
-- Add support for javascript and typescript complexity calculation using eslint
+- Added support for javascript and typescript complexity calculation using eslint
+
+## [1.2.0] - 2024-09-20
+
+- Fixed bug in CLI where new flags and `--since` would not be recognized
+- Improved selection of observations included in the output
+- Fixed calculation of churn that would never be zero
 - Fixed behavior when --since or short-hand flags were not provided
 
-## [1.4.0] - 2024-10-10
+## [1.1.0] - 2024-09-20
 
-- Add timetravel mode to visualise code quality over time
-- Add alpha, beta, and gamma scores to summaries
-- Fixed broken Ruby complexity calculation
+- Introduced `--summary` flag to output summary statistics for churn and complexity
+- Introduced `--month`, `--quarter`, and `--year` short-hand flags to calculate churn for different time periods relative to the most recent commit
+
+## [1.0.0] - 2024-06-07
+
+- Initial release

data/README.md

@@ -1,3 +1,5 @@
+[![Gem Version](https://badge.fury.io/rb/churn_vs_complexity.svg)](https://badge.fury.io/rb/churn_vs_complexity)
+
 # ChurnVsComplexity
 
 A tool to visualise code complexity in a project and help direct refactoring efforts.
@@ -22,9 +24,11 @@ Or install it yourself as:
 
     $ gem install churn_vs_complexity
 
-This gem depends on git for churn analysis and [PMD](https://pmd.github.io) for complexity analysis of JVM based languages.
+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`.
 
-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`.
+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.
 
 ## Usage
 
@@ -45,10 +49,10 @@ Usage: churn_vs_complexity [options] folder
     -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.
         --dry-run                    Echo the chosen options from the CLI
     -h, --help                       Display help
-
-
+        --version                    Display version
 ```
 
 Note that when using the `--timetravel` mode, the semantics of some flags are subtly different from normal mode:
@@ -71,6 +75,8 @@ Summary points in timetravel mode instead include an alpha score, which is the s
 
 `churn_vs_complexity --java -m --since 2019-03-01 --timetravel 30 --graph my_java_project > ~/Desktop/timetravel-after-1st-march-2019.html`
 
+`churn_vs_complexity --delta 1496402e81e68e86c5ac240559099fbe581a9a2g --delta 2845296758861773778d70d96328a5f2a1a9e933  --js --summary my_javascript_project > ~/Desktop/interesting-commits.txt`
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/churn_vs_complexity/churn.rb

@@ -4,6 +4,14 @@ require 'git'
 
 module ChurnVsComplexity
   module Churn
+    module Disabled
+      def self.calculate(*)
+        raise Error, 'Churn is disabled'
+      end
+
+      def self.date_of_latest_commit(*) = :disabled
+    end
+
     module GitCalculator
       class << self
         def calculate(folder:, file:, since:)
@@ -11,7 +19,7 @@ module ChurnVsComplexity
           earliest_date = [date_of_first_commit(folder:), since].max
           formatted_date = earliest_date.strftime('%Y-%m-%d')
           cmd = %(git --git-dir #{git_dir} --work-tree #{folder} log --format="%H" --follow --since="#{formatted_date}" -- #{file} | wc -l)
-          `#{cmd}`.to_i
+          `(#{cmd}) 2>/dev/null`.to_i
         end
 
         def date_of_latest_commit(folder:)

data/lib/churn_vs_complexity/cli/main.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module ChurnVsComplexity
+  module CLI
+    module Main
+      class << self
+        def run!(options, folder)
+          validate_folder!(folder)
+          validate_options!(options)
+          config = config(options)
+          config.validate!
+
+          config.checker.check(folder:)
+        end
+
+        private
+
+        def validate_folder!(folder)
+          raise ValidationError, 'No folder selected. Use --help for usage information.' if folder.nil? || folder.empty?
+          raise ValidationError, "Folder #{folder} does not exist" unless File.directory?(folder)
+        end
+
+        def validate_options!(options)
+          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 unless options[:serializer].nil?
+
+          raise ValidationError, 'No serializer selected. Use --help for usage information.'
+        end
+
+        def config(options)
+          config_class =
+            case options[:mode]
+            when :timetravel then Timetravel::Config
+            when :delta then Delta::Config
+            else Normal::Config
+            end
+          config_class.new(**options)
+        end
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/cli/parser.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module ChurnVsComplexity
+  module CLI
+    module Parser
+      def self.create
+        options = { excluded: [] }
+        parser = OptionParser.new do |opts|
+          opts.banner = 'Usage: churn_vs_complexity [options] folder'
+
+          opts.on('--java', 'Check complexity of java classes') do
+            options[:language] = :java
+          end
+
+          opts.on('--ruby', 'Check complexity of ruby files') do
+            options[:language] = :ruby
+          end
+
+          opts.on('--js', '--ts', '--javascript', '--typescript',
+                  'Check complexity of javascript and typescript files',) do
+            options[:language] = :javascript
+          end
+
+          opts.on('--csv', 'Format output as CSV') do
+            options[:serializer] = :csv
+          end
+
+          opts.on('--graph', 'Format output as HTML page with Churn vs Complexity graph') do
+            options[:serializer] = :graph
+          end
+
+          opts.on('--summary', 'Output summary statistics (mean and median) for churn and complexity') do
+            options[:serializer] = :summary
+          end
+
+          opts.on('--excluded PATTERN',
+                  'Exclude file paths including this string. Can be used multiple times.',) do |value|
+            options[:excluded] << value
+          end
+
+          opts.on('--since YYYY-MM-DD',
+                  'Normal mode: Calculate churn after this date. Timetravel mode: calculate summaries from this date',) do |value|
+            options[:since] = value
+          end
+
+          opts.on('-m', '--month', 'Calculate churn for the month leading up to the most recent commit') do
+            options[:relative_period] = :month
+          end
+
+          opts.on('-q', '--quarter', 'Calculate churn for the quarter leading up to the most recent commit') do
+            options[:relative_period] = :quarter
+          end
+
+          opts.on('-y', '--year', 'Calculate churn for the year leading up to the most recent commit') do
+            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
+          end
+
+          opts.on('--dry-run', 'Echo the chosen options from the CLI') do
+            puts options
+            exit
+          end
+
+          opts.on('-h', '--help', 'Display help') do
+            puts opts
+            exit
+          end
+
+          opts.on('--version', 'Display version') do
+            puts ChurnVsComplexity::VERSION
+            exit
+          end
+        end
+        [parser, options]
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/cli.rb

@@ -1,101 +1,18 @@
 # frozen_string_literal: true
 
-require 'date'
-require 'time'
-require 'optparse'
+require_relative 'cli/parser'
+require_relative 'cli/main'
 
 module ChurnVsComplexity
-  class CLI
-    def self.run!
-      # Create an options hash to store parsed options
-      options = { excluded: [] }
-
-      # Initialize OptionParser
-      OptionParser.new do |opts|
-        opts.banner = 'Usage: churn_vs_complexity [options] folder'
-
-        opts.on('--java', 'Check complexity of java classes') do
-          options[:language] = :java
-        end
-
-        opts.on('--ruby', 'Check complexity of ruby files') do
-          options[:language] = :ruby
-        end
-
-        opts.on('--js', '--ts', '--javascript', '--typescript',
-                'Check complexity of javascript and typescript files',) do
-          options[:language] = :javascript
-        end
-
-        opts.on('--csv', 'Format output as CSV') do
-          options[:serializer] = :csv
-        end
-
-        opts.on('--graph', 'Format output as HTML page with Churn vs Complexity graph') do
-          options[:serializer] = :graph
-        end
-
-        opts.on('--summary', 'Output summary statistics (mean and median) for churn and complexity') do
-          options[:serializer] = :summary
-        end
-
-        opts.on('--excluded PATTERN',
-                'Exclude file paths including this string. Can be used multiple times.',) do |value|
-          options[:excluded] << value
-        end
-
-        opts.on('--since YYYY-MM-DD',
-                'Normal mode: Calculate churn after this date. Timetravel mode: calculate summaries from this date',) do |value|
-          options[:since] = value
-        end
-
-        opts.on('-m', '--month', 'Calculate churn for the month leading up to the most recent commit') do
-          options[:relative_period] = :month
-        end
-
-        opts.on('-q', '--quarter', 'Calculate churn for the quarter leading up to the most recent commit') do
-          options[:relative_period] = :quarter
-        end
-
-        opts.on('-y', '--year', 'Calculate churn for the year leading up to the most recent commit') do
-          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('--dry-run', 'Echo the chosen options from the CLI') do
-          puts options
-          exit
-        end
-
-        opts.on('-h', '--help', 'Display help') do
-          puts opts
-          exit
-        end
-      end.parse!
-
-      # First argument that is not an option is the folder
-      folder = ARGV.first
-
-      raise Error, 'No folder selected. Use --help for usage information.' if folder.nil? || folder.empty?
-
-      #  Verify that folder exists
-      raise Error, "Folder #{folder} does not exist" unless File.directory?(folder)
-
-      raise Error, 'No options selected. Use --help for usage information.' if options.empty?
-
-      config = Config.new(**options)
-
-      config.validate!
-
-      if options[:mode] == :timetravel
-        puts config.timetravel.go(folder:)
-      else
-        puts config.to_engine.check(folder:)
+  module CLI
+    class << self
+      def run!
+        parser, options = Parser.create
+        parser.parse!
+        # First argument that is not an option is the folder
+        folder = ARGV.first
+
+        puts Main.run!(options, folder)
       end
     end
   end

data/lib/churn_vs_complexity/complexity/eslint_calculator.rb

@@ -23,6 +23,12 @@ module ChurnVsComplexity
           end
         end
 
+        def check_dependencies!
+          `npm --version`
+        rescue Errno::ENOENT
+          raise Error, 'Needs node and npm installed'
+        end
+
         private
 
         def gem_root

data/lib/churn_vs_complexity/complexity/pmd/files_calculator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module Complexity
+    module PMD
+      class FilesCalculator
+        def initialize(cache_components:)
+          @cache_components = cache_components
+        end
+
+        def folder_based? = false
+
+        def calculate(files:)
+          return Parser.empty_result if files.empty?
+
+          cache_path = PMD.resolve_cache_path(*@cache_components)
+          files_arg = files.map { |file| "-d #{file}" }.join(' ')
+          command = "pmd check #{files_arg} -R #{PMD.resolve_ruleset_path} -f json -t #{CONCURRENCY} --cache #{cache_path} 2>/dev/null"
+          output = `#{command}`
+
+          Parser.new.parse(output)
+        end
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/complexity/pmd/folder_calculator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module Complexity
+    module PMD
+      module FolderCalculator
+        class << self
+          def folder_based? = true
+
+          def calculate(folder:)
+            cache_path = PMD.resolve_cache_path(folder)
+            output = `pmd check -d #{folder} -R #{PMD.resolve_ruleset_path} -f json -t #{CONCURRENCY} --cache #{cache_path} 2>/dev/null`
+
+            Parser.new.parse(output)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/complexity/{pmd_calculator.rb → pmd.rb}

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
+require_relative 'pmd/folder_calculator'
+require_relative 'pmd/files_calculator'
+
 module ChurnVsComplexity
   module Complexity
-    module PMDCalculator
+    module PMD
       CONCURRENCY = Etc.nprocessors
 
       class << self
-        def folder_based? = true
+        def resolve_ruleset_path
+          ruleset_path = File.join(gem_root, 'tmp', 'pmd-support', 'ruleset.xml')
+          raise "ruleset.xml not found in #{ruleset_path}" unless File.exist?(ruleset_path)
 
-        def calculate(folder:)
-          cache_path = resolve_cache_path
-          output = `pmd check -d #{folder} -R #{resolve_ruleset_path} -f json -t #{CONCURRENCY}  --cache #{cache_path}`
-          File.delete(cache_path)
+          ruleset_path
+        end
 
-          Parser.new.parse(output)
+        def resolve_cache_path(*components)
+          File.join(ChurnVsComplexity.tmp_dir_path(*components), 'pmd', 'pmd-cache')
         end
 
         def check_dependencies!
@@ -24,23 +28,12 @@ module ChurnVsComplexity
 
         private
 
-        def resolve_ruleset_path
-          ruleset_path = File.join(gem_root, 'tmp', 'pmd-support', 'ruleset.xml')
-          raise "ruleset.xml not found in #{ruleset_path}" unless File.exist?(ruleset_path)
-
-          ruleset_path
-        end
-
-        def resolve_cache_path
-          File.join(gem_root, 'tmp', 'pmd-support', "pmd-cache-#{Process.pid}")
-        end
-
-        def gem_root
-          File.expand_path('../../..', __dir__)
-        end
+        def gem_root = ROOT_PATH
       end
 
       class Parser
+        def self.empty_result = {}
+
         def parse(output)
           doc = JSON.parse(output)
           doc['files'].each_with_object({}) do |file, result|

data/lib/churn_vs_complexity/complexity.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'complexity/pmd_calculator'
+require_relative 'complexity/pmd'
 require_relative 'complexity/flog_calculator'
 require_relative 'complexity/eslint_calculator'
 

data/lib/churn_vs_complexity/complexity_validator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module ComplexityValidator
+    def self.validate!(language)
+      case language
+      when :java
+        Complexity::PMD.check_dependencies!
+      when :javascript
+        Complexity::ESLintCalculator.check_dependencies!
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/concurrent_calculator.rb

@@ -14,8 +14,10 @@ module ChurnVsComplexity
 
     def calculate(folder:, files:, since:)
       latest_commit_date = @churn.date_of_latest_commit(folder:)
-      @git_period = GitDate.git_period(since, latest_commit_date)
-      schedule_churn_calculation(folder, files[:included], @git_period.effective_start_date)
+      unless latest_commit_date == :disabled
+        @git_period = GitDate.git_period(since, latest_commit_date)
+        schedule_churn_calculation(folder, files[:included], @git_period.effective_start_date)
+      end
       calculate_complexity(folder, files)
       await_results
       combine_results
@@ -49,7 +51,7 @@ module ChurnVsComplexity
     end
 
     def await_results
-      @threads.each(&:join)
+      @threads&.each(&:join)
     rescue StandardError => e
       raise Error, "Failed to caculate churn: #{e.message}"
     end

data/lib/churn_vs_complexity/delta/checker.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module Delta
+    class Checker
+      def initialize(serializer:, factory:, commit:, language:, excluded:, data_isolation_id: 0)
+        @serializer = serializer
+        @excluded = excluded
+        @factory = factory
+        @commit = commit
+        @language = language
+        @data_isolation_id = data_isolation_id
+      end
+
+      def check(folder:)
+        raise Error, 'Invalid commit' unless valid_commit?(folder:)
+
+        worktree = setup_worktree(folder:)
+
+        changes = @factory.git_strategy(folder: worktree.folder).changes(commit: @commit)
+        result = commit_summary(folder:)
+        unless changes.empty?
+          ComplexityAnnotator.new(factory: @factory, changes:)
+                             .enhance(worktree_folder: worktree.folder, language: @language, excluded: @excluded, commit: @commit)
+          result[:changes] = changes
+        end
+
+        @serializer.serialize(result)
+      end
+
+      private
+
+      def setup_worktree(folder:)
+        worktree = @factory.worktree(root_folder: folder, git_strategy: @factory.git_strategy(folder:),
+                                     data_isolation_id: @data_isolation_id,)
+        worktree.prepare
+        worktree.checkout(@commit)
+
+        worktree
+      end
+
+      def commit_summary(folder:)
+        CommitHydrator.new(
+          git_strategy: @factory.git_strategy(folder:),
+          serializer: @serializer,
+        ).hydrate(@commit)
+      end
+
+      def valid_commit?(folder:)
+        @factory.git_strategy(folder:).valid_commit?(commit: @commit)
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/delta/commit_hydrator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module Delta
+    class CommitHydrator
+      def initialize(git_strategy:, serializer:)
+        @git_strategy = git_strategy
+        @serializer = serializer
+      end
+
+      def hydrate(commit_sha)
+        commit = @git_strategy.object(commit_sha)
+        summary = { commit: commit.sha }
+        if @serializer.respond_to?(:has_commit_summary?) && @serializer.has_commit_summary?
+          parent, next_commit = @git_strategy.surrounding(commit:)
+          summary.merge!(parent:, next_commit:)
+        end
+        summary
+      end
+    end
+  end
+end

data/lib/churn_vs_complexity/delta/complexity_annotator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module Delta
+    class ComplexityAnnotator
+      def initialize(factory:, changes:)
+        @factory = factory
+        @changes = changes
+      end
+
+      def enhance(worktree_folder:, language:, excluded:, commit:)
+        @changes.each do |change|
+          change[:full_path] = File.join(worktree_folder, change[:path])
+        end
+
+        files = @changes.reject { |change| change[:type] == :deleted }.map { |change| change[:full_path] }
+
+        engine = @factory.engine(cache_components: [worktree_folder, commit], language:, excluded:, files:)
+
+        values_by_file = engine.check(folder: worktree_folder)[:values_by_file]
+
+        valid_extensions = FileSelector.extensions(language)
+        @changes.select! { |change| valid_extensions.any? { |ext| change[:path].end_with?(ext) } }
+        @changes.each do |annotated_file|
+          annotated_file[:complexity] = values_by_file.dig(annotated_file[:full_path], 1)
+        end
+      end
+    end
+  end
+end