clojure.spec CONTRACT for the language-surface tool RESULTS (format_code,
lint_code, run_tests).
Every language pack that registers a :format-fn / :lint-fn / :test-fn
under
:ext/language-tools returns a result map that MUST conform to these specs,
so the shape is UNIFORM across packs (clojure, and a future python / js) and
can never silently drift. Both results share the directory-nested by-dir
grouping ({<dir> {<basename> <payload>}}) that writes each long directory
prefix ONCE.
The result maps cross the strings-only Python boundary, so their keys are
STRINGS ("op", "findings", "by-dir", ...). clojure.spec's s/keys only
speaks keyword keys, so the map specs here are plain predicates over the
string keys, composed from s/map-of / s/coll-of for the nested pieces.
check validates a result and returns it UNCHANGED, throwing ex-info with
s/explain-data when it violates the contract — the schema check the packs
run on every format/lint result before handing it back through the surface.
capability->spec is the single source of truth mapping a capability keyword
to its result spec.
clojure.spec CONTRACT for the language-surface tool RESULTS (`format_code`,
`lint_code`, `run_tests`).
Every language pack that registers a `:format-fn` / `:lint-fn` / `:test-fn`
under
`:ext/language-tools` returns a result map that MUST conform to these specs,
so the shape is UNIFORM across packs (clojure, and a future python / js) and
can never silently drift. Both results share the directory-nested `by-dir`
grouping (`{<dir> {<basename> <payload>}}`) that writes each long directory
prefix ONCE.
The result maps cross the strings-only Python boundary, so their keys are
STRINGS ("op", "findings", "by-dir", ...). clojure.spec's `s/keys` only
speaks keyword keys, so the map specs here are plain predicates over the
string keys, composed from `s/map-of` / `s/coll-of` for the nested pieces.
`check` validates a result and returns it UNCHANGED, throwing ex-info with
`s/explain-data` when it violates the contract — the schema check the packs
run on every format/lint result before handing it back through the surface.
`capability->spec` is the single source of truth mapping a capability keyword
to its result spec.Maps a language-tool capability keyword to the spec its result must satisfy.
Capabilities absent here (:repl-eval-fn, ...) are unconstrained.
Maps a language-tool capability keyword to the spec its result must satisfy. Capabilities absent here (`:repl-eval-fn`, ...) are unconstrained.
(check capability result)Validate result against the language-surface contract for capability,
returning it UNCHANGED when it conforms. Throws ex-info carrying the spec
explain-data when it violates the contract. Unknown capabilities pass
through unchecked, so this is a no-op for tools without a registered spec.
Validate `result` against the language-surface contract for `capability`, returning it UNCHANGED when it conforms. Throws ex-info carrying the spec `explain-data` when it violates the contract. Unknown capabilities pass through unchecked, so this is a no-op for tools without a registered spec.
(complete-test-result language result)One pack's raw run_tests result onto test-result-base — the SINGLE place
the uniform shape is made true.
Per-pack key VOCABULARY is folded onto the canonical names, so the caller
reads pass/fail whatever ran: pytest/bun passed/failed/errored ->
pass/fail (errored counts as failed), an argv cmd -> a command
string. total, is_pass and language are DERIVED only when the pack
reported none — nothing a pack said is ever overwritten.
Non-map results (a pack that returned something else) pass through.
One pack's raw run_tests `result` onto `test-result-base` — the SINGLE place the uniform shape is made true. Per-pack key VOCABULARY is folded onto the canonical names, so the caller reads `pass`/`fail` whatever ran: pytest/bun `passed`/`failed`/`errored` -> `pass`/`fail` (errored counts as failed), an argv `cmd` -> a `command` string. `total`, `is_pass` and `language` are DERIVED only when the pack reported none — nothing a pack said is ever overwritten. Non-map results (a pack that returned something else) pass through.
(explain capability result)The human explain string for a non-conforming result, or nil when valid /
the capability has no registered spec.
The human explain string for a non-conforming `result`, or nil when valid / the capability has no registered spec.
TOTAL key set of EVERY run_tests result — one tool, ONE result shape across
every language pack. A pack fills what its runner measured; the keys it does
NOT fill keep these neutral values instead of VANISHING, so ordinary model
Python (r["failures"][:3], r["total"]) can never KeyError, and never
reads None where a collection belongs.
Counts stay nil when the runner reported none — UNKNOWN is not zero — while
collections default empty and flags default false. Applied ONCE at the
language surface (language-surface/run-tests), AFTER the pack's own
check, so packs keep returning only what they know.
TOTAL key set of EVERY `run_tests` result — one tool, ONE result shape across every language pack. A pack fills what its runner measured; the keys it does NOT fill keep these neutral values instead of VANISHING, so ordinary model Python (`r["failures"][:3]`, `r["total"]`) can never KeyError, and never reads None where a collection belongs. Counts stay nil when the runner reported none — UNKNOWN is not zero — while collections default empty and flags default false. Applied ONCE at the language surface (`language-surface/run-tests`), AFTER the pack's own `check`, so packs keep returning only what they know.
(valid? capability result)True when result conforms to the contract for capability (or the
capability has no registered spec).
True when `result` conforms to the contract for `capability` (or the capability has no registered spec).
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |