docscribe 1.4.1 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e59e0f95a3faa67d4d9d7829ed32e2acd30f3fa5b3236f93d4b5f8bb63ae7616
-  data.tar.gz: cae706be421e11e31c6124a5e918c407b09a0cdd4435c2ad2d427b63ea4a9f80
+  metadata.gz: 5b6ff6ead507182a9530fa2f2cc690d435448284f9212f4fbeea3950dddf40c3
+  data.tar.gz: 17e3285caddd09bda308e89f5cb1eb4579d8f96855177f81dbe459b7ad84e9d4
 SHA512:
-  metadata.gz: c864edd9a99ad81667030ccfc13936ebb8d13948528bc288235aa2e4ff0de349b16eb3bf3f2b9606d33c8af9129357639a29db319e0c62bddd6ec1df997a7fea
-  data.tar.gz: 4c62242b2455c5a6117ba4e1f02335b911b4894c6f15aa852c704d9583cd89ca6e0439fcc4cee6d6b3decb6e33afb75c90effa71a5a24c9e39f3fe56e0245a35
+  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)
@@ -86,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)
@@ -204,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

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