How Spanda API references relate to each other — language surface, compiler crates, JSON contracts, and tutorials.
flowchart TB
LANG["Spanda language (.sd)"]
REF["spanda-reference.md"]
GUIDE["spanda-language.md + topic guides"]
API["api-reference.md"]
CONTRACT["api-contract.json"]
CRATES["crates/README.md + per-crate READMEs"]
TUTOR["tutorials/ + examples/"]
LANG --> REF
LANG --> GUIDE
REF --> TUTOR
GUIDE --> TUTOR
API --> CRATES
CONTRACT --> API
| Level | Document | What it indexes |
|---|---|---|
| 1 — Language | spanda-reference.md | Keywords, std.*, builtins, CLI man-style pages |
| 1 — Language | spanda-language.md | Tutorial-style semantics and syntax |
| 2 — Compiler API | api-reference.md | Rust crates + TypeScript packages (grouped by lean-core layer) |
| 3 — Wire format | api-contract.json | JSON shapes for check, verify, run (CLI, WASM, Node) |
| 4 — Crate layout | crates/README.md | Workspace dependency rules and README index |
| 5 — Learning | tutorials/README.md, examples/README.md | Lessons and runnable .sd programs |
spanda_core::)External embedders depend on spanda-core and import spanda_core::check, spanda_core::run,
etc. The facade re-exports workspace crates and keeps thin compatibility shims.
In-repo code (spanda-cli, spanda-node, spanda-wasm, …) imports owning crates directly:
| Use case | Import |
|---|---|
| Compile / run | spanda_driver::{check, run, compile} |
| AST | spanda_ast::nodes::Program |
| Parse | spanda_parser::parse |
| Verify | spanda_core::verify_compatibility (or spanda_core::hardware_verify) |
| Transport routing | spanda_transport_routing::RoutingCommBus |
| Live hooks | spanda_transport_routing::transport_live |
Full mapping table: api-reference.md § Facade → workspace.
| Package | Role | API index |
|---|---|---|
src/ |
Parser/runtime tests, provider classification | api-reference.md § TypeScript core |
@spanda/lsp |
Language server | api-reference.md § @spanda/lsp |
@davalgi-spanda/web |
Playground | api-reference.md § @davalgi-spanda/web |
@spanda/native |
N-API wrapper | api-reference.md § @spanda/native |
TypeScript delegates to the Rust CLI when target/release/spanda is available.
# Language reference (keywords, std.*, CLI)
python3 scripts/generate_spanda_reference.py
# or: spanda reference --out docs/spanda-reference.md --man-dir docs/man
# Rust + TypeScript compiler API index
python3 scripts/generate_api_reference.py
Run after large API or crate-layout changes. See CONTRIBUTING.md.