docscribe 1.6.0 → 1.6.2

data/lib/docscribe/cli/formatters/json.rb

@@ -20,7 +20,8 @@ module Docscribe
           insert_full_doc_block: 'convention',
           unsorted_tags: 'convention',
           updated_param: 'warning',
-          updated_return: 'warning'
+          updated_return: 'warning',
+          invalid_type: 'warning'
         }.freeze
 
         COP_NAME_MAP = {
@@ -32,7 +33,8 @@ module Docscribe
           insert_full_doc_block: 'Docscribe/MissingDocBlock',
           unsorted_tags: 'Docscribe/UnsortedTags',
           updated_param: 'Docscribe/UpdatedParam',
-          updated_return: 'Docscribe/UpdatedReturn'
+          updated_return: 'Docscribe/UpdatedReturn',
+          invalid_type: 'Docscribe/InvalidType'
         }.freeze
 
         # Output JSON check summary.
@@ -60,7 +62,7 @@ module Docscribe
         # @private
         # @param [Docscribe::CLI::Formatters::state] state formatter state hash
         # @param [Docscribe::CLI::Formatters::opts] _options runtime options hash
-        # @return [Hash<Symbol, Object>]
+        # @return [Docscribe::CLI::Formatters::Json::json_document]
         def build_document(state, _options)
           document_hash(build_files(state), state)
         end
@@ -68,9 +70,9 @@ module Docscribe
         # Build document hash structure.
         #
         # @private
-        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
         # @param [Docscribe::CLI::Formatters::state] state formatter state hash
-        # @return [Hash<Symbol, Object>]
+        # @return [Docscribe::CLI::Formatters::Json::json_document]
         def document_hash(files, state)
           {
             metadata: metadata_hash,
@@ -82,7 +84,7 @@ module Docscribe
         # Build tool metadata hash.
         #
         # @private
-        # @return [Hash<Symbol, String>]
+        # @return [Docscribe::CLI::Formatters::Json::json_metadata]
         def metadata_hash
           {
             docscribe_version: Docscribe::VERSION,
@@ -93,9 +95,9 @@ module Docscribe
         # Build summary statistics hash.
         #
         # @private
-        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
         # @param [Docscribe::CLI::Formatters::state] state formatter state hash
-        # @return [Hash<Symbol, Integer>]
+        # @return [Docscribe::CLI::Formatters::Json::json_summary]
         def summary_hash(files, state)
           {
             offense_count: files.sum { |f| f[:offenses].size },
@@ -109,7 +111,7 @@ module Docscribe
         #
         # @private
         # @param [Docscribe::CLI::Formatters::state] state formatter state hash
-        # @return [Array<Hash<Symbol, Object>>]
+        # @return [Array<Docscribe::CLI::Formatters::Json::json_file>]
         def build_files(state)
           files = [] #: Array[Hash[untyped, untyped]]
 
@@ -124,15 +126,16 @@ module Docscribe
         #
         # @private
         # @param [Docscribe::CLI::Formatters::state] state formatter state hash
-        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
         # @return [void]
         def append_check_files(state, files)
           state[:fail_paths].each do |path|
-            files << file_entry(path, state[:fail_changes][path] || [])
+            merge_or_append(files, path, build_offenses(state[:fail_changes][path] || []))
           end
 
           state[:type_mismatch_paths].each do |path|
-            files << file_entry(path, state[:type_mismatch_changes][path] || [], severity: 'warning')
+            changes = state[:type_mismatch_changes][path] || []
+            merge_or_append(files, path, build_offenses(changes, severity: 'warning'))
           end
         end
 
@@ -140,7 +143,7 @@ module Docscribe
         #
         # @private
         # @param [Docscribe::CLI::Formatters::state] state formatter state hash
-        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
         # @return [void]
         def append_corrected_files(state, files)
           state[:corrected_paths].each do |path|
@@ -152,7 +155,7 @@ module Docscribe
         #
         # @private
         # @param [Docscribe::CLI::Formatters::state] state formatter state hash
-        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
         # @return [void]
         def append_error_files(state, files)
           state[:error_paths].each do |path|
@@ -163,12 +166,12 @@ module Docscribe
         # Merge or append file offenses.
         #
         # @private
-        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
         # @param [String] path file path string
-        # @param [Array<Hash<Symbol, Object>>] offenses offense objects array
+        # @param [Array<Docscribe::CLI::Formatters::Json::json_offense>] offenses offense objects array
         # @return [void]
         def merge_or_append(files, path, offenses)
-          existing = files.find { |f| f[:path] == path }
+          existing = files.find { |f| normalize_path(f[:path]) == normalize_path(path) }
 
           if existing
             existing[:offenses].concat(offenses)
@@ -177,15 +180,18 @@ module Docscribe
           end
         end
 
-        # Build single file entry hash.
+        # Normalize a path for dedup comparison, resolving symlinks
+        # (e.g. /tmp vs /private/tmp on macOS).
         #
         # @private
         # @param [String] path file path string
-        # @param [Array<Docscribe::CLI::Formatters::change>] changes changes info array
-        # @param [String?] severity offense severity level
-        # @return [Hash<Symbol, Object>]
-        def file_entry(path, changes, severity: nil)
-          { path: path, offenses: build_offenses(changes, severity: severity) }
+        # @raise [SystemCallError]
+        # @raise [ArgumentError]
+        # @return [String]
+        def normalize_path(path)
+          File.realpath(path)
+        rescue SystemCallError, ArgumentError
+          File.expand_path(path)
         end
 
         # Build error offense entry.
@@ -193,7 +199,7 @@ module Docscribe
         # @private
         # @param [Docscribe::CLI::Formatters::state] state formatter state hash
         # @param [String] path file path string
-        # @return [Hash<Symbol, Object>]
+        # @return [Docscribe::CLI::Formatters::Json::json_offense]
         def error_offense(state, path)
           error_offense_hash(state[:error_messages][path] || 'Unknown error')
         end
@@ -202,7 +208,7 @@ module Docscribe
         #
         # @private
         # @param [String] message error message string
-        # @return [Hash<Symbol, Object>]
+        # @return [Docscribe::CLI::Formatters::Json::json_offense]
         def error_offense_hash(message)
           { severity: 'fatal', cop_name: 'Docscribe/ProcessingError', message: message,
             corrected: false, correctable: false, location: default_location }
@@ -211,7 +217,7 @@ module Docscribe
         # Default location hash value.
         #
         # @private
-        # @return [Hash<Symbol, Integer>]
+        # @return [Docscribe::CLI::Formatters::Json::json_location]
         def default_location
           { start_line: 1, start_column: 1, last_line: 1, last_column: 1 }
         end
@@ -221,7 +227,7 @@ module Docscribe
         # @private
         # @param [Array<Docscribe::CLI::Formatters::change>] changes changes info array
         # @param [String?] severity offense severity level
-        # @return [Array<Hash<Symbol, Object>>]
+        # @return [Array<Docscribe::CLI::Formatters::Json::json_offense>]
         def build_offenses(changes, severity: nil)
           changes.map { |change| build_offense(change, severity) }
         end
@@ -231,8 +237,18 @@ module Docscribe
         # @private
         # @param [Docscribe::CLI::Formatters::change] change change info hash
         # @param [String?] severity offense severity level
-        # @return [Hash<Symbol, Object>]
+        # @return [Docscribe::CLI::Formatters::Json::json_offense]
         def build_offense(change, severity)
+          offense = base_offense(change, severity)
+          attach_source(offense, change)
+          attach_type(offense, change)
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change
+        # @param [String?] severity
+        # @return [Docscribe::CLI::Formatters::Json::json_offense]
+        def base_offense(change, severity)
           {
             severity: severity || SEVERITY_MAP[change[:type]] || 'convention',
             cop_name: COP_NAME_MAP[change[:type]] || cop_name_fallback(change),
@@ -243,11 +259,40 @@ module Docscribe
           }
         end
 
+        # @private
+        # @param [Docscribe::CLI::Formatters::Json::json_offense] offense
+        # @param [Docscribe::CLI::Formatters::change] change
+        # @return [Docscribe::CLI::Formatters::Json::json_offense]
+        def attach_source(offense, change)
+          source = offense_source(change)
+          offense[:source] = source if source
+          offense
+        end
+
+        # Attach machine-readable change type when present.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::Json::json_offense] offense offense hash being built
+        # @param [Docscribe::CLI::Formatters::change] change change info hash
+        # @return [Docscribe::CLI::Formatters::Json::json_offense]
+        def attach_type(offense, change)
+          type = change[:type] || change['type']
+          offense[:type] = type.to_s if type
+          offense
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change
+        # @return [String, nil]
+        def offense_source(change)
+          change[:source] || change['source']
+        end
+
         # Build location hash from change.
         #
         # @private
         # @param [Docscribe::CLI::Formatters::change] change change info hash
-        # @return [Hash<Symbol, Integer>]
+        # @return [Docscribe::CLI::Formatters::Json::json_location]
         def location_for(change)
           line = change[:line] || 1
           { start_line: line, start_column: 1, last_line: line, last_column: 1 }

data/lib/docscribe/cli/formatters/sarif.rb

@@ -24,7 +24,8 @@ module Docscribe
           insert_full_doc_block: 'note',
           unsorted_tags: 'note',
           updated_param: 'warning',
-          updated_return: 'warning'
+          updated_return: 'warning',
+          invalid_type: 'warning'
         }.freeze
 
         COP_NAME_MAP = {
@@ -36,7 +37,8 @@ module Docscribe
           insert_full_doc_block: 'Docscribe/MissingDocBlock',
           unsorted_tags: 'Docscribe/UnsortedTags',
           updated_param: 'Docscribe/UpdatedParam',
-          updated_return: 'Docscribe/UpdatedReturn'
+          updated_return: 'Docscribe/UpdatedReturn',
+          invalid_type: 'Docscribe/InvalidType'
         }.freeze
 
         SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/' \
@@ -159,12 +161,27 @@ module Docscribe
         # @param [String?] level
         # @return [Hash<Symbol, Object>]
         def build_result(change, path, level: nil)
-          {
+          result = {
             ruleId: cop_name_for(change),
             level: level || SEVERITY_MAP[change[:type]] || 'note',
             message: { text: message_for(change) },
             locations: [location(path, change[:line] || 1)]
           }
+          properties = result_properties(change)
+          result[:properties] = properties unless properties.empty?
+          result
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change
+        # @return [Hash<Symbol, String>]
+        def result_properties(change)
+          source = change[:source] || change['source']
+          type = change[:type] || change['type']
+          properties = {}
+          properties[:source] = source if source
+          properties[:type] = type.to_s if type
+          properties
         end
 
         # @private

data/lib/docscribe/cli/options.rb

@@ -28,7 +28,8 @@ module Docscribe
         no_boilerplate: false,
         progress: false,
         parallel: false,
-        server: false
+        server: false,
+        validate_types: nil #: true or false when --[no-]validate-types is passed, nil otherwise
       }.freeze
 
       module_function
@@ -39,7 +40,7 @@ module Docscribe
                docscribe generate <type> <name> [options]
                docscribe sigs [options] [files...]
                docscribe rbs [options] [files...]
-               docscribe update_types [directory]
+               docscribe update_types [directory|file]
                docscribe check_for_comments [paths...]
 
         Default behavior:
@@ -63,6 +64,7 @@ module Docscribe
                 --sorbet                   Use Sorbet signatures from inline sigs / RBI files when available
                 --rbi-dir DIR              Add a Sorbet RBI directory (repeatable). Implies --sorbet.
                 --rbs-collection           Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.
+                --validate-types           Validate YARD types against inferred/RBS types and report mismatches
 
         Filtering:
                 --include PATTERN          Include PATTERN (method id or file path; glob or /regex/)
@@ -202,6 +204,7 @@ module Docscribe
         define_sorbet_option(opts, options)
         define_rbi_dir_option(opts, options)
         define_rbs_collection_option(opts, options)
+        define_validate_types_option(opts, options)
       end
 
       # Define rbs option
@@ -267,6 +270,18 @@ module Docscribe
         end
       end
 
+      # Define validate types option
+      #
+      # @note module_function: defines #define_validate_types_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_validate_types_option(opts, options)
+        opts.on('--[no-]validate-types', 'Validate YARD types against inferred/RBS types and report mismatches') do |value|
+          options[:validate_types] = value
+        end
+      end
+
       # Define filter options
       #
       # @note module_function: defines #define_filter_options (visibility: private)

data/lib/docscribe/cli/rbs_gen.rb

@@ -29,7 +29,7 @@ module Docscribe
       # @!attribute [rw] options
       #   @return [Array<Docscribe::CLI::RbsGen::ParamTag>]
       #   @param [Array<Docscribe::CLI::RbsGen::ParamTag>] value
-      YardTags = Struct.new(:params, :return_type, :options, keyword_init: true)
+      YardTags = Struct.new(:params, :return_type, :options, keyword_init: true) #: Class[YardTags]
       # @!attribute [rw] name
       #   @return [String]
       #   @param [String] value
@@ -37,7 +37,7 @@ module Docscribe
       # @!attribute [rw] type
       #   @return [String]
       #   @param [String] value
-      ParamTag = Struct.new(:name, :type, keyword_init: true)
+      ParamTag = Struct.new(:name, :type, keyword_init: true) #: Class[ParamTag]
       # @!attribute [rw] name
       #   @return [Symbol]
       #   @param [Symbol] value
@@ -61,7 +61,7 @@ module Docscribe
       # @!attribute [rw] yard_tags
       #   @return [Docscribe::CLI::RbsGen::YardTags?]
       #   @param [Docscribe::CLI::RbsGen::YardTags?] value
-      MethodDef = Struct.new(:name, :scope, :container, :file, :line, :yard_tags, keyword_init: true)
+      MethodDef = Struct.new(:name, :scope, :container, :file, :line, :yard_tags, keyword_init: true) #: Class[MethodDef]
       # @!attribute [rw] containers
       #   @return [Array<String>]
       #   @param [Array<String>] value
@@ -86,7 +86,7 @@ module Docscribe
       #   @return [Boolean]
       #   @param [Boolean] value
       WalkContext = Struct.new(:containers, :method_defs, :path, :comment_map, :src_lines, :inside_sclass,
-                               keyword_init: true)
+                               keyword_init: true) #: Class[WalkContext]
 
       class << self
         # @param [Array<String>] argv

data/lib/docscribe/cli/run.rb

@@ -42,6 +42,7 @@ module Docscribe
           include exclude include_file exclude_file
           rbs rbs_collection sig_dirs
           sorbet rbi_dirs
+          validate_types
         ].freeze
 
         # Run Docscribe for files or STDIN using the selected mode and strategy.
@@ -145,7 +146,7 @@ module Docscribe
         #
         # @param [Docscribe::CLI::Formatters::opts] options parsed CLI options
         # @param [Docscribe::Config] conf effective config
-        # @return [Hash<Symbol, Object>] rewrite result with :output key
+        # @return [Docscribe::CLI::Run::rewrite_result] rewrite result with :output key
         def stdin_rewrite_result(options, conf)
           Docscribe::InlineRewriter.rewrite_with_report(
             $stdin.read,
@@ -243,7 +244,7 @@ module Docscribe
         # @param [Hash<String, Object>] result server result with :changed and :changes keys
         # @param [Array<Docscribe::CLI::Formatters::change>] file_changes change records
         # @param [String] path file path
-        # @param [Object] ctx context hash with :display_path, :options, :state keys
+        # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
         # @return [void]
         def dispatch_server_result(result, file_changes, path, **ctx)
           if ctx[:options][:mode] == :check
@@ -326,14 +327,17 @@ module Docscribe
         #
         # @param [Hash<String, Object>] change change record from server
         # @return [Docscribe::CLI::Formatters::change]
-        def symbolize_change(change)
-          {
+        def symbolize_change(change) # steep:ignore
+          hash = {
             type: change['type'].to_sym,
             file: change['file'],
             line: change['line'],
             method: change['method'],
-            message: change['message']
+            message: change['message'],
+            source: change['source']
           }
+          hash[:param] = change['param'] if change['param']
+          hash.compact
         end
 
         # Expand CLI path arguments into a sorted list of Ruby files.
@@ -416,8 +420,8 @@ module Docscribe
           run_exit_code(options, state)
         end
 
-        # @param [Object] options
-        # @param [Object] conf
+        # @param [Docscribe::CLI::Formatters::opts] options
+        # @param [Docscribe::Config] conf
         # @param [Array<String>] paths
         # @param [Docscribe::CLI::Formatters::state] state
         # @return [void]
@@ -430,7 +434,7 @@ module Docscribe
           thread_count.times.map { parallel_worker(pool) }.each(&:join)
         end
 
-        # @param [Hash<Symbol, Object>] pool
+        # @param [Docscribe::CLI::Run::pool] pool
         # @return [Thread]
         def parallel_worker(pool)
           Thread.new do
@@ -451,7 +455,7 @@ module Docscribe
         end
 
         # @param [String] path
-        # @param [Hash<Symbol, Object>] pool
+        # @param [Docscribe::CLI::Run::pool] pool
         # @raise [StandardError]
         # @return [void]
         # @return [Object] if StandardError
@@ -605,7 +609,7 @@ module Docscribe
           return unless result
 
           dispatch_file_result(path, src: src, out: result[:output], file_changes: result[:changes] || [],
-                                     display_path: display_path, options: options, state: state)
+                                     display_path: display_path, options: options, state: state, conf: conf)
         end
 
         # Print progress indicator to stderr when --progress is active.
@@ -629,7 +633,7 @@ module Docscribe
         # @param [String] src original source code
         # @param [String] out rewritten source code
         # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
-        # @param [Object] ctx context hash with :options, :state, :display_path, :conf
+        # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :options, :state, :display_path, :conf
         # @return [void]
         def dispatch_file_result(path, src:, out:, file_changes:, **ctx)
           if ctx[:options][:mode] == :check
@@ -687,9 +691,9 @@ module Docscribe
         # @private
         # @param [String] path file path
         # @param [String] src source code
-        # @param [Hash<Symbol, Object>] ctx context hash with :conf, :display_path, :options, :state keys
+        # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :conf, :display_path, :options, :state keys
         # @raise [StandardError]
-        # @return [Hash<Symbol, Object>, nil]
+        # @return [Docscribe::CLI::Run::rewrite_result, nil]
         # @return [nil] if StandardError
         def rewrite_result_for_path(path, src:, ctx:)
           conf = ctx[:conf]
@@ -710,7 +714,7 @@ module Docscribe
         # @private
         # @param [String] path file path that caused the error
         # @param [StandardError] error the exception raised during rewriting
-        # @param [Hash<Symbol, Object>] ctx context hash with :state, :options, :display_path
+        # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :state, :options, :display_path
         # @return [void]
         def record_rewrite_error(path, error, ctx)
           state = ctx[:state]
@@ -733,18 +737,97 @@ module Docscribe
         # @param [String] src original source code
         # @param [String] out rewritten source code
         # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
-        # @param [Object] ctx context hash with :display_path, :options, :state keys
+        # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
         # @return [void]
         def handle_check_result(path, src:, out:, file_changes:, **ctx)
           type_mismatches = type_mismatch_changes(file_changes)
-          has_real_changes = file_changes.any? { |c| !%i[updated_param updated_return].include?(c[:type]) }
+          has_real_changes = real_changes?(file_changes)
+          return handle_validated_type_mismatch(path, file_changes, type_mismatches, ctx) if validated_mismatch?(ctx, type_mismatches, out, src, has_real_changes)
+          return handle_no_changes(path, type_mismatches, ctx) if no_real_changes?(out, src, has_real_changes)
 
-          if out == src && !has_real_changes
-            handle_check_no_changes(path, type_mismatches: type_mismatches, display_path: ctx[:display_path],
-                                          options: ctx[:options], state: ctx[:state])
-            return
-          end
+          handle_failed_check(path, file_changes, ctx)
+        end
+
+        # @private
+        # @param [Array<Docscribe::CLI::Formatters::change>] file_changes
+        # @return [Boolean]
+        def real_changes?(file_changes)
+          file_changes.any? { |c| !%i[updated_param updated_return invalid_type].include?(c[:type]) }
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Run::run_ctx] ctx
+        # @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
+        # @param [String] out
+        # @param [String] src
+        # @param [Boolean] has_real_changes
+        # @return [Boolean]
+        def validated_mismatch?(ctx, type_mismatches, out, src, has_real_changes)
+          validate_types_enabled?(ctx) && type_mismatches.any? && out == src && !has_real_changes
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Run::run_ctx] ctx
+        # @return [Boolean]
+        def validate_types_enabled?(ctx)
+          return true if ctx[:options][:validate_types] == true
+          return false if ctx[:options][:validate_types] == false
 
+          ctx[:conf].respond_to?(:validate_types?) && ctx[:conf].validate_types?
+        end
+
+        # @private
+        # @param [String] out
+        # @param [String] src
+        # @param [Boolean] has_real_changes
+        # @return [Boolean]
+        def no_real_changes?(out, src, has_real_changes)
+          out == src && !has_real_changes
+        end
+
+        # @private
+        # @param [String] path
+        # @param [Array<Docscribe::CLI::Formatters::change>] file_changes
+        # @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
+        # @param [Docscribe::CLI::Run::run_ctx] ctx
+        # @return [void]
+        def handle_validated_type_mismatch(path, file_changes, type_mismatches, ctx)
+          handle_failed_check(path, file_changes, ctx)
+          # Drop the records the tracker already holds: the same mismatch must
+          # not appear (and count) twice in JSON output.
+          stored = ctx[:state][:fail_changes][path] || []
+          ctx[:state][:fail_changes][path] = stored - type_mismatches
+          track_validated_mismatch(type_mismatches, ctx, path)
+        end
+
+        # @private
+        # @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
+        # @param [Docscribe::CLI::Run::run_ctx] ctx
+        # @param [String] path raw file path, used as the map key so fail and
+        #   mismatch entries merge in JSON output
+        # @return [void]
+        def track_validated_mismatch(type_mismatches, ctx, path)
+          state = ctx[:state]
+          state[:type_mismatch_paths] << path unless state[:type_mismatch_paths].include?(path)
+          state[:type_mismatch_changes][path] = type_mismatches
+        end
+
+        # @private
+        # @param [String] path
+        # @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
+        # @param [Docscribe::CLI::Run::run_ctx] ctx
+        # @return [void]
+        def handle_no_changes(path, type_mismatches, ctx)
+          handle_check_no_changes(path, type_mismatches: type_mismatches, display_path: ctx[:display_path],
+                                        options: ctx[:options], state: ctx[:state])
+        end
+
+        # @private
+        # @param [String] path
+        # @param [Array<Docscribe::CLI::Formatters::change>] file_changes
+        # @param [Docscribe::CLI::Run::run_ctx] ctx
+        # @return [void]
+        def handle_failed_check(path, file_changes, ctx)
           handle_check_failed(path, file_changes: file_changes, display_path: ctx[:display_path],
                                     options: ctx[:options], state: ctx[:state])
         end
@@ -755,7 +838,7 @@ module Docscribe
         # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
         # @return [Array<Docscribe::CLI::Formatters::change>]
         def type_mismatch_changes(file_changes)
-          file_changes.select { |c| %i[updated_param updated_return].include?(c[:type]) }
+          file_changes.select { |c| %i[updated_param updated_return invalid_type].include?(c[:type]) }
         end
 
         # Handle check result when there are no real changes.
@@ -809,7 +892,7 @@ module Docscribe
         # @param [String] src original source code
         # @param [String] out rewritten source code
         # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
-        # @param [Object] ctx context hash with :display_path, :options, :state keys
+        # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
         # @raise [StandardError]
         # @return [void]
         # @return [Object] if StandardError
@@ -827,7 +910,7 @@ module Docscribe
         # @param [String] path file path
         # @param [String] out rewritten source code
         # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
-        # @param [Hash<Symbol, Object>] ctx context hash with :display_path, :options, :state keys
+        # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
         # @return [void]
         def apply_correction(path, out, file_changes, ctx)
           File.write(path, out)