mdlogbook 0.1.0

data/exe/mlb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "mdlogbook"
+
+exit(Mdlogbook::CLI.new.run ? 0 : 1)

data/lib/mdlogbook/arg_parser.rb

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Mdlogbook
+  # Parses command-line arguments into an ordered list of {PeriodSpec} objects.
+  #
+  # Supported forms (after option parsing):
+  #   (no args)           current month
+  #   YYYY/M              a single month
+  #   YYYY-M              a single month (dash separator)
+  #   YYYY/M YYYY/M       inclusive month range
+  #   YYYY-MM-DD          a single day (also YYYY/MM/DD)
+  #   'YYYY/0*'           partial wildcard month (matched against available files)
+  #   '*/*'               all available months across all years
+  #   'YYYY/{N..M}'       month glob (bash/zsh brace expansion)
+  #   'YYYY/*'            all months of a year
+  #   m / m0 / mN / m-N   relative calendar month (0=current, positive=past, negative=future)
+  #   y / y0 / yN / y-N   relative calendar year (expands to individual month specs)
+  #   q / q0 / qN / q-N   relative calendar quarter (expands to 3 month specs)
+  #   w / w0 / wN / w-N   relative calendar week (Monday-start)
+  #   d / d0 / dN / d-N   relative calendar day (point)
+  #   DN                  duration: last N days including today
+  #   wN..M               simplified range shorthand for w{N..M}
+  #   w..                 open-ended shorthand for w{0..}
+  #   w1..                open-ended shorthand for w{1..}
+  #   'w{0..1}'           relative glob (expands to w0, w1, ...)
+  #   'y{1..}'            open-ended glob (uses filesystem to find oldest available)
+  class ArgParser
+    DATE_RE = /\A(\d{4})[\/-](\d{1,2})[\/-](\d{1,2})\z/
+    MONTH_RE = /\A(\d{4})[\/-](\d{1,2})\z/
+    DURATION_RE = /\AD(\d+)\z/
+    RELATIVE_UNIT_RE = /\A([dwmyq])(.*)\z/i
+    BRACED_RELATIVE_RANGE_RE = /\A\{(\d*)\.\.(\d*)\}\z/
+    SIMPLE_RELATIVE_RANGE_RE = /\A(\d*)\.\.(\d*)\z/
+
+    # Abstract base class for normalized argument directives.
+    #
+    # A directive captures the meaning of one command-line token independently
+    # of its surface syntax, then resolves itself into one or more {PeriodSpec}
+    # objects with help from {DirectiveContext}.
+    class Directive
+      def resolve_with(_resolver)
+        raise NotImplementedError, "#{self.class} must implement #resolve_with"
+      end
+    end
+
+    # Normalized directive representing an explicit single-day target.
+    class DateDirective < Directive
+      def initialize(date)
+        @date = date
+      end
+
+      def resolve_with(_resolver)
+        [PeriodSpec.new(@date, @date)]
+      end
+    end
+
+    # Normalized directive representing an explicit calendar month.
+    class MonthDirective < Directive
+      def initialize(year, month)
+        @year = year
+        @month = month
+      end
+
+      def resolve_with(_resolver)
+        [PeriodSpec.month(@year, @month)]
+      end
+    end
+
+    # Normalized directive representing a trailing duration like D7.
+    class RelativeDurationDirective < Directive
+      def initialize(value)
+        @value = value
+      end
+
+      def resolve_with(resolver)
+        [PeriodSpec.new(resolver.today - (@value - 1), resolver.today, relative: true)]
+      end
+    end
+
+    # Normalized directive representing a single relative point such as m1 or w0.
+    class RelativePointDirective < Directive
+      def initialize(unit, value)
+        @unit = unit
+        @value = value
+      end
+
+      def resolve_with(resolver)
+        Array(resolve_relative_point(resolver))
+      end
+
+      private
+
+      def resolve_relative_point(resolver)
+        today = resolver.today
+        case @unit
+        when "m" then relative_month(today)
+        when "y" then relative_year(today)
+        when "w" then relative_week(today)
+        when "d" then relative_day(today)
+        when "q" then relative_quarter(today)
+        end
+      end
+
+      def relative_month(today)
+        first = Date.new(today.year, today.month, 1)
+        target = (@value >= 0) ? first.prev_month(@value) : first.next_month(-@value)
+        PeriodSpec.month(target.year, target.month, relative: true)
+      end
+
+      def relative_year(today)
+        year = today.year - @value
+        (1..12).map { |month| PeriodSpec.month(year, month, relative: true) }
+      end
+
+      def relative_week(today)
+        monday = today - (today.wday - 1) % 7
+        start = monday - (7 * @value)
+        PeriodSpec.new(start, start + 6, relative: true)
+      end
+
+      def relative_day(today)
+        date = today - @value
+        PeriodSpec.new(date, date, relative: true)
+      end
+
+      def relative_quarter(today)
+        q_start_month = today.month - ((today.month - 1) % 3)
+        first = Date.new(today.year, q_start_month, 1)
+        target_first = (@value >= 0) ? first.prev_month(@value * 3) : first.next_month(-@value * 3)
+        (0..2).map do |i|
+          d = target_first.next_month(i)
+          PeriodSpec.month(d.year, d.month, relative: true)
+        end
+      end
+    end
+
+    # Normalized directive representing a bounded relative range such as w0..2.
+    class RelativeRangeDirective < Directive
+      def initialize(unit, from, to)
+        @unit = unit
+        @from = from
+        @to = to
+      end
+
+      def resolve_with(resolver)
+        expand_relative_range(resolver)
+      end
+
+      private
+
+      def expand_relative_range(resolver)
+        (@from..@to).flat_map { |n| Array(RelativePointDirective.new(@unit, n).resolve_with(resolver)) }
+      end
+    end
+
+    # Normalized directive representing an open-ended relative range such as y1...
+    class RelativeOpenEndedDirective < Directive
+      def initialize(unit, from)
+        @unit = unit
+        @from = from
+      end
+
+      def resolve_with(resolver)
+        parse_open_ended(resolver)
+      end
+
+      private
+
+      def parse_open_ended(resolver)
+        cutoff_date = if @unit == "y"
+          Date.new(resolver.today.year - @from, 12, 31)
+        else
+          Array(RelativePointDirective.new(@unit, @from).resolve_with(resolver)).first.end_date
+        end
+
+        resolver.list_available_months
+          .select { |year, month| Date.new(year, month, 1) <= cutoff_date }
+          .map { |year, month| PeriodSpec.month(year, month, relative: true) }
+      end
+    end
+
+    # Normalized directive representing wildcard-based month selection.
+    class WildcardDirective < Directive
+      def initialize(pattern)
+        @pattern = pattern
+      end
+
+      def resolve_with(resolver)
+        expand_or_resolve_wildcard(resolver)
+      end
+
+      private
+
+      def expand_or_resolve_wildcard(resolver)
+        tokens = resolver.expander.expand(@pattern)
+        return resolve_wildcard(resolver) if tokens == [@pattern]
+
+        parser = resolver.new_parser
+        tokens.flat_map { |token| parser.parse([token]) }
+      end
+
+      def resolve_wildcard(resolver)
+        unless @pattern.include?("/")
+          raise ArgumentError, "unresolvable wildcard: #{@pattern.inspect}"
+        end
+
+        resolver.list_available_months
+          .select { |year, month| File.fnmatch(@pattern, format("%04d/%02d", year, month), File::FNM_PATHNAME) }
+          .map { |year, month| PeriodSpec.month(year, month) }
+      end
+    end
+
+    # Resolves normalized directives into concrete {PeriodSpec} objects.
+    #
+    # Bundles the external resources that directives need during resolution
+    # (reference date, brace expander, file resolver), keeping {ArgParser}
+    # focused on interpreting command-line syntax.
+    class DirectiveContext
+      attr_reader :today, :expander
+
+      def initialize(parser:, today:, file_resolver:, expander:)
+        @parser = parser
+        @today = today
+        @file_resolver = file_resolver
+        @expander = expander
+      end
+
+      def resolve(directive)
+        directive.resolve_with(self)
+      end
+
+      def list_available_months
+        raise ArgumentError, "a FileResolver is required for this operation" unless @file_resolver
+
+        @file_resolver.list_available_months
+      end
+
+      def new_parser
+        ArgParser.new(today: @today, file_resolver: @file_resolver)
+      end
+    end
+
+    # @param today [Date] Reference date for relative specifiers (default: Date.today).
+    # @param file_resolver [FileResolver, nil] Used to resolve open-ended ranges.
+    def initialize(today: Date.today, file_resolver: nil)
+      @today = today
+      @file_resolver = file_resolver
+      @expander = BraceExpander.new
+      @context = DirectiveContext.new(
+        parser: self,
+        today: @today,
+        file_resolver: @file_resolver,
+        expander: @expander
+      )
+    end
+
+    # @param args [Array<String>]
+    # @return [Array<PeriodSpec>]
+    # @raise [ArgumentError] on unrecognised input.
+    def parse(args)
+      return [PeriodSpec.month(@today.year, @today.month)] if args.empty?
+
+      # Special case: exactly two plain month specifiers → range
+      if args.size == 2 && args.all? { |a| MONTH_RE.match?(a) }
+        return parse_month_range(args[0], args[1])
+      end
+
+      args.flat_map { |arg| parse_arg(arg) }
+    end
+
+    private
+
+    def parse_arg(arg)
+      @context.resolve(parse_directive(arg))
+    end
+
+    def parse_directive(arg)
+      parse_date_directive(arg) ||
+        parse_month_directive(arg) ||
+        parse_duration_directive(arg) ||
+        parse_relative_directive(arg) ||
+        parse_wildcard_directive(arg) ||
+        raise_unrecognised!(arg)
+    end
+
+    def parse_date_directive(arg)
+      match = DATE_RE.match(arg)
+      return unless match
+
+      DateDirective.new(Date.new(match[1].to_i, match[2].to_i, match[3].to_i))
+    end
+
+    def parse_month_directive(arg)
+      match = MONTH_RE.match(arg)
+      return unless match
+
+      MonthDirective.new(match[1].to_i, match[2].to_i)
+    end
+
+    def parse_duration_directive(arg)
+      match = DURATION_RE.match(arg)
+      return unless match
+
+      value = match[1].to_i
+      raise ArgumentError, "D0 is not a valid duration (use D1 for today)" if value.zero?
+
+      RelativeDurationDirective.new(value)
+    end
+
+    def parse_relative_directive(arg)
+      match = RELATIVE_UNIT_RE.match(arg)
+      return unless match
+
+      unit = match[1].downcase
+      body = match[2]
+
+      return RelativePointDirective.new(unit, 0) if body.empty?
+      return RelativePointDirective.new(unit, body.to_i) if body.match?(/\A-?\d+\z/)
+
+      from, to = parse_relative_range_body(body, arg)
+      return RelativeOpenEndedDirective.new(unit, from) if to.nil?
+
+      RelativeRangeDirective.new(unit, from, to)
+    end
+
+    def parse_relative_range_body(body, arg)
+      match = BRACED_RELATIVE_RANGE_RE.match(body) || SIMPLE_RELATIVE_RANGE_RE.match(body)
+      raise_invalid_relative_specifier!(arg) unless match
+
+      [relative_bound(match[1]), relative_bound(match[2], empty_default: nil)]
+    end
+
+    def relative_bound(value, empty_default: 0)
+      value.empty? ? empty_default : value.to_i
+    end
+
+    def parse_wildcard_directive(arg)
+      return unless arg.include?("{") || arg.include?("*")
+
+      WildcardDirective.new(arg)
+    end
+
+    def parse_month_range(from_str, to_str)
+      from_m = MONTH_RE.match(from_str)
+      to_m = MONTH_RE.match(to_str)
+      from = PeriodSpec.month(from_m[1].to_i, from_m[2].to_i)
+      to = PeriodSpec.month(to_m[1].to_i, to_m[2].to_i)
+
+      if from.start_date > to.start_date
+        raise ArgumentError, "start month must not be after end month"
+      end
+
+      specs = []
+      d = from.start_date
+      while d <= to.start_date
+        specs << PeriodSpec.month(d.year, d.month)
+        d = d.next_month
+      end
+      specs
+    end
+
+    def raise_invalid_relative_specifier!(arg)
+      raise ArgumentError, "invalid period specifier: #{arg.inspect}"
+    end
+
+    def raise_unrecognised!(arg)
+      raise ArgumentError, "unrecognised period specifier: #{arg.inspect}"
+    end
+  end
+end

data/lib/mdlogbook/brace_expander.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  # Expands brace patterns (bash/zsh style) into an array of strings.
+  #
+  # Supported forms:
+  #   {N..M}    integer range (zero-padding preserved if either bound is zero-padded)
+  #   {..M}     range with start omitted (defaults to 0)
+  #   {a,b,c}   explicit list
+  #   *         month wildcard, equivalent to {01..12} after a slash
+  class BraceExpander
+    # Expands +pattern+ and returns an array of expanded strings.
+    # Open-ended ranges ({N..}) are not supported here; detect them before calling.
+    # @param pattern [String]
+    # @return [Array<String>]
+    def expand(pattern)
+      pattern = pattern.gsub(%r{(?<=/)\*\z}, "{01..12}")
+      expand_pattern(pattern)
+    end
+
+    private
+
+    def expand_pattern(str)
+      open_pos = str.index("{")
+      return [str] unless open_pos
+
+      close_pos = str.index("}", open_pos)
+      return [str] unless close_pos
+
+      prefix = str[0, open_pos]
+      suffix = str[close_pos + 1..]
+      content = str[open_pos + 1, close_pos - open_pos - 1]
+
+      expand_content(content).flat_map { |token| expand_pattern("#{prefix}#{token}#{suffix}") }
+    end
+
+    def expand_content(content)
+      if (m = content.match(/\A(-?\d*)\.\.(-?\d+)\z/))
+        expand_range(m[1], m[2])
+      else
+        content.split(",")
+      end
+    end
+
+    def expand_range(from_str, to_str)
+      from = from_str.empty? ? 0 : from_str.to_i
+      to = to_str.to_i
+      pad = zero_padded?(from_str) || zero_padded?(to_str)
+      width = [from_str.length, to_str.length].max
+
+      nums = (from <= to) ? (from..to).to_a : from.downto(to).to_a
+      nums.map { |n| pad ? n.to_s.rjust(width, "0") : n.to_s }
+    end
+
+    def zero_padded?(str)
+      str.length > 1 && str.start_with?("0")
+    end
+  end
+end

data/lib/mdlogbook/cli.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "date"
+require "fileutils"
+require "securerandom"
+
+module Mdlogbook
+  # Command-line interface for mlb.
+  class CLI
+    # @param path [String, nil] Override path to include in the template.
+    # @return [String] YAML template for config file, respecting XDG_DATA_HOME.
+    def self.init_template(path: nil)
+      data_home = ENV.fetch("XDG_DATA_HOME", "~/.local/share")
+      log_path = path || "#{data_home}/mdlogbook/logs"
+      salt = SecureRandom.hex(16)
+      <<~YAML
+        mdlogbook:
+          path: #{log_path}
+          # target_hours: 160
+          anonymize:
+            salt: "#{salt}"
+      YAML
+    end
+
+    # Holds parsed command-line option flags and values.
+    Options = Struct.new(
+      :format, :regexp, :filter_regexp, :merge, :no_merge, :debug, :edit, :init, :list_projects,
+      :target_hours, :no_target_hours, :line_chart_size, :heatmap_resolution, :project,
+      :config_path, :path_override, :completion
+    ) do
+      def initialize(**)
+        super
+        self.merge ||= false
+        self.no_merge ||= false
+        self.debug ||= false
+        self.edit ||= false
+        self.init ||= false
+        self.no_target_hours ||= false
+        self.list_projects ||= false
+      end
+    end
+
+    # @param argv [Array<String>] Command-line arguments (default: ARGV).
+    # @param stdout [IO] Standard output stream (default: $stdout).
+    # @param stderr [IO] Standard error stream (default: $stderr).
+    # @param today [Date] Reference date for resolving relative period specifiers (default: Date.today).
+    def initialize(argv: ARGV, stdout: $stdout, stderr: $stderr, today: Date.today)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @today = today
+      @opts = Options.new
+    end
+
+    # Parses options, resolves period specifiers to files, then runs the formatter.
+    # @return [Boolean] true on success, false on error.
+    def run
+      parse_options!
+      return print_completion(@opts.completion) if @opts.completion
+      return setup_config if @opts.init
+
+      config = Config.new(config_path: @opts.config_path, project: @opts.project)
+      return print_projects(config) if @opts.list_projects
+
+      apply_config_defaults(config)
+      env = Env.new(opts: @opts, argv: @argv, stdout: @stdout, stderr: @stderr, today: @today, config: config)
+      Runner.dispatch(env: env)
+      true
+    rescue Mdlogbook::Error, ArgumentError, OptionParser::ParseError => e
+      if @opts.debug
+        @stderr.puts "Error: #{e.class}: #{e.message}"
+        @stderr.puts e.backtrace.join("\n")
+      else
+        @stderr.puts "Error: #{e.message}"
+      end
+      false
+    end
+
+    # Enables debug mode.
+    # @return [self]
+    def debug
+      @opts.debug = true
+      self
+    end
+
+    private
+
+    def setup_config
+      config_path = @opts.config_path || default_config_path
+      if File.exist?(config_path)
+        @stderr.puts "Error: config file already exists: #{config_path}"
+        return false
+      end
+      FileUtils.mkdir_p(File.dirname(config_path))
+      File.write(config_path, self.class.init_template(path: @opts.path_override))
+      @stdout.puts "Created config file: #{config_path}"
+      @stdout.puts "Please edit it to set your project path."
+    end
+
+    def print_projects(config)
+      config.projects.each { |name| @stdout.puts name }
+    end
+
+    def default_config_path
+      Config.default_config_path
+    end
+
+    VALID_DEFAULT_VIEWS = %w[simple calendar line_chart grid heatmap].freeze
+
+    def apply_config_defaults(config)
+      @opts.format ||= resolve_default_view(config)
+      @opts.target_hours ||= config.target_hours unless @opts.no_target_hours
+    end
+
+    def resolve_default_view(config)
+      view = config.default_view
+      return :simple unless view
+
+      unless VALID_DEFAULT_VIEWS.include?(view)
+        raise ArgumentError, "invalid default_view: #{view.inspect} (use #{VALID_DEFAULT_VIEWS.join(", ")})"
+      end
+
+      view.to_sym
+    end
+
+    def print_completion(shell)
+      case shell
+      when "bash" then @stdout.puts @registry.completion_bash
+      when "zsh" then @stdout.puts @registry.completion_zsh
+      else raise ArgumentError, "unknown shell: #{shell} (use bash or zsh)"
+      end
+    end
+
+    def parse_options!
+      @registry = build_registry
+      @registry.to_option_parser(banner: <<~TEXT).parse!(@argv)
+        Usage: mlb [options] [period...]
+
+        Primary mode:
+          Choose one of `-e`, `--raw`, `--grep`, or a summary view option.
+          If no view option is given, mlb uses the default summary view.
+          `--filter` applies only to summary views.
+      TEXT
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def build_registry
+      reg = OptionRegistry.new
+
+      reg.separator "Edit:"
+      reg.option(short: "-e", long: "--edit", description: "open the target file in an editor") { @opts.edit = true }
+
+      reg.separator "Summary Views:"
+      reg.option(short: "-s", long: "--simple",
+        description: "show entries as a flat list (default)") { @opts.format = :simple }
+      reg.option(short: "-c", long: "--calendar",
+        description: "show entries as a monthly calendar") { @opts.format = :calendar }
+      reg.option(short: "-l", long: "--line-chart", arg_name: "SIZE", arg_optional: true, type: String,
+        values: %w[small s medium m large l max x],
+        description: "show cumulative hours as a line chart; SIZE: small/s, medium/m, large/l, max/x (default)") do |v|
+        @opts.format = :line_chart
+        @opts.line_chart_size = v
+      end
+      reg.option(long: "--grid",
+        description: "show charts in a 3-column grid layout (up to 12 months)") { @opts.format = :grid }
+      reg.option(long: "--heatmap", arg_name: "RESOLUTION", arg_optional: true, type: String,
+        values: %w[15m 30m 1h],
+        description: "show day-of-week x hour-of-day density plot; RESOLUTION: 15m, 30m (default), 1h") do |v|
+        @opts.format = :heatmap
+        @opts.heatmap_resolution = v
+      end
+      reg.option(long: "--anonymize",
+        description: "output anonymized markdown for AI analysis") { @opts.format = :anonymize }
+      reg.option(long: "--anonymize-dict",
+        description: "output reverse-lookup dictionary for anonymized jobs") { @opts.format = :anonymize_dict }
+      reg.option(long: "--filter", arg_name: "REGEXP", type: Regexp,
+        description: "filter aggregated entries by job name") { |v| @opts.filter_regexp = v }
+      reg.option(long: "--merge",
+        description: "combine all periods into a single result") { @opts.merge = true }
+      reg.option(long: "--no-merge",
+        description: "show each period separately (overrides default merge)") { @opts.no_merge = true }
+      reg.option(long: "--target-hours", arg_name: "HOURS", type: Numeric,
+        description: "override monthly target hours from config") { |v| @opts.target_hours = v }
+      reg.option(long: "--no-target-hours",
+        description: "disable target hours display") { @opts.no_target_hours = true }
+
+      reg.separator "Extract:"
+      reg.option(long: "--raw",
+        description: "output raw markdown content for AI summarization") { @opts.format = :raw }
+      reg.option(long: "--grep", arg_name: "REGEXP", type: Regexp,
+        description: "extract sections whose headings match REGEXP") do |v|
+        @opts.format = :grep
+        @opts.regexp = v
+      end
+
+      reg.separator "Configuration:"
+      reg.option(short: "-p", long: "--project", arg_name: "NAME", type: String,
+        completion: "$(mlb --list-projects 2>/dev/null)",
+        description: "select project (overrides MDLOGBOOK_PROJECT)") { |v| @opts.project = v }
+      reg.option(long: "--list-projects",
+        description: "list all configured project names") { @opts.list_projects = true }
+      reg.option(long: "--config", arg_name: "PATH", type: String, completion: :file,
+        description: "config file path (overrides MDLOGBOOK_CONFIG)") { |v| @opts.config_path = v }
+      reg.option(long: "--path", arg_name: "PATH", type: String, completion: :directory,
+        description: "log directory path (overrides config)") { |v| @opts.path_override = v }
+      reg.option(long: "--init",
+        description: "create a config file template") { @opts.init = true }
+
+      reg.separator "Other:"
+      reg.option(long: "--completion", arg_name: "SHELL", type: String, values: %w[bash zsh],
+        description: "print shell completion script") { |v| @opts.completion = v }
+      reg.option(long: "--debug",
+        description: "show internal diagnostics") { @opts.debug = true }
+      reg.option(short: "-h", long: "--help", description: "show help") do
+        @stdout.puts @registry.to_option_parser(banner: "")
+        exit
+      end
+
+      reg
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+  end
+end