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

Commit after every piece of work

After completing each logical unit of work, commit immediately. Do not let changes accumulate uncommitted across multiple features. Each commit should be a single logical change (one feature, one bugfix, etc.). Use --no-gpg-sign flag for all commits.

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