quality_gate 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c2f18d9b5a74e7d19838e915bb21ab23fe18cb1d2179e0279ec848dec71e9ee
-  data.tar.gz: 8f6d82509a688cf01fb92186caca89a4c330470e05b9a5fb3200fa4c28339b55
+  metadata.gz: 661dea9969d01c65c60ef01523cbdfc2ebae74be253bd3f78b5420b34aad934a
+  data.tar.gz: 6a34cb55d86a89885c635dd0c1b77d203c5432c4f85035b232510e23baa1aad2
 SHA512:
-  metadata.gz: '0938c529aa703c3e0cdeaad45996e715a58b0554f4b87483d1741816056a10012567ef00410d287d15fe8d39996bf99a7cb750101275ec9b7423a044a2bf5e3d'
-  data.tar.gz: 5d822362f3278a6d219401b65379b1d4217e28db160991e7014c25e6a45403c5bd2c1f62df5766d50105d5ae40e80c50c02b5e54619ed0169dc0db723c271d77
+  metadata.gz: 0475a1a8e435e68effb9ea72bfbe3a82c69be9fb66e9c9e14c6cb983aec9354adb2754848a181dba35a128032e6131b1a3ed852defe5f838e1cb8d90589cc05a
+  data.tar.gz: 017605cf3e353c4e1861f03fd0e7fa2ac1ee1c6cedb6ba8fdfdbe99827bf1d186997b3ac794774f0259a23eb36b20a08f6a5957c8e67b7a43d65860755af4399

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.2.1] - 2026-09-22
+
+- Undercover reports stale coverage as an actionable `stale_coverage` finding with gate exit 1, telling operators to re-run the test suite before the coverage gate, instead of a parse failure with exit 2. Unknown validation reasons also fail closed and include their value; malformed output and CLI exit-status checks remain strict.
+
+## [0.2.0] - 2026-09-21
+
+- Gate commands accept `--format markdown` and `format: markdown`, printing a heading with the tally, a checks table, and a findings list for agents and pull request comments.
+- Undercover falls back to `origin/main` or `origin/master` when `origin/HEAD` and the local default branch are absent, so verify checks the diff on CI pull request checkouts instead of skipping. A missing default branch is now reported as missing rather than as a detached checkout.
+- The repository's own `.undercover` keeps Undercover's default test exclusions next to the version file exclusion.
+
 ## [0.1.1] - 2026-09-10
 
 - Text gate output now lists each tool that ran with its status, scope, and duration, so a clean run is distinguishable from a run where nothing executed.

data/README.md

@@ -82,15 +82,16 @@ rubocop      clean        project                  842ms
 
 `verify --files app/models/user.rb` therefore narrows Reek, but still runs the full suite and checks Git changes. JSON includes each adapter's scope and status. When stderr is a terminal, progress names each tool before it starts; redirected output and hook invocations remain quiet except for diagnostics.
 
-Choose text or JSON output with `--format text` or `--format json`:
+Choose text, JSON, or Markdown output with `--format text`, `--format json`, or `--format markdown`:
 
 ```sh
 bundle exec quality_gate verify --format json
+bundle exec quality_gate verify --format markdown
 ```
 
 The shorter form `quality_gate version` works when the installed executable is already on your `PATH`.
 
-The repository config must also use exactly `text` or `json` for `format`; any other configured value is rejected as a configuration error before a gate runs.
+The repository config must also use exactly `text`, `json`, or `markdown` for `format`; any other configured value is rejected as a configuration error before a gate runs.
 
 ## Output contract
 
@@ -171,6 +172,23 @@ When `--format json` is requested, input/configuration failures use the same rep
 
 Consumers should tolerate additive JSON fields. Existing finding and summary fields retain their meanings. An informational Undercover skip remains a finding and returns exit `1`; it is not proof that changed code was covered.
 
+Markdown output is for pasting into agent notes, pull request comments, and chat. It prints a level-two heading with the tally, a checks table when at least one tool ran, and a findings list when there are findings:
+
+```markdown
+## Quality Gate: 1 findings, 0 tool failures
+
+| Tool | Status | Scope | Duration |
+| --- | --- | --- | --- |
+| rubocop | findings | selected_files | 1240ms |
+
+### Findings
+
+- **rubocop** warning `lib/a.rb:4` Layout/First: First message
+  Second message line
+```
+
+Locations are code spans, extra message lines are indented under their finding, and pipe characters in table cells are escaped. Message punctuation is escaped so diagnostic HTML and Markdown markers display literally. Input and configuration errors keep the plain-text stderr behaviour; only JSON has a machine-readable error envelope.
+
 ## Configuration
 
 QualityGate looks for `.quality_gate.yml` in the working repository. Values in that file override the shipped defaults for known top-level keys:
@@ -374,7 +392,7 @@ The default verify adapters always run in order: Reek reports code smells, the t
 
 Reek uses an existing host `.reek.yml` when present and otherwise uses the shipped configuration. It reports smells as warnings and respects `--files`; without selected files it scans the project. Missing selected files are rejected by the CLI before any adapter runs.
 
-Undercover compares against the configured `compare_point` when present. Otherwise it uses the merge base of `HEAD` and the detected default branch: `refs/remotes/origin/HEAD` when available, then local `main`, then local `master`. If history is shallow, the default branch is missing, there is no earlier commit, or a detached checkout has no shared ancestor, verify reports an informational `undercover_skipped` finding with the reason instead of silently passing.
+Undercover compares against the configured `compare_point` when present. Otherwise it uses the merge base of `HEAD` and the detected default branch: `refs/remotes/origin/HEAD` when available, then `main` (local, then `origin/main`), then `master` (local, then `origin/master`). The remote-tracking fallback covers CI pull request checkouts, which are detached and fetch the default branch only as `origin/main`. If history is shallow, the default branch is missing, there is no earlier commit, or a detached checkout has no shared ancestor, verify reports an informational `undercover_skipped` finding with the reason instead of silently passing.
 
 Each uncovered region is a warning that names its file, first line, full line range, node, uncovered lines, and uncovered branch context. If the coverage record is absent, verify reports a tool failure explaining that the SimpleCov wiring is missing. Install it with `quality_gate init --profile ruby` or the Rails generator. The test-suite and Undercover adapters ignore `--files`: the suite and the Git change define their scope.
 
@@ -563,14 +581,49 @@ Clone the repository and install its dependencies:
 bin/setup
 ```
 
-Run the tests, lint checks, or complete default task:
+Run the tests in two separate Ruby processes, lint checks, or complete serial default task:
 
 ```sh
-bundle exec rake test
+bundle exec rake test:parallel
 bundle exec rubocop
 bundle exec rake
 ```
 
+`TEST_WORKERS=4 bundle exec rake test:parallel` changes the worker count.
+`bundle exec rake test` preserves the serial runner and its Minitest filtering
+options; `test:parallel` accepts the same `N`, `X`, and `A` filters. Named latency
+checks (`QUALITY_GATE_ACCEPTANCE_TIMING=1`) always use one worker so concurrent
+tests do not distort their measurements.
+
+This repository's `quality_gate verify` uses the parallel task. Each worker writes
+isolated coverage results; the parent merges them and generates reports only after
+every worker succeeds and supplies coverage. `TEST_WORKERS=1 bundle exec quality_gate verify`
+runs the same coverage pipeline with one worker. CI runs RuboCop separately and
+lets verify run the full suite once per Ruby version.
+
+To investigate test performance with [TestProf](https://github.com/test-prof/test-prof),
+run the serial suite without coverage instrumentation:
+
+```sh
+QUALITY_GATE_PROFILE=1 COVERAGE=0 bundle exec rake test
+```
+
+This opt-in run prints a TagProf breakdown by test directory and an EventProf
+report for `subprocess.quality_gate`, including the ten slowest suites and tests.
+The event measures synchronous `Open3.capture2`, `capture2e`, and `capture3`
+calls, including time waiting for child processes. It does not measure work
+inside those processes or the adapter's separate `popen`/wait implementation.
+The profiling switch is consumed before tests run so nested test projects keep
+their normal output. Ordinary runs do not enable the profilers, and TestProf is
+only a development/test dependency.
+
+Use the serial task for a single report; parallel profiling produces a separate
+report per worker. Existing Minitest filters still apply, for example:
+
+```sh
+QUALITY_GATE_PROFILE=1 COVERAGE=0 bundle exec rake test N=/test_clean_fixture/
+```
+
 The gem is linted by the configuration it ships, so the Sandi Metz budgets apply to its own code. Violations that predate those budgets are frozen file by file in `.rubocop_todo.yml`, which keeps the gate green while forcing new code to meet the budgets. That file is a ratchet: it may only shrink. When you change a file listed there, bring it under the budget and delete its entry; never add one. Regenerate it only after such a burn-down:
 
 ```sh

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

@@ -1,4 +1,4 @@
-# # Output format: "text" or "json".
+# # Output format: "text", "json", or "markdown".
 # format: text
 #
 # # Optional file paths passed to adapters; empty means no configured restriction.

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

@@ -1,4 +1,4 @@
-# # Output format: "text" or "json".
+# # Output format: "text", "json", or "markdown".
 # format: text
 #
 # # Optional file paths passed to RuboCop and Reek; empty means the project scope.

data/lib/quality_gate/adapters/undercover.rb

@@ -10,7 +10,10 @@ module QualityGate
       COVERAGE_PATH = "coverage/coverage.json"
       SKIP_RULE = "undercover_skipped"
       CLI_FOOTER_PATTERN = /\nUndercover finished in \d+(?:\.\d+)?s\n\z/
-      private_constant :CLI_FOOTER_PATTERN
+      NAMED_DEFAULT_BRANCH_REFS = %w[main master].flat_map do |branch|
+        ["refs/heads/#{branch}", "refs/remotes/origin/#{branch}"]
+      end.freeze
+      private_constant :CLI_FOOTER_PATTERN, :NAMED_DEFAULT_BRANCH_REFS
 
       def name = "undercover"
 
@@ -36,8 +39,7 @@ module QualityGate
 
         stdout, stderr, status = capture_with_remaining_timeout(command)
         validate_cli_envelope!(stdout, stderr, status)
-        findings = parse(stdout)
-        validate_cli_result!(status.exitstatus, findings)
+        findings = parse(stdout, exitstatus: status.exitstatus)
         validate_findings!(findings, expected_tool: tool)
         findings
       rescue StandardError => e
@@ -46,11 +48,13 @@ module QualityGate
         clear_call_budget
       end
 
-      def parse(stdout)
+      def parse(stdout, exitstatus: nil)
         document = parsed_document(stdout)
         warnings, summary = report_parts(document)
         findings = warnings.map { finding_from(_1) }
         validate_summary!(summary, warnings)
+        validate_cli_result!(exitstatus, warnings)
+        findings << validation_finding(document["validation"]) unless document["validation"].nil?
         findings
       rescue JSON::ParserError, KeyError, TypeError, ArgumentError => e
         raise ParseError.new(tool: name, reason: e.message)
@@ -94,8 +98,10 @@ module QualityGate
         cli_contract_error!("Undercover output is missing its terminal timing footer")
       end
 
-      def validate_cli_result!(exitstatus, findings)
-        expected_exitstatus = findings.empty? ? 0 : 1
+      def validate_cli_result!(exitstatus, warnings)
+        return if exitstatus.nil?
+
+        expected_exitstatus = warnings.empty? ? 0 : 1
         return if exitstatus == expected_exitstatus
 
         cli_contract_error!("Undercover exit status #{exitstatus} disagrees with its warning count")
@@ -117,7 +123,6 @@ module QualityGate
         summary = document.fetch("summary")
         raise TypeError, "warnings must be an Array" unless warnings.is_a?(Array)
         raise TypeError, "summary must be a mapping" unless summary.is_a?(Hash)
-        raise TypeError, "validation must be nil" unless document["validation"].nil?
 
         [warnings, summary]
       end
@@ -142,9 +147,31 @@ module QualityGate
         )
       end
 
+      def validation_finding(validation)
+        raise TypeError, "validation must be a String or nil" unless validation.is_a?(String)
+
+        Finding.new(
+          tool: name,
+          file: "",
+          line: 0,
+          rule: validation == "stale_coverage" ? "stale_coverage" : "undercover_validation",
+          severity: :error,
+          message: validation_message(validation)
+        )
+      end
+
+      def validation_message(validation)
+        if validation == "stale_coverage"
+          "Undercover coverage data predates the changed files. Re-run the test suite before the coverage gate."
+        else
+          "Undercover validation failed: #{validation.inspect}. Coverage cannot be trusted; " \
+            "resolve the validation issue and re-run the test suite before the coverage gate."
+        end
+      end
+
       def skip_reason
         return "Undercover skipped: repository is shallow; set compare_point explicitly." if shallow_repository?
-        return detached_reason if detached_head?
+        return detached_reason if detached_head? && default_branch_present?
         return first_commit_reason if first_commit?
         return missing_branch_reason unless default_branch_present?
 
@@ -201,7 +228,7 @@ module QualityGate
       def default_branch_ref
         return @default_branch_ref if defined?(@default_branch_ref)
 
-        @default_branch_ref = remote_default_branch || local_default_branch
+        @default_branch_ref = remote_default_branch || named_default_branch
       end
 
       def remote_default_branch
@@ -217,19 +244,12 @@ module QualityGate
         branch
       end
 
-      def local_default_branch
-        %w[main master].each do |branch|
-          ref = "refs/heads/#{branch}"
-          next unless commit_exists?(ref)
-
-          @default_branch_present = true
-          @default_branch_name = branch
-          return ref
-        end
-
-        @default_branch_present = false
-        @default_branch_name = "main"
-        "refs/heads/main"
+      # Local branches win, but a CI pull request checkout often has only the remote-tracking ref.
+      def named_default_branch
+        ref = NAMED_DEFAULT_BRANCH_REFS.find { commit_exists?(_1) }
+        @default_branch_present = !ref.nil?
+        @default_branch_name = ref ? ref.split("/").last : "main"
+        ref || "refs/heads/main"
       end
 
       def merge_base(branch)

data/lib/quality_gate/cli.rb

@@ -166,7 +166,7 @@ module QualityGate
 
             overrides[:files] = [path]
           end
-          parser.on("--format FORMAT", %w[text json]) { |format| overrides[:format] = format }
+          parser.on("--format FORMAT", Config::FORMATS) { |format| overrides[:format] = format }
           parser.on("-h", "--help") { overrides[:help] = true }
         end
       end
@@ -241,10 +241,9 @@ module QualityGate
 
       def reporter_for(format, stdout:)
         case format
-        when "json"
-          Reporters::Json.new(io: stdout)
-        else
-          Reporters::Text.new(io: stdout)
+        when "json" then Reporters::Json.new(io: stdout)
+        when "markdown" then Reporters::Markdown.new(io: stdout)
+        else Reporters::Text.new(io: stdout)
         end
       end
 
@@ -296,7 +295,7 @@ module QualityGate
 
           Options:
             --files PATH [PATH ...]  Replace configured paths for this run; files and directories are allowed
-            --format FORMAT         Choose text or json output (also accepts --format=FORMAT)
+            --format FORMAT         Choose text, json, or markdown output (also accepts --format=FORMAT)
             -h, --help              Show this help
 
           Scope:
@@ -308,6 +307,7 @@ module QualityGate
             quality_gate fast
             quality_gate fast --files app/models/user.rb test/models
             quality_gate verify --format json
+            quality_gate verify --format markdown
 
           Exit status:
             0  Checks completed cleanly
@@ -326,7 +326,7 @@ module QualityGate
 
           Options:
             --files PATH [PATH ...]  Replace configured paths for this run; files and directories are allowed
-            --format FORMAT         Choose text or json output (also accepts --format=FORMAT)
+            --format FORMAT         Choose text, json, or markdown output (also accepts --format=FORMAT)
             -h, --help              Show this help
 
           Scope:
@@ -362,7 +362,7 @@ module QualityGate
             --pretend               Preview changes without writing them
             -h, --help              Show this help
 
-          Init writes a human-readable summary. Gate commands continue to support text and JSON output.
+          Init writes a human-readable summary. Gate commands continue to support text, JSON, and Markdown output.
 
           Examples:
             quality_gate init
@@ -396,7 +396,7 @@ module QualityGate
         contents = File.read(path)
         document = YAML.safe_load(contents)
         format = document.is_a?(Hash) && document["format"]
-        return format if %w[text json].include?(format)
+        return format if Config::FORMATS.include?(format)
 
         nil
       rescue Psych::Exception, SystemCallError, SystemStackError

data/lib/quality_gate/config.rb

@@ -34,6 +34,7 @@ module QualityGate
       compare_point: nil,
       rubocop_config: nil
     }.freeze
+    FORMATS = %w[text json markdown].map!(&:freeze).freeze
     ADAPTER_LAYERS = %i[fast verify audit].freeze
     COVERAGE_KEYS = %i[minimum_line minimum_branch].freeze
     private_constant :ADAPTER_LAYERS, :COVERAGE_KEYS
@@ -95,9 +96,9 @@ module QualityGate
       end
 
       def validate_format(format, path)
-        return if %w[text json].include?(format)
+        return if FORMATS.include?(format)
 
-        fail ConfigError.new(path: path, cause_message: "format must be text or json") # rubocop:disable Style/SignalException
+        fail ConfigError.new(path: path, cause_message: "format must be text, json, or markdown") # rubocop:disable Style/SignalException
       end
 
       def validate_files(files, path)

data/lib/quality_gate/reporters/markdown.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module QualityGate
+  module Reporters
+    # Writes Markdown reports that agents and humans can paste into notes and reviews.
+    class Markdown
+      TABLE_HEADER = ["| Tool | Status | Scope | Duration |", "| --- | --- | --- | --- |"].freeze
+
+      def initialize(io:)
+        @io = io
+      end
+
+      def call(result)
+        io.puts(sections_for(result).join("\n\n"))
+      end
+
+      private
+
+      attr_reader :io
+
+      def sections_for(result)
+        [summary_heading(result), checks_table(result.checks), findings_section(result.findings)].compact
+      end
+
+      def summary_heading(result)
+        "## Quality Gate: #{result.findings.length} findings, #{result.failed_tools.length} tool failures"
+      end
+
+      def checks_table(checks)
+        return if checks.empty?
+
+        [*TABLE_HEADER, *checks.map { render_check(_1) }].join("\n")
+      end
+
+      def render_check(check)
+        cells = [check[:tool], check[:status], check[:scope]].map { table_cell(_1) }
+        "| #{cells.join(" | ")} | #{duration_ms_for(check)}ms |"
+      end
+
+      def duration_ms_for(check)
+        Integer(check[:duration_ms], exception: false) || 0
+      end
+
+      def table_cell(value)
+        FieldSanitizer.for_text(value).gsub("|", "\\|")
+      end
+
+      def findings_section(findings)
+        return if findings.empty?
+
+        ["### Findings", "", *findings.map { render_finding(_1) }].join("\n")
+      end
+
+      def render_finding(finding)
+        message = FieldSanitizer.for_text_message(finding.message).gsub(/[[:punct:]&&[:ascii:]]/) { "\\#{_1}" }
+        lines = message.split("\n", -1)
+        ["- #{finding_prefix(finding)}: #{lines.first}", *lines.drop(1).map { "  #{_1}" }].join("\n")
+      end
+
+      def finding_prefix(finding)
+        tool = "**#{FieldSanitizer.for_text(finding.tool)}**"
+        severity = FieldSanitizer.for_text(finding.severity.to_s)
+        [tool, severity, finding_location(finding), FieldSanitizer.for_text(finding.rule)].compact.join(" ")
+      end
+
+      def finding_location(finding)
+        file = FieldSanitizer.for_text(finding.file)
+        return if file.empty?
+
+        code_span(finding.line.zero? ? file : "#{file}:#{finding.line}")
+      end
+
+      def code_span(text)
+        fence = "`" * (longest_backtick_run(text) + 1)
+        fence.length == 1 ? "`#{text}`" : "#{fence} #{text} #{fence}"
+      end
+
+      def longest_backtick_run(text)
+        text.scan(/`+/).map(&:length).max.to_i
+      end
+    end
+  end
+end

data/lib/quality_gate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QualityGate
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 end

data/lib/quality_gate.rb

@@ -5,6 +5,7 @@ require_relative "quality_gate/exit_code"
 require_relative "quality_gate/finding"
 require_relative "quality_gate/reporters/field_sanitizer"
 require_relative "quality_gate/reporters/json"
+require_relative "quality_gate/reporters/markdown"
 require_relative "quality_gate/reporters/text"
 require_relative "quality_gate/hook_log"
 

data/sig/quality_gate.rbs

@@ -189,6 +189,11 @@ module QualityGate
       def initialize: (io: _Output) -> void
       def call: (Runner::Result result) -> nil
     end
+
+    class Markdown
+      def initialize: (io: _Output) -> void
+      def call: (Runner::Result result) -> nil
+    end
   end
 
   type finding_severity = :error | :warning | :info

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quality_gate
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Lucian Ghinda
@@ -219,6 +219,7 @@ files:
 - lib/quality_gate/railtie.rb
 - lib/quality_gate/reporters/field_sanitizer.rb
 - lib/quality_gate/reporters/json.rb
+- lib/quality_gate/reporters/markdown.rb
 - lib/quality_gate/reporters/text.rb
 - lib/quality_gate/rubocop.rb
 - lib/quality_gate/ruby_profile.rb