quality_gate 0.2.2 → 0.3.0

data/lib/quality_gate/doctor_coverage.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "adapters/simplecov"
+require_relative "doctor_bounded_file"
+require_relative "doctor_report"
+
+module QualityGate
+  # Inspects configured coverage evidence without running coverage tools.
+  class DoctorCoverage
+    def initialize(dir:, config:)
+      @dir = File.expand_path(dir).freeze
+      @config = config
+    end
+
+    def call
+      checks = []
+      checks << undercover_check if enabled?("undercover")
+      checks << simplecov_check if simplecov_configured?
+      return [check("coverage", "not_applicable", "No configured coverage evidence is required.")] if checks.empty?
+
+      checks
+    end
+
+    private
+
+    def undercover_check
+      inspect_artifact("coverage.undercover", Adapters::Undercover::COVERAGE_PATH,
+                       "Undercover coverage evidence", :undercover_shape?)
+    end
+
+    def simplecov_check
+      inspect_artifact("coverage.simplecov", Adapters::SimpleCov::COVERAGE_PATH,
+                       "SimpleCov coverage evidence", :simplecov_shape?)
+    end
+
+    def inspect_artifact(id, relative_path, label, shape)
+      result = DoctorBoundedFile.read(path: File.join(@dir, relative_path))
+      return unreadable_artifact(id, label, result.status) unless result.status == :ok
+
+      parse_artifact(id, label, result.contents, shape)
+    end
+
+    def parse_artifact(id, label, contents, shape)
+      document = JSON.parse(contents)
+      return ready_artifact(id, label) if method(shape).call(document)
+
+      invalid_shape(id, label)
+    rescue JSON::ParserError
+      malformed_json(id, label)
+    end
+
+    def unreadable_artifact(id, label, status)
+      message = unreadable_message(status)
+      check(id, "unchecked", "#{label} #{message}")
+    end
+
+    def unreadable_message(status)
+      return "is missing before the initial suite; run quality_gate verify to create it." if status == :missing
+
+      "could not be read safely (#{status}); inspect the regular file and permissions."
+    end
+
+    def ready_artifact(id, label)
+      message = "#{label} is readable structured evidence only; freshness, wiring, and " \
+        "budget compliance were not checked."
+      check(id, "ready", message)
+    end
+
+    def invalid_shape(id, label)
+      message = "#{label} has an unusable JSON shape; rerun the test suite and " \
+        "inspect the formatter output."
+      check(id, "warning", message)
+    end
+
+    def malformed_json(id, label)
+      message = "#{label} is malformed JSON; rerun the test suite and inspect the " \
+        "coverage formatter output."
+      check(id, "warning", message)
+    end
+
+    def undercover_shape?(document)
+      document.is_a?(Hash) && document["meta"].is_a?(Hash) && document["coverage"].is_a?(Hash)
+    end
+
+    def simplecov_shape?(document)
+      result = document["result"] if document.is_a?(Hash)
+      simplecov_result?(result)
+    end
+
+    def simplecov_result?(result)
+      return false unless result.is_a?(Hash) && valid_percentage?(result["line"])
+
+      !(@config.fetch(:coverage) || {}).key?(:minimum_branch) || valid_percentage?(result["branch"])
+    end
+
+    def simplecov_configured?
+      enabled?("simplecov") && (@config.fetch(:coverage) || {}).any?
+    end
+
+    def enabled?(name)
+      @config.fetch(:adapters).values.any? { _1.include?(name) }
+    end
+
+    def valid_percentage?(value)
+      value.is_a?(Numeric) && value.finite? && value.between?(0, 100)
+    end
+
+    def check(id, status, message)
+      DoctorReport.check(id:, status:, message:)
+    end
+  end
+end

data/lib/quality_gate/doctor_git.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "adapters/undercover"
+require_relative "doctor_report"
+require_relative "doctor_path_lookup"
+
+module QualityGate
+  # Checks Undercover comparison availability through its bounded Git resolver.
+  class DoctorGit < Adapters::Undercover
+    GIT_BUDGET_SECONDS = 5
+
+    def initialize(dir:, config:)
+      @doctor_dir = File.expand_path(dir).freeze
+      @paths = DoctorPathLookup.new(dir: @doctor_dir, path: ENV["PATH"])
+      super(config:)
+    end
+
+    def call
+      perform
+    ensure
+      clear_call_budget
+    end
+
+    private
+
+    def perform
+      return status_check("not_applicable", "Undercover is disabled; no comparison is needed.") unless enabled?
+
+      comparison_with_git
+    rescue StandardError => e
+      failure_check_for(e)
+    end
+
+    def comparison_with_git
+      return invalid_reference if option_like_reference?
+      return path_error unless git_available?
+
+      point = config.fetch(:compare_point)
+      point ? explicit_comparison_check(point) : automatic_comparison_check
+    end
+
+    def explicit_comparison_check(point)
+      start_call_budget(GIT_BUDGET_SECONDS)
+      commit = git_output("rev-parse", "--verify", "--quiet", "#{point}^{commit}", expected_exitstatuses: [1])
+      comparison_result(commit)
+    end
+
+    def automatic_comparison_check
+      start_call_budget(GIT_BUDGET_SECONDS)
+      point = compare_point
+      return no_automatic_point unless point
+
+      [check("comparison", "ready", "Automatic comparison resolves to local commit #{point}.")]
+    end
+
+    def enabled?
+      config.fetch(:adapters).values.any? { _1.include?("undercover") }
+    end
+
+    def git_command(arguments)
+      [@git_executable, "-C", @doctor_dir, *arguments]
+    end
+
+    def check(id, status, message)
+      DoctorReport.check(id:, status:, message:)
+    end
+
+    def no_automatic_point
+      status_check("unchecked", "No automatic comparison is available; fetch history or configure compare_point.")
+    end
+
+    def comparison_result(commit)
+      return [check("comparison", "ready", "Configured comparison resolves to commit #{commit}.")] if commit
+
+      [check("comparison", "blocked",
+             "Configured comparison does not resolve to a commit; choose an existing commit ref.")]
+    end
+
+    def invalid_reference
+      status_check("blocked", "The configured comparison ref is option-like and cannot be checked.")
+    end
+
+    def git_available?
+      @git_executable = @paths.resolve_executable("git")
+      @git_executable.is_a?(String)
+    end
+
+    def status_check(status, message)
+      [check("comparison", status, message)]
+    end
+
+    def failure_check_for(error)
+      return missing_git if error.is_a?(Errno::ENOENT)
+      return timed_out if error.is_a?(TimeoutError)
+
+      status_check("unchecked",
+                   "Git comparison could not be inspected; check local history or configure compare_point.")
+    end
+
+    def option_like_reference?
+      config.fetch(:compare_point)&.start_with?("-")
+    end
+
+    def missing_git
+      status_check("blocked", "Git is unavailable on project-rooted PATH; install Git or add it to PATH.")
+    end
+
+    def timed_out
+      status_check("unchecked", "Git lookup exceeded five seconds; inspect local history or configure compare_point.")
+    end
+
+    def path_error
+      unless @paths.available?
+        return status_check("unchecked",
+                            "PATH is absent, so Git availability is ambiguous; inspect runtime PATH.")
+      end
+
+      missing_git
+    end
+  end
+end

data/lib/quality_gate/doctor_hooks.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "doctor_bounded_file"
+require_relative "doctor_report"
+
+module QualityGate
+  # Summarizes recent automatic-hook history as historical evidence only.
+  class DoctorHooks
+    CLAUDE_HOOK_PATHS = %w[
+      .claude/hooks/quality_gate_fast.rb
+      .claude/hooks/quality_gate_verify_stop.rb
+    ].map!(&:freeze).freeze
+    CODEX_HOOK_PATHS = %w[
+      .codex/hooks.json
+      .codex/hooks/quality_gate_fast.rb
+      .codex/hooks/quality_gate_verify_stop.rb
+    ].map!(&:freeze).freeze
+    HOOK_PATHS = (CLAUDE_HOOK_PATHS + CODEX_HOOK_PATHS).freeze
+    INSTALLED_HOOKS_MESSAGE = "Installed hooks have no history; run a hooked edit and inspect feedback."
+    NO_INSTALLED_HOOKS_MESSAGE = "No hook history or installed hook files were found; " \
+      "automatic feedback was not checked."
+
+    def initialize(dir:)
+      @dir = File.expand_path(dir).freeze
+    end
+
+    def call
+      path = File.join(@dir, HookLog::DEFAULT_PATH)
+      file = DoctorBoundedFile.read(path:, max_bytes: 0)
+      summarize_file(file, path)
+    end
+
+    private
+
+    def summarize_file(file, path)
+      return missing_history if file.status == :missing
+      return unreadable_history(file.status) unless %i[ok oversized].include?(file.status)
+
+      summarize_history(path)
+    end
+
+    def installed_hooks?
+      HOOK_PATHS.any? { File.exist?(File.join(@dir, _1)) || File.symlink?(File.join(@dir, _1)) }
+    end
+
+    def missing_history
+      return [check("hooks", "unchecked", missing_installed_history_message)] if installed_hooks?
+
+      [check("hooks", "not_applicable", NO_INSTALLED_HOOKS_MESSAGE)]
+    end
+
+    def missing_installed_history_message
+      return INSTALLED_HOOKS_MESSAGE unless installed_codex_hook?
+
+      "Codex hook files are present, but Codex execution history and /hooks trust review are unchecked. " \
+        "Run a Codex Stop and review the hook in /hooks."
+    end
+
+    def installed_codex_hook?
+      CODEX_HOOK_PATHS.any? { File.exist?(File.join(@dir, _1)) || File.symlink?(File.join(@dir, _1)) }
+    end
+
+    def unreadable_history(status)
+      message = "Hook history is unsafe or unreadable (#{status}); inspect the log " \
+        "before relying on hook feedback."
+      [check("hooks", "unchecked", message)]
+    end
+
+    def summarize_history(path)
+      records = HookLog.new(path:).recent(limit: 20)
+      return empty_history if records.empty?
+
+      unavailable_history(records)
+    end
+
+    def unavailable_history(records)
+      count = records.count { %w[unavailable verify_unavailable].include?(_1.fetch("outcome")) }
+      return warning(count) if count.positive?
+
+      message = "Recent valid history had no unavailable outcomes; this describes " \
+        "history, not current hook installation."
+      [check("hooks", "ready", message)]
+    end
+
+    def empty_history
+      [check("hooks", "unchecked", "Hook history has no valid recent records; inspect the log.")]
+    end
+
+    def warning(count)
+      message = "#{count} of the last 20 checks were unavailable; inspect bundle " \
+        "installation and the Quality Gate hook setup."
+      [check("hooks", "warning", message)]
+    end
+
+    def check(id, status, message)
+      DoctorReport.check(id:, status:, message:)
+    end
+  end
+end

data/lib/quality_gate/doctor_launchers.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require_relative "doctor_report"
+require_relative "doctor_path_lookup"
+
+module QualityGate
+  class DoctorExplicitTargetCheck
+    def initialize(paths:)
+      @paths = paths
+    end
+
+    def check(argv)
+      command = argv.first(2) == %w[bundle exec] ? argv.drop(2) : argv
+      return ruby_target_problem(command) if ruby_command?(command)
+
+      bundle_target_problem(argv, command)
+    end
+
+    private
+
+    attr_reader :paths
+
+    def ruby_target_problem(command)
+      return search_target_problem(command[2]) if command[1] == "-S" && explicit_path?(command[2])
+      return unless script_argument?(command[1])
+
+      script_problem(command[1])
+    end
+
+    def script_problem(target)
+      path = paths.relative_path(target)
+      return missing_script(target) unless File.file?(path)
+      return unreadable_script(target) unless File.readable?(path)
+
+      nil
+    end
+
+    def bundle_target_problem(argv, command)
+      return unless argv.first(2) == %w[bundle exec] && explicit_path?(command.first)
+      return if paths.executable?(command.first)
+
+      ["blocked", "Explicit bundle target #{command.first} is missing; update the command path or install it."]
+    end
+
+    def search_target_problem(target)
+      return if paths.executable?(target)
+
+      ["blocked", "Ruby -S target #{target} is missing; update its path or install the launcher."]
+    end
+
+    def ruby_command?(command) = File.basename(command.first.to_s) == "ruby"
+    def explicit_path?(target) = target&.include?(File::SEPARATOR)
+    def script_argument?(target) = target && !target.start_with?("-")
+
+    def missing_script(target)
+      ["blocked", "Ruby script #{target} is missing; add the file or update commands.* argv."]
+    end
+
+    def unreadable_script(target)
+      ["blocked", "Ruby script #{target} is unreadable; update its file permissions."]
+    end
+  end
+
+  class DoctorRubySearchTarget
+    def initialize(paths:, known_launchers:)
+      @paths = paths
+      @known_launchers = known_launchers
+    end
+
+    def check(target)
+      return missing_target unless target
+      return explicit_target(target) if target.include?(File::SEPARATOR)
+
+      named_target(target)
+    end
+
+    private
+
+    attr_reader :paths, :known_launchers
+
+    def explicit_target(target)
+      ["ready", "Ruby and explicit target #{target} are present; command behavior was not run."]
+    end
+
+    def named_target(target)
+      return unknown_target unless known_launchers.include?(File.basename(target))
+      return path_unavailable unless paths.available?
+      return ready_target(target) if paths.executable?(target)
+
+      unchecked_target(target)
+    end
+
+    def missing_target = ["unchecked", "ruby -S target was not provided; supply a launcher name."]
+    def unknown_target = ["unchecked", "Ruby -S target is not recognized; inspect or simplify the configured command."]
+    def path_unavailable = ["unchecked", "PATH is unavailable; set PATH to inspect the ruby -S target."]
+
+    def ready_target(target)
+      ["ready", "Ruby and #{target} launchers are present; command behavior was not run."]
+    end
+
+    def unchecked_target(target)
+      ["unchecked", "Ruby -S target #{target} was not found; add it to PATH or inspect bundle paths."]
+    end
+  end
+
+  class DoctorLauncherWrapper
+    def initialize(paths:)
+      @paths = paths
+    end
+
+    def check(launcher, known:)
+      return explicit_launcher(launcher, known) if launcher.include?(File::SEPARATOR)
+      return named_launcher(launcher) if known
+
+      custom_launcher(launcher)
+    end
+
+    private
+
+    attr_reader :paths
+
+    def explicit_launcher(launcher, known)
+      return missing_explicit(launcher) unless paths.executable?(launcher)
+      return ready_launcher(launcher) if known
+
+      unchecked_custom
+    end
+
+    def named_launcher(launcher)
+      return direct_availability(launcher) unless paths.available?
+      return missing_direct(launcher) unless paths.executable?(launcher)
+
+      ready_launcher(launcher)
+    end
+
+    def custom_launcher(launcher)
+      return unavailable_custom unless paths.available?
+      return missing_custom(launcher) unless paths.executable?(launcher)
+
+      unchecked_custom
+    end
+
+    def direct_availability(launcher)
+      ["unchecked", "PATH is unavailable; set PATH to inspect #{launcher} availability."]
+    end
+
+    def missing_direct(launcher)
+      message = "Executable launcher #{launcher} is missing or not executable; " \
+        "install it, update permissions, or add it to PATH."
+      ["blocked", message]
+    end
+
+    def missing_explicit(launcher)
+      message = "Explicit launcher #{launcher} is missing or not executable; " \
+        "update permissions, its command path, or install it."
+      ["blocked", message]
+    end
+
+    def missing_custom(launcher)
+      ["blocked", "Custom wrapper #{launcher} is missing; install it or add it to PATH."]
+    end
+
+    def unavailable_custom
+      ["unchecked", "PATH is unavailable; set PATH to inspect the custom wrapper."]
+    end
+
+    def ready_launcher(launcher)
+      ["ready", "Executable #{launcher} is present; tool version and command behavior were not checked."]
+    end
+
+    def unchecked_custom
+      ["unchecked", "Custom wrapper is present but uninspected; verify its target or use a supported launcher."]
+    end
+  end
+
+  # Checks launch paths without starting analyzers or project commands.
+  class DoctorLaunchers
+    KNOWN_LAUNCHERS = %w[
+      bundle-audit brakeman herb herb-lint rails rake reek rspec rubocop undercover
+    ].map!(&:freeze).freeze
+
+    def initialize(dir:, path: ENV["PATH"])
+      @paths = DoctorPathLookup.new(dir:, path:)
+      @wrapper = DoctorLauncherWrapper.new(paths: @paths)
+      @explicit_targets = DoctorExplicitTargetCheck.new(paths: @paths)
+    end
+
+    def check(adapter:, argv:, gate: nil)
+      report(adapter, gate, *assess(argv))
+    rescue SystemCallError, ArgumentError
+      inspection_error(adapter, gate)
+    end
+
+    private
+
+    attr_reader :paths, :wrapper, :explicit_targets
+
+    def assess(argv)
+      return invalid_argv unless valid_argv?(argv)
+
+      explicit_targets.check(argv) || launch_assessment(argv)
+    end
+
+    def launch_assessment(argv)
+      return assess_bundle(argv.drop(2)) if argv.first(2) == %w[bundle exec]
+      return assess_ruby(argv) if ruby_launcher?(argv.first)
+
+      wrapper.check(argv.first, known: known_launcher?(argv.first))
+    end
+
+    def invalid_argv
+      ["blocked", "Command argv is invalid; provide a non-empty string array in commands.*."]
+    end
+
+    def valid_argv?(argv)
+      argv.is_a?(Array) && argv.any? && argv.all? { _1.is_a?(String) && !_1.empty? }
+    end
+
+    def assess_bundle(command)
+      return ["unchecked", "PATH is unavailable; set PATH to inspect the bundle launcher."] unless paths.available?
+      return missing_bundle_launcher unless paths.executable?("bundle")
+
+      return missing_bundle_target(command.first) if missing_bare_bundle_target?(command.first)
+
+      status, message = assess(command)
+      [status, "bundle is available; #{message}"]
+    end
+
+    def missing_bundle_launcher
+      ["blocked", "The bundle launcher is missing; install Bundler or add it to PATH."]
+    end
+
+    def missing_bare_bundle_target?(target)
+      target && !target.include?(File::SEPARATOR) && !paths.executable?(target)
+    end
+
+    def missing_bundle_target(target)
+      ["unchecked", "Bundle target #{target} was not found; install it or add it to the bundle PATH."]
+    end
+
+    def assess_ruby(argv)
+      return missing_ruby_path unless ruby_path_available?(argv.first)
+      return missing_ruby_launcher unless paths.executable?(argv.first)
+
+      assess_ruby_arguments(argv.drop(1))
+    end
+
+    def assess_ruby_arguments(arguments)
+      return unsupported_ruby_form if arguments.empty?
+      return assess_ruby_script(arguments) unless arguments.first.start_with?("-")
+      return assess_ruby_search(arguments.drop(1)) if arguments.first == "-S"
+
+      unsupported_ruby_form
+    end
+
+    def missing_ruby_launcher
+      ["blocked", "The ruby launcher is missing; install Ruby or add it to PATH."]
+    end
+
+    def unsupported_ruby_form
+      ["unchecked", "Ruby options are not inspected; use a simple ruby script command or inspect it manually."]
+    end
+
+    def ruby_path_available?(launcher)
+      launcher.include?(File::SEPARATOR) || paths.available?
+    end
+
+    def missing_ruby_path
+      ["unchecked", "Ruby launcher is unresolved; set PATH or configure its explicit path."]
+    end
+
+    def assess_ruby_script(arguments)
+      script = arguments.first
+      ["ready", "Ruby launcher and readable script #{script} are present; command behavior was not run."]
+    end
+
+    def assess_ruby_search(arguments)
+      DoctorRubySearchTarget.new(paths:, known_launchers: KNOWN_LAUNCHERS).check(arguments.first)
+    end
+
+    def known_launcher?(value)
+      KNOWN_LAUNCHERS.include?(File.basename(value))
+    end
+
+    def ruby_launcher?(value)
+      File.basename(value) == "ruby"
+    end
+
+    def report(adapter, gate, status, message)
+      id = gate ? "command.#{gate}.#{adapter}" : "command.#{adapter}"
+      DoctorReport.check(id:, status:, message:)
+    end
+
+    def inspection_error(adapter, gate)
+      message = "Could not inspect the launcher; verify its command path and argv."
+      report(adapter, gate, "unchecked", message)
+    end
+  end
+  private_constant :DoctorExplicitTargetCheck, :DoctorLauncherWrapper, :DoctorRubySearchTarget
+end

data/lib/quality_gate/doctor_path_lookup.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module QualityGate
+  # Resolves executable and script paths using the supplied project directory.
+  class DoctorPathLookup
+    def initialize(dir:, path: ENV["PATH"])
+      @dir = File.expand_path(dir)
+      @path = path
+    end
+
+    def resolve_executable(name)
+      return resolve_explicit(name) if explicit_path?(name)
+      return unless @path
+
+      resolve_from_path(name)
+    end
+
+    def executable?(name) = !resolve_executable(name).nil?
+
+    def relative_path(name) = File.expand_path(name, @dir)
+
+    def available? = !@path.nil?
+
+    private
+
+    def resolve_from_path(name)
+      path_entries.each do |entry|
+        candidate = File.expand_path(name, entry)
+        return candidate if executable_file?(candidate)
+      end
+      nil
+    end
+
+    def resolve_explicit(name)
+      path = relative_path(name)
+      path if executable_file?(path)
+    end
+
+    def explicit_path?(name) = name.include?(File::SEPARATOR)
+
+    def path_entries
+      entries = @path.empty? ? [""] : @path.split(File::PATH_SEPARATOR, -1)
+      entries.map { File.expand_path(_1.empty? ? @dir : _1, @dir) }
+    end
+
+    def executable_file?(path)
+      File.file?(path) && File.executable?(path)
+    end
+  end
+
+  private_constant :DoctorPathLookup
+end