browser_review_gate 0.2.2 → 0.4.0

data/lib/browser_review_gate/verify.rb

@@ -0,0 +1,95 @@
+module BrowserReviewGate
+  # One entry point for the verification workflow. Ruby does the bookkeeping: which PR, which decision,
+  # which scenarios are still owed, which environment, whether the app answers, and publishing what an
+  # agent observed. The browser run itself happens in the AI coding agent (Claude Code, Cursor, Codex)
+  # with its browser tool; nothing here drives a browser.
+  class Verify
+    # Exit statuses, so an agent or a script can branch on the outcome.
+    EXIT = {
+      "nothing" => 0, "published" => 0, "saved" => 0,
+      "run_and_publish" => 2, "run_and_save" => 2,
+      "ask_to_start_app" => 3,
+      "request_assessment" => 4, "assessment_requested" => 4,
+      "check_out_pr_head" => 5, "open_pull_request" => 5,
+      "publish_saved" => 6, "not_verified" => 7
+    }.freeze
+
+    def initialize(github:, config:, prompts:, shell: Shell.new, probe: nil, publisher_factory: nil)
+      @github = github
+      @config = config
+      @prompts = prompts
+      @shell = shell
+      @probe = probe
+      @publisher_factory = publisher_factory || lambda { |number, path|
+        Publisher.new(github: github, number: number, report_path: path, config: config, shell: shell)
+      }
+    end
+
+    # Returns [outcome, details]. `report` publishes (or saves, before the PR exists) a finished run.
+    # `request` lets a missing assessment be requested from CI.
+    def run(number: nil, environment: nil, report: nil, request: true)
+      status = Status.new(github: @github, config: @config, shell: @shell, probe: @probe, prompts: @prompts).to_h(number, environment: environment)
+      outcome = status["next"]
+      return [ submit(status, report), status ] if report && %w[run_and_publish run_and_save publish_saved].include?(outcome)
+
+      if outcome == "publish_saved"
+        outcome = @publisher_factory.call(status["pull_request"], nil).publish ? "published" : "not_verified"
+      elsif outcome == "request_assessment" && request
+        @github.dispatch_workflow(@config.workflow, status["pull_request"])
+        outcome = "assessment_requested"
+      end
+      [ outcome, status ]
+    end
+
+    def self.exit_status(outcome) = EXIT.fetch(outcome, 1)
+
+    # What to tell the person or the agent for each outcome.
+    def self.describe(outcome, status)
+      environment = status["environment"] || {}
+      case outcome
+      when "nothing" then "Nothing to run: #{status["waived"] ? "verification was waived" : "no browser run is needed or the PR is verified"}. Human review can be requested."
+      when "published" then "Browser verification published; human review can be requested."
+      when "saved" then "Browser run saved. It is published when the PR for this commit is opened."
+      when "not_verified" then "Results published, but required scenarios still need a passing case. Review stays on hold."
+      when "assessment_requested" then "CI has been asked to assess PR #{status["pull_request"]}. Run verify again in about a minute."
+      when "request_assessment" then "PR #{status["pull_request"]} has no assessment yet. Run verify without --no-request to ask CI for one."
+      when "check_out_pr_head" then "Check out the PR head (#{status["pr_head"]}) with a clean worktree, then run verify again."
+      when "open_pull_request" then "A run is saved for this commit. Open the pull request; it is published then."
+      when "ask_to_start_app" then "The #{environment["name"]} environment does not answer at #{environment["url"]}. Ask the person to start it" \
+        "#{environment["start_command"] ? " (#{environment["start_command"]})" : ""}; do not start it yourself."
+      else run_instructions(status)
+      end
+    end
+
+    def self.run_instructions(status)
+      environment = status["environment"] || {}
+      scenarios = status["scenarios"]
+      list = scenarios.any? ? scenarios.map { |scenario| "  - #{scenario["id"]} [#{scenario["status"]}] #{scenario["name"]}" } :
+                              [ "  - none listed by CI yet: choose them from the diff and #{Prompts::RULES}" ]
+      [ "A browser run is needed#{status["pull_request"] ? " for PR ##{status["pull_request"]}" : ""}.",
+        "Environment: #{environment["name"] || "not configured"}#{environment["url"] ? " at #{environment["url"]}" : ""}.",
+        "Scenarios to run in your browser tool, one case per id:", *list,
+        *trace_note(status),
+        "Then: browser-review-gate verify --report PATH (publishes, or saves before the PR exists)." ].join("\n")
+    end
+
+    def self.trace_note(status)
+      mode = status.dig("policy", "enforced", "trace_check")
+      return [] if mode.nil? || mode == "off"
+
+      [ "Record a Playwright trace (.zip) or a HAR file (.har) for every case and list it as evidence.trace." \
+        "#{mode == "require" ? " Without one, a passing case is refused. If your browser tool can save neither, stop and tell the person." : ""}" ]
+    end
+
+    private
+
+    def submit(status, report)
+      if status["pull_request"]
+        @publisher_factory.call(status["pull_request"], report).publish ? "published" : "not_verified"
+      else
+        @publisher_factory.call(nil, report).save
+        "saved"
+      end
+    end
+  end
+end

data/lib/browser_review_gate/version.rb

@@ -1,3 +1,3 @@
 module BrowserReviewGate
-  VERSION = "0.2.2"
+  VERSION = "0.4.0"
 end

data/lib/browser_review_gate/zip_reader.rb

@@ -0,0 +1,103 @@
+require "zlib"
+
+module BrowserReviewGate
+  # Reads selected entries of a zip archive into memory, using only zlib. Made for Playwright traces,
+  # which come from the agent and are untrusted: entry count, sizes and compression ratio are capped,
+  # nothing is written to disk, and entry names are only compared, never used as paths.
+  class ZipReader
+    MAX_ENTRIES = 10_000
+    MAX_ENTRY_BYTES = 50 * 1024 * 1024
+    MAX_TOTAL_BYTES = 200 * 1024 * 1024
+    MAX_RATIO = 200
+    END_OF_DIRECTORY = "PK\x05\x06".b
+    DIRECTORY_ENTRY = "PK\x01\x02".b
+    LOCAL_ENTRY = "PK\x03\x04".b
+
+    def initialize(path)
+      @path = path
+    end
+
+    # Yields the name and content of every entry whose name the block's filter accepts.
+    def each(filter)
+      total = 0
+      File.open(@path, "rb") do |file|
+        directory(file).each do |entry|
+          next unless filter.call(entry[:name])
+
+          content = read(file, entry)
+          total += content.bytesize
+          raise Error, "trace is larger than #{MAX_TOTAL_BYTES / 1024 / 1024} MB uncompressed" if total > MAX_TOTAL_BYTES
+
+          yield entry[:name], content
+        end
+      end
+    end
+
+    private
+
+    def directory(file)
+      size = file.size
+      tail_size = [ size, 65_557 ].min
+      file.seek(size - tail_size)
+      tail = file.read(tail_size)
+      at = tail.rindex(END_OF_DIRECTORY) or raise Error, "trace is not a zip archive"
+      count, _directory_size, offset = tail[at + 10, 10].unpack("vVV")
+      raise Error, "trace has too many entries" if count > MAX_ENTRIES
+
+      file.seek(offset)
+      Array.new(count) { directory_entry(file) }
+    end
+
+    def directory_entry(file)
+      header = file.read(46)
+      raise Error, "trace zip directory is damaged" unless header&.start_with?(DIRECTORY_ENTRY)
+
+      method, compressed, uncompressed, name_length, extra_length, comment_length, offset =
+        header.unpack("@10v@20VV@28vvv@42V")
+      name = file.read(name_length).to_s.force_encoding(Encoding::UTF_8)
+      file.seek(extra_length + comment_length, IO::SEEK_CUR)
+      { name: name, method: method, compressed: compressed, uncompressed: uncompressed, offset: offset }
+    end
+
+    def read(file, entry)
+      raise Error, "trace entry #{entry[:name][0, 80]} is too large" if entry[:uncompressed] > MAX_ENTRY_BYTES
+      if entry[:compressed].positive? && entry[:uncompressed] / entry[:compressed] > MAX_RATIO
+        raise Error, "trace entry #{entry[:name][0, 80]} is compressed suspiciously well"
+      end
+
+      position = file.pos
+      file.seek(entry[:offset])
+      local = file.read(30)
+      raise Error, "trace zip entry is damaged" unless local&.start_with?(LOCAL_ENTRY)
+
+      name_length, extra_length = local.unpack("@26vv")
+      file.seek(name_length + extra_length, IO::SEEK_CUR)
+      data = file.read(entry[:compressed]).to_s
+      file.seek(position)
+      content = case entry[:method]
+                when 0 then data
+                when 8 then inflate(data)
+                else raise Error, "trace entry #{entry[:name][0, 80]} uses an unsupported compression method"
+                end
+      raise Error, "trace entry #{entry[:name][0, 80]} is not the size its header says" unless content.bytesize == entry[:uncompressed]
+
+      content
+    end
+
+    # Stops as soon as the output passes the entry cap, so a lying header cannot exhaust memory.
+    def inflate(data)
+      inflater = Zlib::Inflate.new(-Zlib::MAX_WBITS)
+      out = +""
+      (0...data.bytesize).step(4096) do |offset|
+        out << inflater.inflate(data.byteslice(offset, 4096))
+        raise Error, "trace entry is larger than it says" if out.bytesize > MAX_ENTRY_BYTES
+      end
+      out << inflater.finish
+      out
+    rescue Zlib::Error
+      raise Error, "trace entry is not valid deflate data"
+    ensure
+      inflater&.close
+    end
+  end
+end

data/lib/browser_review_gate.rb

@@ -23,6 +23,12 @@ module BrowserReviewGate
   autoload :Assessment, File.join(__dir__, "browser_review_gate/assessment")
   autoload :Assessor, File.join(__dir__, "browser_review_gate/assessor")
   autoload :CLI, File.join(__dir__, "browser_review_gate/cli")
+  autoload :Doctor, File.join(__dir__, "browser_review_gate/doctor")
+  autoload :Evidence, File.join(__dir__, "browser_review_gate/evidence")
+  autoload :RevisionHeader, File.join(__dir__, "browser_review_gate/revision_header")
+  autoload :TraceCheck, File.join(__dir__, "browser_review_gate/trace_check")
+  autoload :ZipReader, File.join(__dir__, "browser_review_gate/zip_reader")
+  autoload :Verify, File.join(__dir__, "browser_review_gate/verify")
   autoload :Config, File.join(__dir__, "browser_review_gate/config")
   autoload :Gate, File.join(__dir__, "browser_review_gate/gate")
   autoload :GitHub, File.join(__dir__, "browser_review_gate/github")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browser_review_gate
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Islam Gagiev
@@ -43,6 +43,8 @@ files:
 - lib/browser_review_gate/assessor.rb
 - lib/browser_review_gate/cli.rb
 - lib/browser_review_gate/config.rb
+- lib/browser_review_gate/doctor.rb
+- lib/browser_review_gate/evidence.rb
 - lib/browser_review_gate/gate.rb
 - lib/browser_review_gate/github.rb
 - lib/browser_review_gate/hook.rb
@@ -53,6 +55,7 @@ files:
 - lib/browser_review_gate/prompts.rb
 - lib/browser_review_gate/publisher.rb
 - lib/browser_review_gate/report.rb
+- lib/browser_review_gate/revision_header.rb
 - lib/browser_review_gate/saved_report.rb
 - lib/browser_review_gate/shell.rb
 - lib/browser_review_gate/stats.rb
@@ -65,7 +68,10 @@ files:
 - lib/browser_review_gate/templates/policy.md
 - lib/browser_review_gate/templates/rules.md.erb
 - lib/browser_review_gate/templates/workflow.yml.erb
+- lib/browser_review_gate/trace_check.rb
+- lib/browser_review_gate/verify.rb
 - lib/browser_review_gate/version.rb
+- lib/browser_review_gate/zip_reader.rb
 - lib/generators/browser_review_gate/install/install_generator.rb
 homepage: https://github.com/Halvanhelv/browser_review_gate
 licenses: