|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to coding agents collaborating on this repository. |
| 4 | + |
| 5 | +## Mission |
| 6 | + |
| 7 | +Ordered is a sorted-collection library for Zig. It provides in-memory data structures that keep their elements sorted: |
| 8 | +two set types (value-only) and four map types (key-value), all exposing a small, uniform API for insertion, lookup, |
| 9 | +removal, and in-order iteration. |
| 10 | +Priorities, in order: |
| 11 | + |
| 12 | +1. Correctness of ordering, iteration, and memory management across insertions and removals. |
| 13 | +2. Minimal public API that is consistent across every container type. |
| 14 | +3. Zero non-Zig dependencies, maintainable, and well-tested code. |
| 15 | +4. Cross-platform support (Linux, macOS, and Windows). |
| 16 | + |
| 17 | +## Core Rules |
| 18 | + |
| 19 | +- Use English for code, comments, docs, and tests. |
| 20 | +- Prefer small, focused changes over large refactoring. |
| 21 | +- Add comments only when they clarify non-obvious behavior. |
| 22 | +- Do not add features, error handling, or abstractions beyond what is needed for the current task. |
| 23 | +- Keep the project dependency-free: no external Zig packages or C libraries unless explicitly agreed. |
| 24 | + |
| 25 | +## Writing Style |
| 26 | + |
| 27 | +- Use Oxford commas in inline lists: "a, b, and c" not "a, b, c". |
| 28 | +- Do not use em dashes. Restructure the sentence, or use a colon or semicolon instead. |
| 29 | +- Avoid colorful adjectives and adverbs. Write "TCP proxy" not "lightweight TCP proxy", "scoring components" not "transparent scoring components". |
| 30 | +- Use noun phrases for checklist items, not imperative verbs. Write "redundant index detection" not "detect redundant indexes". |
| 31 | +- Headings in Markdown files must be in the title case: "Build from Source" not "Build from source". Minor words (a, an, the, and, but, or, for, in, |
| 32 | + on, at, to, by, of, is, are, was, were, be) stay lowercase unless they are the first word. |
| 33 | + |
| 34 | +## Repository Layout |
| 35 | + |
| 36 | +- `src/lib.zig`: Public API entry point. Re-exports `SortedSet`, `RedBlackTreeSet`, `BTreeMap`, `SkipListMap`, `TrieMap`, and `CartesianTreeMap`. |
| 37 | +- `src/ordered/sorted_set.zig`: `SortedSet` (insertion-sorted `std.ArrayList` backed by a linear scan for insert and removal). |
| 38 | +- `src/ordered/red_black_tree_set.zig`: `RedBlackTreeSet` (self-balancing BST; takes an explicit three-way comparison function, consistent with the other generic-key containers). |
| 39 | +- `src/ordered/btree_map.zig`: `BTreeMap` (cache-friendly B-tree with configurable branching factor). |
| 40 | +- `src/ordered/skip_list_map.zig`: `SkipListMap` (probabilistic skip list with a per-instance PRNG). |
| 41 | +- `src/ordered/trie_map.zig`: `TrieMap` (prefix tree, specialised for `[]const u8` keys). |
| 42 | +- `src/ordered/cartesian_tree_map.zig`: `CartesianTreeMap` (treap combining BST ordering with max-heap priorities; takes an explicit key-comparison function). |
| 43 | +- `examples/`: Self-contained example programs (`e1_btree_map.zig` through `e6_cartesian_tree_map.zig`) built as executables via `build.zig`. |
| 44 | +- `benches/`: Benchmark programs (`b1_btree_map.zig` through `b6_cartesian_tree_map.zig`) built in `ReleaseFast`. |
| 45 | +- `benches/util/timer.zig`: Internal compatibility shim for the removed `std.time.Timer`, backed by `std.Io.Timestamp`. |
| 46 | +- `.github/workflows/`: CI workflows (`tests.yml` for unit tests on Linux, macOS, and Windows, `docs.yml`, `lints.yml`, and `benches.yml`). |
| 47 | +- `build.zig` / `build.zig.zon`: Zig build configuration and package metadata. |
| 48 | +- `Makefile`: GNU Make wrapper around `zig build` targets. |
| 49 | +- `docs/`: Generated API docs land in `docs/api/` (produced by `make docs`). |
| 50 | + |
| 51 | +## Architecture |
| 52 | + |
| 53 | +### Common API Across Containers |
| 54 | + |
| 55 | +Every map exposes `init(allocator)`, `deinit()`, `count()`, `contains(key)`, `get(key)`, `getPtr(key)`, `put(key, value)`, |
| 56 | +`remove(key)`, and `iterator()`. Every set exposes the same shape with value-only variants. New containers should |
| 57 | +adopt this surface instead of inventing new method names. |
| 58 | + |
| 59 | +### Iteration |
| 60 | + |
| 61 | +Iterators return entries in the natural sort order of the underlying structure. Modifying a container during |
| 62 | +iteration is undefined behaviour; each container's docstring states this explicitly. New iterators should follow |
| 63 | +the same convention and document the contract. |
| 64 | + |
| 65 | +### Randomised Containers |
| 66 | + |
| 67 | +`SkipListMap` and `CartesianTreeMap` use randomness internally (levels and priorities, respectively). Each instance |
| 68 | +owns its own `std.Random.DefaultPrng`, seeded at `init` from an ASLR-derived hash of a stack address, which is |
| 69 | +sufficient randomness for skip-list level selection and treap priority generation. Callers do not need to provide |
| 70 | +a seed. Tests that require deterministic behaviour should use the explicit `*WithPriority` / level-setting API |
| 71 | +on the container rather than seeding the PRNG directly. |
| 72 | + |
| 73 | +### Public API Surface |
| 74 | + |
| 75 | +Everything re-exported from `src/lib.zig` is part of the public API. Changes to names, signatures, or semantics |
| 76 | +there are breaking. The rest of `src/ordered/` is internal and may be refactored freely as long as the public |
| 77 | +surface and its behavior are preserved. |
| 78 | + |
| 79 | +### Dependencies |
| 80 | + |
| 81 | +Ordered has **no external Zig or C dependencies**. |
| 82 | +The only `build.zig.zon` entries should be Ordered itself. |
| 83 | +Please do not add dependencies without prior discussion. |
| 84 | + |
| 85 | +## Zig Conventions |
| 86 | + |
| 87 | +- Zig version: 0.16.0 (as declared in `build.zig.zon` and the Makefile's `ZIG_LOCAL` path). |
| 88 | +- Formatting is enforced by `zig fmt`. Run `make format` before committing. |
| 89 | +- Naming follows Zig standard-library conventions: `camelCase` for functions (e.g. `getPtr`, `keysWithPrefix`), `snake_case` for local variables and |
| 90 | + struct fields, `PascalCase` for types and structs, and `SCREAMING_SNAKE_CASE` for top-level compile-time constants. |
| 91 | + |
| 92 | +## Required Validation |
| 93 | + |
| 94 | +Run the relevant targets for any change: |
| 95 | + |
| 96 | +| Target | Command | What It Runs | |
| 97 | +|------------------|-------------------------------------|-------------------------------------------------------------------| |
| 98 | +| Unit tests | `make test` | Inline `test` blocks across `src/lib.zig` and `src/ordered/*.zig` | |
| 99 | +| Lint | `make lint` | Checks Zig formatting with `zig fmt --check src examples` | |
| 100 | +| Single example | `make run EXAMPLE=e1_btree_map` | Builds and runs one example program | |
| 101 | +| All examples | `make run` | Builds and runs every example under `examples/` | |
| 102 | +| Single benchmark | `make bench BENCHMARK=b1_btree_map` | Builds (ReleaseFast) and runs one benchmark program | |
| 103 | +| All benchmarks | `make bench` | Builds and runs every benchmark under `benches/` | |
| 104 | +| Docs | `make docs` | Generates API docs into `docs/api` | |
| 105 | +| Everything | `make all` | Runs `build`, `test`, `lint`, and `docs` | |
| 106 | + |
| 107 | +## First Contribution Flow |
| 108 | + |
| 109 | +1. Read the relevant module under `src/ordered/` (often one container file per change). |
| 110 | +2. Implement the smallest change that covers the requirement. |
| 111 | +3. Add or update inline `test` blocks in the changed Zig module to cover the new behavior. |
| 112 | +4. Run `make test` and `make lint`. |
| 113 | +5. If the change could affect performance, also run the corresponding benchmark with `make bench BENCHMARK=bN_*`. |
| 114 | + |
| 115 | +Good first tasks: |
| 116 | + |
| 117 | +- New example under `examples/` demonstrating a container method, listed in `examples/README.md`. |
| 118 | +- Additional inline `test` block covering a boundary case (empty container, single element, duplicate key, unicode key). |
| 119 | +- Performance improvement in an existing container, paired with benchmark output before/after. |
| 120 | +- Documentation refinement in a container module's top-level docstring. |
| 121 | + |
| 122 | +## Testing Expectations |
| 123 | + |
| 124 | +- Unit and regression tests live as inline `test` blocks in the module they cover (`src/lib.zig` and `src/ordered/*.zig`). There is no separate |
| 125 | + `tests/` directory. |
| 126 | +- Tests are discovered automatically via `std.testing.refAllDecls(@This())` in `src/lib.zig`, so new `test` blocks only need to live in a module that |
| 127 | + is reachable from `lib.zig`. |
| 128 | +- Every new public function or container branch must ship with at least one `test` block that exercises it, including the error paths where |
| 129 | + applicable. |
| 130 | +- Memory tests should use `std.testing.allocator` so leaks are caught automatically. |
| 131 | +- No public API change is complete without a test covering the new or changed behavior. |
| 132 | + |
| 133 | +## Change Design Checklist |
| 134 | + |
| 135 | +Before coding: |
| 136 | + |
| 137 | +1. Modules affected by the change (which container file, or `lib.zig` if the public surface moves). |
| 138 | +2. Whether the change alters ordering, iteration, or removal semantics, and therefore needs explicit test coverage. |
| 139 | +3. Public API impact, i.e. whether the change adds to or alters anything re-exported from `src/lib.zig`, and is therefore additive or breaking. |
| 140 | +4. Cross-platform implications, especially for anything that touches timing, the filesystem, or non-deterministic ordering. |
| 141 | + |
| 142 | +Before submitting: |
| 143 | + |
| 144 | +1. `make test` passes. |
| 145 | +2. `make lint` passes. |
| 146 | +3. `make bench` still succeeds for any benchmark whose container was touched, with a note on whether performance moved. |
| 147 | +4. Docs updated (`make docs`) if the public API surface changed, and `README.md` ticked or updated if a container was added or removed. |
| 148 | + |
| 149 | +## Commit and PR Hygiene |
| 150 | + |
| 151 | +- Keep commits scoped to one logical change. |
| 152 | +- PR descriptions should include: |
| 153 | + 1. Behavioral change summary. |
| 154 | + 2. Tests added or updated. |
| 155 | + 3. Whether benchmarks were run locally (yes/no), and on which OS, with before/after numbers when relevant. |
0 commit comments