From eb79dc6b5dd82534134a1cea3334fded010e2844 Mon Sep 17 00:00:00 2001 From: Ewan Croft Date: Thu, 16 Jul 2026 17:38:37 +0100 Subject: [PATCH] docs: add repository agent guidance --- AGENTS.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2784536 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,21 @@ +# AGENTS.md + +Guidance for agents working on Selenium, a Python compiler for a lunar/poetic strongly typed language that emits C. + +## Compiler contracts + +- `selenium/` contains lexer, parser, type checking, C emission, CLI, and diagnostics. +- `examples/` contains language fixtures; `.sel` syntax and the documented C-like semantics are public behavior. +- Generated C must be portable and deterministic. + +## Invariants + +- Preserve source positions and distinguish lexical, parse, name, type, and codegen failures. +- Enforce declared types, function signatures, control-flow validity, casts, and return behavior before C emission. +- Escape strings/chars safely and never turn source text into a shell command. +- `--run` must invoke compilers via argument arrays, propagate exit codes, use safe temporary paths, and clean up. +- Avoid undefined C for invalid programs; fail with an actionable source diagnostic instead. + +## Validation + +Install with `pip install -e .`, run the repository tests, and run `python -m compileall selenium`. Compile and execute representative examples with GCC and Clang where available. Cover malformed tokens, type errors, nested control flow, recursion, I/O, escaping, Unicode policy, compiler-not-found, and runtime exit propagation. Do not commit generated binaries or caches. -- 2.51.2