docscribe 1.5.1 → 1.6.0

data/lib/docscribe/cli/coverage.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'docscribe/config'
+require 'docscribe/cli/config_builder'
+require 'docscribe/cli/options'
+
+module Docscribe
+  module CLI
+    # Generate documentation coverage report for Ruby files.
+    module Coverage
+      BANNER = <<~TEXT
+        Usage: docscribe coverage [options] [paths]
+
+        Generate documentation coverage report.
+
+        Options:
+      TEXT
+
+      # @!attribute [rw] total_methods
+      #   @return [Integer]
+      #   @param [Integer] value
+      #
+      # @!attribute [rw] documented_methods
+      #   @return [Integer]
+      #   @param [Integer] value
+      #
+      # @!attribute [rw] total_params
+      #   @return [Integer]
+      #   @param [Integer] value
+      #
+      # @!attribute [rw] documented_params
+      #   @return [Integer]
+      #   @param [Integer] value
+      #
+      # @!attribute [rw] total_returns
+      #   @return [Integer]
+      #   @param [Integer] value
+      #
+      # @!attribute [rw] documented_returns
+      #   @return [Integer]
+      #   @param [Integer] value
+      CoverageStats = Struct.new(
+        :total_methods, :documented_methods,
+        :total_params, :documented_params,
+        :total_returns, :documented_returns,
+        keyword_init: true
+      )
+
+      # Struct tracking documentation coverage metrics per file.
+      class CoverageStats
+        # @return [Integer, Float]
+        def method_coverage
+          total_methods.zero? ? 100.0 : (documented_methods.to_f / total_methods * 100).round(1)
+        end
+
+        # @return [Integer, Float]
+        def param_coverage
+          total_params.zero? ? 100.0 : (documented_params.to_f / total_params * 100).round(1)
+        end
+
+        # @return [Integer, Float]
+        def return_coverage
+          total_returns.zero? ? 100.0 : (documented_returns.to_f / total_returns * 100).round(1)
+        end
+      end
+
+      class << self
+        # @param [Array<String>] argv
+        # @return [Integer]
+        def run(argv)
+          opts = parse_options(argv)
+          return 0 if opts[:help]
+
+          conf = Docscribe::Config.load(opts[:config])
+          paths = expand_paths(argv, conf)
+
+          stats = analyze_coverage(paths, conf)
+
+          print_report(stats, opts)
+          0
+        end
+
+        private
+
+        # @private
+        # @param [Array<String>] argv
+        # @return [Hash<Symbol, Object>]
+        def parse_options(argv)
+          opts = { config: nil, format: 'text' }
+          build_parser(opts).parse!(argv)
+          opts
+        end
+
+        # @private
+        # @param [Hash<Symbol, Object>] opts
+        # @return [OptionParser]
+        def build_parser(opts)
+          OptionParser.new do |o|
+            o.banner = BANNER
+            o.on('--config PATH', 'Path to config file') { |v| opts[:config] = v }
+            o.on('--format FORMAT', 'Output format (text, json)') { |v| opts[:format] = v }
+            o.on('-h', '--help', 'Show help') do
+              opts[:help] = true
+              puts o
+            end
+          end
+        end
+
+        # @private
+        # @param [Array<String>] argv
+        # @param [Docscribe::Config] conf
+        # @return [Array<String>]
+        def expand_paths(argv, conf)
+          require 'pathname'
+          args = argv.empty? ? ['.'] : argv
+          files = expand_files(args)
+          files.uniq.sort.select { |p| conf.process_file?(p) }
+        end
+
+        # @private
+        # @param [Array<String>] args
+        # @return [Array<String>]
+        def expand_files(args)
+          files = [] #: Array[String]
+          args.each do |path|
+            if File.directory?(path)
+              files.concat(Dir.glob(File.join(path, '**', '*.rb')))
+            elsif File.file?(path)
+              files << path
+            end
+          end
+          files
+        end
+
+        # @private
+        # @param [Array<String>] paths
+        # @param [Docscribe::Config] _conf
+        # @return [Docscribe::CLI::Coverage::CoverageStats]
+        def analyze_coverage(paths, _conf)
+          require 'docscribe/parsing'
+          require 'parser/current'
+
+          stats = init_stats
+          paths.each { |path| analyze_file(path, stats) }
+          stats
+        end
+
+        # @private
+        # @return [Docscribe::CLI::Coverage::CoverageStats]
+        def init_stats
+          CoverageStats.new(
+            total_methods: 0, documented_methods: 0,
+            total_params: 0, documented_params: 0,
+            total_returns: 0, documented_returns: 0
+          )
+        end
+
+        # @private
+        # @param [String] path
+        # @param [Docscribe::CLI::Coverage::CoverageStats] stats
+        # @raise [StandardError]
+        # @return [void]
+        # @return [nil] if StandardError
+        def analyze_file(path, stats)
+          src = File.read(path)
+          buffer = Parser::Source::Buffer.new(path, source: src)
+          ast = Docscribe::Parsing.parse_buffer(buffer)
+          analyze_node(ast, stats, src) if ast
+        rescue StandardError => e
+          warn "Skipping #{path}: #{e.message}" if ENV.fetch('DOCSCRIBE_DEBUG', false)
+        end
+
+        # @private
+        # @param [Object] node
+        # @param [Docscribe::CLI::Coverage::CoverageStats] stats
+        # @param [String] src
+        # @return [void]
+        def analyze_node(node, stats, src)
+          return unless node.is_a?(Parser::AST::Node)
+
+          analyze_method_node(node, stats, src) if %i[def defs].include?(node.type)
+
+          node.children.each { |child| analyze_node(child, stats, src) if child.is_a?(Parser::AST::Node) }
+        end
+
+        # @private
+        # @param [Object] node
+        # @param [Docscribe::CLI::Coverage::CoverageStats] stats
+        # @param [String] src
+        # @return [void]
+        def analyze_method_node(node, stats, src)
+          stats.total_methods += 1
+          doc_comment = extract_doc_comment(src, node.loc.expression.line)
+
+          if doc_comment
+            analyze_documented_method(node, stats, doc_comment)
+          else
+            stats.total_returns += 1
+            count_method_params(node, stats)
+          end
+        end
+
+        # @private
+        # @param [Object] node
+        # @param [Docscribe::CLI::Coverage::CoverageStats] stats
+        # @param [String] doc_comment
+        # @return [void]
+        def analyze_documented_method(node, stats, doc_comment)
+          stats.documented_methods += 1
+          stats.documented_returns += 1 if doc_comment.match?(/@return\b/)
+          stats.total_returns += 1
+
+          param_matches = doc_comment.scan(/@param\b/)
+          param_count = count_params(node)
+          stats.total_params += param_count
+          stats.documented_params += [param_matches.size, param_count].min
+        end
+
+        # @private
+        # @param [Object] node
+        # @param [Docscribe::CLI::Coverage::CoverageStats] stats
+        # @return [void]
+        def count_method_params(node, stats)
+          stats.total_params += count_params(node)
+        end
+
+        # @private
+        # @param [Object] node
+        # @return [Integer]
+        def count_params(node)
+          args_node = node.children[2] || node.children[1]
+          return 0 unless args_node.is_a?(Parser::AST::Node) && args_node.type == :args
+
+          args_node.children.count { |a| %i[arg optarg kwarg kwoptarg restarg].include?(a.type) }
+        end
+
+        # @private
+        # @param [String] src
+        # @param [Integer] method_line
+        # @return [String?]
+        def extract_doc_comment(src, method_line)
+          lines = src.lines
+          comment_lines = collect_comment_lines(lines, method_line)
+          comment_lines.empty? ? nil : comment_lines.join
+        end
+
+        # @private
+        # @param [Array<String>] lines
+        # @param [Integer] method_line
+        # @return [Array<String>]
+        def collect_comment_lines(lines, method_line)
+          comment_lines = [] #: Array[String]
+          idx = method_line - 2
+          while idx >= 0
+            line = lines[idx]
+            break unless line =~ /^\s*#/
+
+            comment_lines.unshift(line)
+            idx -= 1
+          end
+          comment_lines
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Coverage::CoverageStats] stats
+        # @param [Hash<Symbol, Object>] opts
+        # @return [void]
+        def print_report(stats, opts)
+          case opts[:format]
+          when 'json'
+            print_json_report(stats)
+          else
+            print_text_report(stats)
+          end
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Coverage::CoverageStats] stats
+        # @return [void]
+        def print_json_report(stats)
+          require 'json'
+          puts JSON.pretty_generate(
+            methods: report_entry(stats.total_methods, stats.documented_methods, stats.method_coverage),
+            params: report_entry(stats.total_params, stats.documented_params, stats.param_coverage),
+            returns: report_entry(stats.total_returns, stats.documented_returns, stats.return_coverage)
+          )
+        end
+
+        # @private
+        # @param [Integer] total
+        # @param [Integer] documented
+        # @param [Integer, Float] coverage
+        # @return [Hash<Symbol, Integer, Float>]
+        def report_entry(total, documented, coverage)
+          { total: total, documented: documented, coverage: coverage }
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Coverage::CoverageStats] stats
+        # @return [void]
+        def print_text_report(stats)
+          puts 'Documentation Coverage Report'
+          puts '============================='
+          puts
+          puts "Methods: #{stats.documented_methods}/#{stats.total_methods} (#{stats.method_coverage}%)"
+          puts "Params:  #{stats.documented_params}/#{stats.total_params} (#{stats.param_coverage}%)"
+          puts "Returns: #{stats.documented_returns}/#{stats.total_returns} (#{stats.return_coverage}%)"
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/cli/init.rb

@@ -58,7 +58,7 @@ module Docscribe
         # @private
         # @return [Hash<Symbol, String, Boolean>]
         def default_init_options
-          { config: 'docscribe.yml', force: false, stdout: false, help: false }
+          { config: 'docscribe.yml', force: false, stdout: false, help: false, pre_commit: false }
         end
 
         # Build and return an OptionParser for the init command.
@@ -69,9 +69,7 @@ module Docscribe
         def build_init_parser(opts)
           OptionParser.new do |o|
             o.banner = BANNER
-            o.on('--config PATH', 'Where to write the config (default: docscribe.yml)') { |v| opts[:config] = v }
-            o.on('-f', '--force', 'Overwrite if the file already exists') { opts[:force] = true }
-            o.on('--stdout', 'Print config template to STDOUT instead of writing a file') { opts[:stdout] = true }
+            add_init_options(o, opts)
             o.on('-h', '--help', 'Show this help') do
               opts[:help] = true
               puts o
@@ -79,6 +77,19 @@ module Docscribe
           end
         end
 
+        # Add init-specific CLI options to the parser.
+        #
+        # @private
+        # @param [OptionParser] parser
+        # @param [Hash<Symbol, Object>] opts options hash
+        # @return [void]
+        def add_init_options(parser, opts)
+          parser.on('--config PATH', 'Where to write the config (default: docscribe.yml)') { |v| opts[:config] = v }
+          parser.on('-f', '--force', 'Overwrite if the file already exists') { opts[:force] = true }
+          parser.on('--stdout', 'Print config template to STDOUT instead of writing a file') { opts[:stdout] = true }
+          parser.on('--pre-commit', 'Install pre-commit hook for docscribe check') { opts[:pre_commit] = true }
+        end
+
         # Write the config template to a file.
         #
         # @private
@@ -86,6 +97,8 @@ module Docscribe
         # @param [String] yaml config template content
         # @return [Integer] exit code
         def write_init_config(opts, yaml)
+          return install_pre_commit_hook(opts) if opts[:pre_commit]
+
           path = opts[:config]
           if File.exist?(path) && !opts[:force]
             warn "Config already exists: #{path} (use --force to overwrite)"
@@ -96,6 +109,70 @@ module Docscribe
           puts "Created: #{path}"
           0
         end
+
+        # @private
+        # @param [Hash<Symbol, Object>] opts
+        # @return [Integer]
+        def install_pre_commit_hook(opts)
+          hook_dir = File.join('.git', 'hooks')
+          hook_path = File.join(hook_dir, 'pre-commit')
+
+          return 1 unless hook_preconditions_met?(hook_dir, hook_path, opts)
+
+          File.write(hook_path, pre_commit_hook_script)
+          File.chmod(0o755, hook_path)
+          puts "Installed pre-commit hook: #{hook_path}"
+          0
+        end
+
+        # Check pre-commit hook installation preconditions.
+        #
+        # @private
+        # @param [String] hook_dir
+        # @param [String] hook_path
+        # @param [Hash<Symbol, Object>] opts
+        # @return [Boolean]
+        def hook_preconditions_met?(hook_dir, hook_path, opts)
+          unless Dir.exist?(hook_dir)
+            warn 'No .git/hooks directory found. Are you in a git repository?'
+            return false
+          end
+
+          if File.exist?(hook_path) && !opts[:force]
+            warn "Pre-commit hook already exists: #{hook_path} (use --force to overwrite)"
+            return false
+          end
+
+          true
+        end
+
+        # Generate the pre-commit hook shell script content.
+        #
+        # @private
+        # @return [String]
+        def pre_commit_hook_script
+          <<~HOOK
+            #!/bin/sh
+            # Docscribe pre-commit hook
+            # Runs docscribe check on staged Ruby files
+
+            STAGED_RUBY_FILES=$(git diff --cached --name-only --diff-filter=ACM -- '*.rb')
+            if [ -z "$STAGED_RUBY_FILES" ]; then
+              exit 0
+            fi
+
+            echo "Checking documentation with docscribe..."
+            bundle exec docscribe check $STAGED_RUBY_FILES
+            RESULT=$?
+
+            if [ $RESULT -ne 0 ]; then
+              echo "Documentation check failed. Please add documentation before committing."
+              exit 1
+            fi
+
+            exit 0
+          HOOK
+        end
       end
     end
   end

data/lib/docscribe/cli/options.rb

@@ -27,6 +27,7 @@ module Docscribe
         keep_descriptions: false,
         no_boilerplate: false,
         progress: false,
+        parallel: false,
         server: false
       }.freeze
 
@@ -76,6 +77,8 @@ module Docscribe
             -q, --quiet                    Only show status, no details
                 --format FORMAT            Output format: text (default), json, or sarif
 
+        Performance:
+                --parallel                 Process files in parallel (default: sequential)
 
         Other:
             -v, --version                  Print version and exit
@@ -335,6 +338,7 @@ module Docscribe
       def define_output_options(opts, options)
         define_verbose_option(opts, options)
         define_progress_option(opts, options)
+        define_parallel_option(opts, options)
         define_explain_option(opts, options)
         define_quiet_option(opts, options)
         define_format_option(opts, options)
@@ -367,6 +371,18 @@ module Docscribe
         end
       end
 
+      # Define parallel option
+      #
+      # @note module_function: defines #define_parallel_option (visibility: private)
+      # @param [Hash<Symbol, Object>] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_parallel_option(opts, options)
+        opts.on('--parallel', 'Process files in parallel (default: sequential)') do
+          options[:parallel] = true
+        end
+      end
+
       # Define explain option
       #
       # @note module_function: defines #define_explain_option (visibility: private)

data/lib/docscribe/cli/rbs_gen.rb

@@ -85,7 +85,8 @@ module Docscribe
       # @!attribute [rw] inside_sclass
       #   @return [Boolean]
       #   @param [Boolean] value
-      WalkContext = Struct.new(:containers, :method_defs, :path, :comment_map, :src_lines, :inside_sclass, keyword_init: true)
+      WalkContext = Struct.new(:containers, :method_defs, :path, :comment_map, :src_lines, :inside_sclass,
+                               keyword_init: true)
 
       class << self
         # @param [Array<String>] argv
@@ -167,7 +168,7 @@ module Docscribe
         # @return [Boolean] if StandardError
         def generate_for_file(path, options)
           process_source?(File.read(path), path, options)
-        rescue Parser::SyntaxError => e # steep:ignore
+        rescue Parser::SyntaxError => e
           warn "Syntax error in #{path}: #{e.message}"
           false
         rescue StandardError => e

data/lib/docscribe/cli/run.rb

@@ -35,6 +35,8 @@ module Docscribe
           processed: 0
         }.freeze
 
+        PARALLEL_DEFAULT_THREADS = 4
+
         CLI_OVERRIDE_KEYS = %i[
           keep_descriptions no_boilerplate
           include exclude include_file exclude_file
@@ -382,6 +384,8 @@ module Docscribe
         # @param [Array<String>] paths Ruby file paths to process
         # @return [Integer] process exit code
         def run_files(options:, conf:, paths:)
+          return run_files_parallel(options: options, conf: conf, paths: paths) if options[:parallel] && paths.size > 1
+
           $stdout.sync = true
 
           state = initial_run_state
@@ -397,6 +401,136 @@ module Docscribe
           run_exit_code(options, state)
         end
 
+        # Process files in parallel using a Thread pool.
+        #
+        # @param [Docscribe::CLI::Formatters::opts] options parsed CLI options
+        # @param [Docscribe::Config] conf effective config
+        # @param [Array<String>] paths Ruby file paths to process
+        # @return [Integer] process exit code
+        def run_files_parallel(options:, conf:, paths:)
+          $stdout.sync = true
+          state = initial_run_state
+          state[:total] = paths.size
+          run_parallel_workers(options, conf, paths, state)
+          finalize_run(options, state)
+          run_exit_code(options, state)
+        end
+
+        # @param [Object] options
+        # @param [Object] conf
+        # @param [Array<String>] paths
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @return [void]
+        def run_parallel_workers(options, conf, paths, state)
+          pool = {
+            paths: paths, state: state, options: options, conf: conf,
+            pwd: Pathname.pwd, mutex: Mutex.new, error_mutex: Mutex.new
+          }
+          thread_count = [ENV.fetch('DOCSCRIBE_THREADS', PARALLEL_DEFAULT_THREADS).to_i, 1].max
+          thread_count.times.map { parallel_worker(pool) }.each(&:join)
+        end
+
+        # @param [Hash<Symbol, Object>] pool
+        # @return [Thread]
+        def parallel_worker(pool)
+          Thread.new do
+            loop do
+              path = fetch_work(pool[:paths], pool[:mutex]) or break
+              run_and_merge(path, pool)
+            end
+          end
+        end
+
+        # @param [Array<String>] paths
+        # @param [Thread::Mutex] mutex
+        # @return [String?]
+        def fetch_work(paths, mutex)
+          path = nil
+          mutex.synchronize { path = paths.shift }
+          path
+        end
+
+        # @param [String] path
+        # @param [Hash<Symbol, Object>] pool
+        # @raise [StandardError]
+        # @return [void]
+        # @return [Object] if StandardError
+        def run_and_merge(path, pool)
+          local_state = initial_run_state
+          process_one_file(path, options: pool[:options], conf: pool[:conf], pwd: pool[:pwd], state: local_state)
+          merge_state(pool[:state], local_state, pool[:error_mutex])
+        rescue StandardError => e
+          handle_worker_error(e, path, pool[:state], pool[:error_mutex])
+        end
+
+        # @param [StandardError] exception
+        # @param [String] path
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @param [Thread::Mutex] error_mutex
+        # @return [void]
+        def handle_worker_error(exception, path, state, error_mutex)
+          error_mutex.synchronize do
+            state[:had_errors] = true
+            state[:error_paths] << path
+            state[:error_messages][path] = "#{exception.class}: #{exception.message}"
+          end
+          $stderr.print('E')
+        end
+
+        # Merge a thread-local state into the shared state under mutex protection.
+        #
+        # @param [Docscribe::CLI::Formatters::state] target shared state to merge into
+        # @param [Docscribe::CLI::Formatters::state] source thread-local state to merge from
+        # @param [Thread::Mutex] mutex mutex protecting the target state
+        # @return [void]
+        def merge_state(target, source, mutex)
+          mutex.synchronize do
+            merge_state_flags(target, source)
+            merge_state_counts(target, source)
+            merge_state_arrays(target, source)
+            merge_state_hashes(target, source)
+          end
+        end
+
+        # @param [Docscribe::CLI::Formatters::state] target
+        # @param [Docscribe::CLI::Formatters::state] source
+        # @return [void]
+        def merge_state_flags(target, source)
+          target[:changed] ||= source[:changed]
+          target[:had_errors] ||= source[:had_errors]
+        end
+
+        # @param [Docscribe::CLI::Formatters::state] target
+        # @param [Docscribe::CLI::Formatters::state] source
+        # @return [void]
+        def merge_state_counts(target, source)
+          target[:checked_ok] += source[:checked_ok]
+          target[:checked_fail] += source[:checked_fail]
+          target[:corrected] += source[:corrected]
+          target[:processed] += source[:processed]
+        end
+
+        # @param [Docscribe::CLI::Formatters::state] target
+        # @param [Docscribe::CLI::Formatters::state] source
+        # @return [void]
+        def merge_state_arrays(target, source)
+          target[:corrected_paths].concat(source[:corrected_paths])
+          target[:fail_paths].concat(source[:fail_paths])
+          target[:error_paths].concat(source[:error_paths])
+          target[:type_mismatch_paths].concat(source[:type_mismatch_paths])
+        end
+
+        # @param [Docscribe::CLI::Formatters::state] target
+        # @param [Docscribe::CLI::Formatters::state] source
+        # @return [void]
+        def merge_state_hashes(target, source)
+          %i[corrected_changes fail_changes error_messages type_mismatch_changes].each do |key|
+            t = target[key] #: Hash[String, untyped]
+            s = source[key] #: Hash[String, untyped]
+            s.each { |k, v| t[k] = v }
+          end
+        end
+
         # @param [Docscribe::CLI::Formatters::opts] options
         # @return [Hash<String, Object>]
         def extract_cli_overrides(options)

data/lib/docscribe/cli/sigs.rb

@@ -169,7 +169,7 @@ module Docscribe
           return unless ast
 
           walk_for_methods(ast, [], methods, path)
-        rescue Parser::SyntaxError => e # steep:ignore
+        rescue Parser::SyntaxError => e
           warn "Syntax error in #{path}: #{e.message}"
         rescue StandardError => e
           warn "Error parsing #{path}: #{e.class}: #{e.message}"

data/lib/docscribe/cli.rb

@@ -18,13 +18,15 @@ module Docscribe
       end
 
       COMMANDS = {
-        'init' => :Init,
+        'check_for_comments' => :CheckForComments,
+        'config' => :ConfigDump,
+        'coverage' => :Coverage,
         'generate' => :Generate,
-        'sigs' => :Sigs,
+        'init' => :Init,
         'rbs' => :RbsGen,
-        'update_types' => :UpdateTypes,
-        'check_for_comments' => :CheckForComments,
-        'server' => :ServerCmd
+        'server' => :ServerCmd,
+        'sigs' => :Sigs,
+        'update_types' => :UpdateTypes
       }.freeze
 
       private

data/lib/docscribe/config.rb

@@ -26,6 +26,16 @@ module Docscribe
       @raw = deep_merge(DEFAULT, raw)
       @config_path = config_path
     end
+
+    # @return [Object]
+    def to_h
+      hash = {} #: Hash[String, Object]
+      instance_variables.each do |var|
+        key = var.to_s.sub('@', '')
+        hash[key] = instance_variable_get(var)
+      end
+      hash
+    end
   end
 end