browser_review_gate 0.2.2 → 0.4.0

data/lib/browser_review_gate/assessor.rb

@@ -16,8 +16,12 @@ module BrowserReviewGate
           type: "array",
           items: {
             type: "object",
-            properties: { id: { type: "string" }, name: { type: "string" } },
-            required: %w[id name],
+            properties: {
+              id: { type: "string" }, name: { type: "string" },
+              priority: { type: "string", enum: Assessment::PRIORITIES },
+              category: { type: "string" }, why: { type: "string" }
+            },
+            required: %w[id name priority category why],
             additionalProperties: false
           }
         }
@@ -27,6 +31,7 @@ module BrowserReviewGate
     }.freeze
 
     IGNORED_REASON = "Only files that cannot change browser behavior were touched."
+    MANDATORY_REASON = "The project settings require browser scenarios for the files this change touches."
 
     def initialize(github:, model:, config: Config.new, prompts: Prompts.new, log: $stdout)
       @github = github
@@ -40,12 +45,13 @@ module BrowserReviewGate
     # when a report it has not judged lacks some of its scenarios; the comment is refreshed either way.
     def assess(number, pull_request: @github.pull_request(number), comments: @github.trusted_comments(number))
       head_sha = pull_request.fetch("head").fetch("sha")
-      report = Report.latest(comments)
+      report = Report.latest(comments, config: @config)
+      commits = @github.pull_request_commits(number)
 
       existing = Assessment.latest(comments)
       assessed_before = existing&.for?(head_sha)
       assessment = assessed_before && existing.settles?(report) ? existing : propose(number, pull_request, head_sha, report)
-      publish(number, assessment, pull_request, comments, report, new_commit: !assessed_before)
+      publish(number, assessment, pull_request, comments, report, commits, new_commit: !assessed_before)
       assessment
     rescue KeyError => error
       raise Error, "Browser assessment data is incomplete: #{error.message}"
@@ -53,27 +59,49 @@ module BrowserReviewGate
 
     private
 
+    # Mandatory scenarios scoped to paths make a run required whatever the model says; the rest are
+    # added whenever a run is required.
     def propose(number, pull_request, head_sha, report)
       files = @github.files(number)
-      return Assessment.not_required(IGNORED_REASON, assessed_sha: head_sha) if files.all? { |file| @config.ignored?(file["filename"]) }
+      paths = files.map { |file| file["filename"] }
+      mandatory = @config.mandatory_scenarios(paths)
+      forced = mandatory.any? { |scenario| scoped?(scenario) }
+      return Assessment.not_required(IGNORED_REASON, assessed_sha: head_sha) if !forced && paths.all? { |path| @config.ignored?(path) }
 
-      text = @model.complete(system: @prompts.assessment, user: user_message(pull_request, files, report), schema: SCHEMA)
-      assessment = Assessment.parse(text, assessed_sha: head_sha, report_seen: report&.fingerprint)
+      text = @model.complete(system: @prompts.assessment(max_count: @config.scenarios["max_count"]), user: user_message(pull_request, files, report), schema: SCHEMA)
+      text = force_required(text) if forced
+      usage = @model.respond_to?(:last_usage) ? @model.last_usage : nil
+      assessment = Assessment.parse(text, assessed_sha: head_sha, report_seen: report&.fingerprint, mandatory: mandatory,
+        max_count: @config.scenarios["max_count"], usage: usage)
       raise Error, "Model returned an invalid browser assessment: #{assessment.errors.join("; ")}" unless assessment.valid?
 
       assessment
     end
 
+    def scoped?(scenario)
+      entry = @config.scenarios["mandatory"].find { |item| scenario["id"] == item["id"] || scenario["id"].start_with?("#{item["id"]}.") }
+      entry && entry["paths"]
+    end
+
+    def force_required(text)
+      data = JSON.parse(text.to_s)
+      return text unless data.is_a?(Hash) && data["decision"] == "not-required"
+
+      JSON.generate(data.merge("decision" => "required", "reason" => MANDATORY_REASON, "scenarios" => []))
+    rescue JSON::ParserError
+      text
+    end
+
     # Ordinary commits keep the label; it goes only when the report does not cover the commit.
-    def publish(number, assessment, pull_request, comments, report, new_commit:)
+    def publish(number, assessment, pull_request, comments, report, commits, new_commit:)
       labelled = pull_request.fetch("labels").any? { |label| label["name"] == @config.label }
-      covered = assessment.covered_by?(report)
+      covered = assessment.covered_by?(report, commits: commits, reuse_passing: @config.scenarios["reuse_passing"])
       run_owed = assessment.required? && !(labelled && covered)
       @github.remove_label(number, @config.label) if run_owed && labelled
 
       comment = Assessment.latest_comment(comments)
       body = assessment.markdown(verified: labelled && covered, command: "#{@config.command} #{number}",
-        author: run_owed ? people_to_tell(pull_request, assessment.assessed_sha) : nil, report: report)
+        author: run_owed ? people_to_tell(pull_request, assessment.assessed_sha) : nil, report: report, commits: commits)
       if comment.nil?
         @github.create_comment(number, body)
       elsif comment["body"] == body

data/lib/browser_review_gate/cli.rb

@@ -11,7 +11,9 @@ module BrowserReviewGate
         eject policy|playbook                     copy a built-in text into the project to rewrite it there
 
       For an AI coding agent, from the checkout that was tested
-        status [--pr NUMBER]                      what the PR needs and what to do next, as JSON
+        verify [--pr NUMBER] [--environment NAME] [--report PATH] [--no-request] [--json]
+                                                  what to run, and with --report publish (or save) the finished run
+        status [--pr NUMBER] [--environment NAME] what the PR needs and what to do next, as JSON
         publish [--pr NUMBER] [--report PATH]     publish observed results (default: the saved run)
         save --report PATH                        keep results until the PR for this commit is opened
         request-assessment NUMBER                 ask CI to assess a PR that has no decision yet
@@ -21,11 +23,13 @@ module BrowserReviewGate
         ci NUMBER                                 assess the PR and take back premature reviewer requests
 
       For the team
-        stats [--days N]                          what the gate did on PRs of the last N days (default 30)
+        doctor [--json]                           check the setup and say what to fix
+        stats [--days N] [--json]                 what the gate did on PRs of the last N days (default 30)
     TEXT
 
-    # `github`, `config` and `model` are replaced in tests.
-    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, github: nil, config: nil, model: nil)
+    # `github`, `config`, `model` and `shell` are replaced in tests.
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, github: nil, config: nil, model: nil, shell: nil)
+      @shell = shell
       @argv = argv.dup
       @github = github
       @config = config
@@ -42,6 +46,8 @@ module BrowserReviewGate
       when "install" then install
       when "eject" then eject
       when "status" then status
+      when "verify" then verify
+      when "doctor" then doctor
       when "publish" then publish
       when "save" then save
       when "request-assessment" then request_assessment
@@ -58,7 +64,10 @@ module BrowserReviewGate
 
     private
 
-    def config = @config ||= Config.load(root)
+    # Local commands read the settings from the default branch when it has them; see Config.load_trusted.
+    def config = @config ||= trusted_config.first
+    def settings_source = @config ? trusted_config.last : nil
+    def trusted_config = @trusted_config ||= (@config ? [ @config, "given" ] : Config.load_trusted(root))
 
     # Settings and rules live at the top of the repository, wherever the command is run from.
     def root
@@ -74,6 +83,9 @@ module BrowserReviewGate
         parser.on("--pr NUMBER", Integer) { |value| parsed[:pr] = value } if flags.include?(:pr)
         parser.on("--report PATH") { |value| parsed[:report] = value } if flags.include?(:report)
         parser.on("--days N", Integer) { |value| parsed[:days] = value } if flags.include?(:days)
+        parser.on("--environment NAME") { |value| parsed[:environment] = value } if flags.include?(:environment)
+        parser.on("--json") { parsed[:json] = true } if flags.include?(:json)
+        parser.on("--no-request") { parsed[:no_request] = true } if flags.include?(:no_request)
         parser.on("--agents LIST", Array) { |value| parsed[:agents] = value } if flags.include?(:install)
         parser.on("--gem-source SOURCE") { |value| parsed[:gem_source] = value } if flags.include?(:install)
         parser.on("--workflow NAME") { |value| parsed[:workflow] = value } if flags.include?(:install)
@@ -101,10 +113,32 @@ module BrowserReviewGate
     end
 
     def status
-      @stdout.puts JSON.pretty_generate(Status.new(github: github, config: config, prompts: Prompts.new(root)).to_h(options(:pr)[:pr]))
+      parsed = options(:pr, :environment)
+      result = Status.new(github: github, config: config, prompts: Prompts.new(root)).to_h(parsed[:pr], environment: parsed[:environment])
+      @stdout.puts JSON.pretty_generate(result.merge("settings_source" => trusted_config.last))
       0
     end
 
+    def verify
+      parsed = options(:pr, :environment, :report, :json, :no_request)
+      outcome, result = Verify.new(github: github, config: config, prompts: Prompts.new(root), shell: @shell || Shell.new)
+        .run(number: parsed[:pr], environment: parsed[:environment], report: parsed[:report], request: !parsed[:no_request])
+      message = Verify.describe(outcome, result)
+      if parsed[:json]
+        @stdout.puts JSON.pretty_generate(result.merge("outcome" => outcome, "message" => message, "settings_source" => trusted_config.last))
+      else
+        @stdout.puts message
+      end
+      Verify.exit_status(outcome)
+    end
+
+    def doctor
+      json = options(:json)[:json]
+      checks = Doctor.new(root: root, github: @github).checks
+      @stdout.puts(json ? Doctor.json(checks) : Doctor.text(checks))
+      checks.any? { |check| check.status == "FAIL" } ? 1 : 0
+    end
+
     def publish
       parsed = options(:pr, :report)
       if Publisher.new(github: github, number: parsed[:pr], report_path: parsed[:report], config: config).publish
@@ -130,25 +164,16 @@ module BrowserReviewGate
     end
 
     def stats
-      days = options(:days).fetch(:days, 30)
+      parsed = options(:days, :json)
+      days = parsed.fetch(:days, 30)
       raise Error, "--days must be a positive number" unless days.positive?
 
-      counts = Stats.new(github: github, config: config).to_h(since: (Time.now.utc - days * 86_400).strftime("%Y-%m-%d"))
-      @stdout.puts "Pull requests touched in the last #{days} days: #{counts["pull_requests"]}",
-        "  assessed by the gate:           #{counts["assessed"]}",
-        "  needed a browser run:           #{counts["required"]}",
-        "    verified by a published run:  #{counts["verified"]}",
-        "    waived:                       #{counts["waived"]}",
-        "    open and still owing a run:   #{counts["owed"]}",
-        "    a run found a failing case:   #{counts["found_a_failure"]}"
+      result = Stats.new(github: github, config: config).to_h(since: (Time.now.utc - days * 86_400).strftime("%Y-%m-%d"))
+      @stdout.puts(parsed[:json] ? JSON.pretty_generate(result) : Stats.text(result, days))
       0
     end
 
-    # Version 0.1.1 installed a `--before` hook that held commands back. It is gone; a project that
-    # still has the entry gets a silent no-op until the installer removes it.
     def hook
-      return 0 if @argv.delete("--before")
-
       agent = @argv.shift
       message = Hook.new(publisher_factory: -> { Publisher.new(github: github, config: config) }).after(@stdin.read)
       output = Hook.render(message, agent)

data/lib/browser_review_gate/config.rb

@@ -1,9 +1,18 @@
+require "uri"
 require "yaml"
 
 module BrowserReviewGate
   # Project settings from .github/browser-review-gate.yml. Every key is optional.
+  #
+  # Some settings are enforced by this gem (it refuses a report or keeps review closed); others are
+  # instructions the agent receives through `status` and `verify`. `ENFORCED` and `AGENT` say which.
   class Config
     PATH = ".github/browser-review-gate.yml"
+    NAME_PATTERN = /\A[a-z][a-z0-9_-]{0,31}\z/
+    EVIDENCE_MODES = %w[never on_failure always].freeze
+    MAX_SCENARIOS = 30
+    MAX_MATRIX_CASES = 24
+
     DEFAULTS = {
       "label" => "browser-verified",
       # A person other than the author adds this label to let review proceed without a browser run.
@@ -16,19 +25,50 @@ module BrowserReviewGate
       "provider" => nil,
       "model" => nil,
       "claude_command" => nil,
-      # How an agent starts and reaches the app for a browser run.
-      "start_command" => nil,
-      "url" => nil,
-      "sign_in" => nil,
+      "environments" => nil,
+      "verification" => nil,
+      "evidence" => nil,
+      "scenarios" => nil,
+      "gate" => nil,
+      "provenance" => nil,
       "skip_authors" => [ "dependabot[bot]", "github-actions[bot]" ],
       "skip_branch_prefixes" => [],
       # A PR that only touches these paths cannot change browser behavior; no model call is made.
       "ignore_paths" => [ "docs/**", "test/**", "spec/**", "**/*.md", ".github/**" ]
     }.freeze
 
+    SECTIONS = {
+      "verification" => { "environment" => nil, "fail_on_console_errors" => false, "fail_on_network_errors" => false },
+      "evidence" => { "screenshots" => "never", "trace" => "never", "console_logs" => false, "network_logs" => false,
+                      "retention_days" => 14, "link_hosts" => [] },
+      "scenarios" => { "max_count" => 12, "reuse_passing" => true, "mandatory" => [], "matrix" => {} },
+      "gate" => { "require_evidence" => false, "block_on_failure" => true },
+      # Checks a case's Playwright trace against the tested commit: off, warn (shown in the PR) or
+      # require (a passing case counts only with a verified trace).
+      "provenance" => { "trace" => "off", "revision_header" => "X-App-Revision", "check_pages" => true, "clock_skew_seconds" => 300 }
+    }.freeze
+    TRACE_MODES = %w[off warn require].freeze
+
+    ENVIRONMENT_KEYS = %w[url healthcheck start_command sign_in].freeze
+    MANDATORY_KEYS = %w[id name why paths matrix].freeze
+
     def self.load(root = Dir.pwd)
       path = File.join(root, PATH)
-      new(File.exist?(path) ? YAML.safe_load_file(path) : {})
+      parse(File.exist?(path) ? File.read(path) : "")
+    end
+
+    # Settings as the default branch has them, for local commands run on a PR branch: a pull request
+    # must not point the agent at another URL or loosen the policy for its own run. Falls back to the
+    # checkout when the default branch has no settings yet. Returns [config, source].
+    def self.load_trusted(root = Dir.pwd, shell: Shell.new)
+      text = shell.call("git", "-C", root, "show", "origin/HEAD:#{PATH}")
+      [ parse(text), "origin/HEAD" ]
+    rescue Error
+      [ load(root), "working tree" ]
+    end
+
+    def self.parse(text)
+      new(text.to_s.strip.empty? ? {} : YAML.safe_load(text))
     rescue Psych::Exception => error
       raise Error, "#{PATH} is not valid YAML: #{error.message}"
     end
@@ -36,15 +76,35 @@ module BrowserReviewGate
     def initialize(data = {})
       data = {} unless data.is_a?(Hash)
       unknown = data.keys - DEFAULTS.keys
+      moved = unknown & %w[url start_command sign_in]
+      raise Error, "#{PATH}: #{moved.join(", ")} moved under environments.local in 0.3.0" if moved.any?
       raise Error, "#{PATH} has unknown keys: #{unknown.join(", ")}" if unknown.any?
 
       @data = DEFAULTS.merge(data.compact)
+      @sections = SECTIONS.to_h { |name, defaults| [ name, section(name, defaults) ] }
+      @environments = read_environments
+      validate
     end
 
-    DEFAULTS.each_key { |key| define_method(key) { @data[key] } }
+    (DEFAULTS.keys - %w[environments verification evidence scenarios gate provenance]).each do |key|
+      define_method(key) { @data[key] }
+    end
 
-    def app
-      { "start_command" => start_command, "url" => url, "sign_in" => sign_in }.compact
+    attr_reader :environments
+
+    def verification = @sections["verification"]
+    def evidence = @sections["evidence"]
+    def scenarios = @sections["scenarios"]
+    def gate = @sections["gate"]
+    def provenance = @sections["provenance"]
+
+    # The environment a run uses: the one named, the configured default, or the only one there is.
+    def environment(name = nil)
+      name ||= verification["environment"] || (environments.size == 1 ? environments.keys.first : nil)
+      return if name.nil?
+      raise Error, "Unknown environment #{name.inspect}; #{PATH} defines: #{environments.keys.join(", ")}" unless environments.key?(name)
+
+      environments.fetch(name).merge("name" => name)
     end
 
     def skip?(author:, branch:)
@@ -52,12 +112,183 @@ module BrowserReviewGate
     end
 
     # "dir/**" means everything under dir; other patterns are globs where "**/" spans directories.
-    def ignored?(path)
-      ignore_paths.any? do |pattern|
+    def ignored?(path) = Config.match?(ignore_paths, path)
+
+    def self.match?(patterns, path)
+      patterns.any? do |pattern|
         next path.start_with?(pattern.delete_suffix("**")) if pattern.end_with?("/**")
 
         File.fnmatch?(pattern, path, File::FNM_PATHNAME | File::FNM_DOTMATCH)
       end
     end
+
+    # Mandatory scenarios that apply to a change touching `paths`, expanded over the matrix where asked.
+    # They are added by this code, not proposed by the model, so a PR cannot talk its way out of them.
+    def mandatory_scenarios(paths)
+      scenarios["mandatory"].select { |entry| entry["paths"].nil? || paths.any? { |path| Config.match?(entry["paths"], path) } }
+        .flat_map { |entry| expand(entry) }
+    end
+
+    # What the settings ask of a run, split by who makes sure it happens.
+    def policy
+      {
+        "enforced" => {
+          "fail_on_console_errors" => verification["fail_on_console_errors"],
+          "fail_on_network_errors" => verification["fail_on_network_errors"],
+          "require_evidence" => gate["require_evidence"],
+          "block_on_failure" => gate["block_on_failure"],
+          "reuse_passing" => scenarios["reuse_passing"],
+          "max_scenarios" => scenarios["max_count"],
+          "trace_check" => provenance["trace"]
+        },
+        "agent" => {
+          "screenshots" => evidence["screenshots"],
+          "trace" => provenance["trace"] == "off" ? evidence["trace"] : "always",
+          "console_logs" => evidence["console_logs"], "network_logs" => evidence["network_logs"]
+        }
+      }
+    end
+
+    private
+
+    def section(name, defaults)
+      value = @data[name] || {}
+      raise Error, "#{PATH}: #{name} must be a mapping" unless value.is_a?(Hash)
+
+      unknown = value.keys - defaults.keys
+      raise Error, "#{PATH}: #{name} has unknown keys: #{unknown.join(", ")}" if unknown.any?
+
+      defaults.merge(value.compact)
+    end
+
+    def read_environments
+      listed = @data["environments"]
+      return {} unless listed
+      raise Error, "#{PATH}: environments must be a mapping of names to settings" unless listed.is_a?(Hash)
+
+      listed.to_h do |name, settings|
+        raise Error, "#{PATH}: environment name #{name.inspect} must be lowercase letters, digits, - or _" unless name.is_a?(String) && NAME_PATTERN.match?(name)
+        raise Error, "#{PATH}: environments.#{name} must be a mapping" unless settings.is_a?(Hash)
+
+        unknown = settings.keys - ENVIRONMENT_KEYS
+        raise Error, "#{PATH}: environments.#{name} has unknown keys: #{unknown.join(", ")}" if unknown.any?
+
+        [ name, settings.compact ]
+      end
+    end
+
+    def validate
+      environments.each do |name, settings|
+        url = settings["url"]
+        raise Error, "#{PATH}: environments.#{name}.url must be an http(s) URL" unless url.nil? || Config.http_url?(url)
+
+        check = settings["healthcheck"]
+        unless check.nil? || (check.is_a?(String) && (check.start_with?("/") || Config.http_url?(check)))
+          raise Error, "#{PATH}: environments.#{name}.healthcheck must be a path starting with / or an http(s) URL"
+        end
+      end
+      environment # the configured default must exist
+      validate_flags
+      validate_evidence
+      validate_provenance
+      validate_scenarios
+    end
+
+    def validate_flags
+      { "verification" => %w[fail_on_console_errors fail_on_network_errors], "evidence" => %w[console_logs network_logs],
+        "scenarios" => %w[reuse_passing], "gate" => %w[require_evidence block_on_failure] }.each do |name, keys|
+        keys.each do |key|
+          raise Error, "#{PATH}: #{name}.#{key} must be true or false" unless [ true, false ].include?(@sections[name][key])
+        end
+      end
+    end
+
+    def validate_evidence
+      %w[screenshots trace].each do |key|
+        next if EVIDENCE_MODES.include?(evidence[key])
+
+        raise Error, "#{PATH}: evidence.#{key} must be one of #{EVIDENCE_MODES.join(", ")}"
+      end
+      days = evidence["retention_days"]
+      raise Error, "#{PATH}: evidence.retention_days must be a whole number from 1 to 365" unless days.is_a?(Integer) && days.between?(1, 365)
+
+      hosts = evidence["link_hosts"]
+      return if hosts.is_a?(Array) && hosts.all? { |host| host.is_a?(String) && host.match?(/\A[a-z0-9.-]+\z/) }
+
+      raise Error, "#{PATH}: evidence.link_hosts must be a list of host names"
+    end
+
+    def validate_provenance
+      raise Error, "#{PATH}: provenance.trace must be one of #{TRACE_MODES.join(", ")}" unless TRACE_MODES.include?(provenance["trace"])
+      raise Error, "#{PATH}: provenance.revision_header must be an HTTP header name" unless provenance["revision_header"].to_s.match?(/\A[A-Za-z0-9-]{1,64}\z/)
+      raise Error, "#{PATH}: provenance.check_pages must be true or false" unless [ true, false ].include?(provenance["check_pages"])
+
+      skew = provenance["clock_skew_seconds"]
+      raise Error, "#{PATH}: provenance.clock_skew_seconds must be a whole number from 0 to 3600" unless skew.is_a?(Integer) && skew.between?(0, 3600)
+    end
+
+    def validate_scenarios
+      count = scenarios["max_count"]
+      raise Error, "#{PATH}: scenarios.max_count must be a whole number from 1 to #{MAX_SCENARIOS}" unless count.is_a?(Integer) && count.between?(1, MAX_SCENARIOS)
+
+      validate_matrix
+      mandatory = scenarios["mandatory"]
+      raise Error, "#{PATH}: scenarios.mandatory must be a list" unless mandatory.is_a?(Array)
+
+      mandatory.each_with_index { |entry, index| validate_mandatory(entry, index + 1) }
+      ids = mandatory_scenarios_all.map { |scenario| scenario["id"] }
+      raise Error, "#{PATH}: scenarios.mandatory ids must be unique after the matrix is applied" unless ids.uniq.size == ids.size
+
+      expanded = mandatory.count { |entry| entry["matrix"] } * matrix_combinations.size
+      raise Error, "#{PATH}: the matrix makes #{expanded} mandatory cases; keep it at #{MAX_MATRIX_CASES} or fewer" if expanded > MAX_MATRIX_CASES
+    end
+
+    def validate_matrix
+      matrix = scenarios["matrix"]
+      valid = matrix.is_a?(Hash) && matrix.all? do |name, values|
+        NAME_PATTERN.match?(name.to_s) && values.is_a?(Array) && values.any? && values.all? { |value| NAME_PATTERN.match?(value.to_s) }
+      end
+      raise Error, "#{PATH}: scenarios.matrix maps a dimension (e.g. role) to a list of short lowercase values" unless valid
+    end
+
+    def validate_mandatory(entry, position)
+      raise Error, "#{PATH}: scenarios.mandatory #{position} must be a mapping" unless entry.is_a?(Hash)
+
+      unknown = entry.keys - MANDATORY_KEYS
+      raise Error, "#{PATH}: scenarios.mandatory #{position} has unknown keys: #{unknown.join(", ")}" if unknown.any?
+      raise Error, "#{PATH}: scenarios.mandatory #{position} id must use letters, digits, dots, underscores or hyphens" unless entry["id"].is_a?(String) && Report::CASE_ID_PATTERN.match?(entry["id"])
+      raise Error, "#{PATH}: scenarios.mandatory #{position} needs a name" unless entry["name"].is_a?(String) && !entry["name"].strip.empty?
+      raise Error, "#{PATH}: scenarios.mandatory #{position} paths must be a list of globs" unless entry["paths"].nil? || (entry["paths"].is_a?(Array) && entry["paths"].all?(String))
+      raise Error, "#{PATH}: scenarios.mandatory #{position} matrix must be true or false" unless [ nil, true, false ].include?(entry["matrix"])
+    end
+
+    def mandatory_scenarios_all = scenarios["mandatory"].flat_map { |entry| expand(entry) }
+
+    # Every combination of the matrix dimensions, e.g. [{"role"=>"admin","viewport"=>"mobile"}, ...].
+    def matrix_combinations
+      matrix = scenarios["matrix"]
+      return [ {} ] if matrix.empty?
+
+      matrix.values.first.product(*matrix.values.drop(1)).map { |values| matrix.keys.zip(values).to_h }
+    end
+
+    def expand(entry)
+      base = { "id" => entry["id"], "name" => entry["name"].split.join(" "), "priority" => "critical", "category" => "mandatory",
+               "why" => entry["why"] || "Required by the project settings for the areas this change touches." }
+      return [ base ] unless entry["matrix"]
+
+      matrix_combinations.map do |combination|
+        suffix = combination.values.join(".")
+        details = combination.map { |dimension, value| "#{dimension} #{value}" }.join(", ")
+        base.merge("id" => "#{entry["id"]}.#{suffix}", "name" => "#{base["name"]} (#{details})", "matrix" => combination)
+      end
+    end
+
+    def self.http_url?(value)
+      uri = URI.parse(value.to_s)
+      %w[http https].include?(uri.scheme) && !uri.host.to_s.empty? && uri.userinfo.nil?
+    rescue URI::InvalidURIError
+      false
+    end
   end
 end