mdlogbook 0.1.0

data/lib/mdlogbook/formatter/base.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  module Formatter
+    # Shared template expansion for preamble/postamble text.
+    module TemplateHelper
+      private
+
+      # Substitutes +{range_begin}+ and +{range_end}+ in +text+.
+      # @param text [String]
+      # @param range_begin [Date, nil]
+      # @param range_end [Date, nil]
+      # @return [String]
+      def expand_range(text, range_begin, range_end)
+        text
+          .gsub("{range_begin}", range_begin&.to_s || "")
+          .gsub("{range_end}", range_end&.to_s || "")
+      end
+    end
+
+    # Shared helpers for remaining-hours display and month-length calculation.
+    module RemainingHelper
+      private
+
+      # Returns the number of days in the month containing +date+.
+      # @param date [Date]
+      # @return [Integer]
+      def days_of_month(date)
+        day1 = Date.new(date.year, date.month, 1)
+        (day1.next_month - day1).to_i
+      end
+
+      # Prints remaining-hours stats when +today+ is in the same month as +first_day+.
+      # @param io [IO]
+      # @param total [Float] Total hours logged so far.
+      # @param first_day [Date] First day of the month.
+      # @param settings [WorkThresholds]
+      # @param today [Date]
+      # @return [void]
+      def print_remaining(io, total, first_day, settings, today)
+        return unless today.year == first_day.year && today.month == first_day.month
+
+        n_days = days_of_month(today)
+        working_day_ratio = settings.working_days_per_month.to_f / n_days
+        rest_days = n_days - today.day + 1
+        remaining = settings.target_hours - total
+
+        io.puts
+        if remaining > 0
+          if rest_days > 0
+            io.printf(
+              "Remaining to meet target: %.2f h/weekday (%.2f h/day, total %.2f h)\n",
+              remaining / (rest_days * working_day_ratio),
+              remaining / rest_days,
+              remaining
+            )
+          else
+            io.printf "Remaining to meet target: total %.2f h\n", remaining
+          end
+        else
+          io.puts "Monthly target already met!"
+        end
+      end
+    end
+
+    # Shared helpers for anonymize formatters to check passthrough rules.
+    module PassthroughHelper
+      private
+
+      # Returns true when +job+ matches any passthrough rule (exact string or /pattern/).
+      # @param job [String]
+      # @param passthrough [Array<String>]
+      # @return [Boolean]
+      def passthrough?(job, passthrough)
+        passthrough.any? do |rule|
+          if rule.start_with?("/") && rule.end_with?("/")
+            Regexp.new(rule[1..-2]).match?(job)
+          else
+            job == rule
+          end
+        end
+      end
+    end
+
+    # Abstract base class for output formatters.
+    # Subclasses must implement {#format_output}.
+    class Base
+      include TemplateHelper
+
+      # Symbols mapped to their plain-text display signs.
+      PLAIN_SIGNS = {
+        excellent: "◎",
+        on_track: "○",
+        below: "△",
+        poor: "×"
+      }.freeze
+
+      # @!attribute [r] color_reset
+      #   @return [String] ANSI reset escape sequence, or empty string when color is disabled.
+      # @!attribute [r] row_colors
+      #   @return [Array<String>] ANSI color codes cycled per date row, or a single empty string.
+      # @!attribute [r] calendar_signs
+      #   @return [Hash{Symbol => String}] Sign characters (optionally colored) keyed by rating.
+      # @!attribute [r] calendar_colors
+      #   @return [Hash{Symbol => String}] ANSI color codes keyed by rating symbol.
+      attr_reader :color_reset, :row_colors, :calendar_signs, :calendar_colors
+
+      # @param color [Boolean] Whether to emit ANSI color codes (default: terminal detection).
+      def initialize(color: $stdout.tty?)
+        if color
+          @color_reset = "\e[0m"
+          @row_colors = [218, 107, 75].map { |n| "\e[38;5;#{n}m" }.freeze
+          @calendar_colors = {
+            excellent: 40, on_track: 45, below: 220, poor: 196, zero: 240
+          }.transform_values { |n| "\e[38;5;#{n}m" }.freeze
+          @calendar_signs = PLAIN_SIGNS.each_with_object({}) { |(key, sign), hash|
+            hash[key] = "#{@calendar_colors[key]}#{sign}#{@color_reset}"
+          }.freeze
+        else
+          @color_reset = ""
+          @row_colors = [""].freeze
+          @calendar_colors = Hash.new("")
+          @calendar_signs = PLAIN_SIGNS
+        end
+      end
+
+      # Formats and writes output for the given result.
+      # Subclasses must override this method.
+      # @param _result [Parser::Result]
+      # @param _settings [WorkThresholds]
+      # @param _io [IO]
+      # @raise [NotImplementedError] Always, unless overridden by a subclass.
+      def format_output(_result, _settings, _io, **_options)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/mdlogbook/formatter/calendar.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Mdlogbook
+  module Formatter
+    # Formats logbook entries as a weekly calendar grid with daily totals and ratings.
+    class Calendar < Base
+      include RemainingHelper
+
+      # Writes a calendar grid for the given result to +io+.
+      # @param result [Parser::Result]
+      # @param settings [WorkThresholds]
+      # @param io [IO] Output stream (default: $stdout).
+      # @param today [Date] Reference date used to calculate remaining hours (default: Date.today).
+      # @param debug [Boolean] When true, prints cumulative diagnostics beside each day sign.
+      # @return [void]
+      def format_output(result, settings, io = $stdout, today: Date.today, debug: false, **_options)
+        if result.dates.empty?
+          print_empty(io)
+          return
+        end
+
+        d_beg = result.dates.first
+        d_end = result.dates.last
+        d_range = d_beg..d_end
+        c_beg = d_beg - (d_beg.wday - 1) % 7
+        c_end = d_end - (d_end.wday - 1) % 7
+
+        print_header(io)
+
+        w_ts = Array.new(7) { [] }
+        sum = 0.0
+        date = c_beg
+
+        until date > c_end
+          ts = []
+          io.print date.strftime("%m/%d ")
+
+          7.times do |idx|
+            d = date + idx
+            day_total = result.entries_on(d).sum(&:time)
+
+            unless d_range.cover?(d)
+              io.print "|   -    "
+              next
+            end
+
+            ts << day_total
+            w_ts[idx] << day_total
+            sum += day_total
+
+            sign = if settings.target_hours?
+              sign_key = compute_sign(day_total, sum, d, d_beg, settings)
+              s = calendar_signs[sign_key]
+              if debug
+                days = (d - d_beg).to_i + 1
+                working_day_ratio = settings.working_days_per_month.to_f / days_of_month(d)
+                working_days = days * working_day_ratio
+                s += Kernel.format("<%.1f %d %.1f %.1f>", sum, days, working_days, sum / working_days)
+              end
+              s
+            else
+              " "
+            end
+
+            color = day_total.zero? ? calendar_colors[:zero] : ""
+            io.printf "| %s%5.2f%s%s ", color, day_total, color_reset, sign
+          end
+
+          week_sum = ts.sum
+          avg = ts.empty? ? 0.0 : week_sum / ts.size
+          io.printf "| %6.2f (%5.2f)\n", week_sum, avg
+          date += 7
+        end
+
+        print_separator(io)
+        print_sum_row(io, w_ts)
+        print_avg_row(io, w_ts)
+        print_remaining(io, sum, d_beg, settings, today) if settings.target_hours?
+      end
+
+      private
+
+      def compute_sign(day_total, sum, date, d_beg, settings)
+        days = (date - d_beg).to_i + 1
+        working_day_ratio = settings.working_days_per_month.to_f / days_of_month(date)
+        working_days = days * working_day_ratio
+        working_days_avg = sum / working_days
+
+        if day_total >= settings.high_threshold || working_days_avg >= settings.high_threshold
+          :excellent
+        elsif day_total >= settings.daily_target || working_days_avg >= settings.daily_target
+          :on_track
+        elsif day_total < settings.low_threshold
+          :poor
+        else
+          :below
+        end
+      end
+
+      def print_header(io)
+        header = "      " + %w[Mon Tue Wed Thu Fri Sat Sun].map { |s| "|  #{s}   " }.join + "|    sum ( avg )"
+        separator = "----- " + "| ------ " * 7 + "| -------------- "
+        io.puts header
+        io.puts separator
+      end
+
+      def print_separator(io)
+        io.puts "----- " + "| ------ " * 7 + "| -------------- "
+      end
+
+      def print_sum_row(io, w_ts)
+        all = []
+        io.print "  sum "
+        w_ts.each do |ts|
+          all.concat(ts)
+          io.printf "| %5.2f  ", ts.sum
+        end
+        total = all.sum
+        if all.empty?
+          io.printf "| %6.2f (  -  )\n", total
+        else
+          io.printf "| %6.2f (%5.2f)\n", total, total / all.size
+        end
+      end
+
+      def print_avg_row(io, w_ts)
+        io.print "  avg "
+        w_ts.each do |ts|
+          if ts.empty?
+            io.print "|   -    "
+          else
+            io.printf "| %5.2f  ", ts.sum / ts.size
+          end
+        end
+        io.puts
+      end
+
+      def print_empty(io)
+        print_header(io)
+        print_separator(io)
+
+        io.print "  sum "
+        7.times { io.print "|   -    " }
+        io.printf "| %6.2f (  -  )\n", 0.0
+
+        io.print "  avg "
+        7.times { io.print "|   -    " }
+        io.puts
+      end
+    end
+  end
+end

data/lib/mdlogbook/formatter/chart_series_builder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  module Formatter
+    # Shared methods for building cumulative chart series used by {LineChart} and {Grid}.
+    module ChartSeriesBuilder
+      private
+
+      # Builds cumulative actual hours for each calendar day.
+      # @param result [Parser::Result]
+      # @param first_day [Date]
+      # @param n_days [Integer]
+      # @return [Array<Float>]
+      def build_actual(result, first_day, n_days)
+        cumulative = 0.0
+        (0...n_days).map do |i|
+          date = first_day + i
+          cumulative += result.entries_on(date).sum(&:time)
+          cumulative
+        end
+      end
+
+      # Builds a straight-line target: day_index * (target / n_days).
+      # @param target_hours [Numeric]
+      # @param n_days [Integer]
+      # @return [Array<Float>]
+      def build_linear_target(target_hours, n_days)
+        daily = target_hours.to_f / n_days
+        (1..n_days).map { |i| i * daily }
+      end
+
+      # Builds a step-wise target that accumulates only on Mon-Fri.
+      # @param settings [WorkThresholds]
+      # @param first_day [Date]
+      # @param n_days [Integer]
+      # @return [Array<Float>]
+      def build_weekday_target(settings, first_day, n_days)
+        working_days_in_month = (0...n_days).count { |i| working_day?(first_day + i) }
+        return Array.new(n_days, 0.0) if working_days_in_month.zero?
+
+        daily = settings.target_hours.to_f / working_days_in_month
+        cumulative = 0.0
+        (0...n_days).map do |i|
+          cumulative += daily if working_day?(first_day + i)
+          cumulative
+        end
+      end
+
+      # Returns true when the date is a weekday (Mon-Fri).
+      # @param date [Date]
+      # @return [Boolean]
+      def working_day?(date)
+        date.wday.between?(1, 5)
+      end
+    end
+  end
+end

data/lib/mdlogbook/formatter/extract.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  module Formatter
+    # Outputs raw logbook content for a date range, suitable for AI summarization.
+    #
+    # Unlike other formatters, this class takes a {RawExtractor::Result} instead of
+    # a {Parser::Result}, preserving all lines (including free-form notes).
+    class Extract
+      include TemplateHelper
+
+      # Writes raw logbook content to +io+.
+      #
+      # @param raw_result [RawExtractor::Result]
+      # @param io [IO] Output stream (default: $stdout).
+      # @param extract_config [Config::ExtractSettings, nil]
+      # @param range_begin [Date, nil] Start of the output period for template substitution.
+      # @param range_end [Date, nil] End of the output period for template substitution.
+      # @return [void]
+      def format_output(raw_result, io = $stdout, extract_config: nil, range_begin: nil, range_end: nil)
+        extract_config ||= Config::ExtractSettings.new(preamble: nil, postamble: nil)
+
+        if extract_config.preamble
+          io.print expand_range(extract_config.preamble, range_begin, range_end)
+        end
+
+        first = true
+        raw_result.each_date do |_date, lines|
+          io.puts unless first
+          first = false
+          lines.each { |line| io.puts line }
+        end
+
+        if extract_config.postamble
+          io.puts
+          io.print expand_range(extract_config.postamble, range_begin, range_end)
+        end
+      end
+    end
+  end
+end

data/lib/mdlogbook/formatter/grid.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "date"
+require "io/console"
+require "unicode_plot"
+
+module Mdlogbook
+  module Formatter
+    # Renders multiple months as a grid of line charts.
+    #
+    # Columns are auto-detected from terminal width:
+    #   * 3 columns when the terminal is wide enough.
+    #   * 2 columns for narrower terminals.
+    #   * 1 column (vertical stack) as a final fallback.
+    #
+    # The legend is shown only on the last chart of the first row (top-right).
+    # Axis labels and remaining-hours stats are not displayed in grid mode.
+    # Each chart shows total hours and daily average below it.
+    class Grid
+      include ChartSeriesBuilder
+
+      # Minimum chart plot-area width before we drop to fewer columns.
+      MIN_CHART_WIDTH = 30
+
+      # Extra terminal columns unicode_plot needs (axis labels + legend text).
+      OVERHEAD = 30
+
+      # Gap between columns.
+      GAP = 2
+
+      # Series type keys used for color lookup when legend names are suppressed.
+      SERIES_TYPES = {
+        today: "today",
+        weekday: "weekday",
+        linear: "linear",
+        actual: "actual"
+      }.freeze
+
+      # Default colors for each series type (matching unicode_plot auto-cycle order).
+      DEFAULT_SERIES_COLORS = {
+        today: :magenta,
+        weekday: :yellow,
+        linear: :cyan,
+        actual: :green
+      }.freeze
+
+      # Renders charts for all given month specs in a grid layout.
+      #
+      # @param results [Array<Array(PeriodSpec, Parser::Result)>] Spec/result pairs, sorted.
+      # @param settings [WorkThresholds]
+      # @param io [IO] Output stream.
+      # @param today [Date] Reference date for the "Today" vertical line.
+      # @param line_chart_config [Config::VisualSettings, nil] Series visibility and color overrides.
+      # @return [void]
+      def format_output(results, settings, io = $stdout, today: Date.today, line_chart_config: nil)
+        vc = line_chart_config || Config::VisualSettings.new
+        term_cols = terminal_width(io)
+        color = tty?(io)
+        cols = detect_columns(term_cols)
+        chart_width = compute_chart_width(term_cols, cols)
+        y_max = unified_y_max(results, settings)
+
+        results.each_slice(cols).with_index do |row_group, row_idx|
+          io.puts if row_idx.positive?
+          last_in_first_row = row_idx.zero? ? row_group.size - 1 : nil
+          rendered = row_group.map.with_index do |(spec, result), col_idx|
+            legend = col_idx == last_in_first_row
+            render_one(result, settings, spec, today, vc, chart_width, y_max,
+              legend: legend, color: color)
+          end
+          paste_side_by_side(rendered, io)
+        end
+      end
+
+      private
+
+      # @return [Integer, nil]
+      def terminal_width(io)
+        io.winsize[1]
+      rescue
+        nil
+      end
+
+      # @return [Boolean]
+      def tty?(io)
+        io.respond_to?(:tty?) && io.tty?
+      end
+
+      # Determines the number of columns (3, 2, or 1) that fit in the terminal.
+      # @param term_cols [Integer, nil]
+      # @return [Integer]
+      def detect_columns(term_cols)
+        return 1 unless term_cols
+
+        [3, 2, 1].find do |n|
+          per_chart = (term_cols - GAP * (n - 1)) / n
+          per_chart - OVERHEAD >= MIN_CHART_WIDTH
+        end || 1
+      end
+
+      # Computes the unicode_plot width parameter for each chart.
+      # @param term_cols [Integer, nil]
+      # @param cols [Integer]
+      # @return [Integer]
+      def compute_chart_width(term_cols, cols)
+        return 60 unless term_cols
+
+        per_chart = (term_cols - GAP * (cols - 1)) / cols
+        [per_chart - OVERHEAD, MIN_CHART_WIDTH].max
+      end
+
+      # Computes a unified Y-axis maximum across all charts.
+      # @return [Float]
+      def unified_y_max(results, settings)
+        target = settings.target_hours? ? settings.target_hours : 0
+        max_actual = results.map do |spec, result|
+          first_day = spec.start_date
+          n_days = (spec.end_date - first_day).to_i + 1
+          build_actual(result, first_day, n_days).last || 0.0
+        end.max || 0.0
+        [target, max_actual].max
+      end
+
+      # Renders a single month chart to an array of lines (including stats footer).
+      # @return [Array<String>]
+      def render_one(result, settings, spec, today, vc, chart_width, y_max, legend:, color:)
+        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
+
+        height = [chart_width / 4, 15].min
+        base_opts = {
+          title: first_day.strftime("%Y-%m"),
+          xlim: [1, n_days], ylim: [0, y_max],
+          width: chart_width, height: height
+        }
+
+        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
+
+        series = build_series(xs, y_actual, y_linear, y_weekday, y_max,
+          today, first_day, effective_vc, legend: legend)
+
+        first_series, *rest_series = series
+        plot = UnicodePlot.lineplot(first_series[:x], first_series[:y],
+          name: first_series[:name], **base_opts, **series_color(first_series[:type], vc))
+        rest_series.each do |s|
+          UnicodePlot.lineplot!(plot, s[:x], s[:y], name: s[:name], **series_color(s[:type], vc))
+        end
+
+        buf = StringIO.new
+        plot.render(buf, color: color)
+        lines = buf.string.lines.map(&:chomp)
+
+        # Inject stats into the title line (first line)
+        total = y_actual.last || 0.0
+        days_with_entries = count_days_with_entries(result, first_day, n_days)
+        stats = format_stats(total, days_with_entries)
+        lines[0] = "#{lines[0]}#{stats}" if lines[0]
+
+        lines
+      end
+
+      def build_series(xs, y_actual, y_linear, y_weekday, y_max, today, first_day, vc, legend:)
+        in_current_month = today.year == first_day.year && today.month == first_day.month
+        show_today = vc.show_today && in_current_month
+
+        series = []
+        if show_today
+          x = today.day.to_f
+          series << {name: legend ? "Today" : "", type: :today,
+                     x: [x, x], y: [0.0, y_max.to_f]}
+        end
+        if vc.show_weekday
+          series << {name: legend ? "Weekday target" : "", type: :weekday,
+                     x: xs, y: y_weekday}
+        end
+        if vc.show_linear
+          series << {name: legend ? "Linear target" : "", type: :linear,
+                     x: xs, y: y_linear}
+        end
+        series << {name: legend ? "Actual" : "", type: :actual,
+                   x: xs, y: y_actual}
+        series
+      end
+
+      # Returns a color keyword argument hash for the given series type.
+      # Always returns a color — either from config or the built-in default.
+      # @param type [Symbol]
+      # @param vc [Config::VisualSettings]
+      # @return [Hash]
+      def series_color(type, vc)
+        key = SERIES_TYPES[type]
+        color = vc.colors[key] || DEFAULT_SERIES_COLORS[type]
+        {color: color}
+      end
+
+      def count_days_with_entries(result, first_day, n_days)
+        (0...n_days).count do |i|
+          date = first_day + i
+          result.entries_on(date).sum(&:time) > 0
+        end
+      end
+
+      def format_stats(total, days_with_entries)
+        avg = days_with_entries.positive? ? total / days_with_entries : 0.0
+        Kernel.format(" (%.1fh %.1fh/d)", total, avg)
+      end
+
+      # Strips ANSI escape sequences to compute visible character width.
+      # @param str [String]
+      # @return [Integer]
+      def visible_length(str)
+        str.gsub(/\e\[[0-9;]*m/, "").length
+      end
+
+      # Pads a string (which may contain ANSI codes) to a visible width.
+      # @param str [String]
+      # @param width [Integer] Desired visible width.
+      # @return [String]
+      def ansi_ljust(str, width)
+        padding = width - visible_length(str)
+        (padding > 0) ? "#{str}#{" " * padding}" : str
+      end
+
+      # Pastes multiple rendered chart line arrays side by side.
+      # @param charts [Array<Array<String>>] Each element is an array of lines.
+      # @param io [IO]
+      def paste_side_by_side(charts, io)
+        max_lines = charts.map(&:size).max
+        empty = [""].freeze
+        charts.each { |c| c.concat(empty * (max_lines - c.size)) }
+        widths = charts.map { |c| c.map { |line| visible_length(line) }.max || 0 }
+        last_col = charts.size - 1
+
+        max_lines.times do |i|
+          row = charts.each_with_index.map do |c, ci|
+            line = c[i]
+            (ci < last_col) ? ansi_ljust(line, widths[ci]) : line
+          end
+          io.puts row.join(" " * GAP)
+        end
+      end
+    end
+  end
+end