hecks 2.9.0 → 3.0.1

data/rust/lsp/.gitignore

@@ -0,0 +1 @@
+/target

data/rust/lsp/Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "hecks_lsp"
+version = "0.1.0"

data/rust/lsp/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "hecks_lsp"
+version = "0.1.0"
+edition = "2021"
+
+# Empty table: makes this crate its own workspace root instead of joining `rust`'s.
+[workspace]
+
+[[bin]]
+name = "hecks-lsp"
+path = "src/main.rs"
+
+# No dependencies beyond std: a small synchronous local tool. LSP stdio framing is a few lines,
+# and src/json.rs vendors a minimal JSON pair as rust/build/src/json.rs does.
+# Revisit if it ever needs to serve concurrent requests.
+[dependencies]

data/rust/lsp/README.md

@@ -0,0 +1,133 @@
+# hecks-lsp
+
+A minimal Language Server Protocol front end for `.bluebook`/`.hecksagon`
+files. It doesn't parse anything itself — it shells out to `rust/parser`'s
+own `hecks-parse` binary and turns whatever that says into
+`textDocument/publishDiagnostics` notifications. See `src/main.rs`'s and
+`src/diagnostics.rs`'s own header comments for the reasoning; this file
+is setup + roadmap.
+
+## What it does today
+
+- `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>`
+  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`
+  (`rust/parser` stops at the first error, so there is never more than
+  one to report — see `diagnostics.rs`).
+- Diagnostics carry the parser's real message and its `expected one of:
+  ...` list, at `severity: Warning` when the cause is
+  `not_yet_implemented` (a real Stage 1 gap, not a bug in your file) and
+  `severity: Error` otherwise.
+- `textDocument/documentSymbol` — an outline of every
+  `aggregate`/`entity`/`value_object`/`command`/`query`/`policy`/
+  `process_manager`/`read_model` in the open file, nested by `do`/`end`
+  depth. Sourced from a text scan of the buffer (`outline.rs`), not from
+  `hecks-parse`'s own IR — see that file's header for why (short version:
+  the IR carries no source line for anything, and often fails to build
+  at all under Stage 1's still-partial coverage, so this needed to work
+  independently of a parse succeeding).
+- `textDocument/definition` — resolves the bare identifier under the
+  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
+  them, not the file doing the referencing).
+
+## What it doesn't do yet
+
+- **`documentSymbol`/`definition` are text-scanned, not grammar-verified.**
+  Real, but a second, unverified idea of the grammar rather than a
+  projection of `syntax.bluebook` the way `rust/parser`'s own
+  `keywords.rs` is — see `outline.rs`'s header for the reasoning and its
+  one real failure mode (a buffer with unbalanced `do`/`end` mid-edit).
+  Only `aggregate`/`entity`/`value_object` names are valid `definition`
+  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.
+- **Only one diagnostic per document.** Inherited from `rust/parser`'s
+  own fail-fast design (`parse::chapter`'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
+  `.bluebook` files, or paired with a `.hecksagon` file
+  (`parse::chapter`'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.
+
+## Building it
+
+```
+cd rust/parser && cargo build   # produces target/debug/hecks-parse
+cd rust/lsp    && cargo build   # produces target/debug/hecks-lsp
+```
+
+`hecks-lsp` looks for `hecks-parse` in this order: `$HECKS_PARSE_BIN`,
+then `$PATH`, then `../parser/target/{debug,release}/hecks-parse`
+relative to wherever it's launched from (the common case while both
+crates are built side by side out of one checkout). If none of those
+resolve, it still runs — every document just gets an empty diagnostics
+list and one `window/logMessage` warning explaining why.
+
+## Wiring it into an editor
+
+**Neovim** (`nvim-lspconfig`, manual server since this isn't a published
+server yet):
+
+```lua
+vim.api.nvim_create_autocmd("FileType", {
+  pattern = { "ruby" }, -- .bluebook/.hecksagon have no LSP-registered
+                         -- filetype of their own yet; match on extension
+                         -- instead if you've set one up, or broaden this
+  callback = function(args)
+    local fname = vim.api.nvim_buf_get_name(args.buf)
+    if not (fname:match("%.bluebook$") or fname:match("%.hecksagon$")) then
+      return
+    end
+    vim.lsp.start({
+      name = "hecks-lsp",
+      cmd = { "/absolute/path/to/rust/lsp/target/debug/hecks-lsp" },
+      root_dir = vim.fs.dirname(fname),
+    })
+  end,
+})
+```
+
+**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.
+
+## Testing it without an editor
+
+`cargo test` covers the pure functions (`chapter_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
+real `.bluebook`'s text → read the `publishDiagnostics` notification
+that comes back.

data/rust/lsp/src/diagnostics.rs

@@ -0,0 +1,165 @@
+//! Maps the first error from `hecks-parse chapter` 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;
+
+pub struct FileDiagnostic {
+    pub line: usize, // 1-indexed
+    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.
+///
+/// `Ok(None)` means the parse succeeded or the buffer declares no chapter.
+/// 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 {
+        return Ok(None);
+    };
+
+    let output = Command::new(hecks_parse)
+        .arg("chapter")
+        .arg("--chapter")
+        .arg(&name)
+        .arg(path)
+        .output()
+        .map_err(|e| format!("could not run {}: {e}", hecks_parse.display()))?;
+
+    if output.status.success() {
+        return Ok(None);
+    }
+
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    let Some(first_line) = stderr.lines().next() else {
+        return Err(format!(
+            "{} exited with {:?} and no stderr",
+            hecks_parse.display(),
+            output.status.code()
+        ));
+    };
+    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> {
+    for line in text.lines() {
+        for needle in ["Hecks.bluebook \"", "Hecks.hecksagon \""] {
+            if let Some(after) = line.trim_start().strip_prefix(needle) {
+                if let Some(end) = after.find('"') {
+                    return Some(after[..end].to_string());
+                }
+            }
+        }
+    }
+    None
+}
+
+/// Parses `<file>:<line>: <message>` with an optional `(expected one of: a, b, c)` suffix.
+// `path` is stripped as a known prefix so a colon inside the message cannot confuse the split.
+fn parse_diagnostic_line(line: &str, path: &Path) -> Option<FileDiagnostic> {
+    let prefix = format!("{}:", path.display());
+    let rest = line.strip_prefix(&prefix)?;
+    let (line_no, rest) = rest.split_once(':')?;
+    let line_no: usize = line_no.trim().parse().ok()?;
+    let rest = rest.strip_prefix(' ').unwrap_or(rest);
+
+    let (message, expected) = match rest.rfind(" (expected one of: ") {
+        Some(idx) if rest.ends_with(')') => {
+            let message = &rest[..idx];
+            let list = &rest[idx + " (expected one of: ".len()..rest.len() - 1];
+            let expected = list.split(", ").map(str::to_string).collect();
+            (message.to_string(), expected)
+        }
+        _ => (rest.to_string(), Vec::new()),
+    };
+
+    Some(FileDiagnostic {
+        line: line_no,
+        not_yet_implemented: message.starts_with("not yet implemented:"),
+        message,
+        expected,
+    })
+}
+
+/// Finds `hecks-parse`: `HECKS_PARSE_BIN`, then `PATH`, then `../parser/target/{debug,release}`.
+pub fn locate_hecks_parse() -> Option<PathBuf> {
+    if let Ok(explicit) = std::env::var("HECKS_PARSE_BIN") {
+        let p = PathBuf::from(explicit);
+        if p.is_file() {
+            return Some(p);
+        }
+    }
+    if let Ok(path) = which("hecks-parse") {
+        return Some(path);
+    }
+    for candidate in [
+        "../parser/target/debug/hecks-parse",
+        "../parser/target/release/hecks-parse",
+    ] {
+        let p = PathBuf::from(candidate);
+        if p.is_file() {
+            return Some(p);
+        }
+    }
+    None
+}
+
+/// Walks `PATH` for a file named `name`.
+fn which(name: &str) -> Result<PathBuf, ()> {
+    let path_var = std::env::var_os("PATH").ok_or(())?;
+    for dir in std::env::split_paths(&path_var) {
+        let candidate = dir.join(name);
+        if candidate.is_file() {
+            return Ok(candidate);
+        }
+    }
+    Err(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn finds_a_bluebook_chapter_name() {
+        let text = "Hecks.bluebook \"Pizzas\" do\nend\n";
+        assert_eq!(chapter_name(text), Some("Pizzas".to_string()));
+    }
+
+    #[test]
+    fn finds_a_hecksagon_chapter_name_when_indented() {
+        let text = "  Hecks.hecksagon \"Banking\" do\nend\n";
+        assert_eq!(chapter_name(text), Some("Banking".to_string()));
+    }
+
+    #[test]
+    fn no_chapter_name_is_not_an_error() {
+        assert_eq!(chapter_name("# just a comment\n"), None);
+    }
+
+    #[test]
+    fn parses_a_diagnostic_with_an_expected_list() {
+        let path = Path::new("/tmp/pizzas.bluebook");
+        let line = "/tmp/pizzas.bluebook:12: unknown word 'topping' in Aggregate (expected one of: attribute, command, query)";
+        let diag = parse_diagnostic_line(line, path).expect("parses");
+        assert_eq!(diag.line, 12);
+        assert_eq!(diag.message, "unknown word 'topping' in Aggregate");
+        assert_eq!(diag.expected, vec!["attribute", "command", "query"]);
+        assert!(!diag.not_yet_implemented);
+    }
+
+    #[test]
+    fn parses_a_not_yet_implemented_diagnostic_with_no_expected_list() {
+        let path = Path::new("/tmp/pizzas.bluebook");
+        let line = "/tmp/pizzas.bluebook:5: not yet implemented: Bluebook.report (Stage 1 — see spec/parser_coverage_spec.rb)";
+        let diag = parse_diagnostic_line(line, path).expect("parses");
+        assert_eq!(diag.line, 5);
+        assert!(diag.expected.is_empty());
+        assert!(diag.not_yet_implemented);
+    }
+}