helix-db AGENTS.md

approach

• ⁠Make invalid states unrepresentable using algebraic data types (e.g. enums).
• ⁠Use code coverage tools to make sure unit test coverage covers every edge case. This should be easily doable if invalid states are unrepresentable.
• Keep things modular.
• Define clear contract boundaries for testability. Document them all, and make sure doc comment examples are ran as tests.
• Use assertions for invariants when encoding within types is not feasible.
• Use clippy and fix code smells reported.
• Prefer iterators, monadic logic, and functional concepts. Where not possible for performance, document why.
• Make invalid state unrepresentable.
• Prefer importing modules over long lists of types. Using module::Type at call sites is fine, keeps names unambiguous, and reduces namespace-collision churn.
• Be wary of things that don't scale. If you have reason to believe why it wont, report back to the user explaining why.
• instead of if let { ... } use let Some(…) = … else { }
• avoid over using helper functions where possible. duplicating a single line of code is clearer than polluting with helper functions. if a large piece of functionality is shared or repeated multiple times then it can be abstracted but you should favour inline code where possible. small pieces of functionality should be inlined instead of abstracted.
• Stage and commit code locally in phases as you go.
• As you make changes, if it is small (e.g. single/couple line addition) or if it is critical to your implementation, make the change.
• Clean up any temporary files or directories you create during your work (including in /private/tmp)
• ⁠match { Example(_) => ExampleVariant } -> use derive macro for Variant and the conversions instead of littering our code with the extra types and functions ⁠- ⁠instead of children structs holding an Arc, maybe just let them take in a &Db in every method that requires it.
• when that's not feasible, evaluate whether passing in an Arc is fine, and if not make sure that holding an Arc won't leak the memory based on how the child is stored in parent.