quality_gate 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b549f0b3f39f5a51bc4c1321a8b0771ae355f4ad1a8da733e6f5cf9c8209a54e
-  data.tar.gz: a0adfdf9647271909cac928c6056ee59114a5eefee5c8173c4ecf8816bbbb5ba
+  metadata.gz: dc4fe18802dfc3fb409d11c8db6eb816df282e1914cd143807436998724eaf19
+  data.tar.gz: f1529c7f7cf1959a889fcc8a88691da70853ccb36e499718a5d56918e58add21
 SHA512:
-  metadata.gz: 6f58b91553cbf70f2224831b4c21f8b2aa279a3e76dba5638445c2d11982363d4820a8d70b54b99fcc83d5b97e1d898292e472c0427b7f2e34c764b2979ab796
-  data.tar.gz: eb7bbe5a088b832b60f28751f6dfd1009a4d6ed1ce291e42c27dcd2abbbb9ccc1310e4d45992bff589723aaf1dd37c47ff9763f1edb5599aace9fbc730621d0e
+  metadata.gz: f5d316d6426037588e9b895ed9f0d0a18d6f59e06b6666d8b37fd079af1bab0dddf991c1b756385ef90a6f5ae562da322f65a704f55d71b302adf5d9de90c63b
+  data.tar.gz: 2a21cb8513b65b1fb5fee6187bb303ae1ece9f575c9d1ae0c46c7cff5e2f27be7e12a88c6543cb9c29fb10fb636e02d0ebd4bab5b246c6d5ba6f99f51505ab39

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [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.
+- The installer no longer injects a coverage block into a test helper that already calls `SimpleCov.start`; it reports the skip and names what to confirm.
+
 ## [0.1.0] - 2026-09-08
 
 - Layered fast, verify, and audit gates with structured findings for Ruby projects.

data/README.md

@@ -45,19 +45,31 @@ The built-in fast path is meant for changed files:
 bundle exec quality_gate fast --files app/models/user.rb
 ```
 
-`verify` records coverage while it runs the full test suite, then checks changed code with Undercover. A clean `verify` or `audit` run prints this clean summary:
+`verify` records coverage while it runs the full test suite, then checks changed code with Undercover. A clean `verify` or `audit` run prints this clean summary: one line per tool that ran, naming its status, scope, and duration, then the tally:
 
 ```text
+reek         clean        project                 312ms
+test_suite   clean        test_suite           189137ms
+undercover   clean        git_diff                619ms
 0 findings, 0 tool failures
 ```
 
+(Durations above are illustrative, not measured figures.) These tool lines make a clean run visible: you see every tool that ran, not just an absence of findings.
+
 Use `--files` to select paths for RuboCop and Reek; the first path follows the option and further paths follow it as separate arguments:
 
 ```sh
 bundle exec quality_gate fast --files lib/quality_gate.rb test/test_quality_gate.rb
 ```
 
-Paths must exist, including paths from the configuration file. Any missing path returns exit `2` before tools run. A bare `fast` scans the project; it does not discover changed files automatically.
+Paths must exist, including paths from the configuration file. Any missing path returns exit `2` before tools run. A bare `fast` scans the project; it does not discover changed files automatically. RuboCop is the only default fast adapter, so a clean bare `fast` run prints one tool line then the tally:
+
+```text
+rubocop      clean        project                  842ms
+0 findings, 0 tool failures
+```
+
+(842ms above is illustrative, not a measured figure.)
 
 | Adapter | Scope with `--files` |
 | --- | --- |
@@ -70,25 +82,36 @@ Paths must exist, including paths from the configuration file. Any missing path
 
 `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
 
-Gate text output includes tool, severity, location when available, rule, and message:
+Gate text output prints, in order: one line per tool that ran, then findings, then the tally.
+
+When at least one tool ran, each gets a line naming the tool, its status, what it inspected, and how long it took:
+
+```text
+<tool> <status> <scope> <duration>ms
+```
+
+`status` is `clean`, `findings`, `tool_failure`, or `skipped`; `scope` describes what the tool inspected, such as `project`, `selected_files`, `git_diff`, `test_suite`, `coverage_summary`, or `lockfile`. These lines distinguish a clean run, which always names its tools, from a run where nothing executed. An empty adapter list runs no tools and prints none of these lines.
+
+Findings come next, with tool, severity, location when available, rule, and message:
 
 ```text
 <tool> <severity> <file>:<line> <rule> <message>
 ```
 
-Multiline messages retain indented detail lines. Findings without a source location omit it rather than printing `:0`. The final gate output line is the summary:
+Multiline messages retain indented detail lines. Findings without a source location omit it rather than printing `:0`. The final gate output line is unchanged, the summary:
 
 ```text
 <n> findings, <m> tool failures
@@ -149,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:
@@ -352,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.
 

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"
 
@@ -144,7 +147,7 @@ module QualityGate
 
       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 +204,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 +220,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/installation.rb

@@ -22,6 +22,7 @@ module QualityGate
     ].freeze
     MARKER_START = "# quality_gate coverage — start"
     MARKER_END = "# quality_gate coverage — end"
+    EXISTING_SIMPLECOV_START = /SimpleCov\s*\.\s*start\b/
     AGENT_CONTRACT_START = "<!-- quality_gate agent contract — start -->"
     AGENT_CONTRACT_END = "<!-- quality_gate agent contract — end -->"
     AGENT_TEMPLATE_PATHS = {
@@ -424,6 +425,7 @@ module QualityGate
     def install_coverage(path, relative_path)
       original = File.binread(path)
       return record(:unchanged, relative_path) if original.include?(MARKER_START.b)
+      return skip_existing_simplecov(relative_path) if EXISTING_SIMPLECOV_START.match?(original)
       return record_pretend_skip(relative_path) if options[:pretend]
 
       content = content_with_coverage(original)
@@ -659,6 +661,12 @@ module QualityGate
       record(:skipped, "test/test_helper.rb (missing; Minitest coverage wiring skipped)")
     end
 
+    def skip_existing_simplecov(relative_path)
+      say "Warning: coverage wiring skipped; #{relative_path} already calls SimpleCov.start. " \
+          "Confirm it enables branch coverage and loads the Undercover formatter."
+      record(:skipped, "#{relative_path} (already starts SimpleCov; coverage wiring skipped)")
+    end
+
     def record_pretend_skip(relative_path)
       record(:skipped, "#{relative_path} (pretend)")
     end

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/reporters/text.rb

@@ -9,6 +9,8 @@ module QualityGate
       end
 
       def call(result)
+        print_checks(result.checks)
+
         result.findings.each do |finding|
           io.puts(render_finding(finding))
         end
@@ -20,6 +22,26 @@ module QualityGate
 
       attr_reader :io
 
+      def print_checks(checks)
+        return if checks.empty?
+
+        checks.each { |check| io.puts(render_check(check)) }
+      end
+
+      def render_check(check)
+        format(
+          "%<tool>-12s %<status>-12s %<scope>-18s %<duration>8dms",
+          tool: FieldSanitizer.for_text(check[:tool]),
+          status: FieldSanitizer.for_text(check[:status]),
+          scope: FieldSanitizer.for_text(check[:scope]),
+          duration: duration_ms_for(check)
+        )
+      end
+
+      def duration_ms_for(check)
+        Integer(check[:duration_ms], exception: false) || 0
+      end
+
       def render_finding(finding)
         lines = FieldSanitizer.for_text_message(finding.message).split("\n", -1)
         ["#{finding_prefix(finding)} #{lines.first}", *lines.drop(1).map { "  #{_1}" }].join("\n")

data/lib/quality_gate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QualityGate
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 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.0
+  version: 0.2.0
 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