pretty-git 0.1.2 → 0.1.4

data/lib/pretty_git/cli_helpers.rb

@@ -9,14 +9,14 @@ module PrettyGit
   # and RuboCop-compliant. Provides parser configuration and execution utilities.
   # rubocop:disable Metrics/ModuleLength
   module CLIHelpers
-    REPORTS = %w[summary activity authors files heatmap languages].freeze
+    REPORTS = %w[summary activity authors files heatmap languages hotspots churn ownership].freeze
     FORMATS = %w[console json csv md yaml xml].freeze
     METRICS = %w[bytes files loc].freeze
 
     module_function
 
     def configure_parser(opts, options)
-      opts.banner = 'Usage: pretty-git [REPORT] [options]'
+      opts.banner = 'Usage: pretty-git [REPORT] [REPO] [options]'
       add_repo_options(opts, options)
       add_time_author_options(opts, options)
       add_path_limit_options(opts, options)
@@ -75,7 +75,9 @@ module PrettyGit
       code = handle_version_help(options, parser, out)
       return code unless code.nil?
 
-      return nil if valid_report?(options[:report]) && valid_theme?(options[:theme]) && valid_metric?(options[:metric])
+      base_ok = valid_report?(options[:report]) && valid_theme?(options[:theme]) && valid_metric?(options[:metric])
+      conflicts_ok = validate_conflicts(options, err)
+      return nil if base_ok && conflicts_ok
 
       print_validation_errors(options, err)
       1
@@ -112,6 +114,17 @@ module PrettyGit
       err.puts "Unknown metric: #{options[:metric]}. Supported: #{METRICS.join(', ')}"
     end
 
+    # Returns true when flags are consistent; otherwise prints errors and returns false
+    def validate_conflicts(options, err)
+      ok = true
+      if options[:metric] && options[:report] != 'languages'
+        err.puts "--metric is only supported for 'languages' report"
+        ok = false
+      end
+      # time_bucket is accepted by multiple reports historically; do not enforce here.
+      ok
+    end
+
     def build_filters(options)
       Filters.new(
         repo_path: options[:repo],

data/lib/pretty_git/filters.rb

@@ -31,14 +31,23 @@ module PrettyGit
 
     private
 
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def time_to_iso8601(val)
       return nil if val.nil? || val.to_s.strip.empty?
 
-      t = val.is_a?(Time) ? val : Time.parse(val.to_s)
-      t = t.getlocal if t.utc_offset.nil?
+      # If value is a date without time, interpret as UTC midnight to avoid
+      # timezone-dependent shifts across environments.
+      if val.is_a?(String) && val.match?(/^\d{4}-\d{2}-\d{2}$/)
+        y, m, d = val.split('-').map(&:to_i)
+        t = Time.new(y, m, d, 0, 0, 0, '+00:00')
+      else
+        # Otherwise parse normally and normalize to UTC.
+        t = val.is_a?(Time) ? val : Time.parse(val.to_s)
+      end
       t.utc.iso8601
     rescue ArgumentError
       raise ArgumentError, "Invalid datetime: #{val} (expected ISO8601 or YYYY-MM-DD)"
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   end
 end

data/lib/pretty_git/git/provider.rb

@@ -7,6 +7,7 @@ require_relative '../types'
 module PrettyGit
   module Git
     # Streams commits from git CLI using `git log --numstat` and parses them.
+    # rubocop:disable Metrics/ClassLength
     class Provider
       SEP_RECORD = "\x1E" # record separator
       SEP_FIELD  = "\x1F" # unit separator
@@ -57,7 +58,7 @@ module PrettyGit
 
         additions = current[:files].sum(&:additions)
         deletions = current[:files].sum(&:deletions)
-        yld << Types::Commit.new(
+        commit = Types::Commit.new(
           sha: current[:sha],
           author_name: current[:author_name],
           author_email: current[:author_email],
@@ -67,6 +68,9 @@ module PrettyGit
           deletions: deletions,
           files: current[:files]
         )
+        return if exclude_author?(commit.author_name, commit.author_email)
+
+        yld << commit
       end
 
       def record_separator?(line)
@@ -120,13 +124,41 @@ module PrettyGit
         @filters.branches&.each { |b| args << "--branches=#{b}" }
       end
 
+      # rubocop:disable Metrics/AbcSize
       def add_path_filters(args)
         path_args = Array(@filters.paths).compact
-        return if path_args.empty?
+        exclude_args = Array(@filters.exclude_paths).compact
+
+        # Nothing to filter by
+        return if path_args.empty? && exclude_args.empty?
 
         args << '--'
-        args.concat(path_args)
+
+        # If only excludes provided, include all paths first
+        args << '.' if path_args.empty? && !exclude_args.empty?
+
+        # Include patterns as-is
+        args.concat(path_args) unless path_args.empty?
+
+        # Exclude patterns via git pathspec magic with glob
+        exclude_args.each do |pat|
+          args << ":(exclude,glob)#{pat}"
+        end
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def exclude_author?(name, email)
+        patterns = Array(@filters.exclude_authors).compact
+        return false if patterns.empty?
+
+        patterns.any? do |pat|
+          pn = pat.to_s
+          name&.downcase&.include?(pn.downcase) || email&.downcase&.include?(pn.downcase)
+        end
       end
+      # rubocop:enable Metrics/CyclomaticComplexity
     end
   end
 end
+# rubocop:enable Metrics/ClassLength

data/lib/pretty_git/render/console_renderer.rb

@@ -153,6 +153,7 @@ module PrettyGit
     end
 
     # Renders human-friendly console output with optional colors.
+    # rubocop:disable Metrics/ClassLength
     class ConsoleRenderer
       def initialize(io: $stdout, color: true, theme: 'basic')
         @io = io
@@ -162,22 +163,21 @@ module PrettyGit
       end
 
       def call(report, result, _filters)
-        case report
-        when 'summary'
-          render_summary(result)
-        when 'activity'
-          render_activity(result)
-        when 'authors'
-          render_authors(result)
-        when 'files'
-          render_files(result)
-        when 'heatmap'
-          render_heatmap(result)
-        when 'languages'
-          LanguagesSection.render(@io, @table, result, color: @color)
-        else
-          @io.puts result.inspect
-        end
+        handlers = {
+          'summary' => method(:render_summary),
+          'activity' => method(:render_activity),
+          'authors' => method(:render_authors),
+          'files' => method(:render_files),
+          'heatmap' => method(:render_heatmap),
+          'languages' => ->(data) { LanguagesSection.render(@io, @table, data, color: @color) },
+          'hotspots' => method(:render_hotspots),
+          'churn' => method(:render_churn),
+          'ownership' => method(:render_ownership)
+        }
+        handler = handlers[report]
+        return @io.puts(result.inspect) unless handler
+
+        handler.call(result)
       end
 
       private
@@ -266,6 +266,42 @@ module PrettyGit
 
       # Languages rendering moved to PrettyGit::Render::LanguagesSection
 
+      def render_hotspots(data)
+        title "Hotspots for #{data[:repo_path]}"
+        line "Period: #{data.dig(:period, :since)} .. #{data.dig(:period, :until)}"
+
+        @io.puts
+        title 'Hotspots'
+        @table.print(%w[path score commits additions deletions], data[:items])
+
+        @io.puts
+        line "Generated at: #{data[:generated_at]}"
+      end
+
+      def render_churn(data)
+        title "Churn for #{data[:repo_path]}"
+        line "Period: #{data.dig(:period, :since)} .. #{data.dig(:period, :until)}"
+
+        @io.puts
+        title 'Churn'
+        @table.print(%w[path churn commits], data[:items])
+
+        @io.puts
+        line "Generated at: #{data[:generated_at]}"
+      end
+
+      def render_ownership(data)
+        title "Ownership for #{data[:repo_path]}"
+        line "Period: #{data.dig(:period, :since)} .. #{data.dig(:period, :until)}"
+
+        @io.puts
+        title 'Ownership'
+        @table.print(%w[path owner owner_share authors], data[:items])
+
+        @io.puts
+        line "Generated at: #{data[:generated_at]}"
+      end
+
       def title(text)
         @io.puts Colors.title(text, @color, @theme)
       end
@@ -276,5 +312,6 @@ module PrettyGit
 
       # table is handled by @table
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/pretty_git/render/csv_renderer.rb

@@ -4,33 +4,36 @@ require 'csv'
 
 module PrettyGit
   module Render
-    # Renders CSV according to specs/output_formats.md and DR-001
+    # Renders CSV according to docs/output_formats.md and DR-001
     class CsvRenderer
+      HEADERS = {
+        'activity' => %w[bucket timestamp commits additions deletions],
+        'authors' => %w[author author_email commits additions deletions avg_commit_size],
+        'files' => %w[path commits additions deletions changes],
+        'heatmap' => %w[dow hour commits],
+        'hotspots' => %w[path score commits additions deletions changes],
+        'churn' => %w[path churn commits additions deletions],
+        'ownership' => %w[path owner owner_share authors]
+      }.freeze
       def initialize(io: $stdout)
         @io = io
       end
 
       def call(report, result, _filters)
-        case report
-        when 'activity'
-          write_csv(%w[bucket timestamp commits additions deletions], result[:items])
-        when 'authors'
-          write_csv(%w[author author_email commits additions deletions avg_commit_size], result[:items])
-        when 'files'
-          write_csv(%w[path commits additions deletions changes], result[:items])
-        when 'heatmap'
-          write_csv(%w[dow hour commits], result[:items])
-        when 'languages'
-          metric = (result[:metric] || 'bytes').to_s
-          headers = ['language', metric, 'percent', 'color']
-          write_csv(headers, result[:items])
-        else
-          raise ArgumentError, "CSV output for report '#{report}' is not supported yet"
-        end
+        headers = headers_for(report, result)
+        write_csv(headers, result[:items])
       end
 
       private
 
+      def headers_for(report, result)
+        return ['language', (result[:metric] || 'bytes').to_s, 'percent', 'color'] if report == 'languages'
+
+        HEADERS.fetch(report) do
+          raise ArgumentError, "CSV output for report '#{report}' is not supported yet"
+        end
+      end
+
       def write_csv(headers, rows)
         csv = CSV.generate(force_quotes: false) do |out|
           out << headers

data/lib/pretty_git/render/markdown_renderer.rb

@@ -2,37 +2,54 @@
 
 module PrettyGit
   module Render
-    # Renders Markdown tables and sections per specs/output_formats.md
+    # Renders Markdown tables and sections per docs/output_formats.md
+    # rubocop:disable Metrics/ClassLength
     class MarkdownRenderer
+      TITLES = {
+        'activity' => 'Activity',
+        'authors' => 'Authors',
+        'files' => 'Top Files',
+        'heatmap' => 'Heatmap',
+        'languages' => 'Languages',
+        'hotspots' => 'Hotspots',
+        'churn' => 'Churn',
+        'ownership' => 'Ownership'
+      }.freeze
+
+      HEADERS = {
+        'activity' => %w[bucket timestamp commits additions deletions],
+        'authors' => %w[author author_email commits additions deletions avg_commit_size],
+        'files' => %w[path commits additions deletions changes],
+        'heatmap' => %w[dow hour commits],
+        'hotspots' => %w[path score commits additions deletions changes],
+        'churn' => %w[path churn commits additions deletions],
+        'ownership' => %w[path owner owner_share authors]
+      }.freeze
       def initialize(io: $stdout)
         @io = io
       end
 
-      # rubocop:disable Metrics/CyclomaticComplexity
       def call(report, result, _filters)
-        case report
-        when 'summary'
-          render_summary(result)
-        when 'activity'
-          render_table('Activity', %w[bucket timestamp commits additions deletions], result[:items])
-        when 'authors'
-          render_table('Authors', %w[author author_email commits additions deletions avg_commit_size], result[:items])
-        when 'files'
-          render_table('Top Files', %w[path commits additions deletions changes], result[:items])
-        when 'heatmap'
-          render_table('Heatmap', %w[dow hour commits], result[:items])
-        when 'languages'
-          metric = (result[:metric] || 'bytes').to_s
-          headers = ['language', metric, 'percent', 'color']
-          render_table('Languages', headers, result[:items])
-        else
-          @io.puts result.inspect
-        end
+        return render_summary(result) if report == 'summary'
+
+        headers = headers_for(report, result)
+        title = title_for(report)
+        rows = sort_rows(report, result[:items], result)
+        render_table(title, headers, rows)
       end
-      # rubocop:enable Metrics/CyclomaticComplexity
 
       private
 
+      def headers_for(report, result)
+        return ['language', (result[:metric] || 'bytes').to_s, 'percent', 'color'] if report == 'languages'
+
+        HEADERS.fetch(report, [])
+      end
+
+      def title_for(report)
+        TITLES.fetch(report, report.to_s.capitalize)
+      end
+
       def render_summary(data)
         header_summary(data)
         print_totals(data[:totals])
@@ -67,6 +84,53 @@ module PrettyGit
         end
         @io.puts 'No data' if rows.empty?
       end
+
+      # Deterministic ordering per docs/determinism.md
+      # NOTE: High branching is intentional to keep tie-breakers explicit and stable across formats.
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def sort_rows(report, rows, ctx = nil)
+        return rows unless rows.is_a?(Array)
+
+        case report
+        when 'hotspots'
+          rows.sort_by { |r| [-to_f(r[:score]), -to_i(r[:commits]), -to_i(r[:changes]), to_s(r[:path])] }
+        when 'churn'
+          rows.sort_by { |r| [-to_i(r[:churn]), -to_i(r[:commits]), to_s(r[:path])] }
+        when 'ownership'
+          rows.sort_by { |r| [-to_f(r[:owner_share]), -to_i(r[:authors]), to_s(r[:path])] }
+        when 'files'
+          rows.sort_by { |r| [-to_i(r[:changes]), -to_i(r[:commits]), to_s(r[:path])] }
+        when 'authors'
+          rows.sort_by { |r| [-to_i(r[:commits]), -to_i(r[:additions]), -to_i(r[:deletions]), to_s(r[:author_email])] }
+        when 'languages'
+          metric = ctx && ctx[:metric] ? ctx[:metric].to_sym : :bytes
+          rows.sort_by { |r| [-to_i(r[metric]), to_s(r[:language])] }
+        when 'activity'
+          rows.sort_by { |r| [to_s(r[:timestamp])] }
+        when 'heatmap'
+          rows.sort_by { |r| [to_i(r[:dow] || r[:day] || r[:weekday]), to_i(r[:hour])] }
+        else
+          rows
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      def to_i(val)
+        Integer(val || 0)
+      rescue StandardError
+        0
+      end
+
+      def to_f(val)
+        Float(val || 0.0)
+      rescue StandardError
+        0.0
+      end
+
+      def to_s(val)
+        (val || '').to_s
+      end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/pretty_git/render/xml_renderer.rb

@@ -10,15 +10,29 @@ module PrettyGit
         @io = io
       end
 
-      def call(_report, result, _filters)
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def call(report, result, _filters)
+        ordered = apply_order(report, result)
         doc = REXML::Document.new
         doc << REXML::XMLDecl.new('1.0', 'UTF-8')
-        root = doc.add_element('report')
-        hash_to_xml(root, result)
+        root_name = case report
+                    when 'hotspots' then 'hotspotsReport'
+                    when 'churn' then 'churnReport'
+                    when 'ownership' then 'ownershipReport'
+                    when 'languages' then 'languagesReport'
+                    when 'files' then 'filesReport'
+                    when 'authors' then 'authorsReport'
+                    when 'activity' then 'activityReport'
+                    when 'heatmap' then 'heatmapReport'
+                    else 'report'
+                    end
+        root = doc.add_element(root_name)
+        hash_to_xml(root, ordered)
         formatter = REXML::Formatters::Pretty.new(2)
         formatter.compact = true
         formatter.write(doc, @io)
       end
+      # rubocop:enable Metrics/CyclomaticComplexity
 
       private
 
@@ -38,6 +52,60 @@ module PrettyGit
           parent.text = obj.nil? ? '' : obj.to_s
         end
       end
+
+      # Deterministic ordering per docs/determinism.md
+      # NOTE: High branching is intentional to keep tie-breakers explicit and stable across formats.
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def apply_order(report, result)
+        dup = Marshal.load(Marshal.dump(result))
+        items = dup[:items]
+        return dup unless items.is_a?(Array)
+
+        dup[:items] =
+          case report
+          when 'hotspots'
+            items.sort_by do |r|
+              [-to_f(r[:score]), -to_i(r[:commits]), -to_i(r[:changes]), to_s(r[:path])]
+            end
+          when 'churn'
+            items.sort_by { |r| [-to_i(r[:churn]), -to_i(r[:commits]), to_s(r[:path])] }
+          when 'ownership'
+            items.sort_by { |r| [-to_f(r[:owner_share]), -to_i(r[:authors]), to_s(r[:path])] }
+          when 'files'
+            items.sort_by { |r| [-to_i(r[:changes]), -to_i(r[:commits]), to_s(r[:path])] }
+          when 'authors'
+            items.sort_by do |r|
+              [-to_i(r[:commits]), -to_i(r[:additions]), -to_i(r[:deletions]), to_s(r[:author_email])]
+            end
+          when 'languages'
+            metric = (dup[:metric] || 'bytes').to_sym
+            items.sort_by { |r| [-to_i(r[metric]), to_s(r[:language])] }
+          when 'activity'
+            items.sort_by { |r| [to_s(r[:timestamp])] }
+          when 'heatmap'
+            items.sort_by { |r| [to_i(r[:dow] || r[:day] || r[:weekday]), to_i(r[:hour])] }
+          else
+            items
+          end
+        dup
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      def to_i(val)
+        Integer(val || 0)
+      rescue StandardError
+        0
+      end
+
+      def to_f(val)
+        Float(val || 0.0)
+      rescue StandardError
+        0.0
+      end
+
+      def to_s(val)
+        (val || '').to_s
+      end
     end
   end
 end

data/lib/pretty_git/render/yaml_renderer.rb

@@ -10,9 +10,11 @@ module PrettyGit
         @io = io
       end
 
-      def call(_report, result, _filters)
+      def call(report, result, _filters)
+        # Apply deterministic ordering for items where applicable
+        ordered = apply_order(report, result)
         # Dump the entire result structure to YAML with string keys for safe parsing
-        @io.write(stringify_keys(result).to_yaml)
+        @io.write(stringify_keys(ordered).to_yaml)
       end
 
       private
@@ -29,6 +31,60 @@ module PrettyGit
           obj
         end
       end
+
+      # Deterministic ordering per docs/determinism.md
+      # NOTE: High branching is intentional to keep tie-breakers explicit and stable across formats.
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def apply_order(report, result)
+        dup = Marshal.load(Marshal.dump(result)) # deep dup
+        items = dup[:items]
+        return dup unless items.is_a?(Array)
+
+        dup[:items] =
+          case report
+          when 'hotspots'
+            items.sort_by do |r|
+              [-to_f(r[:score]), -to_i(r[:commits]), -to_i(r[:changes]), to_s(r[:path])]
+            end
+          when 'churn'
+            items.sort_by { |r| [-to_i(r[:churn]), -to_i(r[:commits]), to_s(r[:path])] }
+          when 'ownership'
+            items.sort_by { |r| [-to_f(r[:owner_share]), -to_i(r[:authors]), to_s(r[:path])] }
+          when 'files'
+            items.sort_by { |r| [-to_i(r[:changes]), -to_i(r[:commits]), to_s(r[:path])] }
+          when 'authors'
+            items.sort_by do |r|
+              [-to_i(r[:commits]), -to_i(r[:additions]), -to_i(r[:deletions]), to_s(r[:author_email])]
+            end
+          when 'languages'
+            metric = (dup[:metric] || 'bytes').to_sym
+            items.sort_by { |r| [-to_i(r[metric]), to_s(r[:language])] }
+          when 'activity'
+            items.sort_by { |r| [to_s(r[:timestamp])] }
+          when 'heatmap'
+            items.sort_by { |r| [to_i(r[:dow] || r[:day] || r[:weekday]), to_i(r[:hour])] }
+          else
+            items
+          end
+        dup
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      def to_i(val)
+        Integer(val || 0)
+      rescue StandardError
+        0
+      end
+
+      def to_f(val)
+        Float(val || 0.0)
+      rescue StandardError
+        0.0
+      end
+
+      def to_s(val)
+        (val || '').to_s
+      end
     end
   end
 end

data/lib/pretty_git/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PrettyGit
-  VERSION = '0.1.2'
+  VERSION = '0.1.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pretty-git
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Pretty Git Authors
@@ -51,8 +51,6 @@ dependencies:
         version: '4.0'
 description: Generates structured analytics from local Git repositories with multiple
   export formats.
-email:
-- ''
 executables:
 - pretty-git
 extensions: []
@@ -66,9 +64,12 @@ files:
 - lib/pretty_git.rb
 - lib/pretty_git/analytics/activity.rb
 - lib/pretty_git/analytics/authors.rb
+- lib/pretty_git/analytics/churn.rb
 - lib/pretty_git/analytics/files.rb
 - lib/pretty_git/analytics/heatmap.rb
+- lib/pretty_git/analytics/hotspots.rb
 - lib/pretty_git/analytics/languages.rb
+- lib/pretty_git/analytics/ownership.rb
 - lib/pretty_git/analytics/summary.rb
 - lib/pretty_git/app.rb
 - lib/pretty_git/cli.rb
@@ -89,9 +90,11 @@ homepage: https://github.com/MikoMikocchi/pretty-git
 licenses:
 - MIT
 metadata:
+  homepage_uri: https://github.com/MikoMikocchi/pretty-git
   source_code_uri: https://github.com/MikoMikocchi/pretty-git
   changelog_uri: https://github.com/MikoMikocchi/pretty-git/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/MikoMikocchi/pretty-git/issues
+  documentation_uri: https://github.com/MikoMikocchi/pretty-git#readme
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: