quality_gate 0.1.0

data/lib/quality_gate/config.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module QualityGate
+  # Reports a configuration file that could not be parsed or read.
+  class ConfigError < Error
+    attr_reader :path
+
+    def initialize(path:, cause_message:)
+      @path = path.dup.freeze
+      super("Could not load config #{@path}: #{cause_message}")
+    end
+  end
+
+  # Loads and exposes quality gate settings resolved against shipped defaults.
+  # rubocop:disable Metrics/ClassLength
+  class Config
+    DEFAULTS = {
+      format: "text",
+      files: [].freeze,
+      adapters: {
+        fast: ["rubocop"].freeze,
+        verify: %w[reek test_suite undercover].map!(&:freeze).freeze,
+        audit: %w[brakeman bundler_audit].map!(&:freeze).freeze
+      }.freeze,
+      commands: {
+        fast: {}.freeze,
+        verify: { test_suite: %w[bin/rails test].map!(&:freeze).freeze }.freeze,
+        audit: {}.freeze
+      }.freeze,
+      timeouts: { default: 120, rubocop: 10, test_suite: 120, undercover: 120 }.freeze,
+      coverage: nil,
+      compare_point: nil,
+      rubocop_config: nil
+    }.freeze
+    ADAPTER_LAYERS = %i[fast verify audit].freeze
+    COVERAGE_KEYS = %i[minimum_line minimum_branch].freeze
+    private_constant :ADAPTER_LAYERS, :COVERAGE_KEYS
+
+    class << self
+      def defaults = DEFAULTS
+
+      def load(dir:)
+        path = File.join(dir, ".quality_gate.yml")
+        return new(DEFAULTS) unless File.exist?(path)
+
+        load_file(path)
+      rescue Psych::Exception, SystemCallError, SystemStackError => e
+        fail ConfigError.new(path: path, cause_message: e.message) # rubocop:disable Style/SignalException
+      end
+
+      private
+
+      def symbolize_keys(value)
+        case value
+        when Hash
+          value.to_h { |key, child| [key.to_sym, symbolize_keys(child)] }
+        when Array
+          value.map { |child| symbolize_keys(child) }
+        else
+          value
+        end
+      end
+
+      def load_file(path)
+        document = YAML.safe_load(File.read(path))
+        validate_document(document, path)
+        overrides = symbolize_keys(document || {})
+        validate_known_settings(overrides, path)
+
+        new(
+          deep_merge(DEFAULTS, known_overrides(overrides)),
+          path: path,
+          unknown_keys: unknown_keys(overrides)
+        )
+      end
+
+      def known_overrides(overrides)
+        overrides.select { |key, _value| DEFAULTS.key?(key) }
+      end
+
+      def unknown_keys(overrides)
+        overrides.keys.reject { |key| DEFAULTS.key?(key) }.map(&:to_s)
+      end
+
+      def validate_known_settings(overrides, path) # rubocop:disable Metrics/AbcSize
+        validate_format(overrides[:format], path) if overrides.key?(:format)
+        validate_files(overrides[:files], path) if overrides.key?(:files)
+        validate_adapters(overrides[:adapters], path) if overrides.key?(:adapters)
+        validate_commands(overrides[:commands], path) if overrides.key?(:commands)
+        validate_coverage(overrides[:coverage], path) if overrides.key?(:coverage)
+        validate_compare_point(overrides[:compare_point], path) if overrides.key?(:compare_point)
+        validate_rubocop_config(overrides[:rubocop_config], path) if overrides.key?(:rubocop_config)
+      end
+
+      def validate_format(format, path)
+        return if %w[text json].include?(format)
+
+        fail ConfigError.new(path: path, cause_message: "format must be text or json") # rubocop:disable Style/SignalException
+      end
+
+      def validate_files(files, path)
+        unless files.is_a?(Array)
+          fail ConfigError.new(path: path, cause_message: "files must be an array") # rubocop:disable Style/SignalException
+        end
+
+        return if files.all? { |file| file.is_a?(String) && !file.empty? }
+
+        fail ConfigError.new( # rubocop:disable Style/SignalException
+          path: path,
+          cause_message: "files entries must be non-empty strings"
+        )
+      end
+
+      def validate_adapters(adapters, path)
+        unless adapters.is_a?(Hash)
+          fail ConfigError.new(path: path, cause_message: "adapters must be a mapping") # rubocop:disable Style/SignalException
+        end
+
+        invalid_keys = adapters.keys - ADAPTER_LAYERS
+        if invalid_keys.any?
+          fail ConfigError.new(path: path, cause_message: "adapters keys must be fast, verify, or audit") # rubocop:disable Style/SignalException
+        end
+
+        adapters.each do |layer, adapter_names|
+          validate_adapter_names(layer, adapter_names, path)
+        end
+      end
+
+      def validate_adapter_names(layer, adapter_names, path)
+        unless adapter_names.is_a?(Array)
+          fail ConfigError.new(path: path, cause_message: "adapters.#{layer} must be an array") # rubocop:disable Style/SignalException
+        end
+
+        return if adapter_names.all? { |name| name.is_a?(String) && !name.empty? }
+
+        fail ConfigError.new(path: path, cause_message: "adapters.#{layer} entries must be non-empty strings") # rubocop:disable Style/SignalException
+      end
+
+      def validate_commands(commands, path)
+        validate_layer_mapping(commands, "commands", path)
+
+        commands.each do |layer, layer_commands|
+          unless layer_commands.is_a?(Hash)
+            fail ConfigError.new(path: path, cause_message: "commands.#{layer} must be a mapping") # rubocop:disable Style/SignalException
+          end
+
+          layer_commands.each do |command_name, argv|
+            validate_command_argv(layer, command_name, argv, path)
+          end
+        end
+      end
+
+      def validate_layer_mapping(value, setting, path)
+        unless value.is_a?(Hash)
+          fail ConfigError.new(path: path, cause_message: "#{setting} must be a mapping") # rubocop:disable Style/SignalException
+        end
+
+        return if (value.keys - ADAPTER_LAYERS).empty?
+
+        cause = "#{setting} keys must be fast, verify, or audit"
+        fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+      end
+
+      def validate_command_argv(layer, command_name, argv, path)
+        unless argv.is_a?(Array) && argv.any?
+          cause = "commands.#{layer}.#{command_name} must be an argv array"
+          fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+        end
+
+        return if argv.all? { _1.is_a?(String) && !_1.empty? }
+
+        cause = "commands.#{layer}.#{command_name} entries must be non-empty strings"
+        fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+      end
+
+      def validate_compare_point(compare_point, path)
+        return if compare_point.nil?
+        return if compare_point.is_a?(String) && !compare_point.empty?
+
+        cause = "compare_point must be nil or a non-empty String"
+        fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+      end
+
+      def validate_coverage(coverage, path)
+        unless coverage.is_a?(Hash) && coverage.any?
+          cause = "coverage must be a non-empty mapping"
+          fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+        end
+
+        invalid_key = (coverage.keys - COVERAGE_KEYS).first
+        if invalid_key
+          cause = "unknown coverage key #{invalid_key}"
+          fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+        end
+
+        coverage.each do |key, value|
+          validate_coverage_value(key, value, path)
+        end
+      end
+
+      def validate_coverage_value(key, value, path)
+        unless value.is_a?(Numeric)
+          cause = "coverage.#{key} must be Numeric"
+          fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+        end
+
+        return if value.finite? && value.between?(0, 100)
+
+        cause = "coverage.#{key} must be within 0..100"
+        fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+      end
+
+      def validate_rubocop_config(rubocop_config, path)
+        return if rubocop_config.nil?
+        return if rubocop_config.is_a?(String) && !rubocop_config.empty?
+
+        fail ConfigError.new(path: path, cause_message: "rubocop_config must be nil or a non-empty String") # rubocop:disable Style/SignalException
+      end
+
+      def validate_document(document, path)
+        unless document.nil? || document.is_a?(Hash)
+          cause = "expected a mapping, got #{document.class}"
+          fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+        end
+
+        validate_keys(document, path)
+      end
+
+      def validate_keys(value, path)
+        case value
+        when Hash
+          value.each do |key, child|
+            validate_key(key, path)
+            validate_keys(child, path)
+          end
+        when Array
+          value.each { |child| validate_keys(child, path) }
+        end
+      end
+
+      def validate_key(key, path)
+        return if key.is_a?(String)
+
+        cause = "configuration keys must be strings, got #{key.class}"
+        fail ConfigError.new(path: path, cause_message: cause) # rubocop:disable Style/SignalException
+      end
+
+      def deep_merge(defaults, overrides)
+        defaults.merge(overrides) do |_key, default, override|
+          if default.is_a?(Hash) && override.is_a?(Hash)
+            deep_merge(default, override)
+          else
+            override
+          end
+        end
+      end
+    end
+
+    attr_reader :path, :unknown_keys
+
+    def initialize(settings, path: nil, unknown_keys: [])
+      @settings = deep_freeze(settings)
+      @path = path&.dup&.freeze
+      @unknown_keys = deep_freeze(unknown_keys)
+    end
+
+    def to_h = @settings
+
+    def fetch(key) = @settings.fetch(key)
+
+    private
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each do |key, child|
+          deep_freeze(key)
+          deep_freeze(child)
+        end
+      when Array
+        value.each { |child| deep_freeze(child) }
+      end
+
+      value.freeze
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/quality_gate/exit_code.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module QualityGate
+  # Provides stable process-independent result codes for command execution.
+  module ExitCode
+    CLEAN = 0
+    FINDINGS = 1
+    TOOL_FAILURE = 2
+
+    @all = [CLEAN, FINDINGS, TOOL_FAILURE].freeze
+
+    def self.all = @all
+  end
+end

data/lib/quality_gate/finding.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+QualityGate::Finding = Data.define(:tool, :file, :line, :rule, :severity, :message)
+
+QualityGate::Finding::SEVERITIES = %i[error warning info].freeze
+QualityGate::Finding::TOOL_FAILURE_RULE = "tool_failure"
+
+QualityGate::Finding.class_eval do
+  def initialize(**attributes)
+    super(
+      **attributes,
+      tool: copy_string(:tool, attributes.fetch(:tool)),
+      file: copy_string(:file, attributes.fetch(:file)),
+      line: validate_line(attributes.fetch(:line)),
+      rule: copy_string(:rule, attributes.fetch(:rule)),
+      message: copy_string(:message, attributes.fetch(:message))
+    )
+  end
+
+  def self.tool_failure(tool:, message:)
+    new(
+      tool: tool,
+      file: "",
+      line: 0,
+      rule: self::TOOL_FAILURE_RULE,
+      severity: :error,
+      message: message
+    )
+  end
+
+  def with(**attributes) = self.class.new(**to_h.merge(attributes))
+
+  def tool_failure? = rule == self.class::TOOL_FAILURE_RULE
+
+  private
+
+  def copy_string(member, value)
+    raise TypeError, "#{member} must be a String" unless value.is_a?(String)
+
+    value.dup.freeze
+  end
+
+  def validate_line(value)
+    raise TypeError, "line must be an Integer" unless value.is_a?(Integer)
+    raise ArgumentError, "line must be greater than or equal to 0" if value.negative?
+
+    value
+  end
+end
+# rubocop:enable Metrics/BlockLength

data/lib/quality_gate/hook_log.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "json"
+
+module QualityGate
+  # Reads the advisory health log written by the automatic hooks.
+  class HookLog
+    DEFAULT_PATH = "log/quality_gate_hooks.jsonl"
+    MAX_SCAN_BYTES = 1024 * 1024
+    MAX_LINE_BYTES = 64 * 1024
+    OUTCOMES = %w[
+      no_file skipped deleted clean findings unavailable
+      verify_skipped verify_debounced verify_clean verify_blocked verify_unavailable verify_cap
+    ].map!(&:freeze).freeze
+    private_constant :MAX_SCAN_BYTES, :MAX_LINE_BYTES, :OUTCOMES
+
+    attr_reader :path
+
+    def initialize(path:)
+      @path = path.dup.freeze
+    end
+
+    def recent(limit: 20)
+      return [] unless limit.positive?
+
+      with_log_file { |io| recent_records(io, limit) }
+    end
+
+    def unavailable_count(limit: 20)
+      recent(limit: limit).count { %w[unavailable verify_unavailable].include?(_1.fetch("outcome")) }
+    end
+
+    def warning_line(limit: 20)
+      count = unavailable_count(limit: limit)
+      return if count.zero?
+
+      "Warning: #{count} of the last #{limit} automatic checks could not run; " \
+        "check bundle install and the Quality Gate hook setup."
+    end
+
+    private
+
+    def with_log_file
+      expected = File.lstat(path)
+      return [] unless expected.file?
+
+      File.open(path, read_flags) do |io|
+        return [] unless same_regular_file?(io.stat, expected, File.lstat(path))
+
+        io.binmode
+        yield io
+      end
+    rescue SystemCallError, IOError
+      []
+    end
+
+    def recent_records(io, limit)
+      records = []
+      tail_bytes(io).split("\n".b).reverse_each do |line|
+        record = parse_line(line)
+        records << record if record
+        break if records.length >= limit
+      end
+      records.reverse
+    end
+
+    def read_flags
+      %i[NONBLOCK NOFOLLOW].reduce(File::RDONLY) do |flags, name|
+        File.const_defined?(name) ? flags | File.const_get(name) : flags
+      end
+    end
+
+    def same_regular_file?(opened, expected, current)
+      [opened, expected, current].all?(&:file?) &&
+        [opened.dev, opened.ino] == [expected.dev, expected.ino] &&
+        [opened.dev, opened.ino] == [current.dev, current.ino]
+    end
+
+    def tail_bytes(io)
+      size = io.stat.size
+      length = [size, MAX_SCAN_BYTES].min
+      offset = size - length
+      starts_at_boundary = line_boundary?(io, offset)
+      io.seek(offset, IO::SEEK_SET)
+      bytes = io.read(length) || "".b
+
+      discard_partial_line(bytes, starts_at_boundary)
+    end
+
+    def line_boundary?(io, offset)
+      return true if offset.zero?
+
+      io.seek(offset - 1, IO::SEEK_SET)
+      io.read(1) == "\n".b
+    end
+
+    def discard_partial_line(bytes, starts_at_boundary)
+      return bytes if starts_at_boundary
+
+      newline = bytes.index("\n".b)
+      return "".b unless newline
+
+      bytes.byteslice(newline + 1, bytes.bytesize - newline - 1)
+    end
+
+    def parse_line(line)
+      return if line.bytesize > MAX_LINE_BYTES
+
+      line = line.dup.force_encoding(Encoding::UTF_8)
+      return unless line.valid_encoding?
+
+      record = JSON.parse(line)
+      record if valid_record?(record)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def valid_record?(record)
+      record.is_a?(Hash) &&
+        record["ts"].is_a?(String) &&
+        record.key?("file") &&
+        (record["file"].nil? || record["file"].is_a?(String)) &&
+        OUTCOMES.include?(record["outcome"]) &&
+        valid_duration?(record["duration_ms"])
+    end
+
+    def valid_duration?(duration)
+      duration.is_a?(Numeric) && duration.finite? && duration >= 0
+    end
+  end
+end

data/lib/quality_gate/init_command.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module QualityGate
+  # Parses and executes the framework-independent project initializer.
+  class InitCommand
+    class << self
+      def run(arguments, stdout:, stderr:, dir:)
+        installer(parse(arguments), dir: dir, stdout: stdout).call
+      rescue OptionParser::ParseError, ArgumentError => e
+        report_failure(e, stderr)
+      end
+
+      private
+
+      def parse(arguments)
+        reject_format!(arguments)
+        options = { profile: "ruby", skip_coverage: false, agents: false, pretend: false }
+        option_parser(options).parse!(arguments)
+        raise OptionParser::InvalidOption, arguments.join(" ") if arguments.any?
+
+        options
+      end
+
+      def installer(options, dir:, stdout:)
+        require_relative "installer"
+
+        Installer.new(destination_root: dir, options: options, stdout: stdout)
+      end
+
+      def reject_format!(arguments = nil)
+        return unless arguments.nil? || arguments.any? { _1 == "--format" || _1.start_with?("--format=") }
+
+        raise OptionParser::InvalidArgument, "init does not support --format; init output is text only"
+      end
+
+      def option_parser(options)
+        OptionParser.new.tap { |parser| parser_definitions(parser, options) }
+      end
+
+      def parser_definitions(parser, options)
+        profile_options(parser, options)
+        test_options(parser, options)
+        boolean_options(parser, options)
+        parser.on("--format FORMAT") { reject_format! }
+        parser.on("-h", "--help") { options[:help] = true }
+      end
+
+      def profile_options(parser, options)
+        parser.on("--profile PROFILE", %w[ruby]) { |profile| options[:profile] = profile }
+        parser.on("--test-framework FRAMEWORK", %w[minitest rspec]) do |framework|
+          options[:test_framework] = framework
+        end
+      end
+
+      def test_options(parser, options)
+        parser.on("--test-helper PATH") { |path| options[:test_helper] = path }
+        parser.on("--test-command COMMAND") { |command| options[:test_command] = command }
+      end
+
+      def boolean_options(parser, options)
+        parser.on("--skip-coverage") { options[:skip_coverage] = true }
+        parser.on("--agents") { options[:agents] = true }
+        parser.on("--pretend") { options[:pretend] = true }
+      end
+
+      def report_failure(error, stderr)
+        report_error(error, stderr)
+        write_line(stderr, "Usage: quality_gate init [options]") if error.is_a?(OptionParser::ParseError)
+        ExitCode::TOOL_FAILURE
+      end
+
+      def report_error(error, stderr)
+        write_line(stderr, "Error: #{error.message}")
+        ExitCode::TOOL_FAILURE
+      rescue StandardError
+        write_line(stderr, "Error: quality_gate init failed")
+        ExitCode::TOOL_FAILURE
+      end
+
+      def write_line(io, message)
+        io.puts(message)
+        true
+      rescue StandardError
+        false
+      end
+    end
+  end
+end