jsx_rosetta 0.5.1 → 0.6.0

data/skills/jsx-rosetta-resolve-todos/tools/apply_substitutions.rb

@@ -0,0 +1,292 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# apply_substitutions.rb
+#
+# Mechanical resolution of jsx_rosetta TODOs of the form:
+#   # TODO: (attribute|style declaration) "<name>" dropped — couldn't translate: <RHS>
+#
+# A user-supplied YAML config declares:
+#   - match:  a regex with one capture group, applied to <RHS>; the capture
+#             becomes the lookup key
+#   - tokens: a map from lookup key → { value, tailwind?, category?, notes? }
+#
+# When <RHS> matches and the captured key is in `tokens`, the value is spliced
+# into the `render Foo.new(...)` immediately below the TODO. Only single-line
+# render calls with string-literal `style:` (or no `style:`) are touched;
+# anything more complex is left untouched.
+#
+# Always re-parses the post-edit file with `ruby -c`; if parsing fails the
+# file is reverted and the run is reported as `parse_failed`.
+#
+# Usage:
+#   apply_substitutions.rb --config <yaml> [--dry-run] [--quiet] <file_or_dir>...
+
+require 'yaml'
+require 'json'
+require 'tempfile'
+require 'optparse'
+
+# --- config ------------------------------------------------------------------
+
+CONFIG_SCHEMA_HINT = <<~MSG.freeze
+  Config must be YAML with:
+    match:  '<regex with one capture group>'
+    tokens:
+      <capture>: { value: <int|string|null>, ... }
+      ...
+MSG
+
+def load_config(path)
+  raw = YAML.safe_load(File.read(path))
+  unless raw.is_a?(Hash) && raw['match'].is_a?(String) && raw['tokens'].is_a?(Hash)
+    abort "invalid config at #{path}\n#{CONFIG_SCHEMA_HINT}"
+  end
+  user_re = Regexp.new(raw['match'])
+  unless user_re.match("").is_a?(NilClass) || user_re.named_captures.any? || user_re.match("x") || user_re.source.include?('(')
+    # weak check; just confirm there's at least one paren group (capture)
+  end
+  raw['_user_re'] = user_re
+  raw['tokens'].freeze
+  raw.freeze
+  raw
+end
+
+# --- regex -------------------------------------------------------------------
+
+# Built dynamically from config so the user's `match:` controls what gets
+# touched. Captures: 1=indent, 2=kind, 3=attr_name, 4+=user-regex captures
+# (capture 4 is the lookup key by convention).
+def build_todo_re(user_re_source)
+  /\A(\s*)# TODO: (attribute|style declaration) "(.+?)" dropped — couldn't translate: #{user_re_source}\s*\z/
+end
+
+# Single-line `render Foo.new(...)` (with optional `do ...`).
+RENDER_RE = /\A(\s*)render\s+([A-Z][A-Za-z0-9_:]*)\.new(\((.*)\))?(\s+do\b.*)?\s*\z/.freeze
+
+RUBY_IDENT_RE = /\A[a-z_][a-z0-9_]*\z/.freeze
+
+Drop = Struct.new(:kind, :name, :key, :line_index, :raw_line, keyword_init: true)
+
+# --- helpers -----------------------------------------------------------------
+
+def camel_to_snake(s)
+  s.gsub(/([a-z0-9])([A-Z])/) { "#{$1}_#{$2}" }.downcase.tr('-', '_')
+end
+
+def valid_ruby_kwarg?(name) = RUBY_IDENT_RE.match?(name)
+
+def quote_string(s)
+  if s.include?("'") && !s.include?('"')
+    "\"#{s}\""
+  elsif s.include?('"') && !s.include?("'")
+    "'#{s}'"
+  else
+    "'#{s.gsub('\\', '\\\\\\\\').gsub("'", "\\\\'")}'"
+  end
+end
+
+def render_inline_style(value)
+  value.is_a?(Numeric) ? "#{value}px" : value.to_s
+end
+
+def render_kwarg_value(value)
+  case value
+  when Numeric then value.to_s
+  when String  then quote_string(value)
+  end
+end
+
+def lookup(config, key)
+  entry = config['tokens'][key]
+  return nil unless entry.is_a?(Hash)
+  entry['value']
+end
+
+def parse_todo(line, idx, todo_re)
+  m = todo_re.match(line)
+  return nil unless m
+  Drop.new(kind: (m[2] == 'attribute' ? :attribute : :style_decl),
+           name: m[3], key: m[4], line_index: idx, raw_line: line)
+end
+
+# --- splice ------------------------------------------------------------------
+
+def splice(render_line, drops, config)
+  m = RENDER_RE.match(render_line)
+  return nil unless m
+  indent, klass, has_parens, args, trailing = m[1], m[2], !m[3].nil?, (m[4] || ''), (m[5] || '')
+
+  resolved = []
+  unresolved = []
+  style_adds = []
+  attr_adds = []
+
+  drops.each do |d|
+    val = lookup(config, d.key)
+    if val.nil?
+      unresolved << d
+      next
+    end
+    case d.kind
+    when :style_decl
+      style_adds << "#{d.name}: #{render_inline_style(val)}"
+      resolved << d
+    when :attribute
+      qv = render_kwarg_value(val)
+      kwarg = camel_to_snake(d.name)
+      if qv.nil? || !valid_ruby_kwarg?(kwarg)
+        unresolved << d
+      else
+        attr_adds << "#{kwarg}: #{qv}"
+        resolved << d
+      end
+    end
+  end
+
+  return nil if resolved.empty?
+
+  new_args = args.dup
+
+  if style_adds.any?
+    str_style_re = /style:\s*(['"])(.*?)\1/
+    if (sm = new_args.match(str_style_re))
+      quote = sm[1]
+      existing_parts = sm[2].split(';').map(&:strip).reject(&:empty?)
+      combined = (existing_parts + style_adds).join('; ') + ';'
+      new_args = new_args.sub(str_style_re, "style: #{quote}#{combined}#{quote}")
+    elsif new_args.match?(/\bstyle:\s*[\{\w]/)
+      # Hash-form style: { ... } or symbol/var ref. Don't try to merge.
+      style_adds.each do
+        d = resolved.reverse.find { |x| x.kind == :style_decl }
+        next unless d
+        resolved.delete(d)
+        unresolved << d
+      end
+      style_adds.clear
+    else
+      kwarg = "style: '#{style_adds.join('; ')};'"
+      new_args = new_args.empty? ? kwarg : "#{kwarg}, #{new_args}"
+      style_adds.clear
+    end
+  end
+
+  if attr_adds.any?
+    new_args = new_args.empty? ? attr_adds.join(', ') : "#{new_args}, #{attr_adds.join(', ')}"
+  end
+
+  return nil if resolved.empty?
+
+  new_line = if has_parens || !new_args.empty?
+    "#{indent}render #{klass}.new(#{new_args})#{trailing}\n"
+  else
+    "#{indent}render #{klass}.new#{trailing}\n"
+  end
+
+  { new_line: new_line, resolved: resolved, unresolved: unresolved }
+end
+
+# --- file processing ---------------------------------------------------------
+
+def process_file(path, config, todo_re)
+  lines = File.read(path).lines
+  out = []
+  pending = []
+  resolved = 0
+  skipped = 0
+
+  i = 0
+  while i < lines.length
+    line = lines[i]
+    if (drop = parse_todo(line, i, todo_re))
+      pending << drop
+      i += 1
+      next
+    end
+
+    if pending.any?
+      result = splice(line, pending, config)
+      if result
+        result[:unresolved].each { |d| out << d.raw_line; skipped += 1 }
+        out << result[:new_line]
+        resolved += result[:resolved].length
+      else
+        pending.each { |d| out << d.raw_line; skipped += 1 }
+        out << line
+      end
+      pending = []
+    else
+      out << line
+    end
+    i += 1
+  end
+
+  pending.each { |d| out << d.raw_line; skipped += 1 }
+
+  return { file: path, resolved: 0, skipped: skipped } if resolved.zero?
+
+  new_content = out.join
+  ok = Tempfile.create(['validate', '.rb']) do |tf|
+    tf.write(new_content); tf.flush
+    system('ruby', '-c', tf.path, out: File::NULL, err: File::NULL)
+  end
+
+  unless ok
+    return { file: path, resolved: 0, skipped: skipped + resolved, parse_failed: true }
+  end
+
+  { file: path, resolved: resolved, skipped: skipped, new_content: new_content }
+end
+
+# --- CLI ---------------------------------------------------------------------
+
+opts = { dry_run: false, quiet: false, config: nil }
+OptionParser.new do |o|
+  o.banner = "usage: apply_substitutions.rb --config <yaml> [--dry-run] [--quiet] <file_or_dir>..."
+  o.on('--config PATH') { |v| opts[:config] = v }
+  o.on('--dry-run')     { opts[:dry_run] = true }
+  o.on('--quiet')       { opts[:quiet] = true }
+end.parse!(ARGV)
+
+abort "missing --config <yaml>\n#{CONFIG_SCHEMA_HINT}" unless opts[:config]
+abort "config not found: #{opts[:config]}" unless File.file?(opts[:config])
+abort "no input files" if ARGV.empty?
+
+config = load_config(opts[:config])
+todo_re = build_todo_re(config['_user_re'].source)
+
+paths = ARGV.flat_map do |arg|
+  if File.directory?(arg)
+    Dir.glob(File.join(arg, '**', '*.rb'))
+  elsif File.file?(arg)
+    [arg]
+  else
+    warn "skip: #{arg} not found"
+    []
+  end
+end
+
+totals = { files: paths.length, modified: 0, resolved: 0, skipped: 0, parse_failed: 0 }
+
+paths.each do |p|
+  r = process_file(p, config, todo_re)
+  totals[:resolved] += r[:resolved]
+  totals[:skipped]  += r[:skipped]
+
+  if r[:parse_failed]
+    totals[:parse_failed] += 1
+    puts JSON.generate(file: r[:file], parse_failed: true) unless opts[:quiet]
+  elsif r[:resolved] > 0
+    totals[:modified] += 1
+    File.write(p, r[:new_content]) unless opts[:dry_run]
+    puts JSON.generate(file: r[:file], resolved: r[:resolved], skipped: r[:skipped]) unless opts[:quiet]
+  end
+end
+
+puts ''
+puts "config:           #{opts[:config]}"
+puts "files scanned:    #{totals[:files]}"
+puts "files modified:   #{totals[:modified]}#{opts[:dry_run] ? ' (dry-run)' : ''}"
+puts "TODOs resolved:   #{totals[:resolved]}"
+puts "TODOs left:       #{totals[:skipped]}"
+puts "parse failures:   #{totals[:parse_failed]}"

data/skills/jsx-rosetta-resolve-todos/tools/diff_corpus.rb

@@ -0,0 +1,161 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# diff_corpus.rb
+#
+# Tally `# TODO:` comments by category in two directories (typically a
+# "before" and "after" snapshot of generated output) and report the
+# per-category delta. Lets the user see the impact of a resolve-todos
+# pipeline pass and confirm the skill's claims aren't pure marketing.
+#
+# Usage:
+#   diff_corpus.rb [--json] <before_dir> <after_dir>
+#
+# Categories match the SKILL.md routing table. Sharpened TODOs (those
+# tagged `# TODO[category]:`) are counted separately so the delta shows
+# both removal of original TODOs and creation of sharpened replacements.
+
+require 'json'
+require 'optparse'
+
+# Original-form TODOs the gem emits. Order matters: more specific patterns
+# first, generic last.
+CATEGORIES = [
+  # "chain_ref" = drops whose RHS starts with `<ident>.<ident>...` (token systems,
+  # GraphQL field accesses, prop chains). `apply_substitutions.rb` resolves the
+  # subset of these that match its configured token regex.
+  [:chain_ref_drop,        /^\s*# TODO: (?:attribute|style declaration) ".+?" dropped — couldn't translate: \w+\.\w/],
+  [:other_drop,            /^\s*# TODO: (?:attribute|style declaration) ".+?" dropped/],
+  [:promoted_ivar,         /^\s*# TODO: render condition references binding\(s\) promoted to @ivar/],
+  [:react_hooks,           /^\s*# TODO: React hooks detected/],
+  [:apollo_hooks,          /^\s*# TODO: Apollo data-fetching hooks detected/],
+  [:nextjs_navigation,     /^\s*# TODO: Next\.js navigation hooks detected/],
+  [:event_handler,         /^\s*# TODO: translate the original JSX `\w+` handler/],
+  [:module_constants,      /^\s*# TODO: module-level constants/],
+  [:generic_js_bailout,    /^\s*# TODO: translate JS to Ruby — original/],
+  [:generic_translate,     /^\s*# TODO: translate "/],
+  [:generic_condition,     /^\s*# TODO: translate condition:/],
+  [:other_todo,            /^\s*# TODO:/]
+].freeze
+
+# Sharpened TODOs emitted by recipes. Captured separately to show
+# "compression" — original removed, sharpened added.
+SHARPENED_RE = /^\s*# TODO\[([a-z_:-]+)\]:/.freeze
+
+def tally(dir)
+  counts = Hash.new(0)
+  sharp_counts = Hash.new(0)
+  todo_files = 0
+  Dir.glob(File.join(dir, '**', '*.rb')).each do |path|
+    file_had_todo = false
+    File.foreach(path) do |line|
+      if (m = SHARPENED_RE.match(line))
+        sharp_counts[m[1].to_sym] += 1
+        counts[:_sharpened_total] += 1
+        file_had_todo = true
+        next
+      end
+      CATEGORIES.each do |sym, re|
+        if re.match?(line)
+          counts[sym] += 1
+          file_had_todo = true
+          break
+        end
+      end
+    end
+    todo_files += 1 if file_had_todo
+  end
+  { categories: counts, sharpened: sharp_counts, files_with_todos: todo_files }
+end
+
+def fmt_delta(n)
+  n.zero? ? '   .' : (n.positive? ? "+#{n}" : n.to_s).rjust(6)
+end
+
+def emit_text(before, after, before_dir, after_dir)
+  cats = (before[:categories].keys + after[:categories].keys).uniq
+  puts "before:  #{before_dir}"
+  puts "after:   #{after_dir}"
+  puts ""
+  puts "                          before  after  delta"
+  puts "  ─────────────────────────────────────────────"
+
+  total_before = 0
+  total_after = 0
+  CATEGORIES.map(&:first).each do |sym|
+    next unless cats.include?(sym)
+    b = before[:categories][sym]
+    a = after[:categories][sym]
+    total_before += b
+    total_after  += a
+    next if b.zero? && a.zero?
+    puts "  %-22s  %6d %6d  %s" % [sym, b, a, fmt_delta(a - b)]
+  end
+
+  # _sharpened_total is the synthetic total
+  sb = before[:categories][:_sharpened_total]
+  sa = after[:categories][:_sharpened_total]
+  total_before += sb
+  total_after  += sa
+  if sb.positive? || sa.positive?
+    puts "  %-22s  %6d %6d  %s" % ['sharpened (compressed)', sb, sa, fmt_delta(sa - sb)]
+  end
+
+  puts "  ─────────────────────────────────────────────"
+  puts "  %-22s  %6d %6d  %s" % ['total', total_before, total_after, fmt_delta(total_after - total_before)]
+  puts ""
+  puts "  files with any TODO:    #{before[:files_with_todos]} → #{after[:files_with_todos]}"
+
+  if (before[:sharpened].any? || after[:sharpened].any?)
+    puts ""
+    puts "  Sharpened-TODO breakdown by tag:"
+    tags = (before[:sharpened].keys + after[:sharpened].keys).uniq.sort
+    tags.each do |tag|
+      b = before[:sharpened][tag]
+      a = after[:sharpened][tag]
+      puts "    %-22s  %6d %6d  %s" % [tag, b, a, fmt_delta(a - b)]
+    end
+  end
+end
+
+def emit_json(before, after, before_dir, after_dir)
+  cats = (before[:categories].keys + after[:categories].keys).uniq.sort
+  out = {
+    before_dir: before_dir,
+    after_dir: after_dir,
+    files_with_todos: { before: before[:files_with_todos], after: after[:files_with_todos] },
+    categories: cats.to_h { |sym|
+      b = before[:categories][sym]
+      a = after[:categories][sym]
+      [sym, { before: b, after: a, delta: a - b }]
+    },
+    sharpened_by_tag: (before[:sharpened].keys + after[:sharpened].keys).uniq.sort.to_h { |tag|
+      b = before[:sharpened][tag]
+      a = after[:sharpened][tag]
+      [tag, { before: b, after: a, delta: a - b }]
+    }
+  }
+  puts JSON.pretty_generate(out)
+end
+
+# --- CLI ---
+
+opts = { json: false }
+OptionParser.new do |o|
+  o.banner = "usage: diff_corpus.rb [--json] <before_dir> <after_dir>"
+  o.on('--json') { opts[:json] = true }
+end.parse!(ARGV)
+
+abort "expected two directory arguments" unless ARGV.size == 2
+before_dir, after_dir = ARGV
+abort "not a directory: #{before_dir}" unless File.directory?(before_dir)
+abort "not a directory: #{after_dir}" unless File.directory?(after_dir)
+
+before = tally(before_dir)
+after  = tally(after_dir)
+
+if opts[:json]
+  emit_json(before, after, before_dir, after_dir)
+else
+  emit_text(before, after, before_dir, after_dir)
+end

data/skills/jsx-rosetta-resolve-todos/tools/discover_bailouts.rb

@@ -0,0 +1,211 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# discover_bailouts.rb
+#
+# Scan a corpus of jsx_rosetta-generated .rb files and surface the dropped-
+# expression RHS values that show up most often. Used to:
+#   - decide which substitutions are worth automating (apply_substitutions.rb)
+#   - spot clusters that look like design-system tokens (e.g. many `theme.X`,
+#     `vars.X`, `tokens.X.Y` references) and suggest a `match:` regex
+#
+# This tool makes no judgements about *what* a reference means — only what
+# patterns repeat. Decisions about how to map them belong to the human (or to
+# the LLM-driven recipes in the skill).
+#
+# Usage:
+#   discover_bailouts.rb [--top N] [--json] [--all-todos] <file_or_dir>...
+#
+#   --top N        Show top N entries per section (default 25).
+#   --json         Emit machine-readable JSON instead of text.
+#   --all-todos    Also tally non-attribute/style TODO categories (hooks,
+#                  module constants, generic JS bailouts) so you can see
+#                  the full distribution. Off by default.
+
+require 'json'
+require 'optparse'
+
+# Match a "dropped" TODO. Captures: kind, attr_name, RHS.
+DROP_RE  = /\A\s*# TODO: (attribute|style declaration) "(.+?)" dropped — couldn't translate: (.+?)\s*\z/.freeze
+
+# Other generic TODO categories — counted only when --all-todos is set.
+OTHER_RE = /\A\s*# TODO: (.+?)\s*\z/.freeze
+
+# Detect a "<root>.<member>" or "<root>.<member>.<member>..." chain at the
+# start of an RHS. Captures: root, full chain.
+CHAIN_RE = /\A(\$?\b[a-z_][A-Za-z0-9_]*)((?:\.[A-Za-z_][A-Za-z0-9_]*)+)/.freeze
+
+# Detect a tagged template literal like `theme.colors.primary` inside backticks.
+TPL_RE = /`[^`]*\$\{([^}]+)\}/.freeze
+
+# --- collection --------------------------------------------------------------
+
+def gather(paths)
+  drops = []   # [{ kind:, attr:, rhs:, file:, line: }]
+  others = Hash.new(0)
+
+  paths.each do |p|
+    File.foreach(p).with_index(1) do |line, lineno|
+      if (m = DROP_RE.match(line))
+        drops << { kind: m[1], attr: m[2], rhs: m[3], file: p, line: lineno }
+      elsif (m = OTHER_RE.match(line))
+        # Normalize generic TODOs by their leading phrase up to "—" or ":"
+        head = m[1].split(/[—:]/).first.strip
+        others[head] += 1
+      end
+    end
+  end
+
+  [drops, others]
+end
+
+# --- analysis ----------------------------------------------------------------
+
+def chain_root(rhs)
+  if (m = CHAIN_RE.match(rhs))
+    m[1]
+  end
+end
+
+def chain_full(rhs)
+  if (m = CHAIN_RE.match(rhs))
+    m[1] + m[2]
+  end
+end
+
+def template_chains(rhs)
+  rhs.scan(TPL_RE).flat_map { |(inner)| [chain_full(inner.strip)].compact }
+end
+
+# Group RHS strings by likely "system" — the root identifier of a member chain.
+# Returns: { "token" => { count: N, distinct_keys: [...], sample_rhs: [...] }, ... }
+def cluster_by_root(drops)
+  clusters = Hash.new { |h, k| h[k] = { count: 0, keys: Hash.new(0), samples: [] } }
+
+  drops.each do |d|
+    rhs = d[:rhs]
+
+    # Plain chain at start of RHS
+    if (root = chain_root(rhs))
+      key = chain_full(rhs)
+      clusters[root][:count] += 1
+      clusters[root][:keys][key] += 1
+      clusters[root][:samples] << rhs if clusters[root][:samples].size < 5
+    end
+
+    # Chains inside template literals (e.g. `1px solid ${token.colorBorder}`)
+    template_chains(rhs).each do |chain|
+      root = chain.split('.').first
+      clusters[root][:count] += 1
+      clusters[root][:keys][chain] += 1
+      clusters[root][:samples] << rhs if clusters[root][:samples].size < 5
+    end
+  end
+
+  clusters
+end
+
+def suggest_regex(root, chains)
+  # Look at the chain depths to pick `<root>\.(\w+)` vs `<root>\.\w+\.(\w+)` etc.
+  depths = chains.keys.map { |c| c.split('.').size }
+  depth = depths.tally.max_by { |_, n| n }.first
+  esc_root = Regexp.escape(root)
+  case depth
+  when 2 then "#{esc_root}\\.(\\w+)"
+  when 3 then "#{esc_root}\\.\\w+\\.(\\w+)"
+  when 4 then "#{esc_root}\\.\\w+\\.\\w+\\.(\\w+)"
+  else        "#{esc_root}((?:\\.\\w+)+)"
+  end
+end
+
+# --- output ------------------------------------------------------------------
+
+def emit_text(drops, others, clusters, top:, all_todos:)
+  puts "=== Dropped expressions ==="
+  puts "  total: #{drops.size}"
+  by_kind = drops.group_by { |d| d[:kind] }.transform_values(&:count)
+  by_kind.each { |k, n| puts "    #{k}: #{n}" }
+  puts
+
+  puts "=== Top #{top} dropped RHS values (verbatim) ==="
+  drops.map { |d| d[:rhs] }.tally.sort_by { |_, n| -n }.first(top).each do |rhs, n|
+    puts "  #{n.to_s.rjust(5)}  #{rhs.length > 90 ? rhs[0, 87] + '...' : rhs}"
+  end
+  puts
+
+  puts "=== Repeating member chains (likely design-system / lookup tables) ==="
+  if clusters.empty?
+    puts "  (none)"
+  else
+    sorted = clusters.sort_by { |_, c| -c[:count] }
+    sorted.first(top).each do |root, c|
+      puts ""
+      puts "  root: #{root}   total refs: #{c[:count]}   distinct keys: #{c[:keys].size}"
+      puts "  suggested match regex:  '#{suggest_regex(root, c[:keys])}'"
+      puts "  top keys:"
+      c[:keys].sort_by { |_, n| -n }.first(8).each do |key, n|
+        puts "    #{n.to_s.rjust(4)}  #{key}"
+      end
+    end
+  end
+  puts
+
+  if all_todos
+    puts "=== Other TODO categories (count by leading phrase) ==="
+    others.sort_by { |_, n| -n }.first(top).each do |head, n|
+      puts "  #{n.to_s.rjust(5)}  #{head}"
+    end
+  end
+end
+
+def emit_json(drops, others, clusters, all_todos:)
+  out = {
+    drops: {
+      total: drops.size,
+      by_kind: drops.group_by { |d| d[:kind] }.transform_values(&:count),
+      top_rhs: drops.map { |d| d[:rhs] }.tally.sort_by { |_, n| -n }.first(50).to_h
+    },
+    chains: clusters.sort_by { |_, c| -c[:count] }.map { |root, c|
+      [root, {
+        count: c[:count],
+        distinct_keys: c[:keys].size,
+        suggested_match: suggest_regex(root, c[:keys]),
+        top_keys: c[:keys].sort_by { |_, n| -n }.first(20).to_h
+      }]
+    }.to_h
+  }
+  out[:other_todos] = others.sort_by { |_, n| -n }.first(50).to_h if all_todos
+  puts JSON.pretty_generate(out)
+end
+
+# --- CLI ---------------------------------------------------------------------
+
+opts = { top: 25, json: false, all_todos: false }
+OptionParser.new do |o|
+  o.banner = "usage: discover_bailouts.rb [--top N] [--json] [--all-todos] <file_or_dir>..."
+  o.on('--top N', Integer) { |v| opts[:top] = v }
+  o.on('--json')           { opts[:json] = true }
+  o.on('--all-todos')      { opts[:all_todos] = true }
+end.parse!(ARGV)
+
+abort "no input files" if ARGV.empty?
+
+paths = ARGV.flat_map do |arg|
+  if File.directory?(arg)
+    Dir.glob(File.join(arg, '**', '*.rb'))
+  elsif File.file?(arg)
+    [arg]
+  else
+    warn "skip: #{arg} not found"
+    []
+  end
+end
+
+drops, others = gather(paths)
+clusters = cluster_by_root(drops)
+
+if opts[:json]
+  emit_json(drops, others, clusters, all_todos: opts[:all_todos])
+else
+  emit_text(drops, others, clusters, top: opts[:top], all_todos: opts[:all_todos])
+end