magpie: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

Magpie is a Rust workspace (Cargo.toml at repo root) with compiler/tooling crates in crates/. Core flow is split across frontend crates (magpie_lex, magpie_parse, magpie_ast), analysis crates (magpie_sema, magpie_hir, magpie_types, magpie_own), and backend crates (magpie_mpir, magpie_arc, magpie_codegen_llvm, magpie_codegen_wasm). CLI entrypoint is crates/magpie_cli/src/main.rs.
Pipeline orchestration is centered in magpie_driver; runtime and platform/tooling crates (for example magpie_rt, magpie_pkg, magpie_memory, magpie_web, magpie_gpu) are also workspace-critical. Use root Cargo.toml workspace members as the source of truth for full crate inventory.
Language fixtures live in tests/fixtures/*.mp, integration tests in tests/integration_test.rs, and standard library modules in std/std.*/*.mp.

Build, Test, and Development Commands

Use Cargo from repo root:

cargo build -p magpie_cli              # build CLI
cargo build --workspace                # build all crates
cargo run -p magpie_cli -- --help      # inspect CLI
cargo test --workspace                 # full test suite
cargo test --test integration_test     # fixture-driven integration tests
cargo test -p magpie_parse snapshot_hello_parser_output

For CLI usage, global flags must come before subcommands:

cargo run -p magpie_cli -- --entry tests/fixtures/hello.mp --emit mpir,llvm-ir build

Toolchain notes (important for backend/link workflows):

• lli is needed for common magpie run LLVM-IR execution flow.
• clang (and often llc) is needed for --emit exe / native linking.
• Missing native tools usually surface as link diagnostics such as MPLINK01 / MPLINK02.
• In --llm mode, builds may auto-run formatting unless --no-auto-fmt; expect possible source rewrites when this mode is enabled.

CLI path resolution pitfall:

• --entry is resolved relative to the current working directory (CWD), not always the repo root.
• If a command fails to find sources, check CWD first before changing code.