hecks 2.8.0 → 3.0.0

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

@@ -0,0 +1,269 @@
+//! Infers a query's symbolic `where` arguments from the compared field's type, once every
+//! aggregate exists so `/` reference hops resolve; pagination symbols stay explicit.
+
+use crate::diag::{Diagnostic, ParseResult};
+use crate::ir;
+use crate::ruby_value;
+
+pub fn apply(file: &str, bluebook: &mut ir::Bluebook) -> ParseResult<()> {
+    let shapes = bluebook.aggregates.clone();
+
+    for aggregate in &mut bluebook.aggregates {
+        let owner = shapes
+            .iter()
+            .find(|candidate| candidate.name == aggregate.name)
+            .expect("aggregate cloned from the same chapter");
+
+        infer_queries(
+            file,
+            &aggregate.name,
+            &mut aggregate.queries,
+            &owner.attributes,
+            owner.lifecycle.as_ref(),
+            &owner.value_objects,
+            Some((owner, &shapes)),
+        )?;
+
+        for entity in &mut aggregate.entities {
+            let entity_shape = owner
+                .entities
+                .iter()
+                .find(|candidate| candidate.name == entity.name)
+                .expect("entity cloned from the same aggregate");
+            infer_queries(
+                file,
+                &format!("{}::{}", aggregate.name, entity.name),
+                &mut entity.queries,
+                &entity_shape.attributes,
+                entity_shape.lifecycle.as_ref(),
+                &owner.value_objects,
+                None,
+            )?;
+        }
+    }
+
+    Ok(())
+}
+
+#[allow(clippy::too_many_arguments)]
+fn infer_queries(
+    file: &str,
+    owner_name: &str,
+    queries: &mut [ir::Query],
+    attributes: &[ir::Attribute],
+    lifecycle: Option<&ir::Lifecycle>,
+    value_objects: &[ir::ValueObject],
+    hop_context: Option<(&ir::Aggregate, &[ir::Aggregate])>,
+) -> ParseResult<()> {
+    for query in queries {
+        let clauses = query.wheres.clone();
+
+        // Local fields resolve first, then reference hops, so inferred arguments keep the
+        // order Ruby gives them even when a hop is written before a local comparison.
+        for clause in &clauses {
+            if clause.field.contains('/') {
+                continue;
+            }
+            let Some(argument_name) = symbolic_name(&clause.value) else {
+                continue;
+            };
+            let leaf = local_leaf(attributes, lifecycle, value_objects, &clause.field);
+            if let Some(leaf) = leaf {
+                append_unless_declared(query, &argument_name, leaf);
+            }
+        }
+
+        if let Some((owner, aggregates)) = hop_context {
+            for clause in &clauses {
+                if !clause.field.contains('/') {
+                    continue;
+                }
+                let Some(argument_name) = symbolic_name(&clause.value) else {
+                    continue;
+                };
+                if let Some(leaf) = hop_leaf(owner, aggregates, &clause.field) {
+                    append_unless_declared(query, &argument_name, leaf);
+                }
+            }
+        }
+
+        for clause in &query.wheres {
+            require_declared_symbol(file, owner_name, query, &clause.value)?;
+        }
+        if let Some(limit) = &query.limit {
+            require_declared_symbol(file, owner_name, query, &limit.value)?;
+        }
+        if let Some(offset) = &query.options.offset {
+            require_declared_symbol(file, owner_name, query, &offset.value)?;
+        }
+    }
+
+    Ok(())
+}
+
+fn append_unless_declared(query: &mut ir::Query, name: &str, leaf: ir::Attribute) {
+    if !query
+        .attributes
+        .iter()
+        .any(|attribute| attribute.name == name)
+    {
+        query.attributes.push(inferred_attribute(name, leaf));
+    }
+}
+
+fn symbolic_name(rendered: &str) -> Option<String> {
+    match ruby_value::read(rendered) {
+        ruby_value::Value::Symbol(name) => Some(name),
+        _ => None,
+    }
+}
+
+fn require_declared_symbol(
+    file: &str,
+    owner_name: &str,
+    query: &ir::Query,
+    rendered: &str,
+) -> ParseResult<()> {
+    let Some(name) = symbolic_name(rendered) else {
+        return Ok(());
+    };
+    if query
+        .attributes
+        .iter()
+        .any(|attribute| attribute.name == name)
+    {
+        return Ok(());
+    }
+
+    Err(Diagnostic::new(
+        file,
+        0,
+        format!(
+            "{owner_name}.{} resolves :{name} from its arguments, but declares no {name} attribute",
+            query.name
+        ),
+    ))
+}
+
+fn local_leaf(
+    attributes: &[ir::Attribute],
+    lifecycle: Option<&ir::Lifecycle>,
+    value_objects: &[ir::ValueObject],
+    path: &str,
+) -> Option<ir::Attribute> {
+    let mut segments = path.split('.');
+    let head = segments.next()?;
+    let nested: Vec<&str> = segments.collect();
+
+    if nested.is_empty() && lifecycle.is_some_and(|held| held.field == head) {
+        return Some(ir::Attribute {
+            name: head.to_string(),
+            type_name: "String".to_string(),
+            ..Default::default()
+        });
+    }
+
+    let mut current = attributes.iter().find(|attribute| attribute.name == head)?;
+    for member_name in nested {
+        let value_object = value_objects
+            .iter()
+            .find(|value_object| value_object.name == current.type_name)?;
+        current = value_object
+            .attributes
+            .iter()
+            .find(|attribute| attribute.name == member_name)?;
+    }
+    Some(current.clone())
+}
+
+fn hop_leaf(
+    owner: &ir::Aggregate,
+    aggregates: &[ir::Aggregate],
+    path: &str,
+) -> Option<ir::Attribute> {
+    let segments: Vec<&str> = path.split('/').collect();
+    let (tail, hops) = segments.split_last()?;
+    if hops.is_empty() || tail.is_empty() {
+        return None;
+    }
+
+    let mut target = owner;
+    for hop in hops {
+        let reference = target
+            .attributes
+            .iter()
+            .find(|attribute| attribute.name == *hop)?;
+        let target_name = reference.reference_target()?;
+        target = aggregates.iter().find(|aggregate| {
+            aggregate.name == target_name
+                || aggregate.name.rsplit("::").next() == target_name.rsplit("::").next()
+        })?;
+    }
+
+    local_leaf(
+        &target.attributes,
+        target.lifecycle.as_ref(),
+        &target.value_objects,
+        tail,
+    )
+}
+
+fn inferred_attribute(name: &str, leaf: ir::Attribute) -> ir::Attribute {
+    ir::Attribute {
+        name: name.to_string(),
+        type_name: leaf.type_name,
+        list: leaf.list,
+        ..Default::default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn pagination_symbols_are_not_inferred_without_a_compared_field() {
+        let cases = [
+            (
+                ir::Query {
+                    name: "Page".to_string(),
+                    limit: Some(ir::LimitSpec {
+                        value: ":page_size".to_string(),
+                        target: None,
+                    }),
+                    ..Default::default()
+                },
+                "page_size",
+            ),
+            (
+                ir::Query {
+                    name: "Page".to_string(),
+                    options: ir::QueryOptions {
+                        offset: Some(ir::OffsetSpec { value: ":start_at".to_string(), target: None }),
+                        ..Default::default()
+                    },
+                    ..Default::default()
+                },
+                "start_at",
+            ),
+        ];
+
+        for (mut query, missing) in cases {
+            let refusal = infer_queries(
+                "fixture.bluebook",
+                "Item",
+                std::slice::from_mut(&mut query),
+                &[],
+                None,
+                &[],
+                None,
+            )
+            .unwrap_err();
+
+            assert!(refusal
+                .to_string()
+                .contains(&format!("declares no {missing} attribute")));
+            assert!(query.attributes.is_empty());
+        }
+    }
+}

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

@@ -0,0 +1,100 @@
+//! Query option words (`offset`, `cursor`, `authorize`, `nulls`, `inspect_query`)
+//! shared by `parse::query` and `parse::read_model`.
+
+use crate::diag::ParseResult;
+use crate::ir;
+use crate::parse::{self, ArgumentGateResult};
+use crate::ruby_value;
+
+/// Applies one already-gated option call (`offset`, `cursor`, `authorize`, `nulls`,
+/// `inspect_query`) onto `options`; `context` only words diagnostics.
+pub fn apply(
+    file: &str,
+    line: usize,
+    word: &str,
+    args: &ArgumentGateResult,
+    options: &mut ir::QueryOptions,
+) -> ParseResult<()> {
+    match word {
+        // The value keeps its rendered text whatever its lexical kind. `on:` is only a
+        // recognized named argument in ReadModel context (ADR 0055); the argument gate has
+        // already refused an undeclared one, so `named_constant` finds nothing for Query.
+        "offset" => {
+            let target = parse::named_constant(args, "on").map(crate::build::naming::demodulise);
+            options.offset = Some(ir::OffsetSpec {
+                value: rendered_positional(args, 1),
+                target,
+            });
+        }
+        "cursor" => options.cursor = Some(rendered_positional(args, 1)),
+        // Both fields are bare names, without the leading colon.
+        "authorize" => {
+            let policy = parse::positional_symbol(file, line, word, args, 1)?;
+            let tenant = parse::named_symbol(args, "tenant");
+            options.authorization = Some(ir::AuthorizationSpec { policy, tenant });
+        }
+        // `nulls :native` is the default, so it leaves `null_semantics` unset.
+        "nulls" => {
+            let mode = parse::positional_symbol(file, line, word, args, 1)?;
+            if mode != "native" {
+                options.null_semantics = Some(mode);
+            }
+        }
+        // `mode` is the one optional positional; it defaults to `:sql`.
+        "inspect_query" => {
+            let mode = match args.positional.iter().find(|(idx, _)| *idx == 1) {
+                Some((_, text)) => text.trim().trim_start_matches(':').to_string(),
+                None => "sql".to_string(),
+            };
+            options.inspection = Some(mode);
+        }
+        other => unreachable!("build::query_options::apply called with an unhandled word: {other}"),
+    }
+    Ok(())
+}
+
+fn rendered_positional(args: &ArgumentGateResult, at: usize) -> String {
+    args.positional
+        .iter()
+        .find(|(idx, _)| *idx == at)
+        .map(|(_, text)| rendered(text))
+        .unwrap_or_default()
+}
+
+fn rendered(raw: &str) -> String {
+    ruby_value::render(&ruby_value::read(raw.trim()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args_with(positional: Vec<(usize, &str)>, named: Vec<(&str, &str)>) -> ArgumentGateResult {
+        ArgumentGateResult {
+            positional: positional
+                .into_iter()
+                .map(|(i, t)| (i, t.to_string()))
+                .collect(),
+            named: named
+                .into_iter()
+                .map(|(n, v)| (n.to_string(), v.to_string()))
+                .collect(),
+        }
+    }
+
+    #[test]
+    fn drops_the_default_null_semantics_mode() {
+        let mut options = ir::QueryOptions::default();
+        let args = args_with(vec![(1, ":native")], vec![]);
+        apply("f.bluebook", 1, "nulls", &args, &mut options).unwrap();
+        assert_eq!(options.null_semantics, None);
+    }
+
+    #[test]
+    fn defaults_inspect_query_to_sql_with_no_argument() {
+        let mut options = ir::QueryOptions::default();
+        let args = args_with(vec![], vec![]);
+        apply("f.bluebook", 1, "inspect_query", &args, &mut options).unwrap();
+        assert_eq!(options.inspection, Some("sql".to_string()));
+    }
+}

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

@@ -0,0 +1,94 @@
+//! Read model `include` head gathering: pluralization, dedup, and the `many:`/`as:`
+//! shape of each aggregate head.
+
+use crate::build::naming;
+use crate::diag::{Diagnostic, ParseResult};
+use crate::ir;
+
+/// Builds the `aggregate_heads` for a read model's `include Type[, as: name]` lines.
+///
+/// A head is `many` unless it names `reference_target`; `output` defaults to the
+/// plural (many) or singular snake name. Refuses two includes projecting the same name.
+pub fn aggregate_heads(
+    file: &str,
+    line: usize,
+    read_model_name: &str,
+    includes: &[(String, Option<String>)],
+    reference_target: Option<&str>,
+) -> ParseResult<Vec<ir::AggregateHead>> {
+    let mut heads: Vec<ir::AggregateHead> = Vec::new();
+
+    for (target, as_name) in includes {
+        let many = Some(target.as_str()) != reference_target;
+        let output = as_name.clone().unwrap_or_else(|| {
+            if many {
+                naming::plural(&naming::snake(target))
+            } else {
+                naming::snake(target)
+            }
+        });
+
+        if heads.iter().any(|head| head.as_name == output) {
+            return Err(Diagnostic::new(
+                file,
+                line,
+                format!("{read_model_name} already projects {output}"),
+            ));
+        }
+
+        heads.push(ir::AggregateHead {
+            aggregate: target.clone(),
+            as_name: output,
+            many,
+        });
+    }
+
+    Ok(heads)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn keeps_an_explicit_as_name_verbatim() {
+        let heads = aggregate_heads(
+            "f.bluebook",
+            1,
+            "WidgetSummary",
+            &[("Widget".to_string(), Some("widget".to_string()))],
+            None,
+        )
+        .unwrap();
+        assert_eq!(heads[0].as_name, "widget");
+    }
+
+    #[test]
+    fn a_reference_target_naming_no_included_head_leaves_every_head_many() {
+        let heads = aggregate_heads(
+            "f.bluebook",
+            1,
+            "ComplianceDashboard",
+            &[("CardPayment".to_string(), None)],
+            Some("Account"),
+        )
+        .unwrap();
+        assert!(heads[0].many, "no included head equals the reference target, so all stay many");
+    }
+
+    #[test]
+    fn refuses_two_includes_projecting_the_same_name() {
+        let err = aggregate_heads(
+            "f.bluebook",
+            1,
+            "Dup",
+            &[
+                ("Widget".to_string(), Some("thing".to_string())),
+                ("Gadget".to_string(), Some("thing".to_string())),
+            ],
+            None,
+        )
+        .unwrap_err();
+        assert!(err.message.contains("already projects thing"));
+    }
+}

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

@@ -0,0 +1,32 @@
+//! Reference and relationship attribute minting.
+
+use crate::ir;
+
+/// Mints the attribute for a `reference_to`: `attribute(as || snake(target), Reference(target))`,
+/// with no `_id` suffix.
+pub fn reference_attribute(target: &str, as_name: Option<&str>, optional: bool) -> ir::Attribute {
+    let target = crate::build::naming::demodulise(target);
+    let name = as_name
+        .map(|s| s.to_string())
+        .unwrap_or_else(|| crate::build::naming::snake(&target));
+    ir::Attribute {
+        name,
+        type_name: format!("Reference<{target}>"),
+        list: false,
+        optional,
+        ..Default::default()
+    }
+}
+
+pub fn relationship_attribute(
+    target: &str,
+    kind: &str,
+    as_name: Option<&str>,
+    optional: bool,
+    list: bool,
+) -> ir::Attribute {
+    let mut attribute = reference_attribute(target, as_name, optional);
+    attribute.list = list;
+    attribute.relationship = Some(kind.to_string());
+    attribute
+}

data/rust/parser/src/canonical.rs

@@ -0,0 +1,114 @@
+//! Source-body slicing and whitespace collapse, mirroring Ruby's `CanonicalForm`.
+//! Hand-mirrored from projection.json: a third rule there needs a matching rule here.
+
+/// Slices the raw source between two byte offsets, before any normalisation.
+pub fn slice(source: &str, start: usize, end: usize) -> &str {
+    &source[start..end]
+}
+
+/// Canonical text of a captured body: whitespace runs collapse to one space, `.length`
+/// becomes `.size`, then trim. Quoted runs pass through untouched, matching Ruby.
+pub fn apply(source: &str) -> String {
+    let collapsed = map_outside_strings(source, collapse_whitespace);
+    let replaced = map_outside_strings(&collapsed, |run| replace_word_boundary(run, ".length", ".size"));
+    replaced.trim().to_string()
+}
+
+/// Applies `transform` to the unquoted runs of `text` and copies quoted runs verbatim;
+/// a backslash escapes the next character inside a quoted run.
+fn map_outside_strings(text: &str, transform: impl Fn(&str) -> String) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut plain = String::new();
+    let mut chars = text.chars().peekable();
+    while let Some(ch) = chars.next() {
+        if ch == '"' || ch == '\'' {
+            out.push_str(&transform(&plain));
+            plain.clear();
+            out.push(ch);
+            let quote = ch;
+            while let Some(inner) = chars.next() {
+                out.push(inner);
+                if inner == '\\' {
+                    if let Some(escaped) = chars.next() {
+                        out.push(escaped);
+                    }
+                    continue;
+                }
+                if inner == quote {
+                    break;
+                }
+            }
+        } else {
+            plain.push(ch);
+        }
+    }
+    out.push_str(&transform(&plain));
+    out
+}
+
+fn collapse_whitespace(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut in_run = false;
+    for ch in text.chars() {
+        if ch.is_whitespace() {
+            if !in_run {
+                out.push(' ');
+                in_run = true;
+            }
+        } else {
+            out.push(ch);
+            in_run = false;
+        }
+    }
+    out
+}
+
+/// Replaces `token` with `replacement` unless another identifier character follows it.
+fn replace_word_boundary(text: &str, token: &str, replacement: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let bytes = text.as_bytes();
+    let mut i = 0;
+    while i < bytes.len() {
+        if text[i..].starts_with(token) {
+            let after = i + token.len();
+            let boundary_ok = match text[after..].chars().next() {
+                None => true,
+                Some(c) => !(c.is_alphanumeric() || c == '_'),
+            };
+            if boundary_ok {
+                out.push_str(replacement);
+                i = after;
+                continue;
+            }
+        }
+        let ch = text[i..].chars().next().unwrap();
+        out.push(ch);
+        i += ch.len_utf8();
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn collapses_runs_of_whitespace() {
+        assert_eq!(apply("balance   >=\n  amount"), "balance >= amount");
+    }
+
+    #[test]
+    fn replaces_length_at_a_word_boundary_only() {
+        assert_eq!(apply("items.length"), "items.size");
+        // `lengthy` must not become `sizey`.
+        assert_eq!(apply("lengthy"), "lengthy");
+    }
+
+    #[test]
+    fn slices_the_exact_source_span() {
+        let source = "given(\"ok\") { balance >= amount }";
+        let start = source.find('{').unwrap();
+        let end = source.rfind('}').unwrap() + 1;
+        assert_eq!(slice(source, start, end), "{ balance >= amount }");
+    }
+}

data/rust/parser/src/diag.rs

@@ -0,0 +1,55 @@
+//! Diagnostics: the one shape every refusal takes.
+//!
+//! There is no lenient mode: an unrecognized construct is always a hard error, never skipped.
+
+use std::fmt;
+
+#[derive(Debug, Clone)]
+pub struct Diagnostic {
+    pub file: String,
+    pub line: usize,
+    pub message: String,
+    /// The legal alternatives at this point; empty when there is nothing more specific.
+    pub expected: Vec<String>,
+}
+
+impl Diagnostic {
+    pub fn new(file: impl Into<String>, line: usize, message: impl Into<String>) -> Self {
+        Self {
+            file: file.into(),
+            line,
+            message: message.into(),
+            expected: Vec::new(),
+        }
+    }
+
+    pub fn with_expected(mut self, expected: Vec<String>) -> Self {
+        self.expected = expected;
+        self
+    }
+
+    /// Diagnostic for a construct the grammar admits but this parser does not implement yet.
+    pub fn not_yet_implemented(
+        file: impl Into<String>,
+        line: usize,
+        what: impl fmt::Display,
+    ) -> Self {
+        Self::new(
+            file,
+            line,
+            format!("not yet implemented: {what} (Stage 1 — see spec/parser_coverage_spec.rb)"),
+        )
+    }
+}
+
+impl fmt::Display for Diagnostic {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}:{}: {}", self.file, self.line, self.message)?;
+        if !self.expected.is_empty() {
+            write!(f, " (expected one of: {})", self.expected.join(", "))?;
+        }
+        Ok(())
+    }
+}
+
+pub type ParseResult<T> = Result<T, Diagnostic>;