Project Instructions

This file provides context for AI assistants working on this project.

Project Type: Rust

See README.md for project overview.

This project uses Git. See .gitignore for excluded files.

CodeWhale reads this file as: AGENTS.md
Agent approach: Prefer edits in crates/ and relevant top-level files only. Avoid modifying generated or build artifacts unless explicitly instructed. Do not assume the repository is fully editable; if any guidance field is blank, pause and ask for clarification before making changes.
Read-only surface: docs/, examples/, target/, tests/ (read for context only; do not modify these directories unless explicitly instructed).
Never edit: target/, Cargo.lock, vendor/, generated/, build/, .git/, .github/workflows/*.yml. If a file appears generated or contains comments like "generated by", do not edit it and ask for confirmation.
Always test with: cargo test -p <crate-name> for the crate you changed. If multiple crates change, run cargo test at the repository root. If the target crate is ambiguous, respond: "Ambiguous test target: please specify the crate name or confirm tests to run." Do not run tests until clarified.

The repo is a Rust workspace with a compiler toolchain split across crates.

Primary CLI binary: crates/coco_cli/src/main.rs
Shared libraries: crates/coco_syntax, crates/coco_parser, crates/coco_formatter, crates/coco_interpreter, and crates/coco_typeck
Most changes should be validated by running the relevant crate tests and, when applicable, the coco_cli command flow.

crates/coco_cli: command-line interface and subcommand wiring
crates/coco_parser: parser for Coco syntax
crates/coco_typeck: gradual type checker
crates/coco_interpreter: bytecode VM, compiler (AST → Chunk), and .cb artifact serialization (serialize module)
crates/coco_syntax: AST definitions and language constructs
crates/coco_span: source span tracking

The bytecode VM is the sole execution model. There are three ways to run a program:

coco run foo.co — lex → parse → compile to a Chunk → VM executes (full pipeline)
coco run foo.cb — deserialize a .cb bytecode artifact → VM executes (skips parse/compile)
coco build foo.co — emits a .cb artifact via coco_interpreter::serialize_chunk; coco build --disasm prints bytecode disassembly

Source text is lexed by coco_lexer
AST is built by coco_parser using coco_syntax
Formatter, type checker, and the VM compiler consume the parsed AST
The VM compiler lowers the AST to a stack-based bytecode Chunk
coco_cli orchestrates file resolution, parsing, diagnostics, type checking, compilation, and execution (or .cb serialization for build)

Frequently-rebuilt files: target/, build artifacts, generated files, and derived test outputs.
Stable scaffolding: Cargo.toml, rust-toolchain.toml, README.md, AGENTS.md, and docs files should remain stable.
Append, don't reorder: Add new context at the end of stable documentation files. Avoid reordering existing checklist items and preserve previous entries when updating conventions.