aboutsummaryrefslogtreecommitdiff
path: root/AGENTS/PITFALLS.md
AgeCommit message (Collapse)Author
2026-10-21docs(agents): split PITFALLS.md into topic files under AGENTS/PITFALLS_ov4
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21docs: document TEMPLATE_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20docs(strings): document the embedded standard library and STRING values_ov4
Describe -no-std, C_STRING literals, library function semantics and owning string lifetimes in the manuals and contributor guidance. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20docs(agents): align dispatch and object lifetime guidance with code_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18feat(classes): add copy constructors and statement-scoped temporaries_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18feat(lexer): support C++ escape sequences in literals_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18feat(operators): document overloads and cover remaining operator forms_ov4
Add fixed cases for every supported operator, imported global and member operators, CASE comparisons, and declared result type errors. Document syntax, exact matching, access rules and temporary receiver lifetimes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17docs(agents): note Windows JIT msvcrt symbol lookup for EXTERN_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17docs: describe EXTERN redeclaration and verified lli runs_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17docs: document EXTERN and INCLUDE_OBJ_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17docs: document OVERLOAD_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17feat(runtime): write runtime diagnostics to stderr_ov4
Runtime check messages and the unhandled-exception message were printed to stdout by the generated program, so `cpsc x.cps -r >out.txt` captured them. They are now formatted with snprintf and written with write(2). Test expectations and docs are updated accordingly. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-17docs: multi-file builds_ov4
Document INCLUDE visibility, primitive GLOBAL variables and MAIN entry rules, and highlight the new keywords in the editor grammar. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17docs(classes): document destructors, DELETE and RAII_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17fix(classes): preserve method-only heap objects and document NEW_ov4
Allocate at least one byte for method-only classes so their heap addresses remain usable through pointers. Complete constructor diagnostics, field-order and exception coverage, document construction and rebinding, and highlight NEW. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17fix(parser): accept optional DO after WHILE condition_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17docs(classes): describe member methods and this semantics_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-17docs(tests): remove obsolete failure history_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-17docs(input): document array and member targets_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16docs(pitfalls): mark embedded ORC execution verified on all CI platforms_ov4
Windows runner failures are fixed and nightly CI is green on Linux, Windows and macOS. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16docs(jit): document ORC execution and verification status_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16fix(compiler): correct CIE semantics and diagnostic locations_ov4
Use standard WHILE headers and default-public class fields, resolve pseudocode identifiers without case sensitivity, and check signed i64 literal boundaries before conversion. Preserve source locations across recursive emission and function diagnostics. Add 22 regression cases and update compiler examples and documentation. Validated all 69 CTest entries with the original Linux Actions seed and verified the release package's embedded, native and IR output paths.
2026-10-16ci(compiler): gate platform packages on reproducible compiler tests_ov4
Run all three suites on Linux, macOS and Windows with the push SHA as seed. Retain failure evidence and document the 12 existing failures, pending human review and remaining coverage gaps. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16feat(constants): implement literal constants with lexical scope_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16feat(control-flow): implement ordered CASE OF matching_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-15fix(codegen): restore runtime diagnostics before throwing_ov4
Reuse historical runtime messages and source-line reporting for arithmetic, array, enum, pointer and file checks while preserving anonymous exceptions. Update the manuals and subsystem guidance to describe diagnostic output. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-15fix(codegen): prevent NUM_TO_STR buffer overflow_ov4
Size REAL buffers for the full fixed-point double range and bound writes with snprintf. Register MinGW CRT aliases for embedded execution. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-14docs(release): document nightly downloads and build workflow_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-14docs(toolchain): clarify MINGW64 LLVM and Clang 23 setup_ov4
Select the MINGW64 compiler executables with explicit Windows paths and add version checks for installed Clang and downloaded LLVM packages. Document Windows PATH requirements and platform-specific C++ driver names. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-14docs(toolchain): document LLVM and Clang 23 requirements_ov4
Update build and native-link examples, PATH version-check rules and LLVM API guidance. Record Linux verification and retain the Windows/macOS verification limits. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-14docs(language): document native C types and explicit casts_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-13docs(language): document exception handling and runtime behavior_ov4
Add the TRY manual for CATCH, ENDTRY, and anonymous THROW. Update runtime error descriptions, language links, and native linking examples; document catch cleanup and embedded runtime integration in the architecture notes. Verify manual generation, rendered output, relative links, and the TRY example. Record Linux LLVM 18 validation and unverified Windows/macOS support. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-13Add record-derived classes with explicit field visibility_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-13feat: support comma-separated OUTPUT expressions_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-13fix: preserve 64-bit integers in NUM_TO_STR_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-13fix: compare strings by content_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-13feat: compile source files with configurable IR output_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-07-26fix: close type-safety holes found by adversarial review; update docs_ov4
Review findings (all reproduced, then fixed and re-verified): - '^x' leaked as a raw address into any builtin context (s <- ^x printed the variable's bytes as a C string; NOT ^x, '&', and ^x = ^x compiled). Address-of is now rejected everywhere except a pointer-typed target. - A whole-array variable passed the nominal gate as a value of its ELEMENT type (s <- arrayOfSeason stored the raw data pointer; = on it emitted invalid IR). Whole arrays are now rejected as operands and as coercion sources; array parameters are unaffected. - Enum values smuggled into INTEGER through array subscripts and DECLARE bounds (a[Autumn], ARRAY[Spring:Winter]); both now go through emitCoercedExpr like every other INTEGER context. - An array DECLAREd inside an IF/WHILE/REPEAT/FOR body and used after the block was a wild-pointer write (constant bounds) or a verifier dump (runtime bounds). Arrays are now block-scoped: control-flow bodies snapshot and restore the ArrayTable, so escape is a clean compile error. - Duplicate parameter names silently shadowed (BYREF write-back defeated); now a parse error. Trailing comma in parameter lists accepted; now a parse error consistent with every other list. - A variable/array/parameter/function could reuse a TYPE name; reserved. - RETURN with a value inside a PROCEDURE was silently discarded (control did not return); now an error, as is a bare RETURN in a FUNCTION. - INPUT r.f mis-parsed into a three-error cascade; now one clear error. - Assigning to an enum constant now says so instead of 'Unknown variable'. Docs: ARCH/CONVENTIONS/EXTENDING/SUBSYSTEMS/PITFALLS rewritten for the TYPE system (ABI additions, nominal-typing invariants, admission-gate doors, array-parameter ABI, new recipes, new sharp edges); README features/TODO updated — random files are unblocked. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26feat: implement CIE 9.1 text file handling ↵_ov4
(OPENFILE/READFILE/WRITEFILE/CLOSEFILE/EOF) Front end: OPENFILE/READFILE/WRITEFILE/CLOSEFILE plus reserved mode keywords READ/WRITE/APPEND (RANDOM reserved with a dedicated not-implemented error); statement nodes in new FileAST.h, parsing in new ParserFile.cc; EOF joins the Builtins table as the 12th builtin and CallExprAST now carries a line number for its runtime diagnostics. Runtime: new FileHandler (StringHandler-shaped leaf) lazily synthesizes internal __cps_file_* helper functions and a 16-slot open-file table keyed by filename content (strcmp — STRING '=' is pointer identity). EOF is an fgetc/ungetc peek; READFILE grows a malloc/realloc line buffer and strips a trailing CR; fopen uses text modes so mingw-w64 line translation works. File-free programs get byte-identical IR. All misuse (not open, wrong mode, reopen, fopen failure, read past EOF, table full) dies with the existing "[Fatal] line N:" pattern via a new RuntimeCheck::emitErrorAndExit overload taking runtime printf args. Also fixes a pre-existing ArithmeticHandler hole surfaced by adversarial review: mixed-width integer operands (i1 BOOLEAN / i8 CHAR vs i64) now widen via ZExt instead of emitting invalid IR, and remaining type mismatches get a clean diagnostic; -EOF(f) and -IS_NUM(x) compile. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26fix: close correctness gaps found by post-refactor adversarial review_ov4
Confirmed by a 17-agent review pass over the refactor diff (12 findings verified against the code and reproduced end-to-end): - marshalCallArgs: BYREF arguments must match the declared parameter type exactly (was: silent bit-reinterpretation, e.g. REAL passed to BYREF INTEGER printed garbage with exit 0); whole-array arguments are rejected (was: callee assignment smashed the array data pointer -> runtime SIGSEGV) - Null guards for CHR/LCASE/UCASE/IS_NUM/NUM_TO_STR/STR_TO_NUM/ASC argument emission (was: compiler SIGSEGV on e.g. CHR(undeclared)), matching the guards MID/RIGHT/LEFT already had - ParseReturnStmt: propagate expression-parse failure (was: diagnostic printed but exit 0) and recognize bare RETURN before ENDWHILE/UNTIL/NEXT (was: bogus diagnostic on legal early return) - emitPrototype rejects FUNCTION/PROCEDURE names that collide with runtime/libc symbols (was: FUNCTION strlen silently hijacked the string runtime; arity mismatch crashed createArgumentAllocas) or with builtins (was: silently shadowed); conflicting redefinitions keep the first signature - FOR STEP is evaluated exactly once, before the loop (was: once per iteration; the runtime-direction refactor had moved it to N+1) - RETURN values are coerced to the declared return type via the signature table (RETURN n in a RETURNS REAL function now compiles) - '&' coerces its operands to STRING (CHAR/number operands work); OUTPUT of a PROCEDURE call reports a clean error AGENTS docs updated to match. All positive samples remain byte-identical to the pre-refactor baseline. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26refactor: extract ParseBlock/ParseExprList, resync-based error recovery_ov4
Seven copy-pasted statement-block loops collapse into ParseBlock(terminators); five comma-separated expression-list loops collapse into ParseExprList(close, allowEmpty), which also fixes "arr[1 2] <- x" being silently accepted as arr[1,2] on the statement path. Error recovery now lives in one place: syncToStatementStart skips to the next statement-start/block-end token, so a bad statement no longer swallows the first token of the following good one. Drop the dead -1000/-1001 token check in ParsePrototypeArgs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26refactor: keep pseudocode signatures, single call-marshalling path_ov4
emitPrototype now records each FUNCTION/PROCEDURE's pseudocode signature (FuncSig: return type + per-param type/BYREF flag). CodeGen:: marshalCallArgs replaces the two verbatim-duplicated marshalling blocks and dispatches on the declared signature instead of inferring BYREF from pointer-typed LLVM params: BYVAL STRING params now receive the string data pointer (no more runtime garbage), and BYVAL args are coerced to the declared type (INTEGER->REAL args no longer emit invalid IR). Top-level prototypes are pre-registered in compile(), so calls may precede definitions; GenerateCall no longer fabricates i64 externs for unknown names - an unregistered callee is a compile error. OUTPUT reports an error when it cannot infer the expression type instead of printing with the INTEGER format. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26refactor: single builtin registry, retire keyword route for builtins_ov4
All 11 builtins now live in one static {Name, Arity, ReturnTypeName} table in CodeGen.cc: emitExpr checks arity against it (uniform "Error: X expects N args" diagnostics) and getExprTypeInfo reads return types from it, removing the duplicated hard-coded table. LENGTH/MID/RIGHT/LEFT/LCASE/UCASE lose their lexer tokens and ParseStringBuiltin; they parse as ordinary identifier calls exactly like ASC/CHR/IS_NUM/NUM_TO_STR/STR_TO_NUM already did. Behavior note: these six names are no longer reserved words. AGENTS docs updated for the new builtin story and the batch-1 error contract (exit codes, verifyModule, fixed descending FOR). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26docs: add AGENTS/ architecture docs for AI-assisted development_ov4
ARCH.md holds the overview (pipeline, build/run, layout); details are split into CONVENTIONS.md, EXTENDING.md, SUBSYSTEMS.md and PITFALLS.md. All claims were verified against the source, most also empirically by compiling and running test programs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>