hecks 3.4.2 → 3.5.0

data/lib/hecks/projections/site/payload/fields.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        # The TypeScript that ties a Payload collection to an aggregate: the collection's field
+        # definitions, one per attribute, and the function that reads a saved document back into the
+        # aggregate's input.
+        #
+        # Both come from the attribute's shape and, where the editor needs something the shape
+        # cannot
+        # say (a date picker, a choice list, an upload, a relation), from a `PayloadField` row.
+        # They are
+        # produced together so a field and the code that reads it cannot disagree.
+        module Fields
+          BANNER = "// Generated by hecks site site_projection.project_site. Do not edit."
+
+          # The kinds a row may name, with the Payload field type each is.
+          KINDS = { "text" => "text", "textarea" => "textarea", "select" => "select", "date" => "date", "day" => "date",
+                    "number" => "number", "upload" => "upload", "relationship" => "relationship" }.freeze
+
+          module_function
+
+          # @param aggregates [Array<Model::Aggregate>] the aggregates to drive
+          # @param rows [Array<Hash{Symbol => Object}>] the checked `PayloadField` rows
+          # @param specs [String] the import path of the generated specs module
+          # @param helpers [String] the import path of the module that holds `nonBlank` and its kin
+          # @return [String] the module
+          # @raise [ArgumentError] when a row names an aggregate or an attribute the domain lacks
+          def render(aggregates, rows:, specs:, helpers:)
+            check(aggregates, rows)
+            body = aggregates.map { |agg| aggregate(agg, rows.select { |row| row[:aggregate] == agg.noun }) }
+            [BANNER, header(aggregates, specs, helpers), shared, *body].join("\n\n") << "\n"
+          end
+
+          def check(aggregates, rows)
+            rows.each do |row|
+              agg = aggregates.find { |candidate| candidate.noun == row[:aggregate] }
+              raise ArgumentError, "PayloadField names #{row[:aggregate]}, which it does not drive" unless agg
+
+              check_attribute(agg, row)
+              check_kind(row)
+            end
+          end
+
+          def check_attribute(agg, row)
+            top, part = row[:attribute].split(".", 2)
+            attr = agg.attrs.find { |candidate| candidate.name == top }
+            where = "PayloadField #{row[:aggregate]}.#{row[:attribute]}"
+            raise ArgumentError, "#{where} is not an attribute" unless attr
+            raise ArgumentError, "#{where} is not a part" if part && !attr.parts&.any? { |each| each.name == part }
+          end
+
+          def check_kind(row)
+            kind = row[:kind]
+            if kind && !KINDS.key?(kind)
+              raise ArgumentError,
+                    "PayloadField kind #{kind.inspect} is one of #{KINDS.keys.join(', ')}"
+            end
+            return unless %w[upload relationship].include?(kind) && !row[:relation]
+
+            raise ArgumentError, "PayloadField #{row[:attribute]} is #{kind} and needs a relation"
+          end
+
+          def header(aggregates, specs, helpers)
+            types = aggregates.map { |agg| "type #{agg.noun}Input" }.join(", ")
+            <<~TS.chomp
+              import type { Field, PayloadRequest } from "payload";
+
+              import { isoOrNull, nonBlank, related, type Doc } from #{helpers.to_json};
+              import { #{types} } from #{specs.to_json};
+            TS
+          end
+
+          def shared
+            <<~TS.chomp
+              const valuesOf = (value: unknown, pick: (raw: unknown) => string | null): string[] =>
+                (Array.isArray(value) ? value : []).map((row) => pick((row as Doc)?.value)).filter((item): item is string => !!item);
+            TS
+          end
+
+          def aggregate(agg, rows)
+            var = "#{agg.noun[0].downcase}#{agg.noun[1..]}"
+            fields = fields_of(agg, rows).map { |name, text| "  #{name}: #{text}," }.join("\n")
+            inputs = agg.attrs.map { |attr| "  #{attr.ts}: #{input(attr, row_for(rows, attr.name), rows)}," }.join("\n")
+            <<~TS.chomp
+              // ---- #{agg.noun} ----
+
+              export const #{var}Fields = {
+              #{fields}
+              } satisfies Record<string, Field>;
+
+              export const #{var}FromDoc = async (req: PayloadRequest, doc: Doc): Promise<#{agg.noun}Input> => ({
+              #{inputs}
+              });
+            TS
+          end
+
+          def row_for(rows, attribute, part = nil)
+            wanted = part ? "#{attribute}.#{part}" : attribute
+            rows.find { |row| row[:attribute] == wanted } || {}
+          end
+
+          def fields_of(agg, rows)
+            agg.attrs.map do |attr|
+              row = row_for(rows, attr.name)
+              [field_name(attr, row), field(agg, attr, row, rows)]
+            end
+          end
+
+          def field_name(attr, row) = row[:field] || attr.ts
+
+          def field(_agg, attr, row, rows)
+            name = field_name(attr, row)
+            return composite(attr, row, name, rows) if attr.shape == :composite
+            return array(attr, row, name) if attr.list
+
+            literal(base(attr, row, name, !attr.optional))
+          end
+
+          def kind_of(attr, row)
+            row[:kind] || (attr.shape == :integer ? "number" : "text")
+          end
+
+          def base(attr, row, name, required)
+            kind = kind_of(attr, row)
+            required = row[:required] if row.key?(:required)
+            pairs = [["name", name.to_json], ["type", KINDS.fetch(kind).to_json]]
+            pairs << ["required", "true"] if required
+            pairs << ["unique", "true"] if attr.name == "slug"
+            pairs << ["defaultValue", row[:default].to_json] if row[:default]
+            pairs.concat(extras(kind, row))
+          end
+
+          def extras(kind, row, describe: true)
+            pairs = []
+            pairs << ["options", options(row[:options])] if kind == "select" && row[:options]
+            pairs << ["relationTo", row[:relation].to_json] if row[:relation]
+            admin = []
+            admin << ["description", row[:description].to_json] if describe && row[:description]
+            if KINDS[kind] == "date"
+              admin << ["date",
+                        "{ pickerAppearance: #{(kind == 'day' ? 'dayOnly' : 'dayAndTime').to_json} }"]
+            end
+            pairs << ["admin", "{ #{admin.map { |key, value| "#{key}: #{value}" }.join(', ')} }"] if admin.any?
+            pairs
+          end
+
+          def options(text)
+            items = text.split(",").map(&:strip).reject(&:empty?).map do |item|
+              value, label = item.split("=", 2)
+              label ? "{ label: #{label.to_json}, value: #{value.to_json} }" : value.to_json
+            end
+            "[#{items.join(', ')}]"
+          end
+
+          def literal(pairs) = "{ #{pairs.map { |key, value| "#{key}: #{value}" }.join(', ')} }"
+
+          def array(_attr, row, name)
+            kind = row[:kind] || "text"
+            element = literal([["name", '"value"'], ["type", KINDS.fetch(kind).to_json], ["required", "true"],
+                               *extras(kind, row, describe: false)])
+            pairs = [["name", name.to_json], ["type", '"array"']]
+            pairs << ["labels", labels(row[:label])] if row[:label]
+            pairs << ["admin", "{ description: #{row[:description].to_json} }"] if row[:description]
+            pairs << ["fields", "[#{element}]"]
+            literal(pairs)
+          end
+
+          def labels(text)
+            singular, plural = text.split("|", 2)
+            "{ singular: #{singular.to_json}, plural: #{(plural || "#{singular}s").to_json} }"
+          end
+
+          def composite(attr, row, name, rows)
+            subs = attr.parts.map do |part|
+              part_row = row_for(rows, attr.name, part.name)
+              literal(base(part, part_row.merge(required: part_row.fetch(:required, true)), part.ts, true))
+            end
+            pairs = [["name", name.to_json], ["type", '"array"']]
+            pairs << ["labels", labels(row[:label])] if row[:label]
+            pairs << ["admin", "{ description: #{row[:description].to_json} }"] if row[:description]
+            pairs << ["fields", "[#{subs.join(', ')}]"]
+            literal(pairs)
+          end
+
+          def input(attr, row, rows)
+            return composite_input(attr, rows) if attr.shape == :composite
+
+            name = row[:field] || attr.ts
+            kind = kind_of(attr, row)
+            return list_input(name, kind) if attr.list
+
+            scalar_input(attr, row, name, kind)
+          end
+
+          def list_input(name, kind) = "valuesOf(doc.#{name}, #{kind == 'date' ? 'isoOrNull' : 'nonBlank'})"
+
+          def scalar_input(attr, row, name, kind)
+            case kind
+            when "upload", "relationship"
+              via = row[:via] || (kind == "upload" ? "url" : "slug")
+              "await related(req, #{row[:relation].to_json}, doc.#{name}, #{via.to_json})"
+            when "date", "day" then date_input(attr, name, kind)
+            when "number" then attr.optional ? "doc.#{name} == null ? null : Number(doc.#{name})" : "Number(doc.#{name})"
+            else attr.optional ? "nonBlank(doc.#{name})" : "String(doc.#{name})"
+            end
+          end
+
+          def date_input(attr, name, kind)
+            return "isoOrNull(doc.#{name})#{' ?? ""' unless attr.optional}" unless attr.shape == :integer || kind == "day"
+
+            stamp = "doc.#{name} ? new Date(doc.#{name} as string).getTime() : Date.now()"
+            "Math.floor((#{stamp}) / 1000)"
+          end
+
+          def composite_input(attr, rows)
+            parts = attr.parts.map { |part| "#{part.ts}: #{part_input(part, row_for(rows, attr.name, part.name))}" }.join(", ")
+            "(Array.isArray(doc.#{attr.ts}) ? doc.#{attr.ts} : []).map((raw) => { const s = raw as Doc; return { #{parts} }; })"
+          end
+
+          def part_input(part, row)
+            return "isoOrNull(s.#{part.ts}) ?? \"\"" if KINDS[row[:kind]] == "date"
+
+            "nonBlank(s.#{part.ts}) ?? \"\""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/payload/lifecycle.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        # The module that turns a spec and a saved document into the commands between the host's
+        # state and
+        # the wanted one. It is the same for every project but for the role its commands declare
+        # and the
+        # path of the module that talks to the host.
+        module Lifecycle
+          BANNER = "// Generated by hecks site site_projection.project_site. Do not edit."
+
+          module_function
+
+          # @param role [String, nil] the role every driven command declares
+          # @param hecks [String] the import path of the module that talks to the host
+          # @return [String] the module
+          def render(role:, hecks:)
+            [BANNER, TEXT.sub("__ROLE__", role.to_json).sub("__HECKS__", hecks.to_json)].join("\n\n")
+          end
+
+          TEXT = <<~TS
+            // Driving one aggregate from a save: what every driven collection shares.
+            //
+            // An editor's save says what the document should look like and where it should
+            // be (live, withdrawn, cancelled). The domain answers with where the aggregate
+            // is now. This works out the commands between the two: create it if the domain
+            // has never seen it, Revise when its facts differ, then walk its lifecycle to
+            // the wanted status along the shortest path the bluebook allows.
+            //
+            // The pure parts (the plan) are separate from `drive`, the one function that
+            // talks to the domain, so the decisions test without a network.
+            import { domain, instancesOf, refusalOf, type Answer } from __HECKS__;
+
+            /** The role every driven command declares; the host compares the role as a plain string. */
+            const ROLE = __ROLE__;
+
+            export type Wire = Record<string, unknown>;
+
+            export interface Command<S> {
+              verb: string;
+              to?: string;
+              with: Wire;
+              /** True when the instances that came back show the command took effect. */
+              confirm: (after: S[]) => boolean;
+            }
+
+            export interface Instance {
+              slug: string;
+              status: string;
+            }
+
+            export interface Spec<S extends Instance, I extends { slug: string }> {
+              /** The aggregate as the host names it, chapter first: "Club::Event". */
+              aggregate: string;
+              /** Its instances in an answer, keyed by slug. */
+              read: (answer: Answer) => S[];
+              /** What the host holds, in the shape a save produces, so the two compare. */
+              toInput: (state: S) => Omit<I, "status">;
+              /** Every attribute but the slug, as `Revise` takes it. */
+              fields: (input: Omit<I, "status">) => Wire;
+              /** The command that creates one (it takes the slug and the fields) and the status it leaves it in. */
+              create: { verb: string; status: string };
+              /** The lifecycle: from a status, the commands that leave it and where they lead. */
+              edges: Record<string, Record<string, string>>;
+            }
+
+            /** A refusal-free plan: nothing is sent for a status the domain cannot reach from where it is. */
+            export class UnreachableStatus extends Error {}
+
+            export const wrapped = (value: string) => ({ value });
+            export const optionalValue = (name: string, value: string | null | undefined) => (value ? { [name]: wrapped(value) } : {});
+
+            /** The text inside a one-attribute value object (`{value}`, `{url}`, `{address}`), or null. */
+            export function unwrap(value: unknown): string | null {
+              if (typeof value === "string") return value || null;
+              if (value && typeof value === "object") {
+                for (const key of ["value", "url", "address"]) {
+                  const inner = (value as Record<string, unknown>)[key];
+                  if (typeof inner === "string" && inner) return inner;
+                }
+              }
+              return null;
+            }
+
+            export const unwrapList = (value: unknown): string[] =>
+              Array.isArray(value) ? value.map(unwrap).filter((item): item is string => !!item) : [];
+
+            export const statusOf = (state: Record<string, unknown>): string => (typeof state.status === "string" ? state.status : "");
+
+            /** The verbs, in order, that take an aggregate from one status to another; null when none does. */
+            export function pathBetween(edges: Record<string, Record<string, string>>, from: string, to: string): string[] | null {
+              if (from === to) return [];
+              const seen = new Set([from]);
+              let frontier: { status: string; verbs: string[] }[] = [{ status: from, verbs: [] }];
+              while (frontier.length) {
+                const next: typeof frontier = [];
+                for (const { status, verbs } of frontier) {
+                  for (const [verb, target] of Object.entries(edges[status] ?? {})) {
+                    if (seen.has(target)) continue;
+                    if (target === to) return [...verbs, verb];
+                    seen.add(target);
+                    next.push({ status: target, verbs: [...verbs, verb] });
+                  }
+                }
+                frontier = next;
+              }
+              return null;
+            }
+
+            const stateOf = <S extends Instance>(after: S[], slug: string) => after.find((s) => s.slug === slug);
+
+            /**
+             * The commands that make the domain's aggregate match `input` and sit in
+             * `desired`. `desired` null means "not on the site": a document the domain has
+             * never seen sends nothing; one it holds is walked to `withdrawn`.
+             */
+            export function planCommands<S extends Instance, I extends { slug: string }>(
+              spec: Spec<S, I>,
+              current: S | undefined,
+              input: Omit<I, "status">,
+              desired: string,
+            ): Command<S>[] {
+              const slug = input.slug;
+              const fields = spec.fields(input);
+              const commands: Command<S>[] = [];
+              let status = current?.status;
+
+              if (!current) {
+                if (spec.create.status !== desired && !pathBetween(spec.edges, spec.create.status, desired)) {
+                  throw new UnreachableStatus(`${spec.aggregate} cannot reach "${desired}" from "${spec.create.status}".`);
+                }
+                commands.push({
+                  verb: spec.create.verb,
+                  with: { slug: wrapped(slug), ...fields },
+                  confirm: (after) => stateOf(after, slug)?.status === spec.create.status,
+                });
+                status = spec.create.status;
+              } else if (JSON.stringify(spec.fields(spec.toInput(current))) !== JSON.stringify(fields)) {
+                commands.push({
+                  verb: "Revise",
+                  to: slug,
+                  with: fields,
+                  confirm: (after) => {
+                    const now = stateOf(after, slug);
+                    return !!now && JSON.stringify(spec.fields(spec.toInput(now))) === JSON.stringify(fields);
+                  },
+                });
+              }
+
+              const path = pathBetween(spec.edges, status ?? "", desired);
+              if (path === null) throw new UnreachableStatus(`${spec.aggregate} "${slug}" cannot go from "${status}" to "${desired}".`);
+              let at = status ?? "";
+              for (const verb of path) {
+                const to = spec.edges[at][verb];
+                commands.push({ verb, to: slug, with: {}, confirm: (after) => stateOf(after, slug)?.status === to });
+                at = to;
+              }
+              return commands;
+            }
+
+            /** Runs the plan against the domain; a command whose result does not show it took effect throws the domain's own words. */
+            export async function drive<S extends Instance, I extends { slug: string }>(
+              spec: Spec<S, I>,
+              input: Omit<I, "status">,
+              desired: string | null,
+              /** The status that means "off the site", used when `desired` is null and the domain holds the aggregate. */
+              offSite: string,
+            ): Promise<void> {
+              const current = spec.read(await domain().read()).find((s) => s.slug === input.slug);
+              // Not on the site and never was (a draft): the domain hears nothing about it.
+              if (desired === null && !current) return;
+              for (const command of planCommands(spec, current, input, desired ?? offSite)) {
+                const verb = `${spec.aggregate.split("::")[1]}.${command.verb}`;
+                const answer = await domain().dispatch(verb, command.with, command.to, ROLE);
+                if (!command.confirm(spec.read(answer))) throw refusalOf(answer, verb);
+              }
+            }
+
+            /** Reads an aggregate's instances, slug first, from an answer. */
+            export const instancesBySlug = (answer: Answer, aggregate: string) => instancesOf(answer, aggregate);
+          TS
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/payload/model.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        # What the generators read from a domain chapter about one aggregate the content system
+        # drives:
+        # its attributes with the shape each takes over the wire, the command that creates it, the
+        # lifecycle edges, and the role its commands declare.
+        #
+        # The model is pure data. It refuses an aggregate it cannot drive, naming why, so a project
+        # learns at generation time rather than from a runtime refusal.
+        class Model
+          # One attribute: `name` is the domain's (snake case), `ts` the camel case the content
+          # system
+          # uses, `shape` one of :value, :url, :address, :integer or :composite, and `parts` the
+          # attributes of a composite value object.
+          Attr = Struct.new(:name, :ts, :shape, :wire_key, :optional, :list, :type, :parts, keyword_init: true)
+
+          # One aggregate: `noun` ("Event"), `fqn` ("Club::Event"), `create` ({verb:, status:}),
+          # `edges` (status => { verb => status }) and `attrs` (the identity first).
+          Aggregate = Struct.new(:noun, :fqn, :create, :edges, :attrs, :identity, :role, keyword_init: true)
+
+          # The single attribute names a one-attribute value object may carry, with the shape each
+          # is.
+          SINGLE = { "value" => :value, "url" => :url, "address" => :address }.freeze
+
+          # @param chapter [Bluebook::Chapter] the domain chapter
+          # @param skip [Array<String>] aggregates to leave out
+          # @return [Array<Aggregate>] each aggregate with a lifecycle and a creating command
+          # @raise [ArgumentError] when such an aggregate cannot be driven
+          def self.read(chapter, skip: [])
+            chapter.aggregates.select { |agg| agg.lifecycle && !skip.include?(agg.hecks_name) }
+                   .map { |agg| new(chapter, agg).aggregate }
+          end
+
+          # @return [Aggregate] the aggregate's model
+          attr_reader :aggregate
+
+          def initialize(chapter, agg)
+            @chapter = chapter
+            @agg = agg
+            @aggregate = Aggregate.new(noun: agg.hecks_name, fqn: "#{chapter.name}::#{agg.hecks_name}", create: create,
+                                       edges: edges, attrs: attrs, identity: agg.identified_by.to_s, role: role)
+          end
+
+          private
+
+          def create
+            command = @agg.commands.find(&:creates?)
+            raise ArgumentError, "#{@agg.hecks_name} has no command that creates it" unless command
+            raise ArgumentError, "#{@agg.hecks_name}'s lifecycle has no default status" unless @agg.lifecycle.default
+
+            { verb: command.hecks_name, status: @agg.lifecycle.default }
+          end
+
+          def edges
+            creating = @agg.commands.select(&:creates?).map(&:hecks_name)
+            map = Hash.new { |hash, key| hash[key] = {} }
+            @agg.lifecycle.transitions.each do |verb, move|
+              next if creating.include?(verb)
+
+              Array(move.from).each { |from| map[from][verb] = move.target }
+              map[move.target]
+            end
+            map.transform_values(&:dup)
+          end
+
+          def role
+            roles = @agg.commands.filter_map { |command| command.role if command.respond_to?(:role) }.uniq
+            if roles.size > 1
+              raise ArgumentError,
+                    "#{@agg.hecks_name}'s commands declare #{roles.size} roles; the driver acts as one"
+            end
+
+            roles.first
+          end
+
+          def attrs
+            @agg.attributes.reject { |attribute| attribute.name == @agg.lifecycle.field }.map { |attribute| attr(attribute) }
+          end
+
+          def attr(attribute)
+            object = value_object(attribute.type)
+            unless object
+              raise ArgumentError,
+                    "#{@agg.hecks_name}.#{attribute.name} is a #{attribute.type}; the driver needs a value object"
+            end
+
+            members = object.attributes
+            shape, key, parts = shape_of(attribute, members)
+            Attr.new(name: attribute.name.to_s, ts: camel(attribute.name), shape: shape, wire_key: key,
+                     optional: attribute.optional?, list: attribute.list?, type: attribute.type, parts: parts)
+          end
+
+          def shape_of(attribute, members)
+            if members.size == 1 && SINGLE.key?(members.first.name.to_s)
+              key = members.first.name.to_s
+              [members.first.type.to_s == "Integer" ? :integer : SINGLE.fetch(key), key, nil]
+            elsif attribute.list? && members.size > 1
+              [:composite, nil, members.map { |member| part(member) }]
+            else
+              raise ArgumentError, "#{@agg.hecks_name}.#{attribute.name} is #{attribute.type}, which the driver cannot carry"
+            end
+          end
+
+          def part(member)
+            unless member.type.to_s == "String"
+              raise ArgumentError, "#{@agg.hecks_name}'s #{member.name} is a #{member.type}; a composite carries text only"
+            end
+
+            Attr.new(name: member.name.to_s, ts: camel(member.name), shape: :value, type: member.type.to_s, optional: false)
+          end
+
+          def value_object(type)
+            @agg.value_objects.find { |object| object.hecks_name == type.to_s }
+          end
+
+          def camel(name)
+            first, *rest = name.to_s.split("_")
+            first + rest.map(&:capitalize).join
+          end
+        end
+      end
+    end
+  end
+end