docscribe 1.2.1 → 1.3.1

data/lib/docscribe/cli/generate.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Docscribe
+  module CLI
+    # Generator for TagPlugin and CollectorPlugin boilerplate.
+    #
+    # Usage:
+    #   docscribe generate tag MyPlugin
+    #   docscribe generate collector MyPlugin
+    #   docscribe generate tag MyPlugin --output lib/docscribe_plugins
+    #   docscribe generate tag MyPlugin --stdout
+    module Generate
+      PLUGIN_TYPES = %w[tag collector].freeze
+
+      class << self
+        # Run the `generate` subcommand.
+        #
+        # @param [Array<String>] argv
+        # @raise [OptionParser::InvalidOption]
+        # @return [Integer] exit code
+        def run(argv)
+          opts = {
+            output: nil,
+            stdout: false
+          }
+
+          parser = OptionParser.new do |o|
+            o.banner = <<~TEXT
+              Usage: docscribe generate <type> <PluginName> [options]
+
+              Types:
+                tag         Generate a TagPlugin skeleton
+                collector   Generate a CollectorPlugin skeleton
+
+              Options:
+            TEXT
+
+            o.on('--output DIR', 'Directory to write the plugin file (default: .)') { |v| opts[:output] = v }
+            o.on('--stdout', 'Print the generated plugin to STDOUT instead of writing a file') { opts[:stdout] = true }
+            o.on('-h', '--help', 'Show this help') do
+              puts o
+              return 0
+            end
+          end
+
+          begin
+            parser.parse!(argv)
+          rescue OptionParser::InvalidOption => e
+            warn e.message
+            warn parser
+            return 1
+          end
+
+          plugin_type = argv.shift
+          class_name  = argv.shift
+
+          unless plugin_type && class_name
+            warn 'Error: both <type> and <PluginName> are required.'
+            warn parser
+            return 1
+          end
+
+          unless PLUGIN_TYPES.include?(plugin_type)
+            warn "Error: unknown type #{plugin_type.inspect}. Must be one of: #{PLUGIN_TYPES.join(', ')}."
+            return 1
+          end
+
+          unless valid_constant?(class_name)
+            warn "Error: #{class_name.inspect} is not a valid Ruby constant name."
+            return 1
+          end
+
+          content = render(plugin_type, class_name)
+
+          if opts[:stdout]
+            puts content
+            return 0
+          end
+
+          write_plugin(content, plugin_type: plugin_type, class_name: class_name, output_dir: opts[:output] || '.')
+        end
+
+        private
+
+        # Check whether a string is a valid Ruby constant name.
+        #
+        # @private
+        # @param [String] str
+        # @return [Boolean]
+        def valid_constant?(str)
+          !!(str =~ /\A[A-Z][A-Za-z0-9]*(?:::[A-Z][A-Za-z0-9]*)*\z/)
+        end
+
+        # Render plugin boilerplate for the given type and class name.
+        #
+        # @private
+        # @param [String] plugin_type 'tag' or 'collector'
+        # @param [String] class_name  CamelCase plugin class name
+        # @return [String]
+        def render(plugin_type, class_name)
+          case plugin_type
+          when 'tag'       then tag_template(class_name)
+          when 'collector' then collector_template(class_name)
+          end
+        end
+
+        # Write the generated content to a file.
+        #
+        # @private
+        # @param [String] content
+        # @param [String] plugin_type
+        # @param [String] class_name
+        # @param [String] output_dir
+        # @return [Integer] exit code
+        def write_plugin(content, plugin_type:, class_name:, output_dir:)
+          filename = "#{underscore(class_name)}.rb"
+          path     = File.join(output_dir, filename)
+
+          if File.exist?(path)
+            warn "Error: #{path} already exists. Remove it first or use --stdout."
+            return 1
+          end
+
+          require 'fileutils'
+          FileUtils.mkdir_p(output_dir)
+          File.write(path, content)
+          puts "Created: #{path}"
+          puts
+          puts next_steps(plugin_type, path)
+          0
+        end
+
+        # Print registration instructions after file creation.
+        #
+        # @private
+        # @param [String] plugin_type
+        # @param [String] path
+        # @return [String]
+        def next_steps(plugin_type, path)
+          base_name = File.basename(path, '.rb').split('_').map(&:capitalize).join
+
+          implement_hint = case plugin_type
+                           when 'tag'
+                             'Implement the #call method to return Array<Docscribe::Plugin::Tag>.'
+                           when 'collector'
+                             'Implement the #collect method to return Array<{anchor_node:, doc:}>.'
+                           end
+
+          <<~TEXT
+            Next steps:
+              1. Open #{path} and implement the plugin logic.
+                 #{implement_hint}
+
+              2. Register the plugin in your docscribe_plugins.rb:
+
+                   require_relative '#{path.delete_suffix('.rb')}'
+                   Docscribe::Plugin::Registry.register(#{base_name}.new)
+
+              3. Add the file to docscribe.yml:
+
+                   plugins:
+                     require:
+                       - ./docscribe_plugins
+          TEXT
+        end
+
+        # Template for a TagPlugin.
+        #
+        # @private
+        # @param [String] class_name
+        # @return [String]
+        def tag_template(class_name)
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require 'docscribe/plugin'
+
+            # #{class_name} — a Docscribe TagPlugin.
+            #
+            # TagPlugins hook into already-collected method insertions and append
+            # additional YARD tags to the generated doc block.
+            #
+            # The +#call+ method is invoked once per documented method. Return an
+            # empty array if this plugin has nothing to add for a particular method.
+            #
+            # @example Registration
+            #   Docscribe::Plugin::Registry.register(#{class_name}.new)
+            class #{class_name} < Docscribe::Plugin::Base::TagPlugin
+              # Generate additional YARD tags for a documented method.
+              #
+              # Available context attributes:
+              #   context.node            # Parser::AST::Node — the :def or :defs node
+              #   context.container       # String  — e.g. "MyModule::MyClass"
+              #   context.scope           # Symbol  — :instance or :class
+              #   context.visibility      # Symbol  — :public, :protected, or :private
+              #   context.method_name     # Symbol  — method name
+              #   context.inferred_params # Hash    — { "name" => "InferredType" }
+              #   context.inferred_return # String  — inferred return type
+              #   context.source          # String  — raw method source text
+              #
+              # @param [Docscribe::Plugin::Context] context method context snapshot
+              # @return [Array<Docscribe::Plugin::Tag>]
+              def call(context)
+                # TODO: implement plugin logic
+                #
+                # Examples:
+                #
+                #   Simple text tag:
+                #     Docscribe::Plugin::Tag.new(name: 'since', text: '1.0.0')
+                #     # => # @since 1.0.0
+                #
+                #   Tag with types:
+                #     Docscribe::Plugin::Tag.new(name: 'raise', types: ['ArgumentError'], text: 'if invalid')
+                #     # => # @raise [ArgumentError] if invalid
+                #
+                #   Conditional tag:
+                #     return [] unless context.visibility == :public
+                #     [Docscribe::Plugin::Tag.new(name: 'api', text: 'public')]
+                []
+              end
+            end
+          RUBY
+        end
+
+        # Template for a CollectorPlugin.
+        #
+        # @private
+        # @param [String] class_name
+        # @return [String]
+        def collector_template(class_name)
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require 'docscribe/plugin'
+            require 'docscribe/infer/ast_walk'
+
+            # #{class_name} — a Docscribe CollectorPlugin.
+            #
+            # CollectorPlugins receive the raw AST and source buffer for each file.
+            # They walk the tree independently and return insertion targets that
+            # Docscribe will document according to the selected strategy.
+            #
+            # Idempotency is handled automatically:
+            #   :safe       — skips insertion if a comment already exists above anchor_node
+            #   :aggressive — removes the existing comment and inserts a fresh block
+            #
+            # Use this plugin type for non-standard constructs that Docscribe's
+            # built-in Collector does not recognize (DSL macros, define_method, etc.).
+            # For ordinary +def+ methods use TagPlugin instead.
+            #
+            # @example Registration
+            #   Docscribe::Plugin::Registry.register(#{class_name}.new)
+            class #{class_name} < Docscribe::Plugin::Base::CollectorPlugin
+              # Walk the AST and return documentation insertion targets.
+              #
+              # Each result must be a Hash with:
+              #   :anchor_node — Parser::AST::Node above which to insert the doc block
+              #   :doc         — String with the complete doc block (newlines included)
+              #
+              # Indentation is applied automatically from anchor_node — do not
+              # prefix lines manually.
+              #
+              # @param [Parser::AST::Node] ast root AST node of the file
+              # @param [Parser::Source::Buffer] buffer source buffer
+              # @return [Array<Hash>]
+              def collect(ast, buffer)
+                results = []
+
+                Docscribe::Infer::ASTWalk.walk(ast) do |node|
+                  # TODO: replace with your target node detection
+                  #
+                  # Example — match bare send calls like `my_dsl_macro :name`:
+                  #
+                  #   next unless node.type == :send
+                  #   recv, meth, name_node, *_rest = *node
+                  #   next unless recv.nil? && meth == :my_dsl_macro
+                  #   next unless name_node&.type == :sym
+                  #
+                  #   macro_name = name_node.children.first
+                  #
+                  #   results << {
+                  #     anchor_node: node,
+                  #     doc: "# \#{macro_name} — generated doc\\n# @return [void]\\n"
+                  #   }
+                end
+
+                results
+              end
+            end
+          RUBY
+        end
+
+        # Convert CamelCase to snake_case for file naming.
+        #
+        # @private
+        # @param [String] str
+        # @return [String]
+        def underscore(str)
+          str
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/cli/options.rb

@@ -19,7 +19,8 @@ module Docscribe
         rbs: false,
         sig_dirs: [],
         sorbet: false,
-        rbi_dirs: []
+        rbi_dirs: [],
+        rbs_collection: false
       }.freeze
 
       module_function
@@ -65,6 +66,7 @@ module Docscribe
                     --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.
+                    --rbs-collection           Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.
 
             Filtering:
                     --include PATTERN          Include PATTERN (method id or file path; glob or /regex/)
@@ -115,6 +117,11 @@ module Docscribe
             options[:rbi_dirs] << v
           end
 
+          opts.on('--rbs-collection', 'Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.') do
+            options[:rbs] = true
+            options[:rbs_collection] = true
+          end
+
           opts.on('--include PATTERN', 'Include PATTERN (method id or file path; glob or /regex/)') do |v|
             route_include_exclude(options, :include, v)
           end

data/lib/docscribe/cli/run.rb

@@ -34,6 +34,7 @@ module Docscribe
         def run(options:, argv:)
           conf = Docscribe::Config.load(options[:config])
           conf = Docscribe::CLI::ConfigBuilder.build(conf, options)
+          conf.load_plugins!
 
           return run_stdin(options: options, conf: conf) if options[:mode] == :stdin
 
@@ -61,6 +62,7 @@ module Docscribe
             code,
             strategy: options[:strategy],
             config: conf,
+            core_rbs_provider: conf.respond_to?(:core_rbs_provider) ? conf.core_rbs_provider : nil,
             file: '(stdin)'
           )
           puts result[:output]
@@ -132,10 +134,10 @@ module Docscribe
 
         private
 
-        # Method documentation.
+        # Initialize the shared state hash used throughout a run.
         #
         # @private
-        # @return [Hash]
+        # @return [Hash] initial state with counters and tracking arrays
         def initial_run_state
           {
             changed: false,
@@ -150,15 +152,15 @@ module Docscribe
           }
         end
 
-        # Method documentation.
+        # Process a single file: read, rewrite, and dispatch to check/write handler.
         #
         # @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]
+        # @param [String] path file path
+        # @param [Hash] options CLI options
+        # @param [Docscribe::Config] conf configuration
+        # @param [Pathname] pwd current working directory
+        # @param [Hash] state shared processing state
+        # @return [void]
         def process_one_file(path, options:, conf:, pwd:, state:)
           display_path = display_path_for(path, pwd: pwd)
 
@@ -217,16 +219,15 @@ module Docscribe
           File.basename(path.to_s)
         end
 
-        # Method documentation.
+        # Read the source file and handle read errors.
         #
         # @private
-        # @param [Object] path Param documentation.
-        # @param [Object] display_path Param documentation.
-        # @param [Hash] options Param documentation.
-        # @param [Object] state Param documentation.
+        # @param [String] path file path to read
+        # @param [String] display_path path shown in CLI output
+        # @param [Hash] options CLI options
+        # @param [Hash] state shared processing state
         # @raise [StandardError]
-        # @return [Object]
-        # @return [nil] if StandardError
+        # @return [String, nil] file contents or nil on error
         def read_source_for_path(path, display_path:, options:, state:)
           File.read(path)
         rescue StandardError => e
@@ -237,23 +238,24 @@ module Docscribe
           nil
         end
 
-        # Method documentation.
+        # Rewrite the source file using InlineRewriter and handle rewrite errors.
         #
         # @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.
+        # @param [String] path file path
+        # @param [String] src source code
+        # @param [Docscribe::Config] conf configuration
+        # @param [String] display_path path shown in CLI output
+        # @param [Hash] options CLI options
+        # @param [Hash] state shared processing state
         # @raise [StandardError]
-        # @return [Object]
-        # @return [nil] if StandardError
+        # @return [Hash, nil] rewrite result or nil on error
         def rewrite_result_for_path(path, src:, conf:, display_path:, options:, state:)
+          core_rbs_provider = conf.respond_to?(:core_rbs_provider) ? conf.core_rbs_provider : nil
           Docscribe::InlineRewriter.rewrite_with_report(
             src,
             strategy: options[:strategy],
             config: conf,
+            core_rbs_provider: core_rbs_provider,
             file: path
           )
         rescue StandardError => e
@@ -264,17 +266,17 @@ module Docscribe
           nil
         end
 
-        # Method documentation.
+        # Handle the result of an inspect (check) run.
         #
         # @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]
+        # @param [String] path file path
+        # @param [String] src original source code
+        # @param [String] out rewritten source code
+        # @param [Array<Hash>] file_changes structured change records
+        # @param [String] display_path path shown in CLI output
+        # @param [Hash] options CLI options
+        # @param [Hash] state shared processing state
+        # @return [void]
         def handle_check_result(path, src:, out:, file_changes:, display_path:, options:, state:)
           if out == src
             options[:verbose] ? puts("OK #{display_path}") : print('.')
@@ -299,19 +301,18 @@ module Docscribe
           state[:fail_changes][path] = file_changes
         end
 
-        # Method documentation.
+        # Handle the result of an autocorrect (write) run.
         #
         # @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.
+        # @param [String] path file path
+        # @param [String] src original source code
+        # @param [String] out rewritten source code
+        # @param [Array<Hash>] file_changes structured change records
+        # @param [String] display_path path shown in CLI output
+        # @param [Hash] options CLI options
+        # @param [Hash] state shared processing state
         # @raise [StandardError]
-        # @return [Object]
-        # @return [Object] if StandardError
+        # @return [void]
         def handle_write_result(path, src:, out:, file_changes:, display_path:, options:, state:)
           if out == src
             options[:verbose] ? puts("OK #{display_path}") : print('.')
@@ -339,12 +340,12 @@ module Docscribe
           options[:verbose] ? warn("ERR #{display_path}: #{state[:error_messages][path]}") : print('E')
         end
 
-        # Method documentation.
+        # Print the check-mode summary (files OK / need updates / errors).
         #
         # @private
-        # @param [Object] state Param documentation.
-        # @param [Hash] options Param documentation.
-        # @return [Object]
+        # @param [Hash] state shared processing state
+        # @param [Hash] options CLI options
+        # @return [void]
         def print_check_summary(state:, options:)
           puts
 
@@ -392,11 +393,11 @@ module Docscribe
           end
         end
 
-        # Method documentation.
+        # Print the write-mode summary (files corrected, errors).
         #
         # @private
-        # @param [Object] state Param documentation.
-        # @return [Object]
+        # @param [Hash] state shared processing state
+        # @return [void]
         def print_write_summary(state:)
           puts
           puts "Docscribe: updated #{state[:corrected]} file(s)" if state[:corrected].positive?

data/lib/docscribe/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'docscribe/cli/init'
+require 'docscribe/cli/generate'
 require 'docscribe/cli/options'
 require 'docscribe/cli/run'
 
@@ -10,7 +11,8 @@ module Docscribe
       # Main CLI entry point.
       #
       # Dispatches:
-      # - `docscribe init ...` to the config-template generator
+      # - `docscribe init ...`     to the config-template generator
+      # - `docscribe generate ...` to the plugin skeleton generator
       # - all other commands to the main option parser and runner
       #
       # @param [Array<String>] argv raw command-line arguments
@@ -18,9 +20,13 @@ module Docscribe
       def run(argv)
         argv = argv.dup
 
-        if argv.first == 'init'
+        case argv.first
+        when 'init'
           argv.shift
           return Docscribe::CLI::Init.run(argv)
+        when 'generate'
+          argv.shift
+          return Docscribe::CLI::Generate.run(argv)
         end
 
         options = Docscribe::CLI::Options.parse!(argv)

data/lib/docscribe/config/defaults.rb

@@ -14,7 +14,9 @@ module Docscribe
     # - optional Sorbet integration
     DEFAULT = {
       'emit' => {
-        'header' => true,
+        'header' => false,
+        'include_default_message' => true,
+        'include_param_documentation' => true,
         'param_tags' => true,
         'return_tag' => true,
         'visibility_tags' => true,
@@ -53,11 +55,12 @@ module Docscribe
         'exclude' => [],
         'files' => {
           'include' => [],
-          'exclude' => []
+          'exclude' => ['spec']
         }
       },
       'rbs' => {
         'enabled' => false,
+        'collection' => false,
         'sig_dirs' => ['sig'],
         'collapse_generics' => false
       },
@@ -65,6 +68,9 @@ module Docscribe
         'enabled' => false,
         'rbi_dirs' => ['sorbet/rbi', 'rbi'],
         'collapse_generics' => false
+      },
+      'plugins' => {
+        'require' => []
       }
     }.freeze
   end

data/lib/docscribe/config/filtering.rb

@@ -16,7 +16,7 @@ module Docscribe
       exclude_patterns = normalize_file_patterns(files['exclude'])
 
       rel = begin
-        Pathname.new(path).relative_path_from(Pathname.pwd).to_s
+        Pathname.new(path).expand_path.relative_path_from(Pathname.pwd).cleanpath.to_s
       rescue StandardError
         path
       end
@@ -121,7 +121,7 @@ module Docscribe
       patterns_to_try << pattern.gsub('/**/', '/') if pattern.include?('/**/')
 
       patterns_to_try.any? do |pat|
-        File.fnmatch?(pat, path, File::FNM_EXTGLOB | File::FNM_PATHNAME)
+        File.fnmatch?(pat, path, File::FNM_EXTGLOB | File::FNM_DOTMATCH | File::FNM_PATHNAME)
       end
     end
 

data/lib/docscribe/config/plugin.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    # Load and register plugins declared under `plugins.require` in config.
+    #
+    # Each entry is expanded relative to the current working directory and
+    # passed to `require`. Registration is expected to happen inside the
+    # required file via {Docscribe::Plugin::Registry.register}.
+    #
+    # Loading failures are non-fatal: a warning is printed and the run
+    # continues without the plugin.
+    #
+    # @raise [LoadError]
+    # @return [void]
+    def load_plugins!
+      paths = Array(raw.dig('plugins', 'require')).compact
+      return if paths.empty?
+
+      require 'docscribe/plugin'
+
+      paths.each do |path|
+        require File.expand_path(path)
+      rescue LoadError => e
+        warn "Docscribe: could not load plugin #{path.inspect}: #{e.message}"
+      end
+    end
+  end
+end