quality_gate 0.1.0

data/lib/generators/quality_gate/install/templates/ruby_agents_section.md.tt

@@ -0,0 +1,15 @@
+<!-- quality_gate agent contract — start -->
+## Quality Gate agent contract
+
+Run `bundle exec quality_gate fast` after Ruby edits. Installed Claude Code hooks can run `bundle exec quality_gate verify` automatically at session end; other clients, including Codex, must run `bundle exec quality_gate verify` manually before you finish a change. Run `bundle exec quality_gate audit` before you merge security-sensitive work.
+
+Fix findings before you continue editing.
+
+- Exit 0 means the gate ran clean.
+- Exit 1 means the gate reported findings and no tool failures.
+- Exit 2 means the gate could not complete cleanly because of invalid input, configuration, or another tool failure.
+
+The default fast path keeps feedback tight with a 10-second RuboCop timeout. Verify and audit keep the broader suite work on the 120-second default timeout.
+
+To reinstall the Ruby profile's agent integration, run `bundle exec quality_gate init --profile ruby --agents`.
+<!-- quality_gate agent contract — end -->

data/lib/generators/quality_gate/install/templates/ruby_quality_gate.yml.tt

@@ -0,0 +1,40 @@
+# # Output format: "text" or "json".
+# format: text
+#
+# # Optional file paths passed to RuboCop and Reek; empty means the project scope.
+# files: []
+#
+# # Plain Ruby adapters run by each gate, in order.
+adapters:
+  fast:
+    - rubocop
+  verify:
+    - reek
+    - test_suite
+<% if @profile.coverage? %>    - undercover
+<% end %>  audit:
+    - bundler_audit
+
+# # Command overrides by gate.
+commands:
+  fast: {}
+  verify:
+    test_suite:
+<% @profile.test_command.each do |argument| %>      - <%= JSON.generate(argument) %>
+<% end %>  audit: {}
+
+# # Command timeouts in seconds.
+timeouts:
+  default: 120
+  rubocop: 10
+  test_suite: 120
+  undercover: 120
+
+# # Aggregate SimpleCov budgets. Leave the entire mapping commented to disable coverage budgeting.
+# coverage:
+
+# # Git ref or commit for Undercover; blank selects the comparison point automatically.
+# compare_point:
+
+# # Explicit RuboCop config path; blank uses host config when present, otherwise the shipped config.
+# rubocop_config:

data/lib/generators/quality_gate/install/templates/ruby_rubocop.yml.tt

@@ -0,0 +1 @@
+inherit_gem: { quality_gate: config/ruby.yml }

data/lib/generators/quality_gate/install/templates/ruby_simplecov.rb.tt

@@ -0,0 +1,11 @@
+if ENV['COVERAGE'] == '1'
+  require 'simplecov'
+  require 'undercover/simplecov_formatter'
+
+  SimpleCov.formatter = SimpleCov::Formatter::Undercover
+  SimpleCov.start do
+    enable_coverage :branch
+    add_filter '/test/'
+    add_filter '/spec/'
+  end
+end

data/lib/generators/quality_gate/install/templates/simplecov.rb.tt

@@ -0,0 +1,10 @@
+if ENV['COVERAGE'] == '1'
+  require 'simplecov'
+  require 'undercover/simplecov_formatter'
+
+  SimpleCov.formatter = SimpleCov::Formatter::Undercover
+  SimpleCov.start do
+    enable_coverage :branch
+    add_filter '/test/'
+  end
+end

data/lib/generators/quality_gate/install/templates/strong_migrations.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'strong_migrations'
+
+<%= strong_migrations_provenance %>
+<% if (version = strong_migrations_baseline) -%>
+StrongMigrations.start_after = <%= migration_version_literal(version) %>
+<% else -%>
+# Set StrongMigrations.start_after after the first migration exists.
+<% end -%>

data/lib/quality_gate/adapter.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+require "English"
+require "open3"
+
+module QualityGate
+  # Raised when adapter output cannot be parsed into findings.
+  class ParseError < Error
+    attr_reader :tool
+
+    def initialize(tool:, reason:)
+      @tool = tool.dup.freeze
+      super("Could not parse #{@tool} output: #{reason}")
+    end
+  end
+
+  # Executes one quality tool without involving a shell and normalizes failures.
+  # rubocop:disable Metrics/ClassLength
+  class Adapter
+    STDERR_LINE_LIMIT = 20
+    TERMINATE_GRACE_SECONDS = 0.2
+
+    def initialize(config:, files: [], diagnostic_io: $stderr)
+      @config = config
+      @files = files.map { copy_string(_1) }.freeze
+      @diagnostic_io = diagnostic_io
+    end
+
+    def call
+      tool = name
+      stderr = +""
+      stdout, stderr, = capture(validated_command, resolved_timeout(tool))
+      findings = parse(stdout)
+      validate_findings!(findings, expected_tool: tool)
+      findings
+    rescue StandardError => e
+      [failure_finding(tool, e, stderr)]
+    end
+
+    def name
+      raise NotImplementedError, "#{self.class} must implement #name"
+    end
+
+    def command
+      raise NotImplementedError, "#{self.class} must implement #command"
+    end
+
+    def parse(_stdout)
+      raise NotImplementedError, "#{self.class} must implement #parse"
+    end
+
+    def timeout
+      resolved_timeout(name)
+    end
+
+    private
+
+    attr_reader :config, :diagnostic_io, :files
+
+    def validated_command
+      value = command
+      return value if value.is_a?(Array) && value.all?(String)
+
+      raise ArgumentError, "command must be an array of strings"
+    end
+
+    def validate_findings!(findings, expected_tool:)
+      raise TypeError, "parse must return an array of findings" unless findings.is_a?(Array)
+
+      findings.each do |finding|
+        raise TypeError, "parse must return finding objects" unless finding.is_a?(Finding)
+        unless finding.tool == expected_tool
+          raise ArgumentError, "finding tool must match adapter #{expected_tool.inspect}"
+        end
+
+        unless Finding::SEVERITIES.include?(finding.severity)
+          raise ArgumentError, "invalid finding severity #{finding.severity.inspect}"
+        end
+      end
+    end
+
+    def capture(argv, timeout_seconds, env: {}, combine_output: false)
+      stdin, stdout, stderr, wait_thread = open_capture(argv, env, combine_output)
+      resources = {
+        process_group_id: -wait_thread.pid,
+        wait_thread:,
+        stdin:,
+        stdout:,
+        stderr:,
+        readers: {}
+      }
+      deadline = monotonic_deadline(timeout_seconds)
+
+      stdin.close
+      register_readers(resources)
+
+      wait_for_process(wait_thread, timeout_seconds, deadline)
+      stdout_text = captured_output(resources, :stdout, timeout_seconds, deadline)
+      stderr_text = captured_output(resources, :stderr, timeout_seconds, deadline)
+
+      [stdout_text, stderr_text, wait_thread.value]
+    ensure
+      cleanup_capture(resources, $ERROR_INFO)
+    end
+
+    def open_capture(argv, env, combine_output)
+      return merged_capture(env, argv) if combine_output
+
+      Open3.popen3(env, *argv, pgroup: true)
+    end
+
+    def merged_capture(env, argv)
+      stdin, output, wait_thread = Open3.popen2e(env, *argv, pgroup: true)
+      [stdin, output, nil, wait_thread]
+    end
+
+    def register_readers(resources)
+      readers = resources.fetch(:readers)
+      readers[:stdout] = reader_thread(resources.fetch(:stdout))
+      stderr = resources.fetch(:stderr)
+      readers[:stderr] = reader_thread(stderr) if stderr
+    end
+
+    def captured_output(resources, stream, timeout_seconds, deadline)
+      reader = resources.fetch(:readers).fetch(stream, nil)
+      return +"" unless reader
+
+      fetch_reader_output(reader, timeout_seconds, deadline)
+    end
+
+    def wait_for_process(wait_thread, timeout_seconds, deadline)
+      return if wait_thread.join(remaining_before(deadline))
+
+      raise TimeoutError, "timeout after #{timeout_seconds} seconds"
+    end
+
+    def fetch_reader_output(reader, timeout_seconds, deadline)
+      return reader.value if reader.join(remaining_before(deadline))
+
+      raise TimeoutError, "timeout after #{timeout_seconds} seconds"
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    def cleanup_capture(resources, active_exception)
+      return unless resources
+
+      terminate_process_group(resources, active_exception) if active_exception
+      cleanup_action(active_exception) { close_pipe(resources.fetch(:stdin)) }
+      cleanup_action(active_exception) { close_pipe(resources.fetch(:stdout)) }
+      cleanup_action(active_exception) { close_pipe(resources.fetch(:stderr)) }
+      cleanup_action(active_exception) { join_reader(resources.fetch(:readers)&.fetch(:stdout, nil)) }
+      cleanup_action(active_exception) { join_reader(resources.fetch(:readers)&.fetch(:stderr, nil)) }
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    def terminate_process_group(resources, active_exception)
+      process_group_id = resources.fetch(:process_group_id)
+      wait_thread = resources.fetch(:wait_thread)
+      process_pid = wait_thread.pid
+
+      cleanup_action(active_exception) { signal_with_fallback("TERM", process_group_id, process_pid) }
+      wait_thread.join(TERMINATE_GRACE_SECONDS)
+      return unless process_group_alive?(process_group_id)
+
+      cleanup_action(active_exception) { signal_with_fallback("KILL", process_group_id, process_pid) }
+      wait_thread.join if wait_thread&.alive?
+    rescue Errno::ESRCH
+      wait_thread.join if wait_thread&.alive?
+    end
+
+    def signal_with_fallback(signal, process_group_id, process_pid)
+      signal_process_group(signal, process_group_id)
+    rescue StandardError
+      signal_process(signal, process_pid)
+    end
+
+    def signal_process_group(signal, process_group_id)
+      return unless process_group_id
+
+      Process.kill(signal, process_group_id)
+    end
+
+    def signal_process(signal, process_pid)
+      Process.kill(signal, process_pid)
+    end
+
+    def process_group_alive?(process_group_id)
+      Process.kill(0, process_group_id)
+      true
+    rescue Errno::EPERM
+      true
+    rescue Errno::ESRCH
+      false
+    end
+
+    def cleanup_action(active_exception)
+      yield
+    rescue StandardError
+      raise unless active_exception
+    end
+
+    def reader_thread(pipe)
+      Thread.new do
+        Thread.current.report_on_exception = false
+        pipe.read.to_s
+      end
+    end
+
+    def close_pipe(pipe)
+      pipe.close unless pipe.nil? || pipe.closed?
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def join_reader(reader)
+      return unless reader
+
+      reader.join
+      reader.value
+    end
+
+    def monotonic_deadline(timeout_seconds)
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
+    end
+
+    def remaining_before(deadline)
+      [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max
+    end
+
+    def failure_message(tool, error, stderr)
+      reason = sanitize_fragment(error.message)
+      message = "#{tool}: #{reason}"
+      stderr_tail = sanitized_stderr_tail(stderr)
+      return message if stderr_tail.empty? || !unreadable_output?(error)
+
+      "#{message} stderr: #{stderr_tail}"
+    end
+
+    def failure_finding(tool, error, stderr)
+      safe_tool = safe_failure_tool(tool)
+      Finding.tool_failure(tool: safe_tool, message: safe_failure_message(safe_tool, error, stderr))
+    rescue StandardError
+      Finding.tool_failure(tool: fallback_tool_name, message: "#{fallback_tool_name}: adapter failure")
+    end
+
+    def safe_failure_tool(tool)
+      normalized_tool_name(tool || fallback_tool_name)
+    rescue StandardError
+      fallback_tool_name
+    end
+
+    def safe_failure_message(tool, error, stderr)
+      failure_message(tool, error, stderr)
+    rescue StandardError
+      "#{tool}: adapter failure"
+    end
+
+    def resolved_timeout(tool)
+      tool_timeouts = config.fetch(:timeouts)
+      raise ArgumentError, "timeouts config must be a mapping" unless tool_timeouts.is_a?(Hash)
+
+      validate_timeout_value(timeout_value_for(tool_timeouts, tool))
+    rescue KeyError
+      raise ArgumentError, "timeouts config is missing"
+    end
+
+    def timeout_value_for(tool_timeouts, tool)
+      return tool_timeouts.fetch(tool.to_sym) if tool_timeouts.key?(tool.to_sym)
+      return tool_timeouts.fetch(:default) if tool_timeouts.key?(:default)
+
+      raise ArgumentError, "timeout default is missing"
+    end
+
+    def validate_timeout_value(timeout_value)
+      return timeout_value if timeout_value.is_a?(Integer) && timeout_value.positive?
+
+      raise ArgumentError, "timeout must be a positive Integer"
+    end
+
+    def unreadable_output?(error)
+      error.is_a?(ParseError)
+    end
+
+    def sanitized_stderr_tail(stderr)
+      stderr
+        .to_s
+        .dup
+        .force_encoding(Encoding::UTF_8)
+        .scrub("?")
+        .lines
+        .map { sanitize_fragment(_1) }
+        .reject(&:empty?)
+        .last(STDERR_LINE_LIMIT)
+        .join(" | ")
+    end
+
+    def sanitize_fragment(text)
+      text
+        .to_s
+        .dup
+        .force_encoding(Encoding::UTF_8)
+        .scrub("?")
+        .gsub(/[[:cntrl:]]+/, " ")
+        .gsub(/\s+/, " ")
+        .strip
+    end
+
+    def fallback_tool_name
+      component = self.class.name.to_s.split("::").last.to_s
+      tool_name = sanitize_fragment(component).downcase
+      tool_name.empty? ? "adapter" : tool_name
+    end
+
+    def normalized_tool_name(tool)
+      sanitized = sanitize_fragment(tool)
+      sanitized.empty? ? fallback_tool_name : sanitized
+    end
+
+    def copy_string(value)
+      value.dup.freeze
+    end
+
+    class TimeoutError < StandardError; end
+
+    private_constant :STDERR_LINE_LIMIT, :TERMINATE_GRACE_SECONDS, :TimeoutError
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/quality_gate/adapters/brakeman.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "json"
+
+module QualityGate
+  module Adapters
+    # Runs Brakeman across the application and normalizes its JSON report.
+    class Brakeman < Adapter
+      class InvalidReport < StandardError; end
+      private_constant :InvalidReport
+
+      CONFIDENCE_MAP = {
+        "High" => :error,
+        "Medium" => :warning,
+        "Weak" => :info
+      }.freeze
+
+      def call
+        tool = name
+        stderr = +""
+        stdout, stderr, status = capture(validated_command, resolved_timeout(tool))
+        findings = parse(stdout)
+        validate_findings!(findings, expected_tool: tool)
+        validate_cli_result!(status, findings)
+        findings
+      rescue StandardError => e
+        [failure_finding(tool, e, stderr)]
+      end
+
+      def name = "brakeman"
+
+      def command = ["brakeman", "-f", "json", "-q", "--no-pager"]
+
+      def parse(stdout)
+        report = parse_report(stdout)
+        warnings = report.fetch("warnings") { invalid_report!("report must include warnings") }
+        errors = report.fetch("errors") { invalid_report!("report must include errors") }
+        validate_errors!(errors)
+        parse_warnings(warnings)
+      rescue JSON::ParserError, InvalidReport => e
+        fail ParseError.new(tool: name, reason: e.message) # rubocop:disable Style/SignalException
+      end
+
+      private
+
+      def parse_report(stdout)
+        report = JSON.parse(stdout)
+        invalid_report!("report must be a JSON object") unless report.is_a?(Hash)
+
+        report
+      end
+
+      def parse_warnings(entries)
+        invalid_report!("warnings must be an array") unless entries.is_a?(Array)
+
+        entries.map { build_finding(_1) }
+      end
+
+      def validate_errors!(errors)
+        invalid_report!("errors must be an array") unless errors.is_a?(Array)
+        invalid_report!("report contains scan errors") unless errors.empty?
+      end
+
+      def validate_cli_result!(status, findings)
+        cli_contract_error!("Brakeman did not exit normally") unless status&.exited?
+
+        exitstatus = status.exitstatus
+        return if exitstatus.zero?
+        return if exitstatus == 3 && findings.any?
+
+        if exitstatus == 3
+          cli_contract_error!("Brakeman exit status 3 disagrees with its warning count")
+        else
+          cli_contract_error!("Brakeman exited with unsupported status #{exitstatus.inspect}")
+        end
+      end
+
+      def cli_contract_error!(reason)
+        fail ParseError.new(tool: name, reason:) # rubocop:disable Style/SignalException
+      end
+
+      def build_finding(warning)
+        invalid_report!("warning must be an object") unless warning.is_a?(Hash)
+
+        Finding.new(tool: name, **finding_attributes(warning))
+      end
+
+      def finding_attributes(warning)
+        line = warning_field(warning, "line")
+        confidence = string_field(warning, "confidence")
+
+        {
+          file: string_field(warning, "file"),
+          line: validated_line(line),
+          rule: string_field(warning, "warning_type"),
+          severity: CONFIDENCE_MAP.fetch(confidence) { invalid_report!("unknown confidence #{confidence.inspect}") },
+          message: string_field(warning, "message")
+        }
+      end
+
+      def warning_field(warning, field)
+        warning.fetch(field) { invalid_report!("warning must include #{field}") }
+      end
+
+      def string_field(warning, field)
+        value = warning_field(warning, field)
+        invalid_report!("#{field} must be a String") unless value.is_a?(String)
+
+        value
+      end
+
+      def validated_line(line)
+        return 0 if line.nil?
+
+        invalid_report!("line must be a non-negative Integer") unless line.is_a?(Integer) && line >= 0
+
+        line
+      end
+
+      def invalid_report!(reason)
+        raise InvalidReport, reason
+      end
+    end
+  end
+end