hecks 0.2.0 → 0.3.0

data/lib/hecks/language/bluebook/query.bluebook

@@ -0,0 +1,245 @@
+Hecks.bluebook "Bluebook" do
+  aggregate "Query" do
+    description "One query declared on an aggregate — what it filters on, how it orders, and how many it returns."
+
+    reference_to Aggregate
+
+    # Which piece declared it — see Command's entity_id.
+    reference_to Entity, as: :entity_id, optional: true
+
+    # THE IMMEDIATE OWNER, AND ITS NAME — the same derivation Command takes
+    # (see the note there), because an ask sits exactly where a verb does and
+    # an entity's asks are its own the same way its verbs are.
+    identified_by :owner_id, :name
+
+    attribute :name,        QueryName
+    attribute :description, QueryText
+    attribute :order_field, QueryText
+    attribute :order_way,   QueryText
+    attribute :limit,       QueryText
+    attribute :wheres,      list_of(Filter)
+    attribute :attributes,  list_of(AskArgument)
+    # EVERY OTHER OPTION A QUERY CAN CARRY, as an open map rather than a field
+    # each. `offset`, `cursor`, `nulls`, `authorize`, `consistency`, `freshness`,
+    # `inspect_query` and `use_index` are eight more specifications, several of them
+    # compound — authorize names a policy AND a tenant, freshness a mode AND a max
+    # age. Eleven more fields would have to be added here one at a time, and the
+    # ninth option would need a twelfth.
+    #
+    # So they ride as rows: the option's NAME, the KEY within it, and the value. The
+    # language already models an open map exactly this way twice — a member's pairs
+    # and a world's settings — and both are their own root for the same reason, that
+    # no value object can hold a map. Held here as a list because an option belongs
+    # to the ask rather than standing alone.
+    attribute :options,     list_of(AskOption)
+
+    value_object "QueryName" do
+      attribute :value, String
+      invariant("a query is named") { !value.to_s.empty? }
+    end
+
+    value_object "QueryText" do
+      attribute :value, String
+    end
+
+    value_object "Filter" do
+      attribute :field, String
+      # THE FIRST USE OF THE WORD. The runtime maps these eight strings
+      # through a hand-typed comparator table ; the set it is mapping to is
+      # one the language DECLARES, and until the link between them was
+      # declared, typing it downstream
+      # would have been a guess. This declares it.
+      attribute :op,    String, admits: "Vocabulary::QueryComparator"
+      attribute :value, String
+    end
+
+    value_object "AskArgument" do
+      attribute :name,    String
+      attribute :type,    String
+      attribute :list,    String
+      attribute :optional, String, optional: true
+      attribute :pattern,  String, optional: true
+      attribute :default, String
+      # The closed set this value must belong to — see Aggregate::Field.
+      attribute :admits, String, optional: true
+      attribute :relationship, String, optional: true
+    end
+
+    # One entry of one option. `option` names which specification it belongs to
+    # (offset, freshness, authorization), `key` the part within it (value, mode,
+    # max_age, policy, tenant), and `value` what was declared. A single-valued
+    # option is one row ; a compound is one row per part ; a repeated one — an index
+    # hint — is one row per occurrence, told apart by `at`.
+    value_object "AskOption" do
+      attribute :option, String
+      attribute :key,    String
+      attribute :value,  String
+      attribute :at,     String
+    end
+
+    # The way back: everything DECLARED IN the aggregate above. The parent
+    # reference IS the query.
+    # WHERE IT SITS AMONG ITS SIBLINGS. Declaration order is a FACT ABOUT THE
+    # SOURCE — the IR is a contract read straight from this file,
+    # field for field AND INDEX FOR INDEX. So the language HOLDS it, instead of
+    # inheriting it from whatever order a store happens to iterate: an ask that
+    # does not say how it is ordered is answered in identity order, which is
+    # right for every other ask and fatal for the one that is the SOURCE.
+    value_object "Position" do
+      attribute :value, Integer
+    end
+
+    attribute :position, Position
+
+    query "DeclaredIn" do
+      attribute :aggregate, QueryText
+      where(aggregate: :aggregate)
+      order_by :position
+    end
+    command "Declare" do
+      role "Language"
+      goal "Open a query on an aggregate"
+
+      reference_to Aggregate
+      # Declared on an aggregate or on one of its entities — see Command.Declare.
+      reference_to Entity, as: :entity_id, optional: true
+      attribute :name,        QueryName
+      attribute :description, QueryText, optional: true
+      attribute :order_field, QueryText, optional: true
+      attribute :order_way,   QueryText, optional: true
+      attribute :limit,       QueryText, optional: true
+
+      attribute :position, Position, optional: true
+      sets :aggregate
+      sets :entity_id
+      sets :name
+      sets :description
+      sets :order_field
+      sets :order_way
+      sets :limit
+      sets :position
+      emits "AskDeclared"
+    end
+
+    command "Filter" do
+      role "Language"
+      goal "Attach one where-clause to the query"
+
+      attribute :field, QueryText
+      # The same word at the same door — see Command.Change.op.
+      attribute :op,    QueryText, admits: "Vocabulary::QueryComparator"
+      attribute :value, QueryText
+
+      sets :wheres, append: { field: :field, op: :op, value: :value }
+
+      emits "FilterAttached"
+    end
+
+    command "Option" do
+      role "Language"
+      goal "Attach one part of one specification option to the query"
+
+      attribute :option, QueryText
+      attribute :key,    QueryText
+      # AN OPTION MAY HAVE NO VALUE. `consistency :snapshot` with no timeout is a
+      # complete declaration, and an option is judged one key at a time — so the
+      # `timeout` row arrives carrying nothing. Requiring a value here made every
+      # such declaration unbuildable, which is a rule about the LANGUAGE, not
+      # about the one spec that noticed.
+      attribute :value,  QueryText, optional: true
+      attribute :at,     QueryText, optional: true
+
+      given("an option is named") { !option.value.to_s.empty? }
+
+      sets :options, append: { option: :option, key: :key, value: :value, at: :at }
+
+      emits "OptionAttached"
+    end
+
+    command "Argument" do
+      role "Language"
+      goal "Attach one parameter to the query"
+
+      attribute :name,    QueryText
+      attribute :type,    QueryText
+      attribute :list,    QueryText
+      attribute :optional, QueryText, optional: true
+      attribute :pattern,  QueryText, optional: true
+      attribute :default, QueryText, optional: true
+      attribute :admits,  QueryText, optional: true
+      # See Command.Argument's own :relationship (command.bluebook) — the
+      # same field, the same reason: an argument minted verbatim from the
+      # owner's own reference-typed attribute must carry that fact through
+      # the self-hosted round trip too, or the language cannot say it about
+      # itself.
+      attribute :relationship, QueryText, optional: true
+
+      sets :attributes, append: { name: :name, type: :type, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits "AskArgumentAttached"
+    end
+
+
+    # HOW QUERY IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: Query.
+    value_object "KeywordSeed" do
+      attribute :word,          String
+      attribute :context,       String, admits: "Syntax::Context"
+      attribute :body,          String, admits: "Syntax::Body"
+      attribute :inner,         String
+      attribute :opens,         String
+      attribute :fills,         String
+      attribute :status,        String, default: "admitted", admits: "Syntax::Status"
+      attribute :was,           String
+      attribute :resolves_via,  String, default: "", admits: "Syntax::ResolutionScope"
+      attribute :disambiguator, String, default: "", admits: "Syntax::Disambiguator"
+
+      member word: "description",     context: "Query", body: "none", inner: "", opens: "", fills: "description"
+      member word: "attribute",       context: "Query", body: "none", inner: "", opens: "", fills: "attributes", calls: "attribute_impl"
+      member word: "reference_to",    context: "Query", body: "none", inner: "", opens: "", fills: "attributes", calls: "reference_to_impl"
+      member word: "where",           context: "Query", body: "none", inner: "", opens: "", fills: "wheres", calls: "where_impl"
+      member word: "order_by",        context: "Query", body: "none", inner: "", opens: "", fills: "order_field", calls: "order_by_impl"
+      member word: "authorize",       context: "Query", body: "none", inner: "", opens: "", fills: "options", calls: "authorize_impl"
+      member word: "inspect_query",   context: "Query", body: "none", inner: "", opens: "", fills: "options"
+
+    end
+
+    value_object "ArgumentSeed" do
+      attribute :keyword,          String
+      attribute :context,          String, admits: "Syntax::Context"
+      attribute :at,               String
+      attribute :named,            String
+      attribute :kind,             String, admits: "Syntax::ArgumentKind"
+      attribute :required,         String
+      attribute :fills,            String
+      attribute :selects,          String
+      attribute :pair_key_fills,   String
+      attribute :pair_value_fills, String
+      attribute :pairs_shape,      String, admits: "Syntax::PairsShape"
+      attribute :status,           String, default: "admitted", admits: "Syntax::Status"
+      attribute :variadic,         String
+      attribute :coerce,           String
+      attribute :blank_message,    String
+
+      member keyword: "description",     context: "Query", at: "1", named: "",         kind: "text",     required: "true",  fills: "description", coerce: "false"
+      member keyword: "attribute",       context: "Query", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "name"
+      member keyword: "attribute",       context: "Query", at: "2", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "attribute",       context: "Query", at: "",  named: "default",  kind: "literal",  required: "false", fills: "default"
+      member keyword: "attribute",       context: "Query", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "attribute",       context: "Query", at: "",  named: "pattern",  kind: "text",     required: "false", fills: "pattern"
+      member keyword: "attribute",       context: "Query", at: "",  named: "admits",   kind: "text",     required: "false", fills: "admits"
+      member keyword: "attribute",       context: "Query", at: "",  named: "one_of",   kind: "list",     required: "false", fills: "one_of"
+      member keyword: "reference_to",    context: "Query", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "reference_to",    context: "Query", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "reference_to",    context: "Query", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "where",           context: "Query", at: "1", named: "",         kind: "pairs",    required: "true",  fills: "wheres", pair_key_fills: "field", pair_value_fills: "value", pairs_shape: "elements"
+      member keyword: "order_by",        context: "Query", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "order_field"
+      member keyword: "order_by",        context: "Query", at: "2", named: "",         kind: "symbol",   required: "false", fills: "order_way"
+      member keyword: "authorize",       context: "Query", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "policy"
+      member keyword: "authorize",       context: "Query", at: "",  named: "tenant",   kind: "symbol",   required: "false", fills: "tenant"
+      member keyword: "inspect_query",   context: "Query", at: "1", named: "",         kind: "symbol",   required: "false", fills: "mode"
+
+    end
+  end
+end

data/lib/hecks/language/bluebook/shape.bluebook

@@ -0,0 +1,292 @@
+Hecks.bluebook "Bluebook" do
+  aggregate "ValueObject" do
+    description "One value object declared on an aggregate — its fields and the rules they must satisfy. Its own root because a value object holds nested lists, which no list element can."
+
+    reference_to Aggregate
+
+    # THE AGGREGATE IT BELONGS TO, AND ITS NAME. A value object belongs to one
+    # aggregate by rule, and `Name` or `Amount` is spelled in half the chapters
+    # there are.
+    identified_by :aggregate, :name
+
+    attribute :name,       ValueObjectName
+    attribute :attributes, list_of(ShapeField)
+    attribute :invariants, list_of(Assertion)
+    attribute :rows,       RowCount, optional: true
+    # S17, ADR 0026 — Member NESTED here, an entity rather than its own
+    # root aggregate (see `entity "Member"`, below). `list_of(Member)`
+    # forward-references it the same way banking's own `attribute :ledger,
+    # list_of(LedgerEntry)` names LedgerEntry before it is declared.
+    attribute :members,    list_of(Member)
+
+    value_object "RowCount" do
+      attribute :value, Integer
+    end
+
+    value_object "ValueObjectName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+      invariant("a value object is named") { !value.to_s.empty? }
+    end
+
+    value_object "ShapeField" do
+      attribute :name,    String, pattern: '[^ \t\n\r]'
+      attribute :type,    String, pattern: '[^ \t\n\r]'
+      attribute :list,    String, pattern: '[^ \t\n\r]'
+      attribute :optional, String, optional: true
+      attribute :pattern,  String, optional: true
+      attribute :default, String
+      # The closed set this value must belong to — see Aggregate::Field.
+      attribute :admits, String, optional: true
+      attribute :relationship, String, optional: true
+      invariant("a field is named") { !name.to_s.empty? }
+      invariant("a field has a type") { !type.to_s.empty? }
+      invariant("a field's list mode is specified") { !list.to_s.empty? }
+    end
+
+    value_object "Assertion" do
+      attribute :description, String, pattern: '[^ \t\n\r]'
+      attribute :canonical,   String, pattern: '[^ \t\n\r]'
+      invariant("an assertion description is present") { !description.to_s.empty? }
+      invariant("an assertion canonical form is present") { !canonical.to_s.empty? }
+    end
+
+    # S17, ADR 0026 — MemberPosition/MemberText/Pair, hoisted up from the
+    # old standalone `aggregate "Member"`. An entity cannot declare its own
+    # `value_object` (EntityBuilder has no such method — a piece borrows its
+    # owning aggregate's, the same way LedgerEntry borrows Account's Money),
+    # so these live here now, one level up, where `entity "Member"` below
+    # can still reach them.
+    #
+    # Named MemberPosition rather than reusing ValueObject's own `Position`
+    # two lines above — that one orders value objects among an AGGREGATE's
+    # siblings ; this one orders admitted rows within ONE value object. Same
+    # shape, different fact, so a shared name would have let one silently
+    # answer for the other.
+    value_object "MemberPosition" do
+      attribute :value, Integer
+    end
+
+    value_object "MemberText" do
+      attribute :value, String
+      # MemberText is free-form serialized text from member definitions,
+      # which can include empty strings and numeric literals — not restricted
+    end
+
+    value_object "Pair" do
+      attribute :key,   String, pattern: '[^ \t\n\r]'
+      attribute :value, String
+      # Pair keys must be named, but values can be empty strings or numeric literals
+      invariant("a pair key is present") { !key.to_s.empty? }
+    end
+
+    # The way back: everything DECLARED IN the aggregate above. The parent
+    # reference IS the query.
+    # WHERE IT SITS AMONG ITS SIBLINGS. Declaration order is a FACT ABOUT THE
+    # SOURCE — the IR is a contract read straight from this file,
+    # field for field AND INDEX FOR INDEX. So the language HOLDS it, instead of
+    # inheriting it from whatever order a store happens to iterate: an ask that
+    # does not say how it is ordered is answered in identity order, which is
+    # right for every other ask and fatal for the one that is the SOURCE.
+    value_object "Position" do
+      attribute :value, Integer
+    end
+
+    attribute :position, Position
+
+    query "DeclaredIn" do
+      attribute :aggregate, ValueObjectText
+      where(aggregate: :aggregate)
+      order_by :position
+    end
+    command "Declare" do
+      role "Language"
+      goal "Open a value object on an aggregate"
+
+      reference_to Aggregate
+      attribute :name, ValueObjectName
+
+      attribute :position, Position, optional: true
+      sets :aggregate
+      sets :name
+      sets :position
+      emits "ShapeDeclared"
+    end
+
+    command "Field" do
+      role "Language"
+      goal "Attach one field to the value object"
+
+      attribute :name,    ValueObjectName
+      attribute :type,    ValueObjectName
+      attribute :list,    ValueObjectName
+      attribute :optional, ValueObjectName, optional: true
+      # FREE TEXT, like `default` beside it and like the pattern every other
+      # element builder takes. `ValueObjectName` carries the invariant "a value
+      # object is named", which is not a thing a regex has to be — it happened to
+      # admit banking's one pattern because that pattern is not empty, and it
+      # said the wrong thing about why.
+      attribute :pattern,  ValueObjectText, optional: true
+      attribute :default, ValueObjectText, optional: true
+      attribute :admits,  ValueObjectText, optional: true
+      # See Command.Argument's own :relationship (command.bluebook) — the
+      # same field, the same reason.
+      attribute :relationship, ValueObjectText, optional: true
+
+      sets :attributes, append: { name: :name, type: :type, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits "ShapeFieldAttached"
+    end
+
+    command "Close" do
+      role "Language"
+      goal "Declare that this value object admits a closed set of rows"
+
+      # Dispatched only when the bluebook declared a one_of — so an EMPTY closed
+      # set is visible where it used to be invisible : a shape that is closed
+      # and admits nothing. Members live in their own root (a row is a list of
+      # pairs inside a list of rows), so the count is offered rather than read.
+
+      given("a closed set admits a member") { rows.value > 0 }
+
+      sets :rows
+
+      emits "ShapeClosed"
+    end
+
+    command "Assert" do
+      role "Language"
+      goal "Attach one invariant to the value object"
+
+      attribute :description, ValueObjectText, optional: true
+      attribute :canonical,   ValueObjectText
+
+      given("a rule says what it means")  { !description.value.to_s.empty? }
+      given("a rule survives extraction") { !canonical.value.to_s.empty? }
+
+      sets :invariants, append: { description: :description, canonical: :canonical }
+
+      emits "AssertionAttached"
+    end
+
+    value_object "ValueObjectText" do
+      attribute :value, String
+      # ValueObjectText is free-form serialized text from member definitions,
+      # which can include empty strings and numeric literals — not restricted
+    end
+
+    # THE MEMBER'S OWN CREATION. S17, ADR 0026 — Member is a genuine ENTITY
+    # now (`entity "Member"`, below), and an entity is never created through
+    # its own dotted verb — banking's own LedgerEntry is created by
+    # `Account.LogEntry`, an ordinary append on the OWNER, never by a
+    # `LedgerEntry.Declare` of its own (EntityInterpreter#element_of only
+    # LOCATES an element already on the list — see entity_interpreter.rb —
+    # it has no path that creates one). So Member's creation moved here,
+    # onto ValueObject, mirroring `Field`/`Close`/`Assert` beside it :
+    # a bare, aggregate-level append. What it creates is empty — pairs fill
+    # in afterward, one at a time, through the entity's own `Pair`.
+    command "Member" do
+      role "Language"
+      goal "Open one admitted row on a value object"
+
+      attribute :position, MemberPosition
+
+      sets :members, append: { position: :position }
+
+      emits "MemberDeclared"
+    end
+
+    # S17, ADR 0026 — ONE ADMITTED ROW, nested rather than its own root
+    # aggregate. A member has no other distinguishing fact : its pairs are
+    # an OPEN MAP, which is the whole reason it used to need a root of its
+    # own, and a map cannot be a path — but that was always a reason it
+    # could not be a VALUE OBJECT, never a reason it could not be an
+    # ENTITY, which is what it structurally always was: a nested, ordered,
+    # separately-mutated element of ValueObject's own list. `ValueObject.
+    # Member` (above) creates it ; `Pair` (below) fills it in, one field
+    # at a time, exactly the way `Command.Rule` fills in a precondition.
+    entity "Member" do
+      description "One admitted row of a value object's one_of — a whole combination of field values, not a per-field choice. Nested under the value object because a row is a list of pairs inside a list of rows."
+
+      # Position is not a mint — it is read straight out of the source
+      # file, the same fact the language already holds deliberately so
+      # that an ask ordered any other way cannot take declaration order
+      # away. `ValueObject.Member` mints it as the walk index at creation
+      # (the same way `declare`'s own `position` field always has), and
+      # every later `Pair` locates the element by it.
+      identified_by MemberPosition, as: :position
+
+      attribute :pairs, list_of(Pair)
+
+      command "Pair" do
+        role "Language"
+        goal "Bind one field of the admitted row"
+
+        attribute :key,   MemberText
+        attribute :value, MemberText
+
+        given("an admitted row binds a named field") { !key.value.to_s.empty? }
+
+        sets :pairs, append: { key: :key, value: :value }
+
+        emits "PairBound"
+      end
+    end
+
+    # HOW VALUEOBJECT IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: ValueObject, OneOf, Type.
+    value_object "KeywordSeed" do
+      attribute :word,          String
+      attribute :context,       String, admits: "Syntax::Context"
+      attribute :body,          String, admits: "Syntax::Body"
+      attribute :inner,         String
+      attribute :opens,         String
+      attribute :fills,         String
+      attribute :status,        String, default: "admitted", admits: "Syntax::Status"
+      attribute :was,           String
+      attribute :resolves_via,  String, default: "", admits: "Syntax::ResolutionScope"
+      attribute :disambiguator, String, default: "", admits: "Syntax::Disambiguator"
+
+      member word: "attribute",       context: "ValueObject", body: "none",   inner: "",      opens: "", fills: "attributes", calls: "attribute_impl"
+      member word: "one_of",          context: "ValueObject", body: "rows",   inner: "OneOf", opens: "", fills: "rows", calls: "one_of_impl"
+      member word: "invariant",       context: "ValueObject", body: "source", inner: "",      opens: "", fills: "invariants", resolves_via: "sibling_scan", calls: "invariant_impl"
+      member word: "member",          context: "ValueObject", body: "none", inner: "", opens: "Member", fills: "", calls: "member_impl"
+      member word: "member",          context: "OneOf",     body: "none", inner: "", opens: "Member", fills: "", calls: "member_impl"
+      member word: "list_of",         context: "Type", body: "none", inner: "", opens: "", fills: "", calls: "list_of_impl"
+      member word: "one_of",          context: "Type", body: "none", inner: "", opens: "", fills: "", calls: "one_of_impl"
+
+    end
+
+    value_object "ArgumentSeed" do
+      attribute :keyword,          String
+      attribute :context,          String, admits: "Syntax::Context"
+      attribute :at,               String
+      attribute :named,            String
+      attribute :kind,             String, admits: "Syntax::ArgumentKind"
+      attribute :required,         String
+      attribute :fills,            String
+      attribute :selects,          String
+      attribute :pair_key_fills,   String
+      attribute :pair_value_fills, String
+      attribute :pairs_shape,      String, admits: "Syntax::PairsShape"
+      attribute :status,           String, default: "admitted", admits: "Syntax::Status"
+      attribute :variadic,         String
+      attribute :coerce,           String
+      attribute :blank_message,    String
+
+      member keyword: "attribute",       context: "ValueObject", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "name"
+      member keyword: "attribute",       context: "ValueObject", at: "2", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "attribute",       context: "ValueObject", at: "",  named: "default",  kind: "literal",  required: "false", fills: "default"
+      member keyword: "attribute",       context: "ValueObject", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "attribute",       context: "ValueObject", at: "",  named: "pattern",  kind: "text",     required: "false", fills: "pattern"
+      member keyword: "attribute",       context: "ValueObject", at: "",  named: "admits",   kind: "text",     required: "false", fills: "admits"
+      member keyword: "attribute",       context: "ValueObject", at: "",  named: "one_of",   kind: "list",     required: "false", fills: "one_of"
+      member keyword: "invariant",       context: "ValueObject", at: "1", named: "",         kind: "text",     required: "true",  fills: "description"
+      member keyword: "member",          context: "ValueObject", at: "1", named: "", kind: "pairs", required: "true", fills: "members", pairs_shape: "verbatim"
+      member keyword: "member",          context: "OneOf",     at: "1", named: "",     kind: "pairs", required: "true",  fills: "members", pairs_shape: "verbatim"
+      member keyword: "list_of",         context: "Type", at: "1", named: "", kind: "constant", required: "true", fills: ""
+      member keyword: "one_of",          context: "Type", at: "1", named: "", kind: "literal",  required: "true", fills: ""
+
+    end
+  end
+end