metz-scan 0.5.3 → 0.6.0

data/lib/metz_scan/commands/scan/runner.rb

@@ -6,6 +6,7 @@ require "rubocop"
 require "stringio"
 
 require "metz_scan/commands/scan/project_config_scope"
+require "metz_scan/commands/scan/suppression_ledger"
 require "metz_scan/commands/scan/target_ruby_version"
 
 module MetzScan
@@ -33,7 +34,7 @@ module MetzScan
           report = TargetRubyVersion.with_project_config(paths, all_cops: all_cops) do
             parse_output(capture_output(rubocop_argv(paths, all_cops: all_cops)))
           end
-          all_cops ? report : ProjectCopScope.honor(report)
+          all_cops ? report : SuppressionLedger.apply(report)
         end
 
         def self.with_errors
@@ -44,7 +45,8 @@ module MetzScan
 
         def self.rubocop_argv(paths, all_cops:)
           require_metz_plugin
-          ["--plugin", "rubocop-metz", *cop_selection_argv(all_cops), "--format", FORMATTER, *paths]
+          ["--plugin", "rubocop-metz", *cop_selection_argv(all_cops), *ledger_argv(all_cops), "--format", FORMATTER,
+           *paths]
         end
 
         def self.require_metz_plugin
@@ -59,9 +61,10 @@ module MetzScan
           TargetFileDiscovery.for_project_config(paths).map { |path| display_path(path) }
         end
 
-        def self.cop_selection_argv(all_cops)
-          all_cops ? [] : ["--force-default-config", "--enable-all-cops", "--only", "Metz"]
-        end
+        def self.cop_selection_argv(all_cops) = all_cops ? [] : ["--force-default-config", "--only", "Metz"]
+
+        # The suppression ledger needs inline-suppressed offenses; AutoFix reuses cop_selection_argv without it.
+        def self.ledger_argv(all_cops) = all_cops ? [] : ["--display-suppressed"]
 
         def self.capture_output(argv)
           out = StringIO.new
@@ -120,7 +123,7 @@ module MetzScan
         end
 
         def self.empty_report
-          { "metadata" => metadata, "files" => [],
+          { "metadata" => metadata, "files" => [], "suppressions" => [],
             "summary" => { "offense_count" => 0, "target_file_count" => 0, "inspected_file_count" => 0 } }
         end
 
@@ -139,44 +142,6 @@ module MetzScan
         end
       end
 
-      # Default mode forces stock Metz *tuning* (--force-default-config) but must
-      # still honor the project's per-cop file *scope* (Include/Exclude), the
-      # same way #33 honors AllCops: Exclude. RuboCop's own excluded_file?
-      # resolves the project config's scope per cop; offenses on files a cop is
-      # scoped off are dropped here. Invalid project config -> nothing to honor
-      # (matches the forced-default target-discovery fallback). See #37.
-      module ProjectCopScope
-        module_function
-
-        def honor(report)
-          store = ProjectConfigScope.store
-          files = Array(report["files"]).map { |file| reject_scoped_off(store, file) }
-          recount(report.merge("files" => files))
-        rescue RuboCop::Error, Psych::Exception
-          report
-        end
-
-        def reject_scoped_off(store, file)
-          absolute = File.expand_path(file.fetch("path"))
-          kept = Array(file["offenses"]).reject { |o| scoped_off?(store, o.fetch("cop_name"), absolute) }
-          file.merge("offenses" => kept)
-        end
-
-        def scoped_off?(store, cop_name, absolute_path)
-          cop_class = RuboCop::Cop::Registry.global.find_by_cop_name(cop_name)
-          return false unless cop_class
-
-          cop_class.new(store.for_file(absolute_path)).excluded_file?(absolute_path)
-        end
-
-        def recount(report)
-          return report unless report["summary"]
-
-          count = Array(report["files"]).sum { |file| Array(file["offenses"]).size }
-          report.merge("summary" => report["summary"].merge("offense_count" => count))
-        end
-      end
-
       module TargetFileDiscovery
         module_function
 

data/lib/metz_scan/commands/scan/suppression_ledger.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "psych"
+require "rubocop"
+
+require "metz_scan/commands/scan/config_exclusions"
+require "metz_scan/commands/scan/inline_directive_locator"
+require "metz_scan/commands/scan/project_config_scope"
+
+module MetzScan
+  module Commands
+    class Scan
+      # Default mode asks RuboCop to --display-suppressed, then partitions every
+      # offense: a project per-cop Exclude hides it (credited even when an
+      # inline disable also covers it), else an inline directive hides it, else
+      # it is live. Hidden offenses leave `files` and the counts; the ones a
+      # project wrote a suppression for are listed under `suppressions`.
+      class SuppressionLedger
+        SORT_KEYS = %w[path line column cop_name].freeze
+
+        def self.apply(report)
+          new(report, ConfigExclusions.new(ProjectConfigScope.store)).apply
+        rescue RuboCop::Error, Psych::Exception
+          new(report, NoConfigExclusions).apply
+        end
+
+        def initialize(report, exclusions)
+          @report = report
+          @exclusions = exclusions
+          @directives = InlineDirectiveLocator.new
+          @records = []
+        end
+
+        def apply
+          files = Array(report["files"]).map { |file| file.merge("offenses" => live_offenses(file)) }
+          recount(report.merge("files" => files, "suppressions" => records.sort_by { |r| r.values_at(*SORT_KEYS) }))
+        end
+
+        private
+
+        attr_reader :report, :exclusions, :directives, :records
+
+        def live_offenses(file)
+          path = file.fetch("path")
+          sourced = Array(file["offenses"]).map { |offense| [offense, suppression_source(path, offense)] }
+          live, hidden = sourced.partition { |_offense, source| source.nil? }
+          hidden.each { |offense, source| record(path, offense, source.record_fields(path, offense)) }
+          live.map(&:first)
+        end
+
+        def suppression_source(path, offense)
+          return exclusions if exclusions.scoped_off?(path, offense)
+
+          directives if offense["suppressed"]
+        end
+
+        # Hidden offenses with no project-written suppression (stock-default
+        # scope, synthetic opt-in coverage) produce no record.
+        def record(path, offense, fields)
+          records << finding(path, offense).merge(fields) if fields
+        end
+
+        def finding(path, offense)
+          location = offense.fetch("location")
+          { "cop_name" => offense.fetch("cop_name"), "path" => path, "line" => location.fetch("start_line"),
+            "column" => location.fetch("start_column"), "message" => offense.fetch("message") }
+        end
+
+        def recount(report)
+          count = report["files"].sum { |file| file["offenses"].size }
+          report.merge("summary" => report.fetch("summary").merge("offense_count" => count))
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/commands/scan/suppression_ledger_formatter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Commands
+    class Scan
+      class SuppressionLedgerFormatter
+        def initialize(parsed)
+          @records = Array(parsed["suppressions"])
+        end
+
+        def lines
+          return [] if records.empty?
+
+          [heading, *records.flat_map { |record| record_lines(record) }, ""]
+        end
+
+        private
+
+        attr_reader :records
+
+        def heading
+          missing = records.count { |record| record.fetch("reason_status") == "missing" }
+          "Suppressed findings: #{records.size}, #{missing} without a reason"
+        end
+
+        def record_lines(record)
+          ["  #{record.fetch('path')}:#{record.fetch('line')}:#{record.fetch('column')} #{record.fetch('message')}",
+           "    #{source(record)}, #{reason(record)}"]
+        end
+
+        def source(record)
+          return "inline disable at line #{record.dig('directive', 'line')}" unless record.fetch("config")
+
+          config = record.fetch("config")
+          "#{[config.fetch('path'), config.fetch('line')].compact.join(':')} Exclude \"#{config.fetch('pattern')}\""
+        end
+
+        def reason(record)
+          case record.fetch("reason_status")
+          when "present" then "reason: #{record.fetch('reason')}"
+          when "missing" then "no reason"
+          else "reason not checked"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/commands/scan/text_renderer.rb

@@ -6,6 +6,7 @@ require_relative "project_analyzer_summary_aggregate_formatter"
 require_relative "project_analyzer_summary_breakdown_formatter"
 require_relative "project_analyzer_triage_formatter"
 require_relative "project_analyzer_triage_priority"
+require_relative "suppression_ledger_formatter"
 
 module MetzScan
   module Commands
@@ -22,16 +23,16 @@ module MetzScan
 
         def render
           emit_project_analyzer_summary
-          sorted_offense_blocks.each do |cop_name, list|
-            render_block(cop_name, list)
-          end
-          ComplianceScorecard.new(parsed).lines.each { |line| stdout.puts line }
+          sorted_offense_blocks.each { |cop_name, list| render_block(cop_name, list) }
+          closing_lines.each { |line| stdout.puts line }
         end
 
         private
 
         attr_reader :stdout, :parsed
 
+        def closing_lines = SuppressionLedgerFormatter.new(parsed).lines + ComplianceScorecard.new(parsed).lines
+
         def render_block(cop_name, list)
           stdout.puts heading(cop_name)
           emit_block_metadata(cop_name, representative_offense(list))

data/lib/metz_scan/commands/scan.rb

@@ -11,6 +11,7 @@ require_relative "scan/text_renderer"
 require_relative "scan/sarif_renderer"
 require_relative "scan/github_annotations_renderer"
 require_relative "scan/auto_fix"
+require_relative "../cli"
 
 module MetzScan
   module Commands
@@ -128,7 +129,6 @@ module MetzScan
       def validate(options)
         return missing_path_arg if options.paths.empty?
         return missing_paths(options.paths) unless options.paths.all? { |p| File.exist?(p) }
-        return nil if options.auto_fix
 
         invalid_format(options.format) unless VALID_FORMATS.include?(options.format)
       end
@@ -168,7 +168,7 @@ module MetzScan
       def parser_error(err)
         stderr.puts "metz-scan scan: #{err.message}"
         stderr.puts USAGE
-        1
+        CLI::USAGE_ERROR
       end
 
       def print_help
@@ -179,17 +179,17 @@ module MetzScan
       def missing_path_arg
         stderr.puts "metz-scan scan: missing PATH argument."
         stderr.puts USAGE
-        1
+        CLI::USAGE_ERROR
       end
 
       def missing_paths(paths)
         paths.reject { |p| File.exist?(p) }.each { |p| stderr.puts "metz-scan scan: no such file or directory: #{p}" }
-        1
+        CLI::USAGE_ERROR
       end
 
       def invalid_format(fmt)
         stderr.puts "metz-scan scan: invalid --format '#{fmt}'. Valid formats: text, json, sarif, gh-annotations."
-        1
+        CLI::USAGE_ERROR
       end
 
       def runner_error(err)

data/lib/metz_scan/project_index/rubydex_backend/method_declarations.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "method_visibility"
+
 module MetzScan
   class ProjectIndex
     class RubydexBackend
       module MethodDeclarations
+        include MethodVisibility
+
         def method_declarations
           method_declaration_entries.sort_by do |declaration|
             [declaration.owner_name.to_s, declaration.method_identity.to_s, declaration.path.to_s,
@@ -15,7 +19,7 @@ module MetzScan
 
         def method_declaration_entries
           graph.declarations.select { |declaration| method_declaration?(declaration) }
-                            .filter_map { |declaration| method_declaration_for(declaration) }
+               .filter_map { |declaration| method_declaration_for(declaration) }
         end
 
         def method_declaration?(declaration)
@@ -31,14 +35,13 @@ module MetzScan
           owner_attributes = method_owner_attributes(declaration)
           return unless owner_attributes
 
-          method_name = method_name_for(owner_attributes.fetch(:signature))
-          identity_attributes(declaration, owner_attributes, method_name)
-            .merge(location_attributes(declaration))
+          method_declaration_identity(declaration, owner_attributes)
         end
 
-        def method_owner_and_signature(declaration)
-          owner_attributes = method_owner_attributes(declaration)
-          [owner_attributes[:owner_name], owner_attributes[:signature]] if owner_attributes
+        def method_declaration_identity(declaration, owner_attributes)
+          location = location_attributes(declaration)
+          method_name = method_name_for(owner_attributes.fetch(:signature))
+          identity_attributes(declaration, owner_attributes, method_name, location).merge(location)
         end
 
         def method_owner_attributes(declaration)
@@ -50,11 +53,28 @@ module MetzScan
             receiver_kind: receiver_kind_for(raw_owner_name) }
         end
 
-        def identity_attributes(declaration, owner_attributes, method_name)
+        def identity_attributes(declaration, owner_attributes, method_name, location_attributes)
+          # For supported Ruby visibility forms, Rubydex::Method#visibility is this analyzer's one index assumption.
+          method_identity_attributes(declaration, owner_attributes, method_name, location_attributes)
+        end
+
+        def method_identity_attributes(declaration, owner_attributes, method_name, location_attributes)
           receiver_kind = owner_attributes.fetch(:receiver_kind)
-          { name: declaration.name, owner_name: owner_attributes.fetch(:owner_name), method_name: method_name,
-            signature: owner_attributes.fetch(:signature), receiver_kind: receiver_kind,
-            method_identity: method_identity_for(receiver_kind, method_name) }
+          core_identity_attributes(declaration, owner_attributes, method_name, receiver_kind)
+            .merge(visibility: visibility_for(declaration,
+                                              visibility_attributes(owner_attributes, method_name, receiver_kind,
+                                                                    location_attributes)))
+        end
+
+        def core_identity_attributes(declaration, owner_attributes, method_name, receiver_kind)
+          { name: declaration.name, owner_name: owner_attributes.fetch(:owner_name),
+            method_name: method_name, signature: owner_attributes.fetch(:signature),
+            receiver_kind: receiver_kind, method_identity: method_identity_for(receiver_kind, method_name) }
+        end
+
+        def visibility_attributes(owner_attributes, method_name, receiver_kind, location_attributes)
+          { owner_name: owner_attributes.fetch(:owner_name), method_name: method_name,
+            receiver_kind: receiver_kind, path: location_attributes.fetch(:path) }
         end
 
         def location_attributes(declaration)
@@ -91,7 +111,8 @@ module MetzScan
 
         def singleton_owner_name(raw_owner_name)
           owner_name, singleton_tail = raw_owner_name.to_s.split("::<", 2)
-          return unless singleton_tail&.delete_suffix(">") == owner_name
+          tail_name = singleton_tail&.delete_suffix(">")
+          return unless tail_name == owner_name || tail_name == owner_name.split("::").last
 
           owner_name
         end

data/lib/metz_scan/project_index/rubydex_backend/method_visibility.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module MetzScan
+  class ProjectIndex
+    class RubydexBackend
+      module MethodVisibility
+        def visibility_for(declaration, attributes)
+          return module_function_visibility(attributes) if module_function_method?(attributes)
+
+          declaration.visibility.to_s
+        end
+
+        def module_function_visibility(attributes)
+          attributes.fetch(:receiver_kind) == "singleton" ? "public" : "private"
+        end
+
+        def module_function_method?(attributes)
+          facts = module_function_facts_for(attributes.fetch(:path))
+          facts.fetch(module_function_owner_name(attributes.fetch(:owner_name)), [])
+               .include?(attributes.fetch(:method_name))
+        end
+
+        def module_function_owner_name(owner_name)
+          owner_name.to_s.split("::<", 2).first
+        end
+
+        def module_function_facts_for(path)
+          return {} unless path && File.file?(path)
+
+          @module_function_facts_by_path ||= {}
+          @module_function_facts_by_path[path] ||= ModuleFunctionFacts.new(path).to_h
+        end
+
+        class ModuleFunctionFacts
+          def initialize(path)
+            @path = path
+          end
+
+          def to_h
+            add_scope_tree_facts(ast, [], {})
+          rescue Parser::SyntaxError
+            {}
+          end
+
+          private
+
+          attr_reader :path
+
+          def ast
+            processed_source.ast
+          end
+
+          def processed_source
+            RuboCop::ProcessedSource.new(File.read(path), RUBY_VERSION.to_f)
+          end
+
+          def add_scope_tree_facts(node, owner_stack, facts)
+            return facts unless node
+            return add_scope_facts(node, owner_stack, facts) if scope_node?(node)
+
+            add_child_scope_facts(node, owner_stack, facts)
+          end
+
+          def add_child_scope_facts(node, owner_stack, facts)
+            node&.children&.each do |child|
+              add_child_scope_fact(child, owner_stack, facts) if child.is_a?(Parser::AST::Node)
+            end
+
+            facts
+          end
+
+          def add_child_scope_fact(child, owner_stack, facts)
+            return add_scope_facts(child, owner_stack, facts) if scope_node?(child)
+
+            add_child_scope_facts(child, owner_stack, facts)
+          end
+
+          def add_scope_facts(scope, owner_stack, facts)
+            owner_name = owner_name_for(scope, owner_stack)
+            nested_stack = owner_name ? [owner_name] : owner_stack
+            add_module_function_facts(facts, owner_name, scope) if owner_name
+            add_scope_tree_facts(scope.body, nested_stack, facts)
+          end
+
+          def add_module_function_facts(facts, owner_name, scope)
+            names = explicit_module_function_names(scope) + default_module_function_names(scope)
+            facts[owner_name] = Array(facts[owner_name]) | names unless names.empty?
+          end
+
+          def owner_name_for(scope, owner_stack)
+            name = scope.identifier.const_name if scope.identifier&.const_type?
+            return unless name
+            return name if name.include?("::") || owner_stack.empty?
+
+            "#{owner_stack.last}::#{name}"
+          end
+
+          def explicit_module_function_names(scope)
+            module_function_sends(scope).flat_map { |node| literal_names(node.arguments) }
+          end
+
+          def default_module_function_names(scope)
+            lines = bare_module_function_lines(scope)
+            direct_defs(scope).select { |node| lines.any? { |line| line < node.loc.keyword.line } }
+                              .map { |node| node.method_name.to_s }
+          end
+
+          def bare_module_function_lines(scope)
+            module_function_sends(scope).select { |node| node.arguments.empty? }
+                                        .map { |node| node.loc.selector.line }
+          end
+
+          def module_function_sends(scope)
+            direct_descendants(scope, :send).select do |node|
+              !node.receiver && node.method_name == :module_function
+            end
+          end
+
+          def direct_defs(scope)
+            direct_descendants(scope, :def)
+          end
+
+          def literal_names(arguments)
+            arguments.filter_map { |argument| literal_name(argument) }
+          end
+
+          def literal_name(argument)
+            argument.value.to_s if argument&.sym_type? || argument&.str_type?
+          end
+
+          def direct_descendants(scope, *types)
+            scope.each_descendant(*types).reject { |node| nested_scope_between?(node, scope) }
+          end
+
+          def nested_scope_between?(node, scope)
+            node.each_ancestor.any? do |ancestor|
+              break false if ancestor.equal?(scope)
+
+              scope_node?(ancestor)
+            end
+          end
+
+          def scope_node?(node)
+            node&.class_type? || node&.module_type?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/project_index/rubydex_backend.rb

@@ -28,7 +28,8 @@ module MetzScan
         require "rubydex"
 
         files = ruby_files_for(paths)
-        graph = Rubydex::Graph.new(workspace_path: workspace_path_for(paths))
+        # 0.4.0: Config owns workspace_path; Graph.new no longer takes it (Shopify/rubydex#965).
+        graph = Rubydex::Graph.configure_for_workspace(workspace_path_for(paths))
         index_errors = index_graph(graph, files, workspace)
 
         new(graph: graph, indexed_files: files, index_errors: index_errors)

data/lib/metz_scan/project_index.rb

@@ -8,7 +8,7 @@ module MetzScan
   class ProjectIndex
     Declaration = Struct.new(:name, :path, :kind, keyword_init: true)
     MethodDeclaration = Struct.new(:name, :owner_name, :method_name, :signature, :path, :line, :column,
-                                   :receiver_kind, :method_identity, keyword_init: true)
+                                   :receiver_kind, :method_identity, :visibility, keyword_init: true)
     Reference = Struct.new(:name, :path, :line, :column, keyword_init: true)
 
     class UnknownBackendError < StandardError; end

data/lib/metz_scan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MetzScan
-  VERSION = "0.5.3"
+  VERSION = "0.6.0"
 end

data/metz-scan.gemspec

@@ -18,21 +18,22 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.3"
 
   spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["documentation_uri"] = "#{spec.homepage}/blob/main/README.md"
   spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
   spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
   spec.metadata["github_repo"] = "ssh://github.com/fuentesjr/metz-scan"
   spec.metadata["github_package_uri"] = "https://github.com/users/fuentesjr/packages/rubygems/package/metz-scan"
 
-  spec.files = Dir.glob("lib/**/*", File::FNM_DOTMATCH).reject { |f| File.directory?(f) } +
-               Dir.glob("bin/metz-scan").select { |f| File.file?(f) } +
-               ["LICENSE", "metz-scan.gemspec"].select { |f| File.exist?(f) }
-  # See rubocop-metz.gemspec: fail loudly if built from the wrong directory
-  # rather than shipping a gem missing its own lib. Build from the repo root:
-  #   gem build metz-scan.gemspec
-  unless spec.files.include?("lib/metz_scan.rb")
-    raise "metz-scan.gemspec: lib/metz_scan.rb missing from packaged files; " \
-          "build from the repo root (gem build metz-scan.gemspec)."
-  end
+  # Resolve files from the gemspec directory so evaluation is CWD-independent.
+  # Do not raise when the entrypoint is absent: Dependabot evaluates gemspecs in
+  # a sparse tree that only materializes require_relative targets (#41). Package
+  # completeness is checked by release_metadata_test against the full checkout.
+  gem_root = __dir__
+  spec.files = Dir.glob("lib/**/*", File::FNM_DOTMATCH, base: gem_root)
+                  .reject { |f| File.directory?(File.join(gem_root, f)) } +
+               Dir.glob("bin/metz-scan", base: gem_root)
+                  .select { |f| File.file?(File.join(gem_root, f)) } +
+               ["LICENSE", "metz-scan.gemspec"].select { |f| File.exist?(File.join(gem_root, f)) }
   spec.bindir        = "bin"
   spec.executables   = ["metz-scan"]
   spec.require_paths = ["lib"]