# axon-frontend
Pure compiler frontend for the AXON programming language: lexer, parser,
AST, epistemic type system, type checker, IR generator, and the compile-time
checker that sits above them.
## Design contract
**Zero runtime dependencies.** This crate must never depend on `tokio`,
`axum`, `sqlx`, `reqwest`, `aws-*`, `jsonwebtoken`, or any other crate
that pulls in networking, persistence, or async runtime. The only
allowed external dep is `serde` (and its proc-macro derive chain).
This contract is enforced in CI: any PR that adds a non-`serde`
dependency to `axon-frontend/Cargo.toml` fails the dep-audit job.
## Who uses this crate
- **`axon` crate** (the AXON runtime, in `../axon-rs/`) — re-exports
`axon-frontend` modules so existing callers keep working.
- **`axon-lsp`** (the Language Server, separate repo) — consumes the
frontend directly without dragging runtime deps.
- **Future tooling** — analyzers, formatters, linters, IDE plugins.
## Module layout
```
axon-frontend/src/
├── lib.rs re-exports the public modules
├── tokens.rs token enum + keyword tables (leaf)
├── lexer.rs source text → tokens (→ tokens)
├── ast.rs AST node definitions + helpers (leaf)
├── parser.rs tokens → AST (→ ast, tokens)
├── epistemic.rs epistemic type primitives (HashMap/HashSet only) (leaf)
├── type_checker.rs AST → type-checked AST (→ ast, epistemic)
├── ir_nodes.rs IR node definitions (leaf)
├── ir_generator.rs AST → IR (→ ast, ir_nodes)
└── checker.rs top-level compile-time checker (→ ast, lexer, parser, type_checker)
```
## Byte-identical parity with Python reference
The AXON project maintains byte-identical parity between a Python
reference implementation (in `../axon/`) and the Rust native runtime.
Because `axon-frontend` implements the parsing + type-checking layer
of the Rust side, its outputs MUST match the Python reference on the
golden-file test corpus. PRs that diverge are release blockers.