rubocop-metz 0.5.2

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "json"
+require "psych"
+require "rubocop"
+require "stringio"
+
+require "metz_scan/commands/scan/project_config_scope"
+require "metz_scan/commands/scan/target_ruby_version"
+
+module MetzScan
+  module Commands
+    class Scan
+      module Runner
+        FORMATTER = "RuboCop::Formatter::MetzJsonFormatter"
+
+        class Error < StandardError; end
+
+        Result = Struct.new(:stdout, :stderr, :status, keyword_init: true)
+
+        def self.invoke(paths, all_cops: false, stderr: $stderr)
+          with_errors { perform(paths, all_cops: all_cops, stderr: stderr) }
+        end
+
+        def self.perform(paths, all_cops:, stderr:)
+          ProjectConfigScope.reset_unresolved_inherit_gems! unless all_cops
+          paths = inspection_paths(paths, all_cops: all_cops)
+          report = paths.empty? ? empty_report : scan(paths, all_cops: all_cops)
+          report.tap { ProjectConfigScope.warn_unresolved_inherit_gems(stderr) unless all_cops }
+        end
+
+        def self.scan(paths, all_cops:)
+          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)
+        end
+
+        def self.with_errors
+          yield
+        rescue LoadError, StandardError => e
+          raise Error, concise_message(e.message)
+        end
+
+        def self.rubocop_argv(paths, all_cops:)
+          require_metz_plugin
+          ["--plugin", "rubocop-metz", *cop_selection_argv(all_cops), "--format", FORMATTER, *paths]
+        end
+
+        def self.require_metz_plugin
+          require "rubocop-metz"
+        rescue LoadError => e
+          raise Error, "could not load rubocop-metz: #{e.message}"
+        end
+
+        def self.inspection_paths(paths, all_cops:)
+          return paths if all_cops
+
+          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.capture_output(argv)
+          out = StringIO.new
+          err = StringIO.new
+          status = with_redirected_io(out, err) { RuboCop::CLI.new.run(argv) }
+          Result.new(stdout: out.string, stderr: err.string, status: status)
+        end
+
+        def self.with_redirected_io(out, err)
+          original = redirect_to(out, err)
+          yield
+        ensure
+          restore_io(original) if original
+        end
+
+        def self.redirect_to(out, err)
+          previous = [$stdout, $stderr]
+          $stdout = out
+          $stderr = err
+          previous
+        end
+
+        def self.restore_io(previous)
+          $stdout = previous[0]
+          $stderr = previous[1]
+        end
+
+        def self.parse_output(result)
+          JSON.parse(result.stdout)
+        rescue JSON::ParserError
+          raise Error, failure_message(result)
+        end
+
+        def self.failure_message(result)
+          detail = concise_message(result.stderr)
+          detail = concise_message(result.stdout) if detail.empty?
+          return detail unless detail.empty?
+
+          "RuboCop exited with status #{result.status} without JSON output"
+        end
+
+        def self.concise_message(text)
+          text.to_s.lines.map(&:strip)
+              .reject(&:empty?)
+              .reject { |line| stack_trace_line?(line) }
+              .first(3)
+              .join(" ")
+        end
+
+        def self.stack_trace_line?(line)
+          line == "Traceback (most recent call last):" || line.match?(/:\d+:in [`']/)
+        end
+
+        def self.exit_code_for(parsed)
+          Array(parsed["files"]).any? { |f| Array(f["offenses"]).any? } ? 1 : 0
+        end
+
+        def self.empty_report
+          { "metadata" => metadata, "files" => [],
+            "summary" => { "offense_count" => 0, "target_file_count" => 0, "inspected_file_count" => 0 } }
+        end
+
+        def self.metadata
+          { "rubocop_version" => RuboCop::Version::STRING, "ruby_engine" => RUBY_ENGINE,
+            "ruby_version" => RUBY_VERSION, "ruby_patchlevel" => RUBY_PATCHLEVEL.to_s,
+            "ruby_platform" => RUBY_PLATFORM }
+        end
+
+        def self.display_path(path)
+          expanded_path = File.expand_path(path)
+          cwd = "#{File.expand_path(Dir.pwd)}#{File::SEPARATOR}"
+          return expanded_path.delete_prefix(cwd) if expanded_path.start_with?(cwd)
+
+          expanded_path
+        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
+
+        def for_project_config(paths)
+          find(paths, ProjectConfigScope.store)
+        rescue RuboCop::Error, Psych::Exception
+          with_forced_defaults(paths)
+        end
+
+        def with_forced_defaults(paths)
+          find(paths, RuboCop::ConfigStore.new.tap(&:force_default_config!))
+        end
+
+        def find(paths, store)
+          RuboCop::TargetFinder.new(store, {}).find(paths, :all_file_types)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "offense_extractor"
+require_relative "sarif_rule_descriptors"
+require_relative "sarif_severity"
+require_relative "../../version"
+
+module MetzScan
+  module Commands
+    class Scan
+      class SarifRenderer
+        SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+        TOOL_URI = "https://github.com/fuentesjr/metz-scan"
+        ROOT_URI_BASE_ID = "ROOT"
+
+        def initialize(stdout, parsed)
+          @stdout = stdout
+          @parsed = parsed
+        end
+
+        def render
+          @stdout.puts JSON.generate(to_h)
+        end
+
+        def to_h
+          { "$schema" => SCHEMA, "version" => "2.1.0",
+            "runs" => [{ "tool" => tool, "results" => results,
+                         "originalUriBaseIds" => original_uri_base_ids }] }
+        end
+
+        private
+
+        def tool
+          { "driver" => { "name" => "metz-scan", "version" => MetzScan::VERSION,
+                          "informationUri" => TOOL_URI, "rules" => reporting_descriptors } }
+        end
+
+        def results
+          offenses.map { |offense| result_for(offense) }
+        end
+
+        def result_for(offense)
+          base_result(offense).tap { |result| add_project_analyzer_properties(result, offense) }
+        end
+
+        def base_result(offense)
+          { "ruleId" => offense[:cop_name], "level" => level_for(offense),
+            "message" => { "text" => offense[:message] },
+            "locations" => [physical_location(offense)],
+            "partialFingerprints" => partial_fingerprints_for(offense) }
+        end
+
+        def add_project_analyzer_properties(result, offense)
+          return unless offense[:project_analyzer]
+
+          result["properties"] = { "project_analyzer" => offense[:project_analyzer] }
+        end
+
+        def reporting_descriptors
+          SarifRuleDescriptors.new(offenses, tool_uri: TOOL_URI).to_a
+        end
+
+        def level_for(offense)
+          SarifSeverity.level_for(offense[:severity])
+        end
+
+        def partial_fingerprints_for(offense)
+          { "primaryLocationLineHash" => Digest::SHA256.hexdigest(fingerprint_parts(offense).join("|")) }
+        end
+
+        def fingerprint_parts(offense)
+          [offense[:cop_name], offense[:path], offense[:line], offense[:column], offense[:message]]
+        end
+
+        def physical_location(offense)
+          { "physicalLocation" => {
+            "artifactLocation" => artifact_location(offense),
+            "region" => region_for(offense)
+          } }
+        end
+
+        def artifact_location(offense)
+          { "uri" => offense[:path], "uriBaseId" => ROOT_URI_BASE_ID }
+        end
+
+        def region_for(offense)
+          { "startLine" => offense[:line], "startColumn" => offense[:column] }
+        end
+
+        def original_uri_base_ids
+          { ROOT_URI_BASE_ID => { "uri" => "file://#{File.expand_path(Dir.pwd)}/" } }
+        end
+
+        def offenses
+          @offenses ||= OffenseExtractor.offenses(@parsed)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "sarif_severity"
+
+module MetzScan
+  module Commands
+    class Scan
+      class SarifRuleDescriptors
+        def initialize(offenses, tool_uri:)
+          @offenses = offenses
+          @tool_uri = tool_uri
+        end
+
+        def to_a
+          offenses_by_cop.map { |cop_name, offenses| descriptor_for(cop_name, offenses) }
+        end
+
+        private
+
+        attr_reader :offenses, :tool_uri
+
+        def descriptor_for(cop_name, offenses)
+          add_optional_texts(base_descriptor(cop_name, offenses), cop_name)
+        end
+
+        def base_descriptor(cop_name, offenses)
+          { "id" => cop_name, "name" => cop_name,
+            "shortDescription" => { "text" => offenses.first[:message].to_s },
+            "defaultConfiguration" => { "level" => descriptor_level(offenses) },
+            "helpUri" => "#{tool_uri}#rule-#{cop_name}" }
+        end
+
+        def add_optional_texts(descriptor, cop_name)
+          descriptor = add_text(descriptor, "help", help_text(cop_name))
+          add_text(descriptor, "fullDescription", full_description_for(cop_name))
+        end
+
+        def add_text(descriptor, key, text)
+          return descriptor if text.to_s.empty?
+
+          descriptor.merge(key => { "text" => text })
+        end
+
+        def descriptor_level(offenses)
+          SarifSeverity.highest_level(offenses.map { |offense| offense[:severity] })
+        end
+
+        def help_text(cop_name)
+          offense_for(cop_name)&.dig(:why_it_matters) || registry_metadata(cop_name).fetch("why_it_matters", nil)
+        end
+
+        def full_description_for(cop_name)
+          offense_for(cop_name)&.dig(:why_it_matters) || registry_metadata(cop_name).fetch("why_it_matters", nil)
+        end
+
+        def registry_metadata(cop_name)
+          return {} unless defined?(RuboCop::Cop::Registry)
+
+          metadata_for(cop_for(cop_name))
+        end
+
+        def metadata_for(cop)
+          return {} unless cop.respond_to?(:why_it_matters)
+
+          { "why_it_matters" => cop.why_it_matters }
+        end
+
+        def cop_for(cop_name)
+          RuboCop::Cop::Registry.global.cops.find { |candidate| candidate.cop_name == cop_name }
+        end
+
+        def offense_for(cop_name)
+          offenses_by_cop.fetch(cop_name, []).first
+        end
+
+        def offenses_by_cop
+          @offenses_by_cop ||= offenses.group_by { |offense| offense[:cop_name] }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MetzScan
+  module Commands
+    class Scan
+      module SarifSeverity
+        LEVEL_BY_SEVERITY = {
+          "error" => "error", "fatal" => "error",
+          "warning" => "warning", "convention" => "warning", "refactor" => "warning",
+          "info" => "note", "information" => "note"
+        }.freeze
+        LEVEL_RANK = { "note" => 0, "warning" => 1, "error" => 2 }.freeze
+
+        module_function
+
+        def level_for(severity)
+          LEVEL_BY_SEVERITY.fetch(severity.to_s, "warning")
+        end
+
+        def highest_level(severities)
+          severities.map { |severity| level_for(severity) }
+                    .max_by { |level| LEVEL_RANK.fetch(level, 1) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "metz_scan/commands/scan/project_config_scope"
+
+module MetzScan
+  module Commands
+    class Scan
+      module TargetRubyVersion
+        ENV_KEY = "RUBOCOP_TARGET_RUBY_VERSION"
+
+        module_function
+
+        def with_project_config(paths, all_cops:, &)
+          return yield if all_cops
+
+          EnvOverride.new(ProjectConfigScope.target_ruby_version(paths)).with_env(&)
+        end
+
+        class EnvOverride
+          def initialize(value)
+            @value = value
+          end
+
+          def with_env(&)
+            return yield unless value
+
+            with_override(&)
+          end
+
+          private
+
+          attr_reader :value
+
+          def with_override
+            preserve
+            ENV[ENV_KEY] = value.to_s
+            yield
+          ensure
+            restore
+          end
+
+          def preserve
+            @had_value = ENV.key?(ENV_KEY)
+            @previous = ENV.fetch(ENV_KEY, nil)
+          end
+
+          def restore
+            return ENV[ENV_KEY] = @previous if @had_value
+
+            ENV.delete(ENV_KEY)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "offense_extractor"
+require_relative "compliance_scorecard"
+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"
+
+module MetzScan
+  module Commands
+    class Scan
+      class TextRenderer
+        ANSI_RESET = "\e[0m"
+        ANSI_BOLD = "\e[1m"
+        ANSI_CYAN = "\e[36m"
+
+        def initialize(stdout, parsed)
+          @stdout = stdout
+          @parsed = parsed
+        end
+
+        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 }
+        end
+
+        private
+
+        attr_reader :stdout, :parsed
+
+        def render_block(cop_name, list)
+          stdout.puts heading(cop_name)
+          emit_block_metadata(cop_name, representative_offense(list))
+          emit_offense_lines(list)
+          stdout.puts
+        end
+
+        def emit_project_analyzer_summary
+          return unless (summary = parsed.dig("summary", "project_analyzers"))
+
+          emit_project_analyzer_summary_heading(summary)
+          emit_project_analyzer_aggregate_summaries(summary)
+          emit_project_analyzer_rule_summaries(summary)
+          stdout.puts
+        end
+
+        def emit_block_metadata(cop_name, offense)
+          emit_why_block(cop_name, offense[:why_it_matters])
+          emit_project_analyzer_triage(offense[:project_analyzer])
+        end
+
+        def emit_offense_lines(list)
+          list.each { |o| stdout.puts "  #{o[:path]}:#{o[:line]}:#{o[:column]} #{o[:message]}" }
+        end
+
+        def emit_project_analyzer_summary_heading(summary)
+          stdout.puts "Project analyzers: #{count_label(summary.fetch('finding_count'), 'finding')}, " \
+                      "#{count_label(summary.fetch('offense_count'), 'offense')} " \
+                      "(advisory signals; review in context)"
+        end
+
+        def emit_project_analyzer_rule_summaries(summary)
+          sorted_project_analyzer_rules(summary).each { |rule| stdout.puts "  #{project_analyzer_rule_summary(rule)}" }
+        end
+
+        def emit_project_analyzer_aggregate_summaries(summary)
+          ProjectAnalyzerSummaryAggregateFormatter.new(summary).lines.each { |line| stdout.puts line }
+        end
+
+        def project_analyzer_rule_summary(rule)
+          summary = "#{rule.fetch('cop_name')}: #{count_label(rule.fetch('finding_count'), 'finding')}, " \
+                    "#{count_label(rule.fetch('offense_count'), 'offense')}, status: #{rule.fetch('status')}, " \
+                    "confidence: #{rule.fetch('confidence')}, severity: #{rule.fetch('triage_severity')}"
+          [summary, mixed_breakdown_hint(rule)].compact.join("; ")
+        end
+
+        def mixed_breakdown_hint(rule)
+          ProjectAnalyzerSummaryBreakdownFormatter.new(rule).call
+        end
+
+        def sorted_offense_blocks
+          OffenseExtractor.offenses(parsed)
+                          .group_by { |offense| offense[:cop_name] }
+                          .sort_by { |cop_name, list| offense_block_sort_key(cop_name, list) }
+        end
+
+        def offense_block_sort_key(cop_name, list)
+          offense = representative_offense(list)
+          metadata = offense[:project_analyzer]
+          return [0, cop_name] unless metadata
+
+          [1, *project_analyzer_priority(metadata), cop_name]
+        end
+
+        def representative_offense(list)
+          list.min_by { |offense| project_analyzer_priority(offense[:project_analyzer] || {}) }
+        end
+
+        def sorted_project_analyzer_rules(summary)
+          Array(summary["rules"]).sort_by do |rule|
+            [*project_analyzer_priority(rule), rule.fetch("cop_name")]
+          end
+        end
+
+        def project_analyzer_priority(metadata)
+          ProjectAnalyzerTriagePriority.sort_key(metadata)
+        end
+
+        def emit_why_block(cop_name, why)
+          return if why.nil? || why.empty?
+
+          stdout.puts "  Why it matters: #{why}"
+          stdout.puts "  Run `metz-scan explain #{cop_name}` for details." if explainable?(cop_name)
+        end
+
+        def emit_project_analyzer_triage(metadata)
+          line = ProjectAnalyzerTriageFormatter.line(metadata)
+          return unless line
+
+          stdout.puts "  #{line}"
+        end
+
+        def count_label(count, noun)
+          "#{count} #{noun}#{'s' unless count == 1}"
+        end
+
+        def explainable?(cop_name)
+          cop_name.start_with?("Metz/")
+        end
+
+        def heading(name)
+          tty? ? "#{ANSI_BOLD}#{ANSI_CYAN}#{name}#{ANSI_RESET}" : name
+        end
+
+        def tty?
+          stdout.respond_to?(:tty?) && stdout.tty?
+        end
+      end
+    end
+  end
+end