lehit 0.2.0

Embeddable Lehit language frontend and Cranelift JIT runtime
Documentation
# Development guide

## Prerequisites

- A current stable Rust toolchain with Edition 2024 support.
- `rustfmt` for formatting.
- `clippy` for advisory linting.
- A host target supported by the selected Cranelift version.

No external service, database, or code generator is required.

## Validation commands

Run the narrowest relevant test first, then the complete baseline:

```text
cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace --all-targets
cargo run --example embed
cargo doc --workspace --no-deps
```

Clippy is useful, but the repository currently contains a warning backlog:

```text
cargo clippy --workspace --all-targets --all-features
```

Do not use `-D warnings` as a project-wide gate until the roadmap cleanup is complete. A change should still avoid adding warnings in files it touches.

### Slow external filesystems

Cargo may report that incremental-cache hard links are unsupported when the repository is on removable or non-native storage. This is not a source-code failure. Build in a local directory to avoid the penalty:

```text
CARGO_TARGET_DIR=/tmp/lehit-target CARGO_INCREMENTAL=0 cargo test --workspace --all-targets
```

## Change workflow

1. Identify the owning layer and its invariants in `docs/architecture.md`.
2. Add a characterization or regression test before changing behavior.
3. Keep mechanical moves separate from algorithm changes when practical.
4. Update all source-of-truth documentation and examples in the same change.
5. Run focused tests, then the workspace test suite and embedding example.
6. Record unresolved risk in `docs/maintenance-roadmap.md`; do not hide it with broad lint allowances.

## Common change recipes

### Add or change syntax

1. Add/update tokens in `src/parsing/lexer/token.rs` only when syntax cannot be expressed using existing tokens.
2. Add lexer edge-case tests in `src/parsing/lexer/mod.rs`.
3. Update AST models and grammar under `src/parsing/ast/`.
4. Add parser-level regression tests in `src/parsing/mod.rs`.
5. Update declaration collection, type lowering, and body analysis as applicable.
6. Add at least one runtime integration test if the construct reaches codegen.

Keep whitespace behavior in grammar, not in token variants. For example, empty parentheses are parsed from `(` and `)` rather than represented by a special `()` token.

### Change the core library

1. Edit the relevant `src/core_lib/*.lt` file.
2. Treat that file as the semantic source of truth.
3. Do not mirror declarations in `RustLib::Script.types` or `FunctionBody::Ir`.
4. Ensure `parsing::tests::parses_all_core_library_sources` and runtime workspace tests pass.
5. Add a semantic/runtime test for observable behavior, not a test of duplicated metadata.

### Add a semantic pass

- Define explicit input, output, and invalidation rules.
- Use canonical paths and stable IDs rather than parallel strings where possible.
- Return structured errors with source spans.
- Avoid reading runtime/JIT state directly; introduce a narrow query interface if layout facts are required.
- Add unit tests for pass-local rules and an end-to-end workspace test.

### Add a native Rust type or function

1. Define the Lehit source contract in `Script.content`.
2. Register only explicitly exported fields/variants/functions.
3. Define physical ABI metadata through `NativeAbi` or the derive macro.
4. Add negative tests for mismatched visibility, fields, variants, and signatures.
5. Document every `unsafe` assumption: layout, call convention, pointer lifetime, and unwind behavior.

### Change JIT or call ABI

- Update `docs/safety.md` first or in the same change.
- Test scalar and aggregate arguments/returns, checked and direct modes, and reload leases.
- Include negative ABI-validation tests.
- Consider target register classes and alignment; matching byte size alone is insufficient.

## Code organization rules

- Use correctly spelled, domain-specific names; pre-release APIs should be renamed rather than preserved through typo aliases.
- Keep module facades (`mod.rs`) focused on module docs and intentional re-exports.
- Prefer one authoritative representation over synchronized mirrors.
- Keep source/semantic identity separate from physical runtime layout.
- Avoid public fields when they can violate invariants; use constructors/builders and validation.
- Every `unsafe` block must explain the invariant that makes it sound.
- Do not add comments that merely repeat the code.

## Test placement

- Lexer and parser characterization tests live close to their public entry points.
- Semantic pass tests live with the pass until shared fixtures justify `semantic/test_support.rs`.
- Cross-layer lifecycle and ABI regressions should move toward top-level `tests/` files.
- Proc-macro diagnostics should use UI/compile-fail tests once `trybuild` is introduced.

## Definition of done

A change is complete when:

- behavior is covered by a test;
- formatting and workspace checks pass;
- the complete test suite passes;
- public behavior, safety contracts, and examples are updated;
- no new duplicate source of truth or untracked technical debt is introduced.