docscribe 1.1.0 → 1.2.1

data/lib/docscribe/cli/run.rb

@@ -0,0 +1,415 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+require 'docscribe/cli/config_builder'
+require 'docscribe/inline_rewriter'
+
+module Docscribe
+  module CLI
+    # Execute Docscribe from parsed CLI options.
+    #
+    # This module handles:
+    # - config loading and CLI overrides
+    # - stdin mode
+    # - file expansion / filtering
+    # - inspect vs write behavior
+    # - process exit status
+    module Run
+      class << self
+        # Run Docscribe for files or STDIN using the selected mode and strategy.
+        #
+        # Modes:
+        # - :check => inspect what the selected strategy would change
+        # - :write => apply the selected strategy in place
+        # - :stdin => rewrite STDIN and print to STDOUT
+        #
+        # Strategies:
+        # - :safe       => merge/add/normalize non-destructively
+        # - :aggressive => rebuild existing doc blocks
+        #
+        # @param [Hash] options parsed CLI options
+        # @param [Array<String>] argv remaining path arguments
+        # @return [Integer] process exit code
+        def run(options:, argv:)
+          conf = Docscribe::Config.load(options[:config])
+          conf = Docscribe::CLI::ConfigBuilder.build(conf, options)
+
+          return run_stdin(options: options, conf: conf) if options[:mode] == :stdin
+
+          paths = expand_paths(argv)
+          paths = paths.select { |p| conf.process_file?(p) }
+
+          if paths.empty?
+            warn 'No files found. Pass files or directories (e.g. `docscribe lib`).'
+            return 1
+          end
+
+          run_files(options: options, conf: conf, paths: paths)
+        end
+
+        # Rewrite code from STDIN using the selected strategy and print the
+        # result.
+        #
+        # @param [Hash] options parsed CLI options
+        # @param [Docscribe::Config] conf effective config
+        # @raise [StandardError]
+        # @return [Integer] process exit code
+        def run_stdin(options:, conf:)
+          code = $stdin.read
+          result = Docscribe::InlineRewriter.rewrite_with_report(
+            code,
+            strategy: options[:strategy],
+            config: conf,
+            file: '(stdin)'
+          )
+          puts result[:output]
+          0
+        rescue StandardError => e
+          warn "Docscribe: Error processing stdin: #{e.class}: #{e.message}"
+          1
+        end
+
+        # Expand CLI path arguments into a sorted list of Ruby files.
+        #
+        # Directories are expanded recursively to `**/*.rb`.
+        # If no arguments are provided, the current directory is used.
+        #
+        # @param [Array<String>] args file and/or directory arguments
+        # @return [Array<String>] unique sorted Ruby file paths
+        def expand_paths(args)
+          files = []
+          args = ['.'] if args.empty?
+
+          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
+
+        # Process file paths in inspect or write mode.
+        #
+        # In inspect mode:
+        # - prints progress/status
+        # - exits non-zero if any file would change or if any errors occurred
+        #
+        # In write mode:
+        # - rewrites changed files in place
+        # - exits non-zero only if errors occurred
+        #
+        # @param [Hash] options parsed CLI options
+        # @param [Docscribe::Config] conf effective config
+        # @param [Array<String>] paths Ruby file paths to process
+        # @return [Integer] process exit code
+        def run_files(options:, conf:, paths:)
+          $stdout.sync = true
+
+          state = initial_run_state
+          pwd = Pathname.pwd
+
+          paths.each do |path|
+            process_one_file(path, options: options, conf: conf, pwd: pwd, state: state)
+          end
+
+          if options[:mode] == :check
+            print_check_summary(state: state, options: options)
+          elsif options[:mode] == :write
+            print_write_summary(state: state)
+          end
+
+          return 1 if state[:had_errors]
+          return 1 if options[:mode] == :check && state[:changed]
+
+          0
+        end
+
+        private
+
+        # Method documentation.
+        #
+        # @private
+        # @return [Hash]
+        def initial_run_state
+          {
+            changed: false,
+            had_errors: false,
+            checked_ok: 0,
+            checked_fail: 0,
+            corrected: 0,
+            fail_paths: [],
+            fail_changes: {},
+            error_paths: [],
+            error_messages: {}
+          }
+        end
+
+        # Method documentation.
+        #
+        # @private
+        # @param [Object] path Param documentation.
+        # @param [Hash] options Param documentation.
+        # @param [Object] conf Param documentation.
+        # @param [Object] pwd Param documentation.
+        # @param [Object] state Param documentation.
+        # @return [Object]
+        def process_one_file(path, options:, conf:, pwd:, state:)
+          display_path = display_path_for(path, pwd: pwd)
+
+          src = read_source_for_path(path, display_path: display_path, options: options, state: state)
+          return unless src
+
+          result = rewrite_result_for_path(path, src: src, conf: conf, display_path: display_path, options: options,
+                                                 state: state)
+          return unless result
+
+          out = result[:output]
+          file_changes = result[:changes] || []
+
+          if options[:mode] == :check
+            handle_check_result(
+              path,
+              src: src,
+              out: out,
+              file_changes: file_changes,
+              display_path: display_path,
+              options: options,
+              state: state
+            )
+          elsif options[:mode] == :write
+            handle_write_result(
+              path,
+              src: src,
+              out: out,
+              file_changes: file_changes,
+              display_path: display_path,
+              options: options,
+              state: state
+            )
+          end
+        end
+
+        # Prefer a relative display path when the file is under the current working directory.
+        #
+        # Falls back to basename for files outside the project root or when relative path
+        # computation fails.
+        #
+        # @private
+        # @param [String] path file path to display
+        # @param [Pathname] pwd current working directory
+        # @raise [StandardError]
+        # @return [String] path shown in CLI output
+        def display_path_for(path, pwd:)
+          abs = Pathname.new(path).expand_path
+
+          pwd_str = pwd.to_s
+          abs_str = abs.to_s
+          return abs.relative_path_from(pwd).to_s if abs_str.start_with?(pwd_str + File::SEPARATOR)
+
+          File.basename(abs_str)
+        rescue StandardError
+          File.basename(path.to_s)
+        end
+
+        # Method documentation.
+        #
+        # @private
+        # @param [Object] path Param documentation.
+        # @param [Object] display_path Param documentation.
+        # @param [Hash] options Param documentation.
+        # @param [Object] state Param documentation.
+        # @raise [StandardError]
+        # @return [Object]
+        # @return [nil] if StandardError
+        def read_source_for_path(path, display_path:, options:, state:)
+          File.read(path)
+        rescue StandardError => e
+          state[:had_errors] = true
+          state[:error_paths] << path
+          state[:error_messages][path] = "#{e.class}: #{e.message}"
+          options[:verbose] ? warn("ERR #{display_path}: #{state[:error_messages][path]}") : print('E')
+          nil
+        end
+
+        # Method documentation.
+        #
+        # @private
+        # @param [Object] path Param documentation.
+        # @param [Object] src Param documentation.
+        # @param [Object] conf Param documentation.
+        # @param [Object] display_path Param documentation.
+        # @param [Hash] options Param documentation.
+        # @param [Object] state Param documentation.
+        # @raise [StandardError]
+        # @return [Object]
+        # @return [nil] if StandardError
+        def rewrite_result_for_path(path, src:, conf:, display_path:, options:, state:)
+          Docscribe::InlineRewriter.rewrite_with_report(
+            src,
+            strategy: options[:strategy],
+            config: conf,
+            file: path
+          )
+        rescue StandardError => e
+          state[:had_errors] = true
+          state[:error_paths] << path
+          state[:error_messages][path] = "#{e.class}: #{e.message}"
+          options[:verbose] ? warn("ERR #{display_path}: #{state[:error_messages][path]}") : print('E')
+          nil
+        end
+
+        # Method documentation.
+        #
+        # @private
+        # @param [Object] path Param documentation.
+        # @param [Object] src Param documentation.
+        # @param [Object] out Param documentation.
+        # @param [Object] file_changes Param documentation.
+        # @param [Object] display_path Param documentation.
+        # @param [Hash] options Param documentation.
+        # @param [Object] state Param documentation.
+        # @return [Object]
+        def handle_check_result(path, src:, out:, file_changes:, display_path:, options:, state:)
+          if out == src
+            options[:verbose] ? puts("OK #{display_path}") : print('.')
+            state[:checked_ok] += 1
+            return
+          end
+
+          if options[:verbose]
+            puts("FAIL #{display_path}")
+            if options[:explain]
+              file_changes.each do |change|
+                puts("  - #{format_change_reason(change)}")
+              end
+            end
+          else
+            print('F')
+          end
+
+          state[:checked_fail] += 1
+          state[:changed] = true
+          state[:fail_paths] << path
+          state[:fail_changes][path] = file_changes
+        end
+
+        # Method documentation.
+        #
+        # @private
+        # @param [Object] path Param documentation.
+        # @param [Object] src Param documentation.
+        # @param [Object] out Param documentation.
+        # @param [Object] file_changes Param documentation.
+        # @param [Object] display_path Param documentation.
+        # @param [Hash] options Param documentation.
+        # @param [Object] state Param documentation.
+        # @raise [StandardError]
+        # @return [Object]
+        # @return [Object] if StandardError
+        def handle_write_result(path, src:, out:, file_changes:, display_path:, options:, state:)
+          if out == src
+            options[:verbose] ? puts("OK #{display_path}") : print('.')
+            return
+          end
+
+          File.write(path, out)
+
+          if options[:verbose]
+            puts("CHANGED #{display_path}")
+            if options[:explain]
+              file_changes.each do |change|
+                puts("  - #{format_change_reason(change)}")
+              end
+            end
+          else
+            print('C')
+          end
+
+          state[:corrected] += 1
+        rescue StandardError => e
+          state[:had_errors] = true
+          state[:error_paths] << path
+          state[:error_messages][path] = "#{e.class}: #{e.message}"
+          options[:verbose] ? warn("ERR #{display_path}: #{state[:error_messages][path]}") : print('E')
+        end
+
+        # Method documentation.
+        #
+        # @private
+        # @param [Object] state Param documentation.
+        # @param [Hash] options Param documentation.
+        # @return [Object]
+        def print_check_summary(state:, options:)
+          puts
+
+          checked_error = state[:error_paths].size
+
+          if state[:checked_fail].zero? && checked_error.zero?
+            puts "Docscribe: OK (#{state[:checked_ok]} files checked)"
+            return
+          end
+
+          puts "Docscribe: FAILED (#{state[:checked_fail]} files need updates, #{checked_error} errors, #{state[:checked_ok]} ok)"
+
+          state[:fail_paths].each do |p|
+            warn "Would update docs: #{p}"
+            next unless options[:explain] && !options[:verbose]
+
+            Array(state[:fail_changes][p]).each do |change|
+              warn "  - #{format_change_reason(change)}"
+            end
+          end
+
+          state[:error_paths].each do |p|
+            warn "Error processing: #{p}"
+            warn "  #{state[:error_messages][p]}" if state[:error_messages][p]
+          end
+        end
+
+        # Format a structured change record into human-readable CLI output.
+        #
+        # @private
+        # @param [Hash] change structured change produced by the inline rewriter
+        # @return [String] human-readable explanation line
+        def format_change_reason(change)
+          line = change[:line] ? " at line #{change[:line]}" : ''
+          method = change[:method] ? " for #{change[:method]}" : ''
+
+          case change[:type]
+          when :unsorted_tags
+            "unsorted tags#{line}"
+          when :missing_param, :missing_return, :missing_raise, :missing_visibility, :missing_module_function_note,
+            :insert_full_doc_block
+            "#{change[:message]}#{method}#{line}"
+          else
+            "#{change[:message] || change[:type].to_s.tr('_', ' ')}#{method}#{line}"
+          end
+        end
+
+        # Method documentation.
+        #
+        # @private
+        # @param [Object] state Param documentation.
+        # @return [Object]
+        def print_write_summary(state:)
+          puts
+          puts "Docscribe: updated #{state[:corrected]} file(s)" if state[:corrected].positive?
+
+          return unless state[:had_errors]
+
+          warn "Docscribe: #{state[:error_paths].size} file(s) had errors"
+          state[:error_paths].each do |p|
+            warn "Error processing: #{p}"
+            warn "  #{state[:error_messages][p]}" if state[:error_messages][p]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/cli.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'docscribe/cli/init'
+require 'docscribe/cli/options'
+require 'docscribe/cli/run'
+
+module Docscribe
+  module CLI
+    class << self
+      # Main CLI entry point.
+      #
+      # Dispatches:
+      # - `docscribe init ...` to the config-template generator
+      # - all other commands to the main option parser and runner
+      #
+      # @param [Array<String>] argv raw command-line arguments
+      # @return [Integer] process exit code
+      def run(argv)
+        argv = argv.dup
+
+        if argv.first == 'init'
+          argv.shift
+          return Docscribe::CLI::Init.run(argv)
+        end
+
+        options = Docscribe::CLI::Options.parse!(argv)
+        Docscribe::CLI::Run.run(options: options, argv: argv)
+      end
+    end
+  end
+end

data/lib/docscribe/config/defaults.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    # Default configuration values used when no `docscribe.yml` is present or
+    # when specific keys are missing from user config.
+    #
+    # These defaults define:
+    # - which documentation tags are emitted
+    # - default generated text
+    # - type inference behavior
+    # - method / file filtering
+    # - optional RBS integration
+    # - optional Sorbet integration
+    DEFAULT = {
+      'emit' => {
+        'header' => true,
+        'param_tags' => true,
+        'return_tag' => true,
+        'visibility_tags' => true,
+        'raise_tags' => true,
+        'rescue_conditional_returns' => true,
+        'attributes' => false
+      },
+      'doc' => {
+        'default_message' => 'Method documentation.',
+        'param_tag_style' => 'type_name',
+        'param_documentation' => 'Param documentation.',
+        'sort_tags' => true,
+        'tag_order' => %w[todo note api private protected param option yieldparam raise return]
+      },
+      'methods' => {
+        'instance' => {
+          'public' => {},
+          'protected' => {},
+          'private' => {}
+        },
+        'class' => {
+          'public' => {},
+          'protected' => {},
+          'private' => {}
+        }
+      },
+      'inference' => {
+        'fallback_type' => 'Object',
+        'nil_as_optional' => true,
+        'treat_options_keyword_as_hash' => true
+      },
+      'filter' => {
+        'visibilities' => %w[public protected private],
+        'scopes' => %w[instance class],
+        'include' => [],
+        'exclude' => [],
+        'files' => {
+          'include' => [],
+          'exclude' => []
+        }
+      },
+      'rbs' => {
+        'enabled' => false,
+        'sig_dirs' => ['sig'],
+        'collapse_generics' => false
+      },
+      'sorbet' => {
+        'enabled' => false,
+        'rbi_dirs' => ['sorbet/rbi', 'rbi'],
+        'collapse_generics' => false
+      }
+    }.freeze
+  end
+end

data/lib/docscribe/config/emit.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    # Whether to emit method header lines such as:
+    #   # +MyClass#foo+ -> Integer
+    #
+    # @return [Boolean]
+    def emit_header?
+      fetch_bool(%w[emit header], true)
+    end
+
+    # Whether to emit `@param` tags.
+    #
+    # @return [Boolean]
+    def emit_param_tags?
+      fetch_bool(%w[emit param_tags], true)
+    end
+
+    # Whether to emit visibility tags such as `@private` and `@protected`.
+    #
+    # @return [Boolean]
+    def emit_visibility_tags?
+      fetch_bool(%w[emit visibility_tags], true)
+    end
+
+    # Whether to emit inferred `@raise` tags.
+    #
+    # @return [Boolean]
+    def emit_raise_tags?
+      fetch_bool(%w[emit raise_tags], true)
+    end
+
+    # Whether to emit conditional rescue-return tags like:
+    #   # @return [String] if FooError
+    #
+    # @return [Boolean]
+    def emit_rescue_conditional_returns?
+      fetch_bool(%w[emit rescue_conditional_returns], true)
+    end
+
+    # Whether to emit YARD `@!attribute` docs for `attr_*` macros.
+    #
+    # @return [Boolean]
+    def emit_attributes?
+      fetch_bool(%w[emit attributes], false)
+    end
+
+    # Whether to emit the `@return` tag for a method, taking per-scope and
+    # per-visibility overrides into account.
+    #
+    # @param [Symbol] scope :instance or :class
+    # @param [Symbol] visibility :public, :protected, or :private
+    # @return [Boolean]
+    def emit_return_tag?(scope, visibility)
+      method_override_bool(
+        scope,
+        visibility,
+        'return_tag',
+        default: fetch_bool(%w[emit return_tag], true)
+      )
+    end
+
+    # Default text inserted into generated doc blocks, taking per-scope and
+    # per-visibility overrides into account.
+    #
+    # @param [Symbol] scope :instance or :class
+    # @param [Symbol] visibility :public, :protected, or :private
+    # @return [String]
+    def default_message(scope, visibility)
+      method_override_str(
+        scope,
+        visibility,
+        'default_message',
+        default: raw.dig('doc', 'default_message') ||
+                 DEFAULT.dig('doc', 'default_message') ||
+                 'Method documentation.'
+      )
+    end
+
+    # Fallback type used when inference cannot determine a more specific type.
+    #
+    # @return [String]
+    def fallback_type
+      raw.dig('inference', 'fallback_type') ||
+        DEFAULT.dig('inference', 'fallback_type') ||
+        'Object'
+    end
+
+    # Whether unions involving nil should be rendered as optional types.
+    #
+    # For example, `String, nil` may become `String?` depending on formatter
+    # behavior.
+    #
+    # @return [Boolean]
+    def nil_as_optional?
+      fetch_bool(%w[inference nil_as_optional], true)
+    end
+
+    # Whether keyword arguments named `options` / `options:` should be treated
+    # specially as Hash values during inference.
+    #
+    # @return [Boolean]
+    def treat_options_keyword_as_hash?
+      fetch_bool(%w[inference treat_options_keyword_as_hash], true)
+    end
+
+    # Param tag syntax style.
+    #
+    # Supported values:
+    # - `"type_name"` => `@param [String] name`
+    # - `"name_type"` => `@param name [String]`
+    #
+    # @return [String]
+    def param_tag_style
+      raw.dig('doc', 'param_tag_style') || DEFAULT.dig('doc', 'param_tag_style')
+    end
+
+    # Default generated parameter description text.
+    #
+    # @return [String]
+    def param_documentation
+      raw.dig('doc', 'param_documentation') || DEFAULT.dig('doc', 'param_documentation')
+    end
+
+    # Whether to include the default placeholder line:
+    #   # Method documentation.
+    #
+    # @return [Boolean]
+    def include_default_message?
+      fetch_bool(%w[emit include_default_message], true)
+    end
+
+    # Whether to append placeholder text to generated @param tags:
+    #   # @param [String] name Param documentation.
+    #
+    # @return [Boolean]
+    def include_param_documentation?
+      fetch_bool(%w[emit include_param_documentation], true)
+    end
+  end
+end