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

Documenting Lux Language Errors

When working on any major task that involves writing Lux code, document every language error, limitation, or surprising behavior you encounter. This log is optimized for LLM consumption so future sessions can avoid repeating mistakes.

File: Maintain an ISSUES.md in the relevant project directory (e.g., ~/src/blu-site/ISSUES.md).

Format for each entry:

## Issue N: <Short descriptive title>

**Category**: Parser limitation | Type checker gap | Missing feature | Runtime error | Documentation gap
**Severity**: High | Medium | Low
**Status**: Open | **Fixed** (commit hash or version)

<1-2 sentence description of the problem>

**Reproduction:**
```lux
// Minimal code that triggers the issue

Error message: <exact error text>

Workaround:

Fix: <if fixed, what was changed and where>

**Rules:**
- Add new issues as you encounter them during any task
- When a previously documented issue gets fixed, update its status to **Fixed** and note the commit/version
- Remove entries that are no longer relevant (e.g., the feature was redesigned entirely)
- Keep the summary table at the bottom of ISSUES.md in sync with the entries
- Do NOT duplicate issues already documented -- check existing entries first

## 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:
```lux
// 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