foundation-base: Instructions file for Codex

Agent Instructions for Foundation Base

This document provides essential context for AI agents working with this codebase.

Testing Framework

IMPORTANT: This project uses a custom testing framework (code.test), NOT the standard clojure.test.

How Tests Work

• The lein test command is aliased in project.clj to run code.test (via :aliases {"test" ["run" "-m" "code.test"]})
• This is NOT the standard Leiningen test runner - it's a custom test framework with different behavior
• Tests are defined using (fact ...) macros and => assertions, not deftest and is

Running Tests

# Run all tests (Warning: ~930 tests, may take several minutes)
lein test

# Run a specific test namespace (RECOMMENDED)
lein test :only code.doc-test
lein test :only std.lib.collection-test

# Run tests matching a namespace pattern
lein test :with code.doc
lein test :with std.lib

Test Syntax

Tests use the fact macro and => arrow assertions:

^{:refer my.namespace/function-name :added "3.0"}
(fact "description of what this tests"
  (function-name arg1 arg2)
  => expected-result)

Fact IDs: one :refer per namespace, or use :id

A fact's id is derived from its :refer metadata (fact-id in code.test.base.runtime). Two facts in the same namespace with the same :refer collide: the later one overwrites the earlier one in the registry, and the earlier fact never runs — the suite still reports green, just with fewer checks. install-fact now prints a WARNING code.test: fact ... will NOT run line at load time when this happens; never let those warnings stand in a namespace you own (many pre-existing ones remain elsewhere in the tree).

• Keep to one fact per :refer per namespace (the existing convention), or
• give every fact a unique explicit id: ^{:refer my.ns/fn :id test-my-fn-2}.

To prove a test file's assertions actually execute, temporarily break one expectation and confirm the run fails (the summary line shows FAILED L:<line>), then revert. Don't trust the passed-check count alone.