docscribe 1.1.0 → 1.2.1

data/exe/docscribe

@@ -1,129 +1,5 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'optparse'
-require 'docscribe/config'
-require 'docscribe/inline_rewriter'
-
-options = {
-  stdin: false,
-  write: false, # rewrite files in place
-  check: false, # dry-run (exit 1 if any file would change)
-  rewrite: false, # replace existing comment blocks when inserting
-  config: nil
-}
-
-parser = OptionParser.new do |opts|
-  opts.banner = 'Usage: docscribe [options] [files...]'
-  opts.on('--stdin', 'Read code from STDIN and print with docs inserted') { options[:stdin] = true }
-  opts.on('--write', 'Rewrite files in place') { options[:write] = true }
-  opts.on('--check', 'Dry-run: exit 1 if any file would change') { options[:check] = true }
-  opts.on('--rewrite', 'Replace existing comment blocks above methods') { options[:rewrite] = true }
-  opts.on('--config PATH', 'Path to config YAML (default: docscribe.yml)') { |v| options[:config] = v }
-  opts.on('--version', 'Print version and exit') do
-    require 'docscribe/version'
-    puts Docscribe::VERSION
-    exit
-  end
-  opts.on('-h', '--help', 'Show this help') do
-    puts opts
-    exit
-  end
-end
-
-parser.parse!(ARGV)
-
-conf = Docscribe::Config.load(options[:config])
-
-def transform(code, replace:, config:)
-  Docscribe::InlineRewriter.insert_comments(code, rewrite: replace, config: config)
-end
-
-def rewrite(code, replace:)
-  Docscribe::InlineRewriter.insert_comments(code, rewrite: replace)
-end
-
-def expand_paths(args)
-  files = []
-
-  args.each do |path|
-    if File.directory?(path)
-      files.concat(Dir.glob(File.join(path, '**', '*.rb')))
-    elsif File.file?(path)
-      files << path
-    else
-      warn "Skipping missing path: #{path}"
-    end
-  end
-
-  files.uniq.sort
-end
-
-if options[:stdin]
-  code = $stdin.read
-  puts rewrite(code, replace: options[:rewrite])
-  exit 0
-end
-
-if ARGV.empty?
-  warn 'No input. Use --stdin or pass file paths. See --help.'
-  exit 1
-end
-
-$stdout.sync = true
-
-paths = expand_paths(ARGV)
-if paths.empty?
-  warn 'No files found. Pass files or directories (e.g. `docscribe --check lib`).'
-  exit 1
-end
-
-changed = false
-checked_ok = 0
-checked_fail = 0
-corrected = 0
-fail_paths = []
-
-paths.each do |path|
-  src = File.read(path)
-  out = transform(src, replace: options[:rewrite], config: conf)
-
-  if options[:check]
-    if out == src
-      print '.'
-      checked_ok += 1
-    else
-      print 'F'
-      checked_fail += 1
-      changed = true
-      fail_paths << path
-    end
-
-  elsif options[:write]
-    if out == src
-      print '.'
-    else
-      File.write(path, out)
-      print 'C'
-      corrected += 1
-    end
-
-  else
-    puts out
-  end
-end
-
-if options[:check]
-  puts
-  if checked_fail.zero?
-    puts "Docscribe: OK (#{checked_ok} files checked)"
-  else
-    puts "Docscribe: FAILED (#{checked_fail} failing, #{checked_ok} ok)"
-    fail_paths.each { |p| warn "Missing docs: #{p}" }
-  end
-elsif options[:write]
-  puts
-  puts "Docscribe: updated #{corrected} file(s)" if corrected.positive?
-end
-
-exit(options[:check] && changed ? 1 : 0)
+require 'docscribe/cli'
+exit Docscribe::CLI.run(ARGV)

data/lib/docscribe/cli/config_builder.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'docscribe/config'
+
+module Docscribe
+  module CLI
+    module ConfigBuilder
+      module_function
+
+      # Build an effective config by applying CLI overrides on top of a base config.
+      #
+      # CLI overrides currently affect:
+      # - method/file include and exclude filters
+      # - RBS enablement and additional signature directories
+      # - Sorbet enablement and RBI directories
+      #
+      # If no relevant CLI override is present, the original config is returned unchanged.
+      #
+      # @note module_function: when included, also defines #build (instance visibility: private)
+      # @param [Docscribe::Config] base base config loaded from YAML/defaults
+      # @param [Hash] options parsed CLI options
+      # @return [Docscribe::Config] merged effective config
+      def build(base, options)
+        needs_override =
+          options[:include].any? ||
+          options[:exclude].any? ||
+          options[:include_file].any? ||
+          options[:exclude_file].any? ||
+          options[:rbs] ||
+          options[:sig_dirs].any? ||
+          options[:sorbet] ||
+          options[:rbi_dirs].any?
+
+        return base unless needs_override
+
+        raw = Marshal.load(Marshal.dump(base.raw))
+
+        raw['filter'] ||= {}
+        raw['filter']['include'] = Array(raw['filter']['include']) + options[:include]
+        raw['filter']['exclude'] = Array(raw['filter']['exclude']) + options[:exclude]
+
+        raw['filter']['files'] ||= {}
+        raw['filter']['files']['include'] = Array(raw['filter']['files']['include']) + options[:include_file]
+        raw['filter']['files']['exclude'] = Array(raw['filter']['files']['exclude']) + options[:exclude_file]
+
+        if options[:rbs] || options[:sig_dirs].any?
+          raw['rbs'] ||= {}
+          raw['rbs']['enabled'] = true
+          raw['rbs']['sig_dirs'] = Array(raw['rbs']['sig_dirs']) + options[:sig_dirs] if options[:sig_dirs].any?
+        end
+
+        if options[:sorbet] || options[:rbi_dirs].any?
+          raw['sorbet'] ||= {}
+          raw['sorbet']['enabled'] = true
+          raw['sorbet']['rbi_dirs'] = Array(raw['sorbet']['rbi_dirs']) + options[:rbi_dirs] if options[:rbi_dirs].any?
+        end
+
+        Docscribe::Config.new(raw)
+      end
+    end
+  end
+end

data/lib/docscribe/cli/init.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'docscribe/config'
+
+module Docscribe
+  module CLI
+    module Init
+      class << self
+        # Create or print a starter Docscribe configuration file.
+        #
+        # Supported behaviors:
+        # - write `docscribe.yml` (default)
+        # - write to a custom path via `--config`
+        # - overwrite an existing file via `--force`
+        # - print the template to STDOUT via `--stdout`
+        #
+        # @param [Array<String>] argv command-line arguments for `docscribe init`
+        # @return [Integer] process exit code
+        def run(argv)
+          opts = {
+            config: 'docscribe.yml',
+            force: false,
+            stdout: false
+          }
+
+          OptionParser.new do |o|
+            o.banner = 'Usage: docscribe init [options]'
+            o.on('--config PATH', 'Where to write the config (default: docscribe.yml)') { |v| opts[:config] = v }
+            o.on('-f', '--force', 'Overwrite if the file already exists') { opts[:force] = true }
+            o.on('--stdout', 'Print config template to STDOUT instead of writing a file') { opts[:stdout] = true }
+            o.on('-h', '--help', 'Show this help') do
+              puts o
+              return 0
+            end
+          end.parse!(argv)
+
+          yaml = Docscribe::Config.default_yaml
+
+          if opts[:stdout]
+            puts yaml
+            return 0
+          end
+
+          path = opts[:config]
+          if File.exist?(path) && !opts[:force]
+            warn "Config already exists: #{path} (use --force to overwrite)"
+            return 1
+          end
+
+          File.write(path, yaml)
+          puts "Created: #{path}"
+          0
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/cli/options.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Docscribe
+  module CLI
+    module Options
+      DEFAULT = {
+        stdin: false,
+        mode: :check,       # :check, :write, :stdin
+        strategy: :safe,    # :safe, :aggressive
+        verbose: false,
+        explain: false,
+        config: nil,
+        include: [],
+        exclude: [],
+        include_file: [],
+        exclude_file: [],
+        rbs: false,
+        sig_dirs: [],
+        sorbet: false,
+        rbi_dirs: []
+      }.freeze
+
+      module_function
+
+      # Parse CLI arguments into normalized Docscribe runtime options.
+      #
+      # CLI behavior model:
+      # - default: inspect mode using the safe strategy
+      # - `-a` / `--autocorrect`: write mode using the safe strategy
+      # - `-A` / `--autocorrect-all`: write mode using the aggressive strategy
+      # - `--stdin`: stdin mode using the selected strategy (safe by default)
+      #
+      # Filtering, config, verbosity, and external type options are applied
+      # orthogonally.
+      #
+      # @note module_function: when included, also defines #parse! (instance visibility: private)
+      # @param [Array<String>] argv raw CLI arguments
+      # @return [Hash] normalized runtime options
+      def parse!(argv)
+        options = Marshal.load(Marshal.dump(DEFAULT))
+        autocorrect_mode = nil
+
+        parser = OptionParser.new do |opts|
+          opts.banner = <<~TEXT
+            Usage: docscribe [options] [files...]
+
+            Default behavior:
+              Inspect files and report what safe doc updates would be applied.
+
+            Autocorrect:
+                -a, --autocorrect              Apply safe doc updates in place
+                                               (insert missing docs, merge existing doc-like blocks,
+                                               normalize tag order)
+                -A, --autocorrect-all          Apply aggressive doc updates in place
+                                               (rebuild existing doc blocks)
+
+            Input / config:
+                    --stdin                    Read code from STDIN and print rewritten output
+                -C, --config PATH              Path to config YAML (default: docscribe.yml)
+
+            Type information:
+                    --rbs                      Use RBS signatures for @param/@return when available
+                    --sig-dir DIR              Add an RBS signature directory (repeatable). Implies `--rbs`.
+                    --sorbet                   Use Sorbet signatures from inline sigs / RBI files when available
+                    --rbi-dir DIR              Add a Sorbet RBI directory (repeatable). Implies --sorbet.
+
+            Filtering:
+                    --include PATTERN          Include PATTERN (method id or file path; glob or /regex/)
+                    --exclude PATTERN          Exclude PATTERN (method id or file path; glob or /regex/)
+                    --include-file PATTERN     Only process files matching PATTERN (glob or /regex/)
+                    --exclude-file PATTERN     Skip files matching PATTERN (glob or /regex/)
+
+            Output:
+                    --verbose                  Print per-file actions
+                -e, --explain                  Show detailed reasons for changes
+
+            Other:
+                -v, --version                  Print version and exit
+                -h, --help                     Show this help
+          TEXT
+
+          opts.on('-a', '--autocorrect', 'Apply safe doc updates in place') do
+            autocorrect_mode = :safe
+          end
+
+          opts.on('-A', '--autocorrect-all', 'Apply aggressive doc updates in place') do
+            autocorrect_mode = :aggressive
+          end
+
+          opts.on('--stdin', 'Read code from STDIN and print rewritten output') do
+            options[:stdin] = true
+          end
+
+          opts.on('-C', '--config PATH', 'Path to config YAML (default: docscribe.yml)') do |v|
+            options[:config] = v
+          end
+
+          opts.on('--rbs', 'Use RBS signatures for @param/@return when available (falls back to inference)') do
+            options[:rbs] = true
+          end
+
+          opts.on('--sig-dir DIR', 'Add an RBS signature directory (repeatable). Implies --rbs.') do |v|
+            options[:rbs] = true
+            options[:sig_dirs] << v
+          end
+
+          opts.on('--sorbet', 'Use Sorbet signatures from inline sigs / RBI files when available') do
+            options[:sorbet] = true
+          end
+
+          opts.on('--rbi-dir DIR', 'Add a Sorbet RBI directory (repeatable). Implies --sorbet.') do |v|
+            options[:sorbet] = true
+            options[:rbi_dirs] << v
+          end
+
+          opts.on('--include PATTERN', 'Include PATTERN (method id or file path; glob or /regex/)') do |v|
+            route_include_exclude(options, :include, v)
+          end
+
+          opts.on('--exclude PATTERN',
+                  'Exclude PATTERN (method id or file path; glob or /regex/). Exclude wins.') do |v|
+            route_include_exclude(options, :exclude, v)
+          end
+
+          opts.on('--include-file PATTERN', 'Only process files matching PATTERN (glob or /regex/)') do |v|
+            options[:include_file] << v
+          end
+
+          opts.on('--exclude-file PATTERN', 'Skip files matching PATTERN (glob or /regex/). Exclude wins.') do |v|
+            options[:exclude_file] << v
+          end
+
+          opts.on('--verbose', 'Print per-file actions') do
+            options[:verbose] = true
+          end
+
+          opts.on('-e', '--explain', 'Show detailed reasons for changes') do
+            options[:explain] = true
+          end
+
+          opts.on('-v', '--version', 'Print version and exit') do
+            require 'docscribe/version'
+            puts Docscribe::VERSION
+            exit 0
+          end
+
+          opts.on('-h', '--help', 'Show this help') do
+            puts opts
+            exit 0
+          end
+        end
+
+        parser.parse!(argv)
+
+        if options[:stdin]
+          options[:mode] = :stdin
+          options[:strategy] = autocorrect_mode || :safe
+        elsif autocorrect_mode
+          options[:mode] = :write
+          options[:strategy] = autocorrect_mode
+        else
+          options[:mode] = :check
+          options[:strategy] = :safe
+        end
+
+        options
+      end
+
+      # Route an include/exclude pattern into method filters or file filters.
+      #
+      # Regex-looking patterns (`/…/`) are treated as method-id filters.
+      # File-like patterns are routed into `*_file`.
+      #
+      # @note module_function: when included, also defines #route_include_exclude (instance visibility: private)
+      # @param [Hash] options mutable parsed options hash
+      # @param [Symbol] kind either :include or :exclude
+      # @param [String] value raw pattern from the CLI
+      # @return [void]
+      def route_include_exclude(options, kind, value)
+        if looks_like_file_pattern?(value)
+          options[:"#{kind}_file"] << value
+        else
+          options[kind] << value
+        end
+      end
+
+      # Heuristically decide whether a pattern looks like a file path or file glob.
+      #
+      # Regex syntax (`/.../`) is intentionally treated as a method-id pattern,
+      # not a file pattern.
+      #
+      # @note module_function: when included, also defines #looks_like_file_pattern? (instance visibility: private)
+      # @param [String] pat pattern passed via CLI
+      # @return [Boolean]
+      def looks_like_file_pattern?(pat)
+        return false if pat.start_with?('/') && pat.end_with?('/') && pat.length >= 2
+
+        pat.include?('/') || pat.include?('**') || pat.end_with?('.rb')
+      end
+    end
+  end
+end