AGENTS.md

1# AGENTS.md
2 
3Guidance for coding agents working in this repository.
4 
5## Project
6 
7buzz is a small/lightweight statically typed scripting language written in Zig.
8 
9Main buzz implementation subsystems:
10 
11- Scanner: `src/Scanner.zig`
12- Parser and AST: `src/Parser.zig`, `src/Ast.zig`
13- Code generation and bytecode: `src/Codegen.zig`, `src/Chunk.zig`
14- Runtime values and objects: `src/value.zig`, `src/obj.zig`
15- VM: `src/vm.zig`
16- GC: `src/GC.zig`
17- JIT: `src/Jit.zig`, `src/mir.zig`
18- FFI: `src/FFI.zig`, `src/lib/buzz_ffi.zig`, `src/lib/ffi.buzz`
19 
20Tooling subsystems:
21 
22- Debugger: `src/Debugger.zig`
23- LSP: `src/lsp.zig`
24- Formatter: `src/renderer.zig`, `src/tests/fmt.zig`
25- REPL: `src/repl.zig`, `src/repl.html`, `src/wasm_repl.zig`
26 
27FFI, Debugger, and LSP are immature. Treat changes there as higher risk.
28 
29## Working Tree Policy
30 
31- Never commit changes.
32- Before editing, check the working tree.
33- If the working tree is clean, make the requested changes normally.
34- If the working tree only has untracked files, edits are allowed. Do not overwrite or delete unrelated untracked files.
35- If the working tree has tracked modifications or staged changes that were not initiated by the current agent/session, continue investigation read-only, then show the diff you would have applied and say that no files were modified because the working copy was not clean.
36- If tracked modifications were initiated by the current agent/session for the active task, the agent may continue editing those files and related files needed to finish the same task.
37- Do not overwrite or revert user changes.
38 
39Agents may delete files they generated during their own work. Do not delete files that were already tracked by git.
40 
41## Do Not Touch
42 
43- Never edit `vendors/`.
44- Do not edit generated or local build artifacts, including `zig-cache/`, `zig-out/`, `dist/`, `build/`, `node_modules/`, object files, dylibs, tarballs, and platform package directories.
45- Only edit `package.json`, `package-lock.json`, or WASM/frontend files when the task is specifically web/WASM-related.
46- Do not download or install dependencies.
47- If submodules are missing, `git submodule update --init` is acceptable.
48- Do not run `scripts/perf_compare_commits.py`.
49 
50## Common Commands
51 
52Quick compile check:
53 
54```sh
55zig build check
56```
57 
58`zig build check` is useful after small changes, but it does not cover every executable in the project.
59 
60Exhaustive compile check:
61 
62```sh
63zig build
64```
65 
66Run all important behavior tests:
67 
68```sh
69zig build test-behavior
70```
71 
72Run formatter tests:
73 
74```sh
75zig build test
76```
77 
78`zig build test` currently tests the buzz formatter. `zig build test-behavior` is the most important test suite for language behavior.
79 
80Run a single buzz file containing `test` blocks:
81 
82```sh
83zig build run -- test tests/behavior/descriptive-name.buzz
84```
85 
86Run a regular buzz script with a `main` function:
87 
88```sh
89zig build run -- run path/to/file.buzz
90```
91 
92Prefer `zig build run` because it builds buzz and then runs the script. Do not bother setting `BUZZ_PATH` manually.
93 
94Check Zig formatting:
95 
96```sh
97zig fmt --check src/*.zig src/**/*.zig
98```
99 
100Only Zig files need formatting checks for now.
101 
102## Validation Expectations
103 
104- If Zig code was touched, run `zig build` before finishing.
105- For language behavior changes, run `zig build test-behavior`.
106- For formatter changes, run `zig build test`.
107- For focused behavior work, first run the relevant file with `zig build run -- test <testfile.buzz>`, then run the broader suite when appropriate.
108- Tests are not expected to be flaky or platform-specific.
109- Supported platforms are macOS and Linux. Do not spend effort on Windows compatibility unless explicitly asked.
110- Do not test WASM unless the task is specifically WASM-related.
111 
112## Tests
113 
114- New language behavior tests go in `tests/behavior/` with a descriptive `.buzz` filename.
115- Existing numbered behavior test filenames are historical; new tests do not need a sequence number.
116- Every language feature or bug fix should include a behavior test unless there is a clear reason not to.
117- Parser, typechecker, compiler, and crash fixes should include a reduced regression test when possible.
118- Do not add fuzzed crashes yourself.
119- Tests that intentionally trigger a buzz compile error belong in `tests/compile_errors/`.
120- Compile-error tests must have a first-line comment containing the expected buzz error message.
121 
122## Style
123 
124- Always write uncapitalized buzz and not Buzz
125- Keep patches minimal and localized.
126- Preserve existing naming and conventions, even if they look inconsistent, unless the task is specifically cleanup.
127- Do not break logic into small functions unless those small functions are used more than once.
128- Zig variables use snake_case.
129- Zig types and functions use camelCase.
130- Comments are encouraged for compiler/runtime logic, but keep them concise and useful.
131- Any non-trivial code added must be properly commented in the code. Comments should explain intent, invariants, or tricky control flow, not restate obvious assignments.
132- Any new Zig file under `src/` must start with a file docblock (`//! ...`) describing the general role of the file.
133- Any new functions, structs, objects, properties, and enums introduced in Zig or buzz code must have a docblock.
134- When modifying of creating a buzz file, always reformat it with `buzz format`
135 
136## Runtime And GC Rules
137 
138- Strings and types are interned.
139- Strings generally come from `gc.copyString`.
140- Types generally come from `gc.type_registry.getTypeDef`.
141- When doing work while the VM is running, temporary buzz objects must be pushed on the stack so they are not collected by the GC.
142 
143## JIT And Debug Flags
144 
145Leave JIT enabled by default. Disable it only to pinpoint an issue.
146 
147Useful build flags include:
148 
149- `-Ddebug=true` for AST, bytecode, and other debug output.
150- `-Ddebug_stack=true` and `-Ddebug_current_instruction=true` for VM instruction/stack tracing.
151- `-Ddebug_placeholders=true` for placeholder resolution.
152- `-Ddebug_type_registry=true` for type registry debugging.
153- `-Dgc_debug=true`, `-Dgc_debug_light=true`, and `-Dgc_debug_access=true` for GC debugging.
154- `-Djit_debug=true` for JIT debugging.
155- `-Djit=false` to disable JIT while isolating runtime issues.
156- `-Djit_asynchronous=<bool>` controls whether JIT jobs run on the worker thread. Keep it enabled by default unless isolating an async publication issue.
157- `-Djit_call_threshold=<int>` is the function call count before a function is considered for JIT compilation.
158- `-Djit_score_threshold=<int>` is the function score gate. Function score is call count multiplied by chunk complexity.
159- `-Djit_hotspot_threshold=<int>` is the loop/hotspot execution count before a hotspot is considered for JIT compilation.
160- `-Djit_hotspot_score_threshold=<int>` is the hotspot score gate. Hotspot score is execution count multiplied by AST hotspot complexity.
161- `-Dcycle_limit=<int>` to limit bytecode execution, noting that it disables JIT compilation.
162- `-Dmemory_limit=<int>` to reproduce or bound memory behavior.
163 
164Current default JIT thresholds are intentionally conservative: call threshold `1024`, function score threshold `65535`, hotspot threshold `256`, hotspot score threshold `65535`, async enabled. When tuning, compare against the full `tests/bench` matrix instead of optimizing a single benchmark:
165 
166## Debugging Guidance
167 
168- For parser/typechecker/codegen issues, prefer the smallest `.buzz` regression test that reproduces the behavior.
169- For VM or GC issues, check object lifetime and stack rooting before changing collection behavior.
170- For JIT issues, compare behavior with JIT enabled and disabled before changing JIT code.
171- For FFI issues, be careful with pointer lifetimes and ownership across the Zig/buzz boundary.
172- If a change may affect performance, mention that in the final response when relevant, but do not run benchmarks unless explicitly asked.
173- If, while working on somnething, you find an unrelated bug, stop the current task and report the isuee to the user with a minimal plan to fix it.
174