hecks 6.0.0 → 7.0.0

data/rust/parser/src/build/correlation_keys.rs

@@ -0,0 +1,125 @@
+//! Resolves a bare `correlates_by` name to an aggregate's identity path, once every aggregate
+//! exists. `correlates_by Message` means `"Message.id"`; mirrors
+//! `BluebookBuilder::Validation#resolve_bare_correlation_keys!` in the Ruby builder.
+
+use crate::diag::{Diagnostic, ParseResult};
+use crate::ir;
+
+/// Rewrites every bare process-manager key that names an aggregate of `bluebook` to
+/// `"<Aggregate>.<identity>"`. A dotted key is left as written; a bare name that names no
+/// aggregate is refused with the same message the Ruby builder gives.
+pub fn resolve_bare(file: &str, bluebook: &mut ir::Bluebook) -> ParseResult<()> {
+    let aggregates = bluebook.aggregates.clone();
+
+    for process_manager in &mut bluebook.process_managers {
+        let key = process_manager.correlates_by.clone();
+        if key.is_empty() || key.contains('.') {
+            continue;
+        }
+
+        let bare = key.rsplit("::").next().unwrap_or(&key);
+        let Some(aggregate) = aggregates.iter().find(|candidate| candidate.name == bare) else {
+            return Err(Diagnostic::new(
+                file,
+                0,
+                bare_correlation_message(&process_manager.name, &key),
+            ));
+        };
+
+        let identity = identity_path(file, &process_manager.name, aggregate)?;
+        process_manager.correlates_by = format!("{}.{identity}", aggregate.name);
+    }
+
+    Ok(())
+}
+
+/// The one field an aggregate is correlated by: its identity, or `id` when it declares none.
+fn identity_path(
+    file: &str,
+    process_manager: &str,
+    aggregate: &ir::Aggregate,
+) -> ParseResult<String> {
+    match aggregate.identified_by.as_slice() {
+        [] => Ok("id".to_string()),
+        [only] => Ok(only.strip_suffix(".value").unwrap_or(only).to_string()),
+        [first, ..] => Err(Diagnostic::new(
+            file,
+            0,
+            format!(
+                "{process_manager} correlates_by {}, but {} has a composite identity — name the one field, e.g. {}.{first}",
+                aggregate.name, aggregate.name, aggregate.name
+            ),
+        )),
+    }
+}
+
+/// The refusal for a bare name that names no aggregate, worded as the Ruby builder words it.
+pub fn bare_correlation_message(process_manager: &str, key: &str) -> String {
+    format!(
+        "{process_manager} correlates_by {key}, which names a whole field rather than one of its scalars — \
+         say which one, e.g. {key}.value (or name an aggregate of this bluebook, which correlates by its identity)"
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn aggregate(name: &str, identified_by: &[&str]) -> ir::Aggregate {
+        ir::Aggregate {
+            name: name.to_string(),
+            identified_by: identified_by.iter().map(ToString::to_string).collect(),
+            ..Default::default()
+        }
+    }
+
+    fn bluebook_with(aggregates: Vec<ir::Aggregate>, key: &str) -> ir::Bluebook {
+        ir::Bluebook {
+            aggregates,
+            process_managers: vec![ir::ProcessManager {
+                name: "ScheduledSend".to_string(),
+                correlates_by: key.to_string(),
+                ..Default::default()
+            }],
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn a_bare_aggregate_name_expands_to_its_id() {
+        let mut bluebook = bluebook_with(vec![aggregate("Message", &["id"])], "Message");
+
+        resolve_bare("t.bluebook", &mut bluebook).unwrap();
+
+        assert_eq!(bluebook.process_managers[0].correlates_by, "Message.id");
+    }
+
+    #[test]
+    fn a_bare_aggregate_name_expands_to_the_identity_it_declares() {
+        let mut bluebook = bluebook_with(vec![aggregate("Sighting", &["code.value"])], "Sighting");
+
+        resolve_bare("t.bluebook", &mut bluebook).unwrap();
+
+        assert_eq!(bluebook.process_managers[0].correlates_by, "Sighting.code");
+    }
+
+    #[test]
+    fn a_bare_name_that_is_no_aggregate_is_refused() {
+        let mut bluebook = bluebook_with(vec![aggregate("Message", &["id"])], "Status");
+
+        let err = resolve_bare("t.bluebook", &mut bluebook).unwrap_err();
+
+        assert!(err
+            .message
+            .contains("ScheduledSend correlates_by Status, which names a whole field"));
+    }
+
+    #[test]
+    fn a_dotted_path_is_left_unchanged() {
+        let mut bluebook = bluebook_with(vec![aggregate("Message", &["id"])], "Message.id");
+
+        resolve_bare("t.bluebook", &mut bluebook).unwrap();
+
+        assert_eq!(bluebook.process_managers[0].correlates_by, "Message.id");
+    }
+}

data/rust/parser/src/build/mod.rs

@@ -2,6 +2,7 @@
 //! one submodule per Ruby source (`attribute_collector.rb` and its siblings).
 
 pub mod closed_sets;
+pub mod correlation_keys;
 pub mod identity;
 pub mod named_pattern;
 pub mod naming;

data/rust/parser/src/emit.rs

@@ -59,7 +59,7 @@ fn canonical_form_table() -> JsonValue {
 
 /// `IR::Bluebook#to_h`; field order is pinned there.
 pub fn bluebook_json(bb: &ir::Bluebook) -> JsonValue {
-    JsonValue::Object(vec![
+    let mut fields = vec![
         (
             "ir_version".to_string(),
             JsonValue::Number(bb.ir_version.to_string()),
@@ -126,7 +126,31 @@ pub fn bluebook_json(bb: &ir::Bluebook) -> JsonValue {
             ),
         ),
         ("canonical_form".to_string(), canonical_form_table()),
-    ])
+    ];
+    // Left out when the bluebook declares no module, as `IR::Bluebook#to_h` leaves it out.
+    if !bb.modules.is_empty() {
+        let at = fields.len() - 1;
+        fields.insert(at, ("modules".to_string(), modules_json(&bb.modules)));
+    }
+    JsonValue::Object(fields)
+}
+
+/// `IR::Bluebook::ModuleRow#to_h`, one row per aggregate a module groups.
+fn modules_json(rows: &[ir::ModuleRow]) -> JsonValue {
+    JsonValue::Array(
+        rows.iter()
+            .map(|row| {
+                JsonValue::Object(vec![
+                    ("name".to_string(), JsonValue::str(row.name.clone())),
+                    ("vision".to_string(), JsonValue::str(row.vision.clone())),
+                    (
+                        "aggregate".to_string(),
+                        JsonValue::str(row.aggregate.clone()),
+                    ),
+                ])
+            })
+            .collect(),
+    )
 }
 
 /// `IR::Aggregate#to_h` (lib/hecks/bluebook/ir/aggregate.rb).
@@ -192,6 +216,12 @@ fn aggregate_json(a: &ir::Aggregate) -> JsonValue {
                 .as_ref()
                 .map_or(JsonValue::Null, ruby_value_json),
         ),
+        // `formerly_known_as` is admitted but the parser does not build it yet, so it is null.
+        ("formerly_known_as".to_string(), JsonValue::Null),
+        (
+            "created_by".to_string(),
+            JsonValue::opt_str(a.created_by.as_ref()),
+        ),
         (
             "acknowledgements".to_string(),
             JsonValue::Array(
@@ -284,7 +314,10 @@ fn given_json(g: &ir::Given) -> JsonValue {
 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())),
+        (
+            "subject".to_string(),
+            JsonValue::opt_str(a.subject.as_ref()),
+        ),
         ("reason".to_string(), JsonValue::str(a.reason.clone())),
     ])
 }
@@ -311,6 +344,10 @@ fn command_json(c: &ir::Command) -> JsonValue {
     if c.roles.len() > 1 {
         fields.push(("roles".to_string(), JsonValue::strings(&c.roles)));
     }
+    // Only a command that names an audience says so, so every other command emits as it always did.
+    if !c.audience.is_empty() {
+        fields.push(("audience".to_string(), JsonValue::strings(&c.audience)));
+    }
     fields.extend(command_json_rest(c));
     JsonValue::Object(fields)
 }
@@ -359,6 +396,7 @@ fn command_json_rest(c: &ir::Command) -> Vec<(String, JsonValue)> {
                 .map_or(JsonValue::Null, ruby_value_json),
         ),
         ("idempotent".to_string(), JsonValue::Bool(c.idempotent)),
+        ("mints_era".to_string(), JsonValue::Bool(c.mints_era)),
     ]
 }
 
@@ -788,6 +826,8 @@ fn process_manager_json(pm: &ir::ProcessManager) -> JsonValue {
             "ends_on".to_string(),
             JsonValue::opt_str(pm.ends_on.as_ref()),
         ),
+        ("endings".to_string(), JsonValue::strings(&pm.endings)),
+        ("resumes".to_string(), JsonValue::strings(&pm.resumes)),
         ("states".to_string(), JsonValue::strings(&pm.states)),
         (
             "handlers".to_string(),
@@ -930,6 +970,10 @@ fn port_operation_json(op: &ir::PortOperation) -> JsonValue {
             JsonValue::Array(op.attributes.iter().map(attribute_json).collect()),
         ),
         ("emits".to_string(), JsonValue::strings(&op.emits)),
+        (
+            "handles".to_string(),
+            JsonValue::Array(op.handles.iter().map(command_value_json).collect()),
+        ),
     ];
     // An `asks` names its direction and both endings, as `PortOperation#to_h` merges them.
     if op.outbound {
@@ -947,6 +991,14 @@ fn port_operation_json(op: &ir::PortOperation) -> JsonValue {
     JsonValue::Object(fields)
 }
 
+/// One `handles` entry as the Ruby IR writes it: the command and the value it takes.
+fn command_value_json(held: &ir::CommandValue) -> JsonValue {
+    JsonValue::Object(vec![
+        ("command".to_string(), JsonValue::str(held.command.clone())),
+        ("value".to_string(), JsonValue::str(held.value.clone())),
+    ])
+}
+
 /// A string, or `null` when absent.
 fn optional_str(value: Option<&String>) -> JsonValue {
     value.map_or(JsonValue::Null, |text| JsonValue::String(text.clone()))

data/rust/parser/src/ir.rs

@@ -49,7 +49,7 @@ pub struct ProjectedField {
 #[derive(Debug, Clone, Default)]
 pub struct Acknowledgement {
     pub finding: String,
-    pub subject: String,
+    pub subject: Option<String>,
     pub reason: String,
 }
 
@@ -107,6 +107,9 @@ pub struct Command {
     /// 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>,
+    /// Who a launcher lists the command for (`audience :record`); empty when the command names
+    /// none, and then absent from the IR.
+    pub audience: Vec<String>,
     pub goal: Option<String>,
     pub references: Option<String>,
     pub attributes: Vec<Attribute>,
@@ -123,6 +126,9 @@ pub struct Command {
     // `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,
+    // `mints_era true`: the command's own record may be written through a boot whose shape no era
+    // holds yet. Emitted as a boolean.
+    pub mints_era: bool,
 }
 
 #[derive(Debug, Clone, Default)]
@@ -248,6 +254,9 @@ pub struct Aggregate {
     // Same raw-captured-Hash shape as `Command.provenance`.
     pub provenance: Literal,
     pub acknowledgements: Vec<Acknowledgement>,
+    // The command that creates this aggregate's records, which a missing-record refusal names; null
+    // when the bluebook declares none.
+    pub created_by: Option<String>,
 }
 
 #[derive(Debug, Clone, Default)]
@@ -343,6 +352,8 @@ pub struct ProcessManager {
     pub correlates_by: String,
     pub starts_on: Option<String>,
     pub ends_on: Option<String>,
+    pub endings: Vec<String>,
+    pub resumes: Vec<String>,
     pub states: Vec<String>,
     pub handlers: Vec<ProcessManagerHandler>,
 }
@@ -359,6 +370,15 @@ pub struct PortOperation {
     pub refuses: Option<String>,
     /// The receiving aggregate as routing metadata (`to: Payment`), not an attribute.
     pub to: Option<String>,
+    /// Which value of which command this operation handles (`handles "Build.build!", value: "wasm"`).
+    pub handles: Vec<CommandValue>,
+}
+
+/// One `handles` line: a command and the value of it this operation takes.
+#[derive(Debug, Clone, Default)]
+pub struct CommandValue {
+    pub command: String,
+    pub value: String,
 }
 
 #[derive(Debug, Clone, Default)]
@@ -388,6 +408,8 @@ pub struct Bluebook {
     pub attaches_to: Vec<String>,
     // `provides "authorization", grant: "..."`: one row per key, in source order.
     pub provides: Vec<Provision>,
+    // `domain_module "Name" do … end`: one row per aggregate a module groups, in source order.
+    pub modules: Vec<ModuleRow>,
 }
 
 impl Default for Bluebook {
@@ -406,10 +428,20 @@ impl Default for Bluebook {
             process_managers: Vec::new(),
             attaches_to: Vec::new(),
             provides: Vec::new(),
+            modules: Vec::new(),
         }
     }
 }
 
+/// One aggregate's place in a module, emitted as `{"name", "vision", "aggregate"}`; the
+/// vision is empty when the module names none.
+#[derive(Debug, Clone, Default)]
+pub struct ModuleRow {
+    pub name: String,
+    pub vision: String,
+    pub aggregate: String,
+}
+
 /// One row of a declared capability, emitted as `{"capability", "key", "verb"}`.
 #[derive(Debug, Clone, Default)]
 pub struct Provision {