metz-scan 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5445ac335e32a5730e08a32f14a5ed924db3c3c8aad1ca7d014082fd86e2b95e
-  data.tar.gz: 19fc36ed7b22163a5d5c1f19f26021da8de907adb3ff8cecbeb04a2ae5a5f768
+  metadata.gz: f8ab2475c975b0058d11664aeddf01dd91b55538137e55ed65af273c4aa62874
+  data.tar.gz: d518ad9b70df91a4e74509f03883a911ea5a858cee6bb72a4f17328d7831c291
 SHA512:
-  metadata.gz: 5b7eb5cde94f2a0136d278d635827779fa1288890bc5b694e6cbc39643daf9b2d8ba1873e308bb8f048bc60392cdf8adbc7d252f2c8feee5d56f6161143c7dc5
-  data.tar.gz: 752000a0f48d9dfda4806844613ca562c405e6d0ed5e03032e98deb9b688719a2dc856d3f2c1530461ba16af6032b9add2b6e89c49b196c25df33613afe0db2d
+  metadata.gz: d63399acc40747d1630dd66a0579d9ea906b71341acfc65ace51f9c39f8dd4e3f1d87b5892a2d0e6b14ddbd115aa8d52ad5eccf69865be695776b5c36ddcc538
+  data.tar.gz: 5d450a47bc76f4dab47a041b4b278e28568f5d692b14a280e95705b7df4106af4c8f9e98ae3c53d8014211a185728e4668bece96637c846608891a4665604fa8

data/lib/metz_scan/analyzers/inheritance_descendants.rb

@@ -50,7 +50,7 @@ module MetzScan
 
       def auto_discovered_base_candidates
         index.declarations.select { |declaration| auto_discovered_base_candidate?(declaration) }
-                          .map(&:name).compact.uniq.sort
+             .map(&:name).compact.uniq.sort
       end
 
       def auto_discovered_base_candidate?(declaration)

data/lib/metz_scan/analyzers/namespace_leak_pressure.rb

@@ -51,7 +51,7 @@ module MetzScan
 
       def declarations
         index.declarations.select { |declaration| declaration_candidate?(declaration) }
-                          .sort_by { |declaration| declaration.name.to_s }
+             .sort_by { |declaration| declaration.name.to_s }
       end
 
       def declaration_candidate?(declaration)

data/lib/metz_scan/analyzers/package_dependency_pressure.rb

@@ -50,7 +50,7 @@ module MetzScan
 
       def declarations
         index.declarations.select { |declaration| declaration_candidate?(declaration) }
-                          .sort_by { |declaration| declaration.name.to_s }
+             .sort_by { |declaration| declaration.name.to_s }
       end
 
       def declaration_candidate?(declaration)

data/lib/metz_scan/analyzers/package_map.rb

@@ -58,7 +58,7 @@ module MetzScan
         index = app_index(parts) || lib_index(parts)
         return false unless index
 
-        parts[(index + 1)..].any? { |part| IGNORED_SUPPORT_SEGMENTS.include?(part) }
+        parts[(index + 1)..].intersect?(IGNORED_SUPPORT_SEGMENTS)
       end
 
       def app_index(parts)

data/lib/metz_scan/analyzers/test_calls_private_method/call_site_collector.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "node_predicates"
+require_relative "receiver_resolution"
+require_relative "scope_facts"
+require_relative "scope_resolution"
+
+module MetzScan
+  module Analyzers
+    class TestCallsPrivateMethod
+      class CallSiteCollector
+        include NodePredicates
+        include ReceiverResolution
+        include ScopeFacts
+        include ScopeResolution
+
+        def initialize(path, declarations:)
+          @path = path
+          @declarations = declarations
+        end
+
+        def call
+          walk(processed_source.ast, [])
+        rescue Parser::SyntaxError
+          []
+        end
+
+        private
+
+        attr_reader :path, :declarations
+
+        def processed_source
+          RuboCop::ProcessedSource.new(File.read(path), RUBY_VERSION.to_f)
+        end
+
+        def walk(node, scopes)
+          return [] unless node
+          return [] if shared_example_group_block?(node)
+          return walk(node.body, scopes + [scope_for_block(node, scopes)]) if example_group_block?(node)
+          return walk_scoped_node(node, scopes) if scoped_node?(node)
+
+          walk_regular_node(node, scopes)
+        end
+
+        def walk_scoped_node(node, scopes)
+          scope = node.class_type? ? scope_for_class(node) : scope_for_local(node, scopes)
+          walk(node.body, scopes + [scope])
+        end
+
+        def walk_regular_node(node, scopes)
+          [call_site_for(node, scopes), *walk_child_nodes(node, scopes)].compact
+        end
+
+        def walk_child_nodes(node, scopes)
+          node.children.grep(RuboCop::AST::Node).flat_map { |child| walk(child, scopes) }
+        end
+
+        def call_site_for(node, scopes)
+          return unless private_send_call?(node)
+
+          build_call_site(node, literal_method_name(node.arguments.first), receiver_target(node.receiver, scopes))
+        end
+
+        def private_send_call?(node)
+          send_like?(node) && SEND_METHODS.include?(node.method_name) && literal_method_name(node.arguments.first)
+        end
+
+        def build_call_site(node, method_name, receiver)
+          return unless receiver
+
+          CallSite.new(path: path, line: node.loc.selector.line, owner_name: receiver.fetch(:owner_name),
+                       method_name: method_name, method_identity: method_identity(receiver.fetch(:receiver_kind),
+                                                                                  method_name),
+                       receiver_kind: receiver.fetch(:receiver_kind))
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/test_calls_private_method/finding.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../occurrence"
+
+module MetzScan
+  module Analyzers
+    class TestCallsPrivateMethod
+      Finding = Struct.new(:source, :rule_id, :message, :path, :line, :owner_name, :method_name,
+                           :method_identity, :receiver_kind, :visibility, :occurrences,
+                           :project_analyzer_status, :confidence, :triage_severity, :triage_summary,
+                           :project_analyzer_metadata, :why_it_matters, :suggested_next_moves,
+                           keyword_init: true) do
+        def report_occurrences
+          occurrences.map { |occurrence| Occurrence.from(occurrence, context: occurrence_context) }.compact
+        end
+
+        def occurrence_context
+          "#{owner_name}#{receiver_kind == 'singleton' ? '.' : '#'}#{method_name}"
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/test_calls_private_method/metadata.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class TestCallsPrivateMethod
+      module Metadata
+        def project_analyzer_metadata_for(site, visibility)
+          category_metadata(visibility)
+            .merge(identity_metadata(site, visibility))
+            .merge("call_site" => { "path" => site.path, "line" => site.line })
+        end
+
+        def category_metadata(visibility)
+          { "project_analyzer_category" => "test_calls_private_method",
+            "test_private_method_category" => "index_confirmed_#{visibility.tr('/', '_')}" }
+        end
+
+        def identity_metadata(site, visibility)
+          { "owner_name" => site.owner_name, "method_name" => site.method_name,
+            "method_identity" => site.method_identity,
+            "receiver_kind" => site.receiver_kind,
+            "visibility" => visibility }
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/test_calls_private_method/node_predicates.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class TestCallsPrivateMethod
+      module NodePredicates
+        def literal_method_name(node)
+          node.value.to_s if node&.sym_type? || node&.str_type?
+        end
+
+        def described_class_call?(node)
+          send_like?(node) && bare_call?(node) && node.method_name == :described_class
+        end
+
+        def bare_call?(node)
+          !node.receiver && node.arguments.empty?
+        end
+
+        def const_name(node)
+          node.const_name if node&.const_type?
+        end
+
+        def method_identity(receiver_kind, method_name)
+          "#{receiver_kind}:#{method_name}"
+        end
+
+        def send_like?(node)
+          node&.send_type? || node&.csend_type?
+        end
+
+        def example_group_block?(node)
+          node&.block_type? && group_method?(node, EXAMPLE_GROUP_METHODS)
+        end
+
+        def shared_example_group_block?(node)
+          node&.block_type? && group_method?(node, SHARED_EXAMPLE_GROUP_METHODS)
+        end
+
+        def local_scope_node?(node)
+          node&.def_type? || node&.defs_type? || node&.block_type?
+        end
+
+        def scoped_node?(node)
+          node&.class_type? || local_scope_node?(node)
+        end
+
+        def group_method?(node, methods)
+          methods.include?(node.send_node.method_name) && example_group_receiver?(node.send_node.receiver)
+        end
+
+        def example_group_receiver?(receiver)
+          !receiver || (receiver.const_type? && receiver.const_name == "RSpec")
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/test_calls_private_method/receiver_resolution.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class TestCallsPrivateMethod
+      module ReceiverResolution
+        def receiver_target(receiver, scopes)
+          return unless receiver
+          return const_receiver_target(receiver) if receiver.const_type?
+          return send_receiver_target(receiver, scopes) if send_like?(receiver)
+
+          assigned_receiver_target(receiver, scopes) if VARIABLE_TYPES.include?(receiver.type)
+        end
+
+        def const_receiver_target(receiver)
+          { owner_name: receiver.const_name, receiver_kind: "singleton" }
+        end
+
+        def send_receiver_target(receiver, scopes)
+          owner_name = new_receiver_owner(receiver, scopes) || subject_receiver_owner(receiver, scopes)
+          { owner_name: owner_name, receiver_kind: "instance" } if owner_name
+        end
+
+        def assigned_receiver_target(receiver, scopes)
+          owner_name = assigned_owner_for(receiver.children.first.to_s, scopes, receiver.type)
+          { owner_name: owner_name, receiver_kind: "instance" } if owner_name
+        end
+
+        def new_receiver_owner(node, scopes)
+          return unless send_like?(node) && node.method_name == :new
+
+          owner_for_new_receiver(node.receiver, scopes)
+        end
+
+        def owner_for_new_receiver(receiver, scopes)
+          return receiver.const_name if receiver&.const_type?
+
+          current_sut_name(scopes) if described_class_call?(receiver)
+        end
+
+        def subject_receiver_owner(node, scopes)
+          return unless bare_call?(node)
+
+          node.method_name == :subject ? bare_subject_owner(scopes) : named_subject_owner(node.method_name, scopes)
+        end
+
+        def named_subject_owner(name, scopes)
+          scope = scopes.reverse.find { |candidate| candidate.subject_definitions.key?(name) }
+          scope&.subject_definitions&.fetch(name) == :sut ? scope.sut_name : nil
+        end
+
+        def bare_subject_owner(scopes)
+          return if scopes.any? { |scope| scope.subject_definitions[:subject] == :non_sut }
+
+          explicit_subject_owner(scopes) || current_sut_name(scopes)
+        end
+
+        def explicit_subject_owner(scopes)
+          scope = scopes.reverse.find { |candidate| candidate.subject_definitions[:subject] == :sut }
+          scope&.sut_name
+        end
+
+        def assigned_owner_for(name, scopes, variable_type)
+          variable_type == :lvar ? local_owner_for(name, scopes) : instance_owner_for(name, scopes)
+        end
+
+        def local_owner_for(name, scopes)
+          scope = scopes.reverse.find { |candidate| candidate.kind == :local && candidate.assignments.key?(name) }
+          scope&.assignments&.fetch(name)
+        end
+
+        def instance_owner_for(name, scopes)
+          owner_values = scopes.select { |scope| scope.assignments.key?(name) }
+                               .map { |scope| scope.assignments.fetch(name) }
+          owner_values.one? ? owner_values.first : nil
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/test_calls_private_method/scope_facts.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class TestCallsPrivateMethod
+      module ScopeFacts
+        def assignments_for(scope_node)
+          grouped_assignment_owners(scope_node).transform_values { |owners| owners.one? ? owners.first : nil }
+        end
+
+        def grouped_assignment_owners(scope_node)
+          direct_descendants(scope_node, *ASSIGNMENT_TYPES).each_with_object({}) do |node, grouped|
+            record_assignment_owner(grouped, node)
+          end
+        end
+
+        def record_assignment_owner(grouped, node)
+          name = node.children.first.to_s
+          grouped[name] ||= []
+          grouped[name] << const_new_owner(node.children[1])
+        end
+
+        def const_new_owner(node)
+          return unless send_like?(node) && node.method_name == :new && node.receiver&.const_type?
+
+          node.receiver.const_name
+        end
+
+        def subject_definitions_for(group, sut_name)
+          direct_descendants(group, :block).each_with_object({}) do |block, definitions|
+            record_subject_definition(definitions, block, sut_name)
+          end
+        end
+
+        def record_subject_definition(definitions, block, sut_name)
+          return unless SUBJECT_DEFINERS.include?(block.send_node.method_name)
+          return if block.send_node.receiver
+
+          definitions[subject_name(block.send_node)] = subject_definition_value(block, sut_name)
+        end
+
+        def subject_definition_value(block, sut_name)
+          subject_body_sut?(block, sut_name) ? :sut : :non_sut
+        end
+
+        def subject_body_sut?(block, sut_name)
+          sut_name && subject_body_owner(block.body, sut_name) == sut_name
+        end
+
+        def subject_body_owner(body, sut_name)
+          return unless send_like?(body) && body.method_name == :new
+          return body.receiver.const_name if body.receiver&.const_type?
+
+          sut_name if described_class_call?(body.receiver)
+        end
+
+        def subject_name(send_node)
+          argument = send_node.arguments.first
+          argument&.sym_type? ? argument.value : :subject
+        end
+
+        def direct_descendants(scope_node, *types)
+          scope_node.each_descendant(*types).reject { |node| nested_scope_between?(node, scope_node) }
+        end
+
+        def nested_scope_between?(node, scope_node)
+          node.each_ancestor.any? do |ancestor|
+            break false if ancestor.equal?(scope_node)
+
+            ancestor.class_type? || example_group_block?(ancestor)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/test_calls_private_method/scope_resolution.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class TestCallsPrivateMethod
+      module ScopeResolution
+        def scope_for_block(node, scopes)
+          sut_name = group_sut_name(node) || current_sut_name(scopes)
+          Scope.new(kind: :example_group, node: node, sut_name: sut_name,
+                    subject_definitions: subject_definitions_for(node, sut_name),
+                    assignments: assignments_for(node))
+        end
+
+        def scope_for_class(node)
+          Scope.new(kind: :class, node: node, sut_name: class_sut_name(node),
+                    subject_definitions: {}, assignments: assignments_for(node))
+        end
+
+        def scope_for_local(node, scopes)
+          Scope.new(kind: :local, node: node, sut_name: current_sut_name(scopes),
+                    subject_definitions: {}, assignments: assignments_for(node))
+        end
+
+        def group_sut_name(block)
+          const_name(block.send_node.arguments.first)
+        end
+
+        def class_sut_name(node)
+          name = const_name(node.identifier)
+          demangled_name_for(name) if name
+        end
+
+        def demangled_name_for(test_class_name)
+          candidate = demangled_candidate(test_class_name)
+          unique_declaration_match(candidate) if candidate
+        end
+
+        def demangled_candidate(test_class_name)
+          return test_class_name.delete_suffix("Test") if test_class_name.end_with?("Test")
+
+          test_class_name.delete_prefix("Test") if test_class_name.start_with?("Test")
+        end
+
+        def unique_declaration_match(candidate)
+          matches = declarations.map(&:name).select { |name| name == candidate || name.end_with?("::#{candidate}") }
+          matches.one? ? matches.first : nil
+        end
+
+        def current_sut_name(scopes)
+          scope = scopes.reverse.find { |candidate| SCOPE_KINDS.include?(candidate.kind) }
+          scope&.sut_name
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/test_calls_private_method/triage.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class TestCallsPrivateMethod
+      module Triage
+        def triage_attributes_for
+          project_analyzer_triage_attributes
+        end
+
+        def project_analyzer_context_attributes(site, visibility)
+          { project_analyzer_metadata: project_analyzer_metadata_for(site, visibility),
+            why_it_matters: WHY, suggested_next_moves: SUGGESTED_NEXT_MOVES }
+        end
+
+        def message_for(site, visibility)
+          "#{site.owner_name}#{site.receiver_kind == 'singleton' ? '.' : '#'}#{site.method_name} is " \
+            "#{visibility}; test behavior through the public interface instead of calling it with send."
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/test_calls_private_method.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+require_relative "../project_index"
+require_relative "project_analyzer_triage"
+require_relative "ruby_file_enumerator"
+require_relative "test_calls_private_method/call_site_collector"
+require_relative "test_calls_private_method/finding"
+require_relative "test_calls_private_method/metadata"
+require_relative "test_calls_private_method/triage"
+
+module MetzScan
+  module Analyzers
+    # Reports tests that call index-confirmed private or protected SUT methods.
+    class TestCallsPrivateMethod
+      include ProjectAnalyzerTriage
+      include Metadata
+      include Triage
+
+      RULE_ID = "MetzProject/TestCallsPrivateMethod"
+      PROJECT_ANALYZER_STATUS = "candidate"
+      CONFIDENCE = "high"
+      TRIAGE_SEVERITY = "manual review"
+      TRIAGE_SUMMARY = "Candidate private-method testing signal; review whether the test should cover public behavior."
+      WHY = "This is the index-confirmed form of Metz/TestReachesPrivate. Prefer this signal when both are " \
+            "enabled because it confirms the test reaches a private or protected method on the subject under test."
+      SUGGESTED_NEXT_MOVES = [
+        "Exercise the public behavior that uses the private method instead of calling the method directly.",
+        "Promote the method to the public interface only when callers outside the object genuinely need it.",
+        "Keep Metz/TestReachesPrivate as the lower-confidence fallback for index-less runs."
+      ].freeze
+      TEST_FILE_PATTERNS = [
+        "**/*_test.rb",
+        "**/test_*.rb",
+        "**/*_spec.rb"
+      ].freeze
+      PRIVATE_VISIBILITIES = %w[private protected].freeze
+      SEND_METHODS = %i[send __send__].freeze
+      EXAMPLE_GROUP_METHODS = %i[describe context feature example_group xdescribe xcontext
+                                 fdescribe fcontext].freeze
+      SHARED_EXAMPLE_GROUP_METHODS = %i[shared_examples shared_examples_for shared_context].freeze
+      SUBJECT_DEFINERS = %i[subject subject!].freeze
+      ASSIGNMENT_TYPES = %i[lvasgn ivasgn].freeze
+      VARIABLE_TYPES = %i[lvar ivar].freeze
+      SCOPE_KINDS = %i[class example_group].freeze
+      private_constant :TEST_FILE_PATTERNS, :PRIVATE_VISIBILITIES, :SEND_METHODS, :EXAMPLE_GROUP_METHODS,
+                       :SHARED_EXAMPLE_GROUP_METHODS, :SUBJECT_DEFINERS, :ASSIGNMENT_TYPES, :VARIABLE_TYPES,
+                       :SCOPE_KINDS
+
+      CallSite = Struct.new(:path, :line, :owner_name, :method_name, :method_identity, :receiver_kind,
+                            keyword_init: true)
+      Scope = Struct.new(:kind, :node, :sut_name, :subject_definitions, :assignments, keyword_init: true)
+
+      def self.test_file?(path)
+        normalized = path.to_s
+        basename = File.basename(normalized)
+        normalized.end_with?("_test.rb", "_spec.rb") || (basename.start_with?("test_") && basename.end_with?(".rb"))
+      end
+
+      def initialize(paths: nil, index: nil)
+        @paths = Array(paths)
+        @index = index || ProjectIndex.build(@paths)
+      end
+
+      def call
+        return [] unless index.available?
+
+        call_sites.filter_map { |site| finding_for(site) }
+      end
+
+      private
+
+      attr_reader :paths, :index
+
+      def call_sites
+        test_files.flat_map { |path| CallSiteCollector.new(path, declarations: index.declarations).call }
+      end
+
+      def test_files
+        RubyFileEnumerator.new(paths: paths, index: index).call.select { |path| self.class.test_file?(path) }
+      end
+
+      def finding_for(site)
+        visibility = confirmed_visibility_for(site)
+        return unless visibility
+
+        Finding.new(finding_attributes(site, visibility))
+      end
+
+      def finding_attributes(site, visibility)
+        core_finding_attributes(site, visibility)
+          .merge(triage_attributes_for)
+          .merge(project_analyzer_context_attributes(site, visibility))
+      end
+
+      def core_finding_attributes(site, visibility)
+        { source: source_name, rule_id: RULE_ID, message: message_for(site, visibility),
+          path: site.path, line: site.line, owner_name: site.owner_name, method_name: site.method_name,
+          method_identity: site.method_identity, receiver_kind: site.receiver_kind, visibility: visibility,
+          occurrences: [site] }
+      end
+
+      def confirmed_visibility_for(site)
+        declarations = confirming_declarations_for(site)
+        return if declarations.empty?
+
+        visibilities = declarations.map(&:visibility).uniq
+        return unless visibilities.all? { |visibility| PRIVATE_VISIBILITIES.include?(visibility) }
+
+        visibilities.one? ? visibilities.first : visibilities.join("/")
+      end
+
+      def confirming_declarations_for(site)
+        methods_by_owner.fetch(site.owner_name, []).select do |declaration|
+          declaration.method_identity == site.method_identity && !self.class.test_file?(declaration.path.to_s)
+        end
+      end
+
+      def methods_by_owner
+        @methods_by_owner ||= index.method_declarations.group_by(&:owner_name)
+      end
+    end
+  end
+end

data/lib/metz_scan/calibration/project_analyzer_evidence_runner/readiness_catalog.rb

@@ -55,13 +55,17 @@ module MetzScan
                           "joins, merges, Arel, single-key finders, bang finders, exists?, or take."
           },
           "MetzProject/SubclassOverridePressure" => {
-            "evidence" => "Expanded active fixtures show 148 findings: 93 low broad-root and " \
-                          "55 medium manual-review findings across abstract hook, cooperative, and " \
-                          "replacement override families.",
+            "evidence" => "Expanded active fixtures show 148 findings across broad-root, abstract hook, " \
+                          "cooperative, and replacement override families.",
             "next" => "Keep parked unless future generic work separates design-pressure hook contracts " \
                       "from deliberate extension protocols and setup conventions.",
             "not_next" => "Do not implement classifier behavior, promote, make default-output eligible, " \
                           "suppress medium categories, or retune thresholds."
+          },
+          "MetzProject/TestCallsPrivateMethod" => {
+            "evidence" => "Index-confirmed testing analyzer; dogfood before any promotion.",
+            "next" => "Dogfood on test-heavy RSpec and Minitest codebases with Rubydex available.",
+            "not_next" => "Do not promote or add runtime double-report coordination with Metz/TestReachesPrivate."
           }
         }.freeze
 

data/lib/metz_scan/cli.rb

@@ -16,6 +16,9 @@ module MetzScan
 
     SUBCOMMANDS = SUBCOMMAND_SUMMARIES.keys.freeze
 
+    # sysexits(3) EX_USAGE: keeps caller errors distinct from exit 1, "findings reported".
+    USAGE_ERROR = 64
+
     def self.start(argv = ARGV, stdout: $stdout, stderr: $stderr)
       new(stdout: stdout, stderr: stderr).run(argv)
     end
@@ -55,15 +58,14 @@ module MetzScan
 
     def show_help_and_fail
       stderr.puts help_text
-      1
+      USAGE_ERROR
     end
 
     def dispatch(args)
       name = args.shift
       return unknown_subcommand(name) unless SUBCOMMANDS.include?(name)
 
-      handler = subcommand_handler(name)
-      handler ? handler.run(args, stdout: stdout, stderr: stderr) : stub_subcommand(name)
+      subcommand_handler(name).run(args, stdout: stdout, stderr: stderr)
     end
 
     SUBCOMMAND_HANDLERS = { "rules" => "Rules", "explain" => "Explain", "scan" => "Scan",
@@ -71,22 +73,14 @@ module MetzScan
     private_constant :SUBCOMMAND_HANDLERS
 
     def subcommand_handler(name)
-      klass_name = SUBCOMMAND_HANDLERS[name]
-      return unless klass_name
-
       require_relative "commands/#{name.tr('-', '_')}"
-      Commands.const_get(klass_name)
-    end
-
-    def stub_subcommand(name)
-      stderr.puts "metz-scan: subcommand '#{name}' is not yet implemented."
-      1
+      Commands.const_get(SUBCOMMAND_HANDLERS.fetch(name))
     end
 
     def unknown_subcommand(name)
       stderr.puts "metz-scan: unknown subcommand '#{name}'."
       stderr.puts help_text
-      1
+      USAGE_ERROR
     end
 
     def help_text