feat(watch): show syncing indicator when incremental update starts

Feature requested by @JustSuperHuman.

Adds an OnSyncing callback to DaemonConfig, called just before the
incremental API call so users see immediate feedback when a file change
is detected. The Watch command implements it as:

  ↻  Syncing N file(s)...

followed by the existing ✓ Updated line once the response arrives.

Also introduces an analyzeClient interface on Daemon so the callback
ordering can be tested without a real HTTP server.

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

Author: greynewell

internal/shards/daemon.go

@@ -29,14 +29,22 @@ type DaemonConfig struct {
 	LogFunc      func(string, ...interface{})
 	// OnReady is called once after the initial generate completes.
 	OnReady func(GraphStats)
+	// OnSyncing is called when an incremental API call starts, before the
+	// response arrives. n is the number of changed files being processed.
+	OnSyncing func(n int)
 	// OnUpdate is called after each incremental update completes.
 	OnUpdate func(GraphStats)
 }
 
+// analyzeClient is the subset of api.Client used by the daemon.
+type analyzeClient interface {
+	AnalyzeShards(ctx context.Context, zipPath, idempotencyKey string, previousDomains []api.PreviousDomain) (*api.ShardIR, error)
+}
+
 // Daemon watches for file changes and keeps shards fresh.
 type Daemon struct {
 	cfg    DaemonConfig
-	client *api.Client
+	client analyzeClient
 	cache  *Cache
 	logf   func(string, ...interface{})
 
@@ -251,6 +259,10 @@ func (d *Daemon) incrementalUpdate(ctx context.Context, changedFiles []string) {
 	}
 	defer os.Remove(zipPath)
 
+	if d.cfg.OnSyncing != nil {
+		d.cfg.OnSyncing(len(changedFiles))
+	}
+
 	ir, err := d.client.AnalyzeShards(ctx, zipPath, "incremental-"+idemKey[:8], nil)
 	if err != nil {
 		d.logf("Incremental API error: %v", err)

internal/shards/daemon_test.go

@@ -1,6 +1,7 @@
 package shards
 
 import (
+	"context"
 	"strings"
 	"testing"
 
@@ -862,3 +863,103 @@ func TestNewUUID_Version4Bits(t *testing.T) {
 		t.Errorf("expected version nibble '4' at start of 3rd group, got %q", parts[2][0])
 	}
 }
+
+// ── OnSyncing callback ────────────────────────────────────────────────────────
+
+// mockAnalyzeClient is a minimal analyzeClient that returns a fixed ShardIR.
+type mockAnalyzeClient struct {
+	result *api.ShardIR
+	err    error
+	called int
+}
+
+func (m *mockAnalyzeClient) AnalyzeShards(_ context.Context, _, _ string, _ []api.PreviousDomain) (*api.ShardIR, error) {
+	m.called++
+	return m.result, m.err
+}
+
+// orderClient records the call order of OnSyncing vs AnalyzeShards.
+type orderClient struct {
+	inner   analyzeClient
+	onCall  func()
+}
+
+func (o *orderClient) AnalyzeShards(ctx context.Context, zipPath, key string, prev []api.PreviousDomain) (*api.ShardIR, error) {
+	if o.onCall != nil {
+		o.onCall()
+	}
+	return o.inner.AnalyzeShards(ctx, zipPath, key, prev)
+}
+
+func TestOnSyncing_CalledWithCorrectFileCount(t *testing.T) {
+	var gotN int
+	d := &Daemon{
+		cfg: DaemonConfig{
+			RepoDir: t.TempDir(),
+			OnSyncing: func(n int) {
+				gotN = n
+			},
+		},
+		client: &mockAnalyzeClient{result: buildIR(nil, nil)},
+		cache:  NewCache(),
+		ir:     buildIR(nil, nil),
+		logf:   func(string, ...interface{}) {},
+	}
+	d.incrementalUpdate(context.Background(), []string{"a.go", "b.go", "c.go"})
+	if gotN != 3 {
+		t.Errorf("OnSyncing got n=%d, want 3", gotN)
+	}
+}
+
+func TestOnSyncing_CalledBeforeAPIResponse(t *testing.T) {
+	seq := 0
+	syncingAt := 0
+	apiAt := 0
+
+	mock := &mockAnalyzeClient{result: buildIR(nil, nil)}
+	d := &Daemon{
+		cfg: DaemonConfig{
+			RepoDir: t.TempDir(),
+			OnSyncing: func(int) {
+				seq++
+				syncingAt = seq
+			},
+		},
+		client: &orderClient{
+			inner: mock,
+			onCall: func() {
+				seq++
+				apiAt = seq
+			},
+		},
+		cache: NewCache(),
+		ir:    buildIR(nil, nil),
+		logf:  func(string, ...interface{}) {},
+	}
+	d.incrementalUpdate(context.Background(), []string{"a.go"})
+
+	if syncingAt == 0 {
+		t.Fatal("OnSyncing was never called")
+	}
+	if apiAt == 0 {
+		t.Fatal("AnalyzeShards was never called")
+	}
+	if syncingAt >= apiAt {
+		t.Errorf("OnSyncing (seq %d) should fire before AnalyzeShards (seq %d)", syncingAt, apiAt)
+	}
+}
+
+func TestOnSyncing_NilSafe(t *testing.T) {
+	// OnSyncing=nil should not panic.
+	d := &Daemon{
+		cfg: DaemonConfig{
+			RepoDir:   t.TempDir(),
+			OnSyncing: nil,
+		},
+		client: &mockAnalyzeClient{result: buildIR(nil, nil)},
+		cache:  NewCache(),
+		ir:     buildIR(nil, nil),
+		logf:   func(string, ...interface{}) {},
+	}
+	d.incrementalUpdate(context.Background(), []string{"a.go"})
+}

internal/shards/handler.go

@@ -263,6 +263,16 @@ func Watch(ctx context.Context, cfg *config.Config, dir string, opts WatchOption
 			line += fmt.Sprintf("  %s(%s)%s\n\n", ansiDim, src, ansiReset)
 			fmt.Print(line)
 		},
+		OnSyncing: func(n int) {
+			noun := "file"
+			if n != 1 {
+				noun = "files"
+			}
+			fmt.Printf("  %s↻%s  Syncing %s%d %s%s...\n",
+				ansiDim, ansiReset,
+				ansiBold, n, noun, ansiReset,
+			)
+		},
 		OnUpdate: func(s GraphStats) {
 			fmt.Printf("  %s✓%s  Updated — %s%d files%s · %s%d functions%s · %s%d relationships%s\n",
 				ansiGreen, ansiReset,