rubocop-metz 0.5.2

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class RepeatedQueryCriteria
+      module Triage
+        CATEGORY_TRIAGE = {
+          "polymorphic_where_criteria" => {
+            triage_summary: "Candidate polymorphic query signal; review whether polymorphic lookup rules need a " \
+                            "name.",
+            why: "Repeated polymorphic query criteria spread type/id coupling across callers and make policy " \
+                 "changes harder to find.",
+            suggested_next_moves: [
+              "Extract a named scope or query object when the polymorphic lookup is a domain concept.",
+              "Keep inline polymorphic criteria only when the repetition is mechanical and local."
+            ]
+          },
+          "compound_association_where_criteria" => {
+            triage_summary: "Candidate compound association query signal; review whether association pairs need a " \
+                            "named query.",
+            why: "Repeated compound association criteria can hide a relationship rule in several callers instead " \
+                 "of behind one named query.",
+            suggested_next_moves: [
+              "Extract a named scope when the association pair represents a reusable relationship.",
+              "Keep simple join-table lookups inline when the criteria are purely mechanical."
+            ]
+          },
+          "scoped_association_where_criteria" => {
+            triage_summary: "Candidate scoped association query signal; review whether scoped criteria belong " \
+                            "behind a named query.",
+            why: "Repeated association-scoped criteria spread filtering rules across callers and make policy " \
+                 "changes harder to find.",
+            suggested_next_moves: [
+              "Extract a named scope or query object when the predicate represents a reusable business concept.",
+              "Keep one-off lookup criteria inline when repetition is incidental or purely local."
+            ]
+          },
+          "where_hash_criteria" => {
+            triage_summary: "Candidate repeated query signal; review whether criteria belong behind a named query.",
+            why: "Repeated query predicates spread data-access rules across callers and make policy changes " \
+                 "harder to find.",
+            suggested_next_moves: [
+              "Extract a named scope or query object when the predicate represents a reusable business concept.",
+              "Keep one-off lookup criteria inline when repetition is incidental or purely local."
+            ]
+          }
+        }.freeze
+        MESSAGE_PHRASES = {
+          "polymorphic_where_criteria" => "repeats polymorphic query criteria",
+          "compound_association_where_criteria" => "repeats compound association query criteria",
+          "scoped_association_where_criteria" => "repeats association-scoped query criteria",
+          "where_hash_criteria" => "appears"
+        }.freeze
+        private_constant :CATEGORY_TRIAGE, :MESSAGE_PHRASES
+
+        private
+
+        def repeated_query_category_for(site)
+          return "polymorphic_where_criteria" if polymorphic_criteria?(site.criteria_keys)
+          return "compound_association_where_criteria" if foreign_key_count(site.criteria_keys) >= 2
+          return "scoped_association_where_criteria" if foreign_key_count(site.criteria_keys).positive?
+
+          "where_hash_criteria"
+        end
+
+        def polymorphic_criteria?(criteria_keys)
+          criteria_keys.any? do |key|
+            key.end_with?("_type") && criteria_keys.include?("#{key.delete_suffix('_type')}_id")
+          end
+        end
+
+        def foreign_key_count(criteria_keys)
+          criteria_keys.count { |key| key.end_with?("_id") }
+        end
+
+        def criteria_key_shape_for(site)
+          repeated_query_category_for(site).delete_suffix("_where_criteria")
+        end
+
+        def category_triage_attributes(category)
+          profile = CATEGORY_TRIAGE.fetch(category)
+
+          { triage_summary: profile.fetch(:triage_summary), why_it_matters: profile.fetch(:why),
+            suggested_next_moves: profile.fetch(:suggested_next_moves) }
+        end
+
+        def query_message_phrase(site, category)
+          return "repeats finder query criteria" if site.query_operation == "finder"
+          return negative_query_message_phrase(category) if site.query_operation == "negative_filter"
+
+          MESSAGE_PHRASES.fetch(category)
+        end
+
+        def negative_query_message_phrase(category)
+          { "polymorphic_where_criteria" => "repeats negative polymorphic query criteria",
+            "compound_association_where_criteria" => "repeats negative compound association query criteria",
+            "scoped_association_where_criteria" => "repeats negative association-scoped query criteria",
+            "where_hash_criteria" => "repeats negative query criteria" }.fetch(category)
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/repeated_query_criteria.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+require_relative "contextual_node_walker"
+require_relative "occurrence"
+require_relative "package_map"
+require_relative "project_analyzer_triage"
+require_relative "repeated_query_criteria/triage"
+require_relative "ruby_file_enumerator"
+
+module MetzScan
+  module Analyzers
+    # Reports repeated hash-style ActiveRecord query predicates across packages.
+    class RepeatedQueryCriteria
+      include ProjectAnalyzerTriage
+      include Triage
+
+      RULE_ID = "MetzProject/RepeatedQueryCriteria"
+      PROJECT_ANALYZER_STATUS = "candidate"
+      CONFIDENCE = "medium"
+      TRIAGE_SEVERITY = "manual review"
+      TRIAGE_SUMMARY = "Candidate repeated query signal; review whether criteria belong behind a named query."
+      WHY = "Repeated query predicates spread data-access rules across callers and make policy changes harder to find."
+      SUGGESTED_NEXT_MOVES = [
+        "Extract a named scope or query object when the predicate represents a reusable business concept.",
+        "Keep one-off lookup criteria inline when repetition is incidental or purely local."
+      ].freeze
+      MINIMUM_FILES = 3
+      MINIMUM_PACKAGES = 2
+      MINIMUM_CRITERIA_KEYS = 2
+      Finding = Struct.new(:source, :rule_id, :message, :query, :receiver, :criteria_keys,
+                           :referring_files, :referring_packages, :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)].compact
+        end
+      end
+
+      def initialize(paths: nil, index: nil, minimum_files: MINIMUM_FILES, minimum_packages: MINIMUM_PACKAGES)
+        @paths = Array(paths)
+        @index = index
+        @minimum_files = minimum_files
+        @minimum_packages = minimum_packages
+      end
+
+      def call
+        query_sites.group_by(&:fingerprint).filter_map do |_fingerprint, sites|
+          finding_for(sites)
+        end
+      end
+
+      private
+
+      attr_reader :paths, :index, :minimum_files, :minimum_packages
+
+      def query_sites
+        ruby_files.flat_map { |path| QuerySiteCollector.new(path).call }
+                  .reject { |site| PackageMap.ignored_path?(site.path) }
+                  .select { |site| PackageMap.package_for(site.path) }
+      end
+
+      def ruby_files
+        RubyFileEnumerator.new(paths: paths, index: index).call
+      end
+
+      def finding_for(sites)
+        grouped = QuerySiteSet.new(sites)
+        return unless grouped.referring_files.size >= minimum_files
+        return unless grouped.referring_packages.size >= minimum_packages
+
+        first = grouped.sites.first
+        Finding.new(finding_attributes(first, grouped))
+      end
+
+      def finding_attributes(first, grouped)
+        category = repeated_query_category_for(first)
+
+        core_finding_attributes(first, grouped, category)
+          .merge(project_analyzer_triage_attributes, category_triage_attributes(category))
+          .merge(project_analyzer_context_attributes(first, grouped, category))
+      end
+
+      def core_finding_attributes(first, grouped, category)
+        { source: source_name, rule_id: RULE_ID, message: message_for(first, grouped, category),
+          query: first.query, receiver: first.receiver, criteria_keys: first.criteria_keys,
+          referring_files: grouped.referring_files, referring_packages: grouped.referring_packages,
+          occurrences: grouped.sites }
+      end
+
+      def project_analyzer_context_attributes(first, grouped, category)
+        { project_analyzer_metadata: project_analyzer_metadata_for(first, grouped, category) }
+      end
+
+      def message_for(site, grouped, category)
+        "#{site.query} #{query_message_phrase(site, category)} in #{grouped.referring_files.size} files across " \
+          "#{grouped.referring_packages.size} packages; consider naming the query criteria."
+      end
+
+      def project_analyzer_metadata_for(site, grouped, category)
+        query_metadata(site, category).merge(query_reference_metadata(grouped))
+      end
+
+      def query_metadata(site, category)
+        query_identity_metadata(site, category).merge(query_shape_metadata(site))
+      end
+
+      def query_identity_metadata(site, category)
+        { "project_analyzer_category" => category, "repeated_query_category" => category, "query" => site.query,
+          "query_method" => site.query_method, "query_operation" => site.query_operation }
+      end
+
+      def query_shape_metadata(site)
+        { "receiver" => site.receiver, "criteria_keys" => site.criteria_keys,
+          "receiver_shape" => site.receiver_shape, "criteria_key_shape" => criteria_key_shape_for(site) }
+      end
+
+      def query_reference_metadata(grouped)
+        { "referring_files" => grouped.referring_files, "referring_packages" => grouped.referring_packages,
+          "occurrences" => occurrences_metadata(grouped) }
+      end
+
+      def occurrences_metadata(grouped)
+        grouped.sites.map { |site| occurrence_metadata(site) }
+      end
+
+      def occurrence_metadata(site)
+        { "path" => site.path, "line" => site.line, "context" => site.context,
+          "expression" => site.expression }.compact
+      end
+
+      class QuerySiteSet
+        def initialize(sites)
+          @sites = sites.sort_by { |site| [site.path, site.line.to_i] }
+        end
+
+        attr_reader :sites
+
+        def referring_files
+          sites.map(&:path).uniq
+        end
+
+        def referring_packages
+          sites.map { |site| PackageMap.package_for(site.path) }.compact.uniq.sort
+        end
+      end
+
+      class QuerySiteCollector
+        FINDER_QUERY_METHODS = %i[find_by find_or_create_by find_or_initialize_by].freeze
+        QuerySite = Struct.new(:receiver, :criteria_keys, :query_method, :query_operation, :enclosing_name,
+                               :method_name, :path, :line, :expression, keyword_init: true) do
+          def query
+            "#{receiver}.#{query_method}(#{criteria_keys.join(', ')})"
+          end
+
+          def receiver_shape
+            receiver.include?(".") ? "scope_chain" : "constant"
+          end
+
+          def fingerprint
+            [receiver, query_method, criteria_keys].join(":")
+          end
+
+          def context
+            return "#{enclosing_name}#{method_name}" if enclosing_name && method_name
+
+            method_name || enclosing_name
+          end
+        end
+
+        def initialize(path)
+          @path = path
+        end
+
+        def call
+          contextual_nodes.filter_map { |contextual_node| query_site_for(contextual_node) }
+        rescue Parser::SyntaxError
+          []
+        end
+
+        private
+
+        attr_reader :path
+
+        def processed_source
+          RuboCop::ProcessedSource.new(File.read(path), RUBY_VERSION.to_f)
+        end
+
+        def contextual_nodes
+          ContextualNodeWalker.new(processed_source.ast).nodes
+        end
+
+        def receiver_fingerprint_for(node)
+          return unless node
+          return node.source if node.type == :const
+          return unless simple_scope_call?(node)
+
+          parent = receiver_fingerprint_for(node.receiver)
+          "#{parent}.#{node.method_name}" if parent
+        end
+
+        def simple_scope_call?(node)
+          node.type == :send && node.receiver && node.arguments.empty? &&
+            node.method_name.to_s.match?(/\A[a-z_]\w*[!?]?\z/)
+        end
+
+        def query_site_for(contextual_node)
+          node = contextual_node.node
+          query_attributes = query_attributes_for(node)
+          return unless query_attributes
+
+          QuerySite.new(query_attributes.merge(context_attributes_for(contextual_node, node)))
+        end
+
+        def context_attributes_for(contextual_node, node)
+          { enclosing_name: contextual_node.enclosing_name, method_name: contextual_node.method_name,
+            path: path, line: node.loc.expression.line, expression: first_line(node) }
+        end
+
+        def query_attributes_for(node)
+          return unless node.type == :send
+
+          positive_where_query_attributes(node) ||
+            finder_query_attributes(node) ||
+            negative_where_query_attributes(node)
+        end
+
+        def positive_where_query_attributes(node)
+          return unless node.method_name == :where
+
+          query_attributes_for_parts(node.receiver, criteria_keys_for(node), "where", "filter")
+        end
+
+        def finder_query_attributes(node)
+          return unless FINDER_QUERY_METHODS.include?(node.method_name)
+
+          query_attributes_for_parts(node.receiver, criteria_keys_for(node), node.method_name.to_s, "finder")
+        end
+
+        def negative_where_query_attributes(node)
+          return unless node.method_name == :not
+
+          receiver_node = empty_where_receiver_for(node)
+          return unless receiver_node
+
+          query_attributes_for_parts(receiver_node.receiver, criteria_keys_for(node), "where.not", "negative_filter")
+        end
+
+        def empty_where_receiver_for(node)
+          receiver_node = node.receiver
+          receiver_node if receiver_node&.type == :send && receiver_node.method_name == :where &&
+                           receiver_node.arguments.empty?
+        end
+
+        def query_attributes_for_parts(receiver_node, criteria_keys, query_method, query_operation)
+          receiver = receiver_fingerprint_for(receiver_node)
+          return unless receiver
+          return unless criteria_keys.size >= MINIMUM_CRITERIA_KEYS
+
+          { receiver: receiver, criteria_keys: criteria_keys, query_method: query_method,
+            query_operation: query_operation }
+        end
+
+        def criteria_keys_for(node)
+          hash = node.arguments.first
+          return [] unless hash&.type == :hash
+          return [] unless hash.children.all? { |child| child.type == :pair }
+
+          hash.children.filter_map { |pair| literal_key(pair.children.first) }.sort
+        end
+
+        def literal_key(node)
+          node.value.to_s if %i[sym str].include?(node.type)
+        end
+
+        def first_line(node)
+          node.loc.expression.source.lines.first.strip
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/ruby_file_enumerator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class RubyFileEnumerator
+      RUBY_GLOB = "**/*.rb"
+
+      def initialize(paths:, index: nil)
+        @paths = Array(paths)
+        @index = index
+      end
+
+      def call
+        return ruby_files_for(paths) unless paths.empty?
+        return index.indexed_files if index&.available?
+
+        []
+      end
+
+      private
+
+      attr_reader :paths, :index
+
+      def ruby_files_for(paths)
+        paths.flat_map { |path| ruby_files_under(path) }.uniq.sort
+      end
+
+      def ruby_files_under(path)
+        expanded = File.expand_path(path)
+        return Dir.glob(File.join(expanded, RUBY_GLOB)) if File.directory?(expanded)
+        return [expanded] if File.file?(expanded) && File.extname(expanded) == ".rb"
+
+        []
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/service_soup/service_call_pattern.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class ServiceSoup
+      class ServiceCallPattern
+        Match = Struct.new(:service_name, :style, keyword_init: true)
+        CLASS_SERVICE_METHODS = %i[call].freeze
+        NEW_SERVICE_METHOD_STYLES = { call: :new_call, perform: :new_perform }.freeze
+
+        def initialize(node)
+          @node = node
+        end
+
+        def match
+          return class_match if class_service_call?
+          return new_match if new_service_call?
+
+          nil
+        end
+
+        private
+
+        attr_reader :node
+
+        def class_match
+          Match.new(service_name: node.receiver.source, style: :class_call)
+        end
+
+        def new_match
+          Match.new(service_name: node.receiver.receiver.source,
+                    style: NEW_SERVICE_METHOD_STYLES.fetch(node.method_name))
+        end
+
+        def class_service_call?
+          CLASS_SERVICE_METHODS.include?(node.method_name) && constant_receiver?(node.receiver)
+        end
+
+        def new_service_call?
+          NEW_SERVICE_METHOD_STYLES.key?(node.method_name) && new_service_receiver?(node.receiver)
+        end
+
+        def new_service_receiver?(receiver)
+          receiver&.type == :send && receiver.method_name == :new && constant_receiver?(receiver.receiver)
+        end
+
+        def constant_receiver?(receiver)
+          receiver&.type == :const
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/service_soup/setup_workflow_triage.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class ServiceSoup
+      module SetupWorkflowTriage
+        CONFIDENCE = "low"
+        TRIAGE_SEVERITY = "setup orchestration"
+        TRIAGE_SUMMARY = "Setup workflow signal; review only when setup orchestration changes often " \
+                         "or hides domain workflow pressure."
+        WHY = "Setup orchestration often intentionally runs a list of tasks; review only when it " \
+              "changes often or hides domain workflow pressure."
+        SUGGESTED_NEXT_MOVES = [
+          "Leave setup orchestration as a list when it is stable and declarative.",
+          "Extract a named workflow only when setup steps change together or need clearer sequencing."
+        ].freeze
+        TOKEN_PATTERN = /\A(?:seeds?|seeders?|setup|install(?:er|ation)?|bootstrap)\z/i
+
+        module_function
+
+        def setup?(workflow)
+          setup_path?(workflow.path) || setup_name?(workflow.name) || setup_method?(workflow.method_name)
+        end
+
+        def attributes(status)
+          { project_analyzer_status: status, confidence: CONFIDENCE,
+            triage_severity: TRIAGE_SEVERITY, triage_summary: TRIAGE_SUMMARY }
+        end
+
+        def setup_path?(path)
+          path.to_s.split(%r{[/\\]}).any? { |segment| setup_token?(File.basename(segment, ".rb")) }
+        end
+
+        def setup_name?(name)
+          name.to_s.split("::").any? { |segment| setup_token?(segment.delete_prefix("#").delete_prefix(".")) }
+        end
+
+        def setup_method?(method_name)
+          setup_token?(method_name.to_s.delete_prefix("#").delete_prefix("."))
+        end
+
+        def setup_token?(token)
+          token.to_s.split(/[_\-.]/).any? { |part| part.match?(TOKEN_PATTERN) }
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/service_soup/workflow_collector.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+require_relative "service_call_pattern"
+
+module MetzScan
+  module Analyzers
+    class ServiceSoup
+      class WorkflowCollector
+        Workflow = Struct.new(:name, :enclosing_name, :method_name, :path, :line, :expression, :service_calls,
+                              keyword_init: true)
+        ServiceCall = Struct.new(:service_name, :path, :line, :expression, :style, keyword_init: true)
+
+        def initialize(path)
+          @path = path
+        end
+
+        def call
+          collect_workflows(processed_source.ast, [], [])
+        rescue Parser::SyntaxError
+          []
+        end
+
+        private
+
+        attr_reader :path
+
+        def processed_source
+          RuboCop::ProcessedSource.new(File.read(path), RUBY_VERSION.to_f)
+        end
+
+        def collect_workflows(node, namespace, workflows)
+          return workflows unless node
+
+          collect_node(node, namespace, workflows)
+        end
+
+        def collect_node(node, namespace, workflows)
+          return collect_namespace(node, namespace, workflows) if %i[class module].include?(node.type)
+          return collect_instance_method(node, namespace, workflows) if node.type == :def
+          return collect_singleton_method(node, namespace, workflows) if node.type == :defs
+
+          collect_child_workflows(node, namespace, workflows)
+        end
+
+        def collect_namespace(node, namespace, workflows)
+          name = constant_name(node.children.first)
+          body = node.children.last
+          collect_workflows(body, namespace + [name].compact, workflows)
+        end
+
+        def collect_instance_method(node, namespace, workflows)
+          service_calls = service_calls_under(node.children[2])
+          workflows << workflow_for(namespace, "##{node.method_name}", node, service_calls) unless service_calls.empty?
+          workflows
+        end
+
+        def collect_singleton_method(node, namespace, workflows)
+          service_calls = service_calls_under(node.children[3])
+          workflows << workflow_for(namespace, ".#{node.method_name}", node, service_calls) unless service_calls.empty?
+          workflows
+        end
+
+        def collect_child_workflows(node, namespace, workflows)
+          node.children.grep(RuboCop::AST::Node).each { |child| collect_workflows(child, namespace, workflows) }
+          workflows
+        end
+
+        def workflow_for(namespace, method_suffix, node, service_calls)
+          enclosing_name = namespace.join("::")
+          Workflow.new(name: "#{enclosing_name}#{method_suffix}", enclosing_name: optional_name(enclosing_name),
+                       method_name: method_suffix, path: path, line: node.loc.expression.line,
+                       expression: first_line(node), service_calls: service_calls)
+        end
+
+        def service_calls_under(node, service_calls = [])
+          return service_calls unless service_search_node?(node)
+
+          collect_service_call(node, service_calls)
+          collect_child_service_calls(node, service_calls)
+        end
+
+        def nested_scope?(node)
+          %i[class module def defs].include?(node.type)
+        end
+
+        def service_search_node?(node)
+          node && !nested_scope?(node)
+        end
+
+        def collect_service_call(node, service_calls)
+          service_call = service_call_for(node)
+          service_calls << service_call if service_call
+        end
+
+        def collect_child_service_calls(node, service_calls)
+          node.children.grep(RuboCop::AST::Node).each { |child| service_calls_under(child, service_calls) }
+          service_calls
+        end
+
+        def service_call_for(node)
+          return unless node.type == :send
+
+          pattern = ServiceCallPattern.new(node).match
+          return unless pattern
+
+          ServiceCall.new(service_name: pattern.service_name, path: path, line: node.loc.expression.line,
+                          expression: first_line(node), style: pattern.style)
+        end
+
+        def constant_receiver?(node)
+          node&.type == :const
+        end
+
+        def constant_name(node)
+          node.source if constant_receiver?(node)
+        end
+
+        def optional_name(name)
+          name unless name.empty?
+        end
+
+        def first_line(node)
+          node.loc.expression.source.lines.first.strip
+        end
+      end
+    end
+  end
+end