feat(report): add json output format (#11)

- add --format flag and validation for human or json modes
  - emit structured json reports with findings, skips, and errors
  - include commit metadata, timestamps, and skip details in outputs
  - add CLI and report tests covering json success and error paths

Author: jcouture

README.md

@@ -48,7 +48,7 @@ Fingerprint: /Users/johnsmith/ghostscan/testdata/invisible/single.txt:unicode/in
 - **Payload-aware heuristics**: Flags long hidden sequences, dense suspicious regions, and explicit payload-plus-decoder correlations while keeping standalone decoder noise out of default results.
 - **Noise reduction for asset contexts**: Suppresses obvious private-use glyph mappings in font-like SVG assets so icon fonts do not dominate the report.
 - **Safe repository traversal**: Skips symlinks, NUL-containing files, oversize files, and common dependency or build directories.
-- **CI-friendly behavior**: Uses deterministic ordering, plain-text output, and exit codes `0`, `1`, and `2`.
+- **CI-friendly behavior**: Uses deterministic ordering, human or JSON output, and exit codes `0`, `1`, and `2`.
 
 ## Installation
 
@@ -84,6 +84,7 @@ ghostscan [flags] [path]
 
 Flags:
       --exclude strings     exclude files or directories matching this glob; repeatable
+      --format string       output format: human or json (default "human")
       --max-file-size int   skip files larger than this many bytes
   -n, --no-color            disable color
       --no-default-excludes disable built-in exclude globs
@@ -118,11 +119,16 @@ ghostscan . --no-default-excludes --exclude "**/*.gen.js"
 
 # Enforce a smaller max file size
 ghostscan --max-file-size 1048576 .
+
+# Emit machine-readable JSON
+ghostscan --format json ./testdata/invisible/single.txt
 ```
 
 ## Output and Exit Codes
 
-`ghostscan` prints a human-readable terminal report. In verbose mode, each finding includes:
+`ghostscan` prints a human-readable terminal report by default and emits a single JSON document when `--format json` is selected.
+
+In human verbose mode, each finding includes:
 
 - file path
 - line and column
@@ -140,6 +146,8 @@ SKIP dist/app.min.js (matched exclude: "**/*.min.js")
 SKIP vendor (matched exclude: "vendor/**")
 ```
 
+JSON output always writes one document to stdout with `tool`, `scan`, `summary`, `findings`, `skipped_files`, and `errors` keys, without ANSI color or human log lines. In JSON mode, fatal execution errors are emitted as a structured report with `errors` populated and exit code `2`.
+
 Exit codes:
 
 | Exit code | Description                                                  |

cmd/root.go

@@ -26,11 +26,13 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"time"
 
 	"github.com/spf13/pflag"
 
 	"github.com/jcouture/ghostscan/internal/app"
 	"github.com/jcouture/ghostscan/internal/exitcode"
+	"github.com/jcouture/ghostscan/internal/report"
 )
 
 func Execute() int {
@@ -63,12 +65,14 @@ func execute(ctx context.Context, args []string, stdout, stderr io.Writer) int {
 	var maxFileSize int64
 	var excludes []string
 	var noDefaultExcludes bool
+	var format string
 	flags.BoolVarP(&noColor, "no-color", "n", false, "disable color")
 	flags.BoolVarP(&version, "version", "v", false, "print version")
 	flags.BoolVar(&verbose, "verbose", false, "print detailed structured finding blocks")
 	flags.BoolVar(&silent, "silent", false, "suppress the startup banner")
 	flags.Int64Var(&maxFileSize, "max-file-size", 0, "skip files larger than this many bytes")
 	flags.StringArrayVar(&excludes, "exclude", nil, "exclude files or directories matching this glob; repeatable")
+	flags.StringVar(&format, "format", string(app.OutputFormatHuman), "output format: human or json")
 	flags.BoolVar(&noDefaultExcludes, "no-default-excludes", false, "disable built-in exclude globs")
 
 	if err := flags.Parse(args); err != nil {
@@ -78,6 +82,12 @@ func execute(ctx context.Context, args []string, stdout, stderr io.Writer) int {
 		return exitcode.ExecutionError
 	}
 
+	outputFormat := app.OutputFormat(format)
+	if err := outputFormat.Validate(); err != nil {
+		_, _ = fmt.Fprintln(stderr, err)
+		return exitcode.ExecutionError
+	}
+
 	if version {
 		_, _ = fmt.Fprintln(stdout, versionString())
 		return exitcode.Success
@@ -104,12 +114,26 @@ func execute(ctx context.Context, args []string, stdout, stderr io.Writer) int {
 		Color:              !noColor,
 		Verbose:            verbose,
 		Silent:             silent,
+		Format:             outputFormat,
 		MaxFileSize:        maxFileSize,
 		Excludes:           excludes,
 		UseDefaultExcludes: !noDefaultExcludes,
 		Version:            Version,
+		Commit:             Commit,
 	})
 	if err != nil {
+		if outputFormat == app.OutputFormatJSON {
+			now := time.Now().UTC()
+			if jsonErr := report.WriteJSONError(stdout, report.Options{
+				Version:     Version,
+				Commit:      Commit,
+				Target:      path,
+				StartedAt:   now,
+				CompletedAt: now,
+			}, err); jsonErr == nil {
+				return exitcode.ExecutionError
+			}
+		}
 		_, _ = fmt.Fprintln(stderr, err)
 		return exitcode.ExecutionError
 	}

cmd/root_bench_test.go

@@ -1,3 +1,23 @@
+// Copyright 2026 Jean-Philippe Couture
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
 package cmd
 
 import (

cmd/root_test.go

@@ -22,6 +22,7 @@ package cmd
 
 import (
 	"context"
+	"encoding/json"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -112,6 +113,12 @@ func TestExecute(t *testing.T) {
 			args:     []string{"--no-color", "--no-default-excludes", filepath.Join("..", "testdata", "clean")},
 			wantCode: exitcode.Success,
 		},
+		{
+			name:     "invalid output format",
+			args:     []string{"--format", "sarif"},
+			wantCode: exitcode.ExecutionError,
+			wantErr:  "unsupported --format",
+		},
 	}
 
 	for _, tt := range tests {
@@ -160,6 +167,103 @@ func TestExecute(t *testing.T) {
 	}
 }
 
+func TestExecuteJSONFormat(t *testing.T) {
+	t.Parallel()
+
+	var stdout strings.Builder
+	var stderr strings.Builder
+
+	code := execute(context.Background(), []string{"--format", "json", filepath.Join("..", "testdata", "clean")}, &stdout, &stderr)
+	if code != exitcode.Success {
+		t.Fatalf("execute() code = %d, want %d", code, exitcode.Success)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty output", stderr.String())
+	}
+	if strings.Contains(stdout.String(), "########") || strings.Contains(stdout.String(), "INF ") || strings.Contains(stdout.String(), "\x1b[") {
+		t.Fatalf("stdout = %q, want JSON-only output", stdout.String())
+	}
+
+	var decoded struct {
+		Tool struct {
+			Name    string `json:"name"`
+			Version string `json:"version"`
+			Commit  string `json:"commit"`
+		} `json:"tool"`
+		Findings []any `json:"findings"`
+		Errors   []any `json:"errors"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &decoded); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v\nstdout=%s", err, stdout.String())
+	}
+	if decoded.Tool.Name != "ghostscan" || decoded.Tool.Version == "" || decoded.Tool.Commit == "" {
+		t.Fatalf("tool = %+v, want populated ghostscan metadata", decoded.Tool)
+	}
+	if len(decoded.Findings) != 0 || len(decoded.Errors) != 0 {
+		t.Fatalf("decoded = %+v, want clean report", decoded)
+	}
+}
+
+func TestExecuteJSONFormatFindingsExitCode(t *testing.T) {
+	t.Parallel()
+
+	var stdout strings.Builder
+	var stderr strings.Builder
+
+	code := execute(context.Background(), []string{"--format", "json", filepath.Join("..", "testdata", "invisible")}, &stdout, &stderr)
+	if code != exitcode.FindingsDetected {
+		t.Fatalf("execute() code = %d, want %d", code, exitcode.FindingsDetected)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty output", stderr.String())
+	}
+
+	var decoded struct {
+		Summary struct {
+			FindingsTotal int `json:"findings_total"`
+		} `json:"summary"`
+		Findings []struct {
+			RuleID string `json:"rule_id"`
+		} `json:"findings"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &decoded); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v\nstdout=%s", err, stdout.String())
+	}
+	if decoded.Summary.FindingsTotal == 0 || len(decoded.Findings) == 0 {
+		t.Fatalf("decoded = %+v, want findings", decoded)
+	}
+	if decoded.Findings[0].RuleID == "" {
+		t.Fatalf("findings[0] = %+v, want rule id", decoded.Findings[0])
+	}
+}
+
+func TestExecuteJSONFormatExecutionError(t *testing.T) {
+	t.Parallel()
+
+	var stdout strings.Builder
+	var stderr strings.Builder
+
+	code := execute(context.Background(), []string{"--format", "json", filepath.Join(t.TempDir(), "missing")}, &stdout, &stderr)
+	if code != exitcode.ExecutionError {
+		t.Fatalf("execute() code = %d, want %d", code, exitcode.ExecutionError)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want no stderr when JSON error report is emitted", stderr.String())
+	}
+
+	var decoded struct {
+		Errors []struct {
+			Message string `json:"message"`
+		} `json:"errors"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &decoded); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v\nstdout=%s", err, stdout.String())
+	}
+	if len(decoded.Errors) != 1 || !strings.Contains(decoded.Errors[0].Message, "discover files from") {
+		t.Fatalf("errors = %+v, want structured fatal execution error", decoded.Errors)
+	}
+}
+
 func TestExecuteHelp(t *testing.T) {
 	t.Parallel()