flycal-cli 0.7.4 → 1.0

data/lib/flycal/mock/config.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flycal
+  module Mock
+    # Resolves mock options from CLI and/or a JSON template under mocks/.
+    class Config
+      TEMPLATE_KEYS = %w[
+        mockCalendar
+        mockEventDescriptionPatterns
+        mockEventCount
+        mockEventFrom
+        mockEventTo
+        mockEventDurationMin
+        mockEventDurationMax
+        mockEventHoursFrom
+        mockEventHoursTo
+        mockSeed
+      ].freeze
+
+      attr_reader :calendar_name, :seed, :patterns, :count,
+                  :range_from, :range_to, :duration_min_seconds, :duration_max_seconds,
+                  :hours_from, :hours_to, :template_name, :raw
+
+      def self.enabled?(options)
+        !options[:mockTemplate].to_s.empty? || !options[:mockCalendar].to_s.empty?
+      end
+
+      def self.from_options(options)
+        new(options)
+      end
+
+      def initialize(options)
+        merged = load_template(options[:mockTemplate])
+        TEMPLATE_KEYS.each do |key|
+          sym = key.to_sym
+          value = options[sym]
+          next if value.nil? || value.to_s.empty?
+
+          merged[key] = value
+        end
+
+        @template_name = options[:mockTemplate].to_s.empty? ? nil : options[:mockTemplate].to_s
+        calendar = merged["mockCalendar"].to_s
+        calendar = options[:mockCalendar].to_s if calendar.empty?
+        @calendar_name = calendar
+        raise Flycal::Error,
+              "Mock mode requires mockCalendar in the template (or --mockCalendar)." if @calendar_name.empty?
+
+        @raw = merged
+        @patterns = split_patterns(merged["mockEventDescriptionPatterns"])
+        @count = Integer(merged["mockEventCount"])
+        @range_from = parse_date(merged["mockEventFrom"], end_of_day: false)
+        @range_to = parse_date(merged["mockEventTo"], end_of_day: true)
+        @duration_min_seconds = DurationParser.to_seconds(merged["mockEventDurationMin"].to_s)
+        @duration_max_seconds = DurationParser.to_seconds(merged["mockEventDurationMax"].to_s)
+        @hours_from = parse_hour_minute(merged["mockEventHoursFrom"])
+        @hours_to = parse_hour_minute(merged["mockEventHoursTo"])
+        @seed = resolve_seed(merged["mockSeed"])
+
+        validate!
+      end
+
+      def to_h
+        {
+          mock_calendar: calendar_name,
+          mock_seed: seed,
+          mock_template: template_name,
+          mock_event_description_patterns: patterns.join(","),
+          mock_event_count: count,
+          mock_event_from: range_from,
+          mock_event_to: range_to,
+          mock_event_duration_min: duration_min_seconds,
+          mock_event_duration_max: duration_max_seconds,
+          mock_event_hours_from: hours_from,
+          mock_event_hours_to: hours_to
+        }
+      end
+
+      private
+
+      def load_template(name)
+        return {} if name.to_s.empty?
+
+        path = find_template_path(name)
+        raise Flycal::Error, "Mock template not found: #{name.inspect} (looked in ./mocks, ./mockTemplates, and gem paths)." unless path
+
+        data = JSON.parse(File.read(path))
+        raise Flycal::Error, "Mock template #{name.inspect} must be a JSON object." unless data.is_a?(Hash)
+
+        data
+      rescue JSON::ParserError => e
+        raise Flycal::Error, "Invalid mock template JSON (#{name}): #{e.message}"
+      end
+
+      def find_template_path(name)
+        base = name.to_s.sub(/\.json\z/, "")
+        gem_root = File.expand_path("../../..", __dir__)
+        candidates = [
+          File.join(Dir.pwd, "mocks", "#{base}.json"),
+          File.join(Dir.pwd, "mockTemplates", "#{base}.json"),
+          File.join(gem_root, "mocks", "#{base}.json"),
+          File.join(gem_root, "mockTemplates", "#{base}.json")
+        ]
+        candidates.find { |p| File.file?(p) }
+      end
+
+      def split_patterns(value)
+        list = value.to_s.split(",").map(&:strip).reject(&:empty?)
+        raise Flycal::Error, "mockEventDescriptionPatterns must list at least one pattern." if list.empty?
+
+        list
+      end
+
+      def parse_date(value, end_of_day:)
+        raise Flycal::Error, "Missing mock date." if value.to_s.empty?
+
+        DateTimeParser.parse(value.to_s, end_of_day: end_of_day)
+      end
+
+      def parse_hour_minute(value)
+        str = value.to_s.strip
+        match = str.match(/\A(\d{1,2}):(\d{2})\z/)
+        raise Flycal::Error, "Invalid mock hour #{value.inspect}. Use HH:MM (e.g. 09:00)." unless match
+
+        hour = match[1].to_i
+        min = match[2].to_i
+        unless hour.between?(0, 23) && min.between?(0, 59)
+          raise Flycal::Error, "Invalid mock hour #{value.inspect}. Use HH:MM (e.g. 09:00)."
+        end
+
+        [hour, min]
+      end
+
+      def resolve_seed(value)
+        return Integer(value) unless value.nil? || value.to_s.empty?
+
+        Random.new_seed & 0xFFFFFFFF
+      end
+
+      def validate!
+        missing = []
+        missing << "mockEventDescriptionPatterns" if patterns.empty?
+        missing << "mockEventCount" if count <= 0
+        missing << "mockEventFrom" if range_from.nil?
+        missing << "mockEventTo" if range_to.nil?
+        missing << "mockEventDurationMin" if duration_min_seconds <= 0
+        missing << "mockEventDurationMax" if duration_max_seconds <= 0
+        raise Flycal::Error, "Missing mock parameters: #{missing.join(", ")}" unless missing.empty?
+
+        if duration_min_seconds > duration_max_seconds
+          raise Flycal::Error, "mockEventDurationMin must be <= mockEventDurationMax."
+        end
+        if range_from > range_to
+          raise Flycal::Error, "mockEventFrom must be before mockEventTo."
+        end
+
+        from_mins = hours_from[0] * 60 + hours_from[1]
+        to_mins = hours_to[0] * 60 + hours_to[1]
+        if from_mins >= to_mins
+          raise Flycal::Error, "mockEventHoursFrom must be before mockEventHoursTo."
+        end
+        if duration_min_seconds > (to_mins - from_mins) * 60
+          raise Flycal::Error,
+                "mockEventDurationMin does not fit in mockEventHoursFrom..mockEventHoursTo window."
+        end
+      end
+    end
+  end
+end

data/lib/flycal/mock/event_generator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Flycal
+  module Mock
+    # Builds deterministic fake calendar events from a Mock::Config.
+    class EventGenerator
+      EventStart = Struct.new(:date_time, :date, keyword_init: true)
+      EventEnd = Struct.new(:date_time, :date, keyword_init: true)
+      Event = Struct.new(:summary, :description, :start, :end, keyword_init: true)
+
+      def initialize(config)
+        @config = config
+        @rng = Random.new(config.seed)
+      end
+
+      def generate
+        counters = Hash.new(0)
+        Array.new(@config.count) do
+          pattern = @config.patterns.sample(random: @rng)
+          counters[pattern] += 1
+          title = "#{pattern}#{counters[pattern]}"
+          start_at, end_at = random_range
+          Event.new(
+            summary: title,
+            description: title,
+            start: EventStart.new(date_time: start_at, date: nil),
+            end: EventEnd.new(date_time: end_at, date: nil)
+          )
+        end.sort_by { |e| e.start.date_time }
+      end
+
+      private
+
+      def random_range
+        day = random_day
+        duration = random_duration_seconds
+        start_at = random_start_on(day, duration)
+        [start_at, start_at + duration]
+      end
+
+      def random_day
+        from_date = @config.range_from.to_date
+        to_date = @config.range_to.to_date
+        span = (to_date - from_date).to_i
+        from_date + @rng.rand(0..span)
+      end
+
+      def random_duration_seconds
+        min = @config.duration_min_seconds
+        max = @config.duration_max_seconds
+        return min if min == max
+
+        @rng.rand(min..max)
+      end
+
+      def random_start_on(day, duration_seconds)
+        from_h, from_m = @config.hours_from
+        to_h, to_m = @config.hours_to
+        window_start = day.to_time + (from_h * 3600) + (from_m * 60)
+        window_end = day.to_time + (to_h * 3600) + (to_m * 60)
+        latest_start = window_end - duration_seconds
+        if latest_start < window_start
+          raise Flycal::Error, "Mock event duration does not fit in the daily hours window."
+        end
+
+        span = (latest_start - window_start).to_i
+        window_start + @rng.rand(0..span)
+      end
+    end
+  end
+end

data/lib/flycal/mock.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Flycal
+  module Mock
+  end
+end

data/lib/flycal/pipeline/aggregator.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/date"
+require "active_support/core_ext/integer"
+require "active_support/core_ext/time"
+
+module Flycal
+  module Pipeline
+    # Second pipeline layer: group events and compute aggregate metrics.
+    #
+    # Default group_by from timeframe:
+    #   day   — timeframe <= 7 days
+    #   week  — timeframe > 7 days and <= 30 days
+    #   month — timeframe > 30 days
+    #
+    # Override with params[:group_by_option] / --groupBy:
+    #   day | week | month | <any other string> (split on | for string grouping)
+    class Aggregator
+      HOURS_PER_WORKING_DAY = 8
+      TIME_GROUP_BY = %w[day week month].freeze
+
+      def call(params)
+        time_min = params[:time_min]
+        time_max = params[:time_max]
+        events = Array(params[:events])
+
+        timeframe_days = (time_max - time_min) / 86400.0
+        group_by = resolve_group_by(timeframe_days, params[:group_by_option])
+
+        params[:timeframe_days] = timeframe_days
+        params[:group_by] = group_by
+
+        ranges = events.filter_map do |ev|
+          next if ev[:start_at].nil? || ev[:end_at].nil?
+
+          [ev[:start_at], ev[:end_at]]
+        end
+
+        total_minutes = ranges.sum { |s, e| (e - s) / 60.0 }
+        params[:totals] = {
+          event_count: events.size,
+          total_minutes: total_minutes,
+          hours: (total_minutes / 60.0).floor,
+          minutes: (total_minutes % 60).round,
+          working_days: (total_minutes / 60.0 / HOURS_PER_WORKING_DAY).round(1)
+        }
+
+        params[:groups] =
+          case group_by
+          when "week" then weekly_groups(events, ranges, time_min, time_max)
+          when "month" then monthly_groups(events, ranges, time_min, time_max)
+          when "string" then string_groups(events, params[:group_by_option])
+          else daily_groups(events, ranges, time_min, time_max)
+          end
+
+        params
+      end
+
+      def self.resolve_group_by(timeframe_days, explicit = nil)
+        raw = explicit.to_s.strip
+        if raw.empty?
+          if timeframe_days > 30
+            "month"
+          elsif timeframe_days > 7
+            "week"
+          else
+            "day"
+          end
+        else
+          key = raw.downcase
+          TIME_GROUP_BY.include?(key) ? key : "string"
+        end
+      end
+
+      private
+
+      def resolve_group_by(timeframe_days, explicit)
+        self.class.resolve_group_by(timeframe_days, explicit)
+      end
+
+      def daily_groups(events, ranges, time_min, time_max)
+        groups = []
+        index = 1
+        current = time_min.to_date
+        end_date = time_max.to_date
+
+        while current <= end_date
+          day_start = [current.to_time, time_min].max
+          day_end = [(current + 1).to_time, time_max].min
+          mins = minutes_in_period(ranges, day_start, day_end)
+          groups << build_group(
+            index: index,
+            key: current.strftime("%Y-%m-%d"),
+            start_at: day_start,
+            end_at: day_end,
+            period_label_end: current,
+            total_minutes: mins,
+            events: events_in_period(events, day_start, day_end)
+          )
+          index += 1
+          current += 1
+        end
+
+        groups
+      end
+
+      def weekly_groups(events, ranges, time_min, time_max)
+        groups = []
+        index = 1
+        current = time_min.to_date.beginning_of_week(:monday)
+
+        while current.to_time < time_max
+          week_start = [current.to_time, time_min].max
+          week_end_date = current.end_of_week(:monday)
+          week_end = [week_end_date.to_time + 1.day, time_max].min
+          mins = minutes_in_period(ranges, week_start, week_end)
+          groups << build_group(
+            index: index,
+            key: "W#{index}",
+            start_at: week_start,
+            end_at: week_end,
+            period_label_end: week_end_date,
+            total_minutes: mins,
+            events: events_in_period(events, week_start, week_end)
+          )
+          index += 1
+          current += 7
+        end
+
+        groups
+      end
+
+      def monthly_groups(events, ranges, time_min, time_max)
+        groups = []
+        index = 1
+        current = time_min.to_date.beginning_of_month
+        end_date = time_max.to_date
+
+        while current <= end_date
+          month_start = current.beginning_of_month.to_time
+          month_end = (current.end_of_month + 1.day).to_time
+          period_start = [month_start, time_min].max
+          period_end = [month_end, time_max].min
+          mins = minutes_in_period(ranges, period_start, period_end)
+          last_day = period_end.to_date - 1
+          groups << build_group(
+            index: index,
+            key: current.strftime("%Y-%m"),
+            start_at: period_start,
+            end_at: period_end,
+            period_label_end: last_day,
+            total_minutes: mins,
+            month_name: "#{Locale.month_name(current)} #{current.year}",
+            events: events_in_period(events, period_start, period_end)
+          )
+          index += 1
+          current = current.next_month.beginning_of_month
+        end
+
+        groups
+      end
+
+      def string_groups(events, group_by_string)
+        patterns = DescriptionQuery.patterns(group_by_string)
+        if patterns.empty?
+          raise Flycal::Error,
+                "groupBy string requires at least one term (e.g. --groupBy \"rui|solver\")."
+        end
+
+        patterns.each_with_index.map do |pattern, idx|
+          matched = events.select do |ev|
+            DescriptionQuery.match_term?(ev[:summary], ev[:description], pattern)
+          end
+          minutes = matched.sum { |ev| ev[:duration_minutes].to_f }
+          build_group(
+            index: idx + 1,
+            key: pattern,
+            start_at: nil,
+            end_at: nil,
+            period_label_end: nil,
+            total_minutes: minutes,
+            events: matched,
+            string: pattern
+          )
+        end
+      end
+
+      def build_group(index:, key:, start_at:, end_at:, period_label_end:, total_minutes:, events:,
+                      month_name: nil, string: nil)
+        {
+          index: index,
+          key: key,
+          start_at: start_at,
+          end_at: end_at,
+          period_label_end: period_label_end,
+          month_name: month_name,
+          string: string,
+          event_count: events.size,
+          total_minutes: total_minutes,
+          hours: (total_minutes / 60.0).round(1),
+          working_days: (total_minutes / 60.0 / HOURS_PER_WORKING_DAY).round(1),
+          events: events
+        }
+      end
+
+      def events_in_period(events, period_start, period_end)
+        events.select do |ev|
+          start_at = ev[:start_at]
+          end_at = ev[:end_at]
+          next false if start_at.nil? || end_at.nil?
+
+          end_at > period_start && start_at < period_end
+        end
+      end
+
+      def minutes_in_period(ranges, period_start, period_end)
+        ranges.sum do |ev_start, ev_end|
+          overlap_start = [ev_start, period_start].max
+          overlap_end = [ev_end, period_end].min
+          overlap_sec = overlap_end - overlap_start
+          overlap_sec > 0 ? overlap_sec / 60.0 : 0
+        end
+      end
+    end
+  end
+end

data/lib/flycal/pipeline/json_renderer.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flycal
+  module Pipeline
+    # Pretty-printed JSON output for search (API / tooling friendly).
+    class JsonRenderer < Renderer
+      def render(params)
+        payload = {
+          "params" => build_params(params),
+          "info" => build_info(params),
+          "text" => lines_for_output(TextRenderer.new.render(params)),
+          "items" => Array(params[:events]).map { |ev| serialize_event(ev) },
+          "groups" => build_groups(params)
+        }
+
+        JSON.pretty_generate(payload) + "\n"
+      end
+
+      private
+
+      def strip_ansi(text)
+        text.to_s.gsub(/\e\[[0-9;]*m/, "")
+      end
+
+      def lines_for_output(text)
+        strip_ansi(text).split("\n")
+      end
+
+      def build_params(params)
+        out = {
+          "command" => params[:command] || "search",
+          "from" => format_time(params[:time_min]),
+          "to" => format_time(params[:time_max]),
+          "calendar" => params[:calendar],
+          "calendar_ids" => Array(params[:calendar_ids]),
+          "description" => params[:description],
+          "format" => params[:format] || "json",
+          "locale" => params[:locale] || Locale.current_locale,
+          "group_by" => params[:group_by],
+          "group_by_option" => blank_to_nil(params[:group_by_option]),
+          "from_option" => blank_to_nil(params[:from_option]),
+          "to_option" => blank_to_nil(params[:to_option]),
+          "in_option" => blank_to_nil(params[:in_option])
+        }
+
+        if params[:use_mock]
+          out["use_mock"] = true
+          out["mock_calendar"] = params[:mock_calendar]
+          out["mock_template"] = params[:mock_template]
+          out["mock_seed"] = params[:mock_seed]
+        end
+
+        out
+      end
+
+      def build_info(params)
+        totals = params[:totals] || {}
+        total_minutes = totals[:total_minutes].to_f
+        info = {
+          "events_found" => totals[:event_count].to_i,
+          "from" => format_time(params[:time_min]),
+          "to" => format_time(params[:time_max]),
+          "total_hours" => (total_minutes / 60.0).round(2),
+          "total_working_days" => totals[:working_days].to_f
+        }
+        info["mock_seed"] = params[:mock_seed] if params[:use_mock] && !params[:mock_seed].nil?
+        info["cache"] = params[:cache_status] if params[:cache_status]
+        info
+      end
+
+      def build_groups(params)
+        type = params[:group_by].to_s
+        Array(params[:groups]).map do |group|
+          {
+            "type" => type,
+            "key" => group[:key],
+            "index" => group[:index],
+            "total_hours" => group[:hours],
+            "total_working_days" => group[:working_days],
+            "events_found" => group[:event_count] || Array(group[:events]).size,
+            "items" => Array(group[:events]).map { |ev| serialize_event(ev) }
+          }.tap do |g|
+            if type == "string"
+              g["string"] = group[:string] || group[:key]
+            else
+              g["from"] = format_time(group[:start_at])
+              g["to"] = format_time(group[:end_at])
+            end
+            g["month_name"] = group[:month_name] if group[:month_name]
+          end
+        end
+      end
+
+      # Shape inspired by Google Calendar API event resources.
+      def serialize_event(ev)
+        raw = ev[:raw]
+        payload = {
+          "summary" => ev[:summary],
+          "description" => ev[:description],
+          "start" => boundary_hash(ev[:start_at], all_day: ev[:all_day]),
+          "end" => boundary_hash(ev[:end_at], all_day: ev[:all_day]),
+          "calendarId" => ev[:calendar_id],
+          "calendarSummary" => ev[:calendar_name]
+        }
+
+        if raw
+          payload["id"] = raw.id if raw.respond_to?(:id) && raw.id
+          payload["status"] = raw.status if raw.respond_to?(:status) && raw.status
+          payload["htmlLink"] = raw.html_link if raw.respond_to?(:html_link) && raw.html_link
+          payload["created"] = format_time(raw.created) if raw.respond_to?(:created) && raw.created
+          payload["updated"] = format_time(raw.updated) if raw.respond_to?(:updated) && raw.updated
+          payload["location"] = raw.location if raw.respond_to?(:location) && raw.location
+          payload["iCalUID"] = raw.i_cal_uid if raw.respond_to?(:i_cal_uid) && raw.i_cal_uid
+        end
+
+        payload.compact
+      end
+
+      def boundary_hash(time, all_day:)
+        return nil if time.nil?
+
+        if all_day
+          { "date" => time.to_date.iso8601 }
+        else
+          { "dateTime" => format_time(time) }
+        end
+      end
+
+      # Google Calendar-style ISO-8601 datetime, e.g. 2026-07-29T14:41:00+00:00
+      def format_time(value)
+        return nil if value.nil?
+        return value.iso8601 if value.respond_to?(:iso8601)
+
+        value.to_s
+      end
+
+      def blank_to_nil(value)
+        str = value.to_s
+        str.empty? ? nil : str
+      end
+    end
+  end
+end

data/lib/flycal/pipeline/params.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Flycal
+  module Pipeline
+    # Mutable bag of CLI + derived parameters passed through the pipeline.
+    class Params
+      def initialize(initial = {})
+        @data = {}
+        initial.each { |k, v| self[k] = v }
+      end
+
+      def [](key)
+        @data[key.to_sym]
+      end
+
+      def []=(key, value)
+        @data[key.to_sym] = value
+      end
+
+      def fetch(key, default = nil, &block)
+        if block
+          @data.fetch(key.to_sym, &block)
+        else
+          @data.fetch(key.to_sym, default)
+        end
+      end
+
+      def key?(key)
+        @data.key?(key.to_sym)
+      end
+
+      def merge!(other)
+        other.each { |k, v| self[k] = v }
+        self
+      end
+
+      def to_h
+        @data.dup
+      end
+
+      def each(&block)
+        @data.each(&block)
+      end
+    end
+  end
+end

data/lib/flycal/pipeline/renderer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Flycal
+  module Pipeline
+    # Third pipeline layer: render aggregated results to a chosen format.
+    class Renderer
+      FORMATS = {
+        "text" => "Flycal::Pipeline::TextRenderer",
+        "json" => "Flycal::Pipeline::JsonRenderer"
+      }.freeze
+
+      def self.for(format)
+        key = format.to_s.strip.downcase
+        key = "text" if key.empty?
+        class_name = FORMATS[key]
+        raise Flycal::Error, "Unsupported format #{format.inspect}. Available: #{FORMATS.keys.join(", ")}" unless class_name
+
+        Object.const_get(class_name).new
+      end
+
+      # @return [String] rendered output
+      def render(params)
+        raise NotImplementedError, "#{self.class}#render must be implemented"
+      end
+    end
+  end
+end