hecks 2.9.0 → 3.0.1

data/rust/parser/src/parse/file.rs

@@ -0,0 +1,67 @@
+//! The outermost gate — `File` context, the three words that begin any
+//! file this parser reads: `bluebook`, `hecksagon`, `world`. Real for
+//! Stage 1, same as every nested line: shape (lex.rs), word, body, and
+//! argument gates (parse/mod.rs) all run here exactly as they do one level
+//! down — nothing about being the top of the file is special-cased.
+
+use crate::diag::{Diagnostic, ParseResult};
+use crate::keywords::KeywordRow;
+use crate::lex::{self, Call, LineShape, SourceLine};
+use crate::ruby_value;
+
+pub fn parse_header<'a>(
+    file: &str,
+    lines: &[SourceLine],
+    pos: &mut usize,
+) -> ParseResult<(&'a KeywordRow, Call, usize)> {
+    let line = *lines.get(*pos).ok_or_else(|| {
+        Diagnostic::new(file, 0, "empty file — expected bluebook/hecksagon/world")
+    })?;
+    let shape = lex::classify(file, &line)?;
+    *pos += 1;
+
+    match shape {
+        LineShape::End => Err(Diagnostic::new(
+            file,
+            line.number,
+            "unexpected 'end' at the top of the file",
+        )),
+        LineShape::Call(call) => {
+            let candidates = super::word_gate(file, &call.word, "File", line.number)?;
+            let row = super::body_gate(file, &candidates, &call.opener, line.number, &call.word)?;
+            super::argument_gate(file, &call.word, "File", &call.args, line.number)?;
+            Ok((row, call, line.number))
+        }
+    }
+}
+
+/// The header's own declared name — `bluebook "Pizzas"`'s first
+/// positional argument (the `text`-kind row, `at: "1"`). Read back through
+/// ruby_value the same way any other captured text argument is.
+pub fn header_name(call: &Call) -> Option<String> {
+    let first = ruby_value::split_items(&call.args).into_iter().next()?;
+    match ruby_value::read(&first) {
+        ruby_value::Value::Str(name) => Some(name),
+        _ => None,
+    }
+}
+
+/// The header's own optional `version:` named argument — `Hecks.bluebook
+/// "Banking", version: "v1" do`, `bluebook`'s own `named: "version"` row
+/// (`context: "File"`). Not exercised by pizzas.bluebook/the framework
+/// trio/the grammar chapters (none pins a version) — confirmed real by
+/// banking.bluebook, the first real corpus member to.
+pub fn header_version(call: &Call) -> Option<String> {
+    ruby_value::split_items(&call.args)
+        .into_iter()
+        .find_map(|segment| {
+            let (name, value) = super::as_named(&segment)?;
+            if name != "version" {
+                return None;
+            }
+            Some(match ruby_value::read(value.trim()) {
+                ruby_value::Value::Str(s) => s,
+                other => ruby_value::to_s(&other),
+            })
+        })
+}

data/rust/parser/src/parse/hecksagon.rs

@@ -0,0 +1,231 @@
+//! The `Hecksagon` construct: a `.hecksagon` file's `port` blocks and `uses_framework` words.
+//! Adapter binds (`persisted_by`, `projected_by`, `subscribe`) are shape-matched and dropped.
+
+use super::domain_port;
+use super::policy;
+use crate::diag::{Diagnostic, ParseResult};
+use crate::ir;
+use crate::lex::{self, LineShape, Opener, SourceLine};
+
+pub fn not_implemented(file: &str, line: usize, word: &str) -> Diagnostic {
+    Diagnostic::not_yet_implemented(file, line, format!("Hecksagon.{word}"))
+}
+
+/// Applies a `.hecksagon` body onto an already-built `ir::Bluebook`, attaching
+/// aggregate-scoped ports to the aggregates the sibling `.bluebook` registered.
+///
+/// `uses_framework_names` and `vendored_bluebook_names` collect each argument in file order
+/// for `hecks-parse resolve`; `ir.json` itself carries neither.
+///
+/// `require_matching_aggregate` is `false` for resolve, which never sees a `.bluebook`, so an
+/// aggregate-scoped `port` skips the attach step instead of failing the lookup.
+pub fn apply(
+    file: &str,
+    lines: &[SourceLine],
+    pos: &mut usize,
+    bluebook: &mut ir::Bluebook,
+    uses_framework_names: &mut Vec<String>,
+    vendored_bluebook_names: &mut Vec<String>,
+    require_matching_aggregate: bool,
+) -> ParseResult<()> {
+    loop {
+        let line = *lines.get(*pos).ok_or_else(|| {
+            let last = lines.last().map(|l| l.number).unwrap_or(0);
+            Diagnostic::new(
+                file,
+                last,
+                "unexpected end of file — still inside Hecksagon",
+            )
+        })?;
+
+        if line.text == "end" {
+            *pos += 1;
+            return Ok(());
+        }
+
+        if let Some((receiver, rest)) = lex::strip_aggregate_receiver(line.text) {
+            *pos += 1;
+            apply_aggregate_qualified(
+                file,
+                lines,
+                pos,
+                line.number,
+                receiver,
+                rest,
+                bluebook,
+                require_matching_aggregate,
+            )?;
+            continue;
+        }
+
+        // Bare root adapter-bind (`persisted_by "Heki"`): any word outside Hecksagon's closed
+        // words is shape-matched and dropped, bypassing the closed-vocabulary `word_gate`.
+        if let LineShape::Call(call) = lex::classify(file, &line)? {
+            if !matches!(
+                call.word.as_str(),
+                "port" | "subscribe" | "uses_framework" | "uses_embryonaut_bluebook" | "attaches" | "translates" | "bounded" | "end"
+            ) {
+                *pos += 1;
+                if matches!(call.opener, Opener::DoBlock { .. }) {
+                    skip_dropped_body(file, lines, pos)?;
+                }
+                continue;
+            }
+        }
+
+        match super::next_line(file, lines, pos, "Hecksagon")? {
+            None => return Ok(()),
+            Some(gated) => match gated.row.word {
+                // A bare root port belongs to the chapter, not an aggregate; validated, then
+                // discarded (`IR::Bluebook#to_h` has no `ports:` key).
+                "port" => {
+                    let name =
+                        super::positional_text(file, gated.line.number, "port", &gated.args, 1)?;
+                    let _ = domain_port::parse_body(file, lines, pos, &name, None)?;
+                }
+                // A cross-domain reaction wired here instead of the `.bluebook`; builds the same
+                // `ir::Policy`, pushed after every policy the sibling file contributed.
+                "translates" => {
+                    let name = super::positional_text(
+                        file,
+                        gated.line.number,
+                        "translates",
+                        &gated.args,
+                        1,
+                    )?;
+                    let built = policy::parse_body(file, lines, pos, &name)?;
+                    bluebook.policies.push(built);
+                }
+                // Gated, then collected; `ir.json` carries no `uses_framework` key.
+                "uses_framework" => {
+                    uses_framework_names.push(super::positional_text(
+                        file,
+                        gated.line.number,
+                        "uses_framework",
+                        &gated.args,
+                        1,
+                    )?);
+                }
+                // Collected like `uses_framework`; a binding fact, absent from `ir.json`.
+                "uses_embryonaut_bluebook" => {
+                    vendored_bluebook_names.push(super::positional_text(
+                        file,
+                        gated.line.number,
+                        "uses_embryonaut_bluebook",
+                        &gated.args,
+                        1,
+                    )?);
+                }
+                "subscribe" => {}
+                // A chapter the gem carries, attached by name (ADR 0080); only the Ruby runtime
+                // loads it, so its one argument is checked and then dropped like `subscribe`.
+                "attaches" => {
+                    super::positional_text(file, gated.line.number, "attaches", &gated.args, 1)?;
+                }
+                // Consumer-owned bounded-context mark; a wiring fact, dropped like `subscribe`.
+                "bounded" => {}
+                _ => {
+                    return Err(super::not_built_yet(
+                        "Hecksagon",
+                        gated.row,
+                        file,
+                        gated.line.number,
+                        &gated.call.word,
+                    ))
+                }
+            },
+        }
+    }
+}
+
+/// `<Domain>::<Aggregate>.<verb>`: `port` attaches a port to the named aggregate; any other
+/// verb is a generic adapter-bind, shape-matched and dropped.
+fn apply_aggregate_qualified(
+    file: &str,
+    lines: &[SourceLine],
+    pos: &mut usize,
+    line_number: usize,
+    receiver: &str,
+    rest: &str,
+    bluebook: &mut ir::Bluebook,
+    require_matching_aggregate: bool,
+) -> ParseResult<()> {
+    let synthetic = SourceLine {
+        number: line_number,
+        text: rest,
+    };
+    let shape = lex::classify(file, &synthetic)?;
+    let call = match shape {
+        LineShape::Call(call) => call,
+        LineShape::End => {
+            return Err(Diagnostic::new(
+                file,
+                line_number,
+                "unexpected 'end' right after an aggregate-qualified receiver",
+            ))
+        }
+    };
+
+    if call.word != "port" {
+        if matches!(call.opener, Opener::DoBlock { .. }) {
+            skip_dropped_body(file, lines, pos)?;
+        }
+        return Ok(());
+    }
+
+    let candidates = super::word_gate(file, "port", "Hecksagon", line_number)?;
+    let row = super::body_gate(file, &candidates, &call.opener, line_number, "port")?;
+    let args = super::argument_gate(file, row.word, "Hecksagon", &call.args, line_number)?;
+    let port_name = super::positional_text(file, line_number, "port", &args, 1)?;
+
+    let aggregate_name = receiver.rsplit("::").next().unwrap_or(receiver);
+    let built = domain_port::parse_body(file, lines, pos, &port_name, Some(aggregate_name))?;
+
+    let found = bluebook
+        .aggregates
+        .iter_mut()
+        .find(|a| a.name == aggregate_name);
+    match found {
+        Some(aggregate) => aggregate.ports.push(built),
+        None if require_matching_aggregate => {
+            return Err(Diagnostic::new(
+                file,
+                line_number,
+                format!("{receiver} declares no such aggregate — a port needs one to belong to"),
+            ));
+        }
+        // Resolve's accumulator has no aggregates; the body was gated, so there is nothing to
+        // attach.
+        None => {}
+    }
+    Ok(())
+}
+
+/// Skips a dropped adapter-bind's `do ... end` body, depth-tracked through the shape gate so
+/// a malformed line inside still refuses.
+fn skip_dropped_body(file: &str, lines: &[SourceLine], pos: &mut usize) -> ParseResult<()> {
+    let mut depth = 1;
+    while depth > 0 {
+        let line = *lines.get(*pos).ok_or_else(|| {
+            let last = lines.last().map(|l| l.number).unwrap_or(0);
+            Diagnostic::new(
+                file,
+                last,
+                "unexpected end of file while skipping a dropped adapter-bind body",
+            )
+        })?;
+        *pos += 1;
+
+        if line.text == "end" {
+            depth -= 1;
+            continue;
+        }
+
+        if let LineShape::Call(call) = lex::classify(file, &line)? {
+            if matches!(call.opener, Opener::DoBlock { .. }) {
+                depth += 1;
+            }
+        }
+    }
+    Ok(())
+}

data/rust/parser/src/parse/lifecycle.rs

@@ -0,0 +1,162 @@
+//! The `Lifecycle` construct: a fold onto the enclosing Aggregate or Entity, not its own category.
+//! Parses `transition` lines and seals the owner's commands against the lifecycle field.
+
+use crate::diag::{Diagnostic, ParseResult};
+use crate::ir;
+use crate::lex::SourceLine;
+use crate::ruby_value;
+
+pub fn not_implemented(file: &str, line: usize, word: &str) -> Diagnostic {
+    Diagnostic::not_yet_implemented(file, line, format!("Lifecycle.{word}"))
+}
+
+// `field` and `default` come from the header line, which the enclosing context has already read.
+pub fn parse_body(
+    file: &str,
+    lines: &[SourceLine],
+    pos: &mut usize,
+    field: &str,
+    default: &str,
+) -> ParseResult<ir::Lifecycle> {
+    let mut lifecycle = ir::Lifecycle {
+        field: field.to_string(),
+        default: default.to_string(),
+        transitions: Vec::new(),
+    };
+
+    loop {
+        let Some(gated) = super::next_line(file, lines, pos, "Lifecycle")? else {
+            refuse_ambiguity(file, *pos, &lifecycle)?;
+            return Ok(lifecycle);
+        };
+
+        match gated.row.word {
+            "transition" => {
+                let line = gated.line.number;
+                let pair_text = super::named_raw(&gated.args, "=>").ok_or_else(|| {
+                    Diagnostic::new(file, line, "'transition' names no 'command => state' pair")
+                })?;
+                let (command_raw, to_state_raw) = super::split_top_level_rocket(pair_text);
+                let command = text_value(command_raw);
+                let to_state = text_value(to_state_raw);
+                let from_states = match super::named_raw(&gated.args, "from") {
+                    None => vec![None],
+                    Some(raw) => from_values(raw).into_iter().map(Some).collect(),
+                };
+
+                for from_state in from_states {
+                    lifecycle.transitions.push(ir::StateTransitionRow {
+                        command: command.clone(),
+                        to_state: to_state.clone(),
+                        from_state,
+                    });
+                }
+            }
+            _ => {
+                return Err(super::not_built_yet(
+                    "Lifecycle",
+                    gated.row,
+                    file,
+                    gated.line.number,
+                    &gated.call.word,
+                ))
+            }
+        }
+    }
+}
+
+// Refuses one command reaching two targets from overlapping `from:` states (`None` overlaps all).
+// Rows are already expanded one per `from:` state. A `from:` naming an undeclared state is left
+// to `hecks model_check`, since a bluebook may exhibit it on purpose. Wording matches Ruby's.
+fn refuse_ambiguity(file: &str, line: usize, lifecycle: &ir::Lifecycle) -> ParseResult<()> {
+    let mut seen: Vec<(&str, Option<&str>, &str)> = Vec::new();
+    for row in &lifecycle.transitions {
+        let from = row.from_state.as_deref();
+        let earlier = seen.iter().find(|(c, f, t)| {
+            *c == row.command && *t != row.to_state && (f.is_none() || from.is_none() || *f == from)
+        });
+        if let Some((_, _, earlier_target)) = earlier {
+            return Err(Diagnostic::new(
+                file,
+                line,
+                format!(
+                    "lifecycle :{} declares two transitions for {:?} from the same state (=> {:?} and => {:?}) — \
+                     which one fires would be declaration order; give them disjoint from: states",
+                    lifecycle.field, row.command, earlier_target, row.to_state
+                ),
+            ));
+        }
+        seen.push((&row.command, from, &row.to_state));
+    }
+    Ok(())
+}
+
+// Refuses a `sets` on the lifecycle field and a `from:` on an owner with no lifecycle.
+// `owner` is the aggregate or entity name; `line` is the owner's own.
+pub fn seal_commands(
+    file: &str,
+    line: usize,
+    owner: &str,
+    lifecycle: Option<&ir::Lifecycle>,
+    commands: &[ir::Command],
+) -> ParseResult<()> {
+    for command in commands {
+        if let Some(lifecycle) = lifecycle {
+            for mutation in &command.mutations {
+                let target = match mutation {
+                    ir::Mutation::Append { target, .. } => target,
+                    ir::Mutation::Other { target, .. } => target,
+                    _ => continue,
+                };
+                if *target == lifecycle.field {
+                    return Err(Diagnostic::new(
+                        file,
+                        line,
+                        format!(
+                            "{owner}.{} sets {target}, {owner}'s lifecycle field — a lifecycle field moves only by \
+                             transition; declare one instead of setting it",
+                            command.name
+                        ),
+                    ));
+                }
+            }
+        }
+        let Some(from) = &command.from else { continue };
+        let froms: Vec<&String> = match from {
+            ir::CommandFrom::Single(s) => vec![s],
+            ir::CommandFrom::Multiple(v) => v.iter().collect(),
+        };
+        if lifecycle.is_none() {
+            return Err(Diagnostic::new(
+                file,
+                line,
+                format!(
+                    "{owner}.{} guards from: {:?}, but {owner} declares no lifecycle — from: checks a lifecycle \
+                     field, and there is none here to check",
+                    command.name,
+                    froms.iter().map(|s| s.as_str()).collect::<Vec<_>>()
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+fn text_value(raw: &str) -> String {
+    match ruby_value::read(raw.trim()) {
+        ruby_value::Value::Str(s) => s,
+        other => ruby_value::to_s(&other),
+    }
+}
+
+// Reads `from: "a"` as one state and `from: ["a", "b"]` as a list.
+fn from_values(raw: &str) -> Vec<String> {
+    let trimmed = raw.trim();
+    if trimmed.starts_with('[') && trimmed.ends_with(']') {
+        return ruby_value::split_items(&trimmed[1..trimmed.len() - 1])
+            .into_iter()
+            .map(|item| text_value(&item))
+            .collect();
+    }
+    vec![text_value(trimmed)]
+}