metz-scan 0.5.3

data/lib/metz_scan/calibration/rubydex_drift_formatter.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MetzScan
+  module Calibration
+    class RubydexDriftFormatter
+      def initialize(summary, analyzers:)
+        @summary = summary
+        @analyzers = analyzers
+      end
+
+      def json
+        JSON.pretty_generate(payload)
+      end
+
+      def text
+        [header_lines, rule_lines, breakdown_lines].flatten.compact.join("\n")
+      end
+
+      private
+
+      attr_reader :summary, :analyzers
+
+      def payload
+        compact_identity.merge(compact_results)
+      end
+
+      def compact_identity
+        { "targets_file" => summary["targets_file"],
+          "targets" => target_names,
+          "analyzers" => analyzers }.compact
+      end
+
+      def compact_results
+        { "finding_count" => summary.fetch("finding_count"),
+          "offense_count" => summary.fetch("offense_count"),
+          "rules" => rules,
+          "breakdowns" => summary.fetch("breakdowns", {}) }
+      end
+
+      def header_lines
+        ["rubydex drift check",
+         targets_file_line,
+         "targets: #{target_names.join(', ')}",
+         "analyzers: #{analyzers.join(', ')}",
+         "findings: #{summary.fetch('finding_count')} (offenses: #{summary.fetch('offense_count')})"]
+      end
+
+      def target_names
+        summary.fetch("targets").map { |target| target.fetch("name") }
+      end
+
+      def targets_file_line
+        "targets file: #{summary['targets_file']}" if summary["targets_file"]
+      end
+
+      def rule_lines
+        return ["rules: none"] if rules.empty?
+
+        ["rules:", *rules.map { |rule| rule_line(rule) }]
+      end
+
+      def rules
+        summary.fetch("project_analyzers", {}).fetch("rules", [])
+      end
+
+      def rule_line(rule)
+        "  - #{rule.fetch('cop_name')}: #{rule.fetch('finding_count')} finding(s), " \
+          "#{rule.fetch('offense_count')} offense(s), status=#{rule.fetch('status', '?')}, " \
+          "confidence=#{rule.fetch('confidence', '?')}, severity=#{rule.fetch('triage_severity', '?')}"
+      end
+
+      def breakdown_lines
+        lines = [breakdown_line("confidence", breakdowns["confidence"]),
+                 breakdown_line("severity", breakdowns["triage_severity"])].compact
+        lines.empty? ? [] : ["breakdowns:", *lines]
+      end
+
+      def breakdowns
+        summary.fetch("breakdowns", {})
+      end
+
+      def breakdown_line(label, values)
+        return if values.to_a.empty?
+
+        "  - #{label}: #{values.map { |value| "#{value.fetch('value')}=#{value.fetch('finding_count')}" }.join(', ')}"
+      end
+    end
+  end
+end

data/lib/metz_scan/cli.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "version"
+
+module MetzScan
+  class CLI
+    SUBCOMMAND_SUMMARIES = {
+      "rules" => "List all Metz/* cops with their one-line rationale",
+      "explain" => "Print full metadata for a single Metz cop",
+      "scan" => "Run rubocop-metz against PATH and render a report",
+      "report" => "Re-render an existing rubocop-metz JSON report",
+      "project-analyzers" => "List project analyzers with status and default-output eligibility"
+    }.freeze
+
+    SUBCOMMANDS = SUBCOMMAND_SUMMARIES.keys.freeze
+
+    def self.start(argv = ARGV, stdout: $stdout, stderr: $stderr)
+      new(stdout: stdout, stderr: stderr).run(argv)
+    end
+
+    def initialize(stdout: $stdout, stderr: $stderr)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run(argv)
+      args = argv.dup
+      return show_help_and_fail if args.empty?
+
+      handle_global_flag(args.first) || dispatch(args)
+    end
+
+    private
+
+    attr_reader :stdout, :stderr
+
+    def handle_global_flag(arg)
+      case arg
+      when "-v", "--version" then print_version
+      when "-h", "--help"    then print_help_and_succeed
+      end
+    end
+
+    def print_version
+      stdout.puts MetzScan::VERSION
+      0
+    end
+
+    def print_help_and_succeed
+      stdout.puts help_text
+      0
+    end
+
+    def show_help_and_fail
+      stderr.puts help_text
+      1
+    end
+
+    def dispatch(args)
+      name = args.shift
+      return unknown_subcommand(name) unless SUBCOMMANDS.include?(name)
+
+      handler = subcommand_handler(name)
+      handler ? handler.run(args, stdout: stdout, stderr: stderr) : stub_subcommand(name)
+    end
+
+    SUBCOMMAND_HANDLERS = { "rules" => "Rules", "explain" => "Explain", "scan" => "Scan",
+                            "report" => "Report", "project-analyzers" => "ProjectAnalyzers" }.freeze
+    private_constant :SUBCOMMAND_HANDLERS
+
+    def subcommand_handler(name)
+      klass_name = SUBCOMMAND_HANDLERS[name]
+      return unless klass_name
+
+      require_relative "commands/#{name.tr('-', '_')}"
+      Commands.const_get(klass_name)
+    end
+
+    def stub_subcommand(name)
+      stderr.puts "metz-scan: subcommand '#{name}' is not yet implemented."
+      1
+    end
+
+    def unknown_subcommand(name)
+      stderr.puts "metz-scan: unknown subcommand '#{name}'."
+      stderr.puts help_text
+      1
+    end
+
+    def help_text
+      option_parser.help
+    end
+
+    def option_parser
+      OptionParser.new do |opts|
+        opts.banner = "Usage: metz-scan [--version] [--help] <subcommand> [<args>]"
+        append_subcommands(opts)
+        append_options(opts)
+      end
+    end
+
+    SUBCOMMAND_ROW = "    %<name>-9s %<summary>s"
+    private_constant :SUBCOMMAND_ROW
+
+    def append_subcommands(opts)
+      opts.separator ""
+      opts.separator "Subcommands:"
+      SUBCOMMAND_SUMMARIES.each { |name, summary| opts.separator(format(SUBCOMMAND_ROW, name: name, summary: summary)) }
+    end
+
+    def append_options(opts)
+      opts.separator ""
+      opts.separator "Options:"
+      opts.on("-v", "--version", "Print the metz-scan version and exit")
+      opts.on("-h", "--help",    "Show this help message and exit")
+    end
+  end
+end

data/lib/metz_scan/commands/explain.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "yaml"
+
+module MetzScan
+  module Commands
+    class Explain
+      USAGE = "Usage: metz-scan explain Metz/CopName"
+      NON_KNOB_KEYS = %w[Description VersionAdded StyleGuide Reference].freeze
+
+      def self.run(argv, stdout:, stderr:)
+        new(stdout: stdout, stderr: stderr).run(argv)
+      end
+
+      def initialize(stdout:, stderr:)
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      def run(argv)
+        args = parse_options(argv.dup)
+        return missing_argument_error if args.empty?
+
+        emit_or_error(args.first)
+      end
+
+      def emit_or_error(cop_name)
+        cop = lookup_metz_cop(cop_name)
+        return unknown_cop_error(cop_name) unless cop
+
+        emit(cop)
+        0
+      end
+
+      private
+
+      attr_reader :stdout, :stderr
+
+      def parse_options(argv)
+        OptionParser.new { |opts| opts.banner = USAGE }.parse!(argv)
+        argv
+      end
+
+      def lookup_metz_cop(name)
+        require "rubocop-metz"
+        cop = RuboCop::Cop::Registry.global.find_by_cop_name(name)
+        cop if cop && metz_cop?(cop)
+      end
+
+      def metz_cop?(cop)
+        cop.cop_name.start_with?("Metz/") && cop.respond_to?(:metz_metadata)
+      end
+
+      def missing_argument_error
+        stderr.puts "metz-scan explain: missing required COP_NAME argument."
+        stderr.puts USAGE
+        stderr.puts "Run `metz-scan rules` to see the list of available Metz cops."
+        1
+      end
+
+      def unknown_cop_error(name)
+        stderr.puts "metz-scan explain: no such cop '#{name}'."
+        stderr.puts "Run `metz-scan rules` to see the list of available Metz cops."
+        1
+      end
+
+      def emit(cop)
+        emit_heading(cop)
+        emit_why(cop)
+        emit_fix_safety(cop)
+        emit_suggested_next_moves(cop)
+        emit_configuration(cop)
+      end
+
+      def emit_heading(cop)
+        stdout.puts cop.cop_name
+        stdout.puts("=" * cop.cop_name.length)
+        stdout.puts
+      end
+
+      def emit_why(cop)
+        stdout.puts "Why it matters:"
+        stdout.puts "  #{cop.why_it_matters}"
+        stdout.puts
+      end
+
+      def emit_fix_safety(cop)
+        stdout.puts "Fix safety: #{cop.fix_safety}"
+        stdout.puts
+      end
+
+      def emit_suggested_next_moves(cop)
+        stdout.puts "Suggested next moves:"
+        cop.suggested_next_moves.each { |move| stdout.puts "  - #{move}" }
+        stdout.puts
+      end
+
+      def emit_configuration(cop)
+        knobs = configuration_knobs(cop.cop_name)
+        return if knobs.empty?
+
+        stdout.puts "Configuration:"
+        knobs.each { |key, value| stdout.puts "  #{key}: #{format_value(value)}" }
+      end
+
+      def configuration_knobs(cop_name)
+        entry = default_config[cop_name] || {}
+        entry.except(*NON_KNOB_KEYS)
+      end
+
+      def default_config
+        @default_config ||= YAML.load_file(default_config_path)
+      end
+
+      def default_config_path
+        RuboCop::Metz::Plugin.new.rules(nil).value.to_s
+      end
+
+      def format_value(value)
+        case value
+        when Array then value.empty? ? "[]" : value.join(", ")
+        else value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/commands/project_analyzers.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+require_relative "scan/project_analyzer_runner"
+
+module MetzScan
+  module Commands
+    class ProjectAnalyzers
+      USAGE = "Usage: metz-scan project-analyzers [--json]"
+
+      def self.run(argv, stdout:, stderr:)
+        new(stdout: stdout, stderr: stderr).run(argv)
+      end
+
+      def initialize(stdout:, stderr:)
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      def run(argv)
+        options = parse_options(argv)
+        return 1 unless options
+
+        entries = analyzer_entries
+        options[:json] ? emit_json(entries) : emit_table(entries)
+        0
+      end
+
+      private
+
+      attr_reader :stdout, :stderr
+
+      def parse_options(argv)
+        options = { json: false }
+        OptionParser.new { |opts| configure_options(opts, options) }.parse!(argv)
+        options
+      rescue OptionParser::ParseError => e
+        parse_error(e)
+      end
+
+      def parse_error(error)
+        stderr.puts error.message
+        stderr.puts option_parser.help
+        nil
+      end
+
+      def configure_options(opts, options)
+        opts.banner = USAGE
+        opts.on("--json", "Emit a JSON array of project analyzers") { options[:json] = true }
+      end
+
+      def option_parser
+        OptionParser.new { |opts| configure_options(opts, {}) }
+      end
+
+      def analyzer_entries
+        Scan::ProjectAnalyzerRunner::ANALYZERS.map { |analyzer| analyzer_entry(analyzer) }
+      end
+
+      def analyzer_entry(analyzer)
+        { name: analyzer::RULE_ID, status: analyzer::PROJECT_ANALYZER_STATUS,
+          default_output: Scan::ProjectAnalyzerRunner.default_output_analyzer?(analyzer),
+          confidence: analyzer::CONFIDENCE, triage_severity: analyzer::TRIAGE_SEVERITY,
+          triage_summary: analyzer::TRIAGE_SUMMARY, why_it_matters: analyzer::WHY,
+          suggested_next_moves: analyzer::SUGGESTED_NEXT_MOVES }
+      end
+
+      def emit_json(entries)
+        stdout.puts JSON.generate(entries)
+      end
+
+      def emit_table(entries)
+        widths = column_widths(entries)
+        stdout.puts row(%w[ANALYZER STATUS DEFAULT CONFIDENCE TRIAGE], widths)
+        stdout.puts row(widths.map { |_key, width| "-" * width }, widths)
+        entries.each { |entry| stdout.puts entry_row(entry, widths) }
+      end
+
+      def column_widths(entries)
+        { name: max_width(entries, :name, "ANALYZER"), status: max_width(entries, :status, "STATUS"),
+          default: "DEFAULT".length, confidence: max_width(entries, :confidence, "CONFIDENCE"),
+          triage: max_width(entries, :triage_severity, "TRIAGE") }
+      end
+
+      def max_width(entries, key, header)
+        [header.length, entries.map { |entry| entry.fetch(key).length }.max].max
+      end
+
+      def entry_row(entry, widths)
+        row([entry.fetch(:name), entry.fetch(:status), default_label(entry),
+             entry.fetch(:confidence), entry.fetch(:triage_severity)], widths)
+      end
+
+      def default_label(entry)
+        entry.fetch(:default_output) ? "yes" : "no"
+      end
+
+      def row(values, widths)
+        values.zip(widths.values).map { |value, width| format("%-#{width}s", value) }.join("  ").rstrip
+      end
+    end
+  end
+end

data/lib/metz_scan/commands/report.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+require_relative "scan/runner"
+require_relative "scan/compliance_scorecard"
+require_relative "scan/text_renderer"
+require_relative "scan/sarif_renderer"
+require_relative "scan/github_annotations_renderer"
+
+module MetzScan
+  module Commands
+    class Report
+      USAGE = "Usage: metz-scan report PATH/TO/JSON [--format text|json|sarif|gh-annotations]"
+      VALID_FORMATS = %w[text json sarif gh-annotations].freeze
+      RENDERERS = { "sarif" => Scan::SarifRenderer, "gh-annotations" => Scan::GithubAnnotationsRenderer }.freeze
+      DEFAULT_FORMAT = "text"
+
+      Options = Struct.new(:format, :path, keyword_init: true)
+
+      def self.run(argv, stdout:, stderr:)
+        new(stdout: stdout, stderr: stderr).run(argv)
+      end
+
+      def initialize(stdout:, stderr:)
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      def run(argv)
+        options = parse_options(argv)
+        validate(options) || emit(options)
+      rescue OptionParser::ParseError => e
+        parser_error(e)
+      end
+
+      private
+
+      attr_reader :stdout, :stderr
+
+      def parse_options(argv)
+        flags = { format: DEFAULT_FORMAT }
+        rest = OptionParser.new { |opts| configure_parser(opts, flags) }.parse(argv)
+        Options.new(**flags, path: rest.first)
+      end
+
+      def configure_parser(opts, flags)
+        opts.banner = USAGE
+        opts.on("--format FORMAT", "Output format: text (default), json, sarif, gh-annotations") do |format|
+          flags[:format] = format
+        end
+      end
+
+      def validate(options)
+        return missing_path_arg unless options.path
+        return missing_file(options.path) unless File.file?(options.path)
+
+        invalid_format(options.format) unless VALID_FORMATS.include?(options.format)
+      end
+
+      def emit(options)
+        parsed = load_json(options.path)
+        return parsed if parsed.is_a?(Integer)
+
+        render(parsed, options.format)
+        Scan::Runner.exit_code_for(parsed)
+      end
+
+      def load_json(path)
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        invalid_json(path, e.message)
+      end
+
+      def render(parsed, format)
+        return render_json(parsed) if format == "json"
+
+        RENDERERS.fetch(format, Scan::TextRenderer).new(stdout, parsed).render
+      end
+
+      def render_json(parsed)
+        Scan::ComplianceScorecard.add_to_summary!(parsed)
+        stdout.puts JSON.generate(parsed)
+      end
+
+      def parser_error(err)
+        stderr.puts "metz-scan report: #{err.message}"
+        stderr.puts USAGE
+        1
+      end
+
+      def missing_path_arg
+        stderr.puts "metz-scan report: missing PATH argument."
+        stderr.puts USAGE
+        1
+      end
+
+      def missing_file(path)
+        stderr.puts "metz-scan report: no such file: #{path}"
+        1
+      end
+
+      def invalid_format(fmt)
+        stderr.puts "metz-scan report: invalid --format '#{fmt}'. Valid formats: text, json, sarif, gh-annotations."
+        1
+      end
+
+      def invalid_json(path, detail)
+        stderr.puts "metz-scan report: invalid JSON in #{path}: #{detail}"
+        1
+      end
+    end
+  end
+end

data/lib/metz_scan/commands/rules.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+module MetzScan
+  module Commands
+    class Rules
+      ANSI_RESET = "\e[0m"
+      ANSI_BOLD = "\e[1m"
+      ANSI_CYAN = "\e[36m"
+      ANSI_GREY = "\e[90m"
+
+      USAGE = "Usage: metz-scan rules [--json]"
+
+      def self.run(argv, stdout:, stderr:)
+        new(stdout: stdout, stderr: stderr).run(argv)
+      end
+
+      def initialize(stdout:, stderr:)
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      def run(argv)
+        options = parse_options(argv)
+        cops = load_cops
+        options[:json] ? emit_json(cops) : emit_table(cops)
+        0
+      end
+
+      private
+
+      attr_reader :stdout, :stderr
+
+      def parse_options(argv)
+        options = { json: false }
+        OptionParser.new { |opts| configure_options(opts, options) }.parse!(argv)
+        options
+      end
+
+      def configure_options(opts, options)
+        opts.banner = USAGE
+        opts.on("--json", "Emit a JSON array of all Metz cops") { options[:json] = true }
+      end
+
+      def load_cops
+        require "rubocop-metz"
+        RuboCop::Cop::Registry.global.cops.select { |cop| cop.cop_name.start_with?("Metz/") }.sort_by(&:cop_name)
+      end
+
+      def emit_json(cops)
+        stdout.puts JSON.generate(cops.map { |cop| json_entry(cop) })
+      end
+
+      def json_entry(cop)
+        { name: cop.cop_name, why_it_matters: cop.why_it_matters,
+          fix_safety: cop.fix_safety.to_s, suggested_next_moves: Array(cop.suggested_next_moves) }
+      end
+
+      def emit_table(cops)
+        name_width = cops.map { |cop| cop.cop_name.length }.max
+        colorize = tty?
+        stdout.puts header_row(name_width, colorize)
+        stdout.puts separator_row(name_width, colorize)
+        cops.each { |cop| stdout.puts data_row(cop, name_width, colorize) }
+      end
+
+      def tty?
+        stdout.respond_to?(:tty?) && stdout.tty?
+      end
+
+      def header_row(name_width, colorize)
+        decorate(format("%-#{name_width}s  %s", "COP", "WHY IT MATTERS"), ANSI_BOLD, colorize)
+      end
+
+      def separator_row(name_width, colorize)
+        dashes = ("-" * name_width)
+        decorate("#{dashes}  #{'-' * 14}", ANSI_GREY, colorize)
+      end
+
+      def data_row(cop, name_width, colorize)
+        colored_name = decorate(format("%-#{name_width}s", cop.cop_name), ANSI_CYAN, colorize)
+        "#{colored_name}  #{cop.why_it_matters}"
+      end
+
+      def decorate(text, code, colorize)
+        colorize ? "#{code}#{text}#{ANSI_RESET}" : text
+      end
+    end
+  end
+end