Add background step syntax to workflow parser and language service

Co-authored-by: Copilot <copilot@github.com>

Author: lokesh755

expressions/src/features.test.ts

@@ -57,7 +57,8 @@ describe("FeatureFlags", () => {
         "blockScalarChompingWarning",
         "allowCaseFunction",
         "allowCopilotRequestsPermission",
-        "allowConcurrencyQueue"
+        "allowConcurrencyQueue",
+        "allowBackgroundSteps"
       ]);
     });
   });

expressions/src/features.ts

@@ -46,6 +46,12 @@ export interface ExperimentalFeatures {
    * @default false
    */
   allowConcurrencyQueue?: boolean;
+
+  /**
+   * Enable background workflow steps and related wait/cancel steps.
+   * @default false
+   */
+  allowBackgroundSteps?: boolean;
 }
 
 /**
@@ -62,7 +68,8 @@ const allFeatureKeys: ExperimentalFeatureKey[] = [
   "blockScalarChompingWarning",
   "allowCaseFunction",
   "allowCopilotRequestsPermission",
-  "allowConcurrencyQueue"
+  "allowConcurrencyQueue",
+  "allowBackgroundSteps"
 ];
 
 export class FeatureFlags {

languageserver/README.md

@@ -128,6 +128,7 @@ initializationOptions: {
 | `missingInputsQuickfix` | Code action to add missing required inputs for actions |
 | `blockScalarChompingWarning` | Warn when block scalars (`\|` or `>`) use implicit clip chomping, which adds a trailing newline that may be unintentional |
 | `allowConcurrencyQueue` | Enable the `concurrency.queue` workflow property |
+| `allowBackgroundSteps` | Enable background workflow steps and related wait/cancel steps |
 
 Individual feature flags take precedence over `all`. For example, `{ all: true, missingInputsQuickfix: false }` enables all experimental features except `missingInputsQuickfix`.
 

languageserver/src/connection.ts

@@ -168,7 +168,8 @@ export function initConnection(connection: Connection) {
         contextProviderConfig: repoContext && contextProviders(client, repoContext, cache),
         fileProvider: getFileProvider(client, cache, repoContext?.workspaceUri, async path => {
           return await connection.sendRequest(Requests.ReadFile, {path});
-        })
+        }),
+        featureFlags
       });
     });
   });

languageservice/src/complete.test.ts

@@ -305,27 +305,43 @@ jobs:
     - run: echo
     - |`;
     const result = await complete(...getPositionFromCursor(input));
-    expect(result).toHaveLength(11);
-    expect(result.map(x => x.label)).toEqual([
-      "continue-on-error",
-      "env",
-      "id",
-      "if",
-      "name",
-      "run",
-      "shell",
-      "timeout-minutes",
-      "uses",
-      "with",
-      "working-directory"
-    ]);
+    expect(result.map(x => x.label)).toEqual(
+      expect.arrayContaining([
+        "continue-on-error",
+        "env",
+        "id",
+        "if",
+        "name",
+        "run",
+        "shell",
+        "timeout-minutes",
+        "uses",
+        "with",
+        "working-directory"
+      ])
+    );
+    expect(result.map(x => x.label)).toEqual(expect.not.arrayContaining(["background", "cancel", "wait", "wait-all"]));
 
     // Includes detail when available. Using continue-on-error as a sample here.
     expect(result.map(x => (x.documentation as MarkupContent)?.value)).toContain(
       "Prevents a job from failing when a step fails. Set to `true` to allow a job to pass when this step fails."
     );
   });
 
+  it("empty step includes background step keys when enabled", async () => {
+    const input = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - run: echo
+    - |`;
+    const result = await complete(...getPositionFromCursor(input), {
+      featureFlags: new FeatureFlags({allowBackgroundSteps: true})
+    });
+    expect(result.map(x => x.label)).toEqual(expect.arrayContaining(["background", "cancel", "wait", "wait-all"]));
+  });
+
   it("loose mapping keys have no completion suggestions", async () => {
     const input = `
 on:

languageservice/src/complete.ts

@@ -42,6 +42,8 @@ import {Value, ValueProviderConfig} from "./value-providers/config.js";
 import {defaultValueProviders} from "./value-providers/default.js";
 import {DefinitionValueMode, definitionValues, TokenStructure} from "./value-providers/definition.js";
 
+const backgroundStepCompletionLabels = new Set(["background", "wait", "wait-all", "cancel"]);
+
 export function getExpressionInput(input: string, pos: number): string {
   // Find start marker around the cursor position
   let startPos = input.lastIndexOf(OPEN_EXPRESSION, pos);
@@ -88,7 +90,7 @@ export async function complete(
   // Parse the document
   const parsedTemplate = isAction
     ? getOrParseAction(file, textDocument.uri, true)
-    : getOrParseWorkflow(file, textDocument.uri, true);
+    : getOrParseWorkflow(file, textDocument.uri, true, config?.featureFlags);
   if (!parsedTemplate.value) {
     return [];
   }
@@ -172,6 +174,10 @@ export async function complete(
     values = values.filter(v => v.label !== "copilot-requests");
   }
 
+  if (!isAction && !config?.featureFlags?.isEnabled("allowBackgroundSteps")) {
+    values = values.filter(v => !backgroundStepCompletionLabels.has(v.label));
+  }
+
   // Offer "(switch to list)" / "(switch to mapping)" when the schema allows alternative forms
   const escapeHatches = getEscapeHatchCompletions(token, keyToken, indentString, newPos, schema);
   values.push(...escapeHatches);

languageservice/src/context-providers/env.ts

@@ -7,7 +7,7 @@ export function getEnvContext(workflowContext: WorkflowContext): DescriptionDict
   const d = new DescriptionDictionary();
 
   //step env
-  if (workflowContext.step?.env) {
+  if (workflowContext.step && "env" in workflowContext.step && workflowContext.step.env) {
     envContext(workflowContext.step.env, d);
   }
 

languageservice/src/context/workflow-context.ts

@@ -67,7 +67,10 @@ export function getWorkflowContext(
         break;
       }
       case "regular-step":
-      case "run-step": {
+      case "run-step":
+      case "wait-step":
+      case "wait-all-step":
+      case "cancel-step": {
         if (isMapping(token)) {
           stepToken = token;
         }

languageservice/src/hover.test.ts

@@ -1,3 +1,4 @@
+import {FeatureFlags} from "@actions/expressions";
 import {isString} from "@actions/workflow-parser";
 import {DescriptionProvider, hover, HoverConfig} from "./hover.js";
 import {getPositionFromCursor} from "./test-utils/cursor-position.js";
@@ -203,3 +204,79 @@ jobs:
     );
   });
 });
+
+describe("hover for background step keywords", () => {
+  const bgConfig: HoverConfig = {featureFlags: new FeatureFlags({allowBackgroundSteps: true})};
+
+  it("on background key", async () => {
+    const input = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: server
+        run: echo hi
+        ba|ckground: true`;
+    const result = await hover(...getPositionFromCursor(input), bgConfig);
+    expect(result).not.toBeNull();
+    expect(result?.contents).toContain("runs this step in the background");
+  });
+
+  it("on wait key", async () => {
+    const input = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: server
+        run: echo hi
+        background: true
+      - wa|it: server`;
+    const result = await hover(...getPositionFromCursor(input), bgConfig);
+    expect(result).not.toBeNull();
+    expect(result?.contents).toContain("background steps to wait for");
+  });
+
+  it("on wait-all key", async () => {
+    const input = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: server
+        run: echo hi
+        background: true
+      - wa|it-all:`;
+    const result = await hover(...getPositionFromCursor(input), bgConfig);
+    expect(result).not.toBeNull();
+    expect(result?.contents).toContain("Wait for all prior background steps");
+  });
+
+  it("on cancel key", async () => {
+    const input = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: server
+        run: echo hi
+        background: true
+      - ca|ncel: server`;
+    const result = await hover(...getPositionFromCursor(input), bgConfig);
+    expect(result).not.toBeNull();
+    expect(result?.contents).toContain("background step to cancel");
+  });
+
+  it("no hover for background keywords when feature flag is off", async () => {
+    const input = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: server
+        run: echo hi
+        ba|ckground: true`;
+    const result = await hover(...getPositionFromCursor(input));
+    expect(result).toBeNull();
+  });
+});

languageservice/src/hover.ts

@@ -1,4 +1,4 @@
-import {data, DescriptionDictionary, Parser} from "@actions/expressions";
+import {data, DescriptionDictionary, FeatureFlags, Parser} from "@actions/expressions";
 import {FunctionDefinition, FunctionInfo} from "@actions/expressions/funcs/info";
 import {Lexer} from "@actions/expressions/lexer";
 import {parseAction} from "@actions/workflow-parser/actions/action-parser";
@@ -35,6 +35,7 @@ export type HoverConfig = {
   descriptionProvider?: DescriptionProvider;
   contextProviderConfig?: ContextProviderConfig;
   fileProvider?: FileProvider;
+  featureFlags?: FeatureFlags;
 };
 
 export type DescriptionProvider = {
@@ -58,7 +59,9 @@ export async function hover(document: TextDocument, position: Position, config?:
   const isAction = isActionDocument(document.uri);
 
   // Parse document
-  const parsedTemplate = isAction ? parseAction(file, nullTrace) : getOrParseWorkflow(file, document.uri);
+  const parsedTemplate = isAction
+    ? parseAction(file, nullTrace)
+    : getOrParseWorkflow(file, document.uri, false, config?.featureFlags);
   if (!parsedTemplate?.value) {
     return null;
   }