rubocop-metz 0.5.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 52d0e1b2249535049c9a049fe4c8955bd0e6478e0c1b852f52a1cece489ac6d8
+  data.tar.gz: 6577bb1134e0e78115148bfb130fcd0d236410080917cc5203f3bd199a088970
+SHA512:
+  metadata.gz: 9290ef1235939702c2a31c7588bc5a8302f2ca994b75e2b39998fe669941094be0cf0eb58bb50cd4e504555167e1e34767ec96524644c5c6aa9859e1efb0a2ba
+  data.tar.gz: a7f3bc181cd224ed873ff5f991b7bff30a320c59b741dd82dd8ef87f99b32cd845e5b6d128ab46593235e06e53963488f02e025b32af3f6f7e4f180bba9377f0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Salvador Fuentes Jr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/metz_scan/analyzers/contextual_node_walker.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module MetzScan
+  module Analyzers
+    class ContextualNodeWalker
+      ContextualNode = Struct.new(:node, :enclosing_name, :method_name, keyword_init: true)
+
+      Context = Struct.new(:namespace, :method_name, keyword_init: true) do
+        def self.root = new(namespace: [], method_name: nil)
+
+        def enclosing_name = namespace.join("::").then { |name| name unless name.empty? }
+
+        def with_namespace(name) = self.class.new(namespace: namespace + [name].compact, method_name: nil)
+
+        def with_method(name) = self.class.new(namespace: namespace, method_name: name)
+      end
+
+      def initialize(root)
+        @root = root
+      end
+
+      def nodes
+        collect(root, Context.root, [])
+      end
+
+      private
+
+      attr_reader :root
+
+      def collect(node, context, nodes)
+        return nodes unless node
+        return collect_scope(node, context, nodes) if scope_node?(node)
+
+        collect_current(node, context, nodes)
+        collect_children(node, context, nodes)
+      end
+
+      def collect_scope(node, context, nodes)
+        return collect_namespace(node, context, nodes) if namespace_node?(node)
+        return collect_method(node, context, nodes) if node.type == :def
+
+        collect_singleton_method(node, context, nodes)
+      end
+
+      def collect_namespace(node, context, nodes)
+        collect(node.children.last, context.with_namespace(constant_name(node.children.first)), nodes)
+      end
+
+      def collect_method(node, context, nodes)
+        collect(node.children[2], context.with_method("##{node.method_name}"), nodes)
+      end
+
+      def collect_singleton_method(node, context, nodes)
+        collect(node.children[3], context.with_method(".#{node.method_name}"), nodes)
+      end
+
+      def collect_current(node, context, nodes)
+        nodes << ContextualNode.new(node: node, enclosing_name: context.enclosing_name,
+                                    method_name: context.method_name)
+      end
+
+      def collect_children(node, context, nodes)
+        node.children.grep(RuboCop::AST::Node).each { |child| collect(child, context, nodes) }
+        nodes
+      end
+
+      def scope_node?(node)
+        namespace_node?(node) || %i[def defs].include?(node.type)
+      end
+
+      def namespace_node?(node)
+        %i[class module].include?(node.type)
+      end
+
+      def constant_name(node)
+        node.source if node&.type == :const
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/cross_package_reference_metadata.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    module CrossPackageReferenceMetadata
+      module_function
+
+      def counts(reference_set)
+        { "referring_file_count" => reference_set.files.size,
+          "referring_package_count" => reference_set.packages.size,
+          "referring_packages" => reference_set.packages,
+          "reference_shape" => reference_shape(reference_set) }
+      end
+
+      def reference_shape(reference_set)
+        { "referring_file_count" => reference_set.files.size,
+          "referring_package_count" => reference_set.packages.size,
+          "referring_package_roots" => reference_set.package_roots,
+          "referring_package_leafs" => reference_set.package_leafs }
+      end
+
+      def declaration_metadata(declaration)
+        { "name" => declaration.name, "kind" => declaration.kind.to_s, "path" => declaration.path }.compact
+      end
+
+      def references_metadata(reference_set)
+        reference_set.references.map { |reference| reference_metadata(reference) }
+      end
+
+      def reference_metadata(reference)
+        { "path" => reference.path, "line" => reference.line, "column" => reference.column,
+          "package" => reference.package }.compact
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/cross_package_reference_set.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class CrossPackageReferenceSet
+      def initialize(references)
+        @references = references
+      end
+
+      attr_reader :references
+
+      def files
+        references.map(&:path).uniq.sort
+      end
+
+      def packages
+        references.map(&:package).uniq.sort
+      end
+
+      def package_roots
+        packages.map { |package| package.to_s.split("/").first }.uniq.sort
+      end
+
+      def package_leafs
+        packages.map { |package| package.to_s.split("/").last }.uniq.sort
+      end
+
+      def enough?(minimum_files, minimum_packages)
+        files.size >= minimum_files && packages.size >= minimum_packages
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/implicit_context_pressure/ambient_context_collector.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+require_relative "../contextual_node_walker"
+require_relative "ambient_context_reference"
+require_relative "current_attribute_collector"
+require_relative "thread_current_collector"
+
+module MetzScan
+  module Analyzers
+    class ImplicitContextPressure
+      class AmbientContextCollector
+        def initialize(path)
+          @path = path
+        end
+
+        def call
+          contextual_nodes.flat_map { |contextual_node| references_for(contextual_node) }
+        rescue Parser::SyntaxError
+          []
+        end
+
+        private
+
+        attr_reader :path
+
+        def references_for(contextual_node)
+          reference_collectors.filter_map { |collector| collector.reference_for(contextual_node) }
+        end
+
+        def reference_collectors
+          [current_attribute_collector, thread_current_collector]
+        end
+
+        def current_attribute_collector
+          @current_attribute_collector ||= CurrentAttributeCollector.new(path)
+        end
+
+        def thread_current_collector
+          @thread_current_collector ||= ThreadCurrentCollector.new(path)
+        end
+
+        def processed_source
+          RuboCop::ProcessedSource.new(File.read(path), RUBY_VERSION.to_f)
+        end
+
+        def contextual_nodes
+          ContextualNodeWalker.new(processed_source.ast).nodes
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/implicit_context_pressure/ambient_context_reference.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class ImplicitContextPressure
+      class AmbientContextCollector
+        Reference = Struct.new(:ambient_context, :kind, :context_key, :attribute, :access_mode,
+                               :enclosing_name, :method_name, :path, :line, :expression,
+                               keyword_init: true) do
+          def context
+            return "#{enclosing_name}#{method_name}" if enclosing_name && method_name
+
+            method_name || enclosing_name
+          end
+        end
+
+        module ReferenceMetadata
+          private
+
+          attr_reader :path
+
+          def context_attributes(contextual_node)
+            { enclosing_name: contextual_node.enclosing_name, method_name: contextual_node.method_name }
+          end
+
+          def location_attributes(node)
+            { path: path, line: node.loc.expression.line, expression: first_line(node) }
+          end
+
+          def first_line(node)
+            node.loc.expression.source.lines.first.strip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/implicit_context_pressure/current_attribute_collector.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class ImplicitContextPressure
+      class AmbientContextCollector
+        class CurrentAttributeCollector
+          include ReferenceMetadata
+
+          ATTRIBUTE_METHOD = /\A[a-z_]\w*=?\z/
+          IGNORED_CURRENT_METHODS = %w[after_reset attributes before_reset reset resets set].freeze
+          private_constant :ATTRIBUTE_METHOD, :IGNORED_CURRENT_METHODS
+
+          def initialize(path)
+            @path = path
+          end
+
+          def reference_for(contextual_node)
+            node = contextual_node.node
+            return unless current_attribute_reference?(node)
+
+            Reference.new(reference_attributes(contextual_node))
+          end
+
+          private
+
+          def reference_attributes(contextual_node)
+            node = contextual_node.node
+            current_attribute_attributes(node)
+              .merge(context_attributes(contextual_node))
+              .merge(location_attributes(node))
+          end
+
+          def current_attribute_attributes(node)
+            attribute = attribute_name(node.method_name)
+            { ambient_context: "#{node.receiver.source}.#{attribute}", kind: "current_attributes",
+              context_key: attribute, attribute: attribute, access_mode: access_mode(node.method_name) }
+          end
+
+          def current_attribute_reference?(node)
+            node.type == :send && current_receiver?(node.receiver) && attribute_method?(node)
+          end
+
+          def current_receiver?(node)
+            node&.type == :const && node.source.split("::").last == "Current"
+          end
+
+          def attribute_method?(node)
+            method_name = node.method_name.to_s
+            method_name.match?(ATTRIBUTE_METHOD) && counted_current_method?(method_name, node.arguments)
+          end
+
+          def counted_current_method?(method_name, arguments)
+            !IGNORED_CURRENT_METHODS.include?(attribute_name(method_name)) &&
+              valid_attribute_argument_count?(method_name, arguments)
+          end
+
+          def valid_attribute_argument_count?(method_name, arguments)
+            method_name.end_with?("=") ? arguments.size == 1 : arguments.empty?
+          end
+
+          def attribute_name(method_name)
+            method_name.to_s.delete_suffix("=")
+          end
+
+          def access_mode(method_name)
+            method_name.to_s.end_with?("=") ? "write" : "read"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../package_map"
+
+module MetzScan
+  module Analyzers
+    class ImplicitContextPressure
+      class ReferenceSet
+        def initialize(references)
+          @references = references.sort_by { |reference| [reference.path, reference.line.to_i] }
+        end
+
+        attr_reader :references
+
+        def referring_files
+          references.map(&:path).uniq
+        end
+
+        def referring_packages
+          references.map { |reference| PackageMap.package_for(reference.path) }.compact.uniq.sort
+        end
+
+        def access_modes
+          references.map(&:access_mode).uniq.sort
+        end
+
+        def context_kind
+          references.first.kind
+        end
+
+        def context_key
+          references.first.context_key
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/analyzers/implicit_context_pressure/thread_current_collector.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class ImplicitContextPressure
+      class AmbientContextCollector
+        class ThreadCurrentCollector
+          include ReferenceMetadata
+
+          THREAD_KEY_READ = :[]
+          THREAD_KEY_WRITE = :[]=
+          private_constant :THREAD_KEY_READ, :THREAD_KEY_WRITE
+
+          def initialize(path)
+            @path = path
+          end
+
+          def reference_for(contextual_node)
+            node = contextual_node.node
+            return unless thread_current_reference?(node)
+
+            Reference.new(reference_attributes(contextual_node))
+          end
+
+          private
+
+          def reference_attributes(contextual_node)
+            node = contextual_node.node
+            thread_current_attributes(node)
+              .merge(context_attributes(contextual_node))
+              .merge(location_attributes(node))
+          end
+
+          def thread_current_attributes(node)
+            { ambient_context: thread_current_context(node), kind: "thread_current",
+              context_key: literal_thread_key(node.arguments.first), access_mode: access_mode(node) }
+          end
+
+          def thread_current_reference?(node)
+            thread_key_access?(node) && thread_current_receiver?(node.receiver) &&
+              literal_thread_key(node.arguments.first)
+          end
+
+          def thread_key_access?(node)
+            return false unless node.type == :send
+            return node.arguments.size == 1 if node.method_name == THREAD_KEY_READ
+            return node.arguments.size == 2 if node.method_name == THREAD_KEY_WRITE
+
+            false
+          end
+
+          def thread_current_receiver?(node)
+            node&.type == :send && node.method_name == :current &&
+              node.arguments.empty? && thread_constant?(node.receiver)
+          end
+
+          def thread_constant?(node)
+            node&.type == :const && node.source == "Thread"
+          end
+
+          def literal_thread_key(node)
+            node.value.to_s if node && %i[sym str].include?(node.type)
+          end
+
+          def thread_current_context(node)
+            "Thread.current[#{node.arguments.first.source}]"
+          end
+
+          def access_mode(node)
+            node.method_name == THREAD_KEY_WRITE ? "write" : "read"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Analyzers
+    class ImplicitContextPressure
+      module Triage
+        CATEGORY_TRIAGE = {
+          "root_current_read" => {
+            triage_summary: "Candidate application Current signal; review whether callers should receive context.",
+            why: "Application-wide Current reads hide dependencies from method signatures and make 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."
+            ]
+          },
+          "root_current_write" => {
+            triage_summary: "Candidate mutable application Current signal; review whether writes should stay at " \
+                            "request boundaries.",
+            why: "Mutable application Current access hides both dependency and mutation order from the callers " \
+                 "that depend on it.",
+            suggested_next_moves: [
+              "Keep Current writes near request, job, or tenant setup boundaries.",
+              "Pass context explicitly once domain collaborators need the value."
+            ]
+          },
+          "namespaced_current_read" => {
+            triage_summary: "Candidate namespaced Current signal; review whether the namespace is leaking ambient " \
+                            "context.",
+            why: "Namespaced Current reads can make a package depend on ambient state owned by another namespace.",
+            suggested_next_moves: [
+              "Pass the namespaced context value into collaborators that use it repeatedly.",
+              "Keep namespace-owned Current access behind the namespace boundary when possible."
+            ]
+          },
+          "namespaced_current_write" => {
+            triage_summary: "Candidate namespaced Current signal with writes; review whether mutation should stay " \
+                            "at namespace boundaries.",
+            why: "Namespaced Current writes spread mutation order across packages and make the ambient context " \
+                 "harder to audit.",
+            suggested_next_moves: [
+              "Keep namespaced Current writes near the boundary that establishes the namespace context.",
+              "Pass explicit context to downstream collaborators instead of writing ambient state mid-workflow."
+            ]
+          },
+          "thread_current_read" => {
+            triage_summary: "Candidate Thread.current signal; review whether thread-local dependencies should be " \
+                            "explicit.",
+            why: "Repeated thread-local reads hide dependencies from method signatures and make context setup " \
+                 "harder to audit.",
+            suggested_next_moves: [
+              "Pass the thread-local value explicitly into collaborators that use it repeatedly.",
+              "Keep thread-local reads at framework, request, or instrumentation boundaries when possible."
+            ]
+          },
+          "thread_current_write" => {
+            triage_summary: "Candidate mutable Thread.current signal; review whether thread-local writes should " \
+                            "stay at setup boundaries.",
+            why: "Repeated thread-local writes hide mutation order in ambient state and make cleanup requirements " \
+                 "harder to audit.",
+            suggested_next_moves: [
+              "Keep Thread.current writes near setup/teardown boundaries that own the thread-local lifecycle.",
+              "Pass explicit context to downstream collaborators instead of mutating thread-local state mid-flow."
+            ]
+          }
+        }.freeze
+        private_constant :CATEGORY_TRIAGE
+
+        private
+
+        def implicit_context_category_for(ambient_context, grouped)
+          return "thread_current_#{access_category_for(grouped)}" if grouped.context_kind == "thread_current"
+
+          "#{current_receiver_scope_for(ambient_context)}_current_#{access_category_for(grouped)}"
+        end
+
+        def current_receiver_scope_for(ambient_context)
+          ambient_context.include?("::Current.") ? "namespaced" : "root"
+        end
+
+        def current_attribute_for(ambient_context)
+          ambient_context.split(".").last
+        end
+
+        def access_category_for(grouped)
+          grouped.access_modes.include?("write") ? "write" : "read"
+        end
+
+        def access_phrase(grouped)
+          return "read and written" if mixed_access?(grouped)
+          return "written" if grouped.access_modes.include?("write")
+
+          "read"
+        end
+
+        def mixed_access?(grouped)
+          grouped.access_modes.include?("read") && grouped.access_modes.include?("write")
+        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
+      end
+    end
+  end
+end