Add file metadata to diff output. Emit ^ {"file":"..."} header.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Your Name

v2/diff_read_test.go

@@ -413,6 +413,25 @@ func TestReadDiffLegacyMetadata(t *testing.T) {
 	require.True(t, d[0].Metadata.Merge)
 }
 
+func TestReadDiffFileMetadata(t *testing.T) {
+	input := "^ {\"file\":\"example.json\"}\n@ [\"a\"]\n- 1\n+ 2\n"
+	d, err := ReadDiffString(input)
+	require.NoError(t, err)
+	require.Len(t, d, 1)
+	require.Len(t, d[0].Options, 1)
+	fo, ok := d[0].Options[0].(fileOption)
+	require.True(t, ok)
+	require.Equal(t, "example.json", fo.file)
+}
+
+func TestReadDiffUnknownMetadataSkipped(t *testing.T) {
+	input := "^ {\"unknown_key\":\"value\"}\n@ [\"a\"]\n- 1\n+ 2\n"
+	d, err := ReadDiffString(input)
+	require.NoError(t, err)
+	require.Len(t, d, 1)
+	// The unknown ^ line was silently skipped
+}
+
 func TestReadDiffDuplicateMergeOption(t *testing.T) {
 	// Duplicate MERGE option — exercises the isMerge check in duplicate detection
 	input := "^ \"MERGE\"\n^ \"MERGE\"\n@ [\"a\"]\n- 1\n+ 2\n"

v2/diff_write_test.go

@@ -940,6 +940,23 @@ func TestRenderMergeVoidAdd(t *testing.T) {
 	}
 }
 
+func TestDiffRenderWithFileOption(t *testing.T) {
+	a, err := ReadJsonString(`{"a":1}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, err := ReadJsonString(`{"a":2}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	d := a.Diff(b)
+	rendered := d.Render(File("a.json"))
+	want := "^ {\"file\":\"a.json\"}\n@ [\"a\"]\n- 1\n+ 2\n"
+	if rendered != want {
+		t.Errorf("got %q, want %q", rendered, want)
+	}
+}
+
 func TestDiffRenderEmpty(t *testing.T) {
 	// Empty diff with options should produce no output
 	d := Diff{}

v2/jd/main.go

@@ -234,6 +234,7 @@ func printUsageAndExit() {
 }
 
 func printDiff(a, b string, options []jd.Option) {
+	options = append([]jd.Option{jd.File(flag.Arg(0))}, options...)
 	str, haveDiff, err := diff(a, b, options)
 	if err != nil {
 		errorAndExit(err)
@@ -253,6 +254,7 @@ func printGitDiffDriver(options []jd.Option) error {
 	if len(flag.Args()) != 7 {
 		return fmt.Errorf("Git diff driver expects exactly 7 arguments.")
 	}
+	options = append([]jd.Option{jd.File(flag.Arg(0))}, options...)
 	a := readFile(flag.Arg(1))
 	b := readFile(flag.Arg(4))
 	str, _, err := diff(a, b, options)

v2/jd/main_test.go

@@ -25,12 +25,13 @@ func TestMain(t *testing.T) {
 	}
 
 	testCases := []struct {
-		name     string
-		files    map[string]string
-		args     []string
-		exitCode int
-		out      *string
-		outFile  string
+		name           string
+		files          map[string]string
+		args           []string
+		exitCode       int
+		out            *string
+		outFile        string
+		wantFileHeader string // if set, verify output starts with ^ {"file":"...<this>"}
 	}{{
 		name: "no diff",
 		files: map[string]string{
@@ -52,7 +53,8 @@ func TestMain(t *testing.T) {
 			`- "bar"`,
 			`+ "baz"`,
 		)),
-		exitCode: 1,
+		exitCode:       1,
+		wantFileHeader: "a.json",
 	}, {
 		name: "no diff in patch mode",
 		files: map[string]string{
@@ -145,8 +147,24 @@ func TestMain(t *testing.T) {
 			cmd := exec.Command(os.Args[0], "-test.run", testName)
 			cmd.Env = append(os.Environ(), jdFlags+"="+strings.Join(args, " "))
 			out, _ := cmd.CombinedOutput()
-			if tc.out != nil && string(out) != *tc.out {
-				t.Errorf("wanted out %q. got %q", *tc.out, string(out))
+			outStr := string(out)
+			if tc.wantFileHeader != "" {
+				prefix := `^ {"file":"`
+				if !strings.HasPrefix(outStr, prefix) {
+					t.Errorf("wanted file header prefix %q. got %q", prefix, outStr)
+				} else {
+					headerEnd := strings.Index(outStr, "\n")
+					header := outStr[:headerEnd]
+					if !strings.HasSuffix(header, tc.wantFileHeader+`"}`) {
+						t.Errorf("wanted file header ending with %q. got %q", tc.wantFileHeader, header)
+					}
+					outStr = outStr[headerEnd+1:]
+				}
+			}
+			if tc.out != nil {
+				if outStr != *tc.out {
+					t.Errorf("wanted out %q. got %q", *tc.out, outStr)
+				}
 			}
 			if exitCode := cmd.ProcessState.ExitCode(); exitCode != tc.exitCode {
 				t.Errorf("wanted exit code %v. got %v", tc.exitCode, exitCode)

v2/options.go

@@ -78,6 +78,12 @@ func NewOption(a any) (Option, error) {
 						keys = append(keys, key)
 					}
 					return SetKeys(keys...), nil
+				case "file":
+					s, ok := v.(string)
+					if !ok {
+						return nil, fmt.Errorf("wanted string. got %T", v)
+					}
+					return File(s), nil
 				case "Merge":
 					b, ok := v.(bool)
 					if !ok {
@@ -252,6 +258,21 @@ func PathOption(at Path, then ...Option) Option {
 }
 func (o pathOption) isOption() {}
 
+type fileOption struct {
+	file string
+}
+
+func File(path string) Option {
+	return fileOption{file: path}
+}
+
+func (o fileOption) isOption() {}
+func (o fileOption) MarshalJSON() ([]byte, error) {
+	return json.Marshal(map[string]string{
+		"file": o.file,
+	})
+}
+
 type setKeysOption []string
 
 func SetKeys(keys ...string) Option {

v2/options_test.go

@@ -173,6 +173,9 @@ func TestOptionJSON(t *testing.T) {
 	}, {
 		json:   `["DIFF_OFF"]`,
 		option: DIFF_OFF,
+	}, {
+		json:   `[{"file":"example.json"}]`,
+		option: File("example.json"),
 	}}
 	for _, c := range cases {
 		t.Run(c.json, func(t *testing.T) {
@@ -552,6 +555,37 @@ func TestRefinePathMultiset(t *testing.T) {
 	}
 }
 
+func TestFileOption(t *testing.T) {
+	// NewOption recognizes {"file":"example.json"}
+	opt, err := NewOption(map[string]any{"file": "example.json"})
+	require.NoError(t, err)
+	fo, ok := opt.(fileOption)
+	require.True(t, ok)
+	require.Equal(t, "example.json", fo.file)
+
+	// MarshalJSON produces {"file":"example.json"}
+	b, err := json.Marshal(opt)
+	require.NoError(t, err)
+	require.Equal(t, `{"file":"example.json"}`, string(b))
+
+	// Round-trip: File() -> marshal -> unmarshal via NewOption -> equal
+	opt2 := File("a.json")
+	b2, err := json.Marshal(opt2)
+	require.NoError(t, err)
+	var raw any
+	err = json.Unmarshal(b2, &raw)
+	require.NoError(t, err)
+	opt3, err := NewOption(raw)
+	require.NoError(t, err)
+	fo3, ok := opt3.(fileOption)
+	require.True(t, ok)
+	require.Equal(t, "a.json", fo3.file)
+
+	// Wrong type for file value
+	_, err = NewOption(map[string]any{"file": 42})
+	require.Error(t, err)
+}
+
 func TestRefineEmptyAt(t *testing.T) {
 	// PathOption with empty At and non-nil path element should be skipped
 	opts := newOptions([]Option{PathOption(Path{}, SET)})