fix(cli): write JSON to stdout, always as an array

[KARTIKrocks]

Summary

sqlguard scan --format json > findings.json produced an empty file. The JSON reporter was built with NewJSONReporter(), which targets stderr, so the one thing a machine-readable format exists for did not work — and piping into jq saw nothing either. explain --format json had the same wiring.

Reproducing it turned up a second defect in the same user story: a clean run emitted nothing at all, so even with the stream fixed a consumer got an empty file rather than a parseable empty array.

# before
$ sqlguard scan --format json ./... > out.json   # stdout 0B, stderr 902B
$ sqlguard scan --format json ./clean > out.json # stdout 0B — not even "[]"

# after
$ sqlguard scan --format json ./... > out.json   # stdout 902B, stderr 0B, exit 1
$ sqlguard scan --format json ./clean > out.json # stdout "[]",  exit 0

Closes #70

Type of change

• Bug fix
• New detection rule
• New integration / parser
• Feature / enhancement
• Docs only
• Refactor / chore

Checklist

• make ci passes (fmt-check, vet, lint, vuln, test-race, lint-docs) across all modules
• Added/updated tests (and, where practical, a failure-mode check)
• Updated docs under website/docs/ with a version marker for anything new (_0.3+_, _Added in 0.3._, // 0.3+) — never website/versioned_docs/
• Updated AGENTS.md / .sqlguard.example.yml if a convention or config key changed
• Added an entry under ## [Unreleased] in CHANGELOG.md
• No new third-party deps in analyzer / middleware / reporter
• Findings stay redaction-safe (no raw literals leak into a Result)

AGENTS.md unticked deliberately: no convention or config key changed. The library reporter defaults are unchanged (see below), so nothing AGENTS.md documents moved.

The design decision worth reviewing

Only the CLI changed. The library defaults are deliberately left alone.

reporter.NewJSONReporter() and NewConsoleReporter() still target stderr, because a reporter wired into middleware runs inside someone else's process — writing findings to that application's stdout would corrupt its output. So the split is product-vs-diagnostic rather than a blanket rule:

	stdout	stderr
CLI --format json	the JSON array	(nothing)
CLI --format console	—	findings + summary
library reporters	—	findings

If you'd rather the library default move too, say so — it's a one-line change, but I think it's wrong for the middleware case.

Notes for reviewers

Docs were documenting the bug. website/docs/scan.md said "Findings go to stderr, so 2> redirection captures them" as though it were intended. That paragraph is rewritten to describe the split by audience, with a _Changed in 0.3._ marker and the 0.2 behaviour. I also added a CI recipe that uploads sqlguard.json as a build artifact, since that is the workflow the format exists for.

Three follow-ups from review are in the second commit:

1. explain accepted any --format value and fell back to console — so --format jsonn > plan.json dialled the database, rendered to stderr and left an empty file, re-creating this very bug for a typo. It now shares scan's newReporter and validates before connecting, so a mistake costs a message rather than a 30-second dial.
2. Now that stdout carries the product, a failed write matters: an encode error only reached a warning on stderr, so a truncated array on a full disk exited 0 and the CI recipe above would upload a corrupt artifact as green. reporter.Reporter cannot return an error, so the CLI wraps stdout in a writer that records the first failure and turns it into a non-zero exit. I did not change the Reporter interface — that ripples through middleware and all six integrations and deserves its own decision.
3. The stream-capture test helper read both pipes only after runScan returned, which deadlocks once either stream exceeds the 64 KiB pipe buffer. It now drains concurrently and closes the read ends.

Every test was checked against its own regression — each fails when the corresponding fix is reverted:

test	reverting	fails with
TestScan_JSONGoesToStdout	NewJSONReporterTo(os.Stdout) → NewJSONReporter()	findings on stderr, stdout unparseable
TestScan_JSONEmptyArrayWhenClean	reporting only when findings exist	"" instead of []
TestScan_JSONLargeOutputDoesNotDeadlock	sequential pipe reads	hangs to the test timeout

The 400-finding fixture asserts it still exceeds 64 KiB, so that guard cannot quietly stop testing anything.

Verified: make ci green across all nine modules (lint-docs fails only on an untracked local scratch file outside this branch); the Docusaurus build passes, so the new scan#usage cross-link resolves under onBrokenLinks: 'throw'.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: KARTIKrocks/sqlguard/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: a877bc41-f705-4f11-8f09-c5472478b3c9

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the remaining explain success-path coverage gap is non-blocking.

Findings

1.  Explain output lacks coverage ▶

Fix with agent prompt

### Issue 1
cmd/sqlguard/explain_test.go:43-45
Every accepted-format case stops at a connection failure, before explain reports anything. These tests cannot catch a regression in JSON stdout routing, clean `[]` output, or the findings exit status. Add a successful-plan test that reaches the JSON reporting path.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR sends CLI JSON reports to stdout and emits [] for clean runs, while keeping console output on stderr.

• It validates explain formats before connecting and makes JSON write failures return an error.
• It adds stream, output-policy, and write-error tests and updates the CLI documentation and changelog.

_{Reviews (2) · Last reviewed commit: "refactor(cli): scope the write-error to ..."}

[greptile-apps]

Explain output lacks coverage Every accepted-format case stops at a connection failure, before explain reports anything. These tests cannot catch a regression in JSON stdout routing, clean [] output, or the findings exit status. Add a successful-plan test that reaches the JSON reporting path.

Prompt To Fix With AI

This is a comment left during a code review.
Path: cmd/sqlguard/explain_test.go
Line: 43-45

Comment:
**Explain output lacks coverage** Every accepted-format case stops at a connection failure, before explain reports anything. These tests cannot catch a regression in JSON stdout routing, clean `[]` output, or the findings exit status. Add a successful-plan test that reaches the JSON reporting path.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!