path: root/TODO.md

- [x] read the compiler, runtime, vm cores, language server, and build tools.
- [x] verify formatted markdown and code in vs code hovers, including bundled server builds.
- [x] add mandatory documentation for every built-in type.
- [x] use `/* ... */` comments as documentation, including comments for individual variables and arguments on the same line.
- [x] run focused tests between changes and avoid repeating the full suite.
- [x] check every core source file through the lsp document protocol with its expected source dependencies; reproduce and fix editor diagnostics, including those in `src/compiler/compiler.zc`.
- [x] rename current i/o and string helpers consistently, including `puts` → `put_s`, `putn` → `put_n`, and `scat` → `cat_s`; update compiler references, examples, tests, and documentation.
- [x] review passing a temporary owned return to an output function; preserve the restriction if it is needed for lifetime safety, otherwise fix it with regression coverage.
- [x] draft `docs/BORROW.md` with a concrete plan for a less intrusive borrow checker and lifetime analyzer.
- [x] grow collector mark work without losing pending objects or counting compiler storage as user objects on the default map.
- [x] verify more than 64 generic declarations, more than 128 instantiations, more than 32 captures, and more than 8 nested closures on the default map.
- [x] move source files into appropriate subdirectories of `src/`, tests into subdirectories of `tests/`, and documentation and designs into `docs/`.
- [x] consolidate windows build, run, and test entry points into one interactive `tinyvm.bat`.
- [x] add a matching interactive `tinyvm.sh` for linux, with direct command mode.
- [x] remove stale planning references from current documentation and code.
- [x] consolidate useful memory-limit information, then remove `CEILINGS.md` if redundant.
- [x] reject stale lsp diagnostics after closing and reopening a document.
- [x] make raw native stack picks obey the same address bounds as the portable backends.
- [x] show array, pointer, struct, enum, alias, and function types in hover previews.
- [x] show inferred types for untyped variables, function returns, arguments, and other inferred declarations.
- [x] verify inference for 600 functions and 5000 locals without silently dropping later edits.
- [x] grow stable frame segments and preserve older local addresses through collection on native, microcore, and javascript.
- [x] verify stable frame growth with llvm 23 and fix the macos libc helper-name conflict.
- [x] inventory fixed addresses and capacities across native, microcore, javascript, and lsp backends in docs/design/memory.md.
- [x] grow execution data and return stacks on native, microcore, and javascript, with explicit runtime reservations and collection after relocation.
- [x] verify operand and return stack growth on llvm and check invalid requests and denied growth without corrupting the vm.
- [x] repeat growth checks on a small generated map.
- [x] verify growing frames on small generated maps.
- [x] preserve all generic parameter names and inference state across nested compilation; infer later function arguments.
- [x] grow assembly and remaining parser scratch storage.
- [x] preserve long lsp request identifiers, grow json and header scratch buffers, and reset tagged-enum records between document checks.
- [x] grow image-building output independently of the building host’s genome slot while preserving logical image addresses.
- [x] grow native code-address metadata and preserve warm calls and invalidation after bulk rewrites.
- [x] restore missing javascript float opcodes and binary32 conversions, then compare focused arithmetic and formatting tests across backends.
- [x] grow program emission and image-building capacity without relocating live code or globals.
- [x] correct the lexer’s float-buffer load and read long float spellings without clipping their exponents.
- [x] point documented image boot headers at the symbol table after packed documentation.
- [x] polish the learning guide and verify its examples against their documented output.
- [x] fix reproducible bugs and apply useful optimizations with regression coverage.
- [x] support build-time adjustment through a consistent generated layout.
- [x] finish growing all compiler tables and execution stacks during execution, preserving live references; heap growth alone does not satisfy this requirement.
- [x] test changed limits, memory growth, invalid configurations, and agreement between image and host layout.
- [x] document available controls and any remaining fixed constraints precisely.
- [x] update builds, runners, editor bundles, tests, and links for the new paths, keeping the repository root focused on entry points.
- [x] preserve useful commands, propagate failures, and handle paths containing spaces.
- [x] verify runner behavior on available hosts and document untested platform behavior.
- [x] polish the learning guide and reference documentation; keep examples executable.
- [x] replace obsolete build commands and distinguish current behavior from historical notes.
- [x] make comments consistent and keep section overviews separate from unrelated declarations.
- [x] keep documentation and comment prose lowercase, matching the older style; preserve case-sensitive code and identifiers.
- [x] preserve full 64-bit integer literals, including values outside the single-word literal format.
- [x] grow stage 0 source input and image output beyond their initial capacities.
- [x] execute javascript vm and micro enhancement recipes with the same slot and output rules as the native hosts.
- [x] add basic bounds and lifetime analysis that warns about provable out-of-bounds access and use after free.
- [x] test definite failures and safe cases so uncertain behavior does not produce a definite warning.
- [x] show known size and lifetime information when hovering over an array or pointer.
- [x] fix the macos first-call crash in native mutual o3 recursion and verify it with a focused regression.
- [x] preserve nonfatal bounds and lifetime warnings across native, microcore, javascript, and both extension hosts.
- [x] verify block documentation, inferred pointer types, and lifetime metadata in the real editor.
- [x] replace quadratic hint deduplication with a growing set and verify large javascript documents.
- [x] make compact compiler maps grow past startup pressure and update obsolete fixed-limit test expectations.
- [x] fix darwin stdio variadic argument placement exposed by native integration tests.
- [x] index local names and preserve shadow chains to avoid rescanning all earlier locals.
- [x] keep cast bounds conservative and infer aggregate aliases as pointers to their stored addresses.
- [x] allow run-only heaps to grow and separate freestanding physical backing from logical vm limits.
- [x] complete final integration checks and refresh generated editor artifacts after the final fixes.
- [x] stop the leftover background test terminal and ensure focused tests exit cleanly.
- [x] show position-aware known values in variable and constant hovers; discard facts after unknown writes and effects.
- [x] verify value previews with focused compiler and editor tests and refresh the editor package.
- [x] separate section comments from declarations, exclude section headings from hover docs, and attach trailing declaration comments correctly.
- [x] make owned-object assignments to globals consume m or u source references through an automatic u transfer, with regression coverage.
- [x] explain inferred lifetimes in hovers, including ownership and borrow sources and where variables are passed up or down.
- [x] support explicitly typed closure returns with fn:type(args) syntax and show the declared result in hovers.
- [x] default compiler hints to blue informational squiggles and support positional hints on, small, and off directives.
- [x] add definition and reference navigation across the current document and included files.
- [x] stream diagnostics and cancel stale check contexts immediately when source changes, keeping editor feedback responsive.
- [x] optional, lowest priority: add a configurable pretty-printer with formatting behavior similar to clang-format; implementation is not required to finish the other work.
- [x] verify embedded runtime, compiler, server and standard library source navigation in generated editor hosts.
- [x] verify relative and nested includes, diagnostics on include strings, and explicit `include std;` without automatic imports.
- [x] finish compiler-backed lsp completions with signatures, documentation, scope, fuzzy relevance and consumed variables last and crossed out.
- [x] repair embedded-source hovers for every declaration in comma-separated and same-line declarations, including constants and backing arrays.
- [x] put section overview comments next to the structures they describe; give initial closure capacities their own descriptions.
- [x] describe base and encoded opcodes inside asm and vm blocks without treating comments, operands or ordinary expressions as instructions.
- [x] describe std in include std;.
- [x] replace fixed-array type syntax [N]T with T[N] in the compiler, bootstrap parser, maintained sources, tests and documentation.
- [x] refresh generated compiler and editor hosts and verify hovers and fixed-array syntax across the available backends.
- [x] use T[?] for growable arrays and T[] for fixed arrays with an inferred declaration-time length; migrate maintained sources and docs.
- [x] support array initializer lists, zero filling and index designators such as { 1, [5] = 0 }, including nested arrays.
- [x] support first-class array compound literals such as (int[]){1,2,3}, with argument decay and lifetime-safe temporary storage.
- [x] add //: non-documentation comments to the compiler, bootstrap compiler and source-only hovers; mark organizational source comments explicitly.
- [x] extend cached analysis results for repeated hover, navigation, semantic-token and completion requests, with source and include invalidation.
- [x] format local hovers as (type) let.lifetime name; // local, retaining transfer details without redundant ownership prose.
- [x] document compiler built-ins, including symbol-table columns such as sval, and expose their source comments in built-in hovers.
- [x] add static to syntax highlighting and show its form and meaning in hover.
- [x] audit built-in runtime signatures for complete source documentation and add hover help for len_s and transfer helpers.
- [x] infer the owned return transfer so returning a local owner does not require an explicit u* recast.
- [x] expand the standard library last with word-string suffix checks and packed-byte length, equality, search, and suffix helpers.
- [x] remove 45 `unchecked` annotations from compiler, runtime, standard library, and language-server helpers where checked ownership contracts and bootstrap/runtime tests proved them safe; give include paths an explicit consumed `.d` lifetime, extract checked format-file parsing, and make navigation walk parent paths in place.
- [x] remove all 12 remaining compiler `unchecked` function annotations and generate checked native struct-return stubs; declare owned token/source returns and consumed generic buffers, make internal allocation lifetimes explicit, and accept same-scope replacement moves into released owners with expired-source diagnostics.
- [x] implement BORROW.md temporary slots and cleanup for proved non-escaping calls, including returned aliases, nested calls, branches and early returns.
- [x] infer parameter read/write/retain/consume/returned-alias effects, resolve recursive summaries to a fixed point, and keep unknown/unchecked/native effects conservative.
- [x] record compiler ownership, alias, bounds, and lifetime facts; infer last-use borrow endings and unambiguous consuming-call transfers.
- [x] track field and index projections, proven disjoint accesses, and invalidation after array mutation or unknown effects.
- [x] improve definite lifetime/bounds diagnostics with cause and later-use locations, retaining hard errors and conservative unknown results.
- [x] make mutable closure captures share storage so counters and stateful callbacks observe updates.
- [x] modernize void-like examples and document the already implemented generated layouts and growing compiler tables without reintroducing fixed limits.
- [x] verify every BORROW.md acceptance case, cleanup/allocation counts and safe neighbors across available backends; update BORROW.md to describe implemented guarantees.
- [x] add deterministic compiler/runtime/stdlib fuzzing for 128 generated expressions, 300 scoped allocations and GC, token-input immutability, and 32 randomized Text/Bytes cases on native and microcore; fuzz LSP open/change, semantic tokens, and `include std` across 32 documents.
- [x] extend deterministic fuzz coverage to 320 malformed and byte-mutated compiler inputs across native and microcore, the same generated runtime/stdlib checks across native, microcore, JavaScript and WebAssembly, and 96 open/change/close/reopen LSP cache cycles in one server session.
- [x] cache packed-byte haystack and prefix lengths once in `Bytes.starts`; verify its results in the stdlib fuzz run and measure a 7.6% median improvement over 7 paired runs of 800,000 prefix checks.
- [x] repair the byte-load benchmark to auto-size its run-only image and use a monotonic timer with repeated samples, so benchmark failures cannot masquerade as timings.
- [x] before further implementation, add acceptance, rejection and regression coverage for every unchecked TODO item, then keep working until all of those tests and the required integration checks pass.
- [x] suppress magic-number hints for literals immediately preceded by an inline block comment, explain this escape in the hint and documentation, and test nearby-comment and uncommented cases.
- [x] hint on unused named function arguments at the parameter, respect hints on/small/off, and cover writes, reads, shadowing, methods, closures, generics and repeated `_` discards.
- [x] infer untyped word strings as `char*` and packed strings as `bstr`; cover reassignment, grouped declarations, parameters, returns, completions and hovers.
- [x] support comma-separated includes, repeated imports, and diagnostics for unknown modules and empty entries.
- [x] repair F12 navigation for every built-in, including `s_to_n`, so definitions open the correct embedded source (`rt.zc` for runtime functions); verify native, JavaScript and WebAssembly LSP hosts and the extension's virtual-source provider.
- [x] normalize all variable hovers to show the type first, including globals, fixed arrays, parameters, fields, inferred and embedded-source declarations; verify `(char*) let hello // global;` and `(word[20000]) let prog // global;` at declarations and uses without a trailing `; type ...`.
- [x] audit maintained string arguments, variables and results so string data uses explicit string types instead of word; preserve word for actual raw cells and buffers.
- [x] implement the compiler API namespace before further standard-library expansion. Outside `compiler.zc`, require `include run;` and `run.name` (for example `run.evals`); bare compiler names are allowed only inside the compiler module. Reserve `core` for VM core APIs.
- [x] implement matching runtime and language-server namespaces before standard-library expansion. Outside their respective modules, require `include rt;` with `rt.name`, or `include lsp;` with `lsp.name`.
- [x] support array receiver calls for len, cap, push, pop and resize, with element-aware lsp completions; reject fixed-array mutation through receiver and free calls, and verify 15 focused accept/reject cases on native and microcore plus lsp completion regressions.
- [x] add consistent `--help` output to the compiler, lsp and other command-line toolchain programs; describe available options and input modes, return successfully without reading source or starting the server, and cover help output and invalid options with focused tests.
- [x] add array operations for push, pop, find, map, filter and related common transformations; support receiver calls such as `x.push(4)` and `x.map(fn (e) { ... })`, include array-method completions, and document and test fixed-array and growable-array behavior.
- [x] install enhancement descriptors before starting self-hosted run-only images; verify arithmetic, generic array methods and reference pop ownership in standalone microcore images.
- [x] indent `case` and `default` labels one level deeper than their `switch` when pretty-printing, and update formatter documentation and regressions.
- [x] propagate inferred types across calls and return flows, including inferring a caller's untyped parameter from a callee's typed parameter and a caller's return type from the returned callee result; cover chains such as `mklist(n)` and `return l` with compiler and hover regressions.
- [x] allow `fixed` and `const` to qualify the same declaration, with consistent parsing, immutable fixed-array semantics, documentation and accept/reject coverage.
- [x] suggest qualified namespace members after prefixes such as `rt.` and verify completion ordering, signatures and documentation for each imported module.
- [x] show library-specific hover documentation on each module name in `include name;`, including comma-separated includes.
- [x] add LSP quick fixes for missing module imports and related compiler diagnostics; insert the relevant explicit include without changing unrelated source text.
- [x] verify collector-growth accounting relative to existing allocations and investigate conservative roots retained after clearing large global arrays.
- [x] allow repeated `_` discard placeholders in parameters and patterns, including tagged-enum payloads and catch-all cases; warn when a bound discard value is read.
- [x] add generic native and hosted microcore thread contexts with isolated vm state, channels, cancellation and cleanup; verify 14 native and 12 microcore fixtures while keeping actor-specific code in its library.
- [ ] give core built-ins and every other toolchain module their own namespace and require an explicit include to access qualified exports: `include core;` enables `core.name`, with the same rule for all other modules. remove implicit toolchain imports, migrate maintained sources and generated code, and verify missing-include diagnostics, completions, hovers and navigation before expanding the standard library.
- [ ] add a generic include-time syntax-extension interface so imported libraries can extend compiler parsing and lowering without module-specific compiler code; keep all extension hooks generic and inactive unless the corresponding library is included.
- [ ] continue removing `unchecked` from the remaining runtime boundaries by teaching the analyzer the missing ownership and drop contracts; document any irreducible low-level escapes. The compiler, standard library and LSP no longer disable checking for their functions.
- [ ] continue fuzzing the compiler, analyzer, runtime, standard library, LSP, build tools and generated artifacts, including analyzer properties, memory-limit edges, compiler image mutation and long-running LSP memory use; fix discovered bugs and performance regressions. Current coverage includes malformed parser inputs, source immutability across runtime compilation, allocation/GC leak deltas, configured-memory growth, and available native, microcore, JavaScript and WebAssembly execution hosts.
- [ ] after the compiler namespace and fuzzing work, add more general functionality to the standard library.
- [ ] implement `include actor;` as a library that injects actor syntax into the compiler through the generic include-time extension interface: `actor` declarations in place of `struct`, implicit `this`, and generic `Actor<I,O>` input/output types. Provide asynchronous parallel execution with independent state and multiple instances; keep actor-specific code out of `compiler.zc` and every file it includes or reads by default, and cover syntax activation, execution, messaging and type safety with tests.
- [ ] document the public standard-library APIs with concise descriptions of behavior, parameters, ownership and return values where applicable; update reference and learning entries, add executable examples and record implemented changes in history; keep prose lowercase and verify docs appear in hovers.
- [ ] revise diagnostics, comments and learning/reference prose using professional compiler documentation guidance, preserving lowercase and adding message regressions.
- [ ] implement and integrate `src/lib/icon.zc` with structured runtime syntax transformations, template matching, execution inspection and stepping, with explicit contracts and comprehensive tests.
- [ ] change the producer of the genome header (`build/core/genome.h`) to emit a c translation unit that embeds the compiler, core and runtime zc sources with a `#embed` directive instead of concatenating them into a 1.5 mb generated header; keep the `.zc` sources as the single source of truth and extend the fixpoint check in `make genome` so it still verifies the emitted genome without materializing a header at all.
- [ ] close the two ownership completeness limits that stop the compiler compiling itself, so `make genome` completes from a clean checkout: allow an owned value held in a local to move into another local when the destination's previous owner is released in the same statement list, and allow a global to hold a bounded borrow of a local so an output stream can be redirected at a scratch buffer without a module-level variable. also give `rt.code_blocks = m*block;` a supported spelling and fix the `only a named owned object can be recast` diagnostic, which does not describe the real constraint. written up in `docs/BOOTSTRAP-OWNERSHIP.md`, which also records a verified partial fix that removes five of the eight current errors.