metz-scan 0.5.3

data/lib/metz_scan/analyzers/namespace_leak_pressure/shared_namespace_triage/exception_declaration.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module MetzScan
+  module Analyzers
+    class NamespaceLeakPressure
+      module SharedNamespaceTriage
+        class ExceptionDeclaration
+          ERROR_SUFFIX_PATTERN = /(?:Error|Exception)\z/
+          EXCEPTION_FAMILY_SEGMENT_PATTERN = /(?:Errors?|Exceptions?)\z/i
+          STANDARD_EXCEPTION_ROOTS = %w[Exception RuntimeError StandardError].freeze
+          private_constant :ERROR_SUFFIX_PATTERN, :EXCEPTION_FAMILY_SEGMENT_PATTERN, :STANDARD_EXCEPTION_ROOTS
+
+          def self.exception?(declaration)
+            new(declaration).exception?
+          end
+
+          def initialize(declaration)
+            @declaration = declaration
+          end
+
+          def exception?
+            return false unless declaration.path && File.file?(declaration.path)
+
+            exception_node?(processed_source.ast, declaration.name.to_s)
+          rescue Parser::SyntaxError, SystemCallError
+            false
+          end
+
+          private
+
+          attr_reader :declaration
+
+          def processed_source
+            RuboCop::ProcessedSource.new(File.read(declaration.path), RUBY_VERSION.to_f)
+          end
+
+          def exception_node?(node, name, namespace = [])
+            return false unless node
+            return module_exception?(node, name, namespace) if node.type == :module
+            return class_exception?(node, name, namespace) if node.type == :class
+            return assignment_exception?(node, name, namespace) if node.type == :casgn
+
+            child_exception?(node, name, namespace)
+          end
+
+          def module_exception?(node, name, namespace)
+            exception_node?(node.children.last, name, namespace_for(node.children.first, namespace))
+          end
+
+          def class_exception?(node, name, namespace)
+            name_node, superclass_node, body = node.children
+            return true if constant_name(name_node, namespace) == name && exception_name?(superclass_node&.source)
+
+            exception_node?(body, name, namespace_for(name_node, namespace))
+          end
+
+          def assignment_exception?(node, name, namespace)
+            assignment_name(node, namespace) == name && class_new_exception?(node.children[2])
+          end
+
+          def child_exception?(node, name, namespace)
+            node.children.grep(RuboCop::AST::Node).any? { |child| exception_node?(child, name, namespace) }
+          end
+
+          def namespace_for(name_node, namespace)
+            namespace + constant_segments(name_node)
+          end
+
+          def constant_name(name_node, namespace)
+            segments = constant_segments(name_node)
+            return segments.join("::") if qualified_constant?(name_node)
+
+            (namespace + segments).join("::")
+          end
+
+          def assignment_name(node, namespace)
+            scope_node, constant_name = node.children
+            return (namespace + [constant_name.to_s]).join("::") unless scope_node
+
+            (constant_segments(scope_node) + [constant_name.to_s]).join("::")
+          end
+
+          def class_new_exception?(node)
+            return false unless node&.type == :send
+            return false unless node.receiver&.source == "Class" && node.method_name == :new
+
+            exception_name?(node.arguments.first&.source)
+          end
+
+          def exception_name?(name)
+            segments = name.to_s.split("::")
+            STANDARD_EXCEPTION_ROOTS.include?(segments.last) || error_tail?(segments.last) ||
+              segments.any? { |segment| exception_family_segment?(segment) }
+          end
+
+          def constant_segments(node)
+            node&.source.to_s.sub(/\A::/, "").split("::").reject(&:empty?)
+          end
+
+          def qualified_constant?(node)
+            node&.source.to_s.include?("::")
+          end
+
+          def error_tail?(segment)
+            segment.to_s.match?(ERROR_SUFFIX_PATTERN)
+          end
+
+          def exception_family_segment?(segment)
+            segment.to_s.match?(EXCEPTION_FAMILY_SEGMENT_PATTERN)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "shared_namespace_triage/exception_declaration"
+
+module MetzScan
+  module Analyzers
+    class NamespaceLeakPressure
+      module SharedNamespaceTriage
+        CATEGORY = "shared_namespace"
+        CONFIDENCE = "low"
+        TRIAGE_SEVERITY = "shared namespace"
+        TRIAGE_SUMMARY = "Shared namespace signal; review public constants and extension points only when " \
+                         "they make app code depend on namespace internals."
+        WHY = "Public constants, error families, and framework extension namespaces are often intentional APIs."
+        SUGGESTED_NEXT_MOVES = [
+          "Leave stable public constants alone when the namespace is the intended API.",
+          "Introduce a narrower public object only when callers repeat namespace-specific knowledge."
+        ].freeze
+        SHARED_SEGMENT_PATTERN =
+          /\A(?:Config|Settings?|Core|Events?|Types?|VERSION|DefaultsProvider|RedisKeys|Registr(?:y|ies)|Errors?|
+              Exceptions?)\z/ix
+        EXCEPTION_FAMILY_SEGMENT_PATTERN = /(?:Errors?|Exceptions?)\z/i
+        ERROR_SUFFIX_PATTERN = /(?:Error|Exception)\z/
+        FRAMEWORK_NAMESPACE_PATTERN = /\A(?:I18n::Backend|Spree::Core)\b/
+        private_constant :SHARED_SEGMENT_PATTERN, :EXCEPTION_FAMILY_SEGMENT_PATTERN, :ERROR_SUFFIX_PATTERN,
+                         :FRAMEWORK_NAMESPACE_PATTERN
+
+        module_function
+
+        def shared?(declaration)
+          shared_name?(declaration.name) ||
+            ExceptionDeclaration.exception?(declaration) ||
+            framework_namespace?(declaration.name)
+        end
+
+        def attributes(status)
+          { project_analyzer_status: status, confidence: CONFIDENCE,
+            triage_severity: TRIAGE_SEVERITY, triage_summary: TRIAGE_SUMMARY }
+        end
+
+        def shared_name?(name)
+          segments = name.to_s.split("::")
+          segments.any? { |segment| shared_segment?(segment) } ||
+            constant_like_tail?(segments.last) || error_like_tail?(segments.last)
+        end
+
+        def framework_namespace?(name)
+          name.to_s.match?(FRAMEWORK_NAMESPACE_PATTERN)
+        end
+
+        def shared_segment?(segment)
+          segment.to_s.match?(SHARED_SEGMENT_PATTERN) || exception_family_segment?(segment)
+        end
+
+        def constant_like_tail?(segment)
+          segment.to_s.match?(/\A[A-Z][A-Z0-9_]*\z/)
+        end
+
+        def error_like_tail?(segment)
+          segment.to_s.match?(ERROR_SUFFIX_PATTERN)
+        end
+
+        def exception_family_segment?(segment)
+          segment.to_s.match?(EXCEPTION_FAMILY_SEGMENT_PATTERN)
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/namespace_leak_pressure.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "../project_index"
+require_relative "namespace_leak_pressure/finding"
+require_relative "namespace_leak_pressure/metadata"
+require_relative "namespace_leak_pressure/namespace"
+require_relative "namespace_leak_pressure/reference_collector"
+require_relative "namespace_leak_pressure/reference_set"
+require_relative "namespace_leak_pressure/shared_namespace_triage"
+require_relative "package_map"
+require_relative "project_analyzer_triage"
+
+module MetzScan
+  module Analyzers
+    # Reports internal namespace constants referenced outside their namespace.
+    class NamespaceLeakPressure
+      include ProjectAnalyzerTriage
+
+      RULE_ID = "MetzProject/NamespaceLeakPressure"
+      PROJECT_ANALYZER_STATUS = "candidate"
+      CONFIDENCE = "medium"
+      TRIAGE_SEVERITY = "manual review"
+      TRIAGE_SUMMARY = "Candidate namespace-boundary signal; review internal constants used across layers."
+      WHY = "Internal namespace constants can become implicit public APIs when distant callers reference them directly."
+      SUGGESTED_NEXT_MOVES = [
+        "Review whether callers should depend on a narrower public namespace interface.",
+        "Look for behavior that belongs behind the namespace boundary instead of in external callers."
+      ].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: 3, minimum_referring_packages: 3)
+        @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.path && Namespace.new(declaration.name).deep? && 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)
+        identity_attributes(declaration, reference_set)
+          .merge(context_attributes(declaration, reference_set))
+      end
+
+      def identity_attributes(declaration, reference_set)
+        { source: source_name, rule_id: RULE_ID, message: message_for(declaration, reference_set),
+          declaration_name: declaration.name, home_namespace: home_namespace_for(declaration.name),
+          declared_package: PackageMap.package_for(declaration.path) }
+      end
+
+      def 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)
+        "#{declaration.name} is referenced from #{reference_set.files.size} files across " \
+          "#{reference_set.packages.size} packages outside #{home_namespace_for(declaration.name)}; " \
+          "review whether callers know too much about this namespace."
+      end
+
+      def metadata_for(declaration, reference_set)
+        Metadata.for(declaration, reference_set, namespace_leak_category_for(declaration))
+      end
+
+      def home_namespace_for(name)
+        Namespace.new(name).home_name
+      end
+
+      def triage_attributes_for(declaration)
+        return SharedNamespaceTriage.attributes(PROJECT_ANALYZER_STATUS) if shared_namespace?(declaration)
+
+        project_analyzer_triage_attributes
+      end
+
+      def namespace_leak_category_for(declaration)
+        shared_namespace?(declaration) ? SharedNamespaceTriage::CATEGORY : "namespace_boundary"
+      end
+
+      def why_for(declaration)
+        shared_namespace?(declaration) ? SharedNamespaceTriage::WHY : WHY
+      end
+
+      def suggested_next_moves_for(declaration)
+        shared_namespace?(declaration) ? SharedNamespaceTriage::SUGGESTED_NEXT_MOVES : SUGGESTED_NEXT_MOVES
+      end
+
+      def shared_namespace?(declaration)
+        SharedNamespaceTriage.shared?(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/occurrence.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    FALLBACK_LINE = 1
+
+    Occurrence = Struct.new(:path, :line, :context, keyword_init: true) do
+      def self.from(value, context: nil)
+        return value if value.is_a?(self)
+        return nil unless value.respond_to?(:path) && value.path
+
+        new(path: value.path, line: line_for(value), context: context)
+      end
+
+      def self.line_for(value)
+        value.line if value.respond_to?(:line)
+      end
+
+      def report_line
+        line || MetzScan::Analyzers::FALLBACK_LINE
+      end
+
+      def line_source
+        line ? "source" : "fallback"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../occurrence"
+
+module MetzScan
+  module Analyzers
+    class PackageDependencyPressure
+      Finding = Struct.new(:source, :rule_id, :message, :declaration_name, :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/package_dependency_pressure/metadata.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../cross_package_reference_metadata"
+
+module MetzScan
+  module Analyzers
+    class PackageDependencyPressure
+      module Metadata
+        module_function
+
+        def for(declaration, reference_set, dependency_pressure_category)
+          CrossPackageReferenceMetadata.counts(reference_set).merge(
+            dependency_metadata(declaration, reference_set, dependency_pressure_category)
+          )
+        end
+
+        def dependency_metadata(declaration, reference_set, dependency_pressure_category)
+          { "declaration" => CrossPackageReferenceMetadata.declaration_metadata(declaration),
+            "declared_package" => PackageMap.package_for(declaration.path),
+            "project_analyzer_category" => dependency_pressure_category,
+            "dependency_pressure_category" => dependency_pressure_category,
+            "references" => CrossPackageReferenceMetadata.references_metadata(reference_set) }
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/package_dependency_pressure/package_map.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "../package_map"
+
+module MetzScan
+  module Analyzers
+    class PackageDependencyPressure
+      PackageMap = MetzScan::Analyzers::PackageMap
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class PackageDependencyPressure
+      class ReferenceCollector
+        def initialize(index)
+          @index = index
+        end
+
+        def for(declaration)
+          declared_package = PackageMap.package_for(declaration.path)
+          index.constant_references_to(declaration.name).filter_map do |reference|
+            counted_reference_for(reference, declaration.path, declared_package)
+          end
+        end
+
+        private
+
+        attr_reader :index
+
+        def counted_reference_for(reference, declaration_path, declared_package)
+          return if same_path?(reference.path, declaration_path)
+          return if PackageMap.ignored_path?(reference.path)
+
+          package = PackageMap.package_for(reference.path)
+          return if !package || package == declared_package
+
+          Reference.new(path: reference.path, line: reference.line, column: reference.column, package: package)
+        end
+
+        def same_path?(left, right)
+          File.expand_path(left) == File.expand_path(right)
+        end
+      end
+    end
+  end
+end

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

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

data/lib/metz_scan/analyzers/package_dependency_pressure/shared_dependency_triage.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class PackageDependencyPressure
+      module SharedDependencyTriage
+        CATEGORY = "shared_dependency"
+        CONFIDENCE = "low"
+        TRIAGE_SEVERITY = "shared dependency"
+        TRIAGE_SUMMARY = "Shared dependency signal; review broad APIs or infrastructure hubs only when " \
+                         "they change often or force package-specific callers to know too much."
+        WHY = "Broad shared dependencies are often intentional, but they can still reveal global APIs " \
+              "that many packages must understand."
+        SUGGESTED_NEXT_MOVES = [
+          "Leave stable shared APIs alone when callers use a narrow, intentional interface.",
+          "Extract package-owned adapters when broad APIs force repeated package-specific knowledge."
+        ].freeze
+        SHARED_NAME_SEGMENTS = "Config(?:uration)?|Settings?|Current|Core|Events?|Types?|" \
+                               "Feature(?:Flag|Toggle)s?|Permissions?|Utils?|Utilities?"
+        NAME_SEGMENT_PATTERN =
+          /\A(?:#{SHARED_NAME_SEGMENTS})\z/i
+        ERROR_SUFFIX_PATTERN = /(?:Error|Exception)\z/
+        INFRASTRUCTURE_LIB_SEGMENT_PATTERN =
+          /\A(?:cache|caches|errors?|exceptions?|freedom_patches|rate_limiter|redis|scheduler)\z/i
+        VALUE_OBJECT_SEGMENT_PATTERN = /\A(?:Amount|Currency|Money|Price)\z/
+        PROTOCOL_MANAGER_SUFFIX_PATTERN = /(?:Manager|Registry|Resolver|Router)\z/
+        private_constant :SHARED_NAME_SEGMENTS, :NAME_SEGMENT_PATTERN, :ERROR_SUFFIX_PATTERN,
+                         :INFRASTRUCTURE_LIB_SEGMENT_PATTERN, :VALUE_OBJECT_SEGMENT_PATTERN,
+                         :PROTOCOL_MANAGER_SUFFIX_PATTERN
+
+        module_function
+
+        def shared?(declaration)
+          shared_name?(declaration.name) || shared_path?(declaration.path) || shared_surface?(declaration)
+        end
+
+        def attributes(status)
+          { project_analyzer_status: status, confidence: CONFIDENCE,
+            triage_severity: TRIAGE_SEVERITY, triage_summary: TRIAGE_SUMMARY }
+        end
+
+        def shared_name?(name)
+          segments = name_segments(name)
+          segments.any? { |segment| segment.match?(NAME_SEGMENT_PATTERN) } ||
+            constant_like_tail?(segments.last) || error_like_tail?(segments.last)
+        end
+
+        def shared_path?(path)
+          package_parts = PackageMap.package_parts(path)
+          return false unless package_parts.first == "lib"
+
+          root_lib_file?(package_parts) || infrastructure_lib_segment?(package_parts)
+        end
+
+        def shared_surface?(declaration)
+          conventional_domain_model?(declaration) ||
+            conventional_value_object?(declaration) ||
+            protocol_manager_surface?(declaration)
+        end
+
+        def name_segments(name)
+          name.to_s.split("::")
+        end
+
+        def constant_like_tail?(segment)
+          segment.to_s.match?(/\A[A-Z][A-Z0-9_]*\z/) && segment.to_s.include?("_")
+        end
+
+        def error_like_tail?(segment)
+          segment.to_s.match?(ERROR_SUFFIX_PATTERN)
+        end
+
+        def root_lib_file?(package_parts)
+          package_parts[1].to_s.end_with?(".rb")
+        end
+
+        def infrastructure_lib_segment?(package_parts)
+          File.basename(package_parts[1].to_s, ".rb").match?(INFRASTRUCTURE_LIB_SEGMENT_PATTERN)
+        end
+
+        def conventional_domain_model?(declaration)
+          PackageMap.package_for(declaration.path) == "app/models" &&
+            conventional_declaration_path?(declaration)
+        end
+
+        def conventional_value_object?(declaration)
+          PackageMap.package_for(declaration.path).to_s.start_with?("lib/") &&
+            name_segments(declaration.name).last.to_s.match?(VALUE_OBJECT_SEGMENT_PATTERN) &&
+            conventional_declaration_path?(declaration)
+        end
+
+        def protocol_manager_surface?(declaration)
+          PackageMap.package_for(declaration.path) == "app/lib" &&
+            name_segments(declaration.name).last.to_s.match?(PROTOCOL_MANAGER_SUFFIX_PATTERN) &&
+            declaration_path_matches_tail?(declaration)
+        end
+
+        def conventional_declaration_path?(declaration)
+          normalized_path(declaration.path).end_with?(conventional_path_suffix(declaration.name))
+        end
+
+        def declaration_path_matches_tail?(declaration)
+          normalized_path(declaration.path).end_with?("#{underscore(name_segments(declaration.name).last)}.rb")
+        end
+
+        def conventional_path_suffix(name)
+          "#{name_segments(name).map { |segment| underscore(segment) }.join('/')}.rb"
+        end
+
+        def underscore(segment)
+          segment.to_s
+                 .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\\1_\\2')
+                 .gsub(/([a-z\d])([A-Z])/, '\\1_\\2')
+                 .tr("-", "_")
+                 .downcase
+        end
+
+        def normalized_path(path)
+          path.to_s.split(File::SEPARATOR).join("/")
+        end
+      end
+    end
+  end
+end