feat(doctor): add --json flag for structured machine-readable output#620
Merged
esengine merged 2 commits intoMay 11, 2026
Merged
Conversation
Enables programmatic consumption of doctor results by CI pipelines and tooling that need to parse health-check status without scraping human-formatted output. Each check now carries a stable `id` so downstream consumers can key off specific checks rather than brittle label strings, while exit-code semantics and the default text output remain unchanged.
Owner
|
Looks great — implementation matches the spec cleanly, tests are in the right shape, no new deps. Just a couple of lint nits blocking CI:
Once CI's green, happy to merge. Thanks for picking this up. |
Author
|
i will fix the CI, just a moment |
Vitest's `vi.stubEnv` and `vi.unstubAllEnvs` provide automatic restoration of environment variables between tests, eliminating the manual save/restore boilerplate that's easy to get wrong. Collapsing the multi-line import also keeps the test file consistent with single-line import style elsewhere.
Author
|
Pushed an update addressing the follow-up.
|
Owner
|
Clean implementation — id taxonomy lines up with the actual checks, the helper is properly factored, tests cover both the shape and the exit-code branch. CI green. Merging. Thanks for the contribution! |
ChasLui
pushed a commit
to ChasLui/DeepSeek-Reasonix
that referenced
this pull request
May 23, 2026
…sengine#620) * feat(doctor): add --json flag for structured machine-readable output Enables programmatic consumption of doctor results by CI pipelines and tooling that need to parse health-check status without scraping human-formatted output. Each check now carries a stable `id` so downstream consumers can key off specific checks rather than brittle label strings, while exit-code semantics and the default text output remain unchanged. * test(doctor): use vi.stubEnv for env isolation in --json tests Vitest's `vi.stubEnv` and `vi.unstubAllEnvs` provide automatic restoration of environment variables between tests, eliminating the manual save/restore boilerplate that's easy to get wrong. Collapsing the multi-line import also keeps the test file consistent with single-line import style elsewhere.
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
2 participants
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.
Summary
Adds a
--jsonflag toreasonix doctorthat emits a single structured JSON document withversion,summary, andchecks[], intended for CI pipelines and tooling that need to parse health-check status without scraping human-formatted output. Default (flag absent) text output and exit-code semantics are unchanged: anyfailcheck still exits 1, otherwise 0.Changes
src/cli/commands/doctor.ts: extendDoctorCheckwith a stableidfield on every check (api-key,config,api-reach,tokenizer,sessions,hooks,semantic,project); addDoctorOptionsand accept it ondoctorCommand; addformatDoctorJson(checks, version)helper that builds{ version, summary: { ok, warn, fail }, checks: [{ id, status, message }] }; when--jsonis set, suppress the header, per-check lines, and colored summary so stdout stays a single jq-parseable document, while still callingprocess.exit(1)on any fail.src/cli/index.ts: register.option("--json", t("ui.jsonHint"))on thedoctorcommand and forward{ json: !!opts.json }intodoctorCommand.tests/doctor-json.test.ts: new vitest coveringformatDoctorJsonshape (version, summary counts, per-check{id,status,message}) anddoctorCommand({ json: true })end-to-end — asserts a single JSON document is written to stdout, no header/summary leaks, and exit code is 1 when any check fails / 0 otherwise.Testing
npm test -- tests/doctor-json.test.ts— passes locally. The test stubsrunDoctorChecksso no network or filesystem state is required, and capturesconsole.logplus a mockedprocess.exitto verify both the payload and the exit-code branch.Notes
The
idvalues are derived from the existing labels and are now part of the exportedDoctorChecktype. There are no in-repo consumers ofDoctorCheckoutsidedoctor.ts, so this is additive for external callers — downstream tools should key offidrather than the human-formattedlabel, which remains a presentation detail.Closes #15