Skip to content

lumen writes only JSON Lines to standard output, under lumen-message/1 (#219) - #270

Draft
flyingrobots wants to merge 2 commits into
mainfrom
feat/jsonl-stdout
Draft

flyingrobots wants to merge 2 commits into
mainfrom
feat/jsonl-stdout

Conversation

@flyingrobots

Copy link
Copy Markdown
Owner

Closes #219

Work in progress: the JSON writer in the command, the lumen-message/1 schema, the messages of ADR 0015 for render, stats, --help and --version, the tests and documentation moved to them.

The first commit of #219: the changelog's entry for the
command describes its standard output as the messages of ADR 0015.

Issue: #219
Agent-Session: 7659171b-5ea2-4675-adcf-cb84ac79c847
Agent-Tool: Claude Code
@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Not yet compiled or tested: the command writes lumen-message/1 messages
(json.rs, messages.rs, stats.rs), schemas/lumen-message-1.schema.json, an
independent test JSON parser and schema-subset validator (tests/json/), and
part of tests/cli.rs moved off the key-value report. Paused by the maintainer.

Issue: #219
Agent-Session: 7659171b-5ea2-4675-adcf-cb84ac79c847
Agent-Tool: Claude Code
@flyingrobots

Copy link
Copy Markdown
Owner Author

Handoff (paused)

Done (committed in b271a7b, pushed; not compiled or tested yet: no container run was made)

  • crates/lumen/src/bin/lumen/json.rs (+ json/tests.rs): a JSON writer (objects, arrays, strings, u64 integers, bool, null; no float). It escapes ", \ and U+0000 to U+001F; the unit tests check the edges U+001F, U+0020 and U+007F, u64::MAX and every character up to U+00FF.
  • messages.rs (+ tests) replaces report.rs: provenance, result, timings (integer µs, saturating at u64::MAX, with a test on that limit), help, version, and emit (one line per message, flushed).
  • stats.rs and stats/traversal.rs build scene_statistics, ray_statistics, traversal_statistics and run_statistics. No means are printed (only totals and counts), and fixed-point values are strings. stats/tests.rs is rewritten to compare against hand-written JSON, and its doc check now looks for each member path in the section ### `TYPE` of cli.md.
  • main.rs prints provenance after the preflight and before the render, then result and timings, then the stats messages. The usage text now says that stdout is JSON Lines.
  • schemas/lumen-message-1.schema.json is generated, uses only a JSON Schema subset, and dispatches on type through allOf/if/then/$ref.
  • crates/lumen/tests/json/{mod.rs,schema.rs}: an independent RFC 8259 parser and a validator for that subset. The validator refuses any keyword outside the subset. The module also provides messages(), which parses and validates every stdout line, plus the helpers one() and types().
  • tests/cli.rs is about half moved: Scratch::lumen now checks every run's stdout.

Not done

  • The rest of cli.rs: the stats tests near the end still use field, and so do the non-Unicode tests and lumen_that_must_refuse_quickly. I also need to add a test that a path with quotes, a control character and non-ASCII round-trips.
  • A new small test file for the parser, the validator and the schema range limits (each limit exactly on it and one past it).
  • tests/tutorial.rs.
  • The docs: cli.md (the report, the stats tables, the usage block), tutorial.md, README (expect a conflict with README: show the three built-in scenes, with the reference scene as the hero image (#180) #268), explanation.md (line 161 and a new evidence-map row), how-to/measure-performance.md, library.md:167, docs/README.md:12, CONTRIBUTING (lines 40 and 148), and a dated clarification in ADR 0015. CHANGELOG is partly done.
  • Mutation evidence, the full gate, and the PR description.

Exact next step: finish cli.rs, then build in the container:
python3 ~/git/devcontainers/bin/devrun lumen ~/git/lumen-219 --worktree --fetch --cpus 4 --memory 8g --timeout 2400 -- cargo clippy --workspace --all-targets --locked -- -D warnings
then cargo test --locked -p lumen.

Open questions for the coordinator

  • ADR 0015 does not set the schema's $id. I left it out rather than choose a URL.
  • scene_statistics also carries scene, scene_content and integrator, so that lumen stats loses nothing.
  • Some member spellings are mine: material_triangles/material_albedo, light.sun (null or an object), KIND.COUNTER_max.
  • A non-Unicode png.path is written in its lossy form (display()), with no lossy flag.

Uncommitted: nothing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

lumen writes only JSON Lines to standard output, under lumen-message/1

1 participant