CLI Reference¶

The kpointer command-line tool ships with the cli module. Its primary use is running the conformance suite against a kPointer implementation in any language.

Synopsis¶

kpointer [--version] <command> [<args>]

Commands¶

kpointer conformance¶

Runs conformance fixtures and reports results.

kpointer conformance [OPTIONS] [PATH...]

Each PATH may be a JSON fixture file or a directory; directories are searched recursively for *.json files (excluding *.schema.json and manifest.json, which are not fixtures). When no PATH is given, the tool defaults to ./conformance.

Options¶

Human-readable output¶

When --full-report is not set, the tool prints a one-line summary on success:

4/4 tests passed.

Or, if some cases were skipped:

3/4 tests passed, 1 skipped.

On failure the summary and per-failure details go to stderr:

2/4 tests passed, 2 failed.

FAILED: empty-segment-key
  file:     conformance/syntax/parsing.json
  expected: {"type":"success","rfc6901":"/","fragment":"#/","depth":1,"isRoot":false}
  actual:   {"type":"success","rfc6901":"","fragment":"#","depth":0,"isRoot":true}

Exit codes¶

Manifest validation¶

When a directory argument (including the implicit default ./conformance) directly contains a manifest.json, the tool validates the fixtures discovered under that directory against it — see the conformance suite's manifest for the file's format and purpose. Individual file arguments and directories without a manifest.json are never validated; there is no opt-out flag.

On a match, human-mode output is unchanged. On a mismatch, a block is appended to stderr:

MANIFEST MISMATCH:
  missing:    algorithm/resolve.json
  unexpected: syntax/scratch.json
  count mismatch: syntax/parsing.json (expected 22, actual 21)

and the process exits 4 (see the exit codes table above).

Machine-readable report (--full-report)¶

The JSON report has the following shape:

{
  "reportFormat": "1.0",
  "tool": { "name": "kPointer", "version": "0.2.0" },
  "summary": {
    "total": 4,
    "passed": 3,
    "failed": 1,
    "skipped": 0,
    "ok": false
  },
  "files": [
    {
      "path": "conformance/syntax/parsing.json",
      "schema": "syntax/parsing",
      "version": "0.1.0",
      "cases": [
        { "name": "rfc6901-root", "status": "pass" },
        { "name": "empty-segment-key", "status": "fail",
          "expected": "…", "actual": "…" },
        { "name": "dot-root", "status": "skip" }
      ]
    }
  ],
  "manifest": {
    "validated": true,
    "ok": false,
    "missingFiles": ["algorithm/resolve.json"],
    "unexpectedFiles": [],
    "countMismatches": [{ "path": "syntax/parsing.json", "expected": 22, "actual": 21 }]
  }
}

status is one of "pass", "fail", or "skip". Failed cases include expected and actual strings; skipped and passed cases omit those fields.

manifest.validated is false, with every other manifest property null, when no in-scope directory input directly contained a manifest.json. When true, manifest.ok reflects whether the discovered fixtures matched it exactly. summary.ok is true only when failed == 0 and (manifest.validated is false or manifest.ok is true) — a manifest mismatch flips summary.ok to false even when every case that ran passed.

This shape is published as a JSON Schema at conformance/full-report.schema.json (schema $id: https://kpointer.commonsware.com/conformance/full-report.schema.json), part of the same conformance distribution as the fixtures. A tool in another language that consumes or produces reports in this shape — for diffing, CI gating, or cross-runner comparison — can validate against it directly instead of parsing this page. A unit test in the cli module validates real --full-report output, including failure, skip, and manifest-mismatch cases, against this schema.

kpointer resolve¶

Resolves a JSON Pointer against a document and reports the outcome.

kpointer resolve [OPTIONS] POINTER

POINTER is a JSON Pointer (RFC 6901 slash-notation), a URI fragment (#/foo), or a JavaScript access path (foo.bar). The document is read from --document FILE or from stdin.

Options¶

Outcomes and exit codes¶

Five mutually exclusive outcomes are possible:

resolved — the pointer resolved to a value. In human mode the value is printed as a plain string (primitives) or compact JSON (objects and arrays). In --json mode the value appears in the canonical model (see below).

absent — the pointer is syntactically valid but the key or index was not present in the document.

error — a kPointer error was raised during pointer parsing (KP-1xxx codes) or resolution (KP-3xxx codes). In human mode the error code and message are written to stderr as KP-NNNN: message.

invalid-input — the document root is a primitive value (string, number, boolean, or null). Pointer resolution requires a struct (object) or list (array) root.

crash — an unexpected exception was raised, typically from a malformed document (e.g. invalid JSON syntax).

--json envelope schema¶

When --json is given, one JSON object is always written to stdout regardless of outcome. The outcome field identifies the variant:

// outcome: resolved
{"outcome":"resolved","value":{"kind":"string","value":"hello"}}

// outcome: absent
{"outcome":"absent"}

// outcome: error
{"outcome":"error","errorCode":"KP-1004","message":"..."}

// outcome: invalid-input
{"outcome":"invalid-input","message":"Document root must be a struct or list, not a primitive value."}

// outcome: crash
{"outcome":"crash","exception":"SerializationException","message":"..."}

Canonical value model¶

The value field in a resolved envelope uses a canonical, adapter-neutral representation. Every primitive and container type is represented as a {"kind":"…","value":…} object. JSON and semantically equivalent YAML inputs produce byte-identical models.

This model is useful for cross-format comparisons and fuzzing: resolve the same logical pointer against a JSON document and a YAML document and compare the --json output byte-for-byte to verify adapter parity.

kpointer validate-report¶

Validates a kpointer conformance --full-report JSON file against the published full-report.schema.json, so a foreign runner's own report output can be checked without reimplementing the schema.

kpointer validate-report REPORT

REPORT is the path to a JSON file produced by kpointer conformance --full-report (from this tool or from another language's runner producing the same shape).

Exit codes¶

A committed example of a fully passing report, conformance/full-report.example.json, ships alongside the fixtures as a reference to diff your own runner's output against; a cli unit test pins it as both schema-valid and byte-for-byte equal (modulo the environment-varying tool.version field) to freshly generated --full-report output.