Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (63 loc) · 4.23 KB

AGENTS.md

File metadata and controls

96 lines (63 loc) · 4.23 KB
Raw

Working on Arkade Compiler

Approach

Understand the requested behavior and trace the code path end to end before editing. For bugs, inspect every caller of the shared code and fix the root cause once.

Use the first solution that holds:

  1. Do not build it if it is not needed.
  2. Reuse an existing project helper or pattern.
  3. Use the Rust standard library or a native platform feature.
  4. Use an already-installed dependency.
  5. Prefer a one-line solution.
  6. Otherwise, write the minimum code that works.

Prefer deletion to addition, boring code to clever code, and the fewest changed files. Do not add abstractions, dependencies, boilerplate, or compatibility behavior unless the task requires them.

Validate inputs at trust boundaries and preserve error handling that prevents data loss. Treat security and compiler correctness as requirements, not cleanup opportunities.

Non-trivial logic needs the smallest runnable regression check that would fail if it broke. Trivial one-line changes do not need a new test.

Comments describe only what is currently true. Add a short comment when an intentional simplification has a known ceiling, and name the condition that would justify replacing it.

Preserve unrelated worktree changes. Do not edit secrets or Git internals. Do not commit or push unless asked; when asked, keep commit messages short and do not add agent attribution.

Project map

This is a Cargo workspace containing the compiler crate at the repository root and the binding generator in arkade-bindgen/.

  • src/parser/grammar.pest defines the language grammar.
  • src/parser/ maps source text into the AST.
  • src/models/mod.rs contains AST and public artifact models.
  • src/compiler/ emits Arkade covenant and tapscript assembly.
  • src/typechecker/ and src/validator/ enforce semantic and artifact invariants.
  • src/main.rs, src/lib.rs, and src/wasm.rs expose the CLI, Rust API, and optional WASM API.
  • tests/ contains integration and regression coverage.
  • examples/ contains source contracts used by tests and the playground.
  • playground/ contains the static browser playground and its build scripts.
  • .github/workflows/ defines workspace CI and playground deployment.

Source and tests are authoritative when README examples or generated output disagree.

Working rules

Language changes commonly cross the grammar, parser, models, typechecker or validator, compiler emission, and tests. Trace the actual flow and change only the layers the behavior needs.

PEG alternative order changes parsing behavior. Review nearby alternatives and add focused parser coverage when editing src/parser/grammar.pest.

Treat public artifact shapes in src/models/mod.rs, assembly generation in src/compiler/, dependencies in Cargo.toml, and deployment workflows as high-risk interfaces. Check downstream consumers and compatibility before changing them.

Keep covenant assembly and L1 tapleaf assembly distinct in implementation and tests. Assert the affected spend group, covenant, leaves, witness shape, and critical opcodes when semantics change.

Normalize or ignore the dynamic updatedAt field in artifact comparisons.

Use “Arkade” in project terminology.

Generated files

Do not hand-edit generated artifacts:

  • playground/contracts.js is generated from examples/**/*.ark by ./playground/generate_contracts.sh.
  • playground/pkg/ is generated by wasm-pack through ./playground/build.sh.
  • examples/**/*.json and examples/**/*.hack are compiler output and are ignored.

Edit the source and regenerate only when needed for local verification. Generated playground files are ignored and produced during deployment.

Verification

Run the smallest check that covers the change, then broaden it in proportion to risk:

cargo test --test features <test-name>
cargo test --test examples <test-name>
cargo test -p arkade-compiler <test-name>
cargo fmt --check

Before handing off Rust changes, run:

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --check

If the playground, WASM bridge, or examples used by it changed, also run:

./playground/build.sh

For fast compiler inspection against a contract:

cargo run -- path/to/contract.ark -o /tmp/contract.json