hecks 0.2.0 → 0.3.0

data/lib/hecks/forms/query_form_renderer.rb

@@ -0,0 +1,114 @@
+require "json"
+require "uri"
+require_relative "html"
+require_relative "field_shape"
+require_relative "field_renderer"
+require_relative "reference_options"
+require_relative "params"
+require_relative "record_table"
+
+module Hecks
+  module Forms
+    # Query -> the page body for its GET view — the working half of what
+    # `query_form.bluebook` names (see docs/command-form-and-query-form-
+    # bluebook.md): a canonical, shareable link (queries are GETs — every
+    # one of them is already a URL, so this says so up front rather than
+    # hiding that behind a form); a row of ready-made links for any
+    # closed-set parameter, since a caller filtering by an enum should not
+    # have to fill in a form to get a link they could just click; a filter
+    # FORM for everything else, which — being a GET form — produces
+    # exactly the same kind of link on submit; and the results table once
+    # a request actually supplies parameters.
+    module QueryFormRenderer
+      def self.render(registry:, domain:, aggregate:, query:, action:, params: {}, results: nil, error: nil)
+        fields = query.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
+        reference_options = ReferenceOptions.collect(registry, domain, fields)
+
+        <<~HTML
+          #{header(domain, aggregate, query)}
+          #{canonical_link(action, fields)}
+          #{quick_links(action, fields)}
+          #{filter_form(action, fields, params, reference_options)}
+          #{error_banner(error)}
+          #{results_section(aggregate, results, domain)}
+          #{inspect_panel(domain, aggregate, query, fields)}
+        HTML
+      end
+
+      def self.header(domain, aggregate, query)
+        <<~HTML
+          <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}")}</h1>
+          #{query.description ? %(<p class="goal">#{Escape.html(query.description)}</p>) : ''}
+          #{badges(query)}
+        HTML
+      end
+
+      def self.badges(query)
+        parts = []
+        parts << %(<span class="badge">limit #{Escape.html(query.limit.to_h[:value])}</span>) if query.limit
+        parts.join
+      end
+
+      def self.canonical_link(action, fields)
+        paths = Params.paths(fields)
+        template = paths.empty? ? action : "#{action}?#{paths.map { |path| "#{path}={#{path}}" }.join('&')}"
+        <<~HTML
+          <p class="help">Every query is a plain GET — this exact URL is bookmarkable, linkable from a dashboard, curlable, whatever a feature needs:</p>
+          <div class="link-row"><code id="canonical-link">#{Escape.html(template)}</code><button type="button" class="copy" data-copy="#canonical-link">copy</button></div>
+        HTML
+      end
+
+      # The one enum-shaped parameter (if there is one) rendered as literal,
+      # clickable links — no form to fill in for "show me the suspended
+      # ones". Capped at the FIRST closed-set field on purpose: a second one
+      # would mean a cross product of links, which reads as noise rather
+      # than help. A query with more than one is still fully reachable
+      # through the filter form below.
+      def self.quick_links(action, fields)
+        field = fields.find { |f| %i[select radio].include?(f.kind) }
+        return "" unless field
+
+        links = field.options.map do |value, label|
+          href = "#{action}?#{field.path}=#{URI.encode_www_form_component(value)}"
+          %(<a href="#{Escape.attr(href)}">#{Escape.html(field.label)}: #{Escape.html(label)}</a>)
+        end
+        %(<div class="example-links">#{links.join}</div>)
+      end
+
+      def self.filter_form(action, fields, params, reference_options)
+        return "" if fields.empty?
+
+        <<~HTML
+          <form method="get" action="#{Escape.attr(action)}">
+            #{fields.map { |f| FieldRenderer.render(f, values: params, reference_options: reference_options) }.join}
+            <div class="actions"><button type="submit">Run query</button></div>
+          </form>
+        HTML
+      end
+
+      def self.error_banner(error)
+        return "" unless error
+
+        %(<div class="error-banner" role="alert"><p><strong>#{Escape.html(error.class.name.split('::').last)}</strong> — #{Escape.html(error.message)}</p></div>)
+      end
+
+      def self.results_section(aggregate, results, domain)
+        return "" unless results
+
+        "<h2>Results (#{results.size})</h2>#{RecordTable.render(aggregate, results, domain: domain)}"
+      end
+
+      def self.inspect_panel(domain, aggregate, query, fields)
+        verb = "#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}"
+        paths = Params.paths(fields)
+        <<~HTML
+          <details class="inspect">
+            <summary>Inspect — #{Escape.html(verb)}</summary>
+            <p>Parameters: #{paths.empty? ? '<em>none</em>' : paths.map { |p| "<code>#{Escape.html(p)}</code>" }.join(', ')}</p>
+            <pre>#{Escape.html(JSON.pretty_generate(query.to_h))}</pre>
+          </details>
+        HTML
+      end
+    end
+  end
+end

data/lib/hecks/forms/record_renderer.rb

@@ -0,0 +1,115 @@
+require_relative "html"
+require_relative "field_shape"
+require_relative "record_table"
+
+module Hecks
+  module Forms
+    # The two pages a `.bluebook` doesn't declare but a browsing developer
+    # always wants: every record of an aggregate, and one record's own
+    # state plus what it can legally do next. Neither is a `query` — they
+    # read the repository directly, the same way `AggregateDoor#all`/`#find`
+    # do (facade/surface/aggregate_door.rb) — so they exist for every
+    # aggregate whether or not its bluebook declared a query at all.
+    module RecordRenderer
+      def self.index(registry:, domain:, aggregate:)
+        instances = registry.repository(domain, aggregate).all
+        <<~HTML
+          <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}")}</h1>
+          #{aggregate.description ? %(<p class="goal">#{Escape.html(aggregate.description)}</p>) : ''}
+          #{creating_links(domain, aggregate)}
+          <h2>Records (#{instances.size})</h2>
+          #{RecordTable.render(aggregate, instances, domain: domain)}
+          #{verb_list(domain, aggregate)}
+        HTML
+      end
+
+      def self.creating_links(domain, aggregate)
+        creators = aggregate.commands.select(&:creates?)
+        return "" if creators.empty?
+
+        links = creators.map { |cmd|
+          %(<a class="button" href="/#{domain}/#{aggregate.hecks_name}/#{cmd.hecks_name}.html">+ #{Escape.html(cmd.hecks_name)}</a>)
+        }
+        %(<div class="actions">#{links.join}</div>)
+      end
+
+      def self.show(registry:, domain:, aggregate:, id:)
+        instance = registry.repository(domain, aggregate).find(id)
+        return nil unless instance
+
+        state = instance.state
+        current = aggregate.lifecycle && state[aggregate.lifecycle.field]
+        <<~HTML
+          <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}")} <span class="mono">#{Escape.html(id)}</span></h1>
+          #{current ? %(<span class="badge role">#{Escape.html(aggregate.lifecycle.field)}: #{Escape.html(current)}</span>) : ''}
+          #{state_table(state)}
+          <h2>Commands</h2>
+          #{command_links(domain, aggregate, id, current)}
+          #{query_links(domain, aggregate)}
+        HTML
+      end
+
+      def self.state_table(state)
+        rows = state.map { |key, value|
+          "<tr><th>#{Escape.html(Humanize.label(key.to_s))}</th><td>#{Escape.html(render_value(value))}</td></tr>"
+        }
+        %(<div class="table-scroll"><table><tbody>#{rows.join}</tbody></table></div>)
+      end
+
+      # `Value.materialize` first — a stored field is a `Runtime::Value`
+      # wherever its attribute is a value object, not a plain Hash (see
+      # record_table.rb's own note on the same read).
+      def self.render_value(value)
+        case (value = Runtime::Value.materialize(value))
+        when Hash then value.map { |k, v| "#{k}: #{render_value(v)}" }.join(", ")
+        when Array then value.map { |v| render_value(v) }.join("; ")
+        else value.to_s
+        end
+      end
+
+      # Every non-creating command, EXCEPT a lifecycle transition that does
+      # not apply from the record's current state — the same rule
+      # `Rules#admissible_transition` enforces at dispatch, read here so a
+      # link that would only refuse is never offered in the first place.
+      def self.command_links(domain, aggregate, id, current_state)
+        commands = aggregate.commands.reject(&:creates?).select { |cmd| applies?(aggregate, cmd, current_state) }
+        return "<p><em>No commands act on an existing #{Escape.html(aggregate.hecks_name)}.</em></p>" if commands.empty?
+
+        items = commands.map do |cmd|
+          href = "/#{domain}/#{aggregate.hecks_name}/#{cmd.hecks_name}.html?to=#{Escape.attr(id)}"
+          %(<li><a href="#{href}"><span>#{Escape.html(cmd.hecks_name)}</span><span class="kind">#{Escape.html(cmd.goal.to_s)}</span></a></li>)
+        end
+        %(<ul class="verb-list">#{items.join}</ul>)
+      end
+
+      def self.applies?(aggregate, command, current_state)
+        transitions = aggregate.lifecycle&.transitions_for(command.hecks_name) || []
+        return true if transitions.empty?
+
+        transitions.any? { |t| t.from.nil? || Array(t.from).map(&:to_s).include?(current_state.to_s) }
+      end
+
+      def self.query_links(domain, aggregate)
+        return "" if aggregate.queries.empty?
+
+        items = aggregate.queries.map do |query|
+          %(<li><a href="/#{domain}/#{aggregate.hecks_name}/#{query.hecks_name}.html"><span>#{Escape.html(query.hecks_name)}</span><span class="kind">query</span></a></li>)
+        end
+        %(<h2>Queries</h2><ul class="verb-list">#{items.join}</ul>)
+      end
+
+      def self.verb_list(domain, aggregate)
+        commands = aggregate.commands.reject(&:creates?)
+        return "" if commands.empty? && aggregate.queries.empty?
+
+        cmd_items = commands.map { |c|
+          %(<li><a href="/#{domain}/#{aggregate.hecks_name}/#{c.hecks_name}.html"><span>#{Escape.html(c.hecks_name)}</span><span class="kind">command</span></a></li>)
+        }
+        query_items = aggregate.queries.map { |q|
+          %(<li><a href="/#{domain}/#{aggregate.hecks_name}/#{q.hecks_name}.html"><span>#{Escape.html(q.hecks_name)}</span><span class="kind">query</span></a></li>)
+        }
+        %(<h2>Every command &amp; query on #{Escape.html(aggregate.hecks_name)}</h2><ul class="verb-list">#{(cmd_items + query_items).join}</ul>)
+      end
+    end
+  end
+end

data/lib/hecks/forms/record_table.rb

@@ -0,0 +1,63 @@
+require_relative "html"
+require_relative "field_shape"
+
+module Hecks
+  module Forms
+    # The one shape every renderer in this directory reads a record as —
+    # `id` plus its state hash. `Runtime::Instance` already answers both,
+    # so `repository.all`'s own records pass straight through; a QUERY's
+    # answer does not (`QueryInterpreter#call` flattens `{id:}.merge(state)`
+    # into one hash with no method to call — see
+    # docs/command-form-and-query-form-bluebook.md's note on why), so
+    # app.rb wraps those results in one of these before they ever reach a
+    # renderer, and every renderer here only has to know one shape.
+    Record = Struct.new(:id, :state)
+
+    # An array of Record (or anything answering `#id`/`#state` — a
+    # Runtime::Instance qualifies without wrapping) -> an HTML table.
+    # Shared by the aggregate index page (record_renderer.rb) and a
+    # query's own results (query_form_renderer.rb) — the same records
+    # read the same columns either way.
+    module RecordTable
+      def self.columns(aggregate)
+        lifecycle = aggregate.lifecycle&.field
+        scalars = aggregate.attributes.reject { |a| a.reference? || a.list? }.map(&:name)
+        [*aggregate.identity_heads, lifecycle, *scalars].compact.uniq.first(7)
+      end
+
+      def self.render(aggregate, instances, domain:)
+        cols = columns(aggregate)
+        head = (["id"] + cols).map { |name| "<th>#{Escape.html(Humanize.label(name.to_s))}</th>" }.join
+        rows = instances.map { |instance| row(instance, aggregate, cols, domain) }
+        return "<p><em>No records.</em></p>" if rows.empty?
+
+        <<~HTML
+          <div class="table-scroll"><table>
+            <thead><tr>#{head}</tr></thead>
+            <tbody>#{rows.join}</tbody>
+          </table></div>
+        HTML
+      end
+
+      def self.row(instance, aggregate, cols, domain)
+        cells = cols.map { |name| "<td>#{Escape.html(cell(instance, name))}</td>" }.join
+        href = "/#{domain}/#{aggregate.hecks_name}/#{instance.id}.html"
+        "<tr><td><a href=\"#{Escape.attr(href)}\">#{Escape.html(instance.id)}</a></td>#{cells}</tr>"
+      end
+
+      def self.cell(instance, name)
+        # `state` holds `Runtime::Value` wherever an attribute is a value
+        # object, not a plain Hash — `.materialize` is the runtime's own
+        # unwrap (value.rb), the same one a `to_h` read anywhere else in
+        # this codebase goes through, so a table cell agrees with every
+        # other reader about what a stored field actually contains.
+        value = Runtime::Value.materialize(instance.state[name])
+        case value
+        when Hash then value.values.first
+        when nil then ""
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/hecks/forms/reference_options.rb

@@ -0,0 +1,30 @@
+module Hecks
+  module Forms
+    # A Field tree (field_shape.rb) -> `{path => [[id, label], ...]}` for
+    # every `:reference` field in it — the options a `<select>` needs.
+    # Shared by CommandFormRenderer and QueryFormRenderer alike: a
+    # command's own reference field and a query's own reference parameter
+    # resolve against the same repository the same way, and neither word
+    # owns this more than the other.
+    module ReferenceOptions
+      def self.collect(registry, domain, fields)
+        targets = {}
+        walk(fields) { |field| targets[field.path] = field.target_aggregate if field.kind == :reference }
+        targets.transform_values { |aggregate| aggregate && options_for(registry, domain, aggregate) }
+      end
+
+      def self.walk(fields, &block)
+        fields.each do |field|
+          block.call(field)
+          walk(field.children, &block) if field.children
+        end
+      end
+
+      def self.options_for(registry, domain, aggregate)
+        registry.repository(domain, aggregate).all.first(200).map { |instance| [instance.id, instance.id] }
+      rescue StandardError
+        nil # a wiring gap (no repository bound) degrades to a plain text id input, not a 500
+      end
+    end
+  end
+end

data/lib/hecks/forms/value_object_shape.rb

@@ -0,0 +1,46 @@
+module Hecks
+  module Forms
+    # THE VALUE-OBJECT CLASSIFICATION every consumer of a resolved VO
+    # shape needs, spelled once — `field_shape.rb` (a command's own
+    # form), `ui_schema.rb` (embryonaut_console's table/detail-panel
+    # renderer, a separate app, not this repo), and
+    # `adapters/driven/sql_query_builder.rb` (a query's own ORDER BY/
+    # WHERE compiler) each grew their own copy of "is this VO money-
+    # shaped," "does it have exactly one attribute, worth unwrapping,"
+    # and "which member of it is numeric" — the same three questions,
+    # answered identically by definition (a VO's shape doesn't change
+    # depending on who's asking), so a fix to one copy was never
+    # guaranteed to reach the others.
+    module ValueObjectShape
+      module_function
+
+      # `Price{cents:, currency:}`/`ContractValue{cents:, currency:}` —
+      # every money-shaped VO in the corpus spells it exactly this way,
+      # the two-attribute convention the language itself never enforces
+      # but every real chapter follows.
+      def money?(value_object)
+        value_object.attributes.map { |a| a.name.to_s }.sort == %w[cents currency]
+      end
+
+      # A VO with exactly one attribute is a NAME for a scalar, not a
+      # genuine group (EmailAddress{address}, CustomerNumber{value}) —
+      # [[feedback_name_the_scalar_field]]'s own reasoning, shared here
+      # rather than re-decided per caller. Returns the sole attribute,
+      # or nil for anything else.
+      def sole_attribute(value_object)
+        return nil unless value_object.attributes.size == 1
+
+        value_object.attributes.first
+      end
+
+      # The first Integer/Float member, or nil — what a numeric
+      # comparison or an ORDER BY compiles against when the VO isn't
+      # money-shaped (money's own two members are handled by `money?`
+      # instead, since which one governs ordering is a money-specific
+      # decision, not a general "pick the first number" one).
+      def numeric_member(value_object)
+        value_object.attributes.find { |a| %w[Integer Float].include?(a.type.to_s) }
+      end
+    end
+  end
+end

data/lib/hecks/forms.rb

@@ -0,0 +1,54 @@
+# The forms surface: `expose` (the DSL a `command_form.bluebook`/
+# `query_form.bluebook` will eventually become — see docs/
+# command-form-and-query-form-bluebook.md), the IR->HTML renderers, and
+# the Rack app that content-negotiates between them and a plain JSON
+# reading of the same dispatch. NOT required by `require "hecks"`
+# itself — a project that never boots this file never pays for `rack`,
+# the same lazy-dependency discipline the Gemfile's own comment already
+# holds `pg`/`oauth2`/`aws-sdk-lambda` to.
+#
+# See docs/command-form-and-query-form-bluebook.md for the design this
+# implements and what it deliberately leaves for later.
+require "hecks"
+require_relative "forms/app"
+
+module Hecks
+  module Forms
+    # `expose`'s own declaration — "which chapters does this app expose" —
+    # kept OUTSIDE the `Hecks.*` collector convention (`Hecks.bluebook`,
+    # `Hecks.hecksagon`, ...) and outside `Runtime::Registry` entirely, on
+    # purpose: a real language word goes through `syntax.bluebook` and
+    # `MetaValidator` (see docs/implemented/guides/extending-hecks.md, "a new word is a
+    # declared row before it is a line of Ruby") and is judged by
+    # spec/syntax_conformance_spec.rb + spec/dsl_coverage_spec.rb — gates
+    # this construct has not earned yet. An ordinary Ruby DSL, one level of
+    # module state, no different in kind from a project's own initializer —
+    # see docs/command-form-and-query-form-bluebook.md, "why this isn't
+    # syntax.bluebook yet".
+    #
+    # ONE `expose` GRANTS A WHOLE CHAPTER, not a command or a query
+    # individually — the future `command_form.bluebook`/`query_form.bluebook`
+    # words are PER-DECLARATION (one command, one query, its own form/view,
+    # possibly its own overrides), which `expose` doesn't do today and was
+    # never trying to; it's the coarse "turn this chapter's forms on at
+    # all" switch those finer words will eventually sit inside.
+    class Config
+      attr_reader :name, :exposes
+
+      def initialize(name)
+        @name    = name.to_s
+        @exposes = []
+      end
+
+      def expose(chapter_name) = @exposes << chapter_name.to_s
+    end
+
+    def self.configure(name, &block)
+      config = Config.new(name)
+      config.instance_eval(&block) if block
+      (@configs ||= {})[config.name] = config
+    end
+
+    def self.config(name) = (@configs || {})[name.to_s]
+  end
+end

data/lib/hecks/fqn.rb

@@ -0,0 +1,94 @@
+module Hecks
+  # A public Bluebook command/query address.
+  #
+  # Realm is deployment identity from a world. Domain@version pins a domain
+  # contract; an unpinned domain is the world's configured latest alias.
+  class Fqn
+    class Invalid < ArgumentError; end
+
+    attr_reader :realm, :domain, :version, :aggregate, :verb
+
+    def self.command(realm:, domain:, aggregate:, command:, version: nil)
+      new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: command, kind: :command)
+    end
+
+    def self.query(realm:, domain:, aggregate: nil, query:, version: nil)
+      new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: query, kind: :query)
+    end
+
+    def self.parse(text)
+      head, separator, verb = text.to_s.rpartition(".")
+      raise Invalid, "FQN must be Realm::Domain::Aggregate.verb — got #{text.inspect}" if separator.empty?
+
+      segments = head.split("::", -1)
+      raise Invalid, "FQN must be Realm::Domain::Aggregate.verb — got #{text.inspect}" unless [1, 2, 3].include?(segments.length) && segments.none?(&:empty?) && !verb.empty?
+
+      realm, domain_spec, aggregate = case segments.length
+                                      when 3 then segments
+                                      # A two-segment lowercase address is the
+                                      # public realm/domain form for a
+                                      # domain-level read model.
+                                      when 2 then query_name?(verb) ? [segments[0], segments[1], nil] : [nil, *segments]
+                                      else [nil, segments.first, nil]
+                                      end
+      domain, version = split_domain(domain_spec)
+      kind = if command_name?(verb)
+               :command
+             elsif query_name?(verb)
+               :query
+             else
+               raise Invalid, "FQN verb must be PascalCase command or snake_case query — got #{text.inspect}"
+             end
+
+      raise Invalid, "domain-level FQNs are query-only — got #{text.inspect}" if aggregate.nil? && kind == :command
+
+      new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: verb, kind: kind)
+    end
+
+    def self.command_name?(name) = /\A[A-Z][A-Za-z0-9]*\z/.match?(name.to_s)
+    def self.query_name?(name)   = /\A[a-z][a-z0-9_]*\z/.match?(name.to_s)
+
+    def initialize(realm:, domain:, version: nil, aggregate:, verb:, kind:)
+      @realm     = realm && segment(realm, "realm")
+      @domain    = segment(domain, "domain")
+      @version   = version && segment(version, "version")
+      @aggregate = aggregate && segment(aggregate, "aggregate")
+      @verb      = segment(verb, "verb")
+      @kind      = kind.to_sym
+
+      valid = command? ? self.class.command_name?(@verb) : self.class.query_name?(@verb)
+      raise Invalid, "#{@kind} FQN has an invalid verb #{@verb.inspect}" unless valid
+    end
+
+    def command? = @kind == :command
+    def query?   = @kind == :query
+    def kind     = @kind
+
+    def to_s
+      domain = @version ? "#{@domain}@#{@version}" : @domain
+      [[@realm, domain, @aggregate].compact.join("::"), @verb].join(".")
+    end
+
+    def ==(other) = other.is_a?(Fqn) && to_s == other.to_s
+    alias eql? ==
+    def hash = to_s.hash
+
+    private
+
+    def self.split_domain(value)
+      domain, version, extra = value.to_s.split("@", 3)
+      raise Invalid,
+            "FQN domain version is malformed: #{value.inspect}" if domain.empty? || extra || (value.include?("@") && version.to_s.empty?)
+
+      [domain, version]
+    end
+
+    def segment(value, label)
+      text = value.to_s
+      raise Invalid,
+            "FQN #{label} cannot be empty or contain a separator" if text.empty? || text.include?("::") || text.include?(".") || text.include?("@")
+
+      text
+    end
+  end
+end

data/lib/hecks/framework/bluebook/compliance.bluebook

@@ -0,0 +1 @@
+../../../../examples/compliance/bluebook/compliance.bluebook