hecks 4.0.0 → 6.0.0

data/rust/lsp/README.md

@@ -12,7 +12,7 @@ is setup + roadmap.
 - `initialize` / `initialized` / `shutdown` / `exit`
 - `textDocument/didOpen` / `didChange` (full sync) / `didSave` / `didClose`
 - On every one of those, stages the buffer to a scratch file and runs
-  `hecks-parse chapter --chapter <Name> <scratch file>`, where `<Name>`
+  `hecks-parse bluebook --bluebook <Name> <scratch file>`, where `<Name>`
   is scraped from the buffer's own `Hecks.bluebook "Name"` /
   `Hecks.hecksagon "Name"` line. A clean parse publishes an empty
   diagnostics list; a failure publishes exactly one `Diagnostic`
@@ -34,10 +34,18 @@ is setup + roadmap.
   cursor (a `reference_to Customer` / `belongs_to Account` usage) to
   wherever that aggregate/entity/value_object is actually declared,
   first in the same file, then across sibling `.bluebook`/`.hecksagon`
-  files in the same directory (a chapter routinely spans several files —
-  `parse::chapter`'s own header — and the declaration is often in one of
+  files in the same directory (a bluebook routinely spans several files —
+  `parse::bluebook`'s own header — and the declaration is often in one of
   them, not the file doing the referencing).
 
+- **Files written as sentences** (a first line of `Domain: <name>`; see ADR 0131) get two
+  things the Ruby form does not. A refusal names the column it went wrong at, so the squiggle
+  starts there instead of underlining the line. And `textDocument/completion` offers the
+  sentences legal at the cursor: the server asks `hecks-parse complete <file> --line N --col N`,
+  which reads the same phrase table the parser matches against, and returns each sentence as an
+  editor snippet with a tab stop for every fill-in. The edit replaces what has been typed on the
+  line, from the indent to the cursor.
+
 ## What it doesn't do yet
 
 - **`documentSymbol`/`definition` are text-scanned, not grammar-verified.**
@@ -49,34 +57,27 @@ is setup + roadmap.
   targets (`outline::is_reference_target`) — a `command`/`query` name
   is never referenced by a bare identifier elsewhere in the corpus the
   way a type name is, so it isn't one.
-- **No column info.** `rust/parser`'s own `Diagnostic` only tracks a
-  line, so every diagnostic underlines the whole line. Real squiggle
-  precision needs `rust/parser` to track columns first — nothing to fix
-  here until then.
-- **No completion, hover, or go-to-definition.** The parser's four gates
-  (`rust/parser/src/parse/mod.rs`: shape → word → body → argument)
-  already encode "what's legal at this point in the grammar" — that's
-  exactly what a completion engine needs, but it's not exposed as
-  anything this crate can call today. The clean way to add it, in
-  keeping with `rust/parser` staying a bin-only, subprocess-only sibling
-  (see `diagnostics.rs`'s header): add a new `hecks-parse` subcommand
-  (e.g. `hecks-parse complete --chapter <Name> <file> --line N --col N`)
-  that runs the same gates up to the cursor and prints the legal next
-  words as JSON, the same shape `run_coverage` already prints its list
-  in. Once that exists, wiring `textDocument/completion` here is a small
-  addition, not a redesign.
+- **No column info for the Ruby form.** Its gates track a line only, so a refusal in a
+  Ruby-shaped file underlines the whole line. Only the sentence form names a column.
+- **No completion for the Ruby form, and no hover.** The Ruby-shaped gates
+  (`rust/parser/src/parse/mod.rs`: shape → word → body → argument) encode "what's legal here"
+  but expose it to nothing this crate can call. `hecks-parse complete` does that for the
+  sentence form only, from its phrase table; a Ruby-form equivalent would run the gates up to
+  the cursor the same way.
+- **Completion offers sentences, not names.** It does not yet suggest the fields, types or
+  states in scope for a fill-in; the parser's refusal lists them after the fact.
 - **Only one diagnostic per document.** Inherited from `rust/parser`'s
-  own fail-fast design (`parse::chapter`'s doc comment: "Stops at the
+  own fail-fast design (`parse::bluebook`'s doc comment: "Stops at the
   FIRST diagnostic"). If that ever becomes a `Vec<Diagnostic>`, this
   crate's `diagnostics::run` only needs to return `Vec<FileDiagnostic>`
   instead of `Option<FileDiagnostic>` — `main.rs` already publishes
   whatever list it's handed.
-- **Single-file chapters only.** A chapter split across multiple
+- **Single-file bluebooks only.** A bluebook split across multiple
   `.bluebook` files, or paired with a `.hecksagon` file
-  (`parse::chapter`'s own header describes both), is only ever checked
+  (`parse::bluebook`'s own header describes both), is only ever checked
   one file at a time here. Fine for every example under `examples/*/`
   today; would need this crate to also track a project's file layout
-  (which files share a chapter name) to do better.
+  (which files share a bluebook name) to do better.
 
 ## Building it
 
@@ -119,13 +120,12 @@ vim.api.nvim_create_autocmd("FileType", {
 **VS Code**: `editors/vscode/` (repo root) is a minimal real extension —
 see its own README for build/install steps. Not published to the
 marketplace; installed locally (copy into your extensions directory, or
-F5 an Extension Development Host). It contributes no syntax highlighting
-grammar (a separate gap — see the top-level tooling report), just the
-language client wiring.
+F5 an Extension Development Host). Its syntax highlighting is Ruby's own grammar
+under the extension's scope name (see its README), plus the language client wiring.
 
 ## Testing it without an editor
 
-`cargo test` covers the pure functions (`chapter_name` extraction,
+`cargo test` covers the pure functions (`declaration_name` extraction,
 `Diagnostic` line parsing, JSON round-tripping). For a full stdio
 round-trip, speak Content-Length-framed JSON-RPC to the process
 directly — `initialize` → `initialized` → `textDocument/didOpen` with a

data/rust/lsp/src/diagnostics.rs

@@ -1,29 +1,33 @@
-//! Maps the first error from `hecks-parse chapter` on a buffer to an LSP diagnostic.
+//! Maps the first error from `hecks-parse bluebook` on a buffer to an LSP diagnostic.
 //! The parser reports a file and line only, so a diagnostic covers the whole line.
 
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
+/// The parser's refusal of a buffer, in the terms an editor needs.
 pub struct FileDiagnostic {
     pub line: usize, // 1-indexed
+    /// The 1-indexed character column the problem starts at; `None` when the parser refused
+    /// the line as a whole, as it does for every file in the Ruby form.
+    pub column: Option<usize>,
     pub message: String,
     pub expected: Vec<String>,
     /// True when the grammar admits the construct but the parser does not build it yet.
     pub not_yet_implemented: bool,
 }
 
-/// Runs `hecks-parse chapter` on the file at `path` and returns at most one diagnostic.
+/// Runs `hecks-parse bluebook` on the file at `path` and returns at most one diagnostic.
 ///
-/// `Ok(None)` means the parse succeeded or the buffer declares no chapter.
+/// `Ok(None)` means the parse succeeded or the buffer declares no bluebook.
 /// Runs the parser as a subprocess because `rust/parser` ships only a binary target.
 pub fn run(hecks_parse: &Path, path: &Path, text: &str) -> Result<Option<FileDiagnostic>, String> {
-    let Some(name) = chapter_name(text) else {
+    let Some(name) = declaration_name(text) else {
         return Ok(None);
     };
 
     let output = Command::new(hecks_parse)
-        .arg("chapter")
-        .arg("--chapter")
+        .arg("bluebook")
+        .arg("--bluebook")
         .arg(&name)
         .arg(path)
         .output()
@@ -44,10 +48,25 @@ pub fn run(hecks_parse: &Path, path: &Path, text: &str) -> Result<Option<FileDia
     Ok(parse_diagnostic_line(first_line, path))
 }
 
-/// Finds the name in the first `Hecks.bluebook "Name"` or `Hecks.hecksagon "Name"` line.
-// Hand-scanned because this crate takes no dependencies.
-fn chapter_name(text: &str) -> Option<String> {
+/// Finds the name in the first `Hecks.bluebook "Name"` or `Hecks.hecksagon "Name"` line, or in
+/// the `Domain: name` line of a file written as sentences, whose words are capitalised and joined.
+/// Hand-scanned because this crate takes no dependencies.
+pub fn declaration_name(text: &str) -> Option<String> {
     for line in text.lines() {
+        if let Some(after) = line.trim_start().strip_prefix("Domain:") {
+            let name: String = after
+                .split_whitespace()
+                .map(|word| {
+                    let mut chars = word.chars();
+                    chars.next().map_or_else(String::new, |first| {
+                        first.to_uppercase().collect::<String>() + chars.as_str()
+                    })
+                })
+                .collect();
+            if !name.is_empty() {
+                return Some(name);
+            }
+        }
         for needle in ["Hecks.bluebook \"", "Hecks.hecksagon \""] {
             if let Some(after) = line.trim_start().strip_prefix(needle) {
                 if let Some(end) = after.find('"') {
@@ -66,6 +85,15 @@ fn parse_diagnostic_line(line: &str, path: &Path) -> Option<FileDiagnostic> {
     let rest = line.strip_prefix(&prefix)?;
     let (line_no, rest) = rest.split_once(':')?;
     let line_no: usize = line_no.trim().parse().ok()?;
+    // A file written as sentences also names the column: `<file>:<line>:<column>: <message>`.
+    let (column, rest) = match rest.split_once(':') {
+        Some((digits, after))
+            if !digits.is_empty() && digits.chars().all(|c| c.is_ascii_digit()) =>
+        {
+            (digits.parse().ok(), after)
+        }
+        _ => (None, rest),
+    };
     let rest = rest.strip_prefix(' ').unwrap_or(rest);
 
     let (message, expected) = match rest.rfind(" (expected one of: ") {
@@ -80,6 +108,7 @@ fn parse_diagnostic_line(line: &str, path: &Path) -> Option<FileDiagnostic> {
 
     Some(FileDiagnostic {
         line: line_no,
+        column,
         not_yet_implemented: message.starts_with("not yet implemented:"),
         message,
         expected,
@@ -126,20 +155,51 @@ mod tests {
     use super::*;
 
     #[test]
-    fn finds_a_bluebook_chapter_name() {
+    fn finds_a_bluebook_bluebook_name() {
         let text = "Hecks.bluebook \"Pizzas\" do\nend\n";
-        assert_eq!(chapter_name(text), Some("Pizzas".to_string()));
+        assert_eq!(declaration_name(text), Some("Pizzas".to_string()));
     }
 
     #[test]
-    fn finds_a_hecksagon_chapter_name_when_indented() {
+    fn finds_a_hecksagon_bluebook_name_when_indented() {
         let text = "  Hecks.hecksagon \"Banking\" do\nend\n";
-        assert_eq!(chapter_name(text), Some("Banking".to_string()));
+        assert_eq!(declaration_name(text), Some("Banking".to_string()));
+    }
+
+    #[test]
+    fn finds_a_sentence_file_bluebook_name_from_its_domain_line() {
+        assert_eq!(
+            declaration_name("Domain: customer orders\n"),
+            Some("CustomerOrders".to_string())
+        );
+    }
+
+    #[test]
+    fn reads_the_column_a_sentence_refusal_names() {
+        let path = Path::new("/tmp/page.bluebook");
+        let line = "/tmp/page.bluebook:11:5: this is not a sentence I know in a value object: \"Rull x\" (expected one of: Rule <description> holds when <condition>)";
+        let diag = parse_diagnostic_line(line, path).expect("parses");
+        assert_eq!((diag.line, diag.column), (11, Some(5)));
+        assert!(diag.message.starts_with("this is not a sentence I know"));
+        assert_eq!(
+            diag.expected,
+            vec!["Rule <description> holds when <condition>"]
+        );
+    }
+
+    #[test]
+    fn a_whole_line_refusal_has_no_column() {
+        let path = Path::new("/tmp/pizzas.bluebook");
+        let line = "/tmp/pizzas.bluebook:12: unknown word 'topping' in Aggregate";
+        assert_eq!(
+            parse_diagnostic_line(line, path).expect("parses").column,
+            None
+        );
     }
 
     #[test]
-    fn no_chapter_name_is_not_an_error() {
-        assert_eq!(chapter_name("# just a comment\n"), None);
+    fn no_bluebook_name_is_not_an_error() {
+        assert_eq!(declaration_name("# just a comment\n"), None);
     }
 
     #[test]

data/rust/lsp/src/main.rs

@@ -1,5 +1,5 @@
 //! `hecks-lsp`: a minimal stdio language server for `.bluebook`/`.hecksagon` files.
-//! Publishes diagnostics from `hecks-parse chapter` and serves document symbols and definitions.
+//! Publishes diagnostics from `hecks-parse bluebook` and serves document symbols and definitions.
 
 mod diagnostics;
 mod json;
@@ -64,6 +64,15 @@ impl Server {
                                 ("textDocumentSync", Json::Number(1)),
                                 ("documentSymbolProvider", Json::Bool(true)),
                                 ("definitionProvider", Json::Bool(true)),
+                                // Offered for files written as sentences: the sentences legal
+                                // at the cursor, drawn from the parser's own phrase table.
+                                (
+                                    "completionProvider",
+                                    Json::object(vec![(
+                                        "triggerCharacters",
+                                        Json::Array(vec![Json::string(" ")]),
+                                    )]),
+                                ),
                             ]),
                         ),
                         (
@@ -151,6 +160,12 @@ impl Server {
                     let _ = rpc::write_message(out, &rpc::response(id, result));
                 }
             }
+            "textDocument/completion" => {
+                if let Some(id) = id {
+                    let result = self.suggest_sentences(message).unwrap_or(Json::Null);
+                    let _ = rpc::write_message(out, &rpc::response(id, result));
+                }
+            }
             "textDocument/didClose" => {
                 if let Some(uri) = message
                     .get("params")
@@ -220,8 +235,57 @@ impl Server {
         }
     }
 
+    /// The sentences an author may write at the cursor of a file written as sentences, asked of
+    /// `hecks-parse complete` so the editor offers only what the parser would accept.
+    fn suggest_sentences(&self, message: &Json) -> Option<Json> {
+        let params = message.get("params")?;
+        let uri = params.get("textDocument")?.get("uri")?.as_str()?;
+        let position = params.get("position")?;
+        let line = position.get("line")?.as_i64()? as usize;
+        let character = position.get("character")?.as_i64()? as usize;
+        let text = self.documents.get(uri)?;
+        let hecks_parse = self.hecks_parse.as_ref()?;
+
+        let temp_path = temp_path_for(uri);
+        std::fs::create_dir_all(temp_path.parent()?).ok()?;
+        std::fs::write(&temp_path, text).ok()?;
+        let output = std::process::Command::new(hecks_parse)
+            .arg("complete")
+            .arg(&temp_path)
+            .args([
+                "--line",
+                &(line + 1).to_string(),
+                "--col",
+                &(character + 1).to_string(),
+            ])
+            .output()
+            .ok()?;
+        if !output.status.success() {
+            return None;
+        }
+        let found = Json::parse(&String::from_utf8_lossy(&output.stdout)).ok()?;
+
+        let current = text.lines().nth(line).unwrap_or("");
+        let indent = current
+            .chars()
+            .take_while(|c| c.is_whitespace())
+            .count()
+            .min(character);
+        let items = found
+            .get("items")?
+            .as_array()?
+            .iter()
+            .filter_map(|item| {
+                let label = item.get("label")?.as_str()?;
+                let snippet = item.get("snippet")?.as_str()?;
+                Some(completion_item(label, snippet, line, indent, character))
+            })
+            .collect();
+        Some(Json::Array(items))
+    }
+
     /// Resolves the identifier under the cursor to its declaration in this buffer,
-    /// then in sibling `.bluebook`/`.hecksagon` files, since a chapter spans several files.
+    /// then in sibling `.bluebook`/`.hecksagon` files, since a bluebook spans several files.
     fn find_definition(&self, message: &Json) -> Option<Json> {
         let params = message.get("params")?;
         let uri = params.get("textDocument")?.get("uri")?.as_str()?;
@@ -383,15 +447,47 @@ fn log(out: &mut impl Write, severity: i64, message: &str) {
     let _ = rpc::write_message(out, &rpc::notification("window/logMessage", params));
 }
 
-/// Builds a full-line diagnostic: Warning when not yet implemented, else Error.
+/// One offered sentence: its label, and the snippet that replaces what has been typed on the
+/// line (from the indent to the cursor) with the whole sentence and a tab stop per fill-in.
+fn completion_item(label: &str, snippet: &str, line: usize, indent: usize, cursor: usize) -> Json {
+    let at = |character: usize| {
+        Json::object(vec![
+            ("line", Json::Number(line as i64)),
+            ("character", Json::Number(character as i64)),
+        ])
+    };
+    Json::object(vec![
+        ("label", Json::string(label)),
+        // 15 = Snippet (LSP CompletionItemKind); 2 = the text is in snippet syntax.
+        ("kind", Json::Number(15)),
+        ("insertTextFormat", Json::Number(2)),
+        ("filterText", Json::string(label)),
+        (
+            "textEdit",
+            Json::object(vec![
+                (
+                    "range",
+                    Json::object(vec![("start", at(indent)), ("end", at(cursor))]),
+                ),
+                ("newText", Json::string(snippet)),
+            ]),
+        ),
+    ])
+}
+
+/// Builds a diagnostic that starts at the parser's column when it names one and covers the
+/// whole line otherwise: Warning when not yet implemented, else Error.
 /// The `expected` list is folded into the message text.
 fn lsp_diagnostic(diag: &diagnostics::FileDiagnostic, text: &str) -> Json {
     let zero_based_line = diag.line.saturating_sub(1) as i64;
+    let start = diag
+        .column
+        .map_or(0, |column| column.saturating_sub(1) as i64);
     let line_len = text
         .lines()
         .nth(diag.line.saturating_sub(1))
         .map_or(0, |l| l.chars().count() as i64)
-        .max(1);
+        .max(start + 1);
 
     let mut message = diag.message.clone();
     if !diag.expected.is_empty() {
@@ -406,7 +502,7 @@ fn lsp_diagnostic(diag: &diagnostics::FileDiagnostic, text: &str) -> Json {
                     "start",
                     Json::object(vec![
                         ("line", Json::Number(zero_based_line)),
-                        ("character", Json::Number(0)),
+                        ("character", Json::Number(start)),
                     ]),
                 ),
                 (

data/rust/parser/fuzz/Cargo.toml

@@ -13,8 +13,8 @@ publish = false
 libfuzzer-sys = "0.4"
 
 [[bin]]
-name = "chapter"
-path = "fuzz_targets/chapter.rs"
+name = "bluebook"
+path = "fuzz_targets/bluebook.rs"
 test = false
 doc = false
 bench = false

data/rust/parser/fuzz/README.md

@@ -7,12 +7,12 @@ which is its own workspace and is never built by `cargo build` or `cargo test` i
 rustup toolchain install nightly
 cargo install cargo-fuzz
 cd rust/parser
-cargo +nightly fuzz run chapter -- -max_total_time=60   # bluebook parse + determinism
+cargo +nightly fuzz run bluebook -- -max_total_time=60   # bluebook parse + determinism
 cargo +nightly fuzz run resolve -- -max_total_time=60   # hecksagon `attaches` resolution
 ```
 
-Seed a run from the fixtures: `cargo +nightly fuzz run chapter ../tests/fixtures`. A crash lands
-in `fuzz/artifacts/`; copy it to a `.bluebook` and run `hecks-parse chapter --chapter Fuzzed
+Seed a run from the fixtures: `cargo +nightly fuzz run bluebook ../tests/fixtures`. A crash lands
+in `fuzz/artifacts/`; copy it to a `.bluebook` and run `hecks-parse bluebook --bluebook Fuzzed
 <file>` to reproduce it.
 
 The seeded harness in `tests/fuzz.rs` is what CI runs; this directory is for longer

data/rust/parser/fuzz/fuzz_targets/{chapter.rs → bluebook.rs}

@@ -1,9 +1,9 @@
-//! Coverage-guided target for `parse::chapter::parse_chapter`.
+//! Coverage-guided target for `parse::bluebook::parse_bluebook`.
 //!
 //! The parser is a binary crate, so this target includes its modules by path and declares them at
 //! its own crate root, which is where their `crate::` references resolve.
 //!
-//! Run from `rust/parser` with a nightly toolchain: `cargo +nightly fuzz run chapter`.
+//! Run from `rust/parser` with a nightly toolchain: `cargo +nightly fuzz run bluebook`.
 #![no_main]
 #![allow(dead_code)]
 
@@ -37,9 +37,9 @@ fuzz_target!(|data: &[u8]| {
     };
     let files = [("fuzz.bluebook".to_string(), source.to_string())];
     // A refusal is a normal answer; only a panic or a hang is a finding.
-    if let Ok(bluebook) = parse::chapter::parse_chapter("Fuzzed", &files) {
+    if let Ok(bluebook) = parse::declaration::parse_bluebook("Fuzzed", &files) {
         let first = emit::write(&emit::bluebook_json(&bluebook));
-        let again = parse::chapter::parse_chapter("Fuzzed", &files)
+        let again = parse::declaration::parse_bluebook("Fuzzed", &files)
             .map(|b| emit::write(&emit::bluebook_json(&b)));
         assert_eq!(
             Ok(first),

data/rust/parser/fuzz/fuzz_targets/resolve.rs

@@ -1,4 +1,4 @@
-//! Coverage-guided target for `parse::chapter::resolve_hecksagon_dependencies`.
+//! Coverage-guided target for `parse::bluebook::resolve_hecksagon_dependencies`.
 //!
 //! Run from `rust/parser` with a nightly toolchain: `cargo +nightly fuzz run resolve`.
 #![no_main]
@@ -31,5 +31,5 @@ fuzz_target!(|data: &[u8]| {
     let Ok(source) = std::str::from_utf8(data) else {
         return;
     };
-    let _ = parse::chapter::resolve_hecksagon_dependencies("Fuzzed", "fuzz.hecksagon", source);
+    let _ = parse::declaration::resolve_hecksagon_dependencies("Fuzzed", "fuzz.hecksagon", source);
 });

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

@@ -10,6 +10,20 @@ const TABLE: &[(&str, &str)] = &[
     ("snake_name", r"^[a-z][a-z0-9_]*$"),
     ("git_sha", r"^[0-9a-fA-F]{7,40}$"),
     ("digits", r"^[0-9]+$"),
+    ("identifier", r"^[A-Za-z][A-Za-z0-9_]*$"),
+    ("csv_list", r"^[^ \t\n\r,]+(,[^ \t\n\r,]+)*$"),
+    (
+        "command_ref",
+        r"^[A-Z][A-Za-z0-9]*::[A-Z][A-Za-z0-9]*\.[A-Z][A-Za-z0-9]*$",
+    ),
+    ("host_port", r"^[A-Za-z0-9_-]+(:[0-9]+)?$"),
+    ("instance_id", r"^i-[0-9a-f]+$"),
+    ("hostname", r"^[A-Za-z0-9][A-Za-z0-9.-]*$"),
+    ("word_chars", r"^[A-Za-z0-9_]*$"),
+    ("version", r"^[0-9]+[.][0-9]+[.][0-9]+"),
+    ("http_scheme", r"^https?://"),
+    ("capitalized", r"[A-Z][A-Za-z0-9]*"),
+    ("single_line", r"[^\n\r]"),
 ];
 
 /// The regex source `name` stands for, or `None` when the language gives no such name.
@@ -20,6 +34,14 @@ pub fn source(name: &str) -> Option<&'static str> {
         .map(|(_, source)| *source)
 }
 
+/// The name the language gives `source`, or `None` when no name stands for exactly that regex.
+pub fn name_of(source: &str) -> Option<&'static str> {
+    TABLE
+        .iter()
+        .find(|(_, given)| *given == source)
+        .map(|(name, _)| *name)
+}
+
 /// Every name the language gives, in table order.
 pub fn names() -> Vec<&'static str> {
     TABLE.iter().map(|(name, _)| *name).collect()

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

@@ -19,6 +19,58 @@ pub fn reference_attribute(target: &str, as_name: Option<&str>, optional: bool)
     }
 }
 
+/// The shapes `reference_to one_of(A, B), as: :subject` mints (ADR 0127), mirroring
+/// `AggregateBuilder::OneOfReference`: the `one_of` attribute, the closed set of the variants'
+/// names (`SubjectType`) and the tagged value object (`Subject`, a `type` and an `id`).
+pub struct OneOfReference {
+    pub attribute: ir::Attribute,
+    pub type_set: ir::ValueObject,
+    pub tagged: ir::ValueObject,
+}
+
+/// Mints a tagged reference's attribute and shapes; `aggregate` qualifies the `admits:` name.
+pub fn one_of_reference(
+    aggregate: &str,
+    variants: &[String],
+    as_name: &str,
+    optional: bool,
+) -> OneOfReference {
+    let tagged_name = crate::build::naming::pascal(as_name);
+    let set_name = format!("{tagged_name}Type");
+    let mut type_set = crate::build::closed_sets::synthesize(&set_name, variants);
+    type_set.name.clone_from(&set_name);
+    let string_field = |name: &str, admits: Option<String>| ir::Attribute {
+        name: name.to_string(),
+        type_name: "String".to_string(),
+        admits,
+        ..Default::default()
+    };
+    let tagged = ir::ValueObject {
+        name: tagged_name.clone(),
+        attributes: vec![
+            string_field("type", Some(format!("{aggregate}::{set_name}"))),
+            string_field("id", None),
+        ],
+        invariants: Vec::new(),
+        closed_set: false,
+        members: Vec::new(),
+    };
+    let attribute = ir::Attribute {
+        name: as_name.to_string(),
+        type_name: tagged_name,
+        optional,
+        relationship: Some("one_of".to_string()),
+        ..Default::default()
+    };
+    OneOfReference {
+        attribute,
+        type_set,
+        tagged,
+    }
+}
+
+/// Mints a relationship attribute (`reference_to`, `has_one`, `belongs_to`, `has_many`), recording
+/// the word that minted it.
 pub fn relationship_attribute(
     target: &str,
     kind: &str,

data/rust/parser/src/diag.rs

@@ -4,25 +4,38 @@
 
 use std::fmt;
 
+/// A refusal: where it happened, what is wrong and what would have been accepted.
 #[derive(Debug, Clone)]
 pub struct Diagnostic {
     pub file: String,
     pub line: usize,
+    /// The 1-based character column the problem starts at; `None` for a construct that is
+    /// refused as a whole line, which is every refusal of the Ruby-shaped grammar.
+    pub column: Option<usize>,
     pub message: String,
     /// The legal alternatives at this point; empty when there is nothing more specific.
     pub expected: Vec<String>,
 }
 
 impl Diagnostic {
+    /// A refusal of a whole line.
     pub fn new(file: impl Into<String>, line: usize, message: impl Into<String>) -> Self {
         Self {
             file: file.into(),
             line,
+            column: None,
             message: message.into(),
             expected: Vec::new(),
         }
     }
 
+    /// The same refusal, pointing at the character column it starts at.
+    pub const fn with_column(mut self, column: usize) -> Self {
+        self.column = Some(column);
+        self
+    }
+
+    /// The same refusal, listing what would have been accepted.
     pub fn with_expected(mut self, expected: Vec<String>) -> Self {
         self.expected = expected;
         self
@@ -44,7 +57,14 @@ impl Diagnostic {
 
 impl fmt::Display for Diagnostic {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "{}:{}: {}", self.file, self.line, self.message)?;
+        match self.column {
+            Some(column) => write!(
+                f,
+                "{}:{}:{}: {}",
+                self.file, self.line, column, self.message
+            )?,
+            None => write!(f, "{}:{}: {}", self.file, self.line, self.message)?,
+        }
         if !self.expected.is_empty() {
             write!(f, " (expected one of: {})", self.expected.join(", "))?;
         }
@@ -52,4 +72,5 @@ impl fmt::Display for Diagnostic {
     }
 }
 
+/// A parse that either succeeds or is refused with a [`Diagnostic`].
 pub type ParseResult<T> = Result<T, Diagnostic>;