simon/jolt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
jolt/docs/spec
History
Yogthos eb7a9f1b20 core: spec 35-var batch A — 1.11 parsers, map/partition variants, with-redefs, ns fns 
Fifteen vars from the spec coverage gap (docs/spec/coverage.md):
parse-long/parse-double/parse-boolean (strict validation; scan-number alone
accepts 0x10), newline, current-time-ms (host clock for time), update-keys/
update-vals (PHM base, collisions last-wins), partitionv/partitionv-all/
splitv-at (lazy seqs of vectors; splitv-at's tail stays a seq, matching the
reference), with-redefs/with-redefs-fn (roots restored on throw), time,
macroexpand (expand-1 to fixpoint), alias/ns-unalias (write BOTH alias stores
— require :as uses string-keyed :imports while ns-aliases reads :aliases;
split filed), ns-publics (symbol-keyed map; publics == interns, no privacy).

Three pre-existing bugs fixed along the way:
- (partition n step pad coll) misparsed pad as the coll and returned ()
- (require 'bare.symbol) rejected — only vector specs were accepted
- analyze-form leaked the interpreted analyzer's ns on a punt: a throw out of
  the analyzer left current-ns=jolt.analyzer and :compile-ns set, so the
  fallback interpretation resolved user vars against the wrong namespace
  (bit (var user-sym) under compile mode)

And one overlay-authoring landmine documented in-code: a 20-coll fn must not
use 30-macros macros (with-redefs-fn's dotimes compiled as a forward ref that
resolved to the macro fn at runtime) — loop/recur instead.

Gate: conformance 316x3 (+14 rows), suite 4324 pass / 78 clean (was 4081/72;
parse_*/update_* files now contribute), baselines raised, all specs+unit,
fixpoint, self-host, sci, staged. Coverage: missing-portable 35 -> 20.
2026-06-10 11:16:54 -04:00
..
00-front-matter.md docs: language specification RFC + spec skeleton with normative exemplars 2026-06-10 10:53:44 -04:00
03-special-forms.md docs: language specification RFC + spec skeleton with normative exemplars 2026-06-10 10:53:44 -04:00
09-core-library.md docs: language specification RFC + spec skeleton with normative exemplars 2026-06-10 10:53:44 -04:00
coverage.md core: spec 35-var batch A — 1.11 parsers, map/partition variants, with-redefs, ns fns 2026-06-10 11:16:54 -04:00
README.md docs: language specification RFC + spec skeleton with normative exemplars 2026-06-10 10:53:44 -04:00

README.md

The Clojure Language Specification (Draft)

A normative, implementation-independent specification of the Clojure language, developed alongside jolt's self-hosted compiler and validated by its executable conformance suites. Why: Clojure has no spec — every alternative implementation re-derives semantics from the reference implementation and folklore. See the RFC for motivation, scope, evidence sources, and process: ../rfc/0001-language-specification.md.

Documents

Doc Content Status
00-front-matter.md conformance terms, entry format, host classification drafted
01-evaluation.md … 08-macros.md see chapter plan in front matter planned
03-special-forms.md special-form catalog + normative exemplars (if, let*) exemplars
09-core-library.md per-var entry format + exemplars (first, reduce, parse-uuid) exemplars
coverage.md generated dashboard over the 694-var surface generated

Regenerate the dashboard after surface changes: python3 tools/spec_coverage.py (requires clojuredocs-export.json in the repo root and a working jolt checkout).

Current numbers (2026-06-10)

Of the 694 clojure.core vars in the ClojureDocs inventory:

  • 380 implemented in jolt and exercised by the behavioral suites
  • 154 implemented but not directly tested — each gets a test with its spec entry
  • 35 portable but missing from jolt (parse-long/parse-double/ parse-boolean, update-keys/update-vals, macroexpand, time, partitionv/partitionv-all/splitv-at, with-redefs, with-open, reader fns, ns-introspection stragglers, …) — tracked as implementation gaps
  • 22 resolvable in code but invisible to ns introspection (resolve/ns-publics can't see seed-fallback names like compare, gensym, type) — a conformance finding in its own right
  • the rest classified host/JVM/concurrency (see dashboard)

How this connects to the test suites

  • test/integration/conformance-test.janet — 302 assertions, each run through three independent execution paths (interpreter, bootstrap compiler, self-hosted compiler) that must agree. Spec entries cite these.
  • test/spec/*.janet — ~1,500 behavioral cases organized by topic.
  • vendor/clojure-test-suite — the cross-dialect suite (≥4081 assertions passing); dialect splits there are classification evidence.
  • jank's per-construct corpus (~/src/jank/compiler+runtime/test/jank) is the granularity model for §2/§3 conformance.

The invariant: every numbered normative statement names its conformance test, or is marked UNVERIFIED. The spec cannot drift from the implementations that check it.