Skip to content

Latest commit

 

History

History
84 lines (65 loc) · 3.96 KB

AGENTS.md

File metadata and controls

84 lines (65 loc) · 3.96 KB

Repository Guidelines

Core Rust, MLIR, and C/FFI boundary code should include explicit comments whenever safety assumptions, phase contracts, missing support, or non-obvious invariants would otherwise be unclear.

Project Structure & Module Organization

Zmeu is a Rust compiler prototype with staged HIR, MIR, MLIR, and native backend paths. Core Rust lives in src/, including src/mir_v1, src/mlir, src/runtime, and src/syntax_v1. Runtime C support is in runtime/, standard library sources are in std/, and MLIR dialect/pass code is under mlir/. Tests are grouped through tests/phase0.rs and tests/phase0/. Examples live in examples/; benchmark fixtures live in benchmarks/. Use STATUS.md and docs/README.md as the active documentation map.

Build, Test, and Development Commands

  • cargo fmt --check: verify Rust formatting.
  • cargo test: run the default interpreter/frontend regression suite.
  • cargo clippy --all-targets -- -D warnings: run default lint checks.
  • cargo build --features mlir-backend: build MLIR support.
  • env -u MLIR_DIR -u LLVM_DIR -u ZMEU_MLIR_DIR -u ZMEU_LLVM_DIR cargo test --features mlir-backend: run MLIR tests.
  • cargo run -- check examples/core/control_flow.zmeu: check a sample program.
  • cargo run --features mlir-backend -- build examples/core/control_flow.zmeu -o /tmp/zmeu-control-flow: build natively.
  • ZMEU_BIN=target/release/zmeu benchmarks/ir_counts.sh: collect IR counters.

Coding Style & Naming Conventions

Use standard Rust formatting and keep lints warning-free. Prefer names that match existing compiler phases: HIR, MIR, CFG MIR, MLIR, and runtime. Rust modules/functions use snake_case; types/variants use UpperCamelCase.

Architecture Rules

Every feature can expand across HIR, MIR, diagnostics, borrowing, MLIR, runtime, and examples, so design the full path first. If a feature, syntax change, or implementation path appears likely to harm Zmeu's goals, say so before implementing it. Explain the downside, then propose better-scoped variants that preserve the compiler contract, safety boundary, diagnostics, and trajectory.

The core pipeline rule is:

checker proves safety
lowering preserves facts
backend assumes facts
runtime defends only where needed
diagnostics retain source spans through every frontend phase

LLVM codegen must not become the safety checker. Invalid programs should never reach codegen.

Testing Guidelines

Add semantic tests before backend-only changes. Put phase0 coverage in tests/phase0/*.rs, and use small examples/ fixtures. Diagnostics need stable rule IDs, deterministic text, source spans, expected/found wording, and concrete fix guidance. Run default and mlir-backend tests when touching lowering, runtime, native builds, or MLIR.

Commit & Pull Request Guidelines

PR titles must use Conventional Commit format because squash-merge titles feed Release Please changelogs and version bumps. Use lowercase types such as feat:, fix:, perf:, docs:, refactor:, test:, chore:, ci:, or build:; add ! for breaking changes. Do not include [codex] in PR titles.

Use descriptive commit messages that make the implemented change inferable from history. Prefer an imperative subject plus a body for non-trivial work, and use Conventional Commit subjects for merge-bound commits: feat: add Result CLI fixture followed by bullets explaining parser/checker/runtime effects and tests. PRs should explain motivation, changed compiler phases, verification commands, benchmark threshold updates, and intentional diagnostic wording changes.

Agent-Specific Instructions

Do not treat archived plans as permission to broaden the language surface. When MLIR syntax, dialect design, lowering, TableGen/ODS, or Rust/C++ MLIR boundary details are unclear, consult both docs/zmeu-mlir-skill.md and the official MLIR documentation at https://mlir.llvm.org/docs/ before guessing. Prefer small executable milestones, deterministic output, and inspectable compiler facts.