rubocop-metz 0.5.2

data/lib/metz_scan/commands/scan.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+require_relative "../version"
+require_relative "scan/compliance_scorecard"
+require_relative "scan/runner"
+require_relative "scan/project_analyzer_runner"
+require_relative "scan/text_renderer"
+require_relative "scan/sarif_renderer"
+require_relative "scan/github_annotations_renderer"
+require_relative "scan/auto_fix"
+
+module MetzScan
+  module Commands
+    class ScanOptions
+      USAGE = "Usage: metz-scan scan PATH... [--format text|json|sarif|gh-annotations] " \
+              "[--all-cops] [--project-analyzers] [--auto-fix [--unsafe] [--dry-run]]"
+      VALID_FORMATS = %w[text json sarif gh-annotations].freeze
+      DEFAULT_FORMAT = "text"
+
+      Options = Struct.new(:format, :paths, :all_cops, :project_analyzers, :auto_fix, :unsafe, :dry_run, :help,
+                           keyword_init: true)
+
+      def self.parse(argv)
+        new.parse(argv)
+      end
+
+      def self.help
+        new.help
+      end
+
+      def parse(argv)
+        flags = default_flags
+        paths = option_parser(flags).parse(argv)
+        Options.new(**flags, paths: paths)
+      end
+
+      def help
+        option_parser(default_flags).help
+      end
+
+      private
+
+      def default_flags
+        { format: DEFAULT_FORMAT, all_cops: false, project_analyzers: false, auto_fix: false, unsafe: false,
+          dry_run: false, help: false }
+      end
+
+      def option_parser(flags)
+        OptionParser.new(USAGE) { |opts| configure_parser(opts, flags) }
+      end
+
+      def configure_parser(opts, flags)
+        configure_format_parser(opts, flags)
+        configure_cop_selection_parser(opts, flags)
+        configure_project_analyzer_parser(opts, flags)
+        configure_auto_fix_parser(opts, flags)
+        configure_help_parser(opts, flags)
+      end
+
+      def configure_format_parser(opts, flags)
+        opts.on("--format FORMAT", "Output format: text (default), json, sarif, gh-annotations") do |format|
+          flags[:format] = format
+        end
+      end
+
+      def configure_cop_selection_parser(opts, flags)
+        opts.on("--all-cops", "Run the full RuboCop suite instead of Metz/* cops by default") do
+          flags[:all_cops] = true
+        end
+      end
+
+      def configure_project_analyzer_parser(opts, flags)
+        opts.on("--project-analyzers", "Include all opt-in project analyzer findings") do
+          flags[:project_analyzers] = true
+        end
+      end
+
+      def configure_auto_fix_parser(opts, flags)
+        opts.on("--auto-fix", "Apply RuboCop's safe fixes (delegates to rubocop -a)") { flags[:auto_fix] = true }
+        opts.on("--unsafe", "With --auto-fix, also apply unsafe fixes (rubocop -A)") { flags[:unsafe] = true }
+        opts.on("--dry-run", "With --auto-fix, print diff without modifying files") { flags[:dry_run] = true }
+      end
+
+      def configure_help_parser(opts, flags)
+        opts.on("-h", "--help", "Show this help message and exit") { flags[:help] = true }
+      end
+    end
+
+    class Scan
+      USAGE = ScanOptions::USAGE
+      VALID_FORMATS = ScanOptions::VALID_FORMATS
+      RENDERERS = { "sarif" => SarifRenderer, "gh-annotations" => GithubAnnotationsRenderer }.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)
+        handle_options(parse_options(argv))
+      rescue OptionParser::ParseError => e
+        parser_error(e)
+      rescue Runner::Error => e
+        runner_error(e)
+      end
+
+      private
+
+      attr_reader :stdout, :stderr
+
+      def handle_options(options)
+        return print_help if options.help
+
+        validate(options) || dispatch(options)
+      end
+
+      def parse_options(argv)
+        ScanOptions.parse(argv)
+      end
+
+      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
+
+      def dispatch(options)
+        return AutoFix.new(stdout: stdout, stderr: stderr).run(options) if options.auto_fix
+
+        scan(options)
+      end
+
+      def scan(options)
+        parsed = Runner.invoke(options.paths, all_cops: options.all_cops, stderr: stderr)
+        merge_project_analyzers(parsed, options)
+        add_compliance_summary(parsed)
+        render(parsed, options.format)
+        Runner.exit_code_for(parsed)
+      end
+
+      def add_compliance_summary(parsed)
+        ComplianceScorecard.add_to_summary!(parsed)
+      end
+
+      def merge_project_analyzers(parsed, options)
+        ProjectAnalyzerRunner.merge!(parsed, options.paths, **project_analyzer_options(options))
+      end
+
+      def project_analyzer_options(options)
+        { default_output: !options.project_analyzers }
+      end
+
+      def render(parsed, format)
+        return stdout.puts JSON.generate(parsed) if format == "json"
+
+        RENDERERS.fetch(format, TextRenderer).new(stdout, parsed).render
+      end
+
+      def parser_error(err)
+        stderr.puts "metz-scan scan: #{err.message}"
+        stderr.puts USAGE
+        1
+      end
+
+      def print_help
+        stdout.puts ScanOptions.help
+        0
+      end
+
+      def missing_path_arg
+        stderr.puts "metz-scan scan: missing PATH argument."
+        stderr.puts USAGE
+        1
+      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
+      end
+
+      def invalid_format(fmt)
+        stderr.puts "metz-scan scan: invalid --format '#{fmt}'. Valid formats: text, json, sarif, gh-annotations."
+        1
+      end
+
+      def runner_error(err)
+        stderr.puts "metz-scan scan: RuboCop failed: #{err.message}"
+        2
+      end
+    end
+  end
+end

data/lib/metz_scan/project_index/null_backend.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MetzScan
+  class ProjectIndex
+    class NullBackend
+      def initialize(reason:)
+        @reason = reason
+      end
+
+      attr_reader :reason
+
+      def name = :null
+
+      def available? = false
+
+      def indexed_files = []
+
+      def index_errors = []
+
+      def diagnostics = []
+
+      def declarations = []
+
+      def method_declarations = []
+
+      def documents = []
+
+      def descendants_of(_name) = []
+
+      def constant_references_to(_name) = []
+
+      def search(_query) = []
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MetzScan
+  class ProjectIndex
+    class RubydexBackend
+      module FileDiscovery
+        RUBY_GLOB = "**/*.rb"
+        private_constant :RUBY_GLOB
+
+        def ruby_files_for(paths)
+          paths.flat_map { |path| ruby_files_under(path) }.uniq.sort
+        end
+
+        def workspace_path_for(paths)
+          expanded = File.expand_path(paths.first || Dir.pwd)
+          return expanded if File.directory?(expanded)
+
+          File.dirname(expanded)
+        end
+
+        private
+
+        def ruby_files_under(path)
+          expanded = File.expand_path(path)
+          return Dir.glob(File.join(expanded, RUBY_GLOB)) if File.directory?(expanded)
+          return [expanded] if File.file?(expanded) && File.extname(expanded) == ".rb"
+
+          []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module MetzScan
+  class ProjectIndex
+    class RubydexBackend
+      module LocationFormatting
+        def path_from_location(location)
+          return unless location
+
+          path_from_file_location(location) || path_from_uri_location(location) || location.to_s
+        end
+
+        def path_from_file_location(location)
+          location.to_file_path if location.respond_to?(:to_file_path)
+        rescue StandardError
+          nil
+        end
+
+        def path_from_uri_location(location)
+          path_from_uri(location.uri) if location.respond_to?(:uri)
+        end
+
+        def path_from_uri(uri)
+          string = uri.to_s
+          return URI(string).path if string.start_with?("file:")
+
+          string
+        rescue URI::InvalidURIError
+          string
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module MetzScan
+  class ProjectIndex
+    class RubydexBackend
+      module MethodDeclarations
+        def method_declarations
+          method_declaration_entries.sort_by do |declaration|
+            [declaration.owner_name.to_s, declaration.method_identity.to_s, declaration.path.to_s,
+             declaration.line.to_i]
+          end
+        end
+
+        private
+
+        def method_declaration_entries
+          graph.declarations.select { |declaration| method_declaration?(declaration) }
+                            .filter_map { |declaration| method_declaration_for(declaration) }
+        end
+
+        def method_declaration?(declaration)
+          defined?(Rubydex::Method) && declaration.instance_of?(Rubydex::Method)
+        end
+
+        def method_declaration_for(declaration)
+          attributes = method_declaration_attributes(declaration)
+          MethodDeclaration.new(**attributes) if attributes
+        end
+
+        def method_declaration_attributes(declaration)
+          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))
+        end
+
+        def method_owner_and_signature(declaration)
+          owner_attributes = method_owner_attributes(declaration)
+          [owner_attributes[:owner_name], owner_attributes[:signature]] if owner_attributes
+        end
+
+        def method_owner_attributes(declaration)
+          raw_owner_name = raw_owner_name_for(declaration)
+          signature = signature_for(declaration.name, raw_owner_name)
+          return unless raw_owner_name && signature
+
+          { owner_name: normalized_owner_name(raw_owner_name), signature: signature,
+            receiver_kind: receiver_kind_for(raw_owner_name) }
+        end
+
+        def identity_attributes(declaration, owner_attributes, method_name)
+          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) }
+        end
+
+        def location_attributes(declaration)
+          location = definition_display_location(declaration)
+          { path: path_from_location(location), line: line_from_location(location),
+            column: column_from_location(location) }
+        end
+
+        def raw_owner_name_for(declaration)
+          declaration.owner.name if declaration.respond_to?(:owner) && declaration.owner.respond_to?(:name)
+        end
+
+        def signature_for(name, owner_name)
+          name.to_s.delete_prefix("#{owner_name}#")
+              .delete_prefix("#{owner_name}.")
+              .delete_prefix("#{owner_name}::")
+        end
+
+        def method_name_for(signature)
+          signature.to_s.sub(/\(.*\)\z/, "")
+        end
+
+        def receiver_kind_for(raw_owner_name)
+          singleton_owner_name?(raw_owner_name) ? "singleton" : "instance"
+        end
+
+        def normalized_owner_name(raw_owner_name)
+          singleton_owner_name?(raw_owner_name) ? singleton_owner_name(raw_owner_name) : raw_owner_name
+        end
+
+        def singleton_owner_name?(raw_owner_name)
+          singleton_owner_name(raw_owner_name)
+        end
+
+        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
+
+          owner_name
+        end
+
+        def method_identity_for(receiver_kind, method_name)
+          "#{receiver_kind}:#{method_name}"
+        end
+
+        def definition_display_location(declaration)
+          definition = declaration.definitions.first if declaration.respond_to?(:definitions)
+          display_location_for(definition)
+        end
+
+        def line_from_location(location)
+          location.start_line if location.respond_to?(:start_line)
+        end
+
+        def column_from_location(location)
+          location.start_column if location.respond_to?(:start_column)
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/project_index/rubydex_backend.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "rubydex_backend/file_discovery"
+require_relative "rubydex_backend/location_formatting"
+require_relative "rubydex_backend/method_declarations"
+
+module MetzScan
+  class ProjectIndex
+    class RubydexBackend
+      include LocationFormatting
+      include MethodDeclarations
+      extend FileDiscovery
+
+      DECLARATION_KINDS = { "Rubydex::Class" => :class, "Rubydex::Module" => :module }.freeze
+
+      def self.available?
+        require "rubydex"
+        true
+      rescue LoadError
+        false
+      end
+
+      def self.unavailable_reason
+        "rubydex is not installed; enable the optional rubydex bundle group first"
+      end
+
+      def self.build(paths, workspace: false)
+        require "rubydex"
+
+        files = ruby_files_for(paths)
+        graph = Rubydex::Graph.new(workspace_path: workspace_path_for(paths))
+        index_errors = index_graph(graph, files, workspace)
+
+        new(graph: graph, indexed_files: files, index_errors: index_errors)
+      end
+
+      def self.index_graph(graph, files, workspace)
+        errors = workspace ? graph.index_workspace : graph.index_all(files)
+        graph.resolve
+        errors
+      end
+      private_class_method :index_graph
+
+      def initialize(graph:, indexed_files:, index_errors:)
+        @graph = graph
+        @indexed_files = indexed_files
+        @index_errors = Array(index_errors)
+      end
+
+      attr_reader :graph, :indexed_files, :index_errors
+
+      def name = :rubydex
+
+      def available? = true
+
+      def reason = nil
+
+      def diagnostics
+        graph.diagnostics.to_a
+      end
+
+      def declarations
+        entries = graph.declarations.map do |declaration|
+          Declaration.new(name: declaration.name, path: definition_path(declaration),
+                          kind: declaration_kind(declaration))
+        end
+
+        entries.sort_by { |declaration| [declaration.name.to_s, declaration.path.to_s] }
+      end
+
+      def documents
+        graph.documents.map { |document| path_from_uri(document.uri) }.compact.sort
+      end
+
+      def descendants_of(name)
+        declaration = graph[name]
+        return [] unless declaration.respond_to?(:descendants)
+
+        declaration.descendants.map(&:name).reject { |descendant| descendant == name }.sort
+      end
+
+      def constant_references_to(name)
+        declaration = graph[name]
+        return [] unless declaration.respond_to?(:references)
+
+        declaration.references.map { |reference| normalized_reference(reference) }.compact.sort_by do |reference|
+          [reference.path.to_s, reference.line.to_i, reference.column.to_i, reference.name.to_s]
+        end
+      end
+
+      def search(query)
+        graph.search(query).map(&:name).sort
+      end
+
+      private
+
+      def definition_path(declaration)
+        definition = declaration.definitions.first if declaration.respond_to?(:definitions)
+        path_from_display_location(definition)
+      end
+
+      def declaration_kind(declaration) = DECLARATION_KINDS[declaration.class.name]
+
+      def path_from_display_location(definition)
+        path_from_location(display_location_for(definition))
+      end
+
+      def display_location_for(definition)
+        location = definition&.location
+        return location.to_display if location.respond_to?(:to_display)
+
+        location
+      end
+
+      def normalized_reference(reference)
+        location = reference.location.to_display
+        Reference.new(**reference_attributes(reference, location))
+      end
+
+      def reference_attributes(reference, location)
+        { name: reference_name(reference), path: path_from_location(location),
+          line: location.start_line, column: location.start_column }
+      end
+
+      def reference_name(reference)
+        return reference.declaration.name if reference.respond_to?(:declaration)
+        return reference.name if reference.respond_to?(:name)
+
+        nil
+      end
+    end
+  end
+end

data/lib/metz_scan/project_index.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "project_index/null_backend"
+require_relative "project_index/rubydex_backend"
+
+module MetzScan
+  # Thin facade over optional project-wide indexes used by future analyzers.
+  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)
+    Reference = Struct.new(:name, :path, :line, :column, keyword_init: true)
+
+    class UnknownBackendError < StandardError; end
+    class UnavailableBackendError < StandardError; end
+
+    BACKENDS = %i[auto null rubydex].freeze
+    private_constant :BACKENDS
+
+    def self.build(paths, backend: :auto, workspace: false)
+      backend = backend.to_sym
+      raise UnknownBackendError, "unknown project index backend: #{backend}" unless BACKENDS.include?(backend)
+
+      new(build_backend(Array(paths), backend, workspace))
+    end
+
+    def self.build_backend(paths, backend, workspace)
+      case backend
+      when :auto then auto_backend(paths, workspace)
+      when :null then null_backend("project index disabled")
+      when :rubydex then rubydex_backend(paths, workspace)
+      end
+    end
+    private_class_method :build_backend
+
+    def self.auto_backend(paths, workspace)
+      return rubydex_backend(paths, workspace) if RubydexBackend.available?
+
+      null_backend(RubydexBackend.unavailable_reason)
+    end
+    private_class_method :auto_backend
+
+    def self.rubydex_backend(paths, workspace)
+      raise UnavailableBackendError, RubydexBackend.unavailable_reason unless RubydexBackend.available?
+
+      RubydexBackend.build(paths, workspace: workspace)
+    end
+    private_class_method :rubydex_backend
+
+    def self.null_backend(reason)
+      NullBackend.new(reason: reason)
+    end
+    private_class_method :null_backend
+
+    def initialize(backend)
+      @backend = backend
+    end
+
+    attr_reader :backend
+
+    def backend_name
+      backend.name
+    end
+
+    def available?
+      backend.available?
+    end
+
+    def reason
+      backend.reason
+    end
+
+    def indexed_files
+      backend.indexed_files
+    end
+
+    def index_errors
+      backend.index_errors
+    end
+
+    def diagnostics
+      backend.diagnostics
+    end
+
+    def declarations
+      backend.declarations
+    end
+
+    def method_declarations
+      backend.method_declarations
+    end
+
+    def documents
+      backend.documents
+    end
+
+    def descendants_of(name)
+      backend.descendants_of(name)
+    end
+
+    def constant_references_to(name)
+      backend.constant_references_to(name)
+    end
+
+    def search(query)
+      backend.search(query)
+    end
+  end
+end

data/lib/metz_scan/version.rb

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

data/lib/metz_scan.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "metz_scan/version"
+require_relative "metz_scan/cli"
+require_relative "metz_scan/project_index"