quality_gate 0.2.1 → 0.3.0

data/lib/quality_gate/cli.rb

@@ -6,12 +6,13 @@ module QualityGate
   # Parses command-line input and coordinates configured quality gates.
   # rubocop:disable Metrics/ClassLength
   class CLI
-    SUBCOMMANDS = %w[fast verify audit version init].map!(&:freeze).freeze
-    GATE_SUBCOMMANDS = SUBCOMMANDS.first(3).freeze
+    SUBCOMMANDS = %w[fast verify audit deep version init doctor].map!(&:freeze).freeze
+    GATE_SUBCOMMANDS = %w[fast verify audit deep].map!(&:freeze).freeze
     GATE_TOOLS = {
       "fast" => %w[rubocop].freeze,
       "verify" => %w[reek test_suite undercover].freeze,
-      "audit" => %w[brakeman bundler_audit].freeze
+      "audit" => %w[brakeman bundler_audit].freeze,
+      "deep" => %w[rubycritic].freeze
     }.freeze
 
     class << self
@@ -61,6 +62,7 @@ module QualityGate
         end
         return print_version(stdout, stderr) if subcommand == "version" && arguments.empty?
         return run_init(arguments, stdout: stdout, stderr: stderr, dir: dir) if subcommand == "init"
+        return run_doctor(arguments, stdout: stdout, stderr: stderr, dir: dir) if subcommand == "doctor"
 
         nil
       end
@@ -71,6 +73,10 @@ module QualityGate
         InitCommand.run(arguments, stdout: stdout, stderr: stderr, dir: dir)
       end
 
+      def run_doctor(arguments, stdout:, stderr:, dir:)
+        DoctorCommand.new(dir:, registry: registry).run(arguments, stdout:, stderr:)
+      end
+
       def execute_command(subcommand, arguments, stdout:, stderr:, dir:, format:)
         unless GATE_SUBCOMMANDS.include?(subcommand)
           return invalid_command(subcommand, stdout: stdout, stderr: stderr, format: format)
@@ -87,6 +93,9 @@ module QualityGate
 
         settings = config.to_h.merge(overrides)
         validate_paths!(settings.fetch(:files), dir)
+        operation = baseline_operation(subcommand, settings, overrides, dir)
+        settings[:baseline_operation] = operation if operation
+        settings.delete(:baseline_option)
         validate_simplecov_configuration!(subcommand, settings, config.path || File.join(dir, ".quality_gate.yml"))
         dispatch(subcommand, settings, stdout: stdout, stderr: stderr)
       end
@@ -161,6 +170,7 @@ module QualityGate
 
       def option_parser(overrides)
         OptionParser.new.tap do |parser|
+          add_baseline_options(parser, overrides)
           parser.on("--files PATH") do |path|
             raise OptionParser::InvalidOption, "--files" if overrides.key?(:files)
 
@@ -171,6 +181,54 @@ module QualityGate
         end
       end
 
+      def add_baseline_options(parser, overrides)
+        parser.on("--baseline PATH") { |path| set_baseline_option(overrides, :compare, path) }
+        parser.on("--create-baseline PATH") { |path| set_baseline_option(overrides, :create, path) }
+        parser.on("--ratchet-baseline PATH") { |path| set_baseline_option(overrides, :ratchet, path) }
+      end
+
+      def set_baseline_option(overrides, mode, path)
+        raise OptionParser::InvalidOption, "baseline options are mutually exclusive" if overrides.key?(:baseline_option)
+        raise OptionParser::InvalidArgument, "baseline path must be non-empty" if path.empty?
+
+        overrides[:baseline_option] = { mode:, path: }
+      end
+
+      def baseline_operation(subcommand, settings, overrides, dir)
+        requested = overrides[:baseline_option]
+        return unless requested || settings.fetch(:baseline).key?(subcommand.to_sym)
+
+        validate_baseline_gate!(subcommand)
+        operation = requested || configured_baseline(settings, subcommand)
+        validate_baseline_scope!(operation, settings, overrides)
+        resolved_baseline(operation, dir)
+      end
+
+      def validate_baseline_gate!(subcommand)
+        return if %w[fast verify].include?(subcommand)
+
+        raise ArgumentError, "baselines are supported only for fast and verify"
+      end
+
+      def configured_baseline(settings, subcommand)
+        { mode: :compare, path: settings.fetch(:baseline).fetch(subcommand.to_sym) }
+      end
+
+      def validate_baseline_scope!(operation, settings, overrides)
+        return unless %i[create ratchet].include?(operation.fetch(:mode))
+        return unless overrides.key?(:files) || settings.fetch(:files).any?
+
+        raise ArgumentError, "baseline creation and ratcheting require the full configured file scope"
+      end
+
+      def resolved_baseline(operation, dir)
+        {
+          mode: operation.fetch(:mode),
+          path: File.expand_path(operation.fetch(:path), dir),
+          root: File.expand_path(dir)
+        }
+      end
+
       def append_remaining_files(overrides, arguments)
         if overrides.key?(:files)
           overrides[:files].concat(arguments)
@@ -204,6 +262,7 @@ module QualityGate
       end
 
       def dispatch(subcommand, settings, stdout:, stderr:)
+        operation = settings.delete(:baseline_operation)
         config = Config.new(settings)
         diagnostic_io = terminal_diagnostic_io(stderr)
         result = Runner.new(
@@ -212,6 +271,8 @@ module QualityGate
           diagnostic_io: diagnostic_io
         ).call
 
+        result = apply_baseline_operation(result, operation, subcommand, settings) if operation
+
         begin
           reporter_for(settings.fetch(:format), stdout: stdout).call(result)
         rescue StandardError => e
@@ -222,6 +283,11 @@ module QualityGate
         result.exit_code
       end
 
+      def apply_baseline_operation(result, operation, subcommand, settings)
+        tools = settings.fetch(:adapters).fetch(subcommand.to_sym)
+        BaselineRun.new(operation:, gate: subcommand, tools:).call(result)
+      end
+
       def adapters_for(subcommand, settings:, config:, diagnostic_io:)
         settings.fetch(:adapters).fetch(subcommand.to_sym).map do |adapter_name|
           build_adapter(
@@ -282,7 +348,7 @@ module QualityGate
         return gate_help_text(gate) if gate
 
         <<~TEXT
-          Usage: quality_gate <fast|verify|audit|version|init> [options]
+          Usage: quality_gate <fast|verify|audit|deep|version|init|doctor> [options]
 
           Run one Quality Gate check for the current project.
 
@@ -290,24 +356,32 @@ module QualityGate
             fast      RuboCop (quick feedback for selected files)
             verify    Reek, test_suite, and Undercover (tests and coverage)
             audit     Brakeman and bundler_audit (security checks)
+            deep      RubyCritic (complexity and duplication checks; optional)
             version   Print the Quality Gate version
             init      Install a plain Ruby project configuration
+            doctor    Inspect bounded preflight readiness without running gates
 
           Options:
             --files PATH [PATH ...]  Replace configured paths for this run; files and directories are allowed
             --format FORMAT         Choose text, json, or markdown output (also accepts --format=FORMAT)
+            --baseline PATH         Accept recorded warnings on fast/verify
+            --create-baseline PATH  Create a warning snapshot on fast/verify
+            --ratchet-baseline PATH Shrink a clean fast/verify snapshot
             -h, --help              Show this help
 
           Scope:
             Without --files, the configured files are used. With --files, the command-line paths replace them.
             RuboCop and Reek scan selected paths. The test suite runs in full; Undercover checks the Git diff.
             Brakeman scans the application and bundler-audit scans the lockfile.
+            RubyCritic and Debride scan the whole project; --files does not narrow their scans.
 
           Examples:
             quality_gate fast
             quality_gate fast --files app/models/user.rb test/models
             quality_gate verify --format json
             quality_gate verify --format markdown
+            quality_gate doctor --format json
+            quality_gate deep --format json
 
           Exit status:
             0  Checks completed cleanly
@@ -318,6 +392,9 @@ module QualityGate
 
       def gate_help_text(gate)
         tools = GATE_TOOLS.fetch(gate).join(", ")
+        return deep_gate_help_text(tools) if gate == "deep"
+
+        baseline_options = baseline_help_options(gate)
 
         <<~TEXT
           Usage: quality_gate #{gate} [options]
@@ -327,6 +404,7 @@ module QualityGate
           Options:
             --files PATH [PATH ...]  Replace configured paths for this run; files and directories are allowed
             --format FORMAT         Choose text, json, or markdown output (also accepts --format=FORMAT)
+            #{baseline_options.chomp}
             -h, --help              Show this help
 
           Scope:
@@ -346,6 +424,44 @@ module QualityGate
         TEXT
       end
 
+      def baseline_help_options(gate)
+        return "" unless %w[fast verify].include?(gate)
+
+        [
+          "--baseline PATH         Compare with a warning snapshot",
+          "  --create-baseline PATH  Create a warning snapshot",
+          "  --ratchet-baseline PATH Shrink a clean snapshot"
+        ].join("\n")
+      end
+
+      def deep_gate_help_text(tools)
+        <<~TEXT
+          Usage: quality_gate deep [options]
+
+          Run the deep gate using these default tools: #{tools}.
+          RubyCritic is the default analyzer, optional and installed separately.
+          Enable optional Debride with adapters.deep: [debride]; install it separately.
+
+          Options:
+            --files PATH [PATH ...]  Validate paths for this run; deep analyzers scan the whole project
+            --format FORMAT         Choose text, json, or markdown output (also accepts --format=FORMAT)
+            -h, --help              Show this help
+
+          Scope:
+            Deep analyzers scan the whole project. --files paths are validated but do not narrow their scans.
+
+          Examples:
+            quality_gate deep
+            quality_gate deep --format json
+            # Configure adapters.deep: [debride] to run Debride
+
+          Exit status:
+            0  Checks completed cleanly
+            1  Checks completed with findings
+            2  Quality Gate could not complete (input, config, or tool failure)
+        TEXT
+      end
+
       def init_help_text
         <<~TEXT
           Usage: quality_gate init [options]
@@ -358,7 +474,9 @@ module QualityGate
             --test-helper PATH      Use a custom test helper
             --test-command COMMAND  Override the test command
             --skip-coverage         Omit coverage and Undercover setup
-            --agents                Install optional agent hooks and contracts
+            --agents                Install optional Claude Code hooks and contracts
+            --codex                 Install optional Codex patch feedback and Stop verification
+            --ci                    Generate an optional GitHub Actions workflow
             --pretend               Preview changes without writing them
             -h, --help              Show this help
 
@@ -367,6 +485,7 @@ module QualityGate
           Examples:
             quality_gate init
             quality_gate init --test-framework rspec
+            quality_gate init --codex
             quality_gate init --pretend
         TEXT
       end
@@ -430,12 +549,16 @@ module QualityGate
       def registry
         {
           "reek" => QualityGate::Adapters::Reek,
+          "herb" => QualityGate::Adapters::Herb,
           "rubocop" => QualityGate::Adapters::RuboCop,
           "simplecov" => QualityGate::Adapters::SimpleCov,
           "test_suite" => QualityGate::Adapters::TestSuite,
           "undercover" => QualityGate::Adapters::Undercover,
           "brakeman" => QualityGate::Adapters::Brakeman,
-          "bundler_audit" => QualityGate::Adapters::BundlerAudit
+          "bundler_audit" => QualityGate::Adapters::BundlerAudit,
+          "database_consistency" => QualityGate::Adapters::DatabaseConsistency,
+          "rubycritic" => QualityGate::Adapters::RubyCritic,
+          "debride" => QualityGate::Adapters::Debride
         }.freeze
       end
 

data/lib/quality_gate/codex_fast_hook.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "stringio"
+require_relative "codex_patch_files"
+
+module QualityGate
+  # Runs file-scoped fast checks after Codex applies a native patch.
+  class CodexFastHook
+    FINDING_STRING_FIELDS = %w[tool file rule severity message].freeze
+    private_constant :FINDING_STRING_FIELDS
+
+    class Report
+      def self.parse(output)
+        report = JSON.parse(output)
+        raise TypeError unless valid?(report)
+
+        report
+      end
+
+      def self.valid?(report)
+        report.is_a?(Hash) && valid_findings?(report["findings"]) &&
+          valid_summary?(report["summary"], report.fetch("findings").length)
+      end
+
+      def self.valid_findings?(findings)
+        findings.is_a?(Array) && findings.all? { valid_finding?(_1) }
+      end
+
+      def self.valid_finding?(finding)
+        return false unless finding.is_a?(Hash) && FINDING_STRING_FIELDS.all? { finding[_1].is_a?(String) }
+
+        line = finding["line"]
+        line.is_a?(Integer) && line >= 0 && Finding::SEVERITIES.any? { _1.to_s == finding["severity"] } &&
+          finding["rule"] != Finding::TOOL_FAILURE_RULE
+      end
+
+      def self.valid_summary?(summary, count)
+        return false unless summary.is_a?(Hash)
+
+        findings, failures = summary.values_at("findings", "tool_failures")
+        findings.is_a?(Integer) && findings == count && failures.is_a?(Integer) &&
+          failures.zero? && summary["failed_tools"] == []
+      end
+      private_class_method :valid_findings?, :valid_finding?, :valid_summary?
+    end
+    private_constant :Report
+
+    def initialize(dir:)
+      @dir = File.expand_path(dir)
+    end
+
+    def call(input)
+      return unavailable unless valid_input?(input)
+
+      evaluate(input)
+    rescue StandardError
+      unavailable
+    end
+
+    private
+
+    attr_reader :dir
+
+    def valid_input?(input)
+      input.is_a?(Hash) && input["hook_event_name"] == "PostToolUse" && input["tool_name"] == "apply_patch" &&
+        input.dig("tool_input", "command").is_a?(String) && absolute_existing_path?(input["cwd"])
+    rescue TypeError, NoMethodError
+      false
+    end
+
+    def evaluate(input)
+      root = File.realpath(dir)
+      cwd = File.realpath(input.fetch("cwd"))
+      return unavailable unless inside?(cwd, root) && File.directory?(cwd)
+
+      files = selected_files(input.fetch("tool_input").fetch("command"), cwd, root)
+      files.empty? ? {} : run_fast(files)
+    end
+
+    def absolute_existing_path?(path)
+      path.is_a?(String) && Pathname.new(path).absolute? && File.directory?(path)
+    end
+
+    def inside?(path, root)
+      path == root || path.start_with?("#{root}#{File::SEPARATOR}")
+    end
+
+    def selected_files(patch, cwd, root)
+      paths = CodexPatchFiles.parse(patch)
+      ruby_files = resolved_files(paths, ".rb", cwd, root)
+      erb_files = resolved_files(paths, ".erb", cwd, root)
+      return ruby_files if erb_files.empty? || !herb_enabled?(root)
+
+      ruby_files + erb_files
+    end
+
+    def resolved_files(paths, extension, cwd, root)
+      paths.filter_map { resolved_file(_1, cwd, root) if File.extname(_1) == extension }.uniq
+    end
+
+    def herb_enabled?(root)
+      Config.load(dir: root).fetch(:adapters).fetch(:fast).include?("herb")
+    end
+
+    def resolved_file(path, cwd, root)
+      expanded = File.expand_path(path, cwd)
+      return unless File.file?(expanded)
+
+      canonical_file(expanded, root)
+    rescue SystemCallError
+      nil
+    end
+
+    def canonical_file(path, root)
+      canonical = File.realpath(path)
+      canonical if inside?(canonical, root) && File.file?(canonical)
+    end
+
+    def run_fast(files)
+      stdout = StringIO.new
+      status = CLI.run(["fast", "--format", "json", "--files", *files], stdout:, stderr: StringIO.new, dir:)
+      respond_to_report(status, Report.parse(stdout.string))
+    end
+
+    def respond_to_report(status, report)
+      findings = report.fetch("findings")
+      return {} if status.zero? && findings.empty?
+      return unavailable unless status == 1 && findings.any?
+
+      additional_context("Fix these Quality Gate findings after this edit:\n#{format_findings(findings)}")
+    end
+
+    def format_findings(findings)
+      findings.map { format_finding(_1) }.join("\n")
+    end
+
+    def format_finding(finding)
+      "#{finding.fetch("file")}:#{finding.fetch("line")} " \
+        "[#{finding.fetch("tool")}/#{finding.fetch("rule")}] #{finding.fetch("message")}"
+    end
+
+    def unavailable
+      message = "Quality Gate fast feedback unavailable; run `bundle exec quality_gate fast` manually."
+      { "systemMessage" => message }.merge(
+        "hookSpecificOutput" => hook_output(unavailable_context)
+      )
+    end
+
+    def unavailable_context
+      "Quality Gate fast feedback is unavailable. Run `bundle exec quality_gate fast` manually."
+    end
+
+    def additional_context(context)
+      { "hookSpecificOutput" => hook_output(context) }
+    end
+
+    def hook_output(context)
+      { "hookEventName" => "PostToolUse", "additionalContext" => context }
+    end
+  end
+end

data/lib/quality_gate/codex_patch_files.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module QualityGate
+  # Extracts native apply_patch file operations without interpreting hunk content as paths.
+  class CodexPatchFiles
+    BEGIN_MARKER = "*** Begin Patch"
+    END_MARKER = "*** End Patch"
+    OPERATIONS = %w[Add Update Delete].freeze
+    private_constant :BEGIN_MARKER, :END_MARKER, :OPERATIONS
+
+    def self.parse(patch)
+      new(patch).call
+    end
+
+    def initialize(patch)
+      @lines = patch.lines(chomp: true).map { _1.delete_suffix("\r") }
+      @paths = []
+      @section = nil
+    end
+
+    def call
+      validate_patch!
+      lines[1...-1].each { process_line(_1) }
+      paths
+    end
+
+    private
+
+    attr_reader :lines, :paths, :section
+
+    def validate_patch!
+      raise ArgumentError unless lines.length >= 3 && lines.first == BEGIN_MARKER && lines.last == END_MARKER
+    end
+
+    def process_line(line)
+      process_operation(line) || process_move(line) || process_end_of_file(line) || process_content(line)
+    end
+
+    def process_operation(line)
+      match = line.match(/\A\*\*\* (#{OPERATIONS.join("|")}) File: (.+)\z/)
+      return false unless match
+
+      record_operation(match)
+      true
+    end
+
+    def record_operation(match)
+      @section = { operation: match[1], moved: false, in_hunk: false }
+      paths << match[2] unless match[1] == "Delete"
+    end
+
+    def process_move(line)
+      return false unless line.start_with?("*** Move to: ")
+
+      apply_move(line.delete_prefix("*** Move to: "))
+      true
+    end
+
+    def apply_move(destination)
+      valid_move!(destination)
+      paths[-1] = destination
+      section[:moved] = true
+    end
+
+    def valid_move!(destination)
+      valid = section && section.fetch(:operation) == "Update" && !section.fetch(:moved) &&
+              !section.fetch(:in_hunk) && !destination.empty?
+      raise ArgumentError unless valid
+    end
+
+    def process_end_of_file(line)
+      return false unless line == "*** End of File"
+
+      valid = section && section.fetch(:operation) == "Update" && section.fetch(:in_hunk)
+      raise ArgumentError unless valid
+
+      section[:in_hunk] = true
+      true
+    end
+
+    def process_content(line)
+      raise ArgumentError unless valid_content_line?(line)
+
+      section[:in_hunk] = true
+    end
+
+    def valid_content_line?(line)
+      section && valid_content?(line)
+    end
+
+    def valid_content?(line)
+      line.start_with?("+", "-", " ", "@@", "\")
+    end
+  end
+end

data/lib/quality_gate/codex_stop_hook.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+require "stringio"
+
+module QualityGate
+  # Runs the full verification gate at a native Codex Stop boundary.
+  class CodexStopHook
+    VERIFY_ARGUMENTS = %w[verify --format json].freeze
+    STRING_FIELDS = %w[tool file rule severity message].freeze
+    private_constant :VERIFY_ARGUMENTS, :STRING_FIELDS
+
+    def initialize(dir:)
+      @dir = File.expand_path(dir)
+    end
+
+    def call(input)
+      return unavailable unless valid_input?(input)
+
+      run_verify(input.fetch("stop_hook_active"))
+    rescue StandardError
+      unavailable
+    end
+
+    private
+
+    attr_reader :dir
+
+    def valid_input?(input)
+      input.is_a?(Hash) && input["hook_event_name"] == "Stop" &&
+        [true, false].include?(input["stop_hook_active"])
+    end
+
+    def run_verify(active)
+      stdout = StringIO.new
+      status = CLI.run(VERIFY_ARGUMENTS, stdout:, stderr: StringIO.new, dir:)
+      respond_to_report(status, parse_report(stdout.string), active)
+    end
+
+    def parse_report(output)
+      report = JSON.parse(output)
+      raise TypeError unless valid_report?(report)
+
+      report
+    end
+
+    def valid_report?(report)
+      return false unless report.is_a?(Hash) && valid_findings?(report["findings"])
+
+      valid_summary?(report["summary"], report["findings"].length)
+    end
+
+    def valid_findings?(findings)
+      findings.is_a?(Array) && findings.all? { valid_finding?(_1) }
+    end
+
+    def valid_finding?(finding)
+      finding.is_a?(Hash) && STRING_FIELDS.all? { finding[_1].is_a?(String) } && finding["line"].is_a?(Integer) &&
+        finding["line"] >= 0 && Finding::SEVERITIES.any? { _1.to_s == finding["severity"] } &&
+        finding["rule"] != Finding::TOOL_FAILURE_RULE
+    end
+
+    def valid_summary?(summary, count)
+      return false unless summary.is_a?(Hash)
+
+      findings, failures = summary.values_at("findings", "tool_failures")
+      findings.is_a?(Integer) && findings == count && failures.is_a?(Integer) &&
+        failures.zero? && summary["failed_tools"] == []
+    end
+
+    def respond_to_report(status, report, active)
+      findings = report.fetch("findings")
+      return {} if status.zero? && findings.empty?
+      return unavailable unless status == 1 && findings.any?
+      return capped(findings) if active
+
+      { "decision" => "block", "reason" => "Fix these findings before finishing:\n#{format_findings(findings)}" }
+    end
+
+    def format_findings(findings)
+      findings.map { format_finding(_1) }.join("\n")
+    end
+
+    def format_finding(finding)
+      file = finding.fetch("file")
+      line = finding.fetch("line")
+      tool, rule, message = finding.values_at("tool", "rule", "message")
+      "#{file}:#{line} [#{tool}/#{rule}] #{message}"
+    end
+
+    def capped(findings)
+      message = "Quality Gate continuation limit reached; remaining findings:\n#{format_findings(findings)}"
+      { "systemMessage" => message }
+    end
+
+    def unavailable
+      message = "Quality Gate verification unavailable; run " \
+        "`bundle exec quality_gate verify --format json` manually."
+      { "systemMessage" => message }
+    end
+  end
+end