hecks 3.2.0 → 3.3.0

data/lib/hecks/projections/site/site_cdn.rb

@@ -11,9 +11,10 @@ module Hecks
       # on it: the distribution's cache behaviours and the load balancer's listener rules.
       #
       # The blocks are returned by name, `"behaviors"` and `"listener_rules"`, as text from the
-      # left margin. `Regions` puts each between the markers of the same name in the project's
-      # template, at the markers' indentation. The text is a pure function of the table and the
-      # edge rows.
+      # left margin; a project whose `Edge` row says `alb: false` has no load balancer and gets
+      # `"behaviors"` alone. `Regions` puts each between the markers of the same name in the
+      # project's template, at the markers' indentation. The text is a pure function of the table
+      # and the edge rows.
       module SiteCdn
         extend Projector::Target
 
@@ -25,7 +26,7 @@ module Hecks
         # @param options [Hash{Symbol => Object}] `:registry` (Runtime::Registry) the project booted
         #   into; or `:table` (Table) and `:edge` (Edge), already read
         # @return [Hash{String => String}] each region's name to its text; empty when the chapter
-        #   declares no edge
+        #   declares no edge, and without `"listener_rules"` when the edge has no load balancer
         # @raise [Table::Invalid] when the table or the edge is refused
         def call(bluebook:, options: {})
           registry = options[:registry]
@@ -33,6 +34,8 @@ module Hecks
           edge = options[:edge] || Edge.read(bluebook, table: table, vocabulary: Table.vocabulary(registry))
           return {} unless edge
 
+          return { "behaviors" => behaviors(edge) } unless edge.alb?
+
           { "behaviors" => behaviors(edge), "listener_rules" => listener_rules(edge) }
         end
 

data/lib/hecks/projections/site/table/checks.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
+require_relative "../edge/pattern"
+
 module Hecks
   module Projections
     module Site
       class Table
         # What no single row can show, and what a row contradicts in itself once its defaults are
-        # filled: a path declared twice, a switch the rows disagree on, an off route that sits in a
-        # navigation, an indexable route that is not public.
+        # filled: a path declared twice, a switch the rows disagree on, a navigation entry that
+        # cannot be linked to, an indexable route that is not public, a public route beneath a
+        # prefix that is not.
         class Checks
           SWITCH_ID = /\A[a-z][a-z0-9_]*\z/
+          FRAGMENT = /\A[A-Za-z0-9][\w:.-]*\z/
           PUBLIC_MENUS = %w[desktop mobile footer].freeze
 
           # The navigation slots a row sits in.
           #
-          # @param row [Row] a row
+          # @param row [Row, Link] a row or link
           # @return [Array<String>] some of `desktop`, `mobile`, `footer`, `admin`
           def self.navigation(row)
             { "desktop" => row.nav_order, "mobile" => row.mobile_order, "footer" => row.footer_column,
@@ -22,8 +26,10 @@ module Hecks
 
           # @param rows [Array<Row>] the table's rows, defaults filled in
           # @param problems [Array<String>] collects each problem found, one line each
-          def initialize(rows, problems)
+          # @param links [Array<Link>] the table's extra navigation entries
+          def initialize(rows, problems, links: [])
             @rows = rows
+            @links = links
             @problems = problems
           end
 
@@ -32,7 +38,8 @@ module Hecks
             check_duplicate_paths
             check_switches
             @rows.each { |row| check_row(row) }
-            check_unique(@rows.filter_map(&:admin_key), "admin key")
+            @links.each { |link| check_link(link) }
+            check_unique((@rows + @links).filter_map(&:admin_key), "admin key")
             check_unique(@rows.map(&:source).grep(/\Aglobal:/), "source")
           end
 
@@ -63,6 +70,7 @@ module Hecks
             check_redirect(row, path)
             check_navigation(row, path)
             check_indexing(row, path)
+            check_beneath_prefix(row, path)
             return unless row.preview == "draft" && row.source == "none"
 
             problem(path, "previews as a draft but has source none; a draft preview needs a global: or collection: source")
@@ -90,13 +98,51 @@ module Hecks
             slots = self.class.navigation(row)
             return if slots.empty?
 
-            problem(path, "is off and sits in the #{slots.join(' and ')} navigation") if row.off
-            problem(path, "sits in the navigation but is a #{row.kind}; only a page does") unless row.kind == "page"
+            unless row.verbs.include?("GET")
+              problem(path, "sits in the navigation but answers #{row.verbs.join(',')}; a link is a GET")
+            end
             problem(path, "sits in the navigation and has a parameter") if path.match?(/[:*]/)
             problem(path, "sits in the navigation and has no label") if row.label.to_s.empty?
+            check_heading(row, path)
             check_menu_audience(row, path, slots)
           end
 
+          def check_heading(item, path)
+            return unless item.mobile_heading
+            return problem(path, "has a mobile_heading but no mobile_order") if item.mobile_order.nil?
+
+            problem(path, "has an empty mobile_heading") if item.mobile_heading.strip.empty?
+          end
+
+          def check_link(link)
+            path = "NavLink #{link.path}"
+            slots = self.class.navigation(link)
+            problem(path, "sits in no navigation; give it nav_order, mobile_order, footer_column or admin_key") if slots.empty?
+            problem(path, "has a parameter; a link is to one page") if link.path.to_s.match?(/[:*]/)
+            problem(path, "has no label") if link.label.to_s.empty?
+            if link.fragment && !link.fragment.match?(FRAGMENT)
+              problem(path, "has fragment #{link.fragment.inspect}; a fragment is an element id, written without #")
+            end
+            check_heading(link, path)
+            check_menu_audience(link, path, slots)
+          end
+
+          # A public route under a prefix that is not public (the sign-in page beside the admin
+          # pages) inherits nothing from the prefix, so the row has to say what it is: its cache
+          # class is declared, not derived from its auth.
+          def check_beneath_prefix(row, path)
+            return if row.auth != "public" || row.explicit_cache || row.path.nil?
+
+            pattern = Edge::Pattern.edge(row.path)
+            prefix = @rows.find do |other|
+              other.auth != "public" && other.path && Edge::Pattern.strictly_covers?(Edge::Pattern.edge(other.path), pattern)
+            end
+            return unless prefix
+
+            problem(path, "is public but sits beneath #{prefix.path}, which is #{prefix.auth}; " \
+                          "name its cache class (cache: \"no_store\" for a sign-in page) to say that is meant")
+          end
+
           def check_menu_audience(row, path, slots)
             public_slots = slots & PUBLIC_MENUS
             if row.auth != "public" && public_slots.any?

data/lib/hecks/projections/site/table/link_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Table
+        # One extra navigation entry that points at a route the table declares, optionally at a
+        # fragment of its page. `off` and `switch` are copied from the route it points at.
+        Link = Struct.new(:path, :fragment, :label, :nav_group, :nav_order, :mobile_order, :mobile_heading,
+                          :footer_column, :footer_order, :admin_key, :admin_order, :off, :switch, :auth,
+                          keyword_init: true)
+
+        # Turns a declared `NavLink` member into a `Link`: checks its fields and their types, and
+        # copies the facts it shares with the route it points at.
+        class LinkBuilder
+          # The fields a link may carry, with the Ruby class each takes.
+          FIELDS = { path: String, fragment: String, label: String, nav_group: String, nav_order: Integer,
+                     mobile_order: Integer, mobile_heading: String, footer_column: String,
+                     footer_order: Integer, admin_key: String, admin_order: Integer }.freeze
+
+          # @param rows [Array<Row>] the table's rows, which a link points at
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(rows, problems)
+            @rows = rows
+            @problems = problems
+          end
+
+          # @param member [Hash{Symbol => Object}] the declared fields of one link
+          # @param index [Integer] the link's position, for a message about a link with no path
+          # @return [Link] the link; its problems are in `problems`
+          def call(member, index)
+            label = "NavLink #{member[:path] || "row #{index + 1}"}"
+            fields = checked_fields(member, label)
+            target = @rows.find { |row| row.path == fields[:path] && row.verbs.include?("GET") }
+            problem(label, "points at no route that answers GET; declare the route first") unless target
+            link = Link.new(**fields, off: target ? target.off : false, switch: target ? target.switch : "",
+                                      auth: target ? target.auth : "public")
+            link.footer_order ||= 0 if link.footer_column
+            link.admin_order ||= 0 if link.admin_key
+            link
+          end
+
+          private
+
+          def checked_fields(member, label)
+            member.each_key do |key|
+              problem(label, "has no field #{key}; fields are #{FIELDS.keys.join(', ')}") unless FIELDS.key?(key)
+            end
+            known = member.slice(*FIELDS.keys)
+            known.each do |key, value|
+              next if value.is_a?(FIELDS.fetch(key))
+
+              problem(label, "has #{key} #{value.inspect}; #{key} is a #{FIELDS.fetch(key)}")
+            end
+            problem(label, "needs a path") unless known[:path]
+            known
+          end
+
+          def problem(label, text) = @problems << "#{label} #{text}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/table/row_builder.rb

@@ -8,7 +8,8 @@ module Hecks
         Row = Struct.new(:path, :kind, :render, :auth, :verbs, :cache, :origin, :source,
                          :indexable, :switch, :off, :preview, :label, :seo, :redirect_to, :aliases,
                          :nav_group, :nav_order, :mobile_order, :footer_column, :footer_order,
-                         :admin_key, :admin_order, :compress, :alb_rule, :cdn, keyword_init: true)
+                         :admin_key, :admin_order, :compress, :alb_rule, :cdn,
+                         :seo_title, :edge_verbs, :mobile_heading, :explicit_cache, keyword_init: true)
 
         # Turns a declared member into a `Row`: checks its fields and their types, fills the
         # defaults, and checks each closed-set value against the Site chapter's vocabulary.
@@ -19,7 +20,8 @@ module Hecks
                      off: :bool, preview: String, label: String, seo: String, redirect_to: String,
                      aliases: String, nav_group: String, nav_order: Integer, mobile_order: Integer,
                      footer_column: String, footer_order: Integer, admin_key: String,
-                     admin_order: Integer, compress: :bool, alb_rule: String, cdn: :bool }.freeze
+                     admin_order: Integer, compress: :bool, alb_rule: String, cdn: :bool,
+                     seo_title: String, edge_methods: String, mobile_heading: String }.freeze
 
           # The value objects of the Site chapter's `Route` aggregate whose members are the closed
           # sets, by the row field each constrains.
@@ -50,7 +52,9 @@ module Hecks
             label = path || label
             check_source(label, source)
             verbs = fields.delete(:methods)
-            row = Row.new(**fields, verbs: verbs, path: path, source: source,
+            edge_verbs = fields.delete(:edge_methods)
+            row = Row.new(**fields, verbs: verbs, edge_verbs: edge_verbs, path: path, source: source,
+                                    explicit_cache: !fields[:cache].nil?,
                                     kind: fields[:kind] || default_kind(source), auth: fields[:auth] || "public",
                                     origin: fields[:origin] || default_origin(source))
             fill_defaults(row)
@@ -94,6 +98,7 @@ module Hecks
             row.cdn = true if row.cdn.nil?
             row.render ||= row.kind == "page" ? "prerender" : "ssr"
             row.verbs = list(row.verbs || (row.source.start_with?("command:") ? "POST" : "GET"))
+            row.edge_verbs = row.edge_verbs.nil? ? row.verbs : list(row.edge_verbs)
             row.aliases = list(row.aliases)
             row.cache ||= default_cache(row)
             row.indexable = indexable_by_default?(row) if row.indexable.nil?
@@ -123,11 +128,21 @@ module Hecks
 
               problem(label, "has #{field} #{row[field].inspect}; #{field} is one of #{@vocabulary.fetch(field).join(', ')}")
             end
-            row.verbs.each do |verb|
-              next if @vocabulary.fetch(:http_method).include?(verb)
+            check_verbs(row, label)
+          end
+
+          def check_verbs(row, label)
+            { "method" => row.verbs, "edge method" => row.edge_verbs }.each do |what, verbs|
+              verbs.each do |verb|
+                next if @vocabulary.fetch(:http_method).include?(verb)
 
-              problem(label, "has method #{verb.inspect}; methods are #{@vocabulary.fetch(:http_method).join(', ')}")
+                problem(label, "has #{what} #{verb.inspect}; methods are #{@vocabulary.fetch(:http_method).join(', ')}")
+              end
             end
+            return if (row.verbs - row.edge_verbs).empty?
+
+            problem(label, "has edge_methods #{row.edge_verbs.join(',')}, which leave out its methods " \
+                           "#{(row.verbs - row.edge_verbs).join(',')}; the edge must allow every verb the route answers")
           end
 
           def check_source(label, source)

data/lib/hecks/projections/site/table.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "table/row_builder"
+require_relative "table/link_builder"
 require_relative "table/checks"
 
 module Hecks
@@ -21,9 +22,15 @@ module Hecks
         # The name of the value object a client declares its rows in.
         ROW_OBJECT = "Route"
 
+        # The name of the value object a client declares its extra navigation entries in.
+        LINK_OBJECT = "NavLink"
+
         # @return [Array<Row>] the rows, in the order the client declared them
         attr_reader :rows
 
+        # @return [Array<Link>] the extra navigation entries, in the order the client declared them
+        attr_reader :links
+
         # Finds the one chapter of a project that declares the route table.
         #
         # @param registry [Runtime::Registry] the registry the project booted into
@@ -47,7 +54,8 @@ module Hecks
         # @return [Table] the checked table
         # @raise [Invalid] when the Site chapter is not attached or a row is refused
         def self.read(chapter, registry:)
-          new(rows_of(chapter), vocabulary: vocabulary(registry), registry: registry)
+          new(rows_of(chapter), vocabulary: vocabulary(registry), registry: registry,
+                                links: rows_of(chapter, LINK_OBJECT))
         end
 
         # @param registry [Runtime::Registry] a registry holding the Site chapter
@@ -76,20 +84,23 @@ module Hecks
         # @param vocabulary [Hash{Symbol => Array<String>}] the closed sets
         # @param registry [Runtime::Registry, nil] where a `command:` or `query:` source is looked
         #   up; nil skips that check
+        # @param links [Array<Hash{Symbol => Object}>] the declared `NavLink` rows
         # @raise [Invalid] when a row is refused
-        def initialize(members, vocabulary:, registry: nil)
+        def initialize(members, vocabulary:, registry: nil, links: [])
           problems = []
           builder = RowBuilder.new(vocabulary: vocabulary, registry: registry, problems: problems)
           @rows = members.each_with_index.map { |member, index| builder.call(member, index) }
-          Checks.new(@rows, problems).call
+          link_builder = LinkBuilder.new(@rows, problems)
+          @links = links.each_with_index.map { |member, index| link_builder.call(member, index) }
+          Checks.new(@rows, problems, links: @links).call
           return if problems.empty?
 
           raise Invalid, "the route table is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
         end
 
-        # The navigation slots a row sits in.
+        # The navigation slots a row or link sits in.
         #
-        # @param row [Row] a row
+        # @param row [Row, Link] a row or link
         # @return [Array<String>] some of `desktop`, `mobile`, `footer`, `admin`
         def navigation(row) = Checks.navigation(row)
       end

data/lib/hecks/quality_control/adapters/git_pr.rb

@@ -64,20 +64,6 @@ module Hecks
         raise Refusal, "the working tree at #{@repo_dir} is dirty — commit or discard first:\n#{dirty}"
       end
 
-      # Refuses one more pull request than the day's cap allows; a cap of zero is no cap.
-      #
-      # @param opened_today [Integer] how many PRs the ledger recorded since local midnight
-      # @param cap [Integer] `PR_CAP_PER_DAY`
-      # @return [void]
-      # @raise [Refusal] when `opened_today` has reached a positive `cap`
-      def assert_under_daily_cap!(opened_today:, cap:)
-        return unless cap.positive? && opened_today >= cap
-
-        raise Refusal, "#{opened_today} PR(s) already opened since local midnight, and " \
-                       "QualityControlDials::PR_CAP_PER_DAY is #{cap} — leave this as an open Bug/Angle " \
-                       "and open it tomorrow, or raise the dial in qa/settings.yml"
-      end
-
       # Refuses a fix commit that is not part of the branch being opened.
       #
       # @param commit [String] the commit the ledger says fixes the bug

data/lib/hecks/quality_control/cli/qa_discover_external_domains.rb

@@ -26,7 +26,7 @@ module Hecks
       SKIP_DIR_BASENAMES = %w[.git .hg .svn vendor node_modules .bundle tmp log coverage .yardoc .ruby-lsp
                               .parked bower_components .claude dist build].freeze
 
-      # Word-boundary matched so "hecksagain" (a real, separate gem) and "hecks_site" never
+      # Word-boundary matched so a near-miss gem name (a separate gem) and "hecks_site" never
       # false-positive as a hecks dependency.
       GEMFILE_PATTERN = /gem\s*\(?\s*["']hecks["']/
       GEMFILE_LOCK_PATTERN = /^\s+hecks\s+\(/

data/lib/hecks/quality_control/cli/qa_open_pr.rb

@@ -15,9 +15,10 @@ module Hecks
     # take the record and the `GitPr` adapter agrees. The command's `given`s are the rules, asked
     # as a dry run before anything is opened: the branch starts with the practice's prefix; with
     # `--bug`, the bug is `fixed`; with `--angle`, it is `investigating`. The adapter answers the
-    # rest: the tree is clean, `PR_CAP_PER_DAY` (0 = uncapped) is unmet since local midnight, and
-    # the bug's commit is an ancestor of `HEAD`. It is idempotent. `QA_REPO_DIR` picks the checkout
-    # `git` runs in, so a spec can use a throwaway repo and a fake `gh`.
+    # rest: the tree is clean and the bug's commit is an ancestor of `HEAD`. The per-day cap
+    # (`PR_CAP_PER_DAY`, 0 = uncapped) is `DailyQuota.Take`'s own `given`: asked as a dry run with
+    # the others, and taken for real once the PR is recorded. It is idempotent. `QA_REPO_DIR`
+    # picks the checkout `git` runs in, so a spec can use a throwaway repo and a fake `gh`.
     class QaOpenPr
       EXIT_OK = 0
 
@@ -147,7 +148,10 @@ module Hecks
           "reads as picked up before something is built from it)"
         when "the branch is one this practice recognises as its own"
           " (the branch is #{@branch.inspect}; a PR this practice opens is on a branch it can recognise " \
-          "as its own, QualityControlDials::BRANCH_PREFIX)"
+          "as its own)"
+        when "the day's cap is not spent"
+          " (QualityControlDials::PR_CAP_PER_DAY is #{dial(:PR_CAP_PER_DAY, 0)} — leave this as an open " \
+          "Bug/Angle and open it tomorrow, or raise the dial in qa/settings.yml)"
         else ""
         end
       end
@@ -184,15 +188,23 @@ module Hecks
         check_ancestry
       end
 
+      # The record of the UTC day the clock reads: `DailyQuota.Today` fills the day from the clock.
+      def todays_quota = query("DailyQuota.Today").first
+
+      # A day with no record has spent nothing, so only an opened day can refuse.
       def check_daily_cap
         cap = dial(:PR_CAP_PER_DAY, 0)
-        return unless cap.positive?
+        quota = todays_quota
+        return unless cap.positive? && quota
+
+        refuse_unless_ledger_takes("QualityControl::DailyQuota.Take", today: quota[:today], cap: { value: cap })
+      end
 
-        today = Time.now
-        midnight = Time.new(today.year, today.month, today.day).to_i
-        opened_today = query("Patch.OpenedSince", since: { value: midnight }).size +
-                       query("Improvement.OpenedSince", since: { value: midnight }).size
-        refusing { @git_pr.assert_under_daily_cap!(opened_today: opened_today, cap: cap) }
+      # Counts the PR just recorded against the day, opening the day's record on its first.
+      def take_daily_slot
+        row = todays_quota
+        quota = row ? ::QualityControl::DailyQuota.find(row[:today][:value]) : ::QualityControl::DailyQuota.open!
+        quota.take!(cap: { value: dial(:PR_CAP_PER_DAY, 0) })
       end
 
       def check_ancestry
@@ -271,6 +283,7 @@ module Hecks
           branch: { value: view[:headRefName] }, commit: { value: sha }, title: { value: view[:title] },
           now: { value: now }
         )
+        take_daily_slot
         puts "recorded Patch ##{number} for #{@bug.id} at #{sha[0, 7]}"
       end
 
@@ -282,12 +295,15 @@ module Hecks
         end
 
         # A run that stopped between `open!` and `land!` leaves the record `opened`: finish it.
-        existing || ::QualityControl::Improvement.open!(
-          **(@angle ? { angle: @angle.id } : {}),
-          number: { value: number }, url: { value: view[:url] },
-          branch: { value: view[:headRefName] }, title: { value: view[:title] },
-          now: { value: now }
-        )
+        unless existing
+          ::QualityControl::Improvement.open!(
+            **(@angle ? { angle: @angle.id } : {}),
+            number: { value: number }, url: { value: view[:url] },
+            branch: { value: view[:headRefName] }, title: { value: view[:title] },
+            now: { value: now }
+          )
+          take_daily_slot
+        end
         ::QualityControl::Improvement.find(number).land!(number: { value: number }, commit: { value: sha })
         puts "recorded Improvement ##{number}#{" for #{@angle.id}" if @angle}, landed at #{sha[0, 7]}"
       end

data/lib/hecks/quality_control/cli/qa_seed_angles.rb

@@ -54,13 +54,13 @@ module Hecks
                      "cannot see, because there is no second engine to disagree with. " \
                      "spec/rust_conformance_fuzz_spec.rb's own DOMAINS list wires up only pizzas and " \
                      "banking for CI-gated differential fuzzing. rust/Cargo.toml already declares " \
-                     "compiled-binary features for compliance and roster (plus embryonaut and meta) that " \
+                     "compiled-binary features for compliance and roster (plus meta) that " \
                      "sit unused for this purpose; examples/chess and examples/directory have no Cargo " \
                      "feature at all — `hecks project_rust` has never regenerated a binary for either. " \
                      "Widening either list would let differential fuzzing catch a whole bug class " \
                      "Ruby-only fuzzing cannot, on domains the practice already owns.",
           citation:  "BUG#1/#3/#4 (engine-divergence bugs); spec/rust_conformance_fuzz_spec.rb DOMAINS " \
-                     "(pizzas/banking only); rust/Cargo.toml [features] (compliance/roster/embryonaut/" \
+                     "(pizzas/banking only); rust/Cargo.toml [features] (compliance/roster/" \
                      "meta have binaries and are not wired in; chess/directory have no feature at all)",
           proposer:  "Claude QA"
         },

data/lib/hecks/quality_control/cli/qa_seed_targets.rb

@@ -12,8 +12,7 @@ module Hecks
     # rotation `Target`, printing each one's inferred capabilities. It is idempotent: references
     # already on file are skipped whatever their status (re-`Identify` refuses).
     #
-    # It skips `examples/embryonaut` (an external product) and `lib/hecks/framework` (no standalone
-    # Rust binary) on purpose.
+    # It skips `lib/hecks/framework` (no standalone Rust binary) on purpose.
     class QaSeedTargets
       # Identifies the targets the ledger lacks.
       #