Imported from DrEden33773/sysy (AGENTS.md). Install upstream with npx skills add DrEden33773/sysy. Copyright stays with the author.

Repository Agent Guide

This repository contains a from-scratch Rust 2024 implementation of the PKU MiniC SysY compiler practice target. Keep durable repository artifacts in English.

Core Constraints

• Do not copy or port existing SysY compiler implementations. Official PKU tools and public fixtures may be used only for validation.
• Preserve the required CLI:
  • compiler -koopa input.sy -o output.koopa
  • compiler -riscv input.sy -o output.s
  • compiler -perf input.sy -o output.s
• Keep the compiler stable-compatible with the workspace rust-version and edition = "2024".
• Treat docs/optimization.md as the current Lv9+ scope source. PKU-aligned representative optimization coverage is the target unless the maintainer explicitly reopens the broader research-grade plan.

Refactoring Rules

• Prefer files under roughly 800 lines. Existing implementation files should stay below a 1200-line hard cap unless a documented exception is unavoidable.
• Split by compiler topic: frontend parsing/lowering, SSA model, mem2reg, scalar optimization, register allocation, machine optimization, and backend rendering.
• Never use include!() anywhere in this repository. Split implementation with normal Rust modules, explicit imports, and the narrowest practical visibility, such as pub(in crate::backend::ssa) for internal cross-module helpers.
• Keep refactors semantic-preserving unless the task explicitly asks for a behavior change. Run tests before claiming success.

Comments and Documentation

• Public types and public functions need /// doc comments explaining purpose, return behavior, and errors when relevant.
• Use // comments for non-obvious why: conservative correctness assumptions, ABI details, SSA/CFG invariants, alias barriers, pass-order dependencies, and validation boundaries.
• Avoid comments that restate obvious code. Prefer better names or smaller helpers first.
• Keep all code comments in English.
• Keep Markdown prose paragraphs on a single physical line. Use a blank line, not a single newline, to separate prose paragraphs; preserve intentional Markdown structure such as headings, lists, tables, and code fences.

Progress Rhythm

• Do not advance one tiny slice at a time by default. Before implementation, inspect the remaining backlog and group related slices into a medium-sized topic that can be designed, implemented, tested, documented, and committed together.
• Keep docs/progress.md, docs/verification.md, and docs/optimization.md current when the change affects milestones, validation evidence, or optimization scope.
• Update process-record files under docs/ promptly during each work round. Record meaningful implementation progress, verification evidence, failures, scope changes, and next-step decisions while the context is still fresh.
• Commit at the end of each completed work round with a concise conventional message.

Verification

Use the narrowest command that proves the current change during iteration, then run the full gate before claiming an implementation topic is done:

cargo fmt --check
cargo test
cargo clippy --all-targets --all-features --locked -- -D warnings

For official-style validation, use the PKU compiler-dev container:

docker run --rm -v "$PWD:/root/compiler" maxxing/compiler-dev autotest -koopa /root/compiler
docker run --rm -v "$PWD:/root/compiler" maxxing/compiler-dev autotest -riscv /root/compiler
docker run --rm -v "$PWD:/root/compiler" maxxing/compiler-dev autotest -perf -s perf /root/compiler