lux/CLAUDE.md

Lux Project Notes

Development Environment

This is a Nix environment. Tools like cargo, rustc, clippy, etc. are not available in the base shell.

To run Rust/Cargo commands, use one of:

nix develop --command cargo test
nix develop --command cargo build
nix develop --command cargo clippy
nix develop --command cargo fmt

Or enter the development shell first:

nix develop
# then run commands normally
cargo test

The lux binary can be run directly if already built:

./target/debug/lux test
./target/release/lux <file.lux>

For additional tools not in the dev shell:

nix-shell -p <program>

Development Workflow

When making changes:

1. Always run tests: cargo check && cargo test - fix all errors and warnings
2. Lint the Lux code: ./target/release/lux lint - fix warnings
3. Check Lux code: ./target/release/lux check - type check + lint in one pass
4. Format Lux code: ./target/release/lux fmt - auto-format all .lux files
5. Write tests: Add tests to cover new code
6. Document features: Provide documentation and tutorials for new features/frameworks
7. Fix language limitations: If you encounter parser/type system limitations, fix them (without regressions on guarantees or speed)
8. Git commits: Always use --no-gpg-sign flag

Post-work checklist (run after each major piece of work)

nix develop --command cargo check       # No Rust errors
nix develop --command cargo test        # All tests pass (currently 381)
./target/release/lux check              # Type check + lint all .lux files
./target/release/lux fmt                # Format all .lux files
./target/release/lux lint               # Standalone lint pass

IMPORTANT: Always verify Lux code you write:

• Run with interpreter: ./target/release/lux file.lux
• Compile to binary: ./target/release/lux compile file.lux
• Both must work before claiming code is functional
• The C backend has limited effect support (Console, File only - no HttpServer, Http, etc.)

CLI Commands & Aliases

Command	Alias	Description
lux fmt	lux f	Format .lux files
lux test	lux t	Run test suite
lux check	lux k	Type check + lint
lux lint	lux l	Lint only (with --explain for detailed help)
lux serve	lux s	Static file server
lux compile	lux c	Compile to binary

Code Quality

• Fix all compiler warnings before committing
• Ensure all tests pass (currently 381 tests)
• Add new tests when adding features
• Keep examples and documentation in sync

Lux Language Notes

Top-level expressions

Bare run expressions are not allowed at top-level. You must wrap them in a let binding:

// WRONG: parse error
run main() with {}

// CORRECT
let output = run main() with {}

String methods

Lux uses module-qualified function calls, not method syntax on primitives:

// WRONG: not valid syntax
path.endsWith(".html")

// CORRECT
String.endsWith(path, ".html")

Available String functions

Key string functions (all in String. namespace):

• String.length(s) - get length
• String.startsWith(s, prefix) - check prefix
• String.endsWith(s, suffix) - check suffix
• String.split(s, delimiter) - split into list
• String.join(list, delimiter) - join list
• String.substring(s, start, end) - extract substring
• String.indexOf(s, needle) - find position (returns Option)
• String.replace(s, old, new) - replace occurrences
• String.trim(s) - trim whitespace
• String.toLower(s) / String.toUpper(s) - case conversion