[PIPE-5387] add "terminal" shorthand for upstream job requires array

Adds the ability to use "terminal" in place of [success, failure,
canceled, not_run] when specifying the upstream job requirements.

Also adds a small hint to users that they can do this, with a code
action to do it for them.

Author: parkuman

pkg/ast/workflow.go

@@ -52,9 +52,10 @@ type JobRef struct {
 }
 
 type Require struct {
-	Name   string
-	Status []string
-	Range  protocol.Range
+	Name        string
+	Status      []string
+	Range       protocol.Range
+	StatusRange protocol.Range
 }
 
 type WorkflowTrigger struct {

pkg/parser/validate/workflow.go

@@ -9,6 +9,8 @@ import (
 	"github.com/CircleCI-Public/circleci-yaml-language-server/pkg/utils"
 )
 
+var TerminalJobStatuses = []string{"success", "failed", "canceled", "not_run"}
+
 func (val Validate) ValidateWorkflows() {
 	for _, workflow := range val.Doc.Workflows {
 		val.validateSingleWorkflow(workflow)
@@ -56,6 +58,47 @@ func (val Validate) validateSingleWorkflow(workflow ast.Workflow) error {
 					require.Range,
 					fmt.Sprintf("Cannot find declaration for job reference %s", require.Name)))
 			}
+
+			if requireHasAllTerminalStatuses(require.Status) {
+				// Use " terminal" for multi-line arrays so there's a space after the colon.
+				// "terminal" for inline arrays since we're replacing an array that is
+				// already spaced after the colon. e.g.
+				//
+				// Inline:
+				// Before: - job_name: [inline-array]
+				// After:  - job_name: terminal
+				//
+				// Vs multi-line:
+				// Before:
+				// - job_name:
+				//   - success
+				//
+				// After:
+				// - job_name: terminal
+				newText := "terminal"
+				if require.StatusRange.Start.Line != require.StatusRange.End.Line {
+					newText = " terminal"
+				}
+				codeAction := utils.CreateCodeActionTextEdit(
+					"Simplify these statuses to 'terminal'",
+					val.Doc.URI,
+					[]protocol.TextEdit{
+						{
+							NewText: newText,
+							Range:   require.StatusRange,
+						},
+					},
+					true, // preferred
+				)
+				val.addDiagnostic(
+					protocol.Diagnostic{
+						Range:    require.StatusRange,
+						Message:  fmt.Sprintf("Statuses: '%v' can be simplified to just 'terminal'", require.Status),
+						Severity: protocol.DiagnosticSeverityHint,
+						Data:     []protocol.CodeAction{codeAction},
+					},
+				)
+			}
 		}
 
 		if cachedFile := val.Cache.FileCache.GetFile(val.Doc.URI); val.Context.Api.Token != "" &&
@@ -142,3 +185,30 @@ func (val Validate) validateDAG(workflow ast.Workflow) {
 		}
 	}
 }
+
+func requireHasAllTerminalStatuses(statuses []string) bool {
+	if len(statuses) != len(TerminalJobStatuses) {
+		return false
+	}
+
+	terminalSet := make(map[string]bool)
+	for _, status := range TerminalJobStatuses {
+		terminalSet[status] = false
+	}
+
+	for _, s := range statuses {
+		if _, ok := terminalSet[s]; ok {
+			terminalSet[s] = true
+		} else {
+			return false
+		}
+	}
+
+	for _, found := range terminalSet {
+		if !found {
+			return false
+		}
+	}
+
+	return true
+}

pkg/parser/validate/workflow_test.go

@@ -234,3 +234,279 @@ workflows:
 
 	CheckYamlErrors(t, testCases)
 }
+
+func TestTerminalJobStatusesHint(t *testing.T) {
+	testCases := []struct {
+		name            string
+		yamlContent     string
+		expectHint      bool
+		expectedNewText string
+		expectedRange   protocol.Range
+	}{
+		{
+			name: "All terminal statuses present - should show hint",
+			yamlContent: `version: 2.1
+
+jobs:
+  job1:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+  job2:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+
+workflows:
+  test-workflow:
+    jobs:
+      - job1
+      - job2:
+          requires:
+            - job1: [success, failed, canceled, not_run]`,
+			expectHint:      true,
+			expectedNewText: "terminal",
+			expectedRange: protocol.Range{
+				Start: protocol.Position{Line: 20, Character: 20},
+				End:   protocol.Position{Line: 20, Character: 56},
+			},
+		},
+		{
+			name: "All terminal statuses as YAML list - should show hint",
+			yamlContent: `version: 2.1
+
+jobs:
+  job1:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+  job2:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+
+workflows:
+  test-workflow:
+    jobs:
+      - job1
+      - job2:
+          requires:
+            - job1:
+              - success
+              - failed
+              - canceled
+              - not_run`,
+			expectHint:      true,
+			expectedNewText: " terminal",
+			expectedRange: protocol.Range{
+				Start: protocol.Position{Line: 20, Character: 19},
+				End:   protocol.Position{Line: 24, Character: 23},
+			},
+		},
+		{
+			name: "All terminal statuses in different order - should show hint",
+			yamlContent: `version: 2.1
+
+jobs:
+  job1:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+  job2:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+
+workflows:
+  test-workflow:
+    jobs:
+      - job1
+      - job2:
+          requires:
+            - job1: [not_run, canceled, failed, success]`,
+			expectHint:      true,
+			expectedNewText: "terminal",
+			expectedRange: protocol.Range{
+				Start: protocol.Position{Line: 20, Character: 20},
+				End:   protocol.Position{Line: 20, Character: 56},
+			},
+		},
+		{
+			name: "Only some terminal statuses - no hint",
+			yamlContent: `version: 2.1
+
+jobs:
+  job1:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+  job2:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+
+workflows:
+  test-workflow:
+    jobs:
+      - job1
+      - job2:
+          requires:
+            - job1: [success, failed]`,
+			expectHint: false,
+		},
+		{
+			name: "Mix of terminal and non-terminal statuses - no hint",
+			yamlContent: `version: 2.1
+
+jobs:
+  job1:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+  job2:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+
+workflows:
+  test-workflow:
+    jobs:
+      - job1
+      - job2:
+          requires:
+            - job1: [success, failed, canceled, not_run, unknown]`,
+			expectHint: false,
+		},
+		{
+			name: "All terminal statuses with anchor - should show hint",
+			yamlContent: `version: 2.1
+
+jobs:
+  job1:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+  job2:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - run: echo "test"
+
+workflows:
+  test-workflow:
+    jobs:
+      - job1
+      - job2:
+          requires:
+            - job1: &terminal-statuses [success, failed, canceled, not_run]`,
+			expectHint:      true,
+			expectedNewText: "terminal",
+			expectedRange: protocol.Range{
+				Start: protocol.Position{Line: 20, Character: 39},
+				End:   protocol.Position{Line: 20, Character: 75},
+			},
+		},
+	}
+
+	for _, tt := range testCases {
+		t.Run(tt.name, func(t *testing.T) {
+			val := CreateValidateFromYAML(tt.yamlContent)
+			val.Validate()
+
+			diags := *val.Diagnostics
+
+			// Filter for only Hint severity diagnostics
+			hintDiags := []protocol.Diagnostic{}
+			for _, d := range diags {
+				if d.Severity == protocol.DiagnosticSeverityHint {
+					hintDiags = append(hintDiags, d)
+				}
+			}
+
+			if !tt.expectHint {
+				if len(hintDiags) != 0 {
+					t.Errorf("Expected no hint diagnostics, got %d", len(hintDiags))
+				}
+				return
+			}
+
+			if len(hintDiags) != 1 {
+				t.Fatalf("Expected 1 hint diagnostic, got %d", len(hintDiags))
+			}
+
+			diag := hintDiags[0]
+			if diag.Severity != protocol.DiagnosticSeverityHint {
+				t.Errorf("Expected Hint severity, got %v", diag.Severity)
+			}
+
+			if diag.Data == nil {
+				t.Fatal("Expected diagnostic to have code actions")
+			}
+
+			codeActions, ok := diag.Data.([]protocol.CodeAction)
+			if !ok {
+				t.Fatalf("Expected Data to be []protocol.CodeAction, got %T", diag.Data)
+			}
+
+			if len(codeActions) == 0 {
+				t.Fatal("Expected at least one code action")
+			}
+
+			// Find the terminal simplification code action
+			var terminalAction *protocol.CodeAction
+			for i := range codeActions {
+				if codeActions[i].Title == "Simplify these statuses to 'terminal'" {
+					terminalAction = &codeActions[i]
+					break
+				}
+			}
+
+			if terminalAction == nil {
+				t.Fatal("Expected 'Simplify these statuses to 'terminal'' code action")
+			}
+
+			if terminalAction.Kind != "quickfix" {
+				t.Errorf("Expected kind 'quickfix', got %s", terminalAction.Kind)
+			}
+
+			if !terminalAction.IsPreferred {
+				t.Error("Expected IsPreferred to be true")
+			}
+
+			if terminalAction.Edit == nil {
+				t.Fatal("Expected Edit to be non-nil")
+			}
+
+			changes := terminalAction.Edit.Changes
+			if len(changes) != 1 {
+				t.Fatalf("Expected 1 change, got %d", len(changes))
+			}
+
+			for _, edits := range changes {
+				if len(edits) != 1 {
+					t.Fatalf("Expected 1 text edit, got %d", len(edits))
+				}
+
+				edit := edits[0]
+				if edit.NewText != tt.expectedNewText {
+					t.Errorf("Expected NewText %q, got %q", tt.expectedNewText, edit.NewText)
+				}
+
+				if edit.Range != tt.expectedRange {
+					t.Errorf("Expected Range %v, got %v", tt.expectedRange, edit.Range)
+				}
+			}
+		})
+	}
+}