fix: resolve all rubocop offenses

- Add documentation comments on all modules
- Split Config.load into merge_yaml!/merge_env! private helpers
- Split UrlParser.parse into validate_scheme!/extract_path_and_iid
- Extract build_option_parser/define_info_options from parse_args
- Extract run() from main to reduce method length
- Use Regexp.new for IMAGE_PATTERN to avoid %r{} parser conflict
- Replace $stderr.puts with warn

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Matthieu Ciappara

bin/issue-md

@@ -40,6 +40,7 @@ class IssueMdError < StandardError; end
 
 # ── Configuration ─────────────────────────────────────────────────────────────
 
+# 4-layer config: defaults < config.yml < env vars < CLI flags.
 module Config
   CONFIG_DIR  = File.expand_path('~/.issue-md')
   CONFIG_PATH = File.join(CONFIG_DIR, 'config.yml')
@@ -54,45 +55,67 @@ module Config
 
   def self.load(cli_overrides = {})
     config = DEFAULTS.dup
+    merge_yaml!(config)
+    merge_env!(config)
+    cli_overrides.each { |k, v| config[k] = v unless v.nil? }
+    config
+  end
 
-    if File.exist?(CONFIG_PATH)
-      yaml = YAML.safe_load(File.read(CONFIG_PATH)) || {}
-      yaml.each { |k, v| config[k] = v unless v.nil? }
-    end
+  def self.merge_yaml!(config)
+    return unless File.exist?(CONFIG_PATH)
 
+    yaml = YAML.safe_load(File.read(CONFIG_PATH)) || {}
+    yaml.each { |k, v| config[k] = v unless v.nil? }
+  end
+
+  def self.merge_env!(config)
     ENV_MAPPING.each do |env_key, config_key|
       config[config_key] = ENV[env_key] if ENV.key?(env_key)
     end
-
-    cli_overrides.each { |k, v| config[k] = v unless v.nil? }
-    config
   end
+
+  private_class_method :merge_yaml!, :merge_env!
 end
 
 # ── URL parsing ───────────────────────────────────────────────────────────────
 
+# Extracts base_url, project_path, and issue_iid from a GitLab issue URL.
 module UrlParser
   def self.parse(url)
     uri = URI.parse(url)
-    raise IssueMdError, "Expected an http(s) URL, got: #{url}" unless %w[http https].include?(uri.scheme)
+    validate_scheme!(uri, url)
+    project_path, iid = extract_path_and_iid(uri, url)
+    host = uri.port && ![80, 443].include?(uri.port) ? "#{uri.host}:#{uri.port}" : uri.host
+
+    { base_url: "#{uri.scheme}://#{host}", project_path: project_path, issue_iid: iid }
+  end
 
+  def self.validate_scheme!(uri, url)
+    return if %w[http https].include?(uri.scheme)
+
+    raise IssueMdError, "Expected an http(s) URL, got: #{url}"
+  end
+
+  def self.extract_path_and_iid(uri, url)
     path_before, _, issue_segment = uri.path.partition('/-/issues/')
     raise IssueMdError, "URL does not look like a GitLab issue: #{url}" if issue_segment.empty?
 
     iid = issue_segment.split('/').first.to_i
     raise IssueMdError, "Could not extract issue IID from: #{url}" if iid.zero?
 
-    host = uri.port && ![80, 443].include?(uri.port) ? "#{uri.host}:#{uri.port}" : uri.host
-
-    { base_url: "#{uri.scheme}://#{host}",
-      project_path: path_before.delete_prefix('/'),
-      issue_iid: iid }
+    [path_before.delete_prefix('/'), iid]
   end
+
+  private_class_method :validate_scheme!, :extract_path_and_iid
 end
 
 # ── Image downloading ─────────────────────────────────────────────────────────
 
+# Downloads GitLab /uploads/ images and rewrites markdown references to local paths.
 module ImageDownloader
+  # Matches GitLab markdown image references: ![alt](/uploads/path){optional-attrs}
+  IMAGE_PATTERN = Regexp.new('!\[([^\]]*)\]\((/uploads/[^)]+)\)(\{[^}]*\})?').freeze
+
   module_function
 
   def build_opts(base_url:, token:, project_path:, dest_dir:)
@@ -109,7 +132,7 @@ module ImageDownloader
     state = { image_dir: File.join(dest_dir, '.issue-md-images'), downloaded: false }
     opts = { gitlab_url: gitlab_url, project_path: project_path, token: token }
 
-    text.gsub(%r{!\[([^\]]*)\]\((/uploads/[^)]+)\)(\{[^}]*\})?}) do
+    text.gsub(IMAGE_PATTERN) do
       replace_reference(::Regexp.last_match(1), ::Regexp.last_match(2), opts, state)
     end
   end
@@ -173,6 +196,7 @@ end
 
 # ── Issue formatting ──────────────────────────────────────────────────────────
 
+# Formats a GitLab issue as markdown with header, comments, and related links.
 module IssueFormatter
   module_function
 
@@ -227,63 +251,82 @@ def fetch_issue(client, project_path, issue_iid, img_opts)
 end
 
 def build_client(base_url, token)
-  raise IssueMdError, 'Missing GitLab API token (set GITLAB_API_TOKEN, use -t, or add to ~/.issue-md/config.yml)' unless token
+  unless token
+    raise IssueMdError,
+          'Missing GitLab API token (set GITLAB_API_TOKEN, use -t, or add to ~/.issue-md/config.yml)'
+  end
 
   Gitlab.client(endpoint: "#{base_url}/api/v4", private_token: token)
 end
 
 # ── Argument parsing ──────────────────────────────────────────────────────────
 
-def parse_args(argv)
-  cli_overrides = {}
-  opts = {}
-
-  parser = OptionParser.new do |o|
+def build_option_parser(cli_overrides, opts)
+  OptionParser.new do |o|
     o.banner = 'Usage: issue-md [options] <ISSUE_URL>'
     o.on('-t', '--token TOKEN', 'GitLab API token') { |v| cli_overrides['gitlab_api_token'] = v }
     o.on('-o', '--output FILE', 'Write markdown to FILE instead of stdout') { |v| opts[:output_file] = v }
     o.on('-d', '--download-images DIR', 'Download images to DIR') { |v| opts[:download_dir] = v }
-    o.on('-v', '--version', 'Show version and exit') { puts "issue-md #{VERSION}"; exit 0 }
-    o.on('-h', '--help', 'Show this help') { puts o; exit 0 }
+    define_info_options(o)
   end
+end
+
+def define_info_options(opts)
+  opts.on('-v', '--version', 'Show version and exit') do
+    puts "issue-md #{VERSION}"
+    exit 0
+  end
+  opts.on('-h', '--help', 'Show this help') do
+    puts opts
+    exit 0
+  end
+end
 
+def parse_args(argv)
+  cli_overrides = {}
+  opts = {}
+  parser = build_option_parser(cli_overrides, opts)
   parser.parse!(argv)
   raise IssueMdError, "Expected exactly one issue URL argument.\n\n#{parser}" if argv.size != 1
 
-  config = Config.load(cli_overrides)
-  parsed = UrlParser.parse(argv.first)
-
-  opts.merge(config: config, **parsed)
+  opts.merge(config: Config.load(cli_overrides), **UrlParser.parse(argv.first))
 end
 
 # ── Main ──────────────────────────────────────────────────────────────────────
 
-def main
-  args = parse_args(ARGV)
-  token = args[:config]['gitlab_api_token']
-  client = build_client(args[:base_url], token)
-
-  img_opts = nil
-  if args[:download_dir]
-    img_opts = ImageDownloader.build_opts(
-      base_url: args[:base_url], token: token,
-      project_path: args[:project_path], dest_dir: args[:download_dir]
-    )
-  end
+def build_image_opts(args, token)
+  return nil unless args[:download_dir]
 
-  markdown = fetch_issue(client, args[:project_path], args[:issue_iid], img_opts)
+  ImageDownloader.build_opts(
+    base_url: args[:base_url], token: token,
+    project_path: args[:project_path], dest_dir: args[:download_dir]
+  )
+end
 
-  if args[:output_file]
-    File.write(args[:output_file], markdown)
-    $stderr.puts "Written to #{args[:output_file]}"
+def write_output(markdown, output_file)
+  if output_file
+    File.write(output_file, markdown)
+    warn "Written to #{output_file}"
   else
     puts markdown
   end
+end
+
+def run(args)
+  token = args[:config]['gitlab_api_token']
+  client = build_client(args[:base_url], token)
+  img_opts = build_image_opts(args, token)
+  markdown = fetch_issue(client, args[:project_path], args[:issue_iid], img_opts)
+  write_output(markdown, args[:output_file])
+end
+
+def main
+  run(parse_args(ARGV))
 rescue IssueMdError => e
-  $stderr.puts "error: #{e.message}"
+  warn "error: #{e.message}"
   exit 1
 rescue Gitlab::Error::ResponseError => e
-  $stderr.puts "GitLab API error: #{e.message}"
+  warn "GitLab API error: #{e.message}"
   exit 1
 rescue Interrupt
   exit 130