docs(06-06): complete scan output wiring plan

.planning/phases/06-output-reporting/06-06-SUMMARY.md

@@ -0,0 +1,110 @@
+---
+phase: 06-output-reporting
+plan: 06
+subsystem: cli
+tags: [cobra, cli, output-dispatch, exit-codes, sarif, csv, json, ci-cd]
+
+requires:
+  - phase: 06-output-reporting
+    provides: "formatter registry (table/json/csv/sarif), output.Options, ErrUnknownFormat"
+provides:
+  - "scan --output=table|json|sarif|csv wired through output.Get()"
+  - "renderScanOutput helper for hermetic unit testing"
+  - "OUT-06 exit-code contract: 0 clean, 1 findings, 2 tool error"
+  - "version var in cmd package (ldflags-settable) feeding SARIF tool.driver.version"
+affects: [07-import-hooks, 15-ci-cd-integration]
+
+tech-stack:
+  added: []
+  patterns:
+    - "Extract RunE output dispatch into a small helper (renderScanOutput) so tests exercise the dispatch path without booting scanner/DB"
+    - "Error wrapping with fmt.Errorf(\"%w (valid: %s)\", ErrUnknownFormat, ...) keeps errors.Is checks intact while surfacing user guidance"
+    - "Root Execute differentiates exit 1 (findings, set inline in scan RunE) from exit 2 (any non-nil RunE error)"
+
+key-files:
+  created:
+    - cmd/scan_output_test.go
+    - .planning/phases/06-output-reporting/06-06-SUMMARY.md
+  modified:
+    - cmd/scan.go
+    - cmd/root.go
+
+key-decisions:
+  - "Exit 1 is emitted directly inside scan RunE via os.Exit(1) before RunE returns — this preserves the 1-vs-2 split without plumbing a sentinel error"
+  - "version is declared as a package-level var (default \"dev\") so goreleaser can override via -ldflags -X; SARIF tool.driver.version uses it"
+  - "renderScanOutput takes io.Writer (not os.Stdout) so tests can capture output without redirecting file descriptors"
+  - "Unknown-format error wraps output.ErrUnknownFormat AND appends the valid list in the same string — one error, both machine-readable and human-readable"
+
+requirements-completed: [OUT-05, OUT-06]
+
+duration: 3min
+completed: 2026-04-05
+---
+
+# Phase 06 Plan 06: Scan Output Wiring and Exit Codes Summary
+
+**Scan command now dispatches --output=table|json|sarif|csv through the formatter registry and honors the OUT-06 exit-code contract (0 clean, 1 findings, 2 error) for CI/CD consumers.**
+
+## Performance
+
+- **Duration:** ~3 min
+- **Tasks:** 2
+- **Files modified:** 2 (cmd/scan.go, cmd/root.go)
+- **Files created:** 1 (cmd/scan_output_test.go)
+
+## Accomplishments
+
+- Replaced inline `jsonFinding` switch in scan RunE with a single call to `output.Get(flagOutput)` → `Formatter.Format(...)`, unlocking SARIF and CSV for scan output.
+- Extracted the dispatch into `renderScanOutput(findings, name, unmask, w io.Writer)` so the logic can be unit-tested without booting the full scanner/DB/consent pipeline.
+- Implemented OUT-06 exit-code contract:
+  - `0`: scan returns cleanly, no findings
+  - `1`: `os.Exit(1)` at the tail of scan RunE when `len(findings) > 0`
+  - `2`: root `Execute()` now maps any non-nil `rootCmd.Execute()` error to `os.Exit(2)` (was 1)
+- Added `version` package var + `versionString()` helper so SARIF `tool.driver.version` is populated and overridable via `-ldflags "-X github.com/salvacybersec/keyhunter/cmd.version=..."`.
+- Updated `--output` help text to list all four formats.
+- Four-test coverage in `cmd/scan_output_test.go`:
+  1. `TestScanOutput_FormatNamesIncludeAll` — registry wiring guard
+  2. `TestRenderScanOutput_UnknownReturnsError` — `errors.Is(err, output.ErrUnknownFormat)` + "valid:" substring
+  3. `TestRenderScanOutput_JSONSucceeds` — valid `[]` JSON for empty findings
+  4. `TestRenderScanOutput_TableEmpty` — "No API keys found" sentinel
+
+## Verification
+
+- `go build ./...` — clean
+- `go vet ./cmd/...` — clean
+- `go test ./... -count=1` — all packages green (cmd, engine, engine/sources, legal, output, providers, storage, verify)
+- `go test ./cmd/... -run "TestScanOutput|TestRenderScanOutput" -count=1` — 4/4 pass
+
+## Commits
+
+| Task | Type | Hash | Message |
+| ---- | ---- | ---- | ------- |
+| 1 | feat | c9114e4 | wire scan --output to formatter registry and exit-code contract |
+| 2 | test | cdf3c8a | cover scan output dispatch and unknown-format error |
+
+## Deviations from Plan
+
+None — plan executed exactly as written. The `renderScanOutput` helper called out as optional in Task 2 was added during Task 1 (the plan explicitly permitted this consolidation in Task 2 step 1).
+
+## Files Touched
+
+**Modified:**
+- `cmd/scan.go` — removed inline `jsonFinding` struct + `encoding/json` import; added `io`/`strings` imports; replaced output switch with `renderScanOutput` helper; introduced `version` var + `versionString()`; updated flag help text.
+- `cmd/root.go` — `Execute()` now exits with code 2 (was 1) on non-nil `rootCmd.Execute()` error, with a comment documenting the OUT-06 exit-code contract.
+
+**Created:**
+- `cmd/scan_output_test.go` — four tests covering registration, unknown-format error, JSON dispatch, table dispatch.
+
+## Known Stubs
+
+None. All four registered formatters (table, json, csv, sarif) are fully wired and exercised by tests.
+
+## Self-Check: PASSED
+
+- cmd/scan.go contains `output.Get(name)` — verified (in renderScanOutput)
+- cmd/scan.go contains `output.Options{` — verified
+- cmd/scan.go no longer contains `jsonFinding` — verified
+- cmd/root.go contains `os.Exit(2)` — verified
+- cmd/scan_output_test.go exists with four tests — verified
+- Task 1 commit c9114e4 present in git log — verified
+- Task 2 commit cdf3c8a present in git log — verified