metz-scan 0.5.3

data/lib/metz_scan/analyzers/service_soup.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "../project_index"
+require_relative "occurrence"
+require_relative "project_analyzer_triage"
+require_relative "ruby_file_enumerator"
+require_relative "service_soup/setup_workflow_triage"
+require_relative "service_soup/workflow_collector"
+
+module MetzScan
+  module Analyzers
+    # Reports workflow methods that coordinate many service-style calls.
+    class ServiceSoup
+      include ProjectAnalyzerTriage
+
+      RULE_ID = "MetzProject/ServiceSoup"
+      PROJECT_ANALYZER_STATUS = "validated"
+      DEFAULT_OUTPUT_ELIGIBLE = true
+      CONFIDENCE = "medium"
+      TRIAGE_SEVERITY = "design pressure"
+      TRIAGE_SUMMARY = "Validated workflow signal; review methods that coordinate several distinct services."
+      WHY = "Service-object soup scatters one workflow across many procedural steps " \
+            "and makes orchestration harder to change."
+      SUGGESTED_NEXT_MOVES = [
+        "Introduce a workflow object that owns the multi-step process.",
+        "Keep the controller or job action at one high-level command when possible."
+      ].freeze
+      Finding = Struct.new(:source, :rule_id, :message, :workflow, :services, :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: workflow) }
+        end
+      end
+
+      def initialize(paths: nil, index: nil, minimum_services: 3)
+        @paths = Array(paths)
+        @index = index
+        @minimum_services = minimum_services
+      end
+
+      def call
+        workflows.filter_map { |workflow| finding_for(workflow) }
+      end
+
+      private
+
+      attr_reader :paths, :index, :minimum_services
+
+      def workflows
+        ruby_files.flat_map { |path| WorkflowCollector.new(path).call }
+      end
+
+      def ruby_files
+        RubyFileEnumerator.new(paths: paths, index: index).call
+      end
+
+      def finding_for(workflow)
+        services = service_names(workflow)
+        return if services.size < minimum_services
+
+        Finding.new(finding_attributes(workflow, services))
+      end
+
+      def finding_attributes(workflow, services)
+        workflow_attributes(workflow, services).merge(
+          triage_attributes_for(workflow),
+          project_analyzer_metadata: project_analyzer_metadata_for(workflow),
+          why_it_matters: why_for(workflow), suggested_next_moves: suggested_next_moves_for(workflow)
+        )
+      end
+
+      def triage_attributes_for(workflow)
+        return setup_triage_attributes if setup_orchestration?(workflow)
+
+        project_analyzer_triage_attributes
+      end
+
+      def setup_triage_attributes
+        SetupWorkflowTriage.attributes(PROJECT_ANALYZER_STATUS)
+      end
+
+      def why_for(workflow)
+        setup_orchestration?(workflow) ? SetupWorkflowTriage::WHY : WHY
+      end
+
+      def suggested_next_moves_for(workflow)
+        setup_orchestration?(workflow) ? SetupWorkflowTriage::SUGGESTED_NEXT_MOVES : SUGGESTED_NEXT_MOVES
+      end
+
+      def workflow_attributes(workflow, services)
+        { source: source_name, rule_id: RULE_ID, message: message_for(workflow, services),
+          workflow: workflow.name, services: services, occurrences: workflow.service_calls }
+      end
+
+      def service_names(workflow)
+        workflow.service_calls.map(&:service_name).uniq.sort
+      end
+
+      def setup_orchestration?(workflow)
+        SetupWorkflowTriage.setup?(workflow)
+      end
+
+      def message_for(workflow, services)
+        "#{workflow.name} coordinates #{services.size} distinct services; " \
+          "consider a workflow object that owns the process."
+      end
+
+      def project_analyzer_metadata_for(workflow)
+        { "workflow" => workflow_metadata(workflow),
+          "services" => workflow.service_calls.map { |service_call| service_call_metadata(service_call) } }
+      end
+
+      def workflow_metadata(workflow)
+        { "context" => workflow.name, "enclosing" => workflow.enclosing_name,
+          "method" => workflow.method_name, "line" => workflow.line,
+          "expression" => workflow.expression }.compact
+      end
+
+      def service_call_metadata(service_call)
+        { "service" => service_call.service_name, "path" => service_call.path,
+          "line" => service_call.line, "expression" => service_call.expression,
+          "style" => service_call.style.to_s }.compact
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/subclass_override_pressure/family_builder.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class SubclassOverridePressure
+      module FamilyBuilder
+        private
+
+        def base_candidates
+          return configured_base_candidates unless base_names.empty?
+
+          auto_discovered_base_candidates
+        end
+
+        def configured_base_candidates
+          base_names.filter_map { |name| declarations_by_name[name] }
+        end
+
+        def auto_discovered_base_candidates
+          index.declarations.select { |declaration| auto_discovered_base_candidate?(declaration) }
+        end
+
+        def auto_discovered_base_candidate?(declaration)
+          declaration.name && declaration.path && class_candidate?(declaration) &&
+            !ignored_declaration_name?(declaration.name)
+        end
+
+        def class_candidate?(declaration)
+          !declaration.respond_to?(:kind) || declaration.kind.nil? || declaration.kind == :class
+        end
+
+        def findings_for(base)
+          descendants = sorted_descendants(base.name)
+          return [] if descendants.size < minimum_overriding_descendants
+
+          base_methods(base).filter_map { |base_method| finding_for(base, base_method, descendants) }
+        end
+
+        def sorted_descendants(base_name)
+          index.descendants_of(base_name).reject { |name| ignored_declaration_name?(name) }.sort
+        end
+
+        def base_methods(base)
+          methods = methods_by_owner.fetch(base.name, [])
+          methods.uniq { |method| method_identity_for(method) }
+                 .sort_by { |method| method_identity_for(method) }
+        end
+
+        def finding_for(base, base_method, descendants)
+          overrides = overrides_for(method_identity_for(base_method), descendants)
+          return if overrides.size < minimum_overriding_descendants
+
+          Finding.new(finding_attributes(override_family(base, base_method, descendants, overrides)))
+        end
+
+        def overrides_for(method_identity, descendants)
+          descendants.filter_map { |descendant| method_declaration_for(descendant, method_identity) }
+                     .sort_by { |declaration| declaration.owner_name.to_s }
+        end
+
+        def method_declaration_for(owner_name, method_identity)
+          methods_by_owner.fetch(owner_name, []).find do |declaration|
+            method_identity_for(declaration) == method_identity
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../occurrence"
+
+module MetzScan
+  module Analyzers
+    class SubclassOverridePressure
+      Finding = Struct.new(:source, :rule_id, :message, :base_name, :method_name, :method_identity,
+                           :receiver_kind, :descendant_count, :overriding_descendants, :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
+          occurrence = occurrences.first
+          [Occurrence.from(occurrence, context: occurrence_context(occurrence))].compact
+        end
+
+        def occurrence_context(occurrence)
+          "#{occurrence&.owner_name}#{method_separator(occurrence)}#{method_name}"
+        end
+
+        def method_separator(occurrence)
+          return "#" unless occurrence.respond_to?(:receiver_kind)
+
+          occurrence.receiver_kind == "singleton" ? "." : "#"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class SubclassOverridePressure
+      module Metadata
+        def project_analyzer_metadata_for(family)
+          core_project_analyzer_metadata(family)
+            .merge("overriding_descendants" => family.overrides.map(&:owner_name),
+                   "override_locations" => override_locations(family))
+            .compact
+        end
+
+        def core_project_analyzer_metadata(family)
+          category_metadata(subclass_override_category(family)).merge(family_metadata(family))
+        end
+
+        def category_metadata(category)
+          { "project_analyzer_category" => category, "subclass_override_category" => category }
+        end
+
+        def family_metadata(family)
+          family_identity_metadata(family)
+            .merge(body_fact_metadata(family))
+            .merge(count_metadata(family))
+        end
+
+        def family_identity_metadata(family)
+          { "base_name" => family.base.name, "method_name" => family.method_name,
+            "method_identity" => family.method_identity, "receiver_kind" => family.receiver_kind,
+            "root_kind" => family.root_kind }
+        end
+
+        def body_fact_metadata(family)
+          { "base_method_body_kind" => family.base_method_body_kind,
+            "overrides_calling_super_count" => family.overrides_calling_super_count }
+        end
+
+        def count_metadata(family)
+          { "descendant_count" => family.descendants.size, "override_count" => family.overrides.size }
+        end
+
+        def override_locations(family)
+          family.overrides.map { |declaration| override_location(family, declaration) }
+        end
+
+        def override_location(family, declaration)
+          override_identity_location(declaration)
+            .merge("calls_super" => family.override_body_facts.fetch(declaration.owner_name).calls_super)
+            .compact
+        end
+
+        def override_identity_location(declaration)
+          { "owner_name" => declaration.owner_name, "path" => declaration.path, "line" => declaration.line,
+            "receiver_kind" => receiver_kind_for(declaration),
+            "method_identity" => method_identity_for(declaration) }
+        end
+
+        def subclass_override_category(family)
+          return "broad_root_override" if family.root_kind
+          return "abstract_hook_override" if abstract_hook_body?(family.base_method_body_kind)
+          return "cooperative_override" if family.overrides_calling_super_count.positive?
+          return "replacement_override" unless family.base_method_body_kind == "unknown"
+
+          "subclass_override"
+        end
+
+        def abstract_hook_body?(body_kind)
+          %w[abstract_raise empty default_value].include?(body_kind)
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/subclass_override_pressure/method_body_facts.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module MetzScan
+  module Analyzers
+    class SubclassOverridePressure
+      class MethodBodyFacts
+        Facts = Struct.new(:body_kind, :calls_super, keyword_init: true)
+
+        def initialize
+          @processed_sources = {}
+        end
+
+        def for(declaration)
+          Facts.new(body_kind: body_kind_for(declaration), calls_super: calls_super?(declaration))
+        end
+
+        private
+
+        attr_reader :processed_sources
+
+        def body_kind_for(declaration)
+          body_kind_for_node(method_node_for(declaration))
+        end
+
+        def body_kind_for_node(node)
+          return "unknown" unless node
+
+          body = body_for(node)
+          return "empty" unless body
+
+          body_kind_for_body(body)
+        end
+
+        def body_kind_for_body(body)
+          return "abstract_raise" if abstract_raise?(body)
+          return "default_value" if default_value?(body)
+
+          "concrete"
+        end
+
+        def calls_super?(declaration)
+          body = body_for(method_node_for(declaration))
+          body && each_node(body).any? { |node| %i[super zsuper].include?(node.type) }
+        end
+
+        def method_node_for(declaration)
+          return unless declaration&.path && declaration.line
+
+          ast = processed_source_for(declaration.path)&.ast
+          each_node(ast).find { |node| method_node_at_line?(node, declaration.line) }
+        end
+
+        def processed_source_for(path)
+          return processed_sources[path] if processed_sources.key?(path)
+
+          processed_sources[path] = build_processed_source(path)
+        end
+
+        def build_processed_source(path)
+          RuboCop::ProcessedSource.new(File.read(path), RUBY_VERSION.to_f) if File.file?(path)
+        rescue Parser::SyntaxError
+          nil
+        end
+
+        def method_node_at_line?(node, line)
+          %i[def defs].include?(node.type) && node.loc.expression.line == line
+        end
+
+        def body_for(node)
+          return unless node
+
+          node.body
+        end
+
+        def abstract_raise?(body)
+          each_node(body).any? { |node| raise_not_implemented?(node) }
+        end
+
+        def raise_not_implemented?(node)
+          node.type == :send && node.method_name == :raise &&
+            node.source.match?(/NotImplemented|must implement|override/i)
+        end
+
+        def default_value?(body)
+          %i[nil true false str sym array hash].include?(body.type)
+        end
+
+        def each_node(root, &block)
+          return enum_for(:each_node, root) unless block
+          return unless root
+
+          block.call(root)
+          root.children.grep(RuboCop::AST::Node).each { |child| each_node(child, &block) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class SubclassOverridePressure
+      module Triage
+        CATEGORY_TRIAGE = {
+          "abstract_hook_override" => {
+            triage_summary: "Candidate abstract hook override signal; review whether subclasses implement an " \
+                            "implicit hook protocol.",
+            why: "Abstract hooks can make inheritance an implicit protocol whose required behavior is only " \
+                 "visible after reading every subclass.",
+            suggested_next_moves: [
+              "Name the hook contract in the base class or an extracted collaborator.",
+              "Keep deliberate extension points when each subclass implements the same stable role."
+            ]
+          },
+          "cooperative_override" => {
+            triage_summary: "Candidate cooperative override signal; review whether super-based extension points " \
+                            "are explicit.",
+            why: "Cooperative overrides rely on template-method ordering, so base changes can break subclasses " \
+                 "that extend behavior with super.",
+            suggested_next_moves: [
+              "Keep cooperative hooks small and document the call order expected around super.",
+              "Extract the variable step when subclasses need independent behavior."
+            ]
+          },
+          "replacement_override" => {
+            triage_summary: "Candidate replacement override signal; review subclasses that replace concrete " \
+                            "base behavior.",
+            why: "Replacement overrides can weaken substitution when callers expect the concrete base behavior " \
+                 "but subclasses silently replace it.",
+            suggested_next_moves: [
+              "Prefer composition when subclasses replace the same concrete behavior for different reasons.",
+              "Push shared behavior into a collaborator when only the selection logic varies."
+            ]
+          }
+        }.freeze
+        MESSAGE_METHODS = {
+          "abstract_hook_override" => :abstract_hook_message_for,
+          "cooperative_override" => :cooperative_override_message_for,
+          "replacement_override" => :replacement_override_message_for
+        }.freeze
+        private_constant :CATEGORY_TRIAGE, :MESSAGE_METHODS
+
+        def triage_attributes_for(family)
+          return broad_root_triage_attributes if family.root_kind
+
+          project_analyzer_triage_attributes.merge(
+            triage_summary: triage_profile_for(family).fetch(:triage_summary)
+          )
+        end
+
+        def project_analyzer_context_attributes(family)
+          profile = triage_profile_for(family)
+
+          { project_analyzer_metadata: project_analyzer_metadata_for(family),
+            why_it_matters: profile.fetch(:why),
+            suggested_next_moves: profile.fetch(:suggested_next_moves) }
+        end
+
+        def message_for(family)
+          public_send(message_method_for(family), family)
+        end
+
+        def broad_root_triage_attributes
+          { project_analyzer_status: PROJECT_ANALYZER_STATUS, confidence: BROAD_ROOT_CONFIDENCE,
+            triage_severity: BROAD_ROOT_TRIAGE_SEVERITY, triage_summary: BROAD_ROOT_TRIAGE_SUMMARY }
+        end
+
+        def triage_profile_for(family)
+          CATEGORY_TRIAGE.fetch(subclass_override_category(family)) { generic_triage_profile }
+        end
+
+        def generic_triage_profile
+          { triage_summary: TRIAGE_SUMMARY, why: WHY, suggested_next_moves: SUGGESTED_NEXT_MOVES }
+        end
+
+        def message_method_for(family)
+          MESSAGE_METHODS.fetch(subclass_override_category(family), :generic_override_message_for)
+        end
+
+        def abstract_hook_message_for(family)
+          "#{family.base.name} descendants implement #{family.method_name} as an abstract hook in " \
+            "#{family.overrides.size} subclasses; consider naming the hook protocol."
+        end
+
+        def cooperative_override_message_for(family)
+          "#{family.base.name} descendants extend #{family.method_name} with super in " \
+            "#{family.overrides_calling_super_count} of #{family.overrides.size} overrides; " \
+            "consider making the extension contract explicit."
+        end
+
+        def replacement_override_message_for(family)
+          "#{family.base.name} descendants replace concrete #{family.method_name} behavior in " \
+            "#{family.overrides.size} subclasses; consider whether composition would make the variation explicit."
+        end
+
+        def generic_override_message_for(family)
+          "#{family.base.name} descendants override #{family.method_name} in #{family.overrides.size} subclasses; " \
+            "consider whether the hook protocol should be explicit."
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/subclass_override_pressure.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "../project_index"
+require_relative "inheritance_descendants/root_kind"
+require_relative "project_analyzer_triage"
+require_relative "subclass_override_pressure/family_builder"
+require_relative "subclass_override_pressure/finding"
+require_relative "subclass_override_pressure/metadata"
+require_relative "subclass_override_pressure/method_body_facts"
+require_relative "subclass_override_pressure/triage"
+
+module MetzScan
+  module Analyzers
+    # Reports base classes whose descendants repeatedly override the same method.
+    class SubclassOverridePressure
+      include ProjectAnalyzerTriage
+      include FamilyBuilder
+      include Metadata
+      include Triage
+
+      RULE_ID = "MetzProject/SubclassOverridePressure"
+      PROJECT_ANALYZER_STATUS = "candidate"
+      CONFIDENCE = "medium"
+      TRIAGE_SEVERITY = "manual review"
+      TRIAGE_SUMMARY = "Candidate subclass override signal; review whether shared hooks hide coupling."
+      BROAD_ROOT_CONFIDENCE = "low"
+      BROAD_ROOT_TRIAGE_SEVERITY = "broad base"
+      BROAD_ROOT_TRIAGE_SUMMARY = "Broad inheritance base with repeated overrides; review only when hook " \
+                                  "changes frequently or subclasses diverge."
+      WHY = "Repeated subclass overrides can turn inheritance into an implicit protocol that is hard to change."
+      SUGGESTED_NEXT_MOVES = [
+        "Review whether the base class is defining a hook protocol that should be explicit.",
+        "Prefer composition when subclasses override the same behavior for unrelated reasons."
+      ].freeze
+      MINIMUM_OVERRIDING_DESCENDANTS = 6
+      IGNORED_DECLARATION_NAMES = %w[BasicObject Class Kernel Module Object].freeze
+      SYNTHETIC_DECLARATION_MARKER = "::<"
+      private_constant :IGNORED_DECLARATION_NAMES, :SYNTHETIC_DECLARATION_MARKER
+
+      OverrideFamily = Struct.new(:base, :base_method, :method_name, :method_identity, :receiver_kind,
+                                  :descendants, :overrides, :root_kind,
+                                  :base_method_body_kind, :override_body_facts, keyword_init: true) do
+        def overrides_calling_super_count
+          override_body_facts.values.count(&:calls_super)
+        end
+      end
+
+      def initialize(paths: nil, index: nil, base_names: nil,
+                     minimum_overriding_descendants: MINIMUM_OVERRIDING_DESCENDANTS)
+        @paths = Array(paths)
+        @index = index || ProjectIndex.build(@paths)
+        @base_names = Array(base_names).compact
+        @minimum_overriding_descendants = minimum_overriding_descendants
+      end
+
+      def call
+        return [] unless index.available?
+
+        base_candidates.flat_map { |base| findings_for(base) }
+      end
+
+      private
+
+      attr_reader :index, :base_names, :minimum_overriding_descendants
+
+      def override_family(base, base_method, descendants, overrides)
+        OverrideFamily.new(override_family_attributes(base, base_method, descendants, overrides))
+      end
+
+      def override_family_attributes(base, base_method, descendants, overrides)
+        override_identity_attributes(base, base_method)
+          .merge(descendants: descendants, overrides: overrides,
+                 base_method_body_kind: body_facts_for(base_method).body_kind,
+                 override_body_facts: override_body_facts_for(overrides))
+      end
+
+      def override_identity_attributes(base, base_method)
+        { base: base, base_method: base_method, method_name: base_method.method_name,
+          method_identity: method_identity_for(base_method), receiver_kind: receiver_kind_for(base_method),
+          root_kind: InheritanceDescendants::RootKind.for(base.name) }
+      end
+
+      def finding_attributes(family)
+        core_finding_attributes(family)
+          .merge(triage_attributes_for(family))
+          .merge(project_analyzer_context_attributes(family))
+      end
+
+      def core_finding_attributes(family)
+        { source: source_name, rule_id: RULE_ID, message: message_for(family),
+          base_name: family.base.name, method_name: family.method_name, method_identity: family.method_identity,
+          receiver_kind: family.receiver_kind, descendant_count: family.descendants.size,
+          overriding_descendants: family.overrides.map(&:owner_name), occurrences: family.overrides }
+      end
+
+      def declarations_by_name
+        @declarations_by_name ||= index.declarations.to_h { |declaration| [declaration.name, declaration] }
+      end
+
+      def methods_by_owner
+        @methods_by_owner ||= index.method_declarations.group_by(&:owner_name)
+      end
+
+      def override_body_facts_for(overrides)
+        overrides.to_h { |override| [override.owner_name, body_facts_for(override)] }
+      end
+
+      def body_facts_for(declaration)
+        body_facts.for(declaration)
+      end
+
+      def body_facts
+        @body_facts ||= MethodBodyFacts.new
+      end
+
+      def ignored_declaration_name?(name)
+        IGNORED_DECLARATION_NAMES.include?(name) || name.include?(SYNTHETIC_DECLARATION_MARKER)
+      end
+
+      def method_identity_for(declaration)
+        return declaration.method_identity if declaration.respond_to?(:method_identity) && declaration.method_identity
+
+        "#{receiver_kind_for(declaration)}:#{declaration.method_name}"
+      end
+
+      def receiver_kind_for(declaration)
+        return declaration.receiver_kind if declaration.respond_to?(:receiver_kind) && declaration.receiver_kind
+
+        declaration.name.to_s.include?(".") ? "singleton" : "instance"
+      end
+    end
+  end
+end