docscribe 1.4.1 → 1.5.0

data/lib/docscribe/cli/check_for_comments.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+require 'docscribe/config/defaults'
+require 'docscribe/config/loader'
+require 'docscribe/config/emit'
+
+module Docscribe
+  module CLI
+    # Check for default placeholder text in generated documentation.
+    #
+    # Usage:
+    #   docscribe check_for_comments [paths...]
+    #
+    # Reads the configured placeholder messages from docscribe.yml (or defaults)
+    # and scans Ruby source files for YARD comments containing those placeholders.
+    # Exits non-zero if any are found.
+    module CheckForComments
+      BANNER = <<~TEXT
+        Usage: docscribe check_for_comments [paths...]
+
+        Check for default placeholder documentation text in Ruby source files.
+
+        Reads placeholder messages from docscribe.yml config (or built-in defaults)
+        and scans .rb files for YARD comments still containing that text.
+
+        Useful in CI to catch auto-generated text that should have been replaced.
+      TEXT
+
+      class << self
+        # @param [Array<String>] argv
+        # @return [Integer]
+        def run(argv)
+          config = Docscribe::Config.load
+          placeholders = resolve_placeholders(config)
+          return no_placeholders_configured if placeholders.empty?
+
+          parse_options(argv)
+          paths = expand_paths(argv)
+          return no_paths if paths.empty?
+
+          results = scan_paths(paths, placeholders)
+          process_results(results)
+        end
+
+        private
+
+        # @private
+        # @param [Docscribe::Config] config
+        # @return [Array<String>]
+        def resolve_placeholders(config)
+          default_msg = raw_or_default(config, %w[doc default_message])
+          param_doc = config.param_documentation
+          [default_msg, param_doc].compact.uniq
+        end
+
+        # @private
+        # @param [Docscribe::Config] config
+        # @param [Array<String>] keys nested keys
+        # @return [String, nil]
+        def raw_or_default(config, keys)
+          raw = config.raw.dig(*keys)
+          return raw if raw
+
+          Docscribe::Config::DEFAULT.dig(*keys)
+        end
+
+        # @private
+        # @return [Integer]
+        def no_placeholders_configured
+          warn 'Docscribe: No placeholder messages configured. Nothing to check.'
+          0
+        end
+
+        # @private
+        # @param [Array<String>] argv
+        # @return [void]
+        def parse_options(argv)
+          OptionParser.new(BANNER) do |opts|
+            opts.on('-h', '--help', 'Show this help') { puts opts or exit 0 }
+          end.parse!(argv)
+        end
+
+        # @private
+        # @param [Array<String>] args
+        # @return [Array<String>]
+        def expand_paths(args)
+          files = [] #: Array[String]
+          args = ['.'] if args.empty?
+          args.each { |path| expand_single_path(files, path) }
+          files.uniq.sort
+        end
+
+        # @private
+        # @param [Array<String>] files
+        # @param [String] path
+        # @return [void]
+        def expand_single_path(files, path)
+          if File.directory?(path)
+            files.concat(Dir.glob(File.join(path, '**', '*.rb')))
+          elsif File.file?(path) && path.end_with?('.rb')
+            files << path
+          elsif File.file?(path)
+            warn "Skipping non-Ruby file: #{path}"
+          else
+            warn "Skipping missing path: #{path}"
+          end
+        end
+
+        # @private
+        # @return [Integer]
+        def no_paths
+          warn 'No files found. Pass files or directories (e.g. `docscribe check_for_comments lib`).'
+          1
+        end
+
+        # @private
+        # @param [Array<String>] paths
+        # @param [Array<String>] placeholders
+        # @return [Array<(String, Array<(Integer, String)>)>]
+        def scan_paths(paths, placeholders)
+          paths.filter_map { |path| scan_file(path, placeholders) }
+        end
+
+        # @private
+        # @param [Array<(String, Array<(Integer, String)>)>] results
+        # @return [Integer]
+        def process_results(results)
+          if results.empty?
+            puts 'Docscribe: No placeholder documentation found.'
+            0
+          else
+            report(results)
+            1
+          end
+        end
+
+        # @private
+        # @param [String] path
+        # @param [Array<String>] placeholders
+        # @return [(String, Array<(Integer, String)>)?]
+        def scan_file(path, placeholders)
+          lines = File.readlines(path)
+          matches = [] #: Array[[Integer, String]]
+
+          lines.each_with_index do |line, idx|
+            next unless comment_line?(line)
+
+            placeholders.each do |placeholder|
+              matches << [idx + 1, line.strip] if line.include?(placeholder)
+            end
+          end
+
+          [path, matches] if matches.any?
+        end
+
+        # @private
+        # @param [String] line
+        # @return [Boolean]
+        def comment_line?(line)
+          stripped = line.strip
+          stripped.start_with?('#') && !stripped.match?(/^#\s*#/)
+        end
+
+        # @private
+        # @param [Array<(String, Array<(Integer, String)>)>] results
+        # @return [void]
+        def report(results)
+          total = results.sum { |_path, matches| matches.size }
+          puts "Docscribe: Found #{total} placeholder(s) in #{results.size} file(s):"
+          puts
+
+          results.each do |path, matches|
+            matches.each do |line_num, text|
+              puts "  #{path}:#{line_num}  #{text}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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
 
@@ -16,58 +17,201 @@ module Docscribe
       #
       # If no relevant CLI override is present, the original config is returned unchanged.
       #
-      # @note module_function: when included, also defines #build (instance visibility: private)
+      # @note module_function: defines #build (visibility: private)
       # @param [Docscribe::Config] base base config loaded from YAML/defaults
-      # @param [Hash] options parsed CLI options
+      # @param [Hash<Symbol, Object>] 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 rbs_overrides?(options)
+        apply_sorbet_overrides(raw, options) if sorbet_overrides?(options)
+        apply_output_overrides(raw, options)
+        conf = Docscribe::Config.new(raw)
+        warn_missing_rbs_collection(conf, options)
+        conf
+      end
+
+      # Whether any CLI override is present.
+      #
+      # @note module_function: defines #needs_override? (visibility: private)
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [Boolean]
+      def needs_override?(options)
+        filter_overrides?(options) ||
+          rbs_overrides?(options) ||
+          sorbet_overrides?(options) ||
+          output_overrides?(options)
+      end
+
+      # Whether any method or file filter CLI options were provided.
+      #
+      # @note module_function: defines #filter_overrides? (visibility: private)
+      # @param [Hash<Symbol, Object>] 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
+      # Apply method and file filter overrides to the raw config.
+      #
+      # @note module_function: defines #apply_filter_overrides (visibility: private)
+      # @param [Hash<String, Object>] raw raw config hash
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [void]
+      def apply_filter_overrides(raw, options)
+        apply_method_filters(raw, options)
+        apply_file_filters(raw, options)
+      end
 
-        raw = Marshal.load(Marshal.dump(base.raw))
+      # Whether any RBS-related CLI options were provided.
+      #
+      # @note module_function: defines #rbs_overrides? (visibility: private)
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [Boolean]
+      def rbs_overrides?(options)
+        options[:rbs] ||
+          options[:rbs_collection] ||
+          options[:sig_dirs].any?
+      end
 
+      # Merge CLI method include/exclude patterns into the raw config hash.
+      #
+      # @note module_function: defines #apply_method_filters (visibility: private)
+      # @param [Hash<String, Object>] raw raw config hash
+      # @param [Hash<Symbol, Object>] 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
+      # Merge CLI file include/exclude patterns into the raw config hash.
+      #
+      # @note module_function: defines #apply_file_filters (visibility: private)
+      # @param [Hash<String, Object>] raw raw config hash
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [void]
+      def apply_file_filters(raw, options)
+        files = raw['filter']['files']
+        if files.nil?
+          files = {} #: Hash[String, untyped]
+          raw['filter']['files'] = files
         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?
+        files['include'] = Array(files['include']) + options[:include_file]
+        files['exclude'] = Array(files['exclude']) + options[:exclude_file]
+        files
+      end
+
+      # Apply RBS-related CLI overrides to the raw config.
+      #
+      # @note module_function: defines #apply_rbs_overrides (visibility: private)
+      # @param [Hash<String, Object>] raw raw config hash
+      # @param [Hash<Symbol, Object>] 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]
+
+        apply_rbs_collection(raw)
+      end
+
+      # Whether any Sorbet-related CLI options were provided.
+      #
+      # @note module_function: defines #sorbet_overrides? (visibility: private)
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [Boolean]
+      def sorbet_overrides?(options)
+        options[:sorbet] ||
+          options[:rbi_dirs].any?
+      end
+
+      # Resolve and apply the RBS collection path into the raw config hash.
+      #
+      # @note module_function: defines #apply_rbs_collection (visibility: private)
+      # @param [Hash<String, Object>] 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. ' \
+               'Run `bundle exec rbs collection install` first.'
         end
+      end
+
+      # Apply Sorbet-related CLI overrides to the raw config.
+      #
+      # @note module_function: defines #apply_sorbet_overrides (visibility: private)
+      # @param [Hash<String, Object>] raw raw config hash
+      # @param [Hash<Symbol, Object>] 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
+
+      # Whether any output-related CLI options were provided.
+      #
+      # @note module_function: defines #output_overrides? (visibility: private)
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [Boolean]
+      def output_overrides?(options)
+        !!options[:keep_descriptions] || !!options[:no_boilerplate]
+      end
+
+      # Apply output-related CLI overrides to the raw config.
+      #
+      # Currently handles:
+      # - `keep_descriptions` -> raw['keep_descriptions']
+      # - `no_boilerplate` -> raw['emit']['include_default_message'] and
+      #   raw['emit']['include_param_documentation'] = false
+      #
+      # @note module_function: defines #apply_output_overrides (visibility: private)
+      # @param [Hash<String, Object>] raw raw config hash
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [void]
+      def apply_output_overrides(raw, options)
+        return unless options[:keep_descriptions] || options[:no_boilerplate]
+
+        raw['keep_descriptions'] = true if options[:keep_descriptions]
+        raw['emit'] ||= {}
+        raw['emit']['include_default_message'] = false if options[:no_boilerplate]
+        raw['emit']['include_param_documentation'] = false if options[:no_boilerplate]
+      end
+
+      # Warn when rbs_collection.lock.yaml exists but --rbs-collection was not passed.
+      #
+      # The warning can be suppressed by setting `rbs.warn_missing_collection: false`
+      # in the project's `docscribe.yml`.
+      #
+      # @note module_function: defines #warn_missing_rbs_collection (visibility: private)
+      # @param [Docscribe::Config] conf effective config
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [void]
+      def warn_missing_rbs_collection(conf, options)
+        return if options[:rbs_collection]
+        return unless conf.rbs_warn_missing_collection?
+        return unless File.exist?('rbs_collection.lock.yaml')
 
-        Docscribe::Config.new(raw)
+        warn 'Docscribe: rbs_collection.lock.yaml found but --rbs-collection not set. ' \
+             'Pass --rbs-collection or set `rbs.collection: true` in docscribe.yml to enable RBS collection. ' \
+             'Set `rbs.warn_missing_collection: false` to suppress this warning.'
       end
     end
   end