mdlogbook 0.1.0

data/lib/mdlogbook/runner/visual_format_runner.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  module Runner
+    # Runs visual output modes: line chart, grid, and heatmap.
+    class VisualFormatRunner < Base
+      def run
+        if @env.line_chart_format?
+          run_line_chart
+        elsif @env.grid_format?
+          run_grid
+        elsif @env.heatmap_format?
+          run_heatmap
+        end
+      end
+
+      private
+
+      def run_line_chart
+        unless all_month_unit?
+          raise ArgumentError, "--line-chart requires month-unit specifiers (e.g. 2026/1, m0, q0)"
+        end
+        if @specs.size > 3
+          raise ArgumentError, "--line-chart supports at most 3 months (got #{@specs.size})"
+        end
+
+        formatter = Formatter::LineChart.new
+        each_sorted_spec.with_index do |spec, index|
+          @env.puts if index.positive?
+          result = load_result(spec)
+          formatter.format_output(
+            result, work_threshold, @env.stdout,
+            spec: spec,
+            size: @env.opts.line_chart_size,
+            today: @env.today,
+            line_chart_config: line_chart_config
+          )
+        end
+      end
+
+      def run_grid
+        unless all_month_unit?
+          raise ArgumentError, "--grid requires month-unit specifiers (e.g. 2026/1, m0, q0)"
+        end
+        if @specs.size > 12
+          raise ArgumentError, "--grid supports at most 12 months (got #{@specs.size})"
+        end
+
+        threshold = work_threshold
+        formatter = Formatter::Grid.new
+        spec_results = each_sorted_spec.map { |spec| [spec, load_result(spec)] }
+        formatter.format_output(spec_results, threshold, @env.stdout, today: @env.today, line_chart_config: line_chart_config)
+      end
+
+      def run_heatmap
+        merged = Parser::Result.new
+        each_spec { |spec| merged.merge!(load_result(spec)) }
+
+        range_begin, range_end = spec_range
+        formatter = Formatter::Heatmap.new
+        formatter.format_output(merged, @env.stdout,
+          resolution: @env.opts.heatmap_resolution,
+          heatmap_config: @env.config.heatmap_settings,
+          range_begin: range_begin,
+          range_end: range_end)
+      end
+
+      def all_month_unit?
+        each_spec.all?(&:month_unit?)
+      end
+
+      def line_chart_config
+        @env.config.visual_settings
+      end
+    end
+  end
+end

data/lib/mdlogbook/runner.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  # Executes the resolved command after CLI has parsed options and loaded config.
+  #
+  # Responsible for dispatching to the appropriate output mode (summary views,
+  # line chart, grid, heatmap, raw extraction, grep, or editor launch) based
+  # on the parsed option flags.
+  module Runner
+    class << self
+      def dispatch(env:)
+        resolver = FileResolver.new(config: env.config, basedir: env.opts.path_override)
+        runner_class =
+          if env.edit?
+            EditorRunner
+          elsif env.extract_format?
+            ExtractFormatRunner
+          elsif env.visual_format?
+            VisualFormatRunner
+          else
+            StandardFormatRunner
+          end
+        runner_class.new(env: env, file_resolver: resolver).run
+      end
+    end
+  end
+end

data/lib/mdlogbook/section_extractor.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Mdlogbook
+  # Extracts markdown sections whose level-2 or level-3 headings match a regexp.
+  class SectionExtractor
+    DATE_HEADER_RE = /^# (\d{4}-\d{2}-\d{2})$/
+    SECTION_HEADER_RE = /^(##|###) (.+)$/
+
+    # Immutable value object representing one extracted markdown section.
+    Section = Data.define(:date, :heading_level, :heading, :lines)
+
+    # Accumulates extracted sections in input order.
+    class Result
+      # @return [Array[Section]]
+      attr_reader :sections
+
+      # Creates an empty result.
+      def initialize
+        @sections = []
+      end
+
+      # Adds a section to the result.
+      # @param section [Section]
+      # @return [void]
+      def add_section(section)
+        @sections << section
+      end
+
+      # Merges another {Result} into this one in place.
+      # @param other [Result]
+      # @return [self]
+      def merge!(other)
+        @sections.concat(other.sections)
+        self
+      end
+
+      # Iterates over extracted sections in input order.
+      # @yield [section]
+      # @yieldparam section [Section]
+      # @return [void]
+      def each_section(&)
+        @sections.each(&)
+      end
+
+      # Returns true when no sections have been added.
+      # @return [Boolean]
+      def empty?
+        @sections.empty?
+      end
+    end
+
+    # Parses logbook content from a file path, extracting matching sections within +date_range+.
+    # @param filename [String]
+    # @param date_range [Range<Date>]
+    # @param regexp [Regexp]
+    # @return [Result]
+    def extract_file(filename, date_range, regexp:)
+      File.open(filename, "r") { |io| extract(io, date_range, regexp: regexp) }
+    end
+
+    # Parses logbook content from an IO object, extracting matching sections within +date_range+.
+    # @param io [IO]
+    # @param date_range [Range<Date>]
+    # @param regexp [Regexp]
+    # @return [Result]
+    def extract(io, date_range, regexp:)
+      result = Result.new
+      current_date = nil
+      current_date_header = nil
+      current_section = nil
+
+      io.each_line do |raw_line|
+        line = raw_line.chomp
+
+        if (date_match = DATE_HEADER_RE.match(line))
+          flush_section(result, current_section, date_range)
+          current_date = Date.parse(date_match[1])
+          current_date_header = line
+          current_section = nil
+          next
+        end
+
+        header_match = SECTION_HEADER_RE.match(line)
+        if header_match
+          current_section = advance_section(result, current_section, current_date, current_date_header, date_range, regexp, line, header_match)
+          next unless current_section
+
+          current_section[:lines] << line if nested_heading?(current_section, header_match)
+          next
+        end
+
+        next unless current_section
+
+        current_section[:lines] << line
+      end
+
+      flush_section(result, current_section, date_range)
+      result
+    end
+
+    private
+
+    def advance_section(result, current_section, current_date, current_date_header, date_range, regexp, line, header_match)
+      level = header_match[1].length
+      heading = header_match[2]
+
+      if current_section && level <= current_section[:heading_level]
+        flush_section(result, current_section, date_range)
+        current_section = nil
+      end
+
+      return current_section unless current_date && regexp.match?(heading)
+
+      {
+        date: current_date,
+        heading_level: level,
+        heading: heading,
+        lines: [current_date_header, "", line]
+      }
+    end
+
+    def flush_section(result, current_section, date_range)
+      return unless current_section
+      return unless date_range.cover?(current_section[:date])
+
+      result.add_section(Section.new(
+        date: current_section[:date],
+        heading_level: current_section[:heading_level],
+        heading: current_section[:heading],
+        lines: current_section[:lines].dup
+      ))
+    end
+
+    def nested_heading?(current_section, header_match)
+      header_match[1].length > current_section[:heading_level]
+    end
+  end
+end

data/lib/mdlogbook/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  # Gem version string following Semantic Versioning.
+  VERSION = "0.1.0"
+end

data/lib/mdlogbook/work_thresholds.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Mdlogbook
+  # Holds working-time thresholds derived from monthly targets.
+  class WorkThresholds
+    # @!attribute [r] target_hours
+    #   @return [Numeric] Monthly target hours.
+    # @!attribute [r] working_days_per_month
+    #   @return [Numeric] Assumed number of working days per month.
+    # @!attribute [r] daily_target
+    #   @return [Float] Target hours per working day.
+    # @!attribute [r] high_threshold
+    #   @return [Float] Upper threshold (120% of daily_target) for "excellent" rating.
+    # @!attribute [r] low_threshold
+    #   @return [Float] Lower threshold (70% of daily_target) for "poor" rating.
+    attr_reader :target_hours, :working_days_per_month,
+      :daily_target, :high_threshold, :low_threshold
+
+    # @param target_hours [Numeric, nil] Monthly target hours, or +nil+ for no target.
+    # @param working_days_per_month [Numeric] Assumed working days per month (default: 20).
+    def initialize(target_hours:, working_days_per_month: 20)
+      @target_hours = target_hours
+      @working_days_per_month = working_days_per_month
+      if target_hours
+        @daily_target = target_hours.to_f / working_days_per_month
+        @high_threshold = @daily_target * 1.2
+        @low_threshold = @daily_target * 0.7
+      end
+    end
+
+    # Returns +true+ when a monthly target is configured.
+    # @return [Boolean]
+    def target_hours?
+      !@target_hours.nil?
+    end
+  end
+end

data/lib/mdlogbook.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Top-level namespace for the mdlogbook gem.
+module Mdlogbook
+  # Base error class for mdlogbook-specific exceptions.
+  class Error < StandardError; end
+end
+
+require_relative "mdlogbook/version"
+require_relative "mdlogbook/config"
+require_relative "mdlogbook/parser"
+require_relative "mdlogbook/work_thresholds"
+require_relative "mdlogbook/file_resolver"
+require_relative "mdlogbook/period_spec"
+require_relative "mdlogbook/brace_expander"
+require_relative "mdlogbook/arg_parser"
+require_relative "mdlogbook/date_filter"
+require_relative "mdlogbook/editor_launcher"
+require_relative "mdlogbook/overlap_checker"
+require_relative "mdlogbook/raw_extractor"
+require_relative "mdlogbook/section_extractor"
+require_relative "mdlogbook/formatter/base"
+require_relative "mdlogbook/formatter/simple"
+require_relative "mdlogbook/formatter/calendar"
+require_relative "mdlogbook/formatter/anonymize"
+require_relative "mdlogbook/formatter/anonymize_dict"
+require_relative "mdlogbook/formatter/extract"
+require_relative "mdlogbook/formatter/chart_series_builder"
+require_relative "mdlogbook/formatter/line_chart"
+require_relative "mdlogbook/formatter/grid"
+require_relative "mdlogbook/formatter/heatmap"
+require_relative "mdlogbook/runner"
+require_relative "mdlogbook/runner/base"
+require_relative "mdlogbook/runner/editor_runner"
+require_relative "mdlogbook/runner/extract_format_runner"
+require_relative "mdlogbook/runner/visual_format_runner"
+require_relative "mdlogbook/runner/standard_format_runner"
+require_relative "mdlogbook/env"
+require_relative "mdlogbook/option_def"
+require_relative "mdlogbook/option_registry"
+require_relative "mdlogbook/cli"

data/sig/mdlogbook/arg_parser.rbs

@@ -0,0 +1,54 @@
+# Parses command-line arguments into an ordered list of PeriodSpec objects.
+class Mdlogbook::ArgParser
+  class Directive
+    def resolve_with: (ArgParser::DirectiveContext) -> Array[Mdlogbook::PeriodSpec]
+  end
+
+  class DateDirective < Directive
+    def initialize: (Date) -> void
+    def resolve_with: (ArgParser::DirectiveContext) -> Array[Mdlogbook::PeriodSpec]
+  end
+
+  class MonthDirective < Directive
+    def initialize: (Integer, Integer) -> void
+    def resolve_with: (ArgParser::DirectiveContext) -> Array[Mdlogbook::PeriodSpec]
+  end
+
+  class RelativeDurationDirective < Directive
+    def initialize: (Integer) -> void
+    def resolve_with: (ArgParser::DirectiveContext) -> Array[Mdlogbook::PeriodSpec]
+  end
+
+  class RelativePointDirective < Directive
+    def initialize: (String, Integer) -> void
+    def resolve_with: (ArgParser::DirectiveContext) -> Array[Mdlogbook::PeriodSpec]
+  end
+
+  class RelativeRangeDirective < Directive
+    def initialize: (String, Integer, Integer) -> void
+    def resolve_with: (ArgParser::DirectiveContext) -> Array[Mdlogbook::PeriodSpec]
+  end
+
+  class RelativeOpenEndedDirective < Directive
+    def initialize: (String, Integer) -> void
+    def resolve_with: (ArgParser::DirectiveContext) -> Array[Mdlogbook::PeriodSpec]
+  end
+
+  class WildcardDirective < Directive
+    def initialize: (String) -> void
+    def resolve_with: (ArgParser::DirectiveContext) -> Array[Mdlogbook::PeriodSpec]
+  end
+
+  class DirectiveContext
+    attr_reader today: Date
+    attr_reader expander: Mdlogbook::BraceExpander
+
+    def initialize: (parser: ArgParser, today: Date, file_resolver: Mdlogbook::FileResolver?, expander: Mdlogbook::BraceExpander) -> void
+    def resolve: (ArgParser::Directive) -> Array[Mdlogbook::PeriodSpec]
+    def list_available_months: () -> Array[[Integer, Integer]]
+    def new_parser: () -> ArgParser
+  end
+
+  def initialize: (?today: Date, ?file_resolver: Mdlogbook::FileResolver?) -> void
+  def parse: (Array[String]) -> Array[Mdlogbook::PeriodSpec]
+end

data/sig/mdlogbook/brace_expander.rbs

@@ -0,0 +1,4 @@
+# Expands brace patterns (bash/zsh style) into an array of strings.
+class Mdlogbook::BraceExpander
+  def expand: (String) -> Array[String]
+end

data/sig/mdlogbook/cli.rbs

@@ -0,0 +1,14 @@
+# Command-line interface for mlb.
+class Mdlogbook::CLI
+  def self.init_template: (?path: String?) -> String
+
+  def initialize: (?argv: Array[String], ?stdout: IO, ?stderr: IO, ?today: Date) -> void
+  def run: () -> bool
+  def debug: () -> self
+
+  private
+
+  def print_completion: (String shell) -> void
+  def parse_options!: () -> void
+  def build_registry: () -> Mdlogbook::OptionRegistry
+end

data/sig/mdlogbook/config.rbs

@@ -0,0 +1,60 @@
+# Loads per-project configuration from a YAML file.
+class Mdlogbook::Config
+  DEFAULT_PROJECT: String
+  DEFAULT_ANONYMIZE_FORMAT: String
+  DEFAULT_HEATMAP_START_HOUR: Integer
+  DEFAULT_VISUAL_SETTINGS: Hash[String, untyped]
+  VALID_VISUAL_COLORS: Array[Symbol]
+
+  # Immutable value object holding anonymize formatter settings.
+  class AnonymizeSettings < Data
+    attr_reader project: String
+    attr_reader format: String
+    attr_reader salt: String
+    attr_reader passthrough: Array[String]
+    attr_reader preamble: String?
+    attr_reader postamble: String?
+
+    def initialize: (project: String, format: String, salt: String, passthrough: Array[String], preamble: String?, postamble: String?) -> void
+  end
+
+  # Immutable value object holding visual formatter settings.
+  class VisualSettings < Data
+    attr_reader show_today: bool
+    attr_reader show_weekday: bool
+    attr_reader show_linear: bool
+    attr_reader colors: Hash[String, Symbol]
+
+    def initialize: (?show_today: bool, ?show_weekday: bool, ?show_linear: bool, ?colors: Hash[String, Symbol]) -> void
+  end
+
+  # Immutable value object holding heatmap formatter settings.
+  class HeatmapSettings < Data
+    attr_reader start_hour: Integer
+
+    def initialize: (start_hour: Integer) -> void
+  end
+
+  # Immutable value object holding extract formatter settings.
+  class ExtractSettings < Data
+    attr_reader preamble: String?
+    attr_reader postamble: String?
+
+    def initialize: (preamble: String?, postamble: String?) -> void
+  end
+
+  attr_reader config_path: String
+
+  def self.default_config_path: () -> String
+  def initialize: (?config_path: String?, ?project: String?) -> void
+  def current_project: () -> String
+  def projects: () -> Array[String]
+  def basedir: (?String) -> String
+  def target_hours: (?String) -> Numeric?
+  def default_view: (?String) -> String?
+  def extract_settings: (?String) -> Config::ExtractSettings
+  def anonymize_settings: (?String) -> Config::AnonymizeSettings
+  def heatmap_settings: (?String) -> Config::HeatmapSettings
+  def editor_args: (?String) -> String?
+  def visual_settings: (?String) -> Config::VisualSettings
+end

data/sig/mdlogbook/date_filter.rbs

@@ -0,0 +1,4 @@
+# Filters a Parser::Result to only include entries within a given PeriodSpec.
+module Mdlogbook::DateFilter
+  def self.filter: (Mdlogbook::Parser::Result, Mdlogbook::PeriodSpec) -> Mdlogbook::Parser::Result
+end

data/sig/mdlogbook/editor_launcher.rbs

@@ -0,0 +1,9 @@
+# Builds and runs an editor command for a logbook file.
+class Mdlogbook::EditorLauncher
+  class NoEditorError < Mdlogbook::Error
+  end
+
+  def initialize: (file: String, ?today: Date, ?args_template: String?) -> void
+  def build_command: () -> Array[String]
+  def launch: () -> bool
+end

data/sig/mdlogbook/env.rbs

@@ -0,0 +1,32 @@
+# Immutable execution context shared by Runner and Executor layers.
+class Mdlogbook::Env
+  attr_reader opts: Mdlogbook::CLI::Options
+  attr_reader argv: Array[String]
+  attr_reader stdout: IO
+  attr_reader stderr: IO
+  attr_reader today: Date
+  attr_reader config: Mdlogbook::Config
+
+  def initialize: (opts: Mdlogbook::CLI::Options, argv: Array[String], stdout: IO, stderr: IO, today: Date, config: Mdlogbook::Config) -> void
+
+  def raw_format?: () -> bool
+  def grep_format?: () -> bool
+  def line_chart_format?: () -> bool
+  def grid_format?: () -> bool
+  def heatmap_format?: () -> bool
+  def overlap_reporting_format?: () -> bool
+  def warning_reporting_format?: () -> bool
+  def anonymize_format?: () -> bool
+  def extract_format?: () -> bool
+  def visual_format?: () -> bool
+
+  def anonymize_settings: () -> Mdlogbook::Config::AnonymizeSettings?
+
+  def edit?: () -> bool
+  def debug?: () -> bool
+  def tty?: () -> bool
+
+  def puts: (*untyped args) -> void
+  def warn: (*untyped args) -> void
+  def alert: (*untyped args) -> void
+end

data/sig/mdlogbook/file_resolver.rbs

@@ -0,0 +1,9 @@
+# Resolves logbook file paths from config and a year/month pair.
+class Mdlogbook::FileResolver
+  attr_reader basedir: String
+  attr_reader project: String
+
+  def initialize: (?config: Mdlogbook::Config, ?basedir: String?) -> void
+  def resolve: (Integer, Integer) -> String
+  def list_available_months: () -> Array[[Integer, Integer]]
+end

data/sig/mdlogbook/formatter/anonymize.rbs

@@ -0,0 +1,4 @@
+# Formats logbook entries as anonymized markdown for AI analysis.
+class Mdlogbook::Formatter::Anonymize < Mdlogbook::Formatter::Base
+  def format_output: (Mdlogbook::Parser::Result, Mdlogbook::WorkThresholds, ?IO, ?anonymize_settings: Mdlogbook::Config::AnonymizeSettings?, ?range_begin: Date?, ?range_end: Date?, **untyped) -> void
+end

data/sig/mdlogbook/formatter/anonymize_dict.rbs

@@ -0,0 +1,4 @@
+# Outputs a reverse-lookup dictionary for anonymized job names.
+class Mdlogbook::Formatter::AnonymizeDict < Mdlogbook::Formatter::Base
+  def format_output: (Mdlogbook::Parser::Result, Mdlogbook::WorkThresholds, ?IO, ?anonymize_settings: Mdlogbook::Config::AnonymizeSettings?, **untyped) -> void
+end

data/sig/mdlogbook/formatter/base.rbs

@@ -0,0 +1,15 @@
+# Abstract base class for output formatters.
+class Mdlogbook::Formatter::Base
+  PLAIN_SIGNS: Hash[Symbol, String]
+
+  attr_reader color_reset: String
+  attr_reader row_colors: Array[String]
+  attr_reader calendar_signs: Hash[Symbol, String]
+  attr_reader calendar_colors: Hash[Symbol, String]
+
+  def initialize: (?color: bool) -> void
+  def format_output: (Mdlogbook::Parser::Result, Mdlogbook::WorkThresholds, IO, **untyped) -> void
+
+  private
+  def passthrough?: (String, Array[String]) -> bool
+end

data/sig/mdlogbook/formatter/calendar.rbs

@@ -0,0 +1,4 @@
+# Formats logbook entries as a weekly calendar grid with daily totals and ratings.
+class Mdlogbook::Formatter::Calendar < Mdlogbook::Formatter::Base
+  def format_output: (Mdlogbook::Parser::Result, Mdlogbook::WorkThresholds, ?IO, ?today: Date, ?debug: bool, **untyped) -> void
+end

data/sig/mdlogbook/formatter/chart_series_builder.rbs

@@ -0,0 +1,9 @@
+# Shared methods for building cumulative chart series.
+module Mdlogbook::Formatter::ChartSeriesBuilder
+  private
+
+  def build_actual: (Mdlogbook::Parser::Result, Date, Integer) -> Array[Float]
+  def build_linear_target: (Numeric, Integer) -> Array[Float]
+  def build_weekday_target: (Mdlogbook::WorkThresholds, Date, Integer) -> Array[Float]
+  def working_day?: (Date) -> bool
+end

data/sig/mdlogbook/formatter/extract.rbs

@@ -0,0 +1,4 @@
+# Outputs raw logbook content for AI summarization.
+class Mdlogbook::Formatter::Extract
+  def format_output: (Mdlogbook::RawExtractor::Result, ?IO, ?extract_config: Mdlogbook::Config::ExtractSettings?, ?range_begin: Date?, ?range_end: Date?) -> void
+end

data/sig/mdlogbook/formatter/grid.rbs

@@ -0,0 +1,8 @@
+# Renders multiple months as a grid of line charts.
+class Mdlogbook::Formatter::Grid
+  MIN_CHART_WIDTH: Integer
+  OVERHEAD: Integer
+  GAP: Integer
+
+  def format_output: (Array[[Mdlogbook::PeriodSpec, Mdlogbook::Parser::Result]], Mdlogbook::WorkThresholds, ?IO, ?today: Date, ?line_chart_config: Mdlogbook::Config::VisualSettings?) -> void
+end

data/sig/mdlogbook/formatter/heatmap.rbs

@@ -0,0 +1,10 @@
+# Renders a day-of-week x hour-of-day density plot showing work patterns.
+class Mdlogbook::Formatter::Heatmap
+  SAMPLE_INTERVAL: Integer
+  HEIGHT: Integer
+  RESOLUTIONS: Hash[String, Integer]
+  DEFAULT_RESOLUTION: String
+  DAY_LABELS: Array[String]
+
+  def format_output: (Mdlogbook::Parser::Result, ?IO, ?resolution: String?, ?heatmap_config: Mdlogbook::Config::HeatmapSettings, ?range_begin: Date?, ?range_end: Date?) -> void
+end

data/sig/mdlogbook/formatter/line_chart.rbs

@@ -0,0 +1,7 @@
+# Renders a cumulative-hours line chart for a single calendar month.
+class Mdlogbook::Formatter::LineChart
+  SIZES: Hash[String, {width: Integer, height: Integer}?]
+  SIZE_ALIASES: Hash[String, String]
+
+  def format_output: (Mdlogbook::Parser::Result, Mdlogbook::WorkThresholds, ?IO, spec: Mdlogbook::PeriodSpec, ?size: String, ?today: Date, ?line_chart_config: Mdlogbook::Config::VisualSettings?, **untyped) -> void
+end

data/sig/mdlogbook/formatter/simple.rbs

@@ -0,0 +1,6 @@
+# Formats logbook entries as a flat list with a total summary line.
+class Mdlogbook::Formatter::Simple < Mdlogbook::Formatter::Base
+  ROW_FORMAT: String
+
+  def format_output: (Mdlogbook::Parser::Result, Mdlogbook::WorkThresholds, ?IO, **untyped) -> void
+end

data/sig/mdlogbook/option_def.rbs

@@ -0,0 +1,30 @@
+# Describes a single CLI option with metadata for OptionParser and shell completion.
+class Mdlogbook::OptionDef
+  attr_reader short: String?
+  attr_reader long: String
+  attr_reader arg_name: String?
+  attr_reader arg_optional: bool
+  attr_reader description: String
+  attr_reader type: Class?
+  attr_reader values: Array[String]?
+  attr_reader completion: (Symbol | String)?
+
+  def initialize: (
+    long: String,
+    description: String,
+    ?short: String?,
+    ?arg_name: String?,
+    ?arg_optional: bool,
+    ?type: Class?,
+    ?values: Array[String]?,
+    ?completion: (Symbol | String)?
+  ) -> void
+
+  def flag?: () -> bool
+  def long_name: () -> String
+  def optparse_args: () -> Array[untyped]
+
+  private
+
+  def optparse_long_flag: () -> String
+end

data/sig/mdlogbook/option_registry.rbs

@@ -0,0 +1,18 @@
+# Collects CLI option definitions and generates OptionParser instances and shell completion scripts.
+class Mdlogbook::OptionRegistry
+  def initialize: () -> void
+  def separator: (String text) -> void
+  def option: (**untyped kwargs) ?{ (untyped) -> void } -> Mdlogbook::OptionDef
+  def definitions: () -> Array[Mdlogbook::OptionDef]
+  def to_option_parser: (banner: String) -> OptionParser
+  def completion_bash: () -> String
+  def completion_zsh: () -> String
+
+  private
+
+  def bash_compgen: (Mdlogbook::OptionDef d) -> String
+  def zsh_specs: (Mdlogbook::OptionDef d) -> Array[String]
+  def zsh_escape_desc: (String desc) -> String
+  def zsh_arg_part: (Mdlogbook::OptionDef d) -> String
+  def zsh_action: (Mdlogbook::OptionDef d) -> String
+end