rubocop-metz 0.5.2

data/lib/metz_scan/analyzers/implicit_context_pressure.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "implicit_context_pressure/ambient_context_collector"
+require_relative "implicit_context_pressure/reference_set"
+require_relative "implicit_context_pressure/triage"
+require_relative "occurrence"
+require_relative "package_map"
+require_relative "project_analyzer_triage"
+require_relative "ruby_file_enumerator"
+
+module MetzScan
+  module Analyzers
+    # Reports repeated ambient CurrentAttributes-style context access.
+    class ImplicitContextPressure
+      include ProjectAnalyzerTriage
+      include Triage
+
+      RULE_ID = "MetzProject/ImplicitContextPressure"
+      PROJECT_ANALYZER_STATUS = "candidate"
+      CONFIDENCE = "medium"
+      TRIAGE_SEVERITY = "manual review"
+      TRIAGE_SUMMARY = "Candidate ambient context signal; review whether dependencies should be explicit."
+      WHY = "Ambient context hides dependencies from method signatures and makes workflows harder to reason about."
+      SUGGESTED_NEXT_MOVES = [
+        "Pass the context value explicitly into collaborators that use it.",
+        "Keep request-scoped globals at application boundaries when possible."
+      ].freeze
+      MINIMUM_FILES = 3
+      MINIMUM_PACKAGES = 2
+      Finding = Struct.new(:source, :rule_id, :message, :ambient_context, :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
+        ambient_references.group_by(&:ambient_context).filter_map do |ambient_context, references|
+          finding_for(ambient_context, references)
+        end
+      end
+
+      private
+
+      attr_reader :paths, :index, :minimum_files, :minimum_packages
+
+      def ambient_references
+        ruby_files.flat_map { |path| AmbientContextCollector.new(path).call }
+                  .reject { |reference| PackageMap.ignored_path?(reference.path) }
+                  .select { |reference| PackageMap.package_for(reference.path) }
+      end
+
+      def ruby_files = RubyFileEnumerator.new(paths: paths, index: index).call
+
+      def finding_for(ambient_context, references)
+        grouped = ReferenceSet.new(references)
+        return unless grouped.referring_files.size >= minimum_files
+        return unless grouped.referring_packages.size >= minimum_packages
+
+        Finding.new(finding_attributes(ambient_context, grouped))
+      end
+
+      def finding_attributes(ambient_context, grouped)
+        category = implicit_context_category_for(ambient_context, grouped)
+
+        finding_core_attributes(ambient_context, grouped, category)
+          .merge(project_analyzer_triage_attributes)
+          .merge(category_triage_attributes(category))
+      end
+
+      def finding_core_attributes(ambient_context, grouped, category)
+        finding_identity_attributes(ambient_context, grouped)
+          .merge(finding_reference_attributes(ambient_context, grouped, category))
+      end
+
+      def finding_identity_attributes(ambient_context, grouped)
+        { source: source_name, rule_id: RULE_ID, message: message_for(ambient_context, grouped),
+          ambient_context: ambient_context }
+      end
+
+      def finding_reference_attributes(ambient_context, grouped, category)
+        { referring_files: grouped.referring_files, referring_packages: grouped.referring_packages,
+          occurrences: grouped.references,
+          project_analyzer_metadata: project_analyzer_metadata_for(ambient_context, grouped, category) }
+      end
+
+      def message_for(ambient_context, grouped)
+        "#{ambient_context} is #{access_phrase(grouped)} from #{grouped.referring_files.size} files across " \
+          "#{grouped.referring_packages.size} packages; consider passing context explicitly."
+      end
+
+      def project_analyzer_metadata_for(ambient_context, grouped, category)
+        implicit_context_metadata(ambient_context, grouped, category).merge(grouped_metadata(grouped))
+      end
+
+      def implicit_context_metadata(ambient_context, grouped, category)
+        { "project_analyzer_category" => category,
+          "implicit_context_category" => category, "ambient_context" => ambient_context,
+          "ambient_context_kind" => grouped.context_kind }
+          .merge(context_specific_metadata(ambient_context, grouped))
+      end
+
+      def context_specific_metadata(ambient_context, grouped)
+        return thread_current_metadata(grouped) if grouped.context_kind == "thread_current"
+
+        { "current_receiver_scope" => current_receiver_scope_for(ambient_context),
+          "current_attribute" => current_attribute_for(ambient_context) }
+      end
+
+      def thread_current_metadata(grouped)
+        { "thread_current_key" => grouped.context_key }
+      end
+
+      def grouped_metadata(grouped)
+        { "access_modes" => grouped.access_modes, "referring_files" => grouped.referring_files,
+          "referring_packages" => grouped.referring_packages, "occurrences" => occurrences_metadata(grouped) }
+      end
+
+      def occurrences_metadata(grouped)
+        grouped.references.map { |reference| reference_metadata(reference) }
+      end
+
+      def reference_metadata(reference)
+        { "path" => reference.path, "line" => reference.line, "context" => reference.context,
+          "expression" => reference.expression, "access_mode" => reference.access_mode }.compact
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class InheritanceDescendants
+      Finding = Struct.new(:source, :rule_id, :message, :base_name, :descendants, :locations, :primary_location,
+                           :why_it_matters, :project_analyzer_status, :confidence, :triage_severity, :triage_summary,
+                           :project_analyzer_metadata, :suggested_next_moves, keyword_init: true) do
+        def occurrences = [primary_location].compact
+
+        def report_occurrences
+          occurrences.map { |occurrence| Occurrence.from(occurrence, context: base_name) }
+        end
+      end
+      Location = Struct.new(:name, :path, keyword_init: true)
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class InheritanceDescendants
+      module Metadata
+        module_function
+
+        def for(base_name, descendants, descendant_locations, context)
+          { "base_name" => base_name, "descendants" => descendants,
+            "descendant_count" => descendants.size,
+            "descendant_locations" => location_metadata(descendant_locations),
+            "project_analyzer_category" => context.fetch(:root_kind),
+            "root_kind" => context.fetch(:root_kind), "source" => context.fetch(:source) }.compact
+        end
+
+        def location_metadata(locations)
+          locations.map { |location| { "name" => location.name, "path" => location.path } }
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/inheritance_descendants/root_kind.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class InheritanceDescendants
+      module RootKind
+        FRAMEWORK_ROOT_NAMESPACES = %w[
+          ActionCable
+          ActionController
+          ActionMailer
+          ActionView
+          ActiveJob
+          ActiveModel
+          ActiveRecord
+          Rails
+          ViteRails
+        ].freeze
+        RAILS_APPLICATION_BASES = %w[ApplicationController ApplicationJob ApplicationMailer ApplicationRecord].freeze
+        RULES = [
+          ["framework root", lambda { |name|
+            FRAMEWORK_ROOT_NAMESPACES.any? { |namespace| name.start_with?("#{namespace}::") }
+          }],
+          ["rails application base", ->(name) { RAILS_APPLICATION_BASES.include?(name) }],
+          ["application job base", lambda { |name|
+            name == "Jobs::Base" || name == "Jobs::Scheduled" || name.start_with?("Jobs::") ||
+              name.end_with?("Job") || name.end_with?("::BaseJob")
+          }],
+          ["application service base", lambda { |name|
+            name == "BaseService" || name.start_with?("Service::") || name.end_with?("::BaseService") ||
+              name.match?(/Base.*Service/) || name.match?(/Service.*Base/)
+          }],
+          ["controller base", ->(name) { name.end_with?("Controller") }],
+          ["serializer base", ->(name) { name.end_with?("Serializer") }],
+          ["policy base", ->(name) { name.end_with?("Policy") }],
+          ["worker base", ->(name) { name.end_with?("Worker") }],
+          ["exception base", lambda { |name|
+            name.end_with?("Error") || name.end_with?("Exception") || name.include?("Exception")
+          }],
+          ["cli base", ->(name) { name.end_with?("CLI::Base") }],
+          ["abstract base", lambda { |name|
+            name.include?("::Base::") || base_token?(name.split("::").last)
+          }]
+        ].freeze
+        private_constant :FRAMEWORK_ROOT_NAMESPACES, :RAILS_APPLICATION_BASES, :RULES
+
+        module_function
+
+        def for(base_name)
+          RULES.find { |_label, matcher| matcher.call(base_name) }&.first
+        end
+
+        def base_token?(name)
+          name == "Base" || name.start_with?("Base") || name.end_with?("Base")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class InheritanceDescendants
+      module Triage
+        BROAD_ROOT_CONFIDENCE = "low"
+        BROAD_ROOT_TRIAGE_SEVERITY = "broad base"
+        BROAD_ROOT_TRIAGE_SUMMARY = "Broad inheritance base; review only when shared behavior changes often " \
+                                    "or descendants diverge."
+
+        module_function
+
+        def attributes_for(root_kind)
+          root_kind ? broad_root_attributes : candidate_attributes
+        end
+
+        def candidate_attributes
+          { project_analyzer_status: PROJECT_ANALYZER_STATUS, confidence: CONFIDENCE,
+            triage_severity: TRIAGE_SEVERITY, triage_summary: TRIAGE_SUMMARY }
+        end
+
+        def broad_root_attributes
+          { project_analyzer_status: PROJECT_ANALYZER_STATUS, confidence: BROAD_ROOT_CONFIDENCE,
+            triage_severity: BROAD_ROOT_TRIAGE_SEVERITY, triage_summary: BROAD_ROOT_TRIAGE_SUMMARY }
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/inheritance_descendants.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "../project_index"
+require_relative "inheritance_descendants/finding"
+require_relative "inheritance_descendants/metadata"
+require_relative "inheritance_descendants/root_kind"
+require_relative "inheritance_descendants/triage"
+require_relative "occurrence"
+
+module MetzScan
+  module Analyzers
+    # Reports configured inheritance roots with enough known descendants.
+    class InheritanceDescendants
+      RULE_ID = "MetzProject/DeepInheritanceTree"
+      PROJECT_ANALYZER_STATUS = "validated"
+      CONFIDENCE = "medium"
+      TRIAGE_SEVERITY = "manual review"
+      TRIAGE_SUMMARY = "Validated inheritance signal; review broad base classes and descendant spread in context."
+      WHY = "Large inheritance trees hide coupling and make changes expensive."
+      SUGGESTED_NEXT_MOVES = [
+        "Review whether the base class is carrying multiple responsibilities.",
+        "Prefer composition or narrower shared modules when descendants only need part of the base behavior."
+      ].freeze
+      IGNORED_DECLARATION_NAMES = %w[BasicObject Class Kernel Module Object].freeze
+      SYNTHETIC_DECLARATION_MARKER = "::<"
+      private_constant :IGNORED_DECLARATION_NAMES, :SYNTHETIC_DECLARATION_MARKER
+
+      def initialize(paths: nil, index: nil, base_names: nil, minimum_descendants: 3)
+        @paths = Array(paths)
+        @index = index || ProjectIndex.build(@paths)
+        @base_names = Array(base_names).compact
+        @minimum_descendants = minimum_descendants
+      end
+
+      def call
+        return [] unless index.available?
+
+        base_candidates.filter_map { |base_name| finding_for(base_name) }
+      end
+
+      private
+
+      attr_reader :index, :base_names, :minimum_descendants
+
+      def base_candidates
+        return base_names unless base_names.empty?
+
+        auto_discovered_base_candidates
+      end
+
+      def auto_discovered_base_candidates
+        index.declarations.select { |declaration| auto_discovered_base_candidate?(declaration) }
+                          .map(&:name).compact.uniq.sort
+      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 finding_for(base_name)
+        descendants = sorted_descendants(base_name)
+        return if descendants.size < minimum_descendants
+
+        build_finding(base_name, descendants)
+      end
+
+      def sorted_descendants(base_name)
+        index.descendants_of(base_name).reject { |name| ignored_declaration_name?(name) }.sort
+      end
+
+      def build_finding(base_name, descendants)
+        descendant_locations = locations_for(descendants)
+        Finding.new(finding_attributes(base_name, descendants, descendant_locations))
+      end
+
+      def finding_attributes(base_name, descendants, descendant_locations)
+        root_kind = RootKind.for(base_name)
+        core_finding_attributes(base_name, descendants, descendant_locations, root_kind)
+          .merge(triage_for(base_name, descendants, descendant_locations, root_kind))
+      end
+
+      def core_finding_attributes(base_name, descendants, descendant_locations, root_kind)
+        { source: index.backend_name.to_s, rule_id: RULE_ID, message: message_for(base_name, descendants, root_kind),
+          base_name: base_name, descendants: descendants, locations: descendant_locations,
+          primary_location: primary_location_for(base_name, descendant_locations), why_it_matters: WHY,
+          suggested_next_moves: SUGGESTED_NEXT_MOVES }
+      end
+
+      def triage_for(base_name, descendants, descendant_locations, root_kind)
+        Triage.attributes_for(root_kind).merge(
+          project_analyzer_metadata: project_analyzer_metadata_for(base_name, descendants, descendant_locations,
+                                                                   root_kind)
+        )
+      end
+
+      def message_for(base_name, descendants, root_kind)
+        label = root_kind ? " (#{root_kind})" : ""
+        "#{base_name}#{label} has #{descendants.size} descendants; " \
+          "consider whether shared behavior is becoming too broad."
+      end
+
+      def locations_for(descendants)
+        descendants.filter_map { |name| location_for(name) }
+      end
+
+      def primary_location_for(base_name, descendant_locations)
+        location_for(base_name) || descendant_locations.first
+      end
+
+      def project_analyzer_metadata_for(base_name, descendants, descendant_locations, root_kind)
+        Metadata.for(base_name, descendants, descendant_locations, metadata_context(root_kind))
+      end
+
+      def metadata_context(root_kind)
+        { root_kind: root_kind, source: index.backend_name.to_s }
+      end
+
+      def location_for(name)
+        declaration = declarations_by_name[name]
+        Location.new(name: name, path: declaration.path) if declaration&.path
+      end
+
+      def declarations_by_name
+        @declarations_by_name ||= index.declarations.to_h { |declaration| [declaration.name, declaration] }
+      end
+
+      def ignored_declaration_name?(name)
+        IGNORED_DECLARATION_NAMES.include?(name) || name.include?(SYNTHETIC_DECLARATION_MARKER)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../occurrence"
+
+module MetzScan
+  module Analyzers
+    class NamespaceLeakPressure
+      Finding = Struct.new(:source, :rule_id, :message, :declaration_name, :home_namespace,
+                           :declared_package, :referring_files, :referring_packages, :references,
+                           :primary_location, :why_it_matters, :project_analyzer_status, :confidence,
+                           :triage_severity, :triage_summary, :project_analyzer_metadata,
+                           :suggested_next_moves, keyword_init: true) do
+        def report_occurrences
+          [Occurrence.from(primary_location, context: declaration_name)].compact
+        end
+      end
+      Location = Struct.new(:name, :path, keyword_init: true)
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../cross_package_reference_metadata"
+
+module MetzScan
+  module Analyzers
+    class NamespaceLeakPressure
+      module Metadata
+        module_function
+
+        def for(declaration, reference_set, namespace_leak_category)
+          CrossPackageReferenceMetadata.counts(reference_set).merge(
+            namespace_metadata(declaration, reference_set, namespace_leak_category)
+          )
+        end
+
+        def namespace_metadata(declaration, reference_set, namespace_leak_category)
+          base_namespace_metadata(declaration)
+            .merge(category_metadata(namespace_leak_category))
+            .merge(references_metadata(reference_set))
+        end
+
+        def base_namespace_metadata(declaration)
+          { "declaration" => CrossPackageReferenceMetadata.declaration_metadata(declaration),
+            "home_namespace" => Namespace.new(declaration.name).home_name,
+            "declared_package" => PackageMap.package_for(declaration.path) }
+        end
+
+        def category_metadata(namespace_leak_category)
+          { "project_analyzer_category" => namespace_leak_category,
+            "namespace_leak_category" => namespace_leak_category }
+        end
+
+        def references_metadata(reference_set)
+          { "references" => CrossPackageReferenceMetadata.references_metadata(reference_set) }
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/namespace_leak_pressure/namespace.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class NamespaceLeakPressure
+      class Namespace
+        def initialize(name)
+          @segments = name.to_s.split("::")
+        end
+
+        attr_reader :segments
+
+        def deep?
+          segments.size >= 3
+        end
+
+        def home_name
+          home_segments.join("::")
+        end
+
+        def home_path_parts
+          home_segments.map { |part| underscore(part) }
+        end
+
+        private
+
+        def home_segments
+          segments[0...-1]
+        end
+
+        def underscore(value)
+          value.to_s
+               .gsub(/([A-Z]+)([A-Z][a-z])/, "\\1_\\2")
+               .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
+               .tr("-", "_")
+               .downcase
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/namespace_leak_pressure/reference_collector.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class NamespaceLeakPressure
+      class ReferenceCollector
+        def initialize(index)
+          @index = index
+        end
+
+        def for(declaration)
+          home_namespace_parts = Namespace.new(declaration.name).home_path_parts
+          index.constant_references_to(declaration.name).filter_map do |reference|
+            counted_reference_for(reference, declaration.path, home_namespace_parts)
+          end
+        end
+
+        private
+
+        attr_reader :index
+
+        def counted_reference_for(reference, declaration_path, home_namespace_parts)
+          return unless counted_reference?(reference, declaration_path, home_namespace_parts)
+
+          package = PackageMap.package_for(reference.path)
+          return unless package
+
+          Reference.new(path: reference.path, line: reference.line, column: reference.column, package: package)
+        end
+
+        def counted_reference?(reference, declaration_path, home_namespace_parts)
+          !same_path?(reference.path, declaration_path) &&
+            !PackageMap.ignored_path?(reference.path) &&
+            !inside_home_namespace?(reference.path, home_namespace_parts)
+        end
+
+        def inside_home_namespace?(path, home_namespace_parts)
+          PackageMap.parts_after_package(path).first(home_namespace_parts.size) == home_namespace_parts
+        end
+
+        def same_path?(left, right)
+          File.expand_path(left) == File.expand_path(right)
+        end
+
+        Reference = Struct.new(:path, :line, :column, :package, keyword_init: true)
+        private_constant :Reference
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/namespace_leak_pressure/reference_set.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../cross_package_reference_set"
+
+module MetzScan
+  module Analyzers
+    class NamespaceLeakPressure
+      class ReferenceSet < CrossPackageReferenceSet
+      end
+    end
+  end
+end