Skip to content

Using the Reference CLI as an Oracle

The conformance fixtures pin the normative behavior a workalike must reproduce, but they cannot anticipate every question you will hit mid-port: an odd combination of transforms, a locale string, a number near a notation boundary, a template shape specific to the app you're porting. When you hit one of these and no fixture answers it, don't guess and don't reason it out from the specification prose alone — ask the reference implementation. kbars render is a cheap, authoritative oracle: build the smallest template/context pair that reproduces your question, run it through the real reference implementation, and treat its output as the target for your own port.

This is a workflow, not a fixture substitute. Anything you learn this way that looks like it should be generally true is a candidate for a new fixture upstream (see Writing a Workalike) — the oracle answers "what does the reference do right now for this specific input," not "what is guaranteed forever." Cross-check anything surprising against the specification's normative text before trusting it as a general rule; if the two disagree, that's a defect to report (see The Conformance Suite's note on the relationship between the spec, the suite, and the reference), not a case where the oracle's behavior silently wins.

Getting the CLI

Today, the CLI is built from a full kBars checkout:

./gradlew :cli:shadowJar

which produces cli/build/libs/kbars-all.jar (see the CLI Reference for the full build and PATH setup). A Homebrew formula distributing a prebuilt kbars binary is planned, which will let you install the oracle with brew install instead of cloning and building the repository — check the CLI Reference for the current installation options, since this page does not duplicate that instruction.

Whichever way you obtain it, confirm the binary's targeted suite version before trusting its answers against a specific suite release:

kbars --version

An oracle answer is only meaningful for the suite version it reports — if you are porting against suite 0.1.0, an oracle built from a main checkout that has since moved past 0.1.0 may answer questions about behavior your target suite doesn't have yet (or has changed). Match the CLI's reported version to the suite version you are targeting, the same way you'd match a fixture's own version field (see The Conformance Suite).

Asking a question

Write the smallest .kbars template and JSON/YAML context that isolates what you're unsure about, then render it:

kbars render -t question.kbars -c question.json

For an exact, byte-level answer — no added trailing newline, and the render's errorCode and softFails if the render doesn't simply succeed — use --json:

kbars render -t question.kbars -c question.json --json

{"outcome":"output","output":"...exact rendered bytes...","softFails":["KB-5006"]}

See the CLI Reference's --json envelope documentation for the error and invalid-context outcome shapes, and Error Codes for what a reported errorCode/softFails entry means.

A worked example

Suppose you're porting the sort transform and you're unsure how it orders a list mixing strings and numbers — a case no fixture happens to pin. Ask the oracle directly:

echo '{{ items | sort }}' > question.kbars
echo '{"items": ["banana", 3, "apple", 1]}' > question.json
kbars render -t question.kbars -c question.json --json

Whatever comes back is your target for that exact input. If the behavior looks like it should be general (not an artifact of this one example), open an issue proposing a new transforms/sort.json case so future porters get it from the fixtures directly instead of re-deriving it the same way you just did.

When the oracle isn't enough

Some questions the oracle cannot answer because they are implementation-defined, not fixed by either the spec or the suite — for example the exact tunable recursion/nesting limits (see Implementation-Defined Behavior). For those, the reference's specific number is informative, not normative; don't port it as a hard requirement.

See also