docs(#95): document ccxray usage --json schema + shape-contract test#101
Merged
Conversation
Add docs/usage.md as the agent-facing contract reference for `ccxray usage --json`: the single-scope object, multi-cwd comparison array, and error object, with per-field types, rounding caps, and the full filter semantics (--last/--cwd/--session/--tools/--open). Cross-linked from README (Usage Analytics) and docs/data-model.md. Doc mirrors server/usage.js (analyze()); verified field-by-field and through two codex review passes — corrected over-claims around percentile method, numeric precision (at-most-N decimals, JSON drops trailing zeros), --open 0-match silence, and --open / "unknown" grouping behavior in multi-cwd mode. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a `usage --json shape contract` test block that asserts the exact
key set and field types of every section (meta/sessions/topSessions/
models/tools/skills/prompts/cache/gapCache) plus the multi-cwd array row
shape, cost-desc ordering, and the { error, hint } error object.
Exact-key assertions catch BOTH a removed field and an accidentally
leaked extra one — turning the agent-facing contract in docs/usage.md
into something CI enforces, not just prose. Nullable fields (title,
skills.loads, skills.scope) lock type-or-null; environment-derived
values are not pinned, keeping the test deterministic across machines.
Update the doc's contract note + changelog to point at this test as the
enforcement mechanism.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Pre-merge review fixes to docs/usage.md: - The intro previously promised value-level determinism and then tried to enumerate exceptions, which kept missing run-time inputs (--last is relative to now, --cwd ~ expands to the local home dir, skills[].scope reads the local filesystem). Reframe the contract as a STABLE SHAPE (key set + field types); values track the index and the runtime environment, with the per-flag/run-time behavior pointed to where it is already documented precisely. - The contract note no longer claims the shape-contract test locks the size budget; size is a separate <5KB-ceiling test, with <4KB framed as the working target under that ceiling. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #95.
What
Documents the
ccxray usage --jsonoutput as an agent-facing contract, and adds a test that enforces it.docs/usage.md(new) — field-by-field reference for all three output shapes: the single-scope object, the multi-cwd comparison array, and the{ error, hint }error object. Plus the full filter semantics (--last/--cwd/--session/--tools/--open) and per-field precision.test/usage.test.js— newusage --json shape contractblock. Exact-key assertions on every section + the multi-cwd row and error shapes, so an accidental field add/remove fails CI. Nullable fields lock type-or-null; environment-derived values aren't pinned (deterministic across machines).Contract framing
The intro frames the contract as a stable shape (key set + field types), not value-level determinism — values track the index and a few run-time-resolved inputs (
--lastrelative to now,--cwd ~home expansion,skills[].scopefrom the local filesystem), each documented where it applies.Verification
node --test test/usage.test.js→ 53 pass / 0 fail.server/usage.js(analyze()+run()), then through repeated codex review passes that corrected several over-claims (percentile method, numeric precision,--open0-match / multi-cwd behavior, multi-cwd"unknown"grouping, determinism scope, size-budget wording, source-of-truth attribution) until clean.🤖 Generated with Claude Code