pretty-git 0.1.4 → 0.1.6

data/lib/pretty_git/cli.rb

@@ -9,9 +9,6 @@ require_relative 'cli_helpers'
 module PrettyGit
   # Command-line interface entry point.
   class CLI
-    SUPPORTED_REPORTS = %w[summary activity authors files heatmap languages hotspots churn ownership].freeze
-    SUPPORTED_FORMATS = %w[console json csv md yaml xml].freeze
-
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity
     def self.run(argv = ARGV, out: $stdout, err: $stderr)
       options = {
@@ -28,6 +25,7 @@ module PrettyGit
         out: nil,
         no_color: false,
         theme: 'basic',
+        _verbose: false,
         _version: false,
         _help: false
       }
@@ -55,11 +53,24 @@ module PrettyGit
       filters = CLIHelpers.build_filters(options)
       CLIHelpers.execute(options[:report], filters, options, out, err)
     rescue ArgumentError => e
-      err.puts e.message
+      err.puts "Error: #{e.message}"
       1
-    rescue StandardError => e
-      err.puts e.message
+    rescue Errno::ENOENT => e
+      # Repository not found is user input error (exit 1), file write error is system error (exit 2)
+      if e.message.include?('chdir') || options[:repo]
+        err.puts "Not a git repository: #{e.message}"
+        1
+      else
+        err.puts "File system error: #{e.message}"
+        2
+      end
+    rescue Errno::EACCES => e
+      err.puts "Permission denied: #{e.message}"
       2
+    rescue StandardError => e
+      err.puts "Unexpected error: #{e.message}"
+      err.puts e.backtrace.first(5).join("\n") if options[:_verbose]
+      99
     end
     # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity
   end

data/lib/pretty_git/cli_helpers.rb

@@ -1,29 +1,71 @@
 # frozen_string_literal: true
 
 require 'optparse'
+require 'fileutils'
 require_relative 'filters'
 require_relative 'app'
+require_relative 'constants'
 
 module PrettyGit
   # Helpers extracted from `PrettyGit::CLI` to keep the CLI class small
   # and RuboCop-compliant. Provides parser configuration and execution utilities.
   # rubocop:disable Metrics/ModuleLength
   module CLIHelpers
-    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
+    REPORTS = PrettyGit::Constants::REPORTS
+    FORMATS = PrettyGit::Constants::FORMATS
+    METRICS = PrettyGit::Constants::METRICS
+    THEMES  = PrettyGit::Constants::THEMES
 
     module_function
 
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def configure_parser(opts, options)
-      opts.banner = 'Usage: pretty-git [REPORT] [REPO] [options]'
+      opts.banner = <<~BANNER
+        Usage: pretty-git [REPORT] [REPO] [options]
+
+        Reports: #{REPORTS.join(', ')}
+        Formats: #{FORMATS.join(', ')}
+        Themes:  #{THEMES.join(', ')}
+      BANNER
+      opts.separator('')
+      opts.separator('Repository and branch:')
       add_repo_options(opts, options)
+      opts.separator('')
+      opts.separator('Time, authors, and bucketing:')
       add_time_author_options(opts, options)
+      opts.separator('')
+      opts.separator('Paths and limits:')
       add_path_limit_options(opts, options)
+      opts.separator('')
+      opts.separator('Format and output:')
       add_format_output_options(opts, options)
+      opts.separator('')
+      opts.separator('Metrics (languages report only):')
       add_metric_options(opts, options)
+      opts.separator('')
+      opts.separator('Other:')
       add_misc_options(opts, options)
+      opts.separator('')
+      opts.separator('Examples:')
+      opts.separator('  # Summary in JSON to stdout')
+      opts.separator('  $ pretty-git summary . --format json')
+      opts.separator('')
+      opts.separator('  # Authors since a date with a limit')
+      opts.separator('  $ pretty-git authors ~/repo --since 2025-01-01 --limit 20')
+      opts.separator('')
+      opts.separator('  # Files with includes/excludes (globs)')
+      opts.separator('  $ pretty-git files . --path app/**/*.rb --exclude-path spec/**')
+      opts.separator('')
+      opts.separator('  # Activity bucketed by week to Markdown file')
+      opts.separator('  $ pretty-git activity . --time-bucket week --format md --out out/report.md')
+      opts.separator('')
+      opts.separator('  # Languages by LOC to CSV (redirect to file)')
+      opts.separator('  $ pretty-git languages . --metric loc --format csv > langs.csv')
+      opts.separator('')
+      opts.separator('  # Hotspots on main with a higher limit to YAML')
+      opts.separator('  $ pretty-git hotspots . --branch main --limit 50 --format yaml')
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def add_repo_options(opts, options)
       opts.on('--repo PATH', 'Path to git repository (default: .)') { |val| options[:repo] = val }
@@ -47,8 +89,14 @@ module PrettyGit
     def add_format_output_options(opts, options)
       opts.on('--format FMT', 'console|json|csv|md|yaml|xml') { |val| options[:format] = val }
       opts.on('--out FILE', 'Output file path') { |val| options[:out] = val }
-      opts.on('--no-color', 'Disable colors in console output') { options[:no_color] = true }
-      opts.on('--theme NAME', 'console color theme: basic|bright|mono') { |val| options[:theme] = val }
+      opts.on('--no-color', 'Disable colors in console output') do
+        options[:no_color] = true
+        options[:_no_color_provided] = true
+      end
+      opts.on('--theme NAME', 'console color theme: basic|bright|mono') do |val|
+        options[:theme] = val
+        options[:_theme_provided] = true
+      end
     end
 
     def add_metric_options(opts, options)
@@ -60,6 +108,7 @@ module PrettyGit
     def add_misc_options(opts, options)
       opts.on('--version', 'Show version') { options[:_version] = true }
       opts.on('--help', 'Show help') { options[:_help] = true }
+      opts.on('--verbose', 'Verbose output (debug)') { options[:_verbose] = true }
     end
 
     def parse_limit(str)
@@ -75,9 +124,14 @@ module PrettyGit
       code = handle_version_help(options, parser, out)
       return code unless code.nil?
 
-      base_ok = valid_report?(options[:report]) && valid_theme?(options[:theme]) && valid_metric?(options[:metric])
+      base_ok = valid_base?(options)
       conflicts_ok = validate_conflicts(options, err)
-      return nil if base_ok && conflicts_ok
+      if base_ok && conflicts_ok
+        early = warn_ignores(options, err)
+        return 0 if early == :early_exit
+
+        return nil
+      end
 
       print_validation_errors(options, err)
       1
@@ -96,19 +150,47 @@ module PrettyGit
     end
 
     def valid_report?(report) = REPORTS.include?(report)
-    def valid_theme?(theme) = %w[basic bright mono].include?(theme)
+    def valid_theme?(theme) = THEMES.include?(theme)
+    def valid_format?(fmt) = FORMATS.include?(fmt)
+
+    def valid_base?(options)
+      valid_report?(options[:report]) &&
+        valid_theme?(options[:theme]) &&
+        valid_metric?(options[:metric]) &&
+        valid_format?(options[:format])
+    end
 
     def valid_metric?(metric)
       metric.nil? || METRICS.include?(metric)
     end
 
     def print_validation_errors(options, err)
-      supported = REPORTS.join(', ')
-      unless valid_report?(options[:report])
-        err.puts "Unknown report: #{options[:report]}."
-        err.puts "Supported: #{supported}"
-      end
-      err.puts "Unknown theme: #{options[:theme]}. Supported: basic, bright, mono" unless valid_theme?(options[:theme])
+      print_report_error(options, err)
+      print_theme_error(options, err)
+      print_format_error(options, err)
+      print_metric_error(options, err)
+    end
+
+    def print_report_error(options, err)
+      return if valid_report?(options[:report])
+
+      err.puts "Unknown report: #{options[:report]}."
+      err.puts "Supported: #{REPORTS.join(', ')}"
+    end
+
+    def print_theme_error(options, err)
+      return if valid_theme?(options[:theme])
+
+      err.puts "Unknown theme: #{options[:theme]}. Supported: #{THEMES.join(', ')}"
+    end
+
+    def print_format_error(options, err)
+      return if valid_format?(options[:format])
+
+      err.puts "Unknown format: #{options[:format]}. Supported: #{FORMATS.join(', ')}"
+    end
+
+    def print_metric_error(options, err)
       return if valid_metric?(options[:metric])
 
       err.puts "Unknown metric: #{options[:metric]}. Supported: #{METRICS.join(', ')}"
@@ -125,12 +207,45 @@ module PrettyGit
       ok
     end
 
+    # Print non-fatal warnings for flags that won't have effect with current options
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def warn_ignores(options, err)
+      return unless err
+
+      fmt = options[:format]
+      return unless fmt && fmt != 'console'
+
+      err.puts "Warning: --theme has no effect when --format=#{fmt}" if options[:theme]
+      err.puts "Warning: --no-color has no effect when --format=#{fmt}" if options[:no_color]
+
+      # Exit early only if user explicitly provided these console-only flags
+      # AND no other significant options that warrant running the app were provided.
+      return unless options[:_theme_provided] || options[:_no_color_provided]
+
+      significant = significant_options?(options)
+      :early_exit unless significant
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    def significant_options?(options)
+      return true if options[:out]
+      return true if options[:metric]
+      return true if options[:time_bucket]
+      return true if options[:limit] && options[:limit] != 10
+
+      any_collection_present?(options, %i[branches authors exclude_authors paths exclude_paths])
+    end
+
+    def any_collection_present?(options, keys)
+      keys.any? { |k| options[k]&.any? }
+    end
+
     def build_filters(options)
       Filters.new(
         repo_path: options[:repo],
         branches: options[:branches],
         since: options[:since],
-        until: options[:until],
+        until_at: options[:until],
         authors: options[:authors],
         exclude_authors: options[:exclude_authors],
         paths: options[:paths],
@@ -141,14 +256,28 @@ module PrettyGit
         format: options[:format],
         out: options[:out],
         no_color: options[:no_color],
-        theme: options[:theme]
+        theme: options[:theme],
+        verbose: options[:_verbose]
       )
     end
 
     def execute(report, filters, options, out, err)
       if options[:out]
-        File.open(options[:out], 'w') do |f|
-          return PrettyGit::App.new.run(report, filters, out: f, err: err)
+        begin
+          dir = File.dirname(options[:out])
+          FileUtils.mkdir_p(dir) unless dir.nil? || dir == '.'
+          File.open(options[:out], 'w') do |f|
+            return PrettyGit::App.new.run(report, filters, out: f, err: err)
+          end
+        rescue Errno::EISDIR
+          err.puts "Cannot write to: #{options[:out]} (is a directory)"
+          return 2
+        rescue Errno::EACCES
+          err.puts "Cannot write to: #{options[:out]} (permission denied)"
+          return 2
+        rescue Errno::ENOENT
+          err.puts "Cannot write to: #{options[:out]} (directory not found)"
+          return 2
         end
       end
 

data/lib/pretty_git/constants.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PrettyGit
+  module Constants
+    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
+
+    THEMES = %w[basic bright mono].freeze
+  end
+end

data/lib/pretty_git/filters.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require 'time'
+require_relative 'utils/time_utils'
 
 module PrettyGit
   Filters = Struct.new(
     :repo_path,
     :branches,
     :since,
-    :until,
+    :until_at,
     :authors,
     :exclude_authors,
     :paths,
@@ -19,35 +20,53 @@ module PrettyGit
     :out,
     :no_color,
     :theme,
+    :verbose,
     keyword_init: true
   ) do
-    def since_iso8601
-      time_to_iso8601(since)
+    # Backward-compat: allow initializing with `until:` keyword by remapping to :until_at
+    # Preserve Struct keyword_init behavior by overriding initialize instead of .new
+    def initialize(*args, **kwargs)
+      # Accept a single Hash positional argument for backward compatibility
+      kwargs = args.first if (kwargs.nil? || kwargs.empty?) && args.length == 1 && args.first.is_a?(Hash)
+      kwargs ||= {}
+
+      if kwargs.key?(:until)
+        Kernel.warn('[pretty-git] DEPRECATION: Filters initialized with :until. Use :until_at instead.')
+        kwargs = kwargs.dup
+        kwargs[:until_at] = kwargs.delete(:until)
+      end
+
+      # Keyword-init struct: prefer keyword form consistently to keep initialize simple
+      super(**kwargs)
     end
 
-    def until_iso8601
-      time_to_iso8601(self[:until])
+    # Backward-compat: support filters.until and filters.until=
+    def until
+      self[:until_at]
+    end
+
+    def until=(val)
+      self[:until_at] = val
     end
 
-    private
+    # Backward-compat for hash-style access used in older specs
+    def [](key)
+      key = :until_at if key == :until
+      super
+    end
 
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-    def time_to_iso8601(val)
-      return nil if val.nil? || val.to_s.strip.empty?
+    def []=(key, value)
+      key = :until_at if key == :until
+      super
+    end
 
-      # 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)"
+    def since_iso8601
+      PrettyGit::Utils::TimeUtils.to_utc_iso8601(since)
+    end
+
+    # Keep method name for backwards compatibility across the codebase
+    def until_iso8601
+      PrettyGit::Utils::TimeUtils.to_utc_iso8601(self[:until_at])
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   end
 end

data/lib/pretty_git/git/provider.rb

@@ -2,7 +2,10 @@
 
 require 'open3'
 require 'time'
+require 'json'
 require_relative '../types'
+require_relative '../logger'
+require_relative '../utils/path_utils'
 
 module PrettyGit
   module Git
@@ -17,10 +20,18 @@ module PrettyGit
       end
 
       # Returns Enumerator of PrettyGit::Types::Commit
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/BlockLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def each_commit
         Enumerator.new do |yld|
+          prof = ENV['PG_PROF'] == '1'
+          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          headers = 0
+          numstat_lines = 0
           cmd = build_git_command
+          PrettyGit::Logger.verbose(
+            "[pretty-git] git cmd: #{cmd.join(' ')} (cwd=#{@filters.repo_path})",
+            @filters.verbose
+          )
           Open3.popen3(*cmd, chdir: @filters.repo_path) do |_stdin, stdout, stderr, wait_thr|
             current = nil
             stdout.each_line do |line|
@@ -28,6 +39,7 @@ module PrettyGit
               # Try to start a new commit from header on any line
               header = start_commit_from_header(line)
               if header
+                headers += 1 if prof
                 # emit previous commit if any
                 emit_current(yld, current)
                 current = header
@@ -36,6 +48,7 @@ module PrettyGit
 
               next if line.empty?
 
+              numstat_lines += 1 if prof
               append_numstat_line(current, line)
             end
 
@@ -44,12 +57,36 @@ module PrettyGit
             status = wait_thr.value
             unless status.success?
               err = stderr.read
-              raise StandardError, (err && !err.empty? ? err : "git log failed with status #{status.exitstatus}")
+              error_msg = err && !err.empty? ? err : "git log failed with status #{status.exitstatus}"
+              # Repository errors are ArgumentError (invalid input), other git errors are StandardError
+              if error_msg.include?('not a git repository') || error_msg.include?('Not a git repository')
+                raise ArgumentError, error_msg
+              end
+
+              raise StandardError, error_msg
+
             end
           end
+
+          t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if prof
+            # Emit a compact profile to stderr
+            elapsed = (t1 - t0)
+            warn format(
+              '[pg_prof] git_provider: time=%<sec>.3fs headers=%<headers>d numstat_lines=%<num>d',
+              { sec: elapsed, headers: headers, num: numstat_lines }
+            )
+            summary = {
+              component: 'git_provider',
+              time_sec: elapsed,
+              headers: headers,
+              numstat_lines: numstat_lines
+            }
+            warn("[pg_prof_json] #{summary.to_json}")
+          end
         end
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/BlockLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       private
 
@@ -73,10 +110,6 @@ module PrettyGit
         yld << commit
       end
 
-      def record_separator?(line)
-        line == SEP_RECORD
-      end
-
       def start_commit_from_header(line)
         sha, author_name, author_email, authored_at, subject = line.split(SEP_FIELD, 5)
         return nil unless subject
@@ -120,14 +153,20 @@ module PrettyGit
       end
 
       def add_author_and_branch_filters(args)
-        @filters.authors&.each { |a| args << "--author=#{a}" }
-        @filters.branches&.each { |b| args << "--branches=#{b}" }
+        @filters.authors&.each do |a|
+          validate_safe_string(a, 'author')
+          args << "--author=#{a}"
+        end
+        # Treat branches as explicit revisions to include
+        @filters.branches&.each do |b|
+          validate_git_ref(b)
+          args << b
+        end
       end
 
-      # rubocop:disable Metrics/AbcSize
       def add_path_filters(args)
-        path_args = Array(@filters.paths).compact
-        exclude_args = Array(@filters.exclude_paths).compact
+        path_args = PrettyGit::Utils::PathUtils.normalize_globs(@filters.paths)
+        exclude_args = PrettyGit::Utils::PathUtils.normalize_globs(@filters.exclude_paths)
 
         # Nothing to filter by
         return if path_args.empty? && exclude_args.empty?
@@ -137,15 +176,14 @@ module PrettyGit
         # If only excludes provided, include all paths first
         args << '.' if path_args.empty? && !exclude_args.empty?
 
-        # Include patterns as-is
+        # Include patterns (normalized)
         args.concat(path_args) unless path_args.empty?
 
-        # Exclude patterns via git pathspec magic with glob
+        # Exclude patterns via git pathspec magic with glob (normalized)
         exclude_args.each do |pat|
           args << ":(exclude,glob)#{pat}"
         end
       end
-      # rubocop:enable Metrics/AbcSize
 
       # rubocop:disable Metrics/CyclomaticComplexity
       def exclude_author?(name, email)
@@ -158,6 +196,31 @@ module PrettyGit
         end
       end
       # rubocop:enable Metrics/CyclomaticComplexity
+
+      # Validates that a string doesn't contain shell metacharacters that could be exploited
+      def validate_safe_string(value, name)
+        return if value.nil? || value.empty?
+
+        # Check for dangerous shell metacharacters
+        return unless value.to_s =~ /[;&|`$()<>]/
+
+        raise ArgumentError, "Invalid #{name}: contains shell metacharacters"
+      end
+
+      # Validates git references (branch names, tags, commit SHAs)
+      # Allows alphanumeric, dash, underscore, slash, dot, @, ^, ~, and :
+      def validate_git_ref(ref)
+        return if ref.nil? || ref.empty?
+
+        # Git ref naming rules are complex, but we allow a safe subset
+        # See: https://git-scm.com/docs/git-check-ref-format
+        raise ArgumentError, "Invalid git ref: #{ref}" unless ref.to_s =~ %r{\A[a-zA-Z0-9/_.\-@^~:]+\z}
+
+        # Additional safety: reject refs that look like options
+        return unless ref.to_s.start_with?('-')
+
+        raise ArgumentError, "Invalid git ref: #{ref} (looks like an option)"
+      end
     end
   end
 end

data/lib/pretty_git/logger.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PrettyGit
+  # Minimal centralized logger for PrettyGit.
+  # Writes to stderr by default; can accept custom IO via keyword.
+  module Logger
+    module_function
+
+    def warn(msg, err: $stderr)
+      err.puts(msg)
+    end
+
+    # Convenience: only emit when enabled is truthy
+    def verbose(msg, enabled, err: $stderr)
+      return unless enabled
+
+      warn(msg, err: err)
+    end
+  end
+end

data/lib/pretty_git/render/console_renderer.rb

@@ -7,6 +7,24 @@ module PrettyGit
   module Render
     # Simple color helpers used by console components.
     module Colors
+      # ANSI color codes for different themes
+      module AnsiCodes
+        # Title colors
+        BRIGHT_TITLE = '1;35'    # Bright magenta
+        BASIC_TITLE = '1;36'     # Cyan
+
+        # Header colors
+        BRIGHT_HEADER = '1;36'   # Bright cyan
+        BASIC_HEADER = '1;34'    # Blue
+
+        # Text styles
+        DIM = '2;37'             # Dim white
+        GREEN = '32'             # Green
+        RED = '31'               # Red
+        YELLOW = '33'            # Yellow
+        BOLD = '1'               # Bold
+      end
+
       module_function
 
       def apply(code, text, enabled)
@@ -16,33 +34,33 @@ module PrettyGit
       end
 
       def title(text, enabled, theme = 'basic')
-        code = theme == 'bright' ? '1;35' : '1;36'
+        code = theme == 'bright' ? AnsiCodes::BRIGHT_TITLE : AnsiCodes::BASIC_TITLE
         apply(code, text, enabled)
       end
 
       def header(text, enabled, theme = 'basic')
-        code = theme == 'bright' ? '1;36' : '1;34'
+        code = theme == 'bright' ? AnsiCodes::BRIGHT_HEADER : AnsiCodes::BASIC_HEADER
         apply(code, text, enabled)
       end
 
       def dim(text, enabled)
-        apply('2;37', text, enabled)
+        apply(AnsiCodes::DIM, text, enabled)
       end
 
       def green(text, enabled)
-        apply('32', text, enabled)
+        apply(AnsiCodes::GREEN, text, enabled)
       end
 
       def red(text, enabled)
-        apply('31', text, enabled)
+        apply(AnsiCodes::RED, text, enabled)
       end
 
       def yellow(text, enabled)
-        apply('33', text, enabled)
+        apply(AnsiCodes::YELLOW, text, enabled)
       end
 
       def bold(text, enabled)
-        apply('1', text, enabled)
+        apply(AnsiCodes::BOLD, text, enabled)
       end
     end