hecks 4.0.0 → 6.0.0

data/rust/parser/src/lex.rs

@@ -3,6 +3,77 @@
 
 use crate::diag::Diagnostic;
 
+/// What a character run is quoted by.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Quoted {
+    /// `"…"`.
+    Double,
+    /// `'…'`.
+    Single,
+    /// `/…/`, a regular expression literal.
+    Regex,
+}
+
+impl Quoted {
+    const fn closer(self) -> char {
+        match self {
+            Self::Double => '"',
+            Self::Single => '\'',
+            Self::Regex => '/',
+        }
+    }
+}
+
+/// Tracks, character by character, whether the scan is inside a string or a regexp literal, so a
+/// `#`, a brace or a bracket there is text and not Ruby.
+#[derive(Debug, Default)]
+struct Quotes {
+    mode: Option<Quoted>,
+    escaping: bool,
+    /// The last character seen outside a literal that was not a space.
+    last: Option<char>,
+}
+
+impl Quotes {
+    /// Feeds one character; true when it is inside a literal or is one of its delimiters.
+    fn inside(&mut self, ch: char) -> bool {
+        if let Some(mode) = self.mode {
+            if self.escaping {
+                self.escaping = false;
+            } else if ch == '\\' {
+                self.escaping = true;
+            } else if ch == mode.closer() {
+                self.mode = None;
+                self.last = Some(ch);
+            }
+            return true;
+        }
+        match ch {
+            '"' => self.mode = Some(Quoted::Double),
+            '\'' if !self
+                .last
+                .is_some_and(|prev| prev.is_alphanumeric() || prev == '_') =>
+            {
+                self.mode = Some(Quoted::Single);
+            }
+            '/' if self.expects_operand() => self.mode = Some(Quoted::Regex),
+            _ => {
+                if !ch.is_whitespace() {
+                    self.last = Some(ch);
+                }
+                return false;
+            }
+        }
+        true
+    }
+
+    /// Whether what comes next is an operand, so a `/` opens a regexp and is not a division.
+    fn expects_operand(&self) -> bool {
+        self.last
+            .is_none_or(|prev| "(,{[=!|&~:?<>+-*%^;".contains(prev))
+    }
+}
+
 #[derive(Debug, Clone, Copy)]
 pub struct SourceLine<'a> {
     pub number: usize,
@@ -80,22 +151,11 @@ pub fn join_continuations(source: &str) -> String {
 }
 
 fn ends_outside_quotes(text: &str) -> bool {
-    let mut quoting = false;
-    let mut escaping = false;
+    let mut quotes = Quotes::default();
     for ch in text.chars() {
-        if escaping {
-            escaping = false;
-            continue;
-        }
-        if quoting && ch == '\\' {
-            escaping = true;
-            continue;
-        }
-        if ch == '"' {
-            quoting = !quoting;
-        }
+        quotes.inside(ch);
     }
-    !quoting
+    quotes.mode.is_none()
 }
 
 fn ends_with_bare_backslash(text: &str) -> bool {
@@ -109,22 +169,9 @@ fn ends_with_bare_comma(text: &str) -> bool {
 /// Not bracket-type aware: mismatched bracket types never occur in real source.
 fn bracket_delta(text: &str) -> i32 {
     let mut depth = 0i32;
-    let mut quoting = false;
-    let mut escaping = false;
+    let mut quotes = Quotes::default();
     for ch in text.chars() {
-        if escaping {
-            escaping = false;
-            continue;
-        }
-        if quoting && ch == '\\' {
-            escaping = true;
-            continue;
-        }
-        if ch == '"' {
-            quoting = !quoting;
-            continue;
-        }
-        if quoting {
+        if quotes.inside(ch) {
             continue;
         }
         match ch {
@@ -137,22 +184,12 @@ fn bracket_delta(text: &str) -> i32 {
 }
 
 fn strip_comment(line: &str) -> &str {
-    let mut quoting = false;
-    let mut escaping = false;
+    let mut quotes = Quotes::default();
     for (byte_idx, ch) in line.char_indices() {
-        if escaping {
-            escaping = false;
-            continue;
-        }
-        if quoting && ch == '\\' {
-            escaping = true;
-            continue;
-        }
-        if ch == '"' {
-            quoting = !quoting;
+        if quotes.inside(ch) {
             continue;
         }
-        if ch == '#' && !quoting {
+        if ch == '#' {
             return &line[..byte_idx];
         }
     }
@@ -269,23 +306,10 @@ fn leading_identifier_end(text: &str) -> usize {
 fn find_top_level_assignment(text: &str) -> Option<usize> {
     let bytes = text.as_bytes();
     let mut depth: i32 = 0;
-    let mut quoting = false;
-    let mut escaping = false;
+    let mut quotes = Quotes::default();
 
     for (idx, ch) in text.char_indices() {
-        if escaping {
-            escaping = false;
-            continue;
-        }
-        if quoting && ch == '\\' {
-            escaping = true;
-            continue;
-        }
-        if ch == '"' {
-            quoting = !quoting;
-            continue;
-        }
-        if quoting {
+        if quotes.inside(ch) {
             continue;
         }
         match ch {
@@ -356,23 +380,10 @@ fn trailing_do(rest: &str) -> Option<(&str, Option<String>)> {
 
 /// A `{` inside parens or written as a hash literal argument is not a source-body opener.
 fn find_top_level_brace(text: &str) -> Option<usize> {
-    let mut quoting = false;
-    let mut escaping = false;
+    let mut quotes = Quotes::default();
     let mut paren_depth: i32 = 0;
     for (idx, ch) in text.char_indices() {
-        if escaping {
-            escaping = false;
-            continue;
-        }
-        if quoting && ch == '\\' {
-            escaping = true;
-            continue;
-        }
-        if ch == '"' {
-            quoting = !quoting;
-            continue;
-        }
-        if quoting {
+        if quotes.inside(ch) {
             continue;
         }
         match ch {
@@ -397,24 +408,11 @@ fn is_hash_literal_brace(before: &str) -> bool {
 
 fn matching_brace_body(text: &str) -> Option<(String, &str)> {
     let mut depth: i32 = 0;
-    let mut quoting = false;
-    let mut escaping = false;
+    let mut quotes = Quotes::default();
     let mut start_byte = None;
 
     for (idx, ch) in text.char_indices() {
-        if escaping {
-            escaping = false;
-            continue;
-        }
-        if quoting && ch == '\\' {
-            escaping = true;
-            continue;
-        }
-        if ch == '"' {
-            quoting = !quoting;
-            continue;
-        }
-        if quoting {
+        if quotes.inside(ch) {
             continue;
         }
         if ch == '{' {
@@ -645,4 +643,34 @@ mod tests {
         // An escaped backslash inside a still-open string is not a line continuation.
         assert!(!ends_with_bare_backslash("template: \"a\\"));
     }
+
+    #[test]
+    fn a_brace_inside_a_single_quoted_string_opens_no_block() {
+        let (args, opener) =
+            split_opener("attribute :value, String, pattern: '^[A-Za-z0-9_-]{11}$'");
+        assert_eq!(opener, Opener::None);
+        assert!(args.ends_with("{11}$'"), "{args}");
+    }
+
+    #[test]
+    fn a_hash_inside_a_regexp_literal_starts_no_comment() {
+        let line = "invariant(\"a hue\") { value.to_s.match?(/\\A#[0-9a-f]{6}\\z/) }";
+        assert_eq!(strip_comment(line), line);
+    }
+
+    #[test]
+    fn a_slash_after_a_word_is_a_division_and_a_comment_after_it_still_strips() {
+        assert_eq!(
+            strip_comment("sets :ratio, to: a / b # per second"),
+            "sets :ratio, to: a / b "
+        );
+    }
+
+    #[test]
+    fn an_apostrophe_in_a_trailing_comment_is_not_a_quote() {
+        assert_eq!(
+            strip_comment("attribute :name, String # the site's own"),
+            "attribute :name, String "
+        );
+    }
 }

data/rust/parser/src/main.rs

@@ -17,7 +17,12 @@ mod ir;
 mod keywords;
 mod lex;
 mod parse;
+// Generated table of the sentence form's phrases; not every column is read by this binary.
+#[allow(dead_code)]
+mod phrases;
+mod render_ruby;
 mod ruby_value;
+mod sentence;
 
 use std::fs;
 use std::process::ExitCode;
@@ -50,7 +55,11 @@ impl From<diag::Diagnostic> for RunError {
 
 fn run(args: &[String]) -> Result<(), RunError> {
     match args.first().map(String::as_str) {
-        Some("chapter") => run_chapter(&args[1..]),
+        Some("bluebook") => run_bluebook(&args[1..]),
+        Some("render") => run_render(&args[1..]),
+        Some("complete") => run_complete(&args[1..]),
+        Some("format") => run_format(&args[1..]),
+        Some("examples") => run_examples(&args[1..]),
         Some("resolve") => run_resolve(&args[1..]),
         Some("adapter") => run_adapter(&args[1..]),
         Some("world") => run_world(&args[1..]),
@@ -59,33 +68,38 @@ fn run(args: &[String]) -> Result<(), RunError> {
             Ok(())
         }
         Some(other) => Err(RunError::Usage(format!(
-            "unknown subcommand '{other}' — expected 'chapter', 'resolve', 'adapter', 'world', or 'coverage'"
+            "unknown subcommand '{other}' — expected 'bluebook', 'resolve', 'adapter', 'world', or 'coverage'"
         ))),
         None => Err(RunError::Usage(
-            "hecks-parse <chapter|resolve|adapter|world|coverage> ...".to_string(),
+            "hecks-parse <bluebook|resolve|adapter|world|coverage> ...".to_string(),
         )),
     }
 }
 
-/// `hecks-parse chapter --chapter <Name> <files...>`: emits the chapter's `ir.json` on stdout.
-fn run_chapter(args: &[String]) -> Result<(), RunError> {
-    let mut chapter_name: Option<String> = None;
+/// The bluebook a `bluebook` or `render` call names and the files it reads, as `(path, source)`.
+fn read_bluebook_args(
+    subcommand: &str,
+    args: &[String],
+) -> Result<(String, Vec<(String, String)>), RunError> {
+    let mut declaration_name: Option<String> = None;
     let mut files: Vec<String> = Vec::new();
     let mut iter = args.iter();
     while let Some(arg) = iter.next() {
-        if arg == "--chapter" {
-            chapter_name = iter.next().cloned();
+        if arg == "--bluebook" {
+            declaration_name = iter.next().cloned();
         } else {
             files.push(arg.clone());
         }
     }
-    let chapter_name = chapter_name.ok_or_else(|| {
-        RunError::Usage("hecks-parse chapter --chapter <Name> <files...>".to_string())
+    let declaration_name = declaration_name.ok_or_else(|| {
+        RunError::Usage(format!(
+            "hecks-parse {subcommand} --bluebook <Name> <files...>"
+        ))
     })?;
     if files.is_empty() {
-        return Err(RunError::Usage(
-            "hecks-parse chapter --chapter <Name> <files...> — no files given".to_string(),
-        ));
+        return Err(RunError::Usage(format!(
+            "hecks-parse {subcommand} --bluebook <Name> <files...> — no files given"
+        )));
     }
 
     let loaded: Vec<(String, String)> = files
@@ -96,51 +110,175 @@ fn run_chapter(args: &[String]) -> Result<(), RunError> {
             Ok((path.clone(), source))
         })
         .collect::<Result<_, RunError>>()?;
+    Ok((declaration_name, loaded))
+}
 
-    let bluebook = parse::chapter::parse_chapter(&chapter_name, &loaded)?;
+/// `hecks-parse bluebook --bluebook <Name> <files...>`: emits the bluebook's `ir.json` on stdout.
+fn run_bluebook(args: &[String]) -> Result<(), RunError> {
+    let (declaration_name, loaded) = read_bluebook_args("bluebook", args)?;
+    let bluebook = parse::declaration::parse_bluebook(&declaration_name, &loaded)?;
     println!("{}", emit::write(&emit::bluebook_json(&bluebook)));
     Ok(())
 }
 
-/// `hecks-parse resolve --chapter <Name> <file.hecksagon>`: prints that chapter's
-/// `attaches` names as JSON, in file order: `gem_chapters` for a chapter the gem carries and
+/// `hecks-parse render --bluebook <Name> <files...>`: prints the bluebook as the Ruby-shaped
+/// bluebook text that declares the same IR, so a bluebook written as sentences can be loaded by
+/// Ruby.
+fn run_render(args: &[String]) -> Result<(), RunError> {
+    let (declaration_name, loaded) = read_bluebook_args("render", args)?;
+    let bluebook = parse::declaration::parse_bluebook(&declaration_name, &loaded)?;
+    let first = loaded.first().map_or("<none>", |(path, _)| path.as_str());
+    let text = render_ruby::ruby_form(&bluebook)
+        .map_err(|why| RunError::Parse(diag::Diagnostic::new(first, 1, why)))?;
+    print!("{text}");
+    Ok(())
+}
+
+/// `hecks-parse examples --bluebook <Name> --examples <file> [--also <file>] <files...>`:
+/// prints the `.behaviors` text that runs the examples file against the bluebook. Each `--also`
+/// file is booted with it but not parsed, as a hecksagon is.
+fn run_examples(args: &[String]) -> Result<(), RunError> {
+    let mut examples_path: Option<String> = None;
+    let mut also: Vec<String> = Vec::new();
+    let mut rest: Vec<String> = Vec::new();
+    let mut iter = args.iter();
+    while let Some(arg) = iter.next() {
+        match arg.as_str() {
+            "--examples" => examples_path = iter.next().cloned(),
+            "--also" => also.extend(iter.next().cloned()),
+            _ => rest.push(arg.clone()),
+        }
+    }
+    let examples_path = examples_path.ok_or_else(|| {
+        RunError::Usage(
+            "hecks-parse examples --bluebook <Name> --examples <file> <files...>".to_string(),
+        )
+    })?;
+    let (declaration_name, loaded) = read_bluebook_args("examples", &rest)?;
+    let source = fs::read_to_string(&examples_path)
+        .map_err(|e| RunError::Usage(format!("could not read '{examples_path}': {e}")))?;
+    let bluebook = parse::declaration::parse_bluebook(&declaration_name, &loaded)?;
+    // The suite boots the bluebook's files and then any `--also` files (the Memory-bound
+    // hecksagon that answers the bluebook's asks), each by its absolute path.
+    let absolute: Vec<String> = loaded
+        .iter()
+        .map(|(path, _)| path)
+        .chain(also.iter())
+        .map(|path| {
+            fs::canonicalize(path)
+                .map_or_else(|_| path.clone(), |full| full.to_string_lossy().into_owned())
+        })
+        .collect();
+    let text = sentence::examples::compile(&bluebook, &absolute, &examples_path, &source)?;
+    print!("{text}");
+    Ok(())
+}
+
+/// `hecks-parse format --bluebook <Name> <files...>`: prints the bluebook, whichever form its files
+/// are written in, as canonical sentences.
+fn run_format(args: &[String]) -> Result<(), RunError> {
+    let (declaration_name, loaded) = read_bluebook_args("format", args)?;
+    let bluebook = parse::declaration::parse_bluebook(&declaration_name, &loaded)?;
+    let first = loaded.first().map_or("<none>", |(path, _)| path.as_str());
+    let text = sentence::format::sentences(&bluebook)
+        .map_err(|why| RunError::Parse(diag::Diagnostic::new(first, 1, why)))?;
+    print!("{text}");
+    Ok(())
+}
+
+/// `hecks-parse complete <file> --line N --col N`: prints, as JSON, the sentences an author may
+/// write at that cursor of a file written as sentences. Both numbers are 1-based.
+fn run_complete(args: &[String]) -> Result<(), RunError> {
+    let usage = || RunError::Usage("hecks-parse complete <file> --line N --col N".to_string());
+    let mut path: Option<&String> = None;
+    let mut line: Option<usize> = None;
+    let mut col: Option<usize> = None;
+    let mut iter = args.iter();
+    while let Some(arg) = iter.next() {
+        match arg.as_str() {
+            "--line" => line = iter.next().and_then(|value| value.parse().ok()),
+            "--col" => col = iter.next().and_then(|value| value.parse().ok()),
+            _ => path = Some(arg),
+        }
+    }
+    let (Some(path), Some(line), Some(col)) = (path, line, col) else {
+        return Err(usage());
+    };
+    let source = fs::read_to_string(path)
+        .map_err(|e| RunError::Usage(format!("could not read '{path}': {e}")))?;
+
+    let found = sentence::complete::complete(&source, line, col);
+    let items: Vec<emit::JsonValue> = found
+        .items
+        .iter()
+        .map(|item| {
+            emit::JsonValue::Object(vec![
+                (
+                    "label".to_string(),
+                    emit::JsonValue::str(item.label.clone()),
+                ),
+                (
+                    "insert".to_string(),
+                    emit::JsonValue::str(item.insert.clone()),
+                ),
+                (
+                    "snippet".to_string(),
+                    emit::JsonValue::str(item.snippet.clone()),
+                ),
+            ])
+        })
+        .collect();
+    let value = emit::JsonValue::Object(vec![
+        ("context".to_string(), emit::JsonValue::str(found.context)),
+        ("items".to_string(), emit::JsonValue::Array(items)),
+    ]);
+    println!("{}", emit::write(&value));
+    Ok(())
+}
+
+/// `hecks-parse resolve --bluebook <Name> <file.hecksagon>`: prints that bluebook's
+/// `attaches` names as JSON, in file order: `gem_bluebooks` for a bluebook the gem carries and
 /// `vendored_packages` for `from: :vendor`.
 ///
-/// `--chapter` is required because one file can hold several `Hecks.hecksagon` blocks.
+/// `--bluebook` is required because one file can hold several `Hecks.hecksagon` blocks.
 fn run_resolve(args: &[String]) -> Result<(), RunError> {
-    let mut chapter_name: Option<String> = None;
+    let mut declaration_name: Option<String> = None;
     let mut path: Option<&String> = None;
     let mut iter = args.iter();
     while let Some(arg) = iter.next() {
-        if arg == "--chapter" {
-            chapter_name = iter.next().cloned();
+        if arg == "--bluebook" {
+            declaration_name = iter.next().cloned();
         } else {
             path = Some(arg);
         }
     }
-    let chapter_name = chapter_name.ok_or_else(|| {
-        RunError::Usage("hecks-parse resolve --chapter <Name> <file.hecksagon>".to_string())
+    let declaration_name = declaration_name.ok_or_else(|| {
+        RunError::Usage("hecks-parse resolve --bluebook <Name> <file.hecksagon>".to_string())
     })?;
     let path = path.ok_or_else(|| {
-        RunError::Usage("hecks-parse resolve --chapter <Name> <file.hecksagon>".to_string())
+        RunError::Usage("hecks-parse resolve --bluebook <Name> <file.hecksagon>".to_string())
     })?;
 
     let source = fs::read_to_string(path)
         .map_err(|e| RunError::Usage(format!("could not read '{path}': {e}")))?;
     let (framework_names, vendored_names) =
-        parse::chapter::resolve_hecksagon_dependencies(&chapter_name, path, &source)?;
+        parse::declaration::resolve_hecksagon_dependencies(&declaration_name, path, &source)?;
 
+    let gem_bluebooks = || {
+        emit::JsonValue::Array(
+            framework_names
+                .iter()
+                .cloned()
+                .map(emit::JsonValue::String)
+                .collect(),
+        )
+    };
     let value = emit::JsonValue::Object(vec![
-        ("domain".to_string(), emit::JsonValue::String(chapter_name)),
         (
-            "gem_chapters".to_string(),
-            emit::JsonValue::Array(
-                framework_names
-                    .into_iter()
-                    .map(emit::JsonValue::String)
-                    .collect(),
-            ),
+            "domain".to_string(),
+            emit::JsonValue::String(declaration_name),
         ),
+        ("gem_bluebooks".to_string(), gem_bluebooks()),
         (
             "vendored_packages".to_string(),
             emit::JsonValue::Array(
@@ -203,6 +341,9 @@ const COVERED_PAIRS: &[(&str, &str)] = &[
     ("port", "Adapter"),
     ("field", "Adapter"),
     ("secret", "Adapter"),
+    ("answers_query", "Adapter"),
+    ("runs", "Adapter"),
+    ("provides", "Adapter"),
     ("world", "File"),
     ("realm", "World"),
     ("latest", "World"),
@@ -219,6 +360,7 @@ const COVERED_PAIRS: &[(&str, &str)] = &[
     ("namespace", "Bluebook"),
     ("description", "Aggregate"),
     ("provenance", "Aggregate"),
+    ("acknowledges", "Aggregate"),
     ("identified_by", "Aggregate"),
     ("attribute", "Aggregate"),
     ("value_object", "Aggregate"),
@@ -241,6 +383,7 @@ const COVERED_PAIRS: &[(&str, &str)] = &[
     ("given", "Command"),
     ("ensures", "Command"),
     ("needs", "Command"),
+    ("idempotent", "Command"),
     ("sets", "Command"),
     ("corrects", "Command"),
     ("delegates_to", "Command"),
@@ -261,6 +404,7 @@ const COVERED_PAIRS: &[(&str, &str)] = &[
     ("mark", "Lifecycle"),
     ("description", "Query"),
     ("attribute", "Query"),
+    ("reference_to", "Query"),
     ("where", "Query"),
     ("order_by", "Query"),
     ("limit", "Query"),
@@ -284,9 +428,13 @@ const COVERED_PAIRS: &[(&str, &str)] = &[
     ("attaches", "Hecksagon"),
     ("driven_by", "Hecksagon"),
     ("operation", "DomainPort"),
+    ("tells", "DomainPort"),
+    ("asks", "DomainPort"),
     ("reference_to", "PortOperation"),
     ("attribute", "PortOperation"),
     ("emits", "PortOperation"),
+    ("answers", "PortOperation"),
+    ("refuses", "PortOperation"),
     ("read_model", "Bluebook"),
     ("description", "ReadModel"),
     ("include", "ReadModel"),

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

@@ -96,6 +96,34 @@ fn parse_body(
                     1,
                 )?);
             }
+            "answers_query" => {
+                adapter.answers.push(super::positional_text(
+                    file,
+                    number,
+                    "answers_query",
+                    &gated.args,
+                    1,
+                )?);
+            }
+            "provides" => {
+                adapter.provides.push(super::positional_text(
+                    file,
+                    number,
+                    "provides",
+                    &gated.args,
+                    1,
+                )?);
+            }
+            // A repeat replaces the earlier value, as the Ruby builder's setter does.
+            "runs" => {
+                adapter.runs = Some(super::positional_text(
+                    file,
+                    number,
+                    "runs",
+                    &gated.args,
+                    1,
+                )?);
+            }
             _ => {
                 return Err(super::not_built_yet(
                     "Adapter",