metz-scan 0.5.3

data/lib/metz_scan/analyzers/package_dependency_pressure.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "../project_index"
+require_relative "package_dependency_pressure/finding"
+require_relative "package_dependency_pressure/metadata"
+require_relative "package_dependency_pressure/package_map"
+require_relative "package_dependency_pressure/reference_collector"
+require_relative "package_dependency_pressure/reference_set"
+require_relative "package_dependency_pressure/shared_dependency_triage"
+require_relative "project_analyzer_triage"
+
+module MetzScan
+  module Analyzers
+    # Reports declarations referenced from several files outside their package.
+    class PackageDependencyPressure
+      include ProjectAnalyzerTriage
+
+      RULE_ID = "MetzProject/PackageDependencyPressure"
+      PROJECT_ANALYZER_STATUS = "candidate"
+      CONFIDENCE = "medium"
+      TRIAGE_SEVERITY = "manual review"
+      TRIAGE_SUMMARY = "Candidate package-boundary signal; review cross-package reference pressure in context."
+      WHY = "Cross-package reference pressure can reveal boundaries that many parts of the system depend on."
+      SUGGESTED_NEXT_MOVES = [
+        "Review whether callers need the full declaration or a narrower interface.",
+        "Look for package-specific workflows that could own repeated dependency edges."
+      ].freeze
+      IGNORED_DECLARATION_NAMES = %w[BasicObject Class Kernel Module Object].freeze
+      SYNTHETIC_DECLARATION_MARKER = "::<"
+      SUPPORTED_KINDS = [nil, :class, :module].freeze
+      private_constant :IGNORED_DECLARATION_NAMES, :SYNTHETIC_DECLARATION_MARKER, :SUPPORTED_KINDS
+
+      def initialize(paths: nil, index: nil, minimum_referring_files: 12, minimum_referring_packages: 5)
+        @paths = Array(paths)
+        @index = index || ProjectIndex.build(@paths)
+        @reference_collector = ReferenceCollector.new(@index)
+        @minimum_referring_files = minimum_referring_files
+        @minimum_referring_packages = minimum_referring_packages
+      end
+
+      def call
+        return [] unless index.available?
+
+        declarations.filter_map { |declaration| finding_for(declaration) }
+      end
+
+      private
+
+      attr_reader :index, :reference_collector, :minimum_referring_files, :minimum_referring_packages
+
+      def declarations
+        index.declarations.select { |declaration| declaration_candidate?(declaration) }
+                          .sort_by { |declaration| declaration.name.to_s }
+      end
+
+      def declaration_candidate?(declaration)
+        declaration.name&.include?("::") && declaration.path && supported_kind?(declaration) &&
+          !ignored_declaration_name?(declaration.name) && !PackageMap.ignored_path?(declaration.path) &&
+          PackageMap.package_for(declaration.path)
+      end
+
+      def supported_kind?(declaration)
+        !declaration.respond_to?(:kind) || SUPPORTED_KINDS.include?(declaration.kind)
+      end
+
+      def finding_for(declaration)
+        reference_set = ReferenceSet.new(reference_collector.for(declaration))
+        return unless reference_set.enough?(minimum_referring_files, minimum_referring_packages)
+
+        Finding.new(finding_attributes(declaration, reference_set))
+      end
+
+      def finding_attributes(declaration, reference_set)
+        core_finding_attributes(declaration, reference_set)
+          .merge(triage_attributes_for(declaration),
+                 project_analyzer_metadata: metadata_for(declaration, reference_set))
+      end
+
+      def core_finding_attributes(declaration, reference_set)
+        declared_package = PackageMap.package_for(declaration.path)
+        core_identity_attributes(declaration, reference_set, declared_package)
+          .merge(core_context_attributes(declaration, reference_set))
+      end
+
+      def core_identity_attributes(declaration, reference_set, declared_package)
+        { source: source_name, rule_id: RULE_ID,
+          message: message_for(declaration, reference_set, declared_package),
+          declaration_name: declaration.name, declared_package: declared_package }
+      end
+
+      def core_context_attributes(declaration, reference_set)
+        { referring_files: reference_set.files,
+          referring_packages: reference_set.packages,
+          references: reference_set.references,
+          primary_location: Location.new(name: declaration.name, path: declaration.path),
+          why_it_matters: why_for(declaration), suggested_next_moves: suggested_next_moves_for(declaration) }
+      end
+
+      def message_for(declaration, reference_set, declared_package)
+        "#{declaration.name} is referenced from #{reference_set.files.size} files across " \
+          "#{reference_set.packages.size} packages outside #{declared_package}; " \
+          "review whether this boundary is carrying too much dependency pressure."
+      end
+
+      def metadata_for(declaration, reference_set)
+        Metadata.for(declaration, reference_set, dependency_pressure_category_for(declaration))
+      end
+
+      def ignored_declaration_name?(name)
+        IGNORED_DECLARATION_NAMES.include?(name) || name.include?(SYNTHETIC_DECLARATION_MARKER)
+      end
+
+      def triage_attributes_for(declaration)
+        return SharedDependencyTriage.attributes(PROJECT_ANALYZER_STATUS) if shared_dependency?(declaration)
+
+        project_analyzer_triage_attributes
+      end
+
+      def why_for(declaration)
+        shared_dependency?(declaration) ? SharedDependencyTriage::WHY : WHY
+      end
+
+      def suggested_next_moves_for(declaration)
+        shared_dependency?(declaration) ? SharedDependencyTriage::SUGGESTED_NEXT_MOVES : SUGGESTED_NEXT_MOVES
+      end
+
+      def dependency_pressure_category_for(declaration)
+        shared_dependency?(declaration) ? SharedDependencyTriage::CATEGORY : "package_boundary"
+      end
+
+      def shared_dependency?(declaration)
+        SharedDependencyTriage.shared?(declaration)
+      end
+
+      Reference = Struct.new(:path, :line, :column, :package, keyword_init: true)
+      private_constant :Reference
+    end
+  end
+end

data/lib/metz_scan/analyzers/package_map.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    # Classifies coarse project packages used by index-backed project analyzers.
+    module PackageMap
+      IGNORED_REFERENCE_ROOTS = %w[spec test].freeze
+      IGNORED_LIB_PACKAGES = %w[generators seed_data seeders tasks test_data].freeze
+      IGNORED_SUPPORT_SEGMENTS = %w[seeds testing_support].freeze
+      private_constant :IGNORED_REFERENCE_ROOTS, :IGNORED_LIB_PACKAGES, :IGNORED_SUPPORT_SEGMENTS
+
+      module_function
+
+      def package_for(path)
+        parts = path.to_s.split(File::SEPARATOR)
+        return package_after(parts, app_index(parts)) if app_index(parts)
+        return package_after(parts, lib_index(parts)) if lib_index(parts)
+
+        nil
+      end
+
+      def ignored_path?(path)
+        parts = path.to_s.split(File::SEPARATOR)
+        ignored_reference_root?(parts) || ignored_lib_package?(parts) || ignored_support_segment?(parts)
+      end
+
+      def parts_after_package(path)
+        parts = path.to_s.split(File::SEPARATOR)
+        index = app_index(parts) || lib_index(parts)
+        return [] unless index
+
+        parts[(index + 2)..] || []
+      end
+
+      def package_parts(path)
+        package_for(path).to_s.split("/")
+      end
+
+      def package_after(parts, index)
+        return unless parts[index + 1]
+
+        "#{parts[index]}/#{parts[index + 1]}"
+      end
+
+      def ignored_reference_root?(parts)
+        index = project_root_index(parts)
+        index && IGNORED_REFERENCE_ROOTS.include?(parts[index])
+      end
+
+      def ignored_lib_package?(parts)
+        index = project_root_index(parts)
+        return false unless index && parts[index] == "lib"
+
+        index && IGNORED_LIB_PACKAGES.include?(parts[index + 1])
+      end
+
+      def ignored_support_segment?(parts)
+        index = app_index(parts) || lib_index(parts)
+        return false unless index
+
+        parts[(index + 1)..].any? { |part| IGNORED_SUPPORT_SEGMENTS.include?(part) }
+      end
+
+      def app_index(parts)
+        parts.rindex("app")
+      end
+
+      def lib_index(parts)
+        parts.rindex("lib")
+      end
+
+      def project_root_index(parts)
+        parts.each_index.reverse_each.find { |index| project_root?(parts[index]) }
+      end
+
+      def project_root?(part)
+        part == "app" || part == "lib" || IGNORED_REFERENCE_ROOTS.include?(part)
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/project_analyzer_triage.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    module ProjectAnalyzerTriage
+      private
+
+      def project_analyzer_triage_attributes
+        { project_analyzer_status: self.class::PROJECT_ANALYZER_STATUS,
+          confidence: self.class::CONFIDENCE,
+          triage_severity: self.class::TRIAGE_SEVERITY,
+          triage_summary: self.class::TRIAGE_SUMMARY }
+      end
+
+      def source_name
+        index ? index.backend_name.to_s : "paths"
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/repeated_branching/branch_site_collector.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+require_relative "branch_value"
+require_relative "../contextual_node_walker"
+require_relative "predicate_chain"
+
+module MetzScan
+  module Analyzers
+    class RepeatedBranching
+      class BranchSiteCollector
+        BranchSite = Struct.new(:signature, :kind, :decision, :branch_values, :enclosing_name, :method_name,
+                                :path, :line, :expression, keyword_init: true)
+        SiteDraft = Struct.new(:kind, :decision, :branch_conditions, :branch_values, :contextual_node,
+                               keyword_init: true)
+
+        def initialize(path)
+          @path = path
+        end
+
+        def call
+          return [] unless File.file?(path)
+
+          contextual_nodes.filter_map { |contextual_node| branch_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
+          MetzScan::Analyzers::ContextualNodeWalker.new(processed_source.ast).nodes
+        end
+
+        def case_branch?(node)
+          node.type == :case && node.children.first
+        end
+
+        def root_if_branch?(node)
+          node.type == :if && node.loc.respond_to?(:keyword) && node.loc.keyword.source == "if"
+        end
+
+        def branch_site_for(contextual_node)
+          node = contextual_node.node
+          return case_site(contextual_node) if case_branch?(node)
+          return if_site(contextual_node) if root_if_branch?(node)
+
+          nil
+        end
+
+        def case_site(contextual_node)
+          node = contextual_node.node
+          decision = node.children.first.source
+          values = case_values(node)
+          build_site(:case, decision, values, contextual_node)
+        end
+
+        def case_values(node)
+          values = node.children.grep(RuboCop::AST::WhenNode).flat_map { |when_node| when_values(when_node) }
+          values.uniq(&:signature).sort_by { |value| [value.text, value.signature] }
+        end
+
+        def when_values(when_node)
+          when_node.conditions.map { |condition| condition_value(condition) }
+        end
+
+        def condition_value(condition)
+          BranchValue.for(condition)
+        end
+
+        def if_site(contextual_node)
+          predicate_chain = PredicateChain.new(contextual_node.node).call
+          return unless predicate_chain
+
+          build_site(:if, predicate_chain.decision, predicate_chain.branch_values, contextual_node)
+        end
+
+        def build_site(kind, decision, values, contextual_node)
+          draft = site_draft(kind, decision, values, contextual_node)
+          return if draft.branch_values.empty?
+
+          BranchSite.new(site_attributes(draft))
+        end
+
+        def site_draft(kind, decision, values, contextual_node)
+          SiteDraft.new(kind: kind, decision: decision, branch_conditions: values,
+                        branch_values: branch_values_for(values), contextual_node: contextual_node)
+        end
+
+        def site_attributes(draft)
+          context_attributes(draft.contextual_node).merge(site_signature_attributes(draft))
+                                                   .merge(site_location_attributes(draft))
+        end
+
+        def signature_for_draft(draft)
+          signature_for(draft.kind, draft.decision, signatures_for(draft.branch_conditions))
+        end
+
+        def site_signature_attributes(draft)
+          { signature: signature_for_draft(draft), kind: draft.kind,
+            decision: draft.decision, branch_values: draft.branch_values }
+        end
+
+        def site_location_attributes(draft)
+          node = draft.contextual_node.node
+          { path: path, line: node.loc.expression.line, expression: first_line(node) }
+        end
+
+        def context_attributes(contextual_node)
+          { enclosing_name: contextual_node.enclosing_name, method_name: contextual_node.method_name }
+        end
+
+        def branch_values_for(values)
+          values.map { |value| value.respond_to?(:text) ? value.text : value }
+        end
+
+        def signatures_for(values)
+          values.map { |value| value.respond_to?(:signature) ? value.signature : value }
+        end
+
+        def signature_for(kind, decision, values)
+          [kind, decision, values].join(":")
+        end
+
+        def first_line(node)
+          node.loc.expression.source.lines.first.strip
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/repeated_branching/branch_value.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class RepeatedBranching
+      class BranchValue
+        def self.for(condition)
+          return literal(condition) if condition.respond_to?(:value)
+
+          new(condition.source, "source:#{condition.source}")
+        end
+
+        def self.literal(condition)
+          text = condition.type == :sym ? ":#{condition.value}" : condition.value.to_s
+          new(text, "#{condition.type}:#{condition.value.inspect}")
+        end
+
+        def initialize(text, signature)
+          @text = text
+          @signature = signature
+        end
+
+        attr_reader :text, :signature
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/repeated_branching/contextual_node_walker.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "../contextual_node_walker"
+
+module MetzScan
+  module Analyzers
+    class RepeatedBranching
+      ContextualNodeWalker = MetzScan::Analyzers::ContextualNodeWalker
+    end
+  end
+end

data/lib/metz_scan/analyzers/repeated_branching/decision_subject.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class RepeatedBranching
+      class DecisionSubject
+        GENERIC_SUBJECTS = %w[action key.to_s type value value.to_s].freeze
+        SIMPLE_IDENTIFIER = /\A@?[a-z_]\w*(?:\.[a-z_]\w*)?\z/
+        private_constant :GENERIC_SUBJECTS, :SIMPLE_IDENTIFIER
+
+        def self.for(decision)
+          new(decision)
+        end
+
+        def initialize(decision)
+          @decision = decision
+        end
+
+        attr_reader :decision
+
+        def generic?
+          kind == "generic"
+        end
+
+        def kind
+          return "generic" if GENERIC_SUBJECTS.include?(decision)
+          return "state" if SIMPLE_IDENTIFIER.match?(decision)
+
+          "expression"
+        end
+
+        def label
+          { "generic" => "generic branch subject",
+            "state" => "state branch subject",
+            "expression" => "expression subject" }.fetch(kind)
+        end
+
+        def summary
+          { "generic" => "Generic subject; use reported contexts before treating this as design pressure.",
+            "state" => "State-like subject; repeated branch tables may describe a shared domain decision.",
+            "expression" => "Expression subject; repeated computed conditions may deserve extraction." }.fetch(kind)
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/repeated_branching/predicate_chain.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class RepeatedBranching
+      class PredicateChain
+        Result = Struct.new(:decision, :branch_values, keyword_init: true)
+        Predicate = Struct.new(:receiver, :method_name, keyword_init: true)
+
+        def initialize(node)
+          @node = node
+        end
+
+        def call
+          predicates = predicate_chain
+          return unless same_receiver_chain?(predicates)
+
+          Result.new(decision: predicates.first.receiver, branch_values: predicate_values(predicates))
+        end
+
+        private
+
+        attr_reader :node
+
+        def predicate_chain
+          if_chain.map { |if_node| predicate_for(if_node.children.first) }
+        end
+
+        def if_chain
+          chain = []
+          chain_if_nodes(node, chain)
+          chain
+        end
+
+        def chain_if_nodes(node, chain)
+          return unless node&.type == :if
+
+          chain << node
+          chain_if_nodes(node.children[2], chain)
+        end
+
+        def predicate_for(node)
+          return unless node&.type == :send && node.receiver && node.method_name.to_s.end_with?("?")
+
+          Predicate.new(receiver: node.receiver.source, method_name: node.method_name.to_s)
+        end
+
+        def same_receiver_chain?(predicates)
+          predicates.size > 1 && predicates.all? && predicates.map(&:receiver).uniq.one?
+        end
+
+        def predicate_values(predicates)
+          predicates.map(&:method_name).uniq.sort
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class RepeatedBranching
+      module Triage
+        GENERIC_CONFIDENCE = "low"
+        GENERIC_TRIAGE_SEVERITY = "context required"
+        GENERIC_TRIAGE_SUMMARY = "Generic repeated-decision signal; use reported contexts and branch values before " \
+                                 "treating this as design pressure."
+        private_constant :GENERIC_CONFIDENCE, :GENERIC_TRIAGE_SEVERITY, :GENERIC_TRIAGE_SUMMARY
+
+        module_function
+
+        def attributes_for(subject, status:, fallback:)
+          return fallback unless subject.generic?
+
+          generic_subject_attributes(status)
+        end
+
+        def generic_subject_attributes(status)
+          { project_analyzer_status: status, confidence: GENERIC_CONFIDENCE,
+            triage_severity: GENERIC_TRIAGE_SEVERITY, triage_summary: GENERIC_TRIAGE_SUMMARY }
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/repeated_branching.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "../project_index"
+require_relative "occurrence"
+require_relative "project_analyzer_triage"
+require_relative "ruby_file_enumerator"
+require_relative "repeated_branching/branch_site_collector"
+require_relative "repeated_branching/decision_subject"
+require_relative "repeated_branching/triage"
+
+module MetzScan
+  module Analyzers
+    # Groups repeated case/if branching decisions across indexed Ruby files.
+    class RepeatedBranching
+      include ProjectAnalyzerTriage
+
+      RULE_ID = "MetzProject/RepeatedBranching"
+      PROJECT_ANALYZER_STATUS = "validated"
+      DEFAULT_OUTPUT_ELIGIBLE = true
+      CONFIDENCE = "medium"
+      TRIAGE_SEVERITY = "design pressure"
+      TRIAGE_SUMMARY = "Validated repeated-decision signal; review repeated decisions in context."
+      WHY = "Repeated branching spreads one domain decision across files and makes change ripple outward."
+      SUGGESTED_NEXT_MOVES = [
+        "Name the domain decision once and reuse it instead of repeating the same branch table.",
+        "Consider polymorphism, a strategy object, or a small lookup object when the branch represents type behavior."
+      ].freeze
+      Finding = Struct.new(:source, :rule_id, :message, :decision, :kind, :branch_values, :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: context_name(occurrence)) }
+        end
+
+        def context_name(occurrence)
+          [occurrence.enclosing_name, occurrence.method_name].compact.join.then { |name| name unless name.empty? }
+        end
+      end
+
+      def initialize(paths: nil, index: nil, minimum_occurrences: 2)
+        @paths = Array(paths)
+        @index = index
+        @minimum_occurrences = minimum_occurrences
+      end
+
+      def call
+        grouped_sites.filter_map { |_signature, sites| finding_for(sites) }
+      end
+
+      private
+
+      attr_reader :paths, :index, :minimum_occurrences
+
+      def grouped_sites
+        branch_sites.group_by(&:signature)
+      end
+
+      def branch_sites
+        ruby_files.flat_map { |path| BranchSiteCollector.new(path).call }
+      end
+
+      def ruby_files
+        RubyFileEnumerator.new(paths: paths, index: index).call
+      end
+
+      def finding_for(sites)
+        return if distinct_paths(sites).size < minimum_occurrences
+
+        first = sites.first
+        Finding.new(finding_attributes(first, sites))
+      end
+
+      def finding_attributes(first, sites)
+        subject = DecisionSubject.for(first.decision)
+        core_finding_attributes(first, sites, subject).merge(triage_attributes_for(first, sites, subject))
+      end
+
+      def triage_attributes_for(first, sites, subject)
+        subject_triage_attributes(subject).merge(
+          project_analyzer_metadata: project_analyzer_metadata_for(first, sites, subject),
+          why_it_matters: WHY, suggested_next_moves: SUGGESTED_NEXT_MOVES
+        )
+      end
+
+      def subject_triage_attributes(subject)
+        Triage.attributes_for(subject, status: PROJECT_ANALYZER_STATUS, fallback: project_analyzer_triage_attributes)
+      end
+
+      def core_finding_attributes(first, sites, subject)
+        { source: source_name, rule_id: RULE_ID, message: message_for(first, sites, subject),
+          decision: first.decision, kind: first.kind, branch_values: first.branch_values, occurrences: sites }
+      end
+
+      def distinct_paths(sites)
+        sites.map(&:path).uniq
+      end
+
+      def message_for(site, sites, subject)
+        "#{site.decision} (#{subject.label}) branches in #{distinct_paths(sites).size} files" \
+          "#{context_suffix(sites)}; " \
+          "consider consolidating the decision."
+      end
+
+      def context_suffix(sites)
+        names = context_names(sites)
+        return "" if names.empty?
+
+        ": #{names.join(', ')}"
+      end
+
+      def context_names(sites)
+        sites.filter_map { |site| context_name(site) }.uniq.sort
+      end
+
+      def context_name(site)
+        [site.enclosing_name, site.method_name].compact.join.then { |name| name unless name.empty? }
+      end
+
+      def project_analyzer_metadata_for(site, sites, subject)
+        { "decision" => site.decision, "kind" => site.kind.to_s,
+          "branch_values" => site.branch_values, "project_analyzer_category" => subject.kind,
+          "decision_subject_kind" => subject.kind,
+          "decision_subject_label" => subject.label, "decision_subject_summary" => subject.summary,
+          "occurrences" => sites.map { |occurrence| occurrence_metadata(occurrence) } }
+      end
+
+      def occurrence_metadata(site)
+        { "context" => context_name(site), "enclosing" => site.enclosing_name,
+          "method" => site.method_name, "path" => site.path, "line" => site.line,
+          "expression" => site.expression }.compact
+      end
+    end
+  end
+end