\n");
html.push_str(
"\n",
+ onclick=\"var s=document.querySelector('.sidebar'),o=document.getElementById('sidebar-overlay');\
+s.classList.toggle('open');o.classList.toggle('active');\" \
+ aria-label=\"Toggle navigation\">☰\n\
+\n",
);
html.push_str(&sidebar_html.replace(
&format!("\">{}", html_escape(&class.name)),
diff --git a/crates/beamtalk-cli/src/commands/doc/site.rs b/crates/beamtalk-cli/src/commands/doc/site.rs
index 73d4d3b65..2f636c1ff 100644
--- a/crates/beamtalk-cli/src/commands/doc/site.rs
+++ b/crates/beamtalk-cli/src/commands/doc/site.rs
@@ -1,11 +1,11 @@
// Copyright 2026 James Casey
// SPDX-License-Identifier: Apache-2.0
-//! Prose documentation and site landing page generation.
+//! Prose documentation, ADR, and site landing page generation.
//!
//! **DDD Context:** CLI / Documentation
-use camino::Utf8Path;
+use camino::{Utf8Path, Utf8PathBuf};
use miette::{Context, IntoDiagnostic, Result};
use std::fmt::Write as _;
use std::fs;
@@ -15,11 +15,19 @@ use super::highlighter::highlight_beamtalk;
use super::layout::{page_footer_simple, page_header};
use super::renderer::{html_escape, render_doc};
+// ---------------------------------------------------------------------------
+// Prose docs
+// ---------------------------------------------------------------------------
+
/// Generate prose documentation pages from markdown files.
+///
+/// `extra_links` is a list of `(source_fragment, dest_html)` pairs used to
+/// rewrite additional cross-references (e.g. ADR links) before rendering.
pub(super) fn generate_prose_docs(
docs_source: &Utf8Path,
site_root: &Utf8Path,
prose_pages: &[(&str, &str, &str)],
+ extra_links: &[(String, String)],
) -> Result<()> {
let docs_output = site_root.join("docs");
fs::create_dir_all(&docs_output)
@@ -48,23 +56,19 @@ pub(super) fn generate_prose_docs(
.into_diagnostic()
.wrap_err_with(|| format!("Failed to read '{source}'"))?;
- // Rewrite cross-references to sibling prose docs (.md → .html)
- let markdown = rewrite_prose_links(&markdown, prose_pages);
+ // Rewrite cross-references to sibling prose docs and ADRs
+ let markdown = rewrite_prose_links(&markdown, prose_pages, extra_links);
let page_title = format!("{title} — Beamtalk");
let mut html = String::new();
html.push_str(&page_header(&page_title, "../style.css", "../"));
html.push_str("
\n");
- html.push_str(
- "\n",
- );
+ html.push_str(SIDEBAR_TOGGLE);
html.push_str(&prose_nav(output_file, prose_pages));
html.push_str("\n");
html.push_str("\n");
html.push_str(&render_doc(&markdown));
@@ -91,6 +95,7 @@ fn prose_nav(active_file: &str, prose_pages: &[(&str, &str, &str)]) -> String {
html.push_str("\n");
html.push_str("\n");
html.push_str("\n");
@@ -109,16 +114,288 @@ fn prose_nav(active_file: &str, prose_pages: &[(&str, &str, &str)]) -> String {
/// Rewrite cross-references between prose docs from `.md` to `.html`.
///
-/// Prose markdown files contain links like `[principles](beamtalk-principles.md)`.
-/// After rendering, those need to point to the generated `.html` files.
-fn rewrite_prose_links(markdown: &str, prose_pages: &[(&str, &str, &str)]) -> String {
+/// Also applies `extra_links` rewrites (e.g. ADR source paths → rendered URLs).
+fn rewrite_prose_links(
+ markdown: &str,
+ prose_pages: &[(&str, &str, &str)],
+ extra_links: &[(String, String)],
+) -> String {
let mut result = markdown.to_string();
for &(source_file, output_file, _) in prose_pages {
result = result.replace(source_file, output_file);
}
+ for (source, dest) in extra_links {
+ result = result.replace(source.as_str(), dest.as_str());
+ }
result
}
+// ---------------------------------------------------------------------------
+// ADR generation
+// ---------------------------------------------------------------------------
+
+/// Metadata for a single Architecture Decision Record.
+struct AdrInfo {
+ /// Zero-padded number string, e.g. `"0001"`.
+ number: String,
+ /// Full stem of the source file, e.g. `"0001-no-compound-assignment"`.
+ slug: String,
+ /// Human title extracted from the H1, e.g. `"No Compound Assignment in Beamtalk"`.
+ title: String,
+ /// Output HTML filename, e.g. `"0001-no-compound-assignment.html"`.
+ output_file: String,
+}
+
+/// Generate ADR pages from `docs/ADR/*.md` files.
+///
+/// Returns a list of `(source_fragment, dest_html)` link rewriting pairs for
+/// use in prose doc rendering, e.g.:
+/// `("ADR/0004-persistent-workspace-management.md",
+/// "../adr/0004-persistent-workspace-management.html")`.
+///
+/// Returns an empty vec (and does nothing) if the ADR directory does not exist.
+pub(super) fn generate_adr_docs(
+ docs_source: &Utf8Path,
+ site_root: &Utf8Path,
+) -> Result> {
+ let adr_source = docs_source.join("ADR");
+ if !adr_source.exists() {
+ return Ok(Vec::new());
+ }
+
+ let adr_output = site_root.join("adr");
+ fs::create_dir_all(&adr_output)
+ .into_diagnostic()
+ .wrap_err("Failed to create adr/ output directory")?;
+
+ let adrs = discover_adrs(&adr_source)?;
+ if adrs.is_empty() {
+ return Ok(Vec::new());
+ }
+
+ // Render each ADR page
+ for adr in &adrs {
+ let source_path = adr_source.join(format!("{}.md", adr.slug));
+ let content = fs::read_to_string(&source_path)
+ .into_diagnostic()
+ .wrap_err_with(|| format!("Failed to read ADR '{}'", adr.slug))?;
+ // Rewrite within-ADR links: sibling .md → .html (same directory)
+ let content = rewrite_adr_internal_links(&content, &adrs);
+ render_adr_page(adr, &adrs, &content, &adr_output)?;
+ }
+
+ // Render ADR index
+ render_adr_index(&adrs, &adr_output)?;
+
+ println!("Generated {} ADR page(s)", adrs.len());
+
+ // Return link-rewriting pairs for prose doc rendering.
+ // Prose pages live in /docs/, so the relative path to /adr/ is ../adr/.
+ let links = adrs
+ .iter()
+ .map(|a| {
+ (
+ format!("ADR/{}.md", a.slug),
+ format!("../adr/{}", a.output_file),
+ )
+ })
+ .collect();
+ Ok(links)
+}
+
+/// Discover and parse ADR files from the given directory.
+fn discover_adrs(adr_source: &Utf8Path) -> Result> {
+ let mut adrs: Vec = fs::read_dir(adr_source)
+ .into_diagnostic()
+ .wrap_err_with(|| format!("Failed to read ADR directory '{adr_source}'"))?
+ .filter_map(|entry| {
+ let entry = entry.ok()?;
+ let path = Utf8PathBuf::from_path_buf(entry.path()).ok()?;
+ let name = path.file_name()?.to_string();
+ // Skip non-markdown and the template
+ if path.extension() != Some("md") || name == "TEMPLATE.md" {
+ return None;
+ }
+ let stem = path.file_stem()?.to_string();
+ // Must start with digits (NNNN-)
+ let number: String = stem.chars().take_while(char::is_ascii_digit).collect();
+ if number.is_empty() {
+ return None;
+ }
+ let content = fs::read_to_string(&path).ok()?;
+ let title = extract_adr_title(&content);
+ Some(AdrInfo {
+ number,
+ slug: stem,
+ title,
+ output_file: format!("{}.html", path.file_stem()?),
+ })
+ })
+ .collect();
+
+ adrs.sort_by(|a, b| a.number.cmp(&b.number));
+ Ok(adrs)
+}
+
+/// Extract the human title from an ADR's first H1 heading.
+///
+/// Strips the `ADR NNNN: ` prefix if present, e.g.:
+/// `# ADR 0001: No Compound Assignment` → `"No Compound Assignment"`.
+fn extract_adr_title(content: &str) -> String {
+ for line in content.lines() {
+ if let Some(rest) = line.strip_prefix("# ") {
+ // Strip "ADR NNNN: " prefix (case-insensitive check)
+ let rest_lower = rest.to_ascii_lowercase();
+ if rest_lower.starts_with("adr ") {
+ if let Some(colon) = rest.find(": ") {
+ return rest[colon + 2..].trim().to_string();
+ }
+ }
+ return rest.trim().to_string();
+ }
+ }
+ String::from("Untitled ADR")
+}
+
+/// Rewrite sibling ADR links within an ADR page (`.md` → `.html`, same dir).
+fn rewrite_adr_internal_links(content: &str, adrs: &[AdrInfo]) -> String {
+ let mut result = content.to_string();
+ for adr in adrs {
+ let md = format!("{}.md", adr.slug);
+ result = result.replace(&md, &adr.output_file);
+ }
+ result
+}
+
+/// Render a single ADR page.
+fn render_adr_page(
+ adr: &AdrInfo,
+ all_adrs: &[AdrInfo],
+ content: &str,
+ adr_output: &Utf8Path,
+) -> Result<()> {
+ let page_title = format!("ADR {} — Beamtalk", adr.number);
+ let mut html = String::new();
+ html.push_str(&page_header(&page_title, "../style.css", "../"));
+ html.push_str("
\n");
+ html.push_str(SIDEBAR_TOGGLE);
+ html.push_str(&adr_nav(&adr.output_file, all_adrs));
+ html.push_str("\n");
+ html.push_str("\n");
+ html.push_str(&render_doc(content));
+ html.push_str(" \n");
+ html.push_str(&page_footer_simple());
+
+ let out_path = adr_output.join(&adr.output_file);
+ fs::write(&out_path, html)
+ .into_diagnostic()
+ .wrap_err_with(|| format!("Failed to write {}", adr.output_file))?;
+ debug!("Generated {out_path}");
+ Ok(())
+}
+
+/// Render the ADR index page listing all decisions.
+fn render_adr_index(adrs: &[AdrInfo], adr_output: &Utf8Path) -> Result<()> {
+ let mut html = String::new();
+ html.push_str(&page_header(
+ "Architecture Decisions — Beamtalk",
+ "../style.css",
+ "../",
+ ));
+ html.push_str("
\n");
+ html.push_str(SIDEBAR_TOGGLE);
+ html.push_str(&adr_nav("index.html", adrs));
+ html.push_str("\n");
+ html.push_str("\n");
+ html.push_str(" \n");
+ html.push_str(&page_footer_simple());
+
+ let index_path = adr_output.join("index.html");
+ fs::write(&index_path, html)
+ .into_diagnostic()
+ .wrap_err("Failed to write adr/index.html")?;
+ debug!("Generated {index_path}");
+ Ok(())
+}
+
+/// Build the sidebar navigation for ADR pages.
+fn adr_nav(active_file: &str, adrs: &[AdrInfo]) -> String {
+ let mut html = String::new();
+ html.push_str("\n");
+ html
+}
+
+// ---------------------------------------------------------------------------
+// Landing page
+// ---------------------------------------------------------------------------
+
+/// Sidebar toggle button + tap-to-close overlay (shared across page types).
+const SIDEBAR_TOGGLE: &str = "\
+\n\
+\n";
+
/// Return (emoji, description) for a prose doc card on the landing page.
///
/// Keyed by `output_file` (the stable `.html` filename) rather than display
@@ -154,6 +431,7 @@ fn landing_card_meta(output_file: &str) -> (&'static str, &'static str) {
"🔒",
"Security model, threat analysis, and sandboxing for untrusted code.",
),
+ "tooling.html" => ("🛠", "CLI, REPL, VS Code extension, and testing framework."),
"known-limitations.html" => (
"⚠️",
"Current limitations and unimplemented features to be aware of.",
@@ -236,6 +514,15 @@ pub(super) fn write_site_landing_page(
);
html.push_str("\n");
+ // ADR card
+ html.push_str("\n");
+ html.push_str("📐\n");
+ html.push_str("
Architecture Decisions
\n"); + html.push_str( + "Key design decisions with context, alternatives considered, \ + and consequences.
\n", + ); + html.push_str("- \n");
+ for adr in adrs {
+ let _ = writeln!(
+ html,
+ "
- {num} — {title} ", + file = adr.output_file, + num = html_escape(&adr.number), + title = html_escape(&adr.title), + ); + } + html.push_str("
Architecture Decisions
\n"); + html.push_str( + "Key design decisions — context, alternatives considered, and consequences.
\n", + ); + html.push_str("\n"); + // Prose docs cards for &(_, file, title) in prose_pages { let (emoji, desc) = landing_card_meta(file); diff --git a/docs/beamtalk-language-features.md b/docs/beamtalk-language-features.md index b894e529d..a2d565ec6 100644 --- a/docs/beamtalk-language-features.md +++ b/docs/beamtalk-language-features.md @@ -4,7 +4,7 @@ Planned language features for beamtalk. See [beamtalk-principles.md](beamtalk-pr **Status:** Active development — implemented features are stable; planned sections are marked inline. -**Syntax note:** Beamtalk uses a cleaned-up Smalltalk syntax: `//` comments (not `"..."`), standard math precedence (not left-to-right), and optional statement terminators (newlines work). +**Syntax note:** Beamtalk uses a modernised Smalltalk syntax: `//` comments (not `"..."`), standard math precedence (not left-to-right), and optional statement terminators (newlines work). --- @@ -160,7 +160,7 @@ Actor subclass: Counter ProtoObject (minimal - identity, DNU) └─ Object (reflection + new) ├─ Integer, String (primitives) - ├─ Value (immutable value objects - ADR 0042) + ├─ Value (immutable value objects) │ └─ Point, Color (value types) └─ Actor (process-based + spawn) └─ Counter, Server (actors) @@ -801,16 +801,25 @@ Pattern matching can bind variables in match arms: Hot code reload via message sends — no dedicated `patch` syntax needed. ```beamtalk -// Replace a method on a running class +// Canonical Counter (already running in the workspace) +Actor subclass: Counter + state: value = 0 + increment => self.value := self.value + 1 + getValue => self.value + +// Replace a single method — existing instances pick it up immediately Counter >> increment => Telemetry log: "incrementing" self.value := self.value + 1 -// Redefine a class to update all future instances +// Redefine the class to add state — new instances get the updated shape Actor subclass: Counter - state: value = 0, lastModified = nil - increment => self.value := self.value + 1 - getValue => ^self.value + state: value = 0 + state: lastModified = nil + increment => + self.value := self.value + 1 + self.lastModified := DateTime now + getValue => self.value ``` --- @@ -1297,95 +1306,4 @@ The full list of structural intrinsics: `actorSpawn`, `actorSpawnWith`, `blockVa --- -## Tooling - -Tooling is part of the language, not an afterthought. Beamtalk is designed to be used interactively. - -### CLI Tools - -```bash -# Project management -beamtalk new myapp # Create new project -beamtalk build # Compile to BEAM -beamtalk run # Compile and start -beamtalk check # Check for errors without compiling -beamtalk daemon start/stop # Manage compiler daemon - -# Development -beamtalk repl # Interactive REPL -``` - -### REPL Features - -```beamtalk -// Spawn and interact -counter := Counter spawn -counter increment -counter getValue // => 1 -``` - -### VS Code Extension - -The [Beamtalk VS Code extension](https://github.com/jamesc/beamtalk/tree/main/editors/vscode) provides: - -- Syntax highlighting for `.bt` files -- Language Server Protocol (LSP) integration -- Error diagnostics with source spans - -### Testing Framework - -Beamtalk includes a native test framework inspired by Smalltalk's SUnit. - -```beamtalk -// stdlib/test/counter_test.bt - -TestCase subclass: CounterTest - - testInitialValue => - self assert: (Counter spawn getValue) equals: 0 - - testIncrement => - self assert: (Counter spawn increment) equals: 1 - - testMultipleIncrements => - counter := Counter spawn - 3 timesRepeat: [counter increment] - self assert: (counter getValue) equals: 3 -``` - -Each test method gets a fresh instance with `setUp` → test → `tearDown` lifecycle. - -#### Assertion Methods - -| Method | Description | Example | -|--------|-------------|---------| -| `assert:` | Assert condition is true | `self assert: (x > 0)` | -| `assert:equals:` | Assert two values are equal | `self assert: result equals: 42` | -| `deny:` | Assert condition is false | `self deny: list isEmpty` | -| `should:raise:` | Assert block raises error | `self should: [1 / 0] raise: #badarith` | -| `fail:` | Unconditional failure | `self fail: "not implemented"` | - -#### Running Tests - -```bash -beamtalk test -``` - -#### REPL Integration - -Run tests interactively from the REPL using either `:` shortcuts or native message sends: - -```text -> :load stdlib/test/counter_test.bt -Loaded CounterTest - -> :test CounterTest -Running 1 test class... - ✓ testIncrement - ✓ testMultipleIncrements -2 passed, 0 failed - -// Equivalent native API — works from compiled code too: -> (Workspace test: CounterTest) failed -// => 0 -``` +See [Tooling](beamtalk-tooling.md) for CLI tools, REPL, VS Code extension, and testing framework. diff --git a/docs/beamtalk-tooling.md b/docs/beamtalk-tooling.md new file mode 100644 index 000000000..20f3e1e86 --- /dev/null +++ b/docs/beamtalk-tooling.md @@ -0,0 +1,87 @@ +# Tooling + +Tooling is part of the language, not an afterthought. Beamtalk is designed to be used interactively. + +## CLI Tools + +```bash +# Project management +beamtalk new myapp # Create new project +beamtalk build # Compile to BEAM +beamtalk run # Compile and start +beamtalk check # Check for errors without compiling +beamtalk daemon start/stop # Manage compiler daemon + +# Development +beamtalk repl # Interactive REPL +beamtalk test # Run test suite +``` + +## REPL Features + +```beamtalk +// Spawn and interact +counter := Counter spawn +counter increment +counter getValue // => 1 +``` + +## VS Code Extension + +The [Beamtalk VS Code extension](https://github.com/jamesc/beamtalk/tree/main/editors/vscode) provides: + +- Syntax highlighting for `.bt` files +- Language Server Protocol (LSP) integration +- Error diagnostics with source spans + +## Testing Framework + +Beamtalk includes a native test framework inspired by Smalltalk's SUnit. + +```beamtalk +// stdlib/test/counter_test.bt + +TestCase subclass: CounterTest + + testInitialValue => + self assert: (Counter spawn getValue) equals: 0 + + testIncrement => + self assert: (Counter spawn increment) equals: 1 + + testMultipleIncrements => + counter := Counter spawn + 3 timesRepeat: [counter increment] + self assert: (counter getValue) equals: 3 +``` + +Each test method gets a fresh instance with `setUp` → test → `tearDown` lifecycle. + +### Assertion Methods + +| Method | Description | Example | +|--------|-------------|---------| +| `assert:` | Assert condition is true | `self assert: (x > 0)` | +| `assert:equals:` | Assert two values are equal | `self assert: result equals: 42` | +| `deny:` | Assert condition is false | `self deny: list isEmpty` | +| `should:raise:` | Assert block raises error | `self should: [1 / 0] raise: #badarith` | +| `fail:` | Unconditional failure | `self fail: "not implemented"` | + +### REPL Integration + +Run tests interactively from the REPL using either `:` shortcuts or native message sends: + +```text +> :load stdlib/test/counter_test.bt +Loaded CounterTest + +> :test CounterTest +Running 1 test class... + ✓ testIncrement + ✓ testMultipleIncrements +2 passed, 0 failed + +// Equivalent native API — works from compiled code too: +> (Workspace test: CounterTest) failed +// => 0 +``` diff --git a/stdlib/src/README.md b/stdlib/src/README.md index 934675fdf..09e4d844b 100644 --- a/stdlib/src/README.md +++ b/stdlib/src/README.md @@ -2,52 +2,6 @@ Copyright 2026 James Casey SPDX-License-Identifier: Apache-2.0 --> -# Beamtalk Standard Library - The standard library for Beamtalk, where everything is a message send. -## Class Hierarchy - -```text -ProtoObject (minimal root - identity, DNU) - └─ Object (value types - reflection, nil testing) - ├─ Integer, Float, String, Atom (sealed primitives) - ├─ True, False, Nil (sealed primitives) - ├─ Block (closures) - ├─ Collection (abstract) - │ ├─ SequenceableCollection - │ │ ├─ Array (Erlang tuple) - │ │ └─ List (Erlang list) - │ ├─ Set (ordsets) - │ └─ Dictionary (Erlang map) - ├─ Beamtalk (system reflection) - └─ Actor (process-based) - └─ (user actors: Counter, Worker, etc.) -``` - -See each `.bt` file for full API documentation and usage examples. - -## BEAM Mapping - -| Beamtalk | Erlang/BEAM | Has Process? | -|----------|-------------|--------------| -| `ProtoObject` | Abstract root | — | -| `Object` | Value type root | ❌ | -| `Actor` | `gen_server` process | ✅ | -| `Integer` | Erlang integer | ❌ | -| `Float` | Erlang float | ❌ | -| `True` / `False` | Atoms `true` / `false` | ❌ | -| `Nil` | Atom `nil` | ❌ | -| `Atom` | Erlang atom | ❌ | -| `Block` | Anonymous fun (closure) | ❌ | -| `String` | Binary `<<"UTF-8">>` | ❌ | -| `Array` | Erlang tuple `{...}` | ❌ | -| `List` | Erlang list `[...]` | ❌ | -| `Set` | `ordsets` (sorted list) | ❌ | -| `Dictionary` | Erlang map `#{...}` | ❌ | - -## Design - -- [Object Model](../docs/beamtalk-object-model.md) — class hierarchy and metaclasses -- [Design Principles](../docs/beamtalk-principles.md) — philosophy and rationale -- [Language Features](../docs/beamtalk-language-features.md) — full syntax specification +See each class page for full API documentation and usage examples.