churn_vs_complexity 1.4.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7484ff3a1c015738808226a78087017f6b7aff5ce42d15879023f32df5648717
-  data.tar.gz: ad3bdeff5ba32e9d7f414b45173d8928b1c463313557202b96aaf5fdcf059109
+  metadata.gz: dba0d67852cef763abe50d7fa5a63a7e9b4687b5232d05b281ed267cf948a0c4
+  data.tar.gz: 1839953429d9840ce96782431d530f45e8169441e54c94badf9f12fc9aea7b0a
 SHA512:
-  metadata.gz: a56e26296acfff22e755c414cab9ee36923e4ccd7181d67691f55feb8f99b5aa738f5d2b7645006f25c632efa346fb535d7fe04923443dedf607772ce1a21323
-  data.tar.gz: f406ee696facf7708e792b67ed8b463f1554365b3939deb4bde40c9fab88dfe891997f611727559a283103c5b7234f71d78d5fe108731628cb3fd8a782a73ce5
+  metadata.gz: 699fad42098c2a7e9e4e1368a03fda265ef3333b0e9c0895f6095e38898cf68a36a1c15d152de98f39a4f2a3ce866ce481bea68f83033876aa0d400cfe024b57
+  data.tar.gz: dd4a1412a7c49e76c7dd7624e80f5bd06f3c5bb027402f3eba8f9842568db3f4f6a2e1f6b9b5a559af6eee61c3049e7cd8848640432e3929f4b554b9c28dc847

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,35 @@
-## [1.0.0] - 2024-06-07
+## [1.5.1] - 2024-10-15
 
-- Initial release
+- Fix bug where worktree checkout silently failed
 
-## [1.1.0] - 2024-09-20
 
-- 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
+## [1.5.0] - 2024-10-14
 
-## [1.2.0] - 2024-09-20
+- Added delta mode to annotate changes in individual commits with complexity
+- Moving PMD cache to the OS temp directory
 
-- 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.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
+
+- 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
 
-- Add timetravel mode to visualise code quality over time
-- Add alpha, beta, and gamma scores to summaries
-- Fixed broken Ruby complexity calculation
+- Initial release

data/README.md

@@ -22,9 +22,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.
 
-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 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`.
+
+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 +47,9 @@ 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 and the previous commit and annotate changed files with complexity score. Can be used multiple times to specify multiple commits.
         --dry-run                    Echo the chosen options from the CLI
     -h, --help                       Display help
-
-
 ```
 
 Note that when using the `--timetravel` mode, the semantics of some flags are subtly different from normal mode:
@@ -71,6 +72,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/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 and the previous commit and annotate changed files with complexity score. 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,43 @@
 # frozen_string_literal: true
 
-require 'date'
-require 'time'
-require 'optparse'
+require_relative 'cli/parser'
 
 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)
+  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
+
+        validate_folder!(folder)
+        validate_options!(options)
+        config = config(options)
+        config.validate!
+        puts config.checker.check(folder:)
+      end
 
-      raise Error, 'No options selected. Use --help for usage information.' if options.empty?
+      private
 
-      config = Config.new(**options)
+      def validate_folder!(folder)
+        raise Error, 'No folder selected. Use --help for usage information.' if folder.nil? || folder.empty?
+        raise Error, "Folder #{folder} does not exist" unless File.directory?(folder)
+      end
 
-      config.validate!
+      def validate_options!(options)
+        raise Error, 'No options selected. Use --help for usage information.' if options.empty?
+        raise Error, 'No language selected. Use --help for usage information.' if options[:language].nil?
+        raise Error, 'No serializer selected. Use --help for usage information.' if options[:serializer].nil?
+      end
 
-      if options[:mode] == :timetravel
-        puts config.timetravel.go(folder:)
-      else
-        puts config.to_engine.check(folder:)
+      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

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,56 @@
+# 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:)
+        summary = { commit: @commit }
+        if @serializer.respond_to?(:has_commit_summary?) && @serializer.has_commit_summary?
+          parent, next_commit = @factory.git_strategy(folder:).surrounding(commit: @commit)
+          summary.merge!(parent:, next_commit:)
+        end
+        summary
+      end
+
+      def valid_commit?(folder:)
+        @factory.git_strategy(folder:).valid_commit?(commit: @commit)
+      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

data/lib/churn_vs_complexity/delta/config.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module Delta
+    class Config
+      def initialize(
+        language:,
+        serializer:,
+        commits:,
+        excluded: [],
+        complexity_validator: ComplexityValidator,
+        factory: Factory,
+        **_options
+      )
+        @language = language
+        @serializer = serializer
+        @excluded = excluded
+        @commits = commits
+        @factory = factory
+      end
+
+      def validate!
+        validate_commits!
+        LanguageValidator.validate!(@language)
+        SerializerValidator.validate!(serializer: @serializer)
+        @factory.complexity_validator.validate!(@language)
+      end
+
+      def checker
+        MultiChecker.new(serializer:, excluded: @excluded, factory: @factory, commits: @commits,
+                         language: @language,)
+      end
+
+      private
+
+      def validate_commits!
+        @commits.each { |commit| validate_commit!(commit) }
+      end
+
+      def validate_commit!(commit)
+        return if commit.match?(/\A[0-9a-f]{40}\z/i) || @commit.match?(/\A[0-9a-f]{8}\z/i)
+
+        raise ValidationError,
+              "Invalid commit: #{commit}. It must be a valid 40-character SHA-1 hash or an 8-character shortened form."
+      end
+
+      def serializer = Serializer.resolve(@serializer)
+    end
+  end
+end