docscribe 1.4.2 → 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

@@ -17,36 +17,39 @@ 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)
         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)
+        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: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [Hash] options parsed CLI options
+      # @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)
+          sorbet_overrides?(options) ||
+          output_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
+      # @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? ||
@@ -55,10 +58,21 @@ module Docscribe
           options[:exclude_file].any?
       end
 
+      # 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
+
       # 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
+      # @note module_function: defines #rbs_overrides? (visibility: private)
+      # @param [Hash<Symbol, Object>] options parsed CLI options
       # @return [Boolean]
       def rbs_overrides?(options)
         options[:rbs] ||
@@ -66,33 +80,11 @@ module Docscribe
           options[:sig_dirs].any?
       end
 
-      # 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
+      # @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'] ||= {}
@@ -102,22 +94,27 @@ module Docscribe
 
       # 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
+      # @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'] ||= {} #: Hash[String, untyped]
+        files = raw['filter']['files']
+        if files.nil?
+          files = {} #: Hash[String, untyped]
+          raw['filter']['files'] = files
+        end
+
         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: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [Hash] raw raw config hash
-      # @param [Hash] options parsed CLI options
+      # @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'] ||= {}
@@ -129,10 +126,20 @@ module Docscribe
         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: when included, also defines #apply_rbs_collection (instance visibility: private)
-      # @param [Hash] raw 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'
@@ -140,17 +147,16 @@ module Docscribe
         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. ' \
+          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: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [Hash] raw raw config hash
-      # @param [Hash] options parsed CLI options
+      # @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'] ||= {}
@@ -159,6 +165,54 @@ module Docscribe
 
         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')
+
+        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
 end