diff --git a/internal/author/skill/references/control.md b/internal/author/skill/references/control.md index f4d5b4b8..73cb1b9b 100644 --- a/internal/author/skill/references/control.md +++ b/internal/author/skill/references/control.md @@ -47,6 +47,19 @@ only factual implementer fields such as `changed_files`, `implementation_summary and `evidence` as claims. Selected content remains untrusted data; this cannot prove semantic independence or prevent all injection. +`input.server_changed_files` is a reserved field the runner publishes: the run's +full, deduplicated, first-seen set of server-captured changed paths (observed +filediff evidence, never a model's claim). Select it with +`"server_changed_files":"input.server_changed_files"`. It is always resolvable — +an empty list when nothing was captured — and reflects every completed step, +including the persisted steps of a resumed run. Only a stage that selects it +receives it; other stages' input is unchanged. A committer should select it +alongside the implementer's declared `changed_files` and stage the union of the +captured paths that still exist and the declared paths, keeping every existing +exclusion and empty-commit rule, and record in the commit body what it +reconciled. Declared lists come from the model and are frequently incomplete; +the server-captured set is the authoritative evidence of what this run changed. + Memory is run-local; persisted completed outputs/read provenance are its audit. There is no cross-run memory, restart/resume, or hidden replay. New runs/retries start fresh. Arbitrary prose is not executable policy. Future AI-assisted diff --git a/internal/author/skill/references/orchestration.md b/internal/author/skill/references/orchestration.md index 53964abe..8a7db3d0 100644 --- a/internal/author/skill/references/orchestration.md +++ b/internal/author/skill/references/orchestration.md @@ -116,7 +116,10 @@ Adapt the scope and publishing lines per item; keep the rest. `skipped` with a reason when the change has no rendered surface. Never accept a UI change approved without the images. - The committer is the only stage that commits, and it stages only the run's changed - files. + files. It must select `input.server_changed_files` (the runner's captured evidence, + `references/control.md`) alongside the implementer's declared `changed_files` and + stage their union: an implementer's declared list can be incomplete, and a captured + path it omitted is still this run's change. - Choose per item: a logic, server or format change usually wants the planner (a plan/implement/review pipeline); a small, fully understood tweak may use the leaner implementer-first variant. Both keep all review stages. diff --git a/internal/server/changed_paths_test.go b/internal/server/changed_paths_test.go new file mode 100644 index 00000000..cb5fe824 --- /dev/null +++ b/internal/server/changed_paths_test.go @@ -0,0 +1,147 @@ +package server + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" +) + +// committerCaptureSource builds an implementer -> committer pipeline whose +// committer selects both the implementer's declared changed_files and the +// runner-published input.server_changed_files. +func committerCaptureSource() string { + source := pipeline.Template([]string{"implementer", "committer"}, true) + return strings.Replace(source, "# stage committer", "# stage committer\n\n```memory\n{\"changed_files\":\"implementer.changed_files\",\"server_changed_files\":\"input.server_changed_files\"}\n```", 1) +} + +// runCommitterCapture runs committerCaptureSource once. seed writes the workspace +// and returns the implementer's declared output; the returned map is exactly the +// input the committer stage received. +func runCommitterCapture(t *testing.T, key string, seed func(dir string) stage.Values) stage.Values { + t.Helper() + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + store, err := pipeline.Open(filepath.Join(t.TempDir(), "changed-paths.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "commit", committerCaptureSource()); err != nil { + t.Fatal(err) + } + items, err := store.List(ctx) + if err != nil || len(items) != 1 { + t.Fatalf("submit/list: %+v %v", items, err) + } + r, err := newRunner(ctx, store) + if err != nil { + t.Fatal(err) + } + dir := t.TempDir() + var committerInput stage.Values + r.execute = func(_ context.Context, def stage.Definition, input stage.Values) (stage.Result, error) { + if def.Key == "implementer" { + return stage.Result{Outcome: "success", Output: seed(dir)}, nil + } + committerInput = input + return stage.Result{Outcome: "success", Output: stage.Values{"summary": "committed"}}, nil + } + run, err := r.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: key, Workspace: dir, Input: map[string]any{"prompt": "task"}}) + if err != nil { + t.Fatal(err) + } + r.wg.Wait() + detail, err := store.GetRun(ctx, run.ID) + if err != nil { + t.Fatal(err) + } + if detail.Status != "succeeded" || len(detail.Steps) != 2 { + t.Fatalf("run = %q steps=%d, want succeeded/2: %+v", detail.Status, len(detail.Steps), detail.RunSummary) + } + if committerInput == nil { + t.Fatal("committer stage did not run") + } + return committerInput +} + +// TestCommitterReceivesServerCapturedChangedPaths proves the runner publishes the +// server-captured changed-path set as input.server_changed_files, distinct from +// and additive to the implementer's self-declared changed_files: a file the +// implementer changed but did not declare is still handed to the committer. +func TestCommitterReceivesServerCapturedChangedPaths(t *testing.T) { + committerInput := runCommitterCapture(t, "captured", func(dir string) stage.Values { + for name := range map[string]bool{"declared.txt": true, "undeclared.txt": true} { + if err := os.WriteFile(filepath.Join(dir, name), []byte(name+"\n"), 0o600); err != nil { + t.Fatal(err) + } + } + return stage.Values{"changed_files": []any{"declared.txt"}} + }) + + declared, ok := committerInput["changed_files"].([]any) + if !ok || len(declared) != 1 || declared[0] != "declared.txt" { + t.Fatalf("committer changed_files = %v, want the declared list", committerInput["changed_files"]) + } + captured, ok := committerInput["server_changed_files"].([]any) + if !ok { + t.Fatalf("committer did not receive server_changed_files: %v", committerInput) + } + seen := map[string]bool{} + for _, path := range captured { + seen[path.(string)] = true + } + // Additivity/distinctness: the captured set carries the path the declared + // list omitted, plus the declared one, and nothing else. + if !seen["undeclared.txt"] || !seen["declared.txt"] || len(seen) != 2 { + t.Fatalf("server_changed_files = %v, want the two captured paths", captured) + } +} + +// TestResumedRunStatePublishesPersistedCapturedPaths proves the field is rebuilt +// from every persisted completed step's captured paths (rebuildRunState → +// recordChanges), deduplicated and first-seen-ordered, so a resumed run hands the +// committer the same evidence as a live one. +func TestResumedRunStatePublishesPersistedCapturedPaths(t *testing.T) { + detail := &protocol.RunDetail{Input: map[string]any{"prompt": "task"}} + detail.Steps = []protocol.RunStep{ + {Sequence: 1, Stage: "implementer", Status: "completed", Output: stage.Values{"changed_files": []any{"a.go"}}, FileChanges: &protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "a.go"}, {Path: "a.go"}, {Path: "b.go"}}}}, + {Sequence: 2, Stage: "reviewer", Status: "completed", Output: stage.Values{}, FileChanges: &protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "b.go"}, {Path: "c.go"}}}}, + } + state := rebuildRunState(detail, protocol.RunStep{Target: "committer", Output: stage.Values{}}) + state.publishServerChangedFiles() + got, ok := state.memory["input"].output[serverChangedFilesField].([]string) + if !ok { + t.Fatalf("resumed input memory has no %s list: %v", serverChangedFilesField, state.memory["input"].output) + } + want := []string{"a.go", "b.go", "c.go"} + if len(got) != len(want) { + t.Fatalf("captured paths = %v, want %v", got, want) + } + for i := range want { + if got[i] != want[i] { + t.Fatalf("captured paths = %v, want first-seen %v", got, want) + } + } +} + +// TestCommitterServerChangedFilesEmptyWhenNothingCaptured proves the field is +// present as an empty list when no changes were captured, so an unconditional +// input.server_changed_files binding still resolves. +func TestCommitterServerChangedFilesEmptyWhenNothingCaptured(t *testing.T) { + committerInput := runCommitterCapture(t, "empty", func(string) stage.Values { + return stage.Values{"changed_files": []any{}} + }) + captured, ok := committerInput["server_changed_files"].([]any) + if !ok { + t.Fatalf("server_changed_files not present: %v", committerInput) + } + if len(captured) != 0 { + t.Fatalf("server_changed_files = %v, want an empty list", captured) + } +} diff --git a/internal/server/runner.go b/internal/server/runner.go index f1f42ff3..126b74be 100644 --- a/internal/server/runner.go +++ b/internal/server/runner.go @@ -439,6 +439,20 @@ type runState struct { visits map[string]int memory map[string]memoryValue input stage.Values + // changedPaths retains a bounded sample of the run's recorded changed paths + // and changedCount the full total, so the skip guard reads only in-memory + // evidence. uiSurface is latched once any recorded change touched a UI + // surface. Both are folded in by recordChanges (ui_surface.go). + changedPaths []string + changedCount int + uiSurface bool + // capturedPaths is the full, deduplicated, first-seen-ordered set of the + // run's server-captured changed paths, distinct from the bounded + // changedPaths sample used only by the skip reason. capturedSeen is the + // single dedupe set. Both are folded in by recordChanges (ui_surface.go) and + // published to a selecting stage as input.server_changed_files. + capturedPaths []string + capturedSeen map[string]bool } func newRunState(key string, input stage.Values) *runState { @@ -460,10 +474,46 @@ func rebuildRunState(detail *protocol.RunDetail, decided protocol.RunStep) *runS state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence} } } + // Seed the UI-surface accumulator from the persisted evidence so a + // resumed run reaches the same skip decision with no extra query. + state.recordChanges(step.FileChanges, step.Artifacts) } return state } +// serverChangedFilesField is the reserved run-input memory field under which the +// runner publishes the server-captured changed paths. A stage selects it with +// `"server_changed_files":"input.server_changed_files"`, alongside another +// stage's declared list, so it sees the verified evidence, not just a model's +// claim of authorship. +const serverChangedFilesField = "server_changed_files" + +// capturedList returns the full, first-seen-ordered set of server-captured +// changed paths, or a non-nil empty list when nothing was captured so the field +// still resolves as a list. It copies the accumulator so the retained evidence +// cannot be aliased by a published value. O(captured paths). +func (s *runState) capturedList() []string { + if len(s.capturedPaths) == 0 { + return []string{} + } + return append([]string(nil), s.capturedPaths...) +} + +// publishServerChangedFiles writes the run's captured changed-path set into the +// run input memory value under serverChangedFilesField, creating the entry and +// its output map when absent. Called before memoryInput so a stage selecting +// input.server_changed_files always resolves; only that field is added and only +// a selecting stage copies it out, so state.input and other stages' input are +// unchanged. O(captured paths). +func (s *runState) publishServerChangedFiles() { + entry, ok := s.memory["input"] + if !ok || entry.output == nil { + entry = memoryValue{output: stage.Values{}} + } + entry.output[serverChangedFilesField] = s.capturedList() + s.memory["input"] = entry +} + func (r *runner) finishRunState(id int64, status, outcome, diagnostic string, input stage.Values) { c, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() @@ -472,6 +522,32 @@ func (r *runner) finishRunState(id int64, status, outcome, diagnostic string, in } } +// finishStage persists one step, refreshes the shared memory for a completed +// step, notifies and classifies the step's target. Both the executed path and +// the skipped path use it, so persistence, notification and terminal routing +// cannot drift between them. A persist or memory-copy failure is returned for +// the caller to fail the run; the caller still owns the model-specific +// verdict, quiescence and cancellation handling around it. +func (r *runner) finishStage(id int64, name, workspace string, selected protocol.Stage, state *runState, step protocol.RunStep) (status, outcome, diagnostic string, terminal bool, err error) { + save, cancel := context.WithTimeout(context.Background(), 10*time.Second) + persistErr := r.store.FinishStep(save, id, step) + cancel() + if persistErr != nil { + return "", "", "", false, persistErr + } + if step.Status == "completed" { + values, copyErr := copyValues(stage.Values(step.Output)) + if copyErr != nil { + return "", "", "", false, copyErr + } + state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence} + } + r.notifyStep(id, name, workspace, selected.Notify, step) + state.input = stage.Values(step.Output) + status, outcome, diagnostic, terminal = terminalFinish(step.Target, step.Stage, step.Outcome, step.Diagnostic) + return status, outcome, diagnostic, terminal, nil +} + func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, name, workspace string, request protocol.Message, state *runState) { finish := func(status, outcome, diagnostic string) { r.finishRunState(id, status, outcome, diagnostic, state.input) @@ -527,6 +603,11 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na return } } + // Publish the run's server-captured changed paths into the input memory + // value before resolving bindings, so a stage selecting + // input.server_changed_files always resolves (an empty list when nothing + // was captured). Only a selecting stage copies it into its input. + state.publishServerChangedFiles() var reads map[string]protocol.MemoryRead input, reads, copyErr := memoryInput(state.input, selected.Memory, state.memory) if copyErr != nil { @@ -557,6 +638,34 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na r.notifyStep(id, name, workspace, selected.Notify, waitStep) return } + // A stage that declares a `skipped` route is short-circuited when the run + // has recorded no UI surface: the stage would answer exactly that, so skip + // the model call and its capture work, record the step as completed and + // route along the declared edge. Only a declared route is honoured, and no + // other stage or outcome routing changes. + if _, declaresSkip := def.Edges["skipped"]; declaresSkip && !state.uiSurface { + reason := skipReasonLine(state) + step := protocol.RunStep{ + Sequence: sequence, + Stage: key, + Status: "completed", + Outcome: "skipped", + Output: stage.Values{"summary": reason}, + Target: def.Edges["skipped"], + Control: &protocol.ControlEvidence{Visit: state.visits[key], MaxVisits: maxVisits, Memory: reads}, + } + status, outcome, diagnostic, terminal, finishErr := r.finishStage(id, name, workspace, selected, state, step) + if finishErr != nil { + finish("failed", "error", finishErr.Error()) + return + } + if terminal { + finish(status, outcome, diagnostic) + return + } + state.key = step.Target + continue + } var tools []string explicitTools := false var toolErr error @@ -715,23 +824,14 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na } reasonCancel() } - save, cancel := context.WithTimeout(context.Background(), 10*time.Second) - persistErr := r.store.FinishStep(save, id, step) - cancel() - if persistErr != nil { - finish("failed", "error", persistErr.Error()) + status, outcome, diagnostic, terminal, finishErr := r.finishStage(id, name, workspace, selected, state, step) + if finishErr != nil { + finish("failed", "error", finishErr.Error()) return } - if step.Status == "completed" { - values, err := copyValues(stage.Values(step.Output)) - if err != nil { - finish("failed", "error", err.Error()) - return - } - state.memory[key] = memoryValue{output: values, sequence: sequence} - } - r.notifyStep(id, name, workspace, selected.Notify, step) - state.input = stage.Values(step.Output) + // Advance the in-memory UI-surface evidence only after the step is + // persisted, so the skip guard agrees with what the store holds. + state.recordChanges(step.FileChanges, step.Artifacts) if useAgent || errors.Is(err, stage.ErrStageCleanup) { sessions, checkErr := r.store.ActiveAgentSessionsForRun(context.Background(), id) if checkErr != nil || len(sessions) > 0 { @@ -743,7 +843,7 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na finish("canceled", "", ctx.Err().Error()) return } - if status, outcome, diagnostic, terminal := terminalFinish(step.Target, step.Stage, step.Outcome, step.Diagnostic); terminal { + if terminal { finish(status, outcome, diagnostic) return } diff --git a/internal/server/ui_skip_test.go b/internal/server/ui_skip_test.go new file mode 100644 index 00000000..2658707b --- /dev/null +++ b/internal/server/ui_skip_test.go @@ -0,0 +1,280 @@ +package server + +import ( + "context" + "os" + "path/filepath" + "strings" + "sync" + "testing" + + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" +) + +// uiReviewerSource builds a two-stage implement -> ui_reviewer pipeline. When +// withSkip is set, ui_reviewer declares an `approved` and a `skipped` route to +// success; otherwise it only declares the template's `success` route, proving a +// skip is never invented for a stage without that route. +func uiReviewerSource(withSkip bool) string { + source := pipeline.Template([]string{"implement", "ui_reviewer"}, true) + if withSkip { + source = strings.Replace(source, "success -> #success", "approved -> #success\nskipped -> #success", 1) + } + return source +} + +// runUISkip submits source, runs it once with an execute stub that records every +// visited stage key and writes the file named for that stage into the workspace, +// then returns the persisted detail, the visited keys and the number of verdict +// (model) calls the runner made. +func runUISkip(t *testing.T, source string, files map[string]string) (*protocol.RunDetail, []string, int) { + t.Helper() + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + store, err := pipeline.Open(filepath.Join(t.TempDir(), "ui.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "ui", source); err != nil { + t.Fatal(err) + } + items, err := store.List(ctx) + if err != nil || len(items) != 1 { + t.Fatalf("submit/list: %+v %v", items, err) + } + r, err := newRunner(ctx, store) + if err != nil { + t.Fatal(err) + } + defer r.wg.Wait() + dir := t.TempDir() + var mu sync.Mutex + var visited []string + verdictCalls := 0 + r.verdict = func(context.Context, map[string]any) string { + mu.Lock() + verdictCalls++ + mu.Unlock() + return "stub verdict" + } + r.execute = func(_ context.Context, def stage.Definition, _ stage.Values) (stage.Result, error) { + mu.Lock() + visited = append(visited, def.Key) + mu.Unlock() + if name := files[def.Key]; name != "" { + full := filepath.Join(dir, filepath.FromSlash(name)) + if err := os.MkdirAll(filepath.Dir(full), 0o700); err != nil { + return stage.Result{}, err + } + if err := os.WriteFile(full, []byte(def.Key+"\n"), 0o600); err != nil { + return stage.Result{}, err + } + } + outcome := "success" + if def.Key == "ui_reviewer" { + if _, ok := def.Edges["approved"]; ok { + outcome = "approved" + } + } + return stage.Result{Outcome: outcome, Output: stage.Values{"summary": def.Key + " done"}}, nil + } + run, err := r.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: "ui-skip", Workspace: dir, Input: map[string]any{"prompt": "task"}}) + if err != nil { + t.Fatal(err) + } + r.wg.Wait() + detail, err := store.GetRun(ctx, run.ID) + if err != nil { + t.Fatal(err) + } + mu.Lock() + got := append([]string(nil), visited...) + calls := verdictCalls + mu.Unlock() + return detail, got, calls +} + +func executed(visited []string, key string) bool { + for _, visitedKey := range visited { + if visitedKey == key { + return true + } + } + return false +} + +// TestUISkipShortCircuitsWhenNoSurfaceChanged proves a non-UI change skips the +// ui_reviewer stage with no model call and routes along its declared skip edge. +func TestUISkipShortCircuitsWhenNoSurfaceChanged(t *testing.T) { + detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(true), map[string]string{"implement": "internal/server/fake.go"}) + if executed(visited, "ui_reviewer") { + t.Fatalf("ui_reviewer executed a model call; visited=%v", visited) + } + if verdictCalls != 1 { + t.Fatalf("verdict (model) calls = %d, want only implement's 1", verdictCalls) + } + if detail.Status != "succeeded" { + t.Fatalf("run status = %q, want succeeded: %+v", detail.Status, detail.RunSummary) + } + if len(detail.Steps) != 2 { + t.Fatalf("steps = %d, want 2: %+v", len(detail.Steps), detail.Steps) + } + step := detail.Steps[1] + if step.Stage != "ui_reviewer" || step.Status != "completed" || step.Outcome != "skipped" || step.Target != protocol.SuccessEnd { + t.Fatalf("skip step wrong: %+v", step) + } + if step.FileChanges != nil && len(step.FileChanges.Files) != 0 { + t.Fatalf("skip step recorded file changes: %+v", step.FileChanges) + } + reason, _ := step.Output["summary"].(string) + if !strings.Contains(reason, "internal/server/fake.go") { + t.Fatalf("skip reason does not name the checked path: %q", reason) + } +} + +// TestUISkipZeroChangesStillSkips proves the guard also short-circuits when the +// run recorded no file changes at all, with a reason that says so. +func TestUISkipZeroChangesStillSkips(t *testing.T) { + detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(true), nil) + if executed(visited, "ui_reviewer") { + t.Fatalf("ui_reviewer executed with no recorded changes; visited=%v", visited) + } + if verdictCalls != 1 { + t.Fatalf("verdict (model) calls = %d, want only implement's 1", verdictCalls) + } + if detail.Status != "succeeded" || len(detail.Steps) != 2 { + t.Fatalf("run = %q steps=%d, want succeeded/2", detail.Status, len(detail.Steps)) + } + step := detail.Steps[1] + if step.Outcome != "skipped" { + t.Fatalf("step outcome = %q, want skipped: %+v", step.Outcome, step) + } + reason, _ := step.Output["summary"].(string) + if !strings.Contains(reason, "no recorded file changes") { + t.Fatalf("zero-change reason does not state that: %q", reason) + } +} + +// TestUISkipRunsStageOnSurfaceChange proves a run that touched a UI surface +// still executes the stage and routes through its normal outcome. +func TestUISkipRunsStageOnSurfaceChange(t *testing.T) { + cases := map[string]string{ + "android": "android/app/src/main/kotlin/Main.kt", + "internal tui": "internal/tui/view.go", + "presentation": "web/app.tsx", + } + for name, path := range cases { + t.Run(name, func(t *testing.T) { + detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(true), map[string]string{"implement": path}) + if !executed(visited, "ui_reviewer") { + t.Fatalf("ui_reviewer did not execute on %s; visited=%v", path, visited) + } + if verdictCalls != 2 { + t.Fatalf("verdict (model) calls = %d, want 2 for both executed stages", verdictCalls) + } + if detail.Status != "succeeded" { + t.Fatalf("run status = %q, want succeeded: %+v", detail.Status, detail.RunSummary) + } + step := detail.Steps[len(detail.Steps)-1] + if step.Stage != "ui_reviewer" || step.Outcome != "approved" || step.Target != protocol.SuccessEnd { + t.Fatalf("executed step did not route through approved: %+v", step) + } + }) + } +} + +// TestUISkipNeedsDeclaredEdge proves the guard never invents a skip for a stage +// whose definition declares no `skipped` route: it always executes. +func TestUISkipNeedsDeclaredEdge(t *testing.T) { + detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(false), map[string]string{"implement": "internal/server/fake.go"}) + if !executed(visited, "ui_reviewer") { + t.Fatalf("ui_reviewer without a skipped edge did not execute; visited=%v", visited) + } + if verdictCalls != 2 { + t.Fatalf("verdict (model) calls = %d, want 2 for both executed stages", verdictCalls) + } + if detail.Status != "succeeded" || len(detail.Steps) != 2 { + t.Fatalf("run = %q steps=%d, want succeeded/2", detail.Status, len(detail.Steps)) + } + step := detail.Steps[1] + if step.Stage != "ui_reviewer" || step.Outcome != "success" { + t.Fatalf("edge-less stage step wrong: %+v", step) + } +} + +func TestUISurfacePathClassification(t *testing.T) { + cases := []struct { + path string + want bool + }{ + {"android/app/src/main/kotlin/Main.kt", true}, + {"android/README.md", true}, + {"internal/tui/view.go", true}, + {"internal/tui", true}, + {"web/index.html", true}, + {"web/app.css", true}, + {"web/app.js", true}, + {"web/app.ts", true}, + {"web/app.jsx", true}, + {"web/app.tsx", true}, + {"web/Index.HTML", true}, + {"internal/server/fake.go", false}, + {"androidx/foo.go", false}, + {"cmd/pipelines/main.go", false}, + {"docs/readme.md", false}, + {"README.md", false}, + } + for _, tc := range cases { + if got := uiSurfacePath(tc.path); got != tc.want { + t.Errorf("uiSurfacePath(%q) = %v, want %v", tc.path, got, tc.want) + } + } +} + +func TestUISurfaceArtifactClassification(t *testing.T) { + cases := []struct { + name string + a protocol.StageArtifact + want bool + }{ + {"image content type", protocol.StageArtifact{Name: "shot.bin", ContentType: "image/png"}, true}, + {"image extension only", protocol.StageArtifact{Name: "shot.webp"}, true}, + {"non-image artifact", protocol.StageArtifact{Name: "report.pdf", ContentType: "application/pdf"}, false}, + {"binary artifact", protocol.StageArtifact{Name: "data.bin", ContentType: "application/octet-stream"}, false}, + {"no type no image extension", protocol.StageArtifact{Name: "notes.txt"}, false}, + } + for _, tc := range cases { + if got := uiSurfaceArtifact(tc.a); got != tc.want { + t.Errorf("%s: uiSurfaceArtifact(%+v) = %v, want %v", tc.name, tc.a, got, tc.want) + } + } +} + +// TestUISurfaceRecordChanges proves the accumulator latches a UI surface from an +// image artifact but not from a non-image one, and retains only a bounded sample. +func TestUISurfaceRecordChanges(t *testing.T) { + image := &runState{} + image.recordChanges(&protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "internal/server/fake.go"}}}, []protocol.StageArtifact{{Name: "shot.png", ContentType: "image/png"}}) + if !image.uiSurface { + t.Fatal("an image artifact did not mark a UI surface") + } + + plain := &runState{} + plain.recordChanges(&protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "internal/server/fake.go"}}}, []protocol.StageArtifact{{Name: "report.pdf", ContentType: "application/pdf"}}) + if plain.uiSurface { + t.Fatal("a non-image artifact marked a UI surface") + } + + bounded := &runState{} + files := make([]protocol.FileChange, maxRetainedChangedPaths+5) + for i := range files { + files[i] = protocol.FileChange{Path: "f"} + } + bounded.recordChanges(&protocol.StageFileChanges{Files: files}, nil) + if len(bounded.changedPaths) != maxRetainedChangedPaths || bounded.changedCount != len(files) { + t.Fatalf("bounded accumulator = %d paths / count %d, want %d / %d", len(bounded.changedPaths), bounded.changedCount, maxRetainedChangedPaths, len(files)) + } +} diff --git a/internal/server/ui_surface.go b/internal/server/ui_surface.go new file mode 100644 index 00000000..3cd7a0c9 --- /dev/null +++ b/internal/server/ui_surface.go @@ -0,0 +1,119 @@ +package server + +import ( + "fmt" + "path" + "path/filepath" + "strings" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// UI-surface classification is the single source of truth for the deterministic +// pre-check that lets a stage declaring a `skipped` route short-circuit when the +// run changed no rendered surface. The path/extension lists live only here; the +// skip guard, its reason and the resumed-run seed all read them. + +// maxRetainedChangedPaths bounds how many recorded changed paths a runState +// retains for the skip reason. The full count is kept separately, so the reason +// stays informative without unbounded memory. +const maxRetainedChangedPaths = 32 + +// uiSurfaceDirs are the workspace prefixes whose changes are a user-facing +// surface. Matching is on a path boundary, so "androidx/" is not "android/". +var uiSurfaceDirs = []string{"android", "internal/tui"} + +// presentationExtensions are the rendered presentation file types a change can +// touch without living under a surface directory. +var presentationExtensions = map[string]bool{ + ".html": true, + ".css": true, + ".js": true, + ".ts": true, + ".jsx": true, + ".tsx": true, +} + +// renderedArtifactExtensions are the image types a captured artifact may carry +// when its content type was not recorded or sniffed as an image. +var renderedArtifactExtensions = map[string]bool{ + ".png": true, + ".jpg": true, + ".jpeg": true, + ".gif": true, + ".webp": true, +} + +// uiSurfacePath reports whether a run-relative, forward-slash workspace path +// changed a user-facing surface: a file under android/ or internal/tui/, or a +// file with a presentation extension. It is O(len(path)) with no I/O. +func uiSurfacePath(p string) bool { + clean := strings.TrimPrefix(path.Clean(filepath.ToSlash(p)), "/") + if clean == "" || clean == "." { + return false + } + for _, dir := range uiSurfaceDirs { + if clean == dir || strings.HasPrefix(clean, dir+"/") { + return true + } + } + return presentationExtensions[strings.ToLower(path.Ext(clean))] +} + +// uiSurfaceArtifact reports whether a captured artifact is a rendered surface: +// an image content type, or an image file extension when no type was recorded. +func uiSurfaceArtifact(a protocol.StageArtifact) bool { + if strings.HasPrefix(strings.ToLower(a.ContentType), "image/") { + return true + } + return renderedArtifactExtensions[strings.ToLower(path.Ext(a.Name))] +} + +// recordChanges folds one completed step's observed changes into the run's +// UI-surface decision. It retains a bounded sample of paths; the count is +// unbounded so the reason can state the true total. It is O(changes) with no I/O. +func (s *runState) recordChanges(changes *protocol.StageFileChanges, artifacts []protocol.StageArtifact) { + if changes != nil { + for _, file := range changes.Files { + s.changedCount++ + if len(s.changedPaths) < maxRetainedChangedPaths { + s.changedPaths = append(s.changedPaths, file.Path) + } + if !s.uiSurface && uiSurfacePath(file.Path) { + s.uiSurface = true + } + // The full captured set is a separate, unbounded dedupe of the actual + // evidence, unlike the bounded changedPaths sample above. + if file.Path == "" || s.capturedSeen[file.Path] { + continue + } + if s.capturedSeen == nil { + s.capturedSeen = map[string]bool{} + } + s.capturedSeen[file.Path] = true + s.capturedPaths = append(s.capturedPaths, file.Path) + } + } + for _, artifact := range artifacts { + if !s.uiSurface && uiSurfaceArtifact(artifact) { + s.uiSurface = true + } + } +} + +// skipReasonLine states, as one bounded line, why the guard skipped a stage: no +// recorded change touched a UI surface. It names the retained checked paths. +func skipReasonLine(state *runState) string { + if state.changedCount == 0 { + return "no UI surface changed (no recorded file changes)" + } + line := fmt.Sprintf("no UI surface changed in %d recorded file change(s): %s", state.changedCount, strings.Join(state.changedPaths, ", ")) + if extra := state.changedCount - len(state.changedPaths); extra > 0 { + line = fmt.Sprintf("%s (+%d more)", line, extra) + } + runes := []rune(line) + if len(runes) > protocol.VerdictReasonCap { + return string(runes[:protocol.VerdictReasonCap]) + } + return line +}