hecks 2.9.0 → 3.0.0

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

@@ -0,0 +1,27 @@
+//! Mirrors `AttributeCollector#synthesise_closed_set`: an inline `one_of("a", "b")` attribute
+//! becomes a closed-set value object named `Naming.pascal(attribute_name)`.
+
+use crate::build::naming;
+use crate::ir;
+
+/// Builds the closed-set value object for `field_name` with one member per value.
+///
+/// Only `AggregateBuilder#build` keeps the result; command, query, value-object and port
+/// builders discard it and keep the derived type name.
+pub fn synthesize(field_name: &str, values: &[String]) -> ir::ValueObject {
+    let type_name = naming::pascal(field_name);
+    ir::ValueObject {
+        name: type_name,
+        attributes: vec![ir::Attribute {
+            name: "value".to_string(),
+            type_name: "String".to_string(),
+            ..Default::default()
+        }],
+        invariants: Vec::new(),
+        closed_set: true,
+        members: values
+            .iter()
+            .map(|value| vec![("value".to_string(), crate::ruby_value::Value::Str(value.clone()))])
+            .collect(),
+    }
+}

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

@@ -0,0 +1,276 @@
+//! Derives the identity paths of `identified_by`, in both its field form and its
+//! `identified_by ValueObject, as: field` form (mirrors `AttributeCollector`).
+
+use crate::diag::{Diagnostic, ParseResult};
+use crate::ir;
+
+/// Resolves `identified_by :field` to its scalar identity paths.
+///
+/// An `id` or `_id`-suffixed name with no matching attribute passes through: the meta-domain
+/// identifies by parent ids the judge's replay supplies (mirrors `attribute_collector.rb`).
+pub fn resolve_identity_field(
+    file: &str,
+    line: usize,
+    context_name: &str,
+    field: &str,
+    value_objects: &[ir::ValueObject],
+    attributes: &[ir::Attribute],
+) -> ParseResult<Vec<String>> {
+    let attr = attributes.iter().find(|a| a.name == field);
+
+    let attr = match attr {
+        Some(attr) => attr,
+        None if field == "id" || field.ends_with("_id") => return Ok(vec![field.to_string()]),
+        None => {
+            return Err(Diagnostic::new(file, line, format!("{context_name}.identified_by :{field} names no attribute {context_name} declares")));
+        }
+    };
+
+    identity_paths_for_attribute(file, line, context_name, attr, value_objects, field, &[])
+}
+
+// Runs at the end of the aggregate body because the value object may be declared after
+// `identified_by`. Mints the identity attribute at `insert_at`.
+#[allow(clippy::too_many_arguments)]
+pub fn resolve_identity_type(
+    file: &str,
+    line: usize,
+    context_name: &str,
+    target: &str,
+    as_field: Option<&str>,
+    insert_at: usize,
+    value_objects: &[ir::ValueObject],
+    attributes: &mut Vec<ir::Attribute>,
+) -> ParseResult<Vec<String>> {
+    let target = crate::build::naming::demodulise(target);
+    let matches: Vec<&ir::ValueObject> =
+        value_objects.iter().filter(|v| v.name == target).collect();
+    if matches.len() > 1 {
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!("{context_name}.identified_by names duplicate value object {target}"),
+        ));
+    }
+    let vo = matches.first().copied().ok_or_else(|| {
+        Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{context_name}.identified_by names {target}, which is not a declared value object"
+            ),
+        )
+    })?;
+
+    if vo.attributes.is_empty() {
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!("{context_name}.identified_by names {target}, which declares no attributes"),
+        ));
+    }
+
+    let field = as_field
+        .map(|s| s.to_string())
+        .unwrap_or_else(|| crate::build::naming::snake(&target));
+    if attributes.iter().any(|attribute| attribute.name == field) {
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{context_name}.identified_by {target} mints :{field}, but that attribute is already declared"
+            ),
+        ));
+    }
+
+    let minted = ir::Attribute {
+        name: field.clone(),
+        type_name: target.clone(),
+        list: false,
+        ..Default::default()
+    };
+    let insert_at = insert_at.min(attributes.len());
+    attributes.insert(insert_at, minted);
+
+    let mut paths = Vec::new();
+    for attribute in &vo.attributes {
+        paths.extend(identity_paths_for_attribute(
+            file,
+            line,
+            context_name,
+            attribute,
+            value_objects,
+            &format!("{field}.{}", attribute.name),
+            std::slice::from_ref(&target),
+        )?);
+    }
+    Ok(paths)
+}
+
+fn identity_paths_for_attribute(
+    file: &str,
+    line: usize,
+    context_name: &str,
+    attribute: &ir::Attribute,
+    value_objects: &[ir::ValueObject],
+    path: &str,
+    visited: &[String],
+) -> ParseResult<Vec<String>> {
+    if attribute.list {
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{context_name}'s identity member {path} is a list — an identity member must be scalar"
+            ),
+        ));
+    }
+    if attribute.optional {
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{context_name}'s identity member {path} is optional — an identity must be wholly known"
+            ),
+        ));
+    }
+    if attribute.reference_target().is_some() {
+        return Ok(vec![path.to_string()]);
+    }
+
+    let Some(nested) = value_objects
+        .iter()
+        .find(|value_object| value_object.name == attribute.type_name)
+    else {
+        return Ok(vec![path.to_string()]);
+    };
+
+    if visited.iter().any(|name| name == &nested.name) {
+        let mut cycle = visited.to_vec();
+        cycle.push(nested.name.clone());
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{context_name}'s identity value objects form a cycle: {}",
+                cycle.join(" -> ")
+            ),
+        ));
+    }
+    if nested.attributes.is_empty() {
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{context_name}'s identity member {path} names {}, which declares no attributes",
+                nested.name
+            ),
+        ));
+    }
+
+    let mut next_visited = visited.to_vec();
+    next_visited.push(nested.name.clone());
+    let mut paths = Vec::new();
+    for member in &nested.attributes {
+        paths.extend(identity_paths_for_attribute(
+            file,
+            line,
+            context_name,
+            member,
+            value_objects,
+            &format!("{path}.{}", member.name),
+            &next_visited,
+        )?);
+    }
+    Ok(paths)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn expands_every_recursively_scalar_member_in_declaration_order() {
+        let mut attributes = Vec::new();
+        let value_objects = vec![
+            ir::ValueObject {
+                name: "BranchCode".to_string(),
+                attributes: vec![ir::Attribute {
+                    name: "value".to_string(),
+                    type_name: "String".to_string(),
+                    ..Default::default()
+                }],
+                ..Default::default()
+            },
+            ir::ValueObject {
+                name: "BoxIdentity".to_string(),
+                attributes: vec![
+                    ir::Attribute {
+                        name: "branch".to_string(),
+                        type_name: "BranchCode".to_string(),
+                        ..Default::default()
+                    },
+                    ir::Attribute {
+                        name: "number".to_string(),
+                        type_name: "Integer".to_string(),
+                        ..Default::default()
+                    },
+                ],
+                ..Default::default()
+            },
+        ];
+
+        let paths = resolve_identity_type(
+            "f.bluebook",
+            1,
+            "SafeDepositBox",
+            "BoxIdentity",
+            Some("location"),
+            0,
+            &value_objects,
+            &mut attributes,
+        )
+        .unwrap();
+
+        assert_eq!(
+            paths,
+            vec![
+                "location.branch.value".to_string(),
+                "location.number".to_string()
+            ]
+        );
+        assert_eq!(attributes[0].name, "location");
+        assert_eq!(attributes[0].type_name, "BoxIdentity");
+    }
+
+    #[test]
+    fn rejects_non_scalar_identity_members() {
+        let mut attributes = Vec::new();
+        let value_objects = vec![ir::ValueObject {
+            name: "Identity".to_string(),
+            attributes: vec![ir::Attribute {
+                name: "regions".to_string(),
+                type_name: "String".to_string(),
+                list: true,
+                ..Default::default()
+            }],
+            ..Default::default()
+        }];
+
+        let error = resolve_identity_type(
+            "f.bluebook",
+            1,
+            "Account",
+            "Identity",
+            None,
+            0,
+            &value_objects,
+            &mut attributes,
+        )
+        .unwrap_err();
+
+        assert!(error
+            .message
+            .contains("identity member identity.regions is a list"));
+    }
+}

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

@@ -0,0 +1,12 @@
+//! Derivations that turn parsed constructs into IR facts a bluebook never spells directly,
+//! one submodule per Ruby source (`attribute_collector.rb` and its siblings).
+
+pub mod closed_sets;
+pub mod identity;
+pub mod naming;
+pub mod pattern_subset;
+pub mod query_derive;
+pub mod query_inference;
+pub mod query_options;
+pub mod read_model;
+pub mod references;

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

@@ -0,0 +1,141 @@
+//! Pure name-shape conversions (mirrors `Hecks::Naming`) shared by the other derivations.
+
+/// `"Pizzas::Order" -> "Order"`.
+pub fn demodulise(type_name: &str) -> String {
+    type_name
+        .rsplit("::")
+        .next()
+        .unwrap_or(type_name)
+        .to_string()
+}
+
+/// A bare command constant (`Account::Debit`) becomes `Account.Debit`; strings pass through.
+///
+/// Only the last `::` is rewritten, so `Banking::Account::Debit` -> `Banking::Account.Debit`.
+pub fn command_ref(raw: &str) -> String {
+    match crate::ruby_value::read(raw.trim()) {
+        crate::ruby_value::Value::Str(s) => s,
+        crate::ruby_value::Value::Bare(bare) => match bare.rsplit_once("::") {
+            Some((path, command)) => format!("{path}.{command}"),
+            None => bare,
+        },
+        other => crate::ruby_value::to_s(&other),
+    }
+}
+
+/// Event reference of a process manager: a bare constant chain keeps only its last segment.
+///
+/// `SagaInterpreter` matches a bare `event.name`, never a `.`-qualified one.
+pub fn event_name_ref(raw: &str) -> String {
+    match crate::ruby_value::read(raw.trim()) {
+        crate::ruby_value::Value::Str(s) => s,
+        crate::ruby_value::Value::Bare(bare) => demodulise(&bare),
+        other => crate::ruby_value::to_s(&other),
+    }
+}
+
+/// `"PizzaName" -> "pizza_name"`, using the same two-pass split as `Hecks::Naming.snake`.
+pub fn snake(text: &str) -> String {
+    let chars: Vec<char> = text.chars().collect();
+    let mut pass1 = String::new();
+    for (i, &ch) in chars.iter().enumerate() {
+        let is_upper_run_boundary = ch.is_ascii_uppercase()
+            && i > 0
+            && chars[i - 1].is_ascii_uppercase()
+            && i + 1 < chars.len()
+            && chars[i + 1].is_ascii_lowercase();
+        if is_upper_run_boundary {
+            pass1.push('_');
+        }
+        pass1.push(ch);
+    }
+
+    let pass1_chars: Vec<char> = pass1.chars().collect();
+    let mut pass2 = String::new();
+    for (i, &ch) in pass1_chars.iter().enumerate() {
+        let is_lower_to_upper_boundary = ch.is_ascii_uppercase()
+            && i > 0
+            && (pass1_chars[i - 1].is_ascii_lowercase() || pass1_chars[i - 1].is_ascii_digit());
+        if is_lower_to_upper_boundary {
+            pass2.push('_');
+        }
+        pass2.push(ch);
+    }
+
+    pass2.to_lowercase()
+}
+
+/// `"pizza_name" -> "PizzaName"`.
+pub fn pascal(text: &str) -> String {
+    text.split('_')
+        .map(|part| {
+            let mut chars = part.chars();
+            match chars.next() {
+                Some(first) => first.to_ascii_uppercase().to_string() + chars.as_str(),
+                None => String::new(),
+            }
+        })
+        .collect()
+}
+
+/// Pluralizes a snake-cased name: `y` -> `ies`, sibilants take `es`, else `s`.
+pub fn plural(text: &str) -> String {
+    if text.len() > 1 {
+        let last = &text[text.len() - 1..];
+        let before_last = text.chars().rev().nth(1);
+        if last == "y" && !matches!(before_last, Some('a' | 'e' | 'i' | 'o' | 'u')) {
+            return format!("{}ies", &text[..text.len() - 1]);
+        }
+    }
+    for suffix in ["s", "x", "z", "ch", "sh"] {
+        if text.ends_with(suffix) {
+            return format!("{text}es");
+        }
+    }
+    format!("{text}s")
+}
+
+/// Inverse of `plural` for `has_many` targets: `ies` -> `y`, trailing `s` dropped.
+pub fn singularize(text: &str) -> String {
+    if text.len() > 3 && text.ends_with("ies") {
+        return format!("{}y", &text[..text.len() - 3]);
+    }
+    if text.len() > 1 && text.ends_with('s') {
+        return text[..text.len() - 1].to_string();
+    }
+    text.to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn pluralizes_a_read_model_head_name() {
+        assert_eq!(plural("state_style"), "state_styles");
+        assert_eq!(plural("collection"), "collections");
+        assert_eq!(plural("company"), "companies");
+        assert_eq!(plural("box"), "boxes");
+    }
+
+    #[test]
+    fn demodulises_a_namespaced_constant() {
+        assert_eq!(demodulise("Pizzas::Order"), "Order");
+        assert_eq!(demodulise("Order"), "Order");
+    }
+
+    #[test]
+    fn command_refs_a_bare_constant_by_its_last_namespace_segment() {
+        assert_eq!(command_ref("Account::Debit"), "Account.Debit");
+        assert_eq!(
+            command_ref("Banking::Account::Debit"),
+            "Banking::Account.Debit"
+        );
+        assert_eq!(command_ref("Debit"), "Debit");
+    }
+
+    #[test]
+    fn command_refs_a_legacy_quoted_string_unchanged() {
+        assert_eq!(command_ref("\"Account.Debit\""), "Account.Debit");
+    }
+}

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

@@ -0,0 +1,161 @@
+//! The regex subset a bluebook `pattern:` may use (mirrors `Hecks::Bluebook::PatternSubset`).
+//! Engines disagree on backreferences, lookaround and `\d`/POSIX classes, so they are refused.
+
+pub struct Rejection {
+    pub construct: &'static str,
+    pub reason: &'static str,
+}
+
+/// `None` when the pattern is in the portable subset, else a `Rejection` naming the construct.
+pub fn validate(pattern: &str) -> Option<Rejection> {
+    let chars: Vec<char> = pattern.chars().collect();
+    let mut index = 0usize;
+
+    while index < chars.len() {
+        if chars[index] == '\\' {
+            let next = chars.get(index + 1).copied();
+            if matches!(next, Some(c) if c.is_ascii_digit() && c != '0') {
+                return Some(refuse("backreference"));
+            }
+            if matches!(next, Some('k') | Some('g')) {
+                return Some(refuse("named_backreference"));
+            }
+            if matches!(
+                next,
+                Some('d') | Some('D') | Some('w') | Some('W') | Some('s') | Some('S')
+            ) {
+                return Some(refuse("perl_class"));
+            }
+            index += if next.is_some() { 2 } else { 1 };
+            continue;
+        }
+
+        if chars[index] == '(' && chars.get(index + 1) == Some(&'?') {
+            let third = chars.get(index + 2).copied();
+            if matches!(third, Some('=') | Some('!')) {
+                return Some(refuse("lookahead"));
+            }
+            if third == Some('<') && matches!(chars.get(index + 3).copied(), Some('=') | Some('!'))
+            {
+                return Some(refuse("lookbehind"));
+            }
+            if third == Some('>') {
+                return Some(refuse("atomic_group"));
+            }
+        }
+
+        if posix_class_at(&chars, index) {
+            return Some(refuse("posix_class"));
+        }
+        if matches!(chars[index], '*' | '+' | '?') && chars.get(index + 1) == Some(&'+') {
+            return Some(refuse("possessive"));
+        }
+
+        index += 1;
+    }
+
+    None
+}
+
+fn refuse(key: &'static str) -> Rejection {
+    let (construct, reason) = REASONS
+        .iter()
+        .find(|(k, _, _)| *k == key)
+        .map(|(_, c, r)| (*c, *r))
+        .expect("unknown PatternSubset rejection key");
+    Rejection { construct, reason }
+}
+
+fn posix_class_at(chars: &[char], index: usize) -> bool {
+    if chars.get(index) != Some(&'[') || chars.get(index + 1) != Some(&':') {
+        return false;
+    }
+    let mut cursor = index + 2;
+    while matches!(chars.get(cursor), Some(c) if c.is_ascii_alphabetic()) {
+        cursor += 1;
+    }
+    chars.get(cursor) == Some(&':') && chars.get(cursor + 1) == Some(&']')
+}
+
+const REASONS: &[(&str, &str, &str)] = &[
+    (
+        "backreference",
+        "backreference",
+        "backreferences cannot be matched in linear time and portable engines refuse them ; a declared pattern may not depend on one",
+    ),
+    (
+        "named_backreference",
+        "named backreference",
+        "a named backreference is still a backreference — it cannot be matched in linear time ; a declared pattern may not depend on one",
+    ),
+    (
+        "perl_class",
+        "perl character class",
+        "engines read it in OPPOSITE directions : ASCII in some and Unicode in others, so an Arabic-Indic digit satisfies one and not the other. Spell the range you mean — [0-9], [A-Za-z0-9_], [ \\t] — which every engine reads the same way",
+    ),
+    (
+        "posix_class",
+        "posix bracket class",
+        "[:digit:] and friends flip between ASCII and Unicode across engines — the mirror of the perl classes, and wrong in the same way. Spell the range you mean",
+    ),
+    (
+        "lookahead",
+        "lookahead",
+        "lookahead cannot be matched in linear time and portable engines refuse it ; a declared pattern may not depend on it",
+    ),
+    (
+        "lookbehind",
+        "lookbehind",
+        "lookbehind cannot be matched in linear time and portable engines refuse it ; a declared pattern may not depend on it",
+    ),
+    (
+        "atomic_group",
+        "atomic group",
+        "an atomic group is a backtracking-engine control knob — linear-time engines reject `(?>` as a syntax error",
+    ),
+    (
+        "possessive",
+        "possessive quantifier",
+        "a possessive quantifier is a backtracking-engine control knob — linear-time engines reject it as a syntax error",
+    ),
+];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn admits_the_explicit_ranges_email_address_pattern_uses() {
+        assert!(validate(r"^[^@ ]+@[^@ ]+\.[^@ ]+$").is_none());
+    }
+
+    #[test]
+    fn refuses_a_perl_digit_class() {
+        let r = validate(r"\d+").unwrap();
+        assert_eq!(r.construct, "perl character class");
+    }
+
+    #[test]
+    fn refuses_a_backreference() {
+        let r = validate(r"(a)\1").unwrap();
+        assert_eq!(r.construct, "backreference");
+    }
+
+    #[test]
+    fn refuses_lookahead() {
+        let r = validate(r"a(?=b)").unwrap();
+        assert_eq!(r.construct, "lookahead");
+    }
+
+    #[test]
+    fn refuses_a_posix_class() {
+        let r = validate(r"[[:digit:]]").unwrap();
+        assert_eq!(r.construct, "posix bracket class");
+    }
+
+    #[test]
+    fn treats_an_escaped_construct_as_a_literal() {
+        // `\(\?=` is the literal text "(?=", not a lookahead.
+        assert!(validate(r"\(\?=").is_none());
+    }
+}

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

@@ -0,0 +1,72 @@
+//! Derives `WhereClause`s from a query's `where` arguments, splitting `{gte: 100}` comparators
+//! and defaulting a bare value to `eq`.
+
+use crate::ir;
+use crate::ruby_value;
+
+/// Splits each `(field, raw-value)` pair into a `WhereClause`; a bare value implies `eq`.
+/// `target` (ADR 0055's `on:`, already resolved and demodulised by the caller) applies to
+/// every clause this one `where` call declares — `None` in Query context, or when a ReadModel's
+/// `where` left `on:` off.
+pub fn where_clauses(pairs: &[(String, String)], target: Option<&str>) -> Vec<ir::WhereClause> {
+    pairs
+        .iter()
+        .map(|(field, raw)| {
+            let trimmed = raw.trim();
+            let (op, operand_raw) = split_comparator(trimmed);
+            let value = ruby_value::render(&ruby_value::read(operand_raw));
+            ir::WhereClause {
+                field: field.clone(),
+                op,
+                value,
+                target: target.map(str::to_string),
+            }
+        })
+        .collect()
+}
+
+/// Refuses `on:` on a Query's `where` — ADR 0055 scopes `on:` to ReadModel only (a plain `query`
+/// has no many-side heads for it to disambiguate between), so this stays a permanent refusal
+/// there, not a not-yet-ported one.
+///
+/// `where` accepts arbitrary field names as named arguments, so an `on:` target would otherwise
+/// misparse as a comparison on a field called "on".
+pub fn refuse_on_target(
+    file: &str,
+    line: usize,
+    word: &str,
+    named: &[(String, String)],
+) -> crate::diag::ParseResult<()> {
+    if named.iter().any(|(name, _)| name == "on") {
+        return Err(crate::diag::Diagnostic::not_yet_implemented(
+            file,
+            line,
+            format!("{word}(on: ...) — per-target read-model filtering (ADR 0055)"),
+        ));
+    }
+    Ok(())
+}
+
+fn split_comparator(raw: &str) -> (String, &str) {
+    if raw.starts_with('{') && raw.ends_with('}') {
+        let inner = raw[1..raw.len() - 1].trim();
+        if let Some((op, operand)) = crate::parse::as_named(inner) {
+            return (op.to_string(), operand);
+        }
+    }
+    ("eq".to_string(), raw)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn refuses_an_on_target_cleanly_instead_of_silently_dropping_or_misparsing_it() {
+        let named = vec![("on".to_string(), "Character".to_string())];
+        let err = refuse_on_target("f.bluebook", 3, "where", &named).unwrap_err();
+        assert!(err.message.contains("on: ...) — per-target read-model filtering (ADR 0055)"));
+        assert_eq!(err.file, "f.bluebook");
+        assert_eq!(err.line, 3);
+    }
+}