feat(extension): add metadata to Poll method and reorder BuildAction enum

Enhance BuildManager.Poll to return build metadata and reorder BuildAction
constants for better semantic ordering.

Changes to Poll method:
- Add map[string]string return value for build metadata
- Document common metadata keys (build_url, commit_sha, duration_ms, etc.)
- Update interface signature: Poll(ctx, id) → (BuildStatus, map[string]string, error)
- Update mocks and tests to handle metadata return value

Changes to BuildAction enum:
- Reorder constants: BuildActionApply now comes before BuildActionValidate
- Apply is the primary action, validate is secondary
- Update all tests and examples to reflect new ordering

Documentation updates:
- Add Build Metadata section explaining common keys
- Update all Poll usage examples to show metadata handling
- Update mock examples with metadata assertions
- Clarify that metadata keys are implementation-defined

The metadata map allows implementations to return provider-specific information
(build URLs, commit SHAs, timestamps, etc.) without changing the interface.

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

Author: djuloori27

entity/build.go

@@ -60,10 +60,10 @@ type BuildAction string
 const (
 	// BuildActionUnknown is the sentinel value for uninitialized actions.
 	BuildActionUnknown BuildAction = ""
-	// BuildActionValidate runs validation/testing on the change without applying it.
-	BuildActionValidate BuildAction = "validate"
 	// BuildActionApply applies the change to the target branch.
 	BuildActionApply BuildAction = "apply"
+	// BuildActionValidate runs validation/testing on the change without applying it.
+	BuildActionValidate BuildAction = "validate"
 )
 
 // BuildChange represents a code change to be processed by the build system.

entity/build_test.go

@@ -53,15 +53,6 @@ func TestBuildChange_Creation(t *testing.T) {
 		wantID   string
 		wantAction BuildAction
 	}{
-		{
-			name: "validate action",
-			change: BuildChange{
-				ChangeID: "D12345",
-				Action:   BuildActionValidate,
-			},
-			wantID:   "D12345",
-			wantAction: BuildActionValidate,
-		},
 		{
 			name: "apply action",
 			change: BuildChange{
@@ -71,6 +62,15 @@ func TestBuildChange_Creation(t *testing.T) {
 			wantID:   "PR-42",
 			wantAction: BuildActionApply,
 		},
+		{
+			name: "validate action",
+			change: BuildChange{
+				ChangeID: "D12345",
+				Action:   BuildActionValidate,
+			},
+			wantID:   "D12345",
+			wantAction: BuildActionValidate,
+		},
 		{
 			name: "unknown action",
 			change: BuildChange{

extension/build/README.md

@@ -22,7 +22,7 @@ type BuildManager interface {
     ) (string, error)
 
     // Poll retrieves the current status of a build from the CI provider
-    Poll(ctx context.Context, id string) (entity.BuildStatus, error)
+    Poll(ctx context.Context, id string) (entity.BuildStatus, map[string]string, error)
 
     // CancelBuild requests cancellation of a build (asynchronous operation)
     CancelBuild(ctx context.Context, id string) error
@@ -60,8 +60,8 @@ type BuildAction string
 
 const (
     BuildActionUnknown   BuildAction = ""         // Sentinel value
-    BuildActionValidate  BuildAction = "validate" // Run validation/testing without applying
     BuildActionApply     BuildAction = "apply"    // Apply the change to the target branch
+    BuildActionValidate  BuildAction = "validate" // Run validation/testing without applying
 )
 ```
 
@@ -105,6 +105,20 @@ func (s BuildStatus) IsTerminal() bool
 
 **Build Lifecycle**: `accepted` → `passed`/`failed`/`cancelled`
 
+### Build Metadata
+
+The `Poll` method returns a `map[string]string` containing additional metadata about the build. The specific keys and values are implementation-defined, but common examples include:
+
+**Common metadata keys:**
+- `build_url` - Direct link to the build in the CI provider's UI
+- `commit_sha` - Git commit SHA being tested
+- `duration_ms` - Build duration in milliseconds
+- `started_at` - Build start timestamp
+- `finished_at` - Build completion timestamp
+- `error_message` - Error details for failed builds
+
+Implementations may include additional provider-specific metadata. Consumers should handle missing keys gracefully.
+
 ## Error Handling
 
 The extension defines sentinel errors following the SubmitQueue pattern:
@@ -119,7 +133,7 @@ Each error has helper functions:
 
 Example:
 ```go
-status, err := buildMgr.Poll(ctx, buildID)
+status, metadata, err := buildMgr.Poll(ctx, buildID)
 if build.IsBuildNotFound(err) {
     // Handle missing build
 }
@@ -132,8 +146,8 @@ if build.IsBuildNotFound(err) {
 ```go
 // 1. Schedule a build with changes
 changes := []entity.BuildChange{
-    {ChangeID: "D12345", Action: entity.BuildActionValidate},
-    {ChangeID: "D12346", Action: entity.BuildActionApply},
+    {ChangeID: "D12345", Action: entity.BuildActionApply},
+    {ChangeID: "D12346", Action: entity.BuildActionValidate},
 }
 
 buildID, err := buildMgr.Schedule(ctx, "my-queue", changes)
@@ -142,11 +156,15 @@ if err != nil {
 }
 
 // 2. Poll for build status
-status, err := buildMgr.Poll(ctx, buildID)
+status, metadata, err := buildMgr.Poll(ctx, buildID)
 if err != nil {
     // Handle error
 }
 
+// Access build metadata
+buildURL := metadata["build_url"]
+commitSHA := metadata["commit_sha"]
+
 // 3. Check if build is done
 if status.IsTerminal() {
     // Build finished: status is passed, failed, or cancelled
@@ -246,7 +264,7 @@ To add support for a new CI provider:
 
 5. **Implement Schedule method**:
    - Look up job name from queue config using `queueName` parameter
-   - Handle both `BuildActionValidate` and `BuildActionApply` actions
+   - Handle both `BuildActionApply` and `BuildActionValidate` actions
    - Create appropriate builds/jobs for each change
    - Return unique build ID
 

extension/build/build_manager.go

@@ -44,8 +44,9 @@ type BuildManager interface {
 	//
 	// Returns:
 	//   - BuildStatus: Current state of the build
+	//   - map[string]string: Additional metadata about the build (e.g., build URL, commit SHA, duration)
 	//   - error: ErrBuildNotFound if the build doesn't exist
-	Poll(ctx context.Context, id string) (entity.BuildStatus, error)
+	Poll(ctx context.Context, id string) (entity.BuildStatus, map[string]string, error)
 
 	// CancelBuild requests cancellation of a build.
 	//

extension/build/mock/build_manager.go

@@ -23,8 +23,8 @@ func TestMockBuildManager_Compilation(t *testing.T) {
 
 	queueName := "test-queue"
 	changes := []entity.BuildChange{
-		{ChangeID: "D12345", Action: entity.BuildActionValidate},
-		{ChangeID: "D12346", Action: entity.BuildActionApply},
+		{ChangeID: "D12345", Action: entity.BuildActionApply},
+		{ChangeID: "D12346", Action: entity.BuildActionValidate},
 	}
 
 	buildID, err := mockBuildMgr.Schedule(
@@ -39,15 +39,22 @@ func TestMockBuildManager_Compilation(t *testing.T) {
 	}
 
 	// Test Poll
+	expectedMetadata := map[string]string{
+		"build_url": "https://ci.example.com/builds/123",
+		"commit_sha": "abc123",
+	}
 	mockBuildMgr.EXPECT().
 		Poll(gomock.Any(), gomock.Any()).
-		Return(entity.BuildStatusPassed, nil)
+		Return(entity.BuildStatusPassed, expectedMetadata, nil)
 
-	status, err := mockBuildMgr.Poll(context.Background(), buildID)
+	status, metadata, err := mockBuildMgr.Poll(context.Background(), buildID)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	if status != entity.BuildStatusPassed {
 		t.Fatalf("expected %v, got %v", entity.BuildStatusPassed, status)
 	}
+	if metadata["build_url"] != expectedMetadata["build_url"] {
+		t.Fatalf("expected metadata %v, got %v", expectedMetadata, metadata)
+	}
 }