mdlogbook 0.1.0

data/lib/mdlogbook/formatter/heatmap.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "unicode_plot"
+
+module Mdlogbook
+  module Formatter
+    # Renders a day-of-week × hour-of-day density plot showing work patterns.
+    #
+    # Each time entry is sampled at regular intervals to produce scatter points,
+    # which are then rendered using {UnicodePlot.densityplot}. The Y axis
+    # represents the day of week (1=Mon … 7=Sun) and the X axis represents the
+    # hour of day.
+    class Heatmap
+      # Sample interval in minutes for generating scatter points from entries.
+      SAMPLE_INTERVAL = 10
+
+      # Height is fixed at 7 rows — one per day of the week.
+      HEIGHT = 7
+
+      # Resolution presets: name → chart width (columns).
+      RESOLUTIONS = {
+        "1h" => 24,
+        "30m" => 48,
+        "15m" => 96
+      }.freeze
+
+      # Default resolution when none is specified.
+      DEFAULT_RESOLUTION = "30m"
+
+      # Day-of-week labels for the legend printed below the chart.
+      DAY_LABELS = %w[Mon Tue Wed Thu Fri Sat Sun].freeze
+
+      # Renders the heatmap for the given result.
+      #
+      # @param result [Parser::Result] Parsed entries (already filtered/merged).
+      # @param io [IO] Output stream.
+      # @param resolution [String, nil] Time resolution: "15m", "30m" (default), or "1h".
+      # @param heatmap_config [Config::HeatmapSettings] Heatmap display settings.
+      # @param range_begin [Date, nil] Start date of the displayed period.
+      # @param range_end [Date, nil] End date of the displayed period.
+      # @return [void]
+      def format_output(result, io = $stdout, resolution: nil, heatmap_config: Config::HeatmapSettings.new(start_hour: Config::DEFAULT_HEATMAP_START_HOUR), range_begin: nil, range_end: nil)
+        start_hour = heatmap_config.start_hour
+        xs, ys = build_points(result, start_hour: start_hour)
+
+        if xs.empty?
+          io.puts "No entries to display."
+          return
+        end
+
+        width = resolve_width(resolution)
+        plot = UnicodePlot.densityplot(
+          xs, ys,
+          title: "Work Hours Heatmap",
+          xlim: [start_hour, start_hour + 24],
+          ylim: [1, 7],
+          width: width,
+          height: HEIGHT
+        )
+        DAY_LABELS.each_with_index do |label, i|
+          plot.annotate_row!(:r, i, label)
+        end
+        plot.render(io)
+        print_summary(io, result, range_begin, range_end)
+      end
+
+      private
+
+      # Generates (hour, weekday) scatter points from all entries.
+      #
+      # Each entry is sampled at {SAMPLE_INTERVAL}-minute steps from start to end.
+      # The weekday Y value is inverted so Monday=7 (top) and Sunday=1 (bottom).
+      # Hours before +start_hour+ are wrapped by adding 24 so they appear on the
+      # right side of the chart.
+      #
+      # @param result [Parser::Result]
+      # @param start_hour [Integer] Hour at which the X axis begins.
+      # @return [Array(Array<Float>, Array<Float>)] xs (hours) and ys (weekdays).
+      def build_points(result, start_hour:)
+        xs = []
+        ys = []
+
+        result.each_date do |date|
+          iso_wday = (date.wday == 0) ? 7 : date.wday
+          wday_y = (8 - iso_wday).to_f
+
+          result.entries_on(date).each do |entry|
+            start_min = entry.start_minutes
+            end_min = entry.end_minutes
+            min = start_min
+
+            while min < end_min
+              hour = min / 60.0
+              hour += 24 if hour < start_hour
+              xs << hour
+              ys << wday_y
+              min += SAMPLE_INTERVAL
+            end
+          end
+        end
+
+        [xs, ys]
+      end
+
+      # Prints the period and summary statistics.
+      # @param io [IO]
+      # @param result [Parser::Result]
+      # @param range_begin [Date, nil]
+      # @param range_end [Date, nil]
+      # @return [void]
+      def print_summary(io, result, range_begin, range_end)
+        total = 0.0
+        days_with_entries = 0
+        result.each_date do |date|
+          daily = result.entries_on(date).sum(&:time)
+          next unless daily > 0
+
+          total += daily
+          days_with_entries += 1
+        end
+
+        parts = []
+        parts << "#{range_begin}~#{range_end}" if range_begin && range_end
+        parts << format("%.1fh total", total)
+        parts << format("%.1fh/day avg", total / days_with_entries) if days_with_entries > 0
+        io.puts parts.join("  ")
+      end
+
+      # Resolves chart width from the resolution name.
+      # @param resolution [String, nil]
+      # @return [Integer]
+      # @raise [ArgumentError] If the resolution name is unknown.
+      def resolve_width(resolution)
+        resolution ||= DEFAULT_RESOLUTION
+        RESOLUTIONS.fetch(resolution) do
+          raise ArgumentError,
+            "unknown --heatmap resolution: #{resolution.inspect} (use #{RESOLUTIONS.keys.join(", ")})"
+        end
+      end
+    end
+  end
+end

data/lib/mdlogbook/formatter/line_chart.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "date"
+require "io/console"
+require "unicode_plot"
+
+module Mdlogbook
+  module Formatter
+    # Renders a cumulative-hours line chart for a single calendar month.
+    #
+    # Three series are drawn (bottom layer to top layer):
+    #   * Weekday target — step-wise projection that advances only on working days (Mon–Fri).
+    #   * Linear target — straight-line projection of the monthly target.
+    #   * Actual — cumulative hours logged per calendar day (drawn last, highest priority).
+    #
+    # Below the chart, remaining-hours stats are printed (same format as {Calendar}).
+    class LineChart
+      include RemainingHelper
+      include ChartSeriesBuilder
+
+      SIZES = {
+        "small" => {width: 60, height: 15},
+        "medium" => {width: 80, height: 20},
+        "large" => {width: 100, height: 25},
+        "max" => nil
+      }.freeze
+
+      SIZE_ALIASES = {"s" => "small", "m" => "medium", "l" => "large", "x" => "max"}.freeze
+
+      # Approximate extra terminal columns unicode_plot needs beyond the chart width
+      # (axis labels on the left + legend text on the right).
+      OVERHEAD = 30
+
+      # Renders a chart and stats for a single month.
+      #
+      # @param result [Parser::Result] Entries filtered to the given month.
+      # @param settings [WorkThresholds]
+      # @param io [IO] Output stream.
+      # @param spec [PeriodSpec] The month being visualised (must be month_unit?).
+      # @param size [String, nil] Chart size: "small", "medium", "large", "max", or nil (auto).
+      # @param today [Date] Reference date for remaining-hours calculation.
+      # @param line_chart_config [Config::VisualSettings, nil] Series visibility and color overrides.
+      # @return [void]
+      def format_output(result, settings, io = $stdout, spec:, size: nil, today: Date.today, line_chart_config: nil, **_options)
+        vc = line_chart_config || Config::VisualSettings.new
+        first_day = spec.start_date
+        last_day = spec.end_date
+        n_days = (last_day - first_day).to_i + 1
+
+        xs = (1..n_days).map(&:to_f)
+
+        y_actual = build_actual(result, first_day, n_days)
+        has_target = settings.target_hours?
+        y_linear = has_target ? build_linear_target(settings.target_hours, n_days) : nil
+        y_weekday = has_target ? build_weekday_target(settings, first_day, n_days) : nil
+
+        actual_max = y_actual.max || 0.0
+        y_max = has_target ? [settings.target_hours, actual_max].max : actual_max
+
+        dims = chart_dimensions(size, io)
+        title = first_day.strftime("%Y-%m")
+        base_opts = {
+          title: title, xlabel: "Day", ylabel: "Hours",
+          xlim: [1, n_days], ylim: [0, y_max],
+          width: dims[:width], height: dims[:height]
+        }
+
+        # Draw series back-to-front: Today (bottom) → Weekday → Linear → Actual (top).
+        in_current_month = today.year == first_day.year && today.month == first_day.month
+        show_today = vc.show_today && in_current_month
+
+        # When no target is set, force-hide target lines regardless of visual config.
+        effective_vc = if has_target
+          vc
+        else
+          Config::VisualSettings.new(show_today: vc.show_today, show_weekday: false,
+            show_linear: false, colors: vc.colors)
+        end
+
+        # The first lineplot call initialises the chart. Use whichever visible series
+        # is the bottom-most, or fall back to a transparent "anchor" series.
+        first_series, *rest_series = build_series(xs, y_actual, y_linear, y_weekday, y_max,
+          today, show_today, effective_vc)
+        plot = UnicodePlot.lineplot(first_series[:x], first_series[:y],
+          name: first_series[:name], **base_opts, **color_opt(first_series[:name], vc))
+        rest_series.each do |s|
+          UnicodePlot.lineplot!(plot, s[:x], s[:y], name: s[:name], **color_opt(s[:name], vc))
+        end
+        plot.render(io)
+
+        if has_target
+          total = y_actual.last || 0.0
+          print_remaining(io, total, first_day, settings, today)
+        end
+      end
+
+      private
+
+      # Builds the ordered list of series to render (bottom to top).
+      # @return [Array<Hash>] Each element has +:name+, +:x+, +:y+.
+      def build_series(xs, y_actual, y_linear, y_weekday, y_max, today, show_today, vc)
+        series = []
+        if show_today
+          x = today.day.to_f
+          series << {name: "Today", x: [x, x], y: [0.0, y_max.to_f]}
+        end
+        series << {name: "Weekday target", x: xs, y: y_weekday} if vc.show_weekday
+        series << {name: "Linear target", x: xs, y: y_linear} if vc.show_linear
+        series << {name: "Actual", x: xs, y: y_actual}
+        series
+      end
+
+      # Returns a color keyword argument hash for the given series name, or {} if not set.
+      # @param name [String]
+      # @param vc [Config::VisualSettings]
+      # @return [Hash]
+      def color_opt(name, vc)
+        key = name.downcase.split.first  # "Actual"→"actual", "Linear target"→"linear", etc.
+        color = vc.colors[key]
+        color ? {color: color} : {}
+      end
+
+      # Resolves chart dimensions for the given size name (or auto-detects from terminal).
+      # @param size [String, nil] Size name or nil for auto-detection.
+      # @param io [IO] Output stream used to query terminal width.
+      # @return [Hash{width: Integer, height: Integer}]
+      def chart_dimensions(size, io)
+        size = SIZE_ALIASES.fetch(size, size)
+
+        if size && size != "max"
+          return SIZES.fetch(size) { raise ArgumentError, "unknown --line-chart size: #{size.inspect} (use small/s, medium/m, large/l, or max/x)" }
+        end
+
+        term_cols = terminal_width(io)
+
+        if term_cols
+          # Auto or max: fill the terminal width.
+          width = [term_cols - OVERHEAD, 60].max
+          height = [width / 4, 35].min
+          {width: width, height: height}
+        elsif size == "max"
+          {width: 140, height: 35}
+        else
+          # Auto but not a TTY: fall back to medium.
+          SIZES["medium"]
+        end
+      end
+
+      def terminal_width(io)
+        io.winsize[1]
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/mdlogbook/formatter/simple.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  module Formatter
+    # Formats logbook entries as a flat list with a total summary line.
+    class Simple < Base
+      ROW_FORMAT = "%s%10s %11s %6.2f  %s%s\n"
+
+      # Writes all entries and a total summary to +io+.
+      # @param result [Parser::Result]
+      # @param settings [WorkThresholds]
+      # @param io [IO] Output stream (default: $stdout).
+      # @return [void]
+      def format_output(result, settings, io = $stdout, **_options)
+        sum = 0.0
+        prev_date = nil
+        colors = row_colors.dup
+
+        result.each_date do |date|
+          unless date == prev_date
+            prev_date = date
+            color = colors.first
+            colors.rotate!
+          end
+
+          result.entries_on(date).sort_by(&:range_str).each do |entry|
+            sum += entry.time
+            io.printf ROW_FORMAT, color, date, entry.range_str, entry.time, entry.job, color_reset
+          end
+        end
+
+        io.puts "-" * 78
+        summary = if settings.target_hours?
+          Kernel.format("(%.1f day, %.1f%% of target)", sum / 8, sum * 100 / settings.target_hours)
+        else
+          Kernel.format("(%.1f day)", sum / 8)
+        end
+        io.printf ROW_FORMAT, "", "", "Total:", sum, summary, ""
+      end
+    end
+  end
+end

data/lib/mdlogbook/option_def.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  # Describes a single CLI option with metadata for OptionParser and shell completion.
+  #
+  # @!attribute [r] short
+  #   @return [String, nil] Short option flag (e.g. "-e").
+  # @!attribute [r] long
+  #   @return [String] Long option flag (e.g. "--edit").
+  # @!attribute [r] arg_name
+  #   @return [String, nil] Argument placeholder name (e.g. "SIZE"), nil for flags.
+  # @!attribute [r] arg_optional
+  #   @return [Boolean] Whether the argument is optional (e.g. --line-chart[=SIZE]).
+  # @!attribute [r] description
+  #   @return [String] Help text for the option.
+  # @!attribute [r] type
+  #   @return [Class, nil] Argument type for OptionParser (String, Numeric, Regexp, nil).
+  # @!attribute [r] values
+  #   @return [Array<String>, nil] Allowed values for shell completion.
+  # @!attribute [r] completion
+  #   @return [Symbol, String, nil] Completion type (:file, :directory) or shell command string.
+  OptionDef = Data.define(:short, :long, :arg_name, :arg_optional, :description, :type, :values, :completion) do
+    # @param long [String] Long option flag (required).
+    # @param description [String] Help text (required).
+    # @param short [String, nil] Short option flag.
+    # @param arg_name [String, nil] Argument placeholder name.
+    # @param arg_optional [Boolean] Whether the argument is optional.
+    # @param type [Class, nil] Argument type for OptionParser.
+    # @param values [Array<String>, nil] Allowed values for shell completion.
+    # @param completion [Symbol, String, nil] Completion type or shell command.
+    def initialize(long:, description:, short: nil, arg_name: nil, arg_optional: false, type: nil, values: nil,
+      completion: nil)
+      super(short: short, long: long, arg_name: arg_name, arg_optional: arg_optional, description: description,
+            type: type, values: values, completion: completion)
+    end
+
+    # @return [Boolean] Whether this option is a flag (takes no argument).
+    def flag?
+      arg_name.nil?
+    end
+
+    # @return [String] The option name without the leading "--".
+    def long_name
+      long.delete_prefix("--")
+    end
+
+    # Generates the argument list for OptionParser#on.
+    #
+    # @return [Array] Arguments suitable for OptionParser#on.
+    def optparse_args
+      args = []
+      args << short if short
+      args << optparse_long_flag
+      args << type if type
+      args << description
+      args
+    end
+
+    private
+
+    # @return [String] Long flag formatted for OptionParser.
+    def optparse_long_flag
+      return long unless arg_name
+
+      arg_optional ? "#{long}[=#{arg_name}]" : "#{long}=#{arg_name}"
+    end
+  end
+end

data/lib/mdlogbook/option_registry.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Mdlogbook
+  # Collects CLI option definitions and generates OptionParser instances and shell completion scripts.
+  class OptionRegistry
+    # @return [void]
+    def initialize
+      @entries = []
+    end
+
+    # Adds a separator line for help text grouping.
+    #
+    # @param text [String] Separator label.
+    # @return [void]
+    def separator(text)
+      @entries << text
+    end
+
+    # Registers an option definition.
+    #
+    # @param kwargs [Hash] Keyword arguments forwarded to {OptionDef}.
+    # @param action [Proc] Block executed when the option is parsed.
+    # @return [OptionDef] The registered definition.
+    def option(**kwargs, &action)
+      defn = OptionDef.new(**kwargs)
+      @entries << [defn, action]
+      defn
+    end
+
+    # Returns only the {OptionDef} entries (excludes separators).
+    #
+    # @return [Array<OptionDef>]
+    def definitions
+      @entries.filter_map { |e| e.is_a?(Array) ? e[0] : nil }
+    end
+
+    # Builds an OptionParser from the registered definitions.
+    #
+    # @param banner [String] Usage banner text.
+    # @return [OptionParser]
+    def to_option_parser(banner:)
+      op = OptionParser.new
+      op.banner = banner
+      @entries.each do |entry|
+        case entry
+        when String
+          op.separator ""
+          op.separator entry
+        when Array
+          defn, action = entry
+          op.on(*defn.optparse_args, &action)
+        end
+      end
+      op
+    end
+
+    # Generates a bash completion script.
+    #
+    # @return [String]
+    def completion_bash
+      all_flags = definitions.flat_map { |d| [d.short, d.long].compact }
+      # Collect all options that have completable values/commands, regardless of arg_optional.
+      # bash COMP_WORDBREAKS includes "=" by default, so --opt=<TAB> splits into prev="--opt" cur="",
+      # making the prev case the primary completion mechanism for both required and optional args.
+      opts_completable = definitions.select { |d| d.arg_name && (d.values || d.completion) }
+
+      lines = []
+      lines << "_mlb() {"
+      lines << "    local cur prev"
+      lines << '    cur="${COMP_WORDS[COMP_CWORD]}"'
+      lines << '    prev="${COMP_WORDS[COMP_CWORD-1]}"'
+      lines << ""
+
+      unless opts_completable.empty?
+        lines << '    case "$prev" in'
+        opts_completable.each do |d|
+          # For optional-arg options, exclude short form from prev case.
+          # "-l small" is invalid (optional args require "=" like --line-chart=small or -lsmall).
+          # Required-arg options like -p/--project accept both "-p foo" and "--project=foo".
+          names = if d.arg_optional
+            d.long
+          else
+            [d.short, d.long].compact.join("|")
+          end
+          lines << "        #{names})"
+          lines << "            #{bash_compgen(d)}"
+          lines << "            return"
+          lines << "            ;;"
+        end
+        lines << "    esac"
+        lines << ""
+      end
+
+      lines << '    if [[ "$cur" == -* ]]; then'
+      lines << "        COMPREPLY=( $(compgen -W \"#{all_flags.join(" ")}\" -- \"$cur\") )"
+      lines << "    fi"
+      lines << "}"
+      lines << "complete -o default -F _mlb mlb"
+      lines.join("\n") + "\n"
+    end
+
+    # Generates a zsh completion script.
+    #
+    # @return [String]
+    def completion_zsh
+      lines = []
+      lines << "#compdef mlb"
+      lines << ""
+      lines << "_mlb() {"
+      lines << "    _arguments -s \\"
+
+      specs = definitions.flat_map { |d| zsh_specs(d) }
+      specs.each_with_index do |spec, i|
+        continuation = (i < specs.size - 1) ? " \\" : ""
+        lines << "        #{spec}#{continuation}"
+      end
+
+      lines << "}"
+      lines << ""
+      lines << "_mlb \"$@\""
+      lines.join("\n") + "\n"
+    end
+
+    private
+
+    # @param d [OptionDef]
+    # @return [String] compgen expression for bash completion.
+    def bash_compgen(d)
+      if d.values
+        "COMPREPLY=( $(compgen -W \"#{d.values.join(" ")}\" -- \"$cur\") )"
+      elsif d.completion == :file
+        "COMPREPLY=( $(compgen -f -- \"$cur\") )"
+      elsif d.completion == :directory
+        "COMPREPLY=( $(compgen -d -- \"$cur\") )"
+      elsif d.completion.is_a?(String)
+        "COMPREPLY=( $(compgen -W \"#{d.completion}\" -- \"$cur\") )"
+      else
+        ""
+      end
+    end
+
+    # @param d [OptionDef]
+    # @return [Array<String>] _arguments spec(s) for zsh completion.
+    def zsh_specs(d)
+      desc = zsh_escape_desc(d.description)
+
+      if d.short && d.arg_name && d.arg_optional
+        # Split optional-arg options with short aliases into two specs.
+        # Short form is a plain flag (-l); long form gets value completion (--line-chart=).
+        # This prevents zsh from suggesting values as a separate word after -l.
+        exclusion = "'(#{d.short} #{d.long})'"
+        arg_part = zsh_arg_part(d)
+        [
+          "#{exclusion}'#{d.short}[#{desc}]'",
+          "#{exclusion}'#{d.long}=[#{desc}]#{arg_part}'"
+        ]
+      elsif d.short
+        exclusion = "'(#{d.short} #{d.long})'"
+        if d.arg_name
+          arg_part = zsh_arg_part(d)
+          ["#{exclusion}{#{d.short},#{d.long}=}'[#{desc}]#{arg_part}'"]
+        else
+          ["#{exclusion}{#{d.short},#{d.long}}'[#{desc}]'"]
+        end
+      elsif d.arg_name
+        arg_part = zsh_arg_part(d)
+        ["'#{d.long}=[#{desc}]#{arg_part}'"]
+      else
+        ["'#{d.long}[#{desc}]'"]
+      end
+    end
+
+    # @param desc [String]
+    # @return [String] description with zsh special characters escaped.
+    def zsh_escape_desc(desc)
+      desc.gsub("'", "'\\\\''").gsub("[", "\\[").gsub("]", "\\]")
+    end
+
+    # @param d [OptionDef]
+    # @return [String] argument part of zsh _arguments spec.
+    def zsh_arg_part(d)
+      colon = d.arg_optional ? "::" : ":"
+      action = zsh_action(d)
+      "#{colon}#{d.arg_name.downcase}:#{action}"
+    end
+
+    # @param d [OptionDef]
+    # @return [String] zsh completion action.
+    def zsh_action(d)
+      if d.values
+        "(#{d.values.join(" ")})"
+      elsif d.completion == :file
+        "_files"
+      elsif d.completion == :directory
+        "_files -/"
+      elsif d.completion.is_a?(String)
+        "(#{d.completion})"
+      else
+        ""
+      end
+    end
+  end
+end

data/lib/mdlogbook/overlap_checker.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  # Detects overlapping time entries within a {Parser::Result}.
+  #
+  # Two entries on the same date overlap when the first entry's end time is
+  # strictly after the second entry's start time (adjacent entries do not count).
+  class OverlapChecker
+    # Immutable value object representing a pair of overlapping entries.
+    #
+    # @!attribute [r] date
+    #   @return [Date]
+    # @!attribute [r] entry_a
+    #   @return [Parser::Entry] The earlier-starting entry.
+    # @!attribute [r] entry_b
+    #   @return [Parser::Entry] The entry that overlaps with +entry_a+.
+    Overlap = Data.define(:date, :entry_a, :entry_b)
+
+    # Returns all overlapping pairs found in +result+.
+    # @param result [Parser::Result]
+    # @return [Array<Overlap>]
+    def check(result)
+      overlaps = []
+      result.each_date do |date|
+        sorted = result.entries_on(date).sort_by(&:start_minutes)
+        sorted.each_cons(2) do |a, b|
+          overlaps << Overlap.new(date: date, entry_a: a, entry_b: b) if a.end_minutes > b.start_minutes
+        end
+      end
+      overlaps
+    end
+
+    # Formats an {Overlap} as a human-readable string.
+    # @param overlap [Overlap]
+    # @return [String]
+    def format_message(overlap)
+      a = overlap.entry_a
+      b = overlap.entry_b
+      "#{overlap.date} #{a.range_str} (line #{a.line_number}) overlaps #{b.range_str} (line #{b.line_number})"
+    end
+  end
+end