jolt/.dirge/memory/PITFALLS.md
Yogthos dfa98746ee Phase 1+2: Clojure→Janet source compiler with symbol classification
- analyze-form: Clojure forms → annotated AST nodes (:op keys)
- emit-ast: AST dispatch → Janet source via StringBuffer
- compile-form: analyze → emit → Janet source string
- Symbol classification: locals, core refs, qualified refs
- Ops: const, do, if, def, fn, let, invoke, quote, vector, map
- Local binding awareness in fn* and let* (shadowing works)
- All 317 existing tests pass, 24 new compiler tests
2026-06-02 14:59:13 -04:00

5 lines
1.1 KiB
Markdown

Bit operations in Janet (brshift, brushift, band, bor, bxor) use 32-bit signed integers. Values from (hash key) can exceed 32-bit range (>2^31). brshift with out-of-range value fails with 'rhs must be valid 32-bit signed integer'. Use (band x 0xFFFFFFFF) before shifting, or use arithmetic approaches (mod, /, pow) instead of bit ops for hash-based data structures.
§
`.clj` source files are loaded at init time by Jolt's own reader/evaluator. PersistentVector (17 forms) and PersistentHashMap (12 forms) live in `src/jolt/clojure/lang/persistent_*.clj`. api.janet's `init` calls `load-persistent-structures` which slurps and eval-forms each file, then swaps clojure.core bindings (vec, vector, vector?, hash-map) to the persistent versions. Pass `{:mutable? true}` to skip loading and use Janet-native types.
§
Janet LSP produces false positives on `.janet` files — it doesn't understand Janet syntax (thinks docstring lines are unresolved symbols, doesn't know `declare-project`/`declare-source` macros, etc.). These are pre-existing and should be ignored — they don't affect runtime correctness.