hecks 4.0.0 → 6.0.0

data/rust/parser/src/emit.rs

@@ -18,7 +18,8 @@ pub enum JsonValue {
 }
 
 impl JsonValue {
-    fn str(s: impl Into<String>) -> Self {
+    /// A JSON string.
+    pub fn str(s: impl Into<String>) -> Self {
         Self::String(s.into())
     }
 
@@ -191,6 +192,15 @@ fn aggregate_json(a: &ir::Aggregate) -> JsonValue {
                 .as_ref()
                 .map_or(JsonValue::Null, ruby_value_json),
         ),
+        (
+            "acknowledgements".to_string(),
+            JsonValue::Array(
+                a.acknowledgements
+                    .iter()
+                    .map(acknowledgement_json)
+                    .collect(),
+            ),
+        ),
     ])
 }
 
@@ -270,6 +280,15 @@ fn given_json(g: &ir::Given) -> JsonValue {
     ])
 }
 
+/// `IR::Aggregate#to_h`'s `acknowledgements:` entry: `{finding:, subject:, reason:}`.
+fn acknowledgement_json(a: &ir::Acknowledgement) -> JsonValue {
+    JsonValue::Object(vec![
+        ("finding".to_string(), JsonValue::str(a.finding.clone())),
+        ("subject".to_string(), JsonValue::str(a.subject.clone())),
+        ("reason".to_string(), JsonValue::str(a.reason.clone())),
+    ])
+}
+
 /// `IR::Aggregate#to_h`'s `projected_fields:` entry: `{name:, reference:, remote_field:}`.
 fn projected_field_json(f: &ir::ProjectedField) -> JsonValue {
     JsonValue::Object(vec![
@@ -284,9 +303,21 @@ fn projected_field_json(f: &ir::ProjectedField) -> JsonValue {
 
 /// `IR::Command#to_h` (lib/hecks/bluebook/ir/command.rb).
 fn command_json(c: &ir::Command) -> JsonValue {
-    JsonValue::Object(vec![
+    let mut fields = vec![
         ("name".to_string(), JsonValue::str(c.name.clone())),
         ("role".to_string(), JsonValue::opt_str(c.role.as_ref())),
+    ];
+    // Only a command run by several roles says so, so every other command emits as it always did.
+    if c.roles.len() > 1 {
+        fields.push(("roles".to_string(), JsonValue::strings(&c.roles)));
+    }
+    fields.extend(command_json_rest(c));
+    JsonValue::Object(fields)
+}
+
+/// The fields of `IR::Command#to_h` after `role` and `roles`.
+fn command_json_rest(c: &ir::Command) -> Vec<(String, JsonValue)> {
+    vec![
         ("goal".to_string(), JsonValue::opt_str(c.goal.as_ref())),
         (
             "references".to_string(),
@@ -327,7 +358,8 @@ fn command_json(c: &ir::Command) -> JsonValue {
                 .as_ref()
                 .map_or(JsonValue::Null, ruby_value_json),
         ),
-    ])
+        ("idempotent".to_string(), JsonValue::Bool(c.idempotent)),
+    ]
 }
 
 /// `ir::CommandFrom`: a bare JSON string for one state, an array for several, `null` for none.
@@ -899,6 +931,15 @@ fn port_operation_json(op: &ir::PortOperation) -> JsonValue {
         ),
         ("emits".to_string(), JsonValue::strings(&op.emits)),
     ];
+    // An `asks` names its direction and both endings, as `PortOperation#to_h` merges them.
+    if op.outbound {
+        fields.push((
+            "direction".to_string(),
+            JsonValue::str("outbound".to_string()),
+        ));
+        fields.push(("answers".to_string(), optional_str(op.answers.as_ref())));
+        fields.push(("refuses".to_string(), optional_str(op.refuses.as_ref())));
+    }
     // Merged in only when present, so domains that never declared one keep byte-identical IR.
     if let Some(to) = &op.to {
         fields.push(("to".to_string(), JsonValue::str(to.clone())));
@@ -906,6 +947,11 @@ fn port_operation_json(op: &ir::PortOperation) -> JsonValue {
     JsonValue::Object(fields)
 }
 
+/// A string, or `null` when absent.
+fn optional_str(value: Option<&String>) -> JsonValue {
+    value.map_or(JsonValue::Null, |text| JsonValue::String(text.clone()))
+}
+
 /// `JSON.generate`'s native encoding of a captured Ruby value, never `Literal.render`ed;
 /// a bare Symbol serializes as its name.
 fn ruby_value_json(value: &ruby_value::Value) -> JsonValue {
@@ -931,8 +977,26 @@ fn ruby_value_json(value: &ruby_value::Value) -> JsonValue {
     }
 }
 
-/// One declared adapter, keys in the order the Ruby side prints them.
+/// One declared adapter, keys in the order the Ruby side prints them; an adapter that provides
+/// capabilities adds `provides`, and a plugin adds `answers` and `runs` after them.
 pub fn adapter_json(adapter: &ir::Adapter) -> JsonValue {
+    let JsonValue::Object(mut keys) = declared_adapter_json(adapter) else {
+        unreachable!("an adapter is a JSON object")
+    };
+    if !adapter.provides.is_empty() {
+        keys.push((
+            "provides".to_string(),
+            JsonValue::strings(&adapter.provides),
+        ));
+    }
+    if let Some(runs) = &adapter.runs {
+        keys.push(("answers".to_string(), JsonValue::strings(&adapter.answers)));
+        keys.push(("runs".to_string(), JsonValue::str(runs.clone())));
+    }
+    JsonValue::Object(keys)
+}
+
+fn declared_adapter_json(adapter: &ir::Adapter) -> JsonValue {
     JsonValue::Object(vec![
         ("name".to_string(), JsonValue::str(adapter.name.clone())),
         (

data/rust/parser/src/expr/ast_json.rs

@@ -223,6 +223,16 @@ pub fn emit_resolver(node: &Resolver) -> JsonValue {
                 JsonValue::Array(path.iter().map(|s| JsonValue::String(s.clone())).collect()),
             ),
         ]),
+        Resolver::Sum {
+            receiver,
+            param,
+            predicate,
+        } => obj(vec![
+            op_tag("sum"),
+            ("receiver", emit_resolver(receiver)),
+            ("param", JsonValue::String(param.clone())),
+            ("predicate", emit_bool(predicate)),
+        ]),
         // The haystack case is intercepted in `emit_include`.
         Resolver::ArrayLiteral(elements) => obj(vec![
             op_tag("array"),

data/rust/parser/src/expr/resolver.rs

@@ -103,6 +103,12 @@ pub enum Resolver {
         predicate: Box<Evaluator>,
         path: Vec<String>,
     },
+    /// `receiver.sum { |param| expression }`: the total of a number worked out for each element.
+    Sum {
+        receiver: Box<Self>,
+        param: String,
+        predicate: Box<Evaluator>,
+    },
 }
 
 const SIGN_TESTS: [(&str, &str); 3] = [("positive?", ">"), ("negative?", "<"), ("zero?", "==")];
@@ -267,19 +273,31 @@ pub fn parse(expr: &str) -> Resolver {
     Resolver::Lookup(expr.to_string())
 }
 
+/// What a block-opening suffix builds.
+#[derive(Clone, Copy)]
+enum Opener {
+    /// `all?`, `any?` or `none?`: a test aggregated over the elements.
+    Block(BlockMode),
+    /// `find`: the first element a test accepts, which may trail a dotted path.
+    Find,
+    /// `sum`: the total of a number worked out for every element.
+    Sum,
+}
+
 /// Block-opener suffixes, in the order Ruby's pattern alternates them.
-const BLOCK_OPENERS: [(&str, Option<BlockMode>); 4] = [
-    ("all?", Some(BlockMode::All)),
-    ("any?", Some(BlockMode::Any)),
-    ("none?", Some(BlockMode::None)),
-    ("find", None),
+const BLOCK_OPENERS: [(&str, Opener); 5] = [
+    ("all?", Opener::Block(BlockMode::All)),
+    ("any?", Opener::Block(BlockMode::Any)),
+    ("none?", Opener::Block(BlockMode::None)),
+    ("find", Opener::Find),
+    ("sum", Opener::Sum),
 ];
 
-/// Hand-matched `/\A(.+?)\.(all?|any?|none?|find)\s*\{\s*\|(\w+)\|\s*/m`: the earliest
+/// Hand-matched `/\A(.+?)\.(all?|any?|none?|find|sum)\s*\{\s*\|(\w+)\|\s*/m`: the earliest
 /// `.suffix { |param|`, then a brace-balanced body. Only `find` may trail a dotted path.
 fn parse_block_opener(expr: &str) -> Option<Resolver> {
     let bytes = expr.as_bytes();
-    let mut best: Option<(usize, Option<BlockMode>, usize, String)> = None;
+    let mut best: Option<(usize, Opener, usize, String)> = None;
 
     for (suffix, mode) in BLOCK_OPENERS {
         let marker = format!(".{suffix}");
@@ -330,7 +348,17 @@ fn parse_block_opener(expr: &str) -> Option<Resolver> {
     let trailing = expr[body_end + 1..].trim();
 
     match mode {
-        None => {
+        Opener::Sum => {
+            if !trailing.is_empty() {
+                return None;
+            }
+            Some(Resolver::Sum {
+                receiver,
+                param,
+                predicate,
+            })
+        }
+        Opener::Find => {
             if !(trailing.is_empty() || trailing.starts_with('.')) {
                 return None;
             }
@@ -346,7 +374,7 @@ fn parse_block_opener(expr: &str) -> Option<Resolver> {
                 path,
             })
         }
-        Some(mode) => {
+        Opener::Block(mode) => {
             if !trailing.is_empty() {
                 return None;
             }
@@ -677,6 +705,18 @@ mod tests {
         }
     }
 
+    #[test]
+    fn parses_a_sum_over_a_list_and_refuses_a_trailing_path() {
+        assert!(matches!(
+            parse("items.sum { |i| i.quantity * i.price }"),
+            Resolver::Sum { ref param, .. } if param == "i"
+        ));
+        assert!(matches!(
+            parse("items.sum { |i| i.price }.total"),
+            Resolver::Lookup(_)
+        ));
+    }
+
     #[test]
     fn parses_match_with_its_pattern_kept_verbatim() {
         let text = r"value.to_s.match?(/\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*\z/)";

data/rust/parser/src/ir.rs

@@ -44,6 +44,15 @@ pub struct ProjectedField {
     pub remote_field: String,
 }
 
+// `acknowledges :finding, "reason", of: :subject`: a finding model_check would report, allowed
+// with its reason; `of:` names the attribute or referenced aggregate it is for.
+#[derive(Debug, Clone, Default)]
+pub struct Acknowledgement {
+    pub finding: String,
+    pub subject: String,
+    pub reason: String,
+}
+
 // One state or several, stored as the plain captured value rather than a `Given`-shaped rule.
 // `None` when the command has no `from:` guard.
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -95,6 +104,9 @@ pub enum Mutation {
 pub struct Command {
     pub name: String,
     pub role: Option<String>,
+    /// Every role that may run the command, when more than one may; `role` is then the first.
+    /// Empty otherwise, and then absent from the IR.
+    pub roles: Vec<String>,
     pub goal: Option<String>,
     pub references: Option<String>,
     pub attributes: Vec<Attribute>,
@@ -108,6 +120,9 @@ pub struct Command {
     pub from: Option<CommandFrom>,
     // The raw captured `provenance from: { ... }` Hash, emitted without `Literal.render`.
     pub provenance: Literal,
+    // `idempotent`: delivering the command twice leaves the state delivering it once does, so a saga
+    // redrive may run it again after a crash left its outcome unknown. Emitted as a boolean.
+    pub idempotent: bool,
 }
 
 #[derive(Debug, Clone, Default)]
@@ -142,7 +157,7 @@ pub struct Query {
 }
 
 /// `AuthorizationSpec#to_h`: both fields are bare `.to_s`, never Literal-rendered.
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct AuthorizationSpec {
     pub policy: String,
     pub tenant: Option<String>,
@@ -150,7 +165,7 @@ pub struct AuthorizationSpec {
 
 /// Mirrors `extra_options_to_h`. A typed struct, not a `BTreeMap`, because Ruby's declared
 /// field order must be preserved. Shared by `Query` and `ReadModel`.
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct QueryOptions {
     pub offset: Option<OffsetSpec>,
     // Already-rendered text; cursor never gets ADR 0055's `on:` (out of scope — see this
@@ -187,7 +202,7 @@ pub struct LimitSpec {
     pub target: Option<String>,
 }
 
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct OffsetSpec {
     pub value: String, // Literal::render spelling
     pub target: Option<String>,
@@ -232,6 +247,7 @@ pub struct Aggregate {
     pub ports: Vec<DomainPort>,
     // Same raw-captured-Hash shape as `Command.provenance`.
     pub provenance: Literal,
+    pub acknowledgements: Vec<Acknowledgement>,
 }
 
 #[derive(Debug, Clone, Default)]
@@ -336,6 +352,11 @@ pub struct PortOperation {
     pub name: String,
     pub attributes: Vec<Attribute>,
     pub emits: Vec<String>,
+    /// True for an `asks`: the domain putting a question to the outside, ended by `answers` or
+    /// `refuses` rather than `emits`.
+    pub outbound: bool,
+    pub answers: Option<String>,
+    pub refuses: Option<String>,
     /// The receiving aggregate as routing metadata (`to: Payment`), not an attribute.
     pub to: Option<String>,
 }
@@ -354,16 +375,16 @@ pub struct Bluebook {
     pub version: Option<String>,
     pub vision: Option<String>,
     pub classification: Option<String>,
-    // `formerly_known_as "OldName"`: always `None` today because `parse/chapter.rs` refuses it,
-    // but the key is emitted on every chapter.
+    // `formerly_known_as "OldName"`: always `None` today because `parse/bluebook.rs` refuses it,
+    // but the key is emitted on every bluebook.
     pub formerly_known_as: Option<String>,
-    // `namespace "Hecks::Domain"`: the Ruby module the chapter installs under (ADR 0080).
+    // `namespace "Hecks::Domain"`: the Ruby module the bluebook installs under (ADR 0080).
     pub namespace: Option<String>,
     pub aggregates: Vec<Aggregate>,
     pub read_models: Vec<ReadModel>,
     pub policies: Vec<Policy>,
     pub process_managers: Vec<ProcessManager>,
-    // Core contexts this chapter attaches to (`attaches_to "Query", "ReadModel"`).
+    // Core contexts this bluebook attaches to (`attaches_to "Query", "ReadModel"`).
     pub attaches_to: Vec<String>,
     // `provides "authorization", grant: "..."`: one row per key, in source order.
     pub provides: Vec<Provision>,
@@ -427,4 +448,10 @@ pub struct Adapter {
     pub secrets: Vec<String>,
     // Field name to default, first-insertion order; a repeated key keeps its first slot.
     pub defaults: Vec<(String, crate::ruby_value::Value)>,
+    // A plugin's qualified queries (`Bluebook::Aggregate.Query`), in declaration order.
+    pub answers: Vec<String>,
+    // A plugin's wasm module, beside its `.adapter` file.
+    pub runs: Option<String>,
+    // The capabilities the adapter provides beyond its port's contract, in declaration order.
+    pub provides: Vec<String>,
 }