beads/cmd/bd/output_test.go
Kevin Glynn 8518e71d66
feat: BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping (#3393)
* feat: add BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping

Follow-up to #3368 as discussed with @maphew. Adds the envelope format
that wraps all --json output as {"schema_version": N, "data": <payload>},
gated behind BD_JSON_ENVELOPE=1 to avoid breaking existing consumers.

Legacy mode (default): unchanged behavior from #3368 — objects get
schema_version injected inline, arrays pass through raw.

Envelope mode (BD_JSON_ENVELOPE=1): uniform wrapping for all types.
The original payload is untouched inside .data — no type corruption,
no field injection. A one-time deprecation notice is emitted to stderr
when --json is used without the env var.

Timeline: envelope becomes default in v2.0, with BD_JSON_ENVELOPE=0
as a temporary escape hatch for one release cycle.

Includes:
- wrapWithSchemaVersion dual-mode logic
- outputJSONError and buildJSONError envelope support
- Deprecation notice on stderr (once per process)
- Tests for both legacy and envelope modes
- Migration guide in docs/JSON_SCHEMA.md

* fix: suppress deprecation notice when stderr is not a TTY

Gate emitEnvelopeDeprecation() on ui.IsStderrTerminal() so the
"NOTE: bd --json output format will change in v2.0" message only
appears in interactive terminals. Test harnesses and pipelines
capture stderr via CombinedOutput(), and the trailing notice after
the JSON closing brace caused json.Unmarshal to fail with
"invalid character 'N' after top-level value" in 15 CI tests.

Follows the same TTY-gating pattern used by ShouldUseColor and
ShouldUseEmoji.

* fix: suppress gosec G304 false positive in hookWorkTreeRoot

The path is filepath.Join(os.Getenv("GIT_DIR"), "gitdir") — reading a
well-known git internal file from a trusted environment variable set by
git itself during hook execution. Not a user-controlled file inclusion.

This false positive causes the Lint CI check to fail on every PR in
the repo, masking real lint issues.
2026-04-21 13:24:17 -07:00

142 lines
3.8 KiB
Go

package main
import (
"encoding/json"
"testing"
)
func TestWrapWithSchemaVersion_Legacy_Object(t *testing.T) {
input := map[string]string{"id": "beads-123", "title": "Test"}
result := wrapWithSchemaVersion(input)
m, ok := result.(map[string]interface{})
if !ok {
t.Fatalf("expected map[string]interface{}, got %T", result)
}
if m["schema_version"] != JSONSchemaVersion {
t.Errorf("schema_version = %v, want %d", m["schema_version"], JSONSchemaVersion)
}
if m["id"] != "beads-123" {
t.Errorf("id = %v, want beads-123", m["id"])
}
}
func TestWrapWithSchemaVersion_Legacy_Slice(t *testing.T) {
input := []string{"a", "b", "c"}
result := wrapWithSchemaVersion(input)
arr, ok := result.([]string)
if !ok {
t.Fatalf("expected []string (passthrough), got %T", result)
}
if len(arr) != 3 {
t.Errorf("slice length = %d, want 3", len(arr))
}
}
func TestWrapWithSchemaVersion_Legacy_Nil(t *testing.T) {
result := wrapWithSchemaVersion(nil)
m, ok := result.(map[string]interface{})
if !ok {
t.Fatalf("expected map[string]interface{}, got %T", result)
}
if m["schema_version"] != JSONSchemaVersion {
t.Errorf("schema_version = %v, want %d", m["schema_version"], JSONSchemaVersion)
}
}
func TestWrapWithSchemaVersion_Envelope_Object(t *testing.T) {
t.Setenv("BD_JSON_ENVELOPE", "1")
input := map[string]string{"id": "beads-123", "title": "Test"}
result := wrapWithSchemaVersion(input)
m, ok := result.(map[string]interface{})
if !ok {
t.Fatalf("expected map[string]interface{}, got %T", result)
}
if m["schema_version"] != JSONSchemaVersion {
t.Errorf("schema_version = %v, want %d", m["schema_version"], JSONSchemaVersion)
}
data, ok := m["data"]
if !ok {
t.Fatal("missing 'data' key in envelope")
}
inner, ok := data.(map[string]string)
if !ok {
t.Fatalf("data type = %T, want map[string]string", data)
}
if inner["id"] != "beads-123" {
t.Errorf("data.id = %v, want beads-123", inner["id"])
}
}
func TestWrapWithSchemaVersion_Envelope_Slice(t *testing.T) {
t.Setenv("BD_JSON_ENVELOPE", "1")
input := []string{"a", "b", "c"}
result := wrapWithSchemaVersion(input)
m, ok := result.(map[string]interface{})
if !ok {
t.Fatalf("expected envelope map, got %T", result)
}
if m["schema_version"] != JSONSchemaVersion {
t.Errorf("schema_version = %v, want %d", m["schema_version"], JSONSchemaVersion)
}
data, ok := m["data"]
if !ok {
t.Fatal("missing 'data' key in envelope")
}
arr, ok := data.([]string)
if !ok {
t.Fatalf("data type = %T, want []string", data)
}
if len(arr) != 3 {
t.Errorf("data length = %d, want 3", len(arr))
}
}
func TestWrapWithSchemaVersion_Envelope_Nil(t *testing.T) {
t.Setenv("BD_JSON_ENVELOPE", "1")
result := wrapWithSchemaVersion(nil)
m, ok := result.(map[string]interface{})
if !ok {
t.Fatalf("expected envelope map, got %T", result)
}
if m["schema_version"] != JSONSchemaVersion {
t.Errorf("schema_version = %v, want %d", m["schema_version"], JSONSchemaVersion)
}
if m["data"] != nil {
t.Errorf("data = %v, want nil", m["data"])
}
}
func TestWrapWithSchemaVersion_Envelope_RoundTrip(t *testing.T) {
t.Setenv("BD_JSON_ENVELOPE", "1")
input := map[string]interface{}{"count": 42, "name": "test"}
result := wrapWithSchemaVersion(input)
data, err := json.Marshal(result)
if err != nil {
t.Fatalf("marshal: %v", err)
}
var parsed map[string]interface{}
if err := json.Unmarshal(data, &parsed); err != nil {
t.Fatalf("unmarshal: %v", err)
}
if parsed["schema_version"] != float64(JSONSchemaVersion) {
t.Errorf("schema_version = %v, want %v", parsed["schema_version"], float64(JSONSchemaVersion))
}
innerData, ok := parsed["data"].(map[string]interface{})
if !ok {
t.Fatalf("data type = %T, want map[string]interface{}", parsed["data"])
}
if innerData["count"] != float64(42) {
t.Errorf("data.count = %v, want 42", innerData["count"])
}
}