docscribe 1.4.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50c74b921731749cbf32726e24e557e526e1f65966e704171a652d10cc4ce945
-  data.tar.gz: 2e254911cf9d81f5d5f7b5df29576c3c5c3c3f0433cfb387c0d22c1ce30eeb60
+  metadata.gz: 5b6ff6ead507182a9530fa2f2cc690d435448284f9212f4fbeea3950dddf40c3
+  data.tar.gz: 17e3285caddd09bda308e89f5cb1eb4579d8f96855177f81dbe459b7ad84e9d4
 SHA512:
-  metadata.gz: 824133cf33505568edc84fe99bd51ced4451616552b2ba33e5584fcbd68bdd2ede0e4df365510a4e6be73ef9bf191a66e37746a5331e2ccb8abae2a80a3f69b4
-  data.tar.gz: 6662f828e5d324c226432df0e00359a36a97cd47dfeedefd4ead014752fbebe51b93e6cb693d6a342ca3d7e24683b74c189576792e558bf12e28bcc6365e2ed2
+  metadata.gz: d7a764fb2d297c1449995727c7d79704db934df7a52f2f2475d21fc6b29c60ea8908fc7ebb560592a3ad6de4d1384937ce75836cbce3e7899eef5918f05e6ab9
+  data.tar.gz: 8ab0b426a364eb5dfe823370148b2e2e9e93ad1f2e788bda9143533aa139821c2d159351255a86d8dd739b647572168e4c539e5764e6d562cc6cf7ea9b79acd2

data/README.md

@@ -44,6 +44,8 @@ Common workflows:
     * [Contents](#contents)
     * [Installation](#installation)
     * [Quick start](#quick-start)
+    * [Architecture](#architecture)
+        * [Data flow](#data-flow)
     * [CLI](#cli)
         * [Options](#options)
         * [Examples](#examples)
@@ -68,7 +70,10 @@ Common workflows:
     * [Plugin system](#plugin-system)
         * [TagPlugin](#tagplugin)
         * [CollectorPlugin](#collectorplugin)
+            * [Plugin doc normalization (CollectorPlugin)](#plugin-doc-normalization-collectorplugin)
+            * [`method_override` (structured patch)](#method_override-structured-patch)
         * [Registering plugins](#registering-plugins)
+        * [Plugin priority](#plugin-priority)
         * [Idempotency](#idempotency)
         * [Plugin examples](#plugin-examples)
     * [Configuration](#configuration)
@@ -83,6 +88,8 @@ Common workflows:
         * [Generate a plugin skeleton](#generate-a-plugin-skeleton)
     * [CI integration](#ci-integration)
     * [Comparison to YARD's parser](#comparison-to-yards-parser)
+    * [Mermaid Architecture Reference](#mermaid-architecture-reference)
+        * [Data flow](#data-flow)
     * [Limitations](#limitations)
     * [Roadmap](#roadmap)
     * [Contributing](#contributing)
@@ -201,6 +208,151 @@ end
 > - Class methods show with a dot (`+Demo.bump+`, `+Demo.internal+`).
 > - Methods inside `class << self` under `private` are marked `@private`.
 
+## Architecture
+
+Docscribe is organized into seven subsystems. The CLI layer receives user input and orchestrates configuration loading,
+then delegates to the core engine which parses source code, collects methods (using an AST walker), builds YARD doc
+lines — combining heuristic type inference, external RBS/Sorbet signatures, and plugin output — and finally rewrites the
+source via a strategy (safe merge or aggressive replace).
+
+```mermaid
+flowchart TB
+    subgraph CLI["CLI Layer"]
+        Exe["exe/docscribe\nEntry point"]
+        Run["CLI::Run\nMain execution\n· expand paths\n· iterate files\n· report results"]
+        Options["CLI::Options\nARGV parsing\n(mode, strategy,\nfilters, flags)"]
+        InitCmd["CLI::Init\ndocscribe init\nGenerate config"]
+        GenCmd["CLI::Generate\ndocscribe generate\nScaffold plugins"]
+        ConfigBuilder["CLI::ConfigBuilder\nApply CLI overrides\nto config"]
+    end
+
+    subgraph Config["Configuration"]
+        ConfigClass["Config\nCentral config object\n· raw hash\n· query methods"]
+        Defaults["config/defaults.rb\nDEFAULT hash"]
+        Loader["config/loader.rb\nYAML loading\n+ deep merge"]
+        Emit["config/emit.rb\nEmission toggles\n(header, tags, etc.)"]
+        Filtering["config/filtering.rb\nFile/method\ninclude/exclude"]
+        RBSConfig["config/rbs.rb\nRBS provider\nfactory"]
+        SorbetConfig["config/sorbet.rb\nSorbet provider\nchain factory"]
+        PluginConfig["config/plugin.rb\nPlugin loading\nfrom YAML"]
+    end
+
+    subgraph Parsing["Parsing"]
+        ParsingModule["Parsing\nBackend selection\n(:parser / :prism)"]
+        ParserGem["Parser gem\n(whitequark/parser)"]
+        Prism["Prism translator\n(Ruby 3.4+)"]
+    end
+
+    subgraph Core["Core Engine"]
+        InlineRewriter["InlineRewriter\n· parse → collect\n· deduplicate → dispatch\n· rewrite"]
+        Collector["Collector\n< Parser::AST::Processor\nAST walker\n· find methods/attrs\n· track visibility\n· track containers"]
+        DocBuilder["DocBuilder\nGenerate YARD doc lines\n· combine inference\n· external signatures\n· plugin tags"]
+        DocBlock["DocBlock\nSafe strategy:\nparse → merge → sort\nexisting doc blocks"]
+        SourceHelpers["SourceHelpers\nPosition/range\nutilities"]
+    end
+
+    subgraph Infer["Inference Engine"]
+        InferModule["Infer\nEntry point"]
+        Params["Infer::Params\nParameter type\nfrom name + default"]
+        Returns["Infer::Returns\nReturn type\nfrom method body"]
+        Raises["Infer::Raises\n@raise tags\nfrom raise/rescue"]
+        Literals["Infer::Literals\nAST literal →\ntype string"]
+        Names["Infer::Names\n:const node →\nFQN string"]
+        ASTWalk["Infer::ASTWalk\nRecursive DFS\nAST traversal"]
+    end
+
+    subgraph Plugins["Plugin System"]
+        PluginModule["Plugin\nTag/Collector\ndispatch"]
+        Registry["Plugin::Registry\nGlobal registry\n· register → route\n· tag_entries\n· collector_entries"]
+        TagPlugin["Base::TagPlugin\nOverride #call(context)\n→ Array<Tag>"]
+        CollectorPlugin["Base::CollectorPlugin\nOverride #collect(ast, buffer)\n→ Array<Hash>"]
+        TagValue["Plugin::Tag\nStruct (name, text, types)"]
+        Context["Plugin::Context\nMethod snapshot struct"]
+    end
+
+    subgraph Types["External Type System"]
+        ProviderChain["ProviderChain\nComposite:\nquery in order\nfirst match wins"]
+        RBSProvider["RBS::Provider\n.rbs files\n→ RBS lib"]
+        RBSFormatter["RBS::TypeFormatter\nRBS type →\nYARD type string"]
+        RBSCollection["RBS::CollectionLoader\nrbs_collection\n.lock.yaml"]
+        SorbetBase["Sorbet::BaseProvider\nRBS::Prototype::RBI\nbridge"]
+        SorbetSource["Sorbet::SourceProvider\nInline sig{}\ndeclarations"]
+        SorbetRBI["Sorbet::RBIProvider\n.rbi files\ndirectories"]
+    end
+
+    Exe --> Run
+    Run --> Options
+    Run --> InitCmd
+    Run --> GenCmd
+    Run --> ConfigBuilder
+    ConfigBuilder --> ConfigClass
+    ConfigClass --> Defaults
+    ConfigClass --> Loader
+    ConfigClass --> Emit
+    ConfigClass --> Filtering
+    ConfigClass --> RBSConfig
+    ConfigClass --> SorbetConfig
+    ConfigClass --> PluginConfig
+    Run --> InlineRewriter
+    InlineRewriter --> ParsingModule
+    ParsingModule --> ParserGem
+    ParsingModule --> Prism
+    InlineRewriter --> Collector
+    Collector --> PluginModule
+    PluginModule --> Registry
+    Registry --> CollectorPlugin
+    InlineRewriter --> DocBuilder
+    DocBuilder --> InferModule
+    InferModule --> Params
+    InferModule --> Returns
+    InferModule --> Raises
+    Params --> Literals
+    Returns --> Literals
+    Raises --> ASTWalk
+    Raises --> Names
+    DocBuilder --> ProviderChain
+    ProviderChain --> SorbetSource
+    ProviderChain --> SorbetRBI
+    ProviderChain --> RBSProvider
+    SorbetSource --> SorbetBase
+    SorbetRBI --> SorbetBase
+    RBSProvider --> RBSFormatter
+    RBSProvider --> RBSCollection
+    DocBuilder --> PluginModule
+    PluginModule --> Registry
+    Registry --> TagPlugin
+    TagPlugin --> TagValue
+    TagPlugin --> Context
+    InlineRewriter --> DocBlock
+    InlineRewriter --> SourceHelpers
+```
+
+### Data flow
+
+```mermaid
+flowchart LR
+    Input["Source files\n(.rb)"] --> Parse["Parsing.parse_buffer\nParser gem / Prism"]
+    Parse --> AST["AST + Comments"]
+    AST --> Collect["Collector.process\n· Find methods\n· Track visibility\n· Find attr_*"]
+    AST --> CollectPlugins["CollectorPlugin#collect\n· Custom AST walks\n· Non-standard constructs"]
+    Collect --> Insertions["Insertion list\n(sorted by position)"]
+    CollectPlugins --> Insertions
+    Insertions --> Dedup["Deduplicate\n(override by position)"]
+    Dedup --> Build["DocBuilder.build_doc_lines\nper insertion"]
+    Build --> Infer["Infer params / returns / raises\n(heuristic fallback)"]
+    Build --> SigQuery["ProviderChain\nquery external types"]
+    Build --> TagPlugins["TagPlugin#call\n(add extra @tags)"]
+    Infer --> ResultDoc["Generated YARD doc block"]
+    SigQuery --> ResultDoc
+    TagPlugins --> ResultDoc
+    ResultDoc --> Strategy{"Strategy?"}
+    Strategy -->|Safe| Merge["DocBlock.merge\npreserve + append + sort"]
+    Strategy -->|Aggressive| Replace["Replace entirely"]
+    Merge --> Rewritten["Rewriter#process\n→ rewritten source"]
+    Replace --> Rewritten
+    Rewritten --> Output["Modified .rb file\n/ STDOUT"]
+```
+
 ## CLI
 
 ```shell
@@ -865,17 +1017,49 @@ class DefineMethodPlugin < Docscribe::Plugin::Base::CollectorPlugin
 end
 ```
 
-Each result hash must have:
+Each result hash must have `:anchor_node` plus either `:doc` or `:method_override`:
 
-| Key            | Type                | Description                                |
-|----------------|---------------------|--------------------------------------------|
-| `:anchor_node` | `Parser::AST::Node` | Node above which to insert the doc block   |
-| `:doc`         | `String`            | Complete doc block text including newlines |
+| Key                | Type                | Description                                                                                                             |
+|--------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------|
+| `:anchor_node`     | `Parser::AST::Node` | Node above which to insert the doc block                                                                                |
+| `:doc`             | `String`            | Complete doc block text including newlines (Docscribe may normalize indentation and default message for method anchors) |
+| `:method_override` | `Hash`              | Structured overrides that patch the standard DocBuilder output instead of replacing it (see below)                      |
 
 > [!NOTE]
 > You do not need to handle indentation manually. Docscribe reads the indentation from `anchor_node` and applies it to
 > every line of `:doc` automatically.
 
+#### Plugin doc normalization (CollectorPlugin)
+
+When returning `doc:`, CollectorPlugins provide raw strings that Docscribe inserts without running the standard
+method DocBuilder pipeline. Docscribe does normalize indentation and may prepend the default method message for
+`def/defs` anchors, but headers (`emit.header`) and param/return tags must be included explicitly.
+
+#### `method_override` (structured patch)
+
+When a CollectorPlugin targets a `def` method, it can return `method_override:` instead of `doc:` to patch the
+standard DocBuilder output rather than replace it entirely:
+
+```ruby
+{
+  anchor_node: node,
+  method_override: {
+    return_type: 'ActiveRecord::Relation', # overrides @return
+    param_types: { 'period' => 'Integer' }, # merges into @param types
+    tags: [Docscribe::Plugin::Tag.new(name: 'since', text: '2.0')] # additional tags
+  }
+}
+```
+
+| Key            | Type                   | Description                                                 |
+|----------------|------------------------|-------------------------------------------------------------|
+| `:return_type` | `String`               | Overrides the `@return` type name                           |
+| `:param_types` | `Hash{String=>String}` | Merges into inferred param types (external sig wins)        |
+| `:tags`        | `Array<Tag/Hash>`      | Tags appended to the doc block (Hash auto-converted to Tag) |
+
+`method_override` merges at the data level before rendering, so the standard pipeline still generates headers,
+`@param` tags, default messages, and tag sorting. Only the specified fields are overridden.
+
 ### Registering plugins
 
 Plugins are registered at load time. The recommended pattern is to put registrations in a dedicated file and reference
@@ -932,9 +1116,11 @@ Higher number means higher priority.
 
 **CollectorPlugin priority (conflicts at the same source position):**
 
-- If a plugin insertion and a standard *method* insertion share the same source position (
-  `anchor_node.loc.expression.begin_pos`), the standard insertion is dropped and the plugin insertion is kept.
-- If multiple CollectorPlugins insert at the same source position, only insertions from the highest-priority plugin(s)
+- For `doc:` insertions: if a plugin insertion and a standard *method* insertion share the same source position
+  (`anchor_node.loc.expression.begin_pos`), the standard insertion is dropped and the plugin insertion is kept.
+- For `method_override:` insertions: the method insertion is kept and patched with the override data. The standard
+  DocBuilder pipeline still runs (generating `@param`, headers, etc.), and only the specified fields are overridden.
+- If multiple CollectorPlugins target the same source position, only insertions from the highest-priority plugin(s)
   are kept (ties are kept).
 - Multiple insertions from the winning plugin(s) at the same position are preserved (e.g. one `@!attribute` per column).
 

data/lib/docscribe/cli/config_builder.rb

@@ -4,6 +4,7 @@ require 'docscribe/config'
 
 module Docscribe
   module CLI
+    # Build and override effective config from CLI flags.
     module ConfigBuilder
       module_function
 
@@ -21,53 +22,142 @@ module Docscribe
       # @param [Hash] options parsed CLI options
       # @return [Docscribe::Config] merged effective config
       def build(base, options)
-        needs_override =
-          options[:include].any?      ||
+        return base unless needs_override?(options)
+
+        raw = Marshal.load(Marshal.dump(base.raw))
+        apply_filter_overrides(raw, options)
+        apply_rbs_overrides(raw, options) if options[:rbs] || options[:rbs_collection] || options[:sig_dirs].any?
+        apply_sorbet_overrides(raw, options) if options[:sorbet] || options[:rbi_dirs].any?
+        Docscribe::Config.new(raw)
+      end
+
+      # Whether any CLI override is present.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [Hash] options parsed CLI options
+      # @return [Boolean]
+      def needs_override?(options)
+        filter_overrides?(options) ||
+          rbs_overrides?(options) ||
+          sorbet_overrides?(options)
+      end
+
+      # Whether any method or file filter CLI options were provided.
+      #
+      # @note module_function: when included, also defines #filter_overrides? (instance visibility: private)
+      # @param [Hash] options parsed CLI options
+      # @return [Boolean]
+      def filter_overrides?(options)
+        options[:include].any? ||
           options[:exclude].any?      ||
           options[:include_file].any? ||
-          options[:exclude_file].any? ||
-          options[:rbs]               ||
-          options[:rbs_collection]    ||
-          options[:sig_dirs].any?     ||
-          options[:sorbet]            ||
-          options[:rbi_dirs].any?
+          options[:exclude_file].any?
+      end
 
-        return base unless needs_override
+      # Whether any RBS-related CLI options were provided.
+      #
+      # @note module_function: when included, also defines #rbs_overrides? (instance visibility: private)
+      # @param [Hash] options parsed CLI options
+      # @return [Boolean]
+      def rbs_overrides?(options)
+        options[:rbs] ||
+          options[:rbs_collection] ||
+          options[:sig_dirs].any?
+      end
 
-        raw = Marshal.load(Marshal.dump(base.raw))
+      # Whether any Sorbet-related CLI options were provided.
+      #
+      # @note module_function: when included, also defines #sorbet_overrides? (instance visibility: private)
+      # @param [Hash] options parsed CLI options
+      # @return [Boolean]
+      def sorbet_overrides?(options)
+        options[:sorbet] ||
+          options[:rbi_dirs].any?
+      end
+
+      # Apply method and file filter overrides to the raw config.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [Hash] raw raw config hash
+      # @param [Hash] options parsed CLI options
+      # @return [void]
+      def apply_filter_overrides(raw, options)
+        apply_method_filters(raw, options)
+        apply_file_filters(raw, options)
+      end
 
+      # Merge CLI method include/exclude patterns into the raw config hash.
+      #
+      # @note module_function: when included, also defines #apply_method_filters (instance visibility: private)
+      # @param [Hash] raw raw config hash
+      # @param [Hash] options parsed CLI options
+      # @return [void]
+      def apply_method_filters(raw, options)
         raw['filter'] ||= {}
         raw['filter']['include'] = Array(raw['filter']['include']) + options[:include]
         raw['filter']['exclude'] = Array(raw['filter']['exclude']) + options[:exclude]
+      end
 
-        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[:rbs_collection] || 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?
-
-          if options[:rbs_collection]
-            require 'docscribe/types/rbs/collection_loader'
-            collection_path = Docscribe::Types::RBS::CollectionLoader.resolve
-            if collection_path
-              raw['rbs']['collection_dirs'] = Array(raw['rbs']['collection_dirs']) + [collection_path]
-            else
-              warn 'Docscribe: rbs_collection.lock.yaml not found or collection not installed. ' \
-                   'Run `bundle exec rbs collection install` first.'
-            end
-          end
-        end
+      # Merge CLI file include/exclude patterns into the raw config hash.
+      #
+      # @note module_function: when included, also defines #apply_file_filters (instance visibility: private)
+      # @param [Hash] raw raw config hash
+      # @param [Hash] options parsed CLI options
+      # @return [void]
+      def apply_file_filters(raw, options)
+        files = raw['filter']['files'] ||= {} #: Hash[String, untyped]
+        files['include'] = Array(files['include']) + options[:include_file]
+        files['exclude'] = Array(files['exclude']) + options[:exclude_file]
+      end
+
+      # Apply RBS-related CLI overrides to the raw config.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [Hash] raw raw config hash
+      # @param [Hash] options parsed CLI options
+      # @return [void]
+      def apply_rbs_overrides(raw, options)
+        raw['rbs'] ||= {}
+        raw['rbs']['enabled'] = true
+        raw['rbs']['sig_dirs'] = Array(raw['rbs']['sig_dirs']) + options[:sig_dirs] if options[:sig_dirs].any?
+
+        return unless options[:rbs_collection]
 
-        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?
+        apply_rbs_collection(raw)
+      end
+
+      # Resolve and apply the RBS collection path into the raw config hash.
+      #
+      # @note module_function: when included, also defines #apply_rbs_collection (instance visibility: private)
+      # @param [Hash] raw raw config hash
+      # @return [void]
+      def apply_rbs_collection(raw)
+        require 'docscribe/types/rbs/collection_loader'
+        collection_path = Docscribe::Types::RBS::CollectionLoader.resolve
+        if collection_path
+          raw['rbs']['collection_dirs'] = Array(raw['rbs']['collection_dirs']) + [collection_path]
+        else
+          warn 'Docscribe: rbs_collection.lock.yaml not found or collection not installed. ' \
+               'Run `bundle exec rbs collection install` first.'
         end
+      end
 
-        Docscribe::Config.new(raw)
+      # Apply Sorbet-related CLI overrides to the raw config.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [Hash] raw raw config hash
+      # @param [Hash] options parsed CLI options
+      # @return [void]
+      def apply_sorbet_overrides(raw, options)
+        raw['sorbet'] ||= {}
+        raw['sorbet']['enabled'] = true
+        return unless options[:rbi_dirs].any?
+
+        raw['sorbet']['rbi_dirs'] = Array(raw['sorbet']['rbi_dirs']) + options[:rbi_dirs]
       end
     end
   end