snitcher_reports 0.2.0

data/lib/snitcher/work_item.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Snitcher
+  # Normalized work item from any source.
+  # Supports NDJSON serialization for Unix-style piping between commands.
+  WorkItem = Data.define(
+    :source,            # Symbol: :jira, :git, :linear, :clickup, :google_calendar
+    :external_id,       # String: "PROJ-123", "abc123", "ENG-456"
+    :title,             # String: issue/PR title
+    :completed_at,      # Time or nil
+    :time_spent_seconds, # Integer or nil
+    :time_source,       # Symbol: :worklog, :calculated, :estimate, nil
+    :url,               # String or nil: link to issue/PR
+    :metadata           # Hash: source-specific extra data
+  ) do
+    def time_spent_human
+      return nil unless time_spent_seconds
+
+      TimeFormatter.format_duration(time_spent_seconds)
+    end
+
+    def completed_date
+      completed_at&.strftime('%Y-%m-%d')
+    end
+
+    # Serialize to a plain Hash suitable for JSON output
+    def to_h
+      {
+        source: source,
+        external_id: external_id,
+        title: title,
+        completed_at: completed_at&.iso8601,
+        time_spent_seconds: time_spent_seconds,
+        time_source: time_source,
+        url: url,
+        metadata: metadata
+      }
+    end
+
+    def to_json(...)
+      to_h.to_json(...)
+    end
+
+    # Deserialize from a Hash (as parsed from JSON)
+    def self.from_h(hash)
+      new(
+        source: hash['source']&.to_sym,
+        external_id: hash['external_id'],
+        title: hash['title'],
+        completed_at: hash['completed_at'] ? Time.parse(hash['completed_at']) : nil,
+        time_spent_seconds: hash['time_spent_seconds'],
+        time_source: hash['time_source']&.to_sym,
+        url: hash['url'],
+        metadata: hash['metadata'] || {}
+      )
+    end
+
+    # Parse NDJSON lines (one JSON object per line) into WorkItem array.
+    # Malformed lines are skipped with a warning to support robust piping.
+    def self.from_ndjson(text)
+      text.lines.filter_map do |line|
+        line = line.strip
+        next if line.empty?
+
+        from_h(JSON.parse(line))
+      rescue JSON::ParserError => e
+        warn "[snitcher] Skipping malformed NDJSON line: #{e.message}"
+        nil
+      end
+    end
+  end
+end

data/lib/snitcher/working_hours_calculator.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require 'holidays'
+require 'tzinfo'
+
+module Snitcher
+  # Calculates working seconds between two UTC timestamps,
+  # filtering to configured business hours and work days.
+  #
+  # When no working hours config is provided, returns raw wall-clock seconds
+  # (backward compatible with existing behavior).
+  #
+  # @example
+  #   config = { timezone: 'Europe/Warsaw', start_hour: '09:00',
+  #              end_hour: '17:00', work_days: [1, 2, 3, 4, 5],
+  #              holidays_region: 'pl' }
+  #   WorkingHoursCalculator.seconds_between(start_utc, end_utc, config)
+  #
+  module WorkingHoursCalculator
+    # Monday through Friday, using Ruby's Date#wday convention (0=Sun, 6=Sat).
+    DEFAULT_WORK_DAYS = [1, 2, 3, 4, 5].freeze
+
+    # Maximum days to iterate (~2 years) before falling back to raw seconds (safety cap).
+    MAX_ITERATION_DAYS = 730
+
+    # HH:MM format regex for time validation.
+    TIME_FORMAT = /\A\d{2}:\d{2}\z/
+
+    # Reusable empty set for when no holidays region is configured.
+    EMPTY_HOLIDAY_SET = Set.new.freeze
+
+    class << self
+      # Calculate working seconds between two UTC timestamps.
+      #
+      # @param start_time [Time] UTC start timestamp
+      # @param end_time [Time] UTC end timestamp
+      # @param working_hours [Hash, nil] working hours config with symbol keys:
+      #   :timezone, :start_hour, :end_hour, :work_days, :holidays_region (optional)
+      # @return [Integer] seconds within working hours, or raw seconds if config nil.
+      #   Returns negative when config is nil and end_time < start_time (raw subtraction).
+      #   Returns 0 when config is present and end_time <= start_time.
+      def seconds_between(start_time, end_time, working_hours = nil)
+        return (end_time - start_time).to_i if working_hours.nil?
+        return 0 if end_time <= start_time
+
+        parsed = parsed_config(working_hours)
+        return 0 unless parsed
+
+        calculate(start_time, end_time, **parsed)
+      end
+
+      # Validates an HH:MM time string format and hour/minute ranges.
+      #
+      # @param value [String] time string to validate
+      # @return [Boolean] true if valid HH:MM with hour 0-23 and minute 0-59
+      # @example
+      #   WorkingHoursCalculator.valid_time_format?('09:00') # => true
+      #   WorkingHoursCalculator.valid_time_format?('25:00') # => false
+      def valid_time_format?(value)
+        return false unless value.is_a?(String) && value.match?(TIME_FORMAT)
+
+        h, m = value.split(':').map(&:to_i)
+        (0..23).cover?(h) && (0..59).cover?(m)
+      end
+
+      # Whether start_hour is strictly before end_hour (night shifts not supported).
+      # The single source of truth for the check #parse_config also relies on.
+      # Assumes HH:MM input: anything else counts as 00:00, so check
+      # valid_time_format? first when the values are not yet validated.
+      #
+      # @param start_hour [String] HH:MM
+      # @param end_hour [String] HH:MM
+      # @return [Boolean]
+      # @example
+      #   WorkingHoursCalculator.ordered?(start_hour: '09:00', end_hour: '17:00') # => true
+      #   WorkingHoursCalculator.ordered?(start_hour: '17:00', end_hour: '09:00') # => false
+      def ordered?(start_hour:, end_hour:)
+        minutes_of(start_hour) < minutes_of(end_hour)
+      end
+
+      # Resets module-level caches. Call in test setup to prevent cross-test leakage.
+      def reset_cache!
+        @parsed_by_config = nil
+        @holiday_set_cache = nil
+      end
+
+      private
+
+      # Parsed configs, keyed by the config hash. A batch report resolves one config per
+      # person and Configuration memoizes them, so this is bounded by the number of people
+      # in the run. key? rather than ||= because parse_config returns nil for inverted
+      # hours, and that answer is worth caching too.
+      # NOTE: Not thread-safe; acceptable because the CLI is single-threaded.
+      def parsed_config(working_hours)
+        cache = (@parsed_by_config ||= {})
+        return cache[working_hours] if cache.key?(working_hours)
+
+        cache[working_hours] = parse_config(working_hours)
+      end
+
+      # Parses working_hours config hash into internal typed representation.
+      # @param working_hours [Hash] config with symbol keys
+      #   (:timezone, :start_hour, :end_hour, :work_days, :holidays_region)
+      # @return [Hash, nil] parsed config, or nil if start >= end (inverted hours)
+      def parse_config(working_hours)
+        start_hour = working_hours[:start_hour].to_s
+        end_hour = working_hours[:end_hour].to_s
+        return nil unless ordered?(start_hour: start_hour, end_hour: end_hour)
+
+        timezone = TZInfo::Timezone.get(working_hours[:timezone])
+        work_days = working_hours[:work_days] || DEFAULT_WORK_DAYS
+        start_h, start_m = start_hour.split(':').map(&:to_i)
+        end_h, end_m = end_hour.split(':').map(&:to_i)
+
+        { timezone: timezone, work_days: work_days,
+          day_start_h: start_h || 0, day_start_m: start_m || 0,
+          day_end_h: end_h || 0, day_end_m: end_m || 0,
+          holidays_region: working_hours[:holidays_region]&.to_sym }
+      end
+
+      # @param hh_mm [String] HH:MM
+      # @return [Integer] minutes since midnight
+      def minutes_of(hh_mm)
+        h, m = hh_mm.to_s.split(':').map(&:to_i)
+        (h.to_i * 60) + m.to_i
+      end
+
+      # Iterates day-by-day from start to end, accumulating seconds that fall
+      # within the configured work-day window (clamped to actual start/end bounds).
+      # rubocop:disable Metrics/ParameterLists
+      def calculate(start_time, end_time, timezone:, work_days:, day_start_h:, day_start_m:, day_end_h:, day_end_m:,
+                    holidays_region: nil)
+        # rubocop:enable Metrics/ParameterLists
+        local_start = timezone.to_local(start_time)
+        local_end = timezone.to_local(end_time)
+        end_date = local_end.to_date
+
+        day_span = (end_date - local_start.to_date).to_i
+        if day_span > MAX_ITERATION_DAYS
+          warn "[Snitcher] Warning: time range spans #{day_span} days (> #{MAX_ITERATION_DAYS}), " \
+               'falling back to raw seconds.'
+          return (end_time - start_time).to_i
+        end
+
+        holiday_dates = build_holiday_set(local_start.to_date, end_date, holidays_region)
+
+        total = 0
+        current_date = local_start.to_date
+
+        while current_date <= end_date
+          if work_days.include?(current_date.wday) && !holiday_dates.include?(current_date)
+            work_day_start_utc = safe_local_to_utc(timezone, current_date, day_start_h, day_start_m)
+            work_day_end_utc = safe_local_to_utc(timezone, current_date, day_end_h, day_end_m)
+
+            effective_start = [start_time, work_day_start_utc].max
+            effective_end = [end_time, work_day_end_utc].min
+
+            total += (effective_end - effective_start).to_i if effective_end > effective_start
+          end
+          current_date = current_date.next_day
+        end
+
+        total
+      end
+
+      # Pre-fetches all public holidays in the date range and returns a Set for O(1) lookup.
+      # Results are cached by region — subsequent calls with the same region and overlapping
+      # date range reuse the cached set (avoids N Holidays.between calls for N issues).
+      # @param start_date [Date] range start
+      # @param end_date [Date] range end
+      # @param region [Symbol, nil] holidays gem region (e.g. :pl)
+      # @return [Set] set of Date objects that are public holidays (empty if no region)
+      def build_holiday_set(start_date, end_date, region)
+        return EMPTY_HOLIDAY_SET if region.nil?
+
+        cache = (@holiday_set_cache ||= {})
+        cached = cache[region]
+        return cached[:set] if cached && cached[:start_date] <= start_date && cached[:end_date] >= end_date
+
+        holiday_set = Holidays.between(start_date, end_date, region, :observed)
+                              .to_set { |h| h[:date] }
+
+        cache[region] = { start_date: start_date, end_date: end_date, set: holiday_set }
+        holiday_set
+      end
+
+      # Safely convert local time to UTC, handling DST ambiguity and gaps.
+      # For ambiguous times (fall-back): picks the first (DST) occurrence.
+      # For gap times (spring-forward): shifts forward past the gap using time arithmetic.
+      # Assumes standard 1-hour DST gap (covers all current IANA zones).
+      def safe_local_to_utc(timezone, date, hour, minute)
+        wall_clock = Time.utc(date.year, date.month, date.day, hour, minute, 0)
+        timezone.local_to_utc(wall_clock, &:first)
+      rescue TZInfo::PeriodNotFound
+        shifted = wall_clock + 3600
+        begin
+          timezone.local_to_utc(Time.utc(shifted.year, shifted.month, shifted.day,
+                                         shifted.hour, shifted.min, 0), &:first)
+        rescue TZInfo::PeriodNotFound
+          shifted # Exotic gap > 1 hour — best-effort: use shifted UTC time directly
+        end
+      end
+    end
+  end
+end

data/lib/snitcher/working_hours_config.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Snitcher
+  # Parses the top-level `working_hours` block and resolves it per person.
+  #
+  # The block's own keys are the shared defaults. A `people:` map, keyed by the work
+  # email a report is requested for, overrides individual keys for one person; every
+  # key that person leaves out is inherited. Omitting the block, or naming nobody in
+  # it, keeps the historical contract: nil, meaning raw wall-clock time.
+  #
+  # @example
+  #   working_hours:
+  #     timezone: "Europe/Warsaw"
+  #     start_hour: "09:00"
+  #     end_hour: "17:00"
+  #     people:
+  #       bob@corp.com:
+  #         timezone: "America/New_York"
+  #
+  class WorkingHoursConfig
+    # Holds the per-person overrides. Stripped before the shared block is validated,
+    # the same way Orchestrator strips :user/:emails before constructing a source.
+    PEOPLE_KEY = 'people'
+
+    # Keys a person may override. Anything else in their block is dropped, so a typo
+    # cannot smuggle an unrecognized key into an otherwise validated config.
+    OVERRIDABLE_KEYS = %w[timezone start_hour end_hour work_days holidays_region].freeze
+
+    def initialize(raw)
+      @raw = raw.is_a?(Hash) ? raw : {}
+      @resolved = {}
+    end
+
+    # The hours that apply to one person: their overrides merged over the shared block,
+    # or the shared block when they are not named. Memoized per email — repeated calls
+    # return the same object, which keeps WorkingHoursCalculator's cache hitting.
+    # @param user_email [String, nil] requested work email; nil asks for the shared block
+    # @return [Hash, nil] validated config with symbolized keys, nil when unconfigured
+    def for(user_email = nil)
+      key = normalize_key(user_email)
+      return @resolved[key] if @resolved.key?(key)
+
+      @resolved[key] = resolve(key)
+    end
+
+    # The same value, but only when this person is actually named in `people:` and their
+    # block was usable. Orchestrator needs to tell "this person is different" from
+    # "everyone gets the shared block", so it can leave a source's injected config alone.
+    # @return [Hash, nil]
+    def override_for(user_email)
+      key = normalize_key(user_email)
+      return nil unless key && people.key?(key)
+
+      resolved = self.for(user_email)
+      # A person whose block failed validation resolves to the shared object itself.
+      resolved.equal?(defaults) ? nil : resolved
+    end
+
+    private
+
+    def normalize_key(user_email)
+      email = user_email.to_s.strip
+      email.empty? ? nil : email
+    end
+
+    def resolve(key)
+      # Parse the shared block first even for a person who overrides every key, so a
+      # broken shared block is reported once instead of only for whoever lacks an entry.
+      base = defaults
+      overrides = key && people[key]
+      return base if overrides.nil? || overrides.empty?
+
+      parse(shared_block.merge(overrides), person: key) || base
+    end
+
+    def defaults
+      return @defaults if defined?(@defaults)
+
+      @defaults = parse(shared_block)
+    end
+
+    def shared_block
+      @shared_block ||= @raw.reject { |key, _| key.to_s == PEOPLE_KEY }
+    end
+
+    def people
+      @people ||= normalize_people(@raw[PEOPLE_KEY])
+    end
+
+    # Coerces the map to { String => Hash } of recognized keys only. Keys are not
+    # validated as emails: sources.<name>.emails does not validate its keys either, and
+    # an address that matches nobody simply never resolves.
+    def normalize_people(raw)
+      return {} if raw.nil?
+
+      unless raw.is_a?(Hash)
+        warn '[Snitcher] Warning: working_hours people must be a map of email => overrides. Ignoring.'
+        return {}
+      end
+
+      raw.each_with_object({}) do |(email, overrides), map|
+        key = email.to_s.strip
+        next if key.empty?
+
+        unless overrides.is_a?(Hash)
+          warn "[Snitcher] Warning: working_hours people entry for #{key} must be a map. Ignoring."
+          next
+        end
+
+        map[key] = overrides.to_h { |k, v| [k.to_s, v] }.slice(*OVERRIDABLE_KEYS)
+      end
+    end
+
+    # Validates one fully merged block. Returns nil — meaning "fall back" — for anything
+    # unusable, warning first. Nothing here raises: a config file must never abort a report.
+    def parse(block, person: nil)
+      return nil if block.empty?
+
+      validated = validate_fields(block, person)
+      return nil unless validated
+
+      Validators.validate_timezone!(validated[:timezone])
+      validated
+    rescue Validators::ValidationError => e
+      # e.message is already a sentence ("Unknown timezone: Foo/Bar"), so this one does not
+      # take the scope prefix the other warnings use.
+      scope = person ? " in working_hours for #{person}" : ''
+      outcome = person ? 'Using the shared working hours.' : 'Working hours disabled.'
+      warn "[Snitcher] Warning: #{e.message}#{scope}. #{outcome}"
+      nil
+    end
+
+    def validate_fields(block, person)
+      if block['timezone'].nil? || block['start_hour'].nil? || block['end_hour'].nil?
+        warn_config('config incomplete (needs timezone, start_hour, end_hour).', fallback_note(person), person)
+        return nil
+      end
+
+      start_hour = block['start_hour'].to_s
+      end_hour = block['end_hour'].to_s
+      return nil unless valid_hours?(block, start_hour, end_hour, person)
+
+      { timezone: block['timezone'], start_hour: start_hour, end_hour: end_hour,
+        work_days: validated_work_days(block['work_days'], person),
+        holidays_region: validated_holidays_region(block['holidays_region'], person) }
+    end
+
+    # Format first, then order: each rule fails with its own warning.
+    def valid_hours?(block, start_hour, end_hour, person)
+      unless WorkingHoursCalculator.valid_time_format?(start_hour) &&
+             WorkingHoursCalculator.valid_time_format?(end_hour)
+        problem = if block['start_hour'].is_a?(Integer) || block['end_hour'].is_a?(Integer)
+                    'start_hour/end_hour must be quoted strings in YAML (e.g., "09:00").'
+                  else
+                    'start_hour/end_hour must be HH:MM format.'
+                  end
+        warn_config(problem, fallback_note(person), person)
+        return false
+      end
+
+      return true if WorkingHoursCalculator.ordered?(start_hour: start_hour, end_hour: end_hour)
+
+      warn_config("start_hour '#{start_hour}' must be before end_hour '#{end_hour}' (night shifts not supported).",
+                  fallback_note(person), person)
+      false
+    end
+
+    def valid_work_days?(work_days)
+      work_days.is_a?(Array) && work_days.all? { |d| d.is_a?(Integer) && (0..6).cover?(d) }
+    end
+
+    def validated_work_days(work_days, person)
+      if work_days && !valid_work_days?(work_days)
+        warn_config('work_days must be array of integers 0-6.', 'Using default Mon-Fri.', person)
+        return WorkingHoursCalculator::DEFAULT_WORK_DAYS
+      end
+
+      work_days || WorkingHoursCalculator::DEFAULT_WORK_DAYS
+    end
+
+    # Validates holidays_region against the holidays gem's known regions.
+    def validated_holidays_region(region, person)
+      return nil if region.nil?
+
+      region_str = region.to_s.strip
+      return nil if region_str.empty?
+
+      unless HolidayRegionResolver.valid_region?(region_str)
+        warn_config("unknown holidays region '#{region_str}'.", 'Holiday exclusion disabled.', person)
+        return nil
+      end
+
+      region_str
+    end
+
+    # Every warning names the block it came from, and a person's warning names them.
+    def warn_config(problem, outcome, person)
+      scope = person ? "working_hours for #{person}" : 'working_hours'
+      warn "[Snitcher] Warning: #{scope} #{problem} #{outcome}"
+    end
+
+    # A broken shared block disables working hours entirely; a broken person block only
+    # sends that person back to the shared one.
+    def fallback_note(person)
+      person ? 'Using the shared working hours.' : 'Working hours disabled; raw wall-clock time is used.'
+    end
+  end
+end

data/lib/snitcher.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+# NOTE: dotenv is deliberately not loaded here — an embedded core must take the host
+# application's ENV as-is.
+
+# NOTE: json is required for the host, not for this file — the public payload is a plain
+# Hash and `payload.to_json` is its documented serialization, so Hash#to_json has to exist
+# after `require "snitcher"`. The suite cannot catch its removal: webmock loads json first.
+require 'json'
+
+module Snitcher
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class << self
+    # Entry point for embedding Snitcher in a host application.
+    # @return [Snitcher::Client]
+    def new(config_path: Configuration::DEFAULT_CONFIG_FILE)
+      Client.new(config_path: config_path)
+    end
+
+    def root
+      @root ||= Pathname.new(File.expand_path('..', __dir__))
+    end
+
+    def loader
+      @loader ||= Zeitwerk::Loader.for_gem.tap do |ldr|
+        ldr.inflector.inflect(
+          'clickup' => 'ClickUp',
+          'jql_validator' => 'JQLValidator'
+        )
+        ldr.setup
+      end
+    end
+  end
+end
+
+Snitcher.loader