Merge pull request #298 from actions/release/0.3.36

Release version 0.3.36

.gitignore

@@ -4,6 +4,9 @@ lerna-debug.log
 node_modules
 .DS_Store
 
+# Nx cache (generated by Lerna/Nx)
+.nx/
+
 # Minified JSON (generated at build time)
 *.min.json
 

docs/esm-migration-plan.md

@@ -4,6 +4,27 @@
 
 This document outlines the plan to migrate from TypeScript's deprecated `"moduleResolution": "node"` (node10) to `"moduleResolution": "node16"` or `"nodenext"`. This change is necessary because the published ESM packages have extensionless imports that don't work correctly in modern ESM environments.
 
+## TL;DR - Remaining Work
+
+- [x] expressions - Migrated ✅
+- [x] workflow-parser - Migrated ✅
+- [x] languageservice - Migrated ✅
+- [x] languageserver - Add `.js` extensions to imports ✅
+- [ ] languageserver - Update `tsconfig.build.json` to `moduleResolution: "node16"` (blocked by vscode-languageserver)
+- [ ] languageserver - Upgrade `vscode-languageserver` to stable v10+ when released
+
+**Blocker:** `vscode-languageserver@8.0.2` lacks ESM exports. Stable v10 with `exports` field needed.
+
+### ⚠️ Important: `skipLibCheck: true` Required
+
+All migrated packages use `skipLibCheck: true` in their `tsconfig.build.json`. This works around a TS2386 "Overload signatures must all be optional or required" error in `@types/node/module.d.ts`.
+
+**Why can't we just fix the error?** The error is in `@types/node`, a third-party package maintained by DefinitelyTyped. We can't modify `node_modules`, and upstream fixes take time.
+
+**Is `skipLibCheck` safe?** Yes. It only skips type checking of `.d.ts` files (declaration files from dependencies). Our own `.ts` source files are still fully type-checked. This is a common and recommended workaround for issues in third-party type definitions.
+
+---
+
 ## Issues Fixed
 
 This migration will resolve the following issues:
@@ -199,14 +220,13 @@ src/connection.ts(1,43): error TS2307: Cannot find module 'vscode-languageserver
 
 With `moduleResolution: "node16"`, TypeScript follows Node.js ESM resolution rules which require explicit `exports` for subpath imports like `vscode-languageserver/browser` and `vscode-languageserver/node`.
 
-**Status:** Verified December 2025. Version 9.0.1 is available but ESM export support is not confirmed.
+**Status:** Partial - `.js` extensions added, waiting for stable `vscode-languageserver` release with ESM exports to complete migration.
 
-**Current Decision:** The languageserver package is **deferred** from this migration until the upstream `vscode-languageserver` package adds proper ESM exports. It will continue using the old `moduleResolution: "node"` configuration.
+**Completed:** All relative imports in languageserver source files have been updated to use `.js` extensions. This is compatible with the current `moduleResolution: "node"` and will enable a seamless migration once a stable vscode-languageserver version with ESM exports is available.
 
 **Options to resolve:**
-- Wait for vscode-languageserver to add ESM exports
-- Try upgrading to vscode-languageserver v9.x to see if exports were added
-- Use a bundler to work around the module resolution
+- Wait for stable vscode-languageserver v10+ with ESM exports
+- Use pre-release `vscode-languageserver@10.0.0-next.16` (has proper exports but is unstable)
 - Fork or patch the dependency
 
 ---
@@ -218,7 +238,7 @@ With `moduleResolution: "node16"`, TypeScript follows Node.js ESM resolution rul
 | expressions | 1068 | ✅ Migrated |
 | workflow-parser | 292 | ✅ Migrated |
 | languageservice | 452 | ✅ Migrated |
-| languageserver | 6 files | ⏸️ Deferred (vscode-languageserver lacks ESM exports) |
+| languageserver | 31 | 🔶 Partial (`.js` extensions added, awaiting stable vscode-languageserver) |
 
 ---
 

expressions/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actions/expressions",
-  "version": "0.3.30",
+  "version": "0.3.36",
   "license": "MIT",
   "type": "module",
   "source": "./src/index.ts",
@@ -36,7 +36,7 @@
     "clean": "rimraf dist",
     "format": "prettier --write '**/*.ts'",
     "format-check": "prettier --check '**/*.ts'",
-    "lint": "eslint 'src/**/*.ts'",
+    "lint": "eslint --max-warnings 0 'src/**/*.ts'",
     "lint-fix": "eslint --fix 'src/**/*.ts'",
     "prepublishOnly": "npm run build && npm run test",
     "test": "NODE_OPTIONS=\"--experimental-vm-modules\" jest",

expressions/src/completion.ts

@@ -2,6 +2,7 @@ import {DescriptionPair} from "./completion/descriptionDictionary.js";
 import {Dictionary, isDictionary} from "./data/dictionary.js";
 import {ExpressionData} from "./data/expressiondata.js";
 import {Evaluator} from "./evaluator.js";
+import {FeatureFlags} from "./features.js";
 import {wellKnownFunctions} from "./funcs.js";
 import {FunctionDefinition, FunctionInfo} from "./funcs/info.js";
 import {Lexer, Token, TokenType} from "./lexer.js";
@@ -26,13 +27,15 @@ export type CompletionItem = {
  * @param context Context available for the expression
  * @param extensionFunctions List of functions available
  * @param functions Optional map of functions to use during evaluation
+ * @param featureFlags Optional feature flags to control which features are enabled
  * @returns Array of completion items
  */
 export function complete(
   input: string,
   context: Dictionary,
   extensionFunctions: FunctionInfo[],
-  functions?: Map<string, FunctionDefinition>
+  functions?: Map<string, FunctionDefinition>,
+  featureFlags?: FeatureFlags
 ): CompletionItem[] {
   // Lex
   const lexer = new Lexer(input);
@@ -63,7 +66,7 @@ export function complete(
     const result = contextKeys(context);
 
     // Merge with functions
-    result.push(...functionItems(extensionFunctions));
+    result.push(...functionItems(extensionFunctions, featureFlags));
 
     return result;
   }
@@ -88,10 +91,15 @@ export function complete(
   return contextKeys(result);
 }
 
-function functionItems(extensionFunctions: FunctionInfo[]): CompletionItem[] {
+function functionItems(extensionFunctions: FunctionInfo[], featureFlags?: FeatureFlags): CompletionItem[] {
   const result: CompletionItem[] = [];
+  const flags = featureFlags ?? new FeatureFlags();
 
   for (const fdef of [...Object.values(wellKnownFunctions), ...extensionFunctions]) {
+    // Filter out case function if feature is disabled
+    if (fdef.name === "case" && !flags.isEnabled("allowCaseFunction")) {
+      continue;
+    }
     result.push({
       label: fdef.name,
       description: fdef.description,

expressions/src/errors.ts

@@ -12,6 +12,7 @@ export enum ErrorType {
   ErrorExceededMaxLength,
   ErrorTooFewParameters,
   ErrorTooManyParameters,
+  ErrorEvenParameters,
   ErrorUnrecognizedContext,
   ErrorUnrecognizedFunction
 }
@@ -42,6 +43,8 @@ function errorDescription(typ: ErrorType): string {
       return "Too few parameters supplied";
     case ErrorType.ErrorTooManyParameters:
       return "Too many parameters supplied";
+    case ErrorType.ErrorEvenParameters:
+      return "Even number of parameters supplied, requires an odd number of parameters";
     case ErrorType.ErrorUnrecognizedContext:
       return "Unrecognized named-value";
     case ErrorType.ErrorUnrecognizedFunction:

expressions/src/features.test.ts

@@ -0,0 +1,62 @@
+import {FeatureFlags} from "./features.js";
+
+describe("FeatureFlags", () => {
+  describe("isEnabled", () => {
+    it("returns false by default when no options provided", () => {
+      const flags = new FeatureFlags();
+      expect(flags.isEnabled("missingInputsQuickfix")).toBe(false);
+    });
+
+    it("returns false by default when empty options provided", () => {
+      const flags = new FeatureFlags({});
+      expect(flags.isEnabled("missingInputsQuickfix")).toBe(false);
+    });
+
+    it("returns true when feature is explicitly enabled", () => {
+      const flags = new FeatureFlags({missingInputsQuickfix: true});
+      expect(flags.isEnabled("missingInputsQuickfix")).toBe(true);
+    });
+
+    it("returns false when feature is explicitly disabled", () => {
+      const flags = new FeatureFlags({missingInputsQuickfix: false});
+      expect(flags.isEnabled("missingInputsQuickfix")).toBe(false);
+    });
+
+    it("returns true when all is enabled", () => {
+      const flags = new FeatureFlags({all: true});
+      expect(flags.isEnabled("missingInputsQuickfix")).toBe(true);
+    });
+
+    it("explicit feature flag takes precedence over all:true", () => {
+      const flags = new FeatureFlags({all: true, missingInputsQuickfix: false});
+      expect(flags.isEnabled("missingInputsQuickfix")).toBe(false);
+    });
+
+    it("explicit feature flag takes precedence over all:false", () => {
+      const flags = new FeatureFlags({all: false, missingInputsQuickfix: true});
+      expect(flags.isEnabled("missingInputsQuickfix")).toBe(true);
+    });
+  });
+
+  describe("getEnabledFeatures", () => {
+    it("returns empty array when no features enabled", () => {
+      const flags = new FeatureFlags();
+      expect(flags.getEnabledFeatures()).toEqual([]);
+    });
+
+    it("returns enabled features", () => {
+      const flags = new FeatureFlags({missingInputsQuickfix: true});
+      expect(flags.getEnabledFeatures()).toEqual(["missingInputsQuickfix"]);
+    });
+
+    it("returns all features when all is enabled", () => {
+      const flags = new FeatureFlags({all: true});
+      expect(flags.getEnabledFeatures()).toEqual([
+        "missingInputsQuickfix",
+        "blockScalarChompingWarning",
+        "actionScaffoldingSnippets",
+        "allowCaseFunction"
+      ]);
+    });
+  });
+});

expressions/src/features.ts

@@ -0,0 +1,91 @@
+/**
+ * Experimental feature flags.
+ *
+ * Individual feature flags take precedence over `all`.
+ * Example: { all: true, missingInputsQuickfix: false } enables all
+ * experimental features EXCEPT missingInputsQuickfix.
+ *
+ * When a feature graduates to stable, its flag becomes a no-op
+ * (the feature will be enabled regardless of the configuration value).
+ */
+export interface ExperimentalFeatures {
+  /**
+   * Enable all experimental features.
+   * Individual feature flags take precedence over this setting.
+   * @default false
+   */
+  all?: boolean;
+
+  /**
+   * Enable quickfix code action for missing required action inputs.
+   * @default false
+   */
+  missingInputsQuickfix?: boolean;
+
+  /**
+   * Warn when block scalars (| or >) use implicit clip chomping,
+   * which adds a trailing newline that may be unintentional.
+   * @default false
+   */
+  blockScalarChompingWarning?: boolean;
+
+  /**
+   * Enable action scaffolding snippets in action.yml files.
+   * Offers Node.js, Composite, and Docker action scaffolds.
+   * @default false
+   */
+  actionScaffoldingSnippets?: boolean;
+
+  /**
+   * Enable the case() function in expressions.
+   * @default false
+   */
+  allowCaseFunction?: boolean;
+}
+
+/**
+ * Keys of ExperimentalFeatures that represent actual features (excludes 'all')
+ */
+export type ExperimentalFeatureKey = Exclude<keyof ExperimentalFeatures, "all">;
+
+/**
+ * All known experimental feature keys.
+ * This list must be kept in sync with the ExperimentalFeatures interface.
+ */
+const allFeatureKeys: ExperimentalFeatureKey[] = [
+  "missingInputsQuickfix",
+  "blockScalarChompingWarning",
+  "actionScaffoldingSnippets",
+  "allowCaseFunction"
+];
+
+export class FeatureFlags {
+  private readonly features: ExperimentalFeatures;
+
+  constructor(features?: ExperimentalFeatures) {
+    this.features = features ?? {};
+  }
+
+  /**
+   * Check if an experimental feature is enabled.
+   *
+   * Resolution order:
+   * 1. Explicit feature flag (if set)
+   * 2. `all` flag (if set)
+   * 3. false (default)
+   */
+  isEnabled(feature: ExperimentalFeatureKey): boolean {
+    const explicit = this.features[feature];
+    if (explicit !== undefined) {
+      return explicit;
+    }
+    return this.features.all ?? false;
+  }
+
+  /**
+   * Returns list of all enabled experimental features.
+   */
+  getEnabledFeatures(): ExperimentalFeatureKey[] {
+    return allFeatureKeys.filter(key => this.isEnabled(key));
+  }
+}

expressions/src/funcs.ts

@@ -1,4 +1,5 @@
 import {ErrorType, ExpressionError} from "./errors.js";
+import {caseFunc} from "./funcs/case.js";
 import {contains} from "./funcs/contains.js";
 import {endswith} from "./funcs/endswith.js";
 import {format} from "./funcs/format.js";
@@ -16,6 +17,7 @@ export type ParseContext = {
 };
 
 export const wellKnownFunctions: {[name: string]: FunctionDefinition} = {
+  case: caseFunc,
   contains: contains,
   endswith: endswith,
   format: format,
@@ -53,4 +55,9 @@ export function validateFunction(context: ParseContext, identifier: Token, argCo
   if (argCount > f.maxArgs) {
     throw new ExpressionError(ErrorType.ErrorTooManyParameters, identifier);
   }
+
+  // case function requires an odd number of arguments
+  if (name === "case" && argCount % 2 === 0) {
+    throw new ExpressionError(ErrorType.ErrorEvenParameters, identifier);
+  }
 }

expressions/src/funcs/case.ts

@@ -0,0 +1,29 @@
+import {ExpressionData, Kind} from "../data/index.js";
+import {FunctionDefinition} from "./info.js";
+
+export const caseFunc: FunctionDefinition = {
+  name: "case",
+  description:
+    "`case( pred1, val1, pred2, val2, ..., default )`\n\nEvaluates predicates in order and returns the value corresponding to the first predicate that evaluates to `true`. If no predicate matches, it returns the last argument as the default value.",
+  minArgs: 3,
+  maxArgs: Number.MAX_SAFE_INTEGER,
+  call: (...args: ExpressionData[]): ExpressionData => {
+    // Evaluate predicate-result pairs
+    for (let i = 0; i < args.length - 1; i += 2) {
+      const predicate = args[i];
+
+      // Predicate must be a boolean
+      if (predicate.kind !== Kind.Boolean) {
+        throw new Error("case predicate must evaluate to a boolean value");
+      }
+
+      // If predicate is true, return the corresponding result
+      if (predicate.value) {
+        return args[i + 1];
+      }
+    }
+
+    // No predicate matched, return default (last argument)
+    return args[args.length - 1];
+  }
+};

expressions/src/index.ts

@@ -4,6 +4,7 @@ export {DescriptionDictionary, DescriptionPair, isDescriptionDictionary} from ".
 export * as data from "./data/index.js";
 export {ExpressionError, ExpressionEvaluationError} from "./errors.js";
 export {Evaluator} from "./evaluator.js";
+export {ExperimentalFeatureKey, ExperimentalFeatures, FeatureFlags} from "./features.js";
 export {wellKnownFunctions} from "./funcs.js";
 export {Lexer, Result} from "./lexer.js";
 export {Parser} from "./parser.js";

expressions/testdata/case.json

@@ -0,0 +1,157 @@
+{
+  "case": [
+    {
+      "expr": "case(true, 'first', 'default')",
+      "result": { "kind": "String", "value": "first" }
+    },
+    {
+      "expr": "case(false, 'first', 'default')",
+      "result": { "kind": "String", "value": "default" }
+    },
+    {
+      "expr": "case(true, 'first', false, 'second', 'default')",
+      "result": { "kind": "String", "value": "first" }
+    },
+    {
+      "expr": "case(false, 'first', true, 'second', 'default')",
+      "result": { "kind": "String", "value": "second" }
+    },
+    {
+      "expr": "case(false, 'first', false, 'second', 'default')",
+      "result": { "kind": "String", "value": "default" }
+    },
+    {
+      "expr": "case(1 == 1, 'equal', 'not equal')",
+      "result": { "kind": "String", "value": "equal" }
+    },
+    {
+      "expr": "case(1 == 2, 'equal', 'not equal')",
+      "result": { "kind": "String", "value": "not equal" }
+    },
+    {
+      "expr": "case(github.ref == 'refs/heads/main', 'main', github.event_name == 'pull_request', 'pr', 'other')",
+      "contexts": {
+        "github": {
+          "ref": "refs/heads/main",
+          "event_name": "push"
+        }
+      },
+      "result": { "kind": "String", "value": "main" }
+    },
+    {
+      "expr": "case(github.ref == 'refs/heads/main', 'main', github.event_name == 'pull_request', 'pr', 'other')",
+      "contexts": {
+        "github": {
+          "ref": "refs/heads/develop",
+          "event_name": "pull_request"
+        }
+      },
+      "result": { "kind": "String", "value": "pr" }
+    },
+    {
+      "expr": "case(github.ref == 'refs/heads/main', 'main', github.event_name == 'pull_request', 'pr', 'other')",
+      "contexts": {
+        "github": {
+          "ref": "refs/heads/develop",
+          "event_name": "push"
+        }
+      },
+      "result": { "kind": "String", "value": "other" }
+    },
+    {
+      "expr": "case(true, 123, 456)",
+      "result": { "kind": "Number", "value": 123 }
+    },
+    {
+      "expr": "case(false, 123, 456)",
+      "result": { "kind": "Number", "value": 456 }
+    },
+    {
+      "expr": "case(github.event == 'pull_request', 0, 1)",
+      "contexts": {
+        "github": {
+          "event": "pull_request"
+        }
+      },
+      "result": { "kind": "Number", "value": 0 }
+    },
+    {
+      "expr": "case(false, 0, 1)",
+      "result": { "kind": "Number", "value": 1 }
+    },
+    {
+      "expr": "case(true, false, true)",
+      "result": { "kind": "Boolean", "value": false }
+    },
+    {
+      "expr": "case(false, false, true)",
+      "result": { "kind": "Boolean", "value": true }
+    },
+    {
+      "expr": "case(true, '', 'default')",
+      "result": { "kind": "String", "value": "" }
+    },
+    {
+      "expr": "case(false, 'first', '')",
+      "result": { "kind": "String", "value": "" }
+    },
+    {
+      "expr": "case(true, fromJSON('[1,2,3]'), 'default')",
+      "result": { "kind": "Array", "value": [1, 2, 3] }
+    },
+    {
+      "expr": "case(true, fromJSON('{\"key\":\"value\"}'), 'default')",
+      "result": { "kind": "Object", "value": { "key": "value" } }
+    },
+    {
+      "expr": "case(false, 'first', false, 'second', false, 'third', false, 'fourth', 'default')",
+      "result": { "kind": "String", "value": "default" }
+    },
+    {
+      "expr": "case(false, 'first', false, 'second', true, 'third', false, 'fourth', 'default')",
+      "result": { "kind": "String", "value": "third" }
+    },
+    {
+      "expr": "case('not a boolean', 'first', 'default')",
+      "err": {
+        "kind": "evaluation",
+        "value": "case predicate must evaluate to a boolean value"
+      }
+    },
+    {
+      "expr": "case(1, 'first', 'default')",
+      "err": {
+        "kind": "evaluation",
+        "value": "case predicate must evaluate to a boolean value"
+      }
+    },
+    {
+      "expr": "case(null, 'first', 'default')",
+      "err": {
+        "kind": "evaluation",
+        "value": "case predicate must evaluate to a boolean value"
+      }
+    },
+    {
+      "expr": "case(fromJSON('[]'), 'first', 'default')",
+      "err": {
+        "kind": "evaluation",
+        "value": "case predicate must evaluate to a boolean value"
+      }
+    },
+    {
+      "expr": "case(fromJSON('{}'), 'first', 'default')",
+      "err": {
+        "kind": "evaluation",
+        "value": "case predicate must evaluate to a boolean value"
+      }
+    },
+    {
+      "expr": "case(true, 'first', false, 'second')",
+      "err": {
+        "kind": "parsing",
+        "value": "Even number of parameters supplied, requires an odd number of parameters: 'case'. Located at position 1 within expression: case(true, 'first', false, 'second')"
+      }
+    }
+  ]
+}

languageserver/README.md

@@ -84,6 +84,11 @@ export interface InitializationOptions {
    * Desired log level
    */
   logLevel?: LogLevel;
+
+  /**
+   * Experimental features that are opt-in
+   */
+  experimentalFeatures?: ExperimentalFeatures;
 }
 ```
 
@@ -100,6 +105,33 @@ const clientOptions: LanguageClientOptions = {
 const client = new LanguageClient("actions-language", "GitHub Actions Language Server", serverOptions, clientOptions);
 ```
 
+### Experimental Features
+
+The language server supports opt-in experimental features via the `experimentalFeatures` initialization option. These features may change or be removed in between releases.
+
+```typescript
+initializationOptions: {
+  experimentalFeatures: {
+    // Enable all experimental features
+    all: true,
+
+    // Or enable specific features
+    missingInputsQuickfix: true,
+  }
+}
+```
+
+**Available experimental features:**
+
+| Feature | Description |
+|---------|-------------|
+| `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 |
+
+Individual feature flags take precedence over `all`. For example, `{ all: true, missingInputsQuickfix: false }` enables all experimental features except `missingInputsQuickfix`.
+
+When a feature graduates to stable, its flag becomes a no-op and the feature will be enabled regardless of the configuration value.
+
 ### Standalone CLI
 
 After installing globally, you can run the language server directly:

languageserver/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actions/languageserver",
-  "version": "0.3.30",
+  "version": "0.3.36",
   "description": "Language server for GitHub Actions",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "clean": "rimraf dist",
     "format": "prettier --write '**/*.ts'",
     "format-check": "prettier --check '**/*.ts'",
-    "lint": "eslint 'src/**/*.ts'",
+    "lint": "eslint --max-warnings 0 'src/**/*.ts'",
     "lint-fix": "eslint --fix 'src/**/*.ts'",
     "prepublishOnly": "npm run build && npm run test",
     "test": "NODE_OPTIONS=\"--experimental-vm-modules\" jest",
@@ -48,8 +48,8 @@
     "actions-languageserver": "./bin/actions-languageserver"
   },
   "dependencies": {
-    "@actions/languageservice": "^0.3.30",
-    "@actions/workflow-parser": "^0.3.30",
+    "@actions/languageservice": "^0.3.36",
+    "@actions/workflow-parser": "^0.3.36",
     "@octokit/rest": "^21.1.1",
     "@octokit/types": "^9.0.0",
     "vscode-languageserver": "^8.0.2",

languageserver/src/connection.ts

@@ -20,18 +20,19 @@ import {
   TextDocumentSyncKind
 } from "vscode-languageserver";
 import {TextDocument} from "vscode-languageserver-textdocument";
-import {getClient} from "./client";
-import {Commands} from "./commands";
-import {contextProviders} from "./context-providers";
-import {descriptionProvider} from "./description-provider";
-import {getFileProvider} from "./file-provider";
-import {InitializationOptions, RepositoryContext} from "./initializationOptions";
-import {onCompletion} from "./on-completion";
-import {ReadFileRequest, Requests} from "./request";
-import {getActionsMetadataProvider} from "./utils/action-metadata";
-import {TTLCache} from "./utils/cache";
-import {timeOperation} from "./utils/timer";
-import {valueProviders} from "./value-providers";
+import {getClient} from "./client.js";
+import {Commands} from "./commands.js";
+import {contextProviders} from "./context-providers.js";
+import {descriptionProvider} from "./description-provider.js";
+import {FeatureFlags} from "@actions/expressions";
+import {getFileProvider} from "./file-provider.js";
+import {InitializationOptions, RepositoryContext} from "./initializationOptions.js";
+import {onCompletion} from "./on-completion.js";
+import {ReadFileRequest, Requests} from "./request.js";
+import {getActionsMetadataProvider} from "./utils/action-metadata.js";
+import {TTLCache} from "./utils/cache.js";
+import {timeOperation} from "./utils/timer.js";
+import {valueProviders} from "./value-providers.js";
 
 export function initConnection(connection: Connection) {
   const documents: TextDocuments<TextDocument> = new TextDocuments(TextDocument);
@@ -41,6 +42,7 @@ export function initConnection(connection: Connection) {
   const cache = new TTLCache();
 
   let hasWorkspaceFolderCapability = false;
+  let featureFlags = new FeatureFlags();
 
   // Register remote console logger with language service
   registerLogger(connection.console);
@@ -64,6 +66,8 @@ export function initConnection(connection: Connection) {
       setLogLevel(options.logLevel);
     }
 
+    featureFlags = new FeatureFlags(options.experimentalFeatures);
+
     const result: InitializeResult = {
       capabilities: {
         textDocumentSync: TextDocumentSyncKind.Full,
@@ -91,6 +95,11 @@ export function initConnection(connection: Connection) {
   });
 
   connection.onInitialized(() => {
+    const enabledFeatures = featureFlags.getEnabledFeatures();
+    if (enabledFeatures.length > 0) {
+      connection.console.info(`Experimental features enabled: ${enabledFeatures.join(", ")}`);
+    }
+
     if (hasWorkspaceFolderCapability) {
       connection.workspace.onDidChangeWorkspaceFolders(() => {
         clearCache();
@@ -114,7 +123,8 @@ export function initConnection(connection: Connection) {
       actionsMetadataProvider: getActionsMetadataProvider(client, cache),
       fileProvider: getFileProvider(client, cache, repoContext?.workspaceUri, async path => {
         return await connection.sendRequest(Requests.ReadFile, {path} satisfies ReadFileRequest);
-      })
+      }),
+      featureFlags
     };
 
     const result = await validate(textDocument, config);

languageserver/src/context-providers.test.ts

@@ -1,9 +1,9 @@
 import {data, DescriptionDictionary} from "@actions/expressions";
 import {WorkflowContext} from "@actions/languageservice/context/workflow-context";
 import {Mode} from "@actions/languageservice/context-providers/default";
-import {contextProviders} from "./context-providers";
-import {RepositoryContext} from "./initializationOptions";
-import {TTLCache} from "./utils/cache";
+import {contextProviders} from "./context-providers.js";
+import {RepositoryContext} from "./initializationOptions.js";
+import {TTLCache} from "./utils/cache.js";
 
 describe("contextProviders", () => {
   const mockCache = new TTLCache();

languageserver/src/context-providers.ts

@@ -3,11 +3,11 @@ import {ContextProviderConfig} from "@actions/languageservice";
 import {Mode} from "@actions/languageservice/context-providers/default";
 import {WorkflowContext} from "@actions/languageservice/context/workflow-context";
 import {Octokit} from "@octokit/rest";
-import {getSecrets} from "./context-providers/secrets";
-import {getStepsContext} from "./context-providers/steps";
-import {getVariables} from "./context-providers/variables";
-import {RepositoryContext} from "./initializationOptions";
-import {TTLCache} from "./utils/cache";
+import {getSecrets} from "./context-providers/secrets.js";
+import {getStepsContext} from "./context-providers/steps.js";
+import {getVariables} from "./context-providers/variables.js";
+import {RepositoryContext} from "./initializationOptions.js";
+import {TTLCache} from "./utils/cache.js";
 
 export function contextProviders(
   client: Octokit | undefined,

languageserver/src/context-providers/action-outputs.ts

@@ -1,7 +1,7 @@
 import {ActionOutputs, ActionReference} from "@actions/languageservice/action";
 import {Octokit} from "@octokit/rest";
-import {fetchActionMetadata} from "../utils/action-metadata";
-import {TTLCache} from "../utils/cache";
+import {fetchActionMetadata} from "../utils/action-metadata.js";
+import {TTLCache} from "../utils/cache.js";
 
 export async function getActionOutputs(
   octokit: Octokit,

languageserver/src/context-providers/secrets.ts

@@ -6,10 +6,10 @@ import {warn} from "@actions/languageservice/log";
 import {isMapping, isString} from "@actions/workflow-parser";
 import {Octokit} from "@octokit/rest";
 
-import {RepositoryContext} from "../initializationOptions";
-import {TTLCache} from "../utils/cache";
-import {errorStatus} from "../utils/error";
-import {getRepoPermission} from "../utils/repo-permission";
+import {RepositoryContext} from "../initializationOptions.js";
+import {TTLCache} from "../utils/cache.js";
+import {errorStatus} from "../utils/error.js";
+import {getRepoPermission} from "../utils/repo-permission.js";
 
 export async function getSecrets(
   workflowContext: WorkflowContext,

languageserver/src/context-providers/steps.test.ts

@@ -3,9 +3,9 @@ import {getStepsContext as getDefaultStepsContext} from "@actions/languageservic
 import {Octokit} from "@octokit/rest";
 import fetchMock from "fetch-mock";
 
-import {createWorkflowContext} from "../test-utils/workflow-context";
-import {TTLCache} from "../utils/cache";
-import {getStepsContext} from "./steps";
+import {createWorkflowContext} from "../test-utils/workflow-context.js";
+import {TTLCache} from "../utils/cache.js";
+import {getStepsContext} from "./steps.js";
 
 const workflow = `
 name: Caching Primes
@@ -84,13 +84,17 @@ it("outputs is an incomplete dictionary to allow dynamic outputs", async () => {
 
   // Get the step context
   const stepContext = stepsContext?.get("cache-primes");
-  expect(stepContext).toBeDefined();
-  expect(isDescriptionDictionary(stepContext!)).toBe(true);
+  if (!stepContext) {
+    throw new Error("Expected stepContext to be defined");
+  }
+  expect(isDescriptionDictionary(stepContext)).toBe(true);
 
   // Get the outputs - should be a dictionary, not null
   const outputs = (stepContext as DescriptionDictionary).get("outputs");
-  expect(outputs).toBeDefined();
-  expect(isDescriptionDictionary(outputs!)).toBe(true);
+  if (!outputs) {
+    throw new Error("Expected outputs to be defined");
+  }
+  expect(isDescriptionDictionary(outputs)).toBe(true);
 
   // Outputs should be marked incomplete to allow dynamic outputs
   const outputsDict = outputs as DescriptionDictionary;

languageserver/src/context-providers/steps.ts

@@ -3,8 +3,8 @@ import {parseActionReference} from "@actions/languageservice/action";
 import {WorkflowContext} from "@actions/languageservice/context/workflow-context";
 import {isActionStep} from "@actions/workflow-parser/model/type-guards";
 import {Octokit} from "@octokit/rest";
-import {TTLCache} from "../utils/cache";
-import {getActionOutputs} from "./action-outputs";
+import {TTLCache} from "../utils/cache.js";
+import {getActionOutputs} from "./action-outputs.js";
 
 export async function getStepsContext(
   octokit: Octokit,

languageserver/src/context-providers/variables.ts

@@ -7,10 +7,10 @@ import {isMapping, isString} from "@actions/workflow-parser";
 import {Octokit} from "@octokit/rest";
 import {RequestError} from "@octokit/request-error";
 
-import {RepositoryContext} from "../initializationOptions";
-import {TTLCache} from "../utils/cache";
-import {errorStatus} from "../utils/error";
-import {getRepoPermission} from "../utils/repo-permission";
+import {RepositoryContext} from "../initializationOptions.js";
+import {TTLCache} from "../utils/cache.js";
+import {errorStatus} from "../utils/error.js";
+import {getRepoPermission} from "../utils/repo-permission.js";
 
 export async function getVariables(
   workflowContext: WorkflowContext,

languageserver/src/description-provider.ts

@@ -1,8 +1,8 @@
 import {DescriptionProvider} from "@actions/languageservice/hover";
 import {Octokit} from "@octokit/rest";
-import {getActionDescription} from "./description-providers/action-description";
-import {getActionInputDescription} from "./description-providers/action-input";
-import {TTLCache} from "./utils/cache";
+import {getActionDescription} from "./description-providers/action-description.js";
+import {getActionInputDescription} from "./description-providers/action-input.js";
+import {TTLCache} from "./utils/cache.js";
 
 export function descriptionProvider(client: Octokit | undefined, cache: TTLCache): DescriptionProvider {
   const getDescription: DescriptionProvider["getDescription"] = async (context, token, path) => {

languageserver/src/description-providers/action-description.test.ts

@@ -1,9 +1,9 @@
 import {Octokit} from "@octokit/rest";
 import fetchMock from "fetch-mock";
-import {createWorkflowContext} from "../test-utils/workflow-context";
-import {TTLCache} from "../utils/cache";
-import {getActionDescription} from "./action-description";
-import {actionsCheckoutMetadata} from "../test-utils/action-metadata";
+import {createWorkflowContext} from "../test-utils/workflow-context.js";
+import {TTLCache} from "../utils/cache.js";
+import {getActionDescription} from "./action-description.js";
+import {actionsCheckoutMetadata} from "../test-utils/action-metadata.js";
 
 const workflow = `
 name: Hello World

languageserver/src/description-providers/action-description.ts

@@ -2,8 +2,8 @@ import {actionUrl, parseActionReference} from "@actions/languageservice/action";
 import {isActionStep} from "@actions/workflow-parser/model/type-guards";
 import {Step} from "@actions/workflow-parser/model/workflow-template";
 import {Octokit} from "@octokit/rest";
-import {fetchActionMetadata} from "../utils/action-metadata";
-import {TTLCache} from "../utils/cache";
+import {fetchActionMetadata} from "../utils/action-metadata.js";
+import {TTLCache} from "../utils/cache.js";
 
 export async function getActionDescription(client: Octokit, cache: TTLCache, step: Step): Promise<string | undefined> {
   if (!isActionStep(step)) {

languageserver/src/description-providers/action-input.test.ts

@@ -2,10 +2,10 @@ import {StringToken} from "@actions/workflow-parser/templates/tokens/string-toke
 import {Octokit} from "@octokit/rest";
 import fetchMock from "fetch-mock";
 
-import {actionsCheckoutMetadata} from "../test-utils/action-metadata";
-import {createWorkflowContext} from "../test-utils/workflow-context";
-import {TTLCache} from "../utils/cache";
-import {getActionInputDescription} from "./action-input";
+import {actionsCheckoutMetadata} from "../test-utils/action-metadata.js";
+import {createWorkflowContext} from "../test-utils/workflow-context.js";
+import {TTLCache} from "../utils/cache.js";
+import {getActionInputDescription} from "./action-input.js";
 
 const workflow = `
 name: Hello World

languageserver/src/description-providers/action-input.ts

@@ -4,8 +4,8 @@ import {isActionStep} from "@actions/workflow-parser/model/type-guards";
 import {Step} from "@actions/workflow-parser/model/workflow-template";
 import {TemplateToken} from "@actions/workflow-parser/templates/tokens/template-token";
 import {Octokit} from "@octokit/rest";
-import {fetchActionMetadata} from "../utils/action-metadata";
-import {TTLCache} from "../utils/cache";
+import {fetchActionMetadata} from "../utils/action-metadata.js";
+import {TTLCache} from "../utils/cache.js";
 
 export async function getActionInputDescription(
   client: Octokit,

languageserver/src/file-provider.ts

@@ -2,7 +2,7 @@ import {File} from "@actions/workflow-parser/workflows/file";
 import {FileProvider} from "@actions/workflow-parser/workflows/file-provider";
 import {fileIdentifier} from "@actions/workflow-parser/workflows/file-reference";
 import {Octokit} from "@octokit/rest";
-import {TTLCache} from "./utils/cache";
+import {TTLCache} from "./utils/cache.js";
 import * as vscodeURI from "vscode-uri";
 
 export function getFileProvider(

languageserver/src/index.ts

@@ -6,7 +6,7 @@ import {
 } from "vscode-languageserver/browser";
 import {createConnection as createNodeConnection} from "vscode-languageserver/node";
 
-import {initConnection} from "./connection";
+import {initConnection} from "./connection.js";
 
 /** Helper function determining whether we are executing with node runtime */
 function isNode(): boolean {

languageserver/src/initializationOptions.ts

@@ -1,3 +1,4 @@
+import {ExperimentalFeatures} from "@actions/expressions";
 import {LogLevel} from "@actions/languageservice/log";
 export {LogLevel} from "@actions/languageservice/log";
 
@@ -28,6 +29,12 @@ export interface InitializationOptions {
    * If a GitHub Enterprise Server should be used, the URL of the API endpoint, eg "https://ghe.my-company.com/api/v3"
    */
   gitHubApiUrl?: string;
+
+  /**
+   * Experimental features that are opt-in.
+   * Features listed here may change or be removed without notice.
+   */
+  experimentalFeatures?: ExperimentalFeatures;
 }
 
 export interface RepositoryContext {

languageserver/src/on-completion.ts

@@ -2,12 +2,12 @@ import {complete} from "@actions/languageservice/complete";
 import {Octokit} from "@octokit/rest";
 import {CompletionItem, Connection, Position} from "vscode-languageserver";
 import {TextDocument} from "vscode-languageserver-textdocument";
-import {contextProviders} from "./context-providers";
-import {getFileProvider} from "./file-provider";
-import {RepositoryContext} from "./initializationOptions";
-import {Requests} from "./request";
-import {TTLCache} from "./utils/cache";
-import {valueProviders} from "./value-providers";
+import {contextProviders} from "./context-providers.js";
+import {getFileProvider} from "./file-provider.js";
+import {RepositoryContext} from "./initializationOptions.js";
+import {Requests} from "./request.js";
+import {TTLCache} from "./utils/cache.js";
+import {valueProviders} from "./value-providers.js";
 
 export async function onCompletion(
   connection: Connection,

languageserver/src/utils/action-metadata.test.ts

@@ -1,7 +1,7 @@
 import {Octokit} from "@octokit/rest";
 import fetchMock from "fetch-mock";
-import {fetchActionMetadata} from "./action-metadata";
-import {TTLCache} from "./cache";
+import {fetchActionMetadata} from "./action-metadata.js";
+import {TTLCache} from "./cache.js";
 
 // A simplified version of the action.yml file from actions/checkout
 const actionMetadataContent = `

languageserver/src/utils/action-metadata.ts

@@ -3,8 +3,8 @@ import {ActionsMetadataProvider} from "@actions/languageservice";
 import {error} from "@actions/languageservice/log";
 import {Octokit, RestEndpointMethodTypes} from "@octokit/rest";
 import {parse} from "yaml";
-import {TTLCache} from "./cache";
-import {errorMessage, errorStatus} from "./error";
+import {TTLCache} from "./cache.js";
+import {errorMessage, errorStatus} from "./error.js";
 
 export function getActionsMetadataProvider(
   client: Octokit | undefined,

languageserver/src/utils/repo-permission.ts

@@ -1,9 +1,9 @@
 import {error} from "@actions/languageservice/log";
 import {Octokit} from "@octokit/rest";
-import {RepositoryContext} from "../initializationOptions";
-import {TTLCache} from "./cache";
-import {errorStatus} from "./error";
-import {getUsername} from "./username";
+import {RepositoryContext} from "../initializationOptions.js";
+import {TTLCache} from "./cache.js";
+import {errorStatus} from "./error.js";
+import {getUsername} from "./username.js";
 
 export type RepoPermission = "admin" | "write" | "read" | "none";
 

languageserver/src/utils/username.ts

@@ -1,5 +1,5 @@
 import {Octokit} from "@octokit/rest";
-import {TTLCache} from "./cache";
+import {TTLCache} from "./cache.js";
 
 export async function getUsername(octokit: Octokit, cache: TTLCache): Promise<string> {
   return await cache.get(`/username`, undefined, () => fetchUsername(octokit));

languageserver/src/value-providers.ts

@@ -2,11 +2,11 @@ import {ValueProviderConfig} from "@actions/languageservice";
 import {WorkflowContext} from "@actions/languageservice/context/workflow-context";
 import {ValueProviderKind} from "@actions/languageservice/value-providers/config";
 import {Octokit} from "@octokit/rest";
-import {RepositoryContext} from "./initializationOptions";
-import {TTLCache} from "./utils/cache";
-import {getActionInputValues} from "./value-providers/action-inputs";
-import {getEnvironments} from "./value-providers/job-environment";
-import {getRunnerLabels} from "./value-providers/runs-on";
+import {RepositoryContext} from "./initializationOptions.js";
+import {TTLCache} from "./utils/cache.js";
+import {getActionInputValues} from "./value-providers/action-inputs.js";
+import {getEnvironments} from "./value-providers/job-environment.js";
+import {getRunnerLabels} from "./value-providers/runs-on.js";
 
 export function valueProviders(
   client: Octokit | undefined,

languageserver/src/value-providers/action-inputs.ts

@@ -3,8 +3,8 @@ import {WorkflowContext} from "@actions/languageservice/context/workflow-context
 import {Value} from "@actions/languageservice/value-providers/config";
 import {isActionStep} from "@actions/workflow-parser/model/type-guards";
 import {Octokit} from "@octokit/rest";
-import {fetchActionMetadata} from "../utils/action-metadata";
-import {TTLCache} from "../utils/cache";
+import {fetchActionMetadata} from "../utils/action-metadata.js";
+import {TTLCache} from "../utils/cache.js";
 
 export async function getActionInputs(
   client: Octokit,

languageserver/src/value-providers/job-environment.ts

@@ -1,6 +1,6 @@
 import {Value} from "@actions/languageservice/value-providers/config";
 import {Octokit} from "@octokit/rest";
-import {TTLCache} from "../utils/cache";
+import {TTLCache} from "../utils/cache.js";
 
 export async function getEnvironments(client: Octokit, cache: TTLCache, owner: string, name: string): Promise<Value[]> {
   const environments = await cache.get(`${owner}/${name}/environments`, undefined, () =>

languageserver/src/value-providers/runs-on.ts

@@ -2,8 +2,8 @@ import {log} from "@actions/languageservice/log";
 import {Value} from "@actions/languageservice/value-providers/config";
 import {DEFAULT_RUNNER_LABELS} from "@actions/languageservice/value-providers/default";
 import {Octokit} from "@octokit/rest";
-import {TTLCache} from "../utils/cache";
-import {errorMessage} from "../utils/error";
+import {TTLCache} from "../utils/cache.js";
+import {errorMessage} from "../utils/error.js";
 
 // Limitation: getRunnerLabels returns default hosted labels and labels for repository self-hosted runners.
 // It doesn't return labels for organization runners visible to the repository.

languageserver/tsconfig.build.json

@@ -5,6 +5,7 @@
     "declaration": true,
     "declarationMap": true,
     "noEmit": false,
-    "outDir": "./dist"
+    "outDir": "./dist",
+    "skipLibCheck": true
   }
 }

languageservice/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actions/languageservice",
-  "version": "0.3.30",
+  "version": "0.3.36",
   "description": "Language service for GitHub Actions",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
     "clean": "rimraf dist",
     "format": "prettier --write '**/*.ts'",
     "format-check": "prettier --check '**/*.ts'",
-    "lint": "eslint 'src/**/*.ts'",
+    "lint": "eslint --max-warnings 0 'src/**/*.ts'",
     "lint-fix": "eslint --fix 'src/**/*.ts'",
     "minify-json": "node ../script/minify-json.js src/context-providers/descriptions.json src/context-providers/events/webhooks.json src/context-providers/events/objects.json src/context-providers/events/schedule.json src/context-providers/events/workflow_call.json",
     "prebuild": "npm run minify-json",
@@ -47,8 +47,8 @@
     "watch": "tsc --build tsconfig.build.json --watch"
   },
   "dependencies": {
-    "@actions/expressions": "^0.3.30",
-    "@actions/workflow-parser": "^0.3.30",
+    "@actions/expressions": "^0.3.36",
+    "@actions/workflow-parser": "^0.3.36",
     "vscode-languageserver-textdocument": "^1.0.7",
     "vscode-languageserver-types": "^3.17.2",
     "vscode-uri": "^3.0.8",

languageservice/src/complete-action.test.ts

@@ -0,0 +1,557 @@
+import {FeatureFlags} from "@actions/expressions";
+import {TextDocument} from "vscode-languageserver-textdocument";
+import {complete, CompletionConfig} from "./complete";
+import {clearCache} from "./utils/workflow-cache";
+
+beforeEach(() => {
+  clearCache();
+});
+
+// Config to enable action scaffolding snippets
+const scaffoldingConfig: CompletionConfig = {
+  featureFlags: new FeatureFlags({actionScaffoldingSnippets: true})
+};
+
+describe("complete action files", () => {
+  function createActionDocument(
+    content: string,
+    uri = "file:///test/action.yml"
+  ): [TextDocument, {line: number; character: number}] {
+    // Parse cursor position and remove the | character
+    const cursorIndex = content.indexOf("|");
+    if (cursorIndex === -1) {
+      throw new Error("No cursor (|) found in content");
+    }
+    const newContent = content.substring(0, cursorIndex) + content.substring(cursorIndex + 1);
+    const doc = TextDocument.create(uri, "yaml", 1, newContent);
+    const position = doc.positionAt(cursorIndex);
+    return [doc, position];
+  }
+
+  describe("expression completion in composite actions", () => {
+    it("completes inputs context", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test action
+inputs:
+  name:
+    description: The name
+  greeting:
+    description: The greeting
+    default: Hello
+runs:
+  using: composite
+  steps:
+    - run: echo "\${{ inputs.| }}"
+      shell: bash`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("name");
+      expect(labels).toContain("greeting");
+    });
+
+    it("completes steps context with prior step IDs", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test action
+runs:
+  using: composite
+  steps:
+    - id: step1
+      run: echo "hello"
+      shell: bash
+    - id: step2
+      run: echo "\${{ steps.| }}"
+      shell: bash`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("step1");
+      expect(labels).not.toContain("step2"); // Current step should not be included
+    });
+
+    it("completes step properties", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test action
+runs:
+  using: composite
+  steps:
+    - id: greet
+      run: echo "hello"
+      shell: bash
+    - run: echo "\${{ steps.greet.| }}"
+      shell: bash`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("outputs");
+      expect(labels).toContain("outcome");
+      expect(labels).toContain("conclusion");
+    });
+
+    it("does not include steps from after cursor position", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test action
+runs:
+  using: composite
+  steps:
+    - id: first
+      run: echo "first"
+      shell: bash
+    - run: echo "\${{ steps.| }}"
+      shell: bash
+    - id: last
+      run: echo "last"
+      shell: bash`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("first");
+      expect(labels).not.toContain("last");
+    });
+
+    it("completes github context in actions", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test action
+runs:
+  using: composite
+  steps:
+    - run: echo "\${{ github.| }}"
+      shell: bash`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("actor");
+      expect(labels).toContain("repository");
+      expect(labels).toContain("ref");
+    });
+
+    it("completes runner context in actions", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test action
+runs:
+  using: composite
+  steps:
+    - run: echo "\${{ runner.| }}"
+      shell: bash`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("os");
+      expect(labels).toContain("arch");
+      expect(labels).toContain("temp");
+    });
+  });
+
+  describe("top-level completions", () => {
+    it("completes top-level keys", async () => {
+      const [doc, position] = createActionDocument(`n|`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("name");
+    });
+
+    it("completes at empty line", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+|`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("description");
+      expect(labels).toContain("runs");
+      expect(labels).toContain("inputs");
+      expect(labels).toContain("outputs");
+      expect(labels).toContain("branding");
+      expect(labels).toContain("author");
+    });
+  });
+
+  describe("runs completions", () => {
+    it("completes runs.using values", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+runs:
+  using: |`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("composite");
+      expect(labels).toContain("node20");
+      expect(labels).toContain("docker");
+    });
+
+    it("completes runs keys", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+runs:
+  |`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("using");
+    });
+
+    it("filters runs keys for node20 actions", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+runs:
+  using: node20
+  |`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      // Should show Node.js action keys
+      expect(labels).toContain("main");
+      expect(labels).toContain("pre");
+      expect(labels).toContain("post");
+      expect(labels).toContain("pre-if");
+      expect(labels).toContain("post-if");
+
+      // Should NOT show composite or docker keys
+      expect(labels).not.toContain("steps");
+      expect(labels).not.toContain("image");
+      expect(labels).not.toContain("entrypoint");
+    });
+
+    it("filters runs keys for composite actions", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+runs:
+  using: composite
+  |`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      // Should show composite action keys
+      expect(labels).toContain("steps");
+
+      // Should NOT show Node.js or docker keys
+      expect(labels).not.toContain("main");
+      expect(labels).not.toContain("pre");
+      expect(labels).not.toContain("post");
+      expect(labels).not.toContain("image");
+    });
+
+    it("filters runs keys for docker actions", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+runs:
+  using: docker
+  |`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      // Should show Docker action keys
+      expect(labels).toContain("image");
+      expect(labels).toContain("args");
+      expect(labels).toContain("env");
+      expect(labels).toContain("entrypoint");
+      expect(labels).toContain("pre-entrypoint");
+      expect(labels).toContain("post-entrypoint");
+
+      // Should NOT show Node.js or composite keys
+      expect(labels).not.toContain("main");
+      expect(labels).not.toContain("steps");
+    });
+
+    it("prioritizes using when not set", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+runs:
+  |`);
+      const completions = await complete(doc, position);
+
+      // Find the using completion
+      const usingCompletion = completions.find(c => c.label === "using");
+      expect(usingCompletion).toBeDefined();
+
+      // It should have a sortText that makes it sort first
+      expect(usingCompletion?.sortText).toBe("0_using");
+    });
+
+    it("completes step keys inside composite action steps", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+runs:
+  using: composite
+  steps:
+    - run: echo hello
+      shell: bash
+    - |`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      // Should show step keys, not filtered by runs-level logic
+      expect(labels).toContain("run");
+      expect(labels).toContain("uses");
+      expect(labels).toContain("shell");
+      expect(labels).toContain("id");
+      expect(labels).toContain("name");
+      expect(labels).toContain("if");
+      expect(labels).toContain("env");
+      expect(labels).toContain("working-directory");
+    });
+  });
+
+  describe("branding completions", () => {
+    it("completes branding keys", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+runs:
+  using: node20
+  main: index.js
+branding:
+  |`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("icon");
+      expect(labels).toContain("color");
+    });
+
+    it("completes branding color values", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+runs:
+  using: node20
+  main: index.js
+branding:
+  color: |`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("blue");
+      expect(labels).toContain("green");
+      expect(labels).toContain("red");
+    });
+  });
+
+  describe("inputs completions", () => {
+    it("completes input property keys", async () => {
+      const [doc, position] = createActionDocument(`name: Test
+description: Test
+inputs:
+  my-input:
+    |
+runs:
+  using: node20
+  main: index.js`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("description");
+      expect(labels).toContain("required");
+      expect(labels).toContain("default");
+      expect(labels).toContain("deprecationMessage");
+    });
+  });
+
+  describe("document type routing", () => {
+    it("routes action.yml to action completion", async () => {
+      const [doc, position] = createActionDocument(`n|`, "file:///my-repo/action.yml");
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("name");
+      // Should NOT contain workflow-specific keys
+      expect(labels).not.toContain("on");
+      expect(labels).not.toContain("jobs");
+    });
+
+    it("includes descriptions from schema for completion items", async () => {
+      const [doc, position] = createActionDocument(`|`, "file:///my-repo/action.yml");
+      const completions = await complete(doc, position);
+
+      const authorCompletion = completions.find(c => c.label === "author");
+      expect(authorCompletion).toBeDefined();
+      expect(authorCompletion?.documentation).toBeDefined();
+      expect((authorCompletion?.documentation as {value: string})?.value).toContain("author");
+    });
+
+    it("includes descriptions for branding completion", async () => {
+      const [doc, position] = createActionDocument(`|`, "file:///my-repo/action.yml");
+      const completions = await complete(doc, position);
+
+      const brandingCompletion = completions.find(c => c.label === "branding");
+      expect(brandingCompletion).toBeDefined();
+      expect(brandingCompletion?.documentation).toBeDefined();
+      expect((brandingCompletion?.documentation as {value: string})?.value).toContain("branding");
+    });
+
+    it("falls back to type description when property has no description", async () => {
+      // `inputs` uses shorthand form in schema: "inputs": "inputs-strict"
+      // So the property has no description, but the type `inputs-strict` does
+      const [doc, position] = createActionDocument(`|`, "file:///my-repo/action.yml");
+      const completions = await complete(doc, position);
+
+      const inputsCompletion = completions.find(c => c.label === "inputs");
+      expect(inputsCompletion).toBeDefined();
+      expect(inputsCompletion?.documentation).toBeDefined();
+      expect((inputsCompletion?.documentation as {value: string})?.value).toContain("Input parameters");
+    });
+
+    it("does not route workflow files to action completion", async () => {
+      const doc = TextDocument.create("file:///repo/.github/workflows/ci.yml", "yaml", 1, `o`);
+      const completions = await complete(doc, {line: 0, character: 1});
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("on");
+      expect(labels).toContain("jobs");
+    });
+  });
+
+  describe("action scaffolding snippets", () => {
+    it("offers full scaffolding snippets in empty file", async () => {
+      const [doc, position] = createActionDocument(`|`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("Node.js Action");
+      expect(labels).toContain("Composite Action");
+      expect(labels).toContain("Docker Action");
+
+      // Verify they are snippets
+      const nodeSnippet = completions.find(c => c.label === "Node.js Action");
+      expect(nodeSnippet?.kind).toBe(15); // CompletionItemKind.Snippet
+      expect(nodeSnippet?.insertTextFormat).toBe(2); // InsertTextFormat.Snippet
+    });
+
+    it("offers full scaffolding snippets when no name or description exists", async () => {
+      const [doc, position] = createActionDocument(`author: me
+|`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+
+      const nodeSnippet = completions.find(c => c.label === "Node.js Action");
+      expect(nodeSnippet).toBeDefined();
+      // Full snippet should include name:
+      expect((nodeSnippet?.textEdit as {newText: string})?.newText).toContain("name:");
+    });
+
+    it("offers runs-only snippets when name exists", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+|`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+
+      const nodeSnippet = completions.find(c => c.label === "Node.js Action");
+      expect(nodeSnippet).toBeDefined();
+      // Runs-only snippet should start with inputs:, not name:
+      expect((nodeSnippet?.textEdit as {newText: string})?.newText).toMatch(/^inputs:/);
+      expect((nodeSnippet?.textEdit as {newText: string})?.newText).toContain("runs:");
+    });
+
+    it("offers runs-only snippets when description exists", async () => {
+      const [doc, position] = createActionDocument(`description: Does something
+|`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+
+      const compositeSnippet = completions.find(c => c.label === "Composite Action");
+      expect(compositeSnippet).toBeDefined();
+      // Runs-only snippet should start with inputs:, not description:
+      expect((compositeSnippet?.textEdit as {newText: string})?.newText).toMatch(/^inputs:/);
+      expect((compositeSnippet?.textEdit as {newText: string})?.newText).toContain("runs:");
+    });
+
+    it("does not offer snippets when runs.using already exists", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+runs:
+  using: composite
+  |`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).not.toContain("Node.js Action");
+      expect(labels).not.toContain("Composite Action");
+      expect(labels).not.toContain("Docker Action");
+    });
+
+    it("offers snippets inside runs when using is not set", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+runs:
+  |`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).toContain("Node.js Action");
+      expect(labels).toContain("Composite Action");
+      expect(labels).toContain("Docker Action");
+    });
+
+    it("does not offer snippets at root level when runs exists", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+runs:
+  steps: []
+|`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).not.toContain("Node.js Action");
+      expect(labels).not.toContain("Composite Action");
+      expect(labels).not.toContain("Docker Action");
+    });
+
+    it("does not offer snippets when nested inside runs steps", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+runs:
+  using: composite
+  steps:
+    - |`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).not.toContain("Node.js Action");
+      expect(labels).not.toContain("Composite Action");
+      expect(labels).not.toContain("Docker Action");
+    });
+
+    it("Node.js snippet contains expected content", async () => {
+      const [doc, position] = createActionDocument(`|`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+
+      const nodeSnippet = completions.find(c => c.label === "Node.js Action");
+      const text = (nodeSnippet?.textEdit as {newText: string})?.newText;
+
+      expect(text).toContain("using: node24");
+      expect(text).toContain("main:");
+      expect(text).toContain("inputs:");
+      expect(text).toContain("outputs:");
+    });
+
+    it("Composite snippet contains expected content", async () => {
+      const [doc, position] = createActionDocument(`|`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+
+      const compositeSnippet = completions.find(c => c.label === "Composite Action");
+      const text = (compositeSnippet?.textEdit as {newText: string})?.newText;
+
+      expect(text).toContain("using: composite");
+      expect(text).toContain("steps:");
+      expect(text).toContain("shell: bash");
+    });
+
+    it("Docker snippet contains expected content", async () => {
+      const [doc, position] = createActionDocument(`|`);
+      const completions = await complete(doc, position, scaffoldingConfig);
+
+      const dockerSnippet = completions.find(c => c.label === "Docker Action");
+      const text = (dockerSnippet?.textEdit as {newText: string})?.newText;
+
+      expect(text).toContain("using: docker");
+      expect(text).toContain("image:");
+      expect(text).toContain("entrypoint:");
+    });
+
+    it("does not offer snippets when feature flag is disabled", async () => {
+      const [doc, position] = createActionDocument(`|`);
+      const completions = await complete(doc, position);
+      const labels = completions.map(c => c.label);
+
+      expect(labels).not.toContain("Node.js Action");
+      expect(labels).not.toContain("Composite Action");
+      expect(labels).not.toContain("Docker Action");
+    });
+  });
+});

languageservice/src/complete-action.ts

@@ -0,0 +1,468 @@
+import {TemplateToken} from "@actions/workflow-parser/templates/tokens/index";
+import {MappingToken} from "@actions/workflow-parser/templates/tokens/mapping-token";
+import {Position} from "vscode-languageserver-textdocument";
+import {CompletionItem, CompletionItemKind, InsertTextFormat, TextEdit} from "vscode-languageserver-types";
+import {Value} from "./value-providers/config.js";
+
+/**
+ * Valid keys for each action type under the `runs:` section.
+ * Source: https://github.com/actions/runner/blob/main/src/Runner.Worker/ActionManifestManager.cs
+ */
+const ACTION_NODE_KEYS = new Set(["using", "main", "pre", "post", "pre-if", "post-if"]);
+const ACTION_COMPOSITE_KEYS = new Set(["using", "steps"]);
+const ACTION_DOCKER_KEYS = new Set([
+  "using",
+  "image",
+  "args",
+  "env",
+  "entrypoint",
+  "pre-entrypoint",
+  "pre-if",
+  "post-entrypoint",
+  "post-if"
+]);
+
+/**
+ * Action scaffolding snippets.
+ *
+ * Full variants include name, description, inputs, outputs, and runs.
+ * Runs-only variants include just the runs block.
+ */
+const ACTION_SNIPPET_NODEJS_FULL = `name: '\${1:Action Name}'
+description: '\${2:What this action does}'
+
+inputs:
+  name:
+    description: 'Name to greet'
+    required: false
+    default: 'World'
+
+outputs:
+  greeting:
+    description: 'The greeting message'
+
+runs:
+  # For more on JavaScript actions (including @actions/toolkit), see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-javascript-action
+  using: node24
+  main: index.js
+  # Sample index.js (vanilla JS, no build required):
+  #
+  #   const fs = require('fs');
+  #   const name = process.env.INPUT_NAME || 'World';
+  #   const greeting = \\\`Hello \\\${name}\\\`;
+  #   console.log(greeting);
+  #   fs.appendFileSync(process.env.GITHUB_OUTPUT, \\\`greeting=\\\${greeting}\\\\n\\\`);
+  #
+  # For JavaScript actions with @actions/toolkit, see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-javascript-action
+`;
+
+const ACTION_SNIPPET_NODEJS_RUNS = `inputs:
+  name:
+    description: 'Name to greet'
+    required: false
+    default: 'World'
+
+outputs:
+  greeting:
+    description: 'The greeting message'
+
+runs:
+  # For more on JavaScript actions (including @actions/toolkit), see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-javascript-action
+  using: node24
+  main: index.js
+  # Sample index.js (vanilla JS, no build required):
+  #
+  #   const fs = require('fs');
+  #   const name = process.env.INPUT_NAME || 'World';
+  #   const greeting = \\\`Hello \\\${name}\\\`;
+  #   console.log(greeting);
+  #   fs.appendFileSync(process.env.GITHUB_OUTPUT, \\\`greeting=\\\${greeting}\\\\n\\\`);
+`;
+
+const ACTION_SNIPPET_NODEJS_USING = `# For more on JavaScript actions (including @actions/toolkit), see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-javascript-action
+  using: node24
+  main: index.js
+  # Sample index.js (vanilla JS, no build required):
+  #
+  #   console.log('Hello World');
+`;
+
+const ACTION_SNIPPET_COMPOSITE_FULL = `name: '\${1:Action Name}'
+description: '\${2:What this action does}'
+
+inputs:
+  name:
+    description: 'Name to greet'
+    required: false
+    default: 'World'
+
+outputs:
+  greeting:
+    description: 'The greeting message'
+    value: \\\${{ steps.greet.outputs.greeting }}
+
+runs:
+  # For more on composite actions, see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action
+  using: composite
+  steps:
+    - id: greet
+      shell: bash
+      env:
+        INPUT_NAME: \\\${{ inputs.name }}
+      run: |
+        GREETING="Hello $INPUT_NAME"
+        echo "$GREETING"
+        echo "greeting=$GREETING" >> $GITHUB_OUTPUT
+`;
+
+const ACTION_SNIPPET_COMPOSITE_RUNS = `inputs:
+  name:
+    description: 'Name to greet'
+    required: false
+    default: 'World'
+
+outputs:
+  greeting:
+    description: 'The greeting message'
+    value: \\\${{ steps.greet.outputs.greeting }}
+
+runs:
+  # For more on composite actions, see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action
+  using: composite
+  steps:
+    - id: greet
+      shell: bash
+      env:
+        INPUT_NAME: \\\${{ inputs.name }}
+      run: |
+        GREETING="Hello $INPUT_NAME"
+        echo "$GREETING"
+        echo "greeting=$GREETING" >> $GITHUB_OUTPUT
+`;
+
+const ACTION_SNIPPET_COMPOSITE_USING = `# For more on composite actions, see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action
+  using: composite
+  steps:
+    - shell: bash
+      run: echo "Hello World"
+`;
+
+const ACTION_SNIPPET_DOCKER_FULL = `name: '\${1:Action Name}'
+description: '\${2:What this action does}'
+
+inputs:
+  name:
+    description: 'Name to greet'
+    required: false
+    default: 'World'
+
+outputs:
+  greeting:
+    description: 'The greeting message'
+
+runs:
+  # For more on Docker actions, see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action
+  using: docker
+  # 'docker://image:tag' uses pre-built image, 'Dockerfile' builds locally
+  image: '\${3:docker://alpine:3.20}'
+  env:
+    INPUT_NAME: \\\${{ inputs.name }}
+  entrypoint: '\${4:sh}'
+  args:
+    - -c
+    - |
+      GREETING="Hello $INPUT_NAME"
+      echo "$GREETING"
+      echo "greeting=$GREETING" >> $GITHUB_OUTPUT
+`;
+
+const ACTION_SNIPPET_DOCKER_RUNS = `inputs:
+  name:
+    description: 'Name to greet'
+    required: false
+    default: 'World'
+
+outputs:
+  greeting:
+    description: 'The greeting message'
+
+runs:
+  # For more on Docker actions, see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action
+  using: docker
+  # 'docker://image:tag' uses pre-built image, 'Dockerfile' builds locally
+  image: '\${1:docker://alpine:3.20}'
+  env:
+    INPUT_NAME: \\\${{ inputs.name }}
+  entrypoint: '\${2:sh}'
+  args:
+    - -c
+    - |
+      GREETING="Hello $INPUT_NAME"
+      echo "$GREETING"
+      echo "greeting=$GREETING" >> $GITHUB_OUTPUT
+`;
+
+const ACTION_SNIPPET_DOCKER_USING = `# For more on Docker actions, see:
+  # https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action
+  using: docker
+  # 'docker://image:tag' uses pre-built image, 'Dockerfile' builds locally
+  image: '\${1:docker://alpine:3.20}'
+  entrypoint: '\${2:sh}'
+  args:
+    - -c
+    - echo "Hello World"
+`;
+
+/**
+ * Filters action.yml `runs:` completions based on the `using:` value.
+ *
+ * When the user is completing keys under `runs:`:
+ * - If `using: node20` is set, only show Node.js action keys
+ * - If `using: composite` is set, only show composite action keys
+ * - If `using: docker` is set, only show Docker action keys
+ * - If `using:` is not set, show all keys but prioritize `using` first
+ */
+export function filterActionRunsCompletions(values: Value[], path: TemplateToken[], root: TemplateToken): Value[] {
+  // Find the runs mapping from the root
+  let runsMapping: MappingToken | undefined;
+  if (root instanceof MappingToken) {
+    for (let i = 0; i < root.count; i++) {
+      const {key, value} = root.get(i);
+      if (key.toString().toLowerCase() === "runs" && value instanceof MappingToken) {
+        runsMapping = value;
+        break;
+      }
+    }
+  }
+  if (!runsMapping) {
+    return values;
+  }
+
+  // Check if the runs mapping is in our path (meaning we're completing inside it)
+  const isInsideRuns = path.some(token => token === runsMapping);
+  if (!isInsideRuns) {
+    return values;
+  }
+
+  // Find where runsMapping is in the path
+  const runsMappingIndex = path.indexOf(runsMapping);
+  if (runsMappingIndex === -1) {
+    return values;
+  }
+
+  // Check if there's anything after runsMapping in the path
+  // If so, we're nested deeper (e.g., inside steps sequence or a step mapping)
+  if (runsMappingIndex < path.length - 1) {
+    return values;
+  }
+
+  // Get the using value from the runs mapping
+  let usingValue: string | undefined;
+  for (let i = 0; i < runsMapping.count; i++) {
+    const {key, value} = runsMapping.get(i);
+    if (key.toString().toLowerCase() === "using") {
+      usingValue = value.toString();
+      break;
+    }
+  }
+
+  // Determine which keys to allow
+  let allowedKeys: Set<string>;
+
+  if (!usingValue) {
+    // No using value set - show all keys but prioritize "using"
+    return values.map(v => {
+      if (v.label.toLowerCase() === "using") {
+        return {...v, sortText: "0_using"}; // Sort first
+      }
+      return v;
+    });
+  } else if (usingValue.match(/^node\d+$/i)) {
+    allowedKeys = ACTION_NODE_KEYS;
+  } else if (usingValue.toLowerCase() === "composite") {
+    allowedKeys = ACTION_COMPOSITE_KEYS;
+  } else if (usingValue.toLowerCase() === "docker") {
+    allowedKeys = ACTION_DOCKER_KEYS;
+  } else {
+    // Unknown using value - show all
+    return values;
+  }
+
+  // Filter to only allowed keys
+  return values.filter(v => allowedKeys.has(v.label.toLowerCase()));
+}
+
+/**
+ * Gets action scaffolding snippet completions for action.yml files.
+ *
+ * Returns snippet completions when `runs.using` is not present, offering
+ * three action types: Node.js, Composite, and Docker.
+ *
+ * Three variants per type:
+ * - "_FULL": Full scaffold with name, description, inputs, outputs, and runs
+ * - "_RUNS": Inputs, outputs, and runs (when name/description already exists)
+ * - "_USING": Minimal runs content (when inside `runs:` mapping)
+ *
+ * Which variant is shown depends on context:
+ * - Inside `runs:` mapping → "_USING" variants
+ * - At root with name/description → "_RUNS" variants
+ * - At root without name/description → "_FULL" variants
+ */
+export function getActionScaffoldingSnippets(
+  root: TemplateToken | undefined,
+  path: TemplateToken[],
+  position: Position
+): CompletionItem[] {
+  // Get the runs mapping from the root, if it exists
+  let runsMapping: MappingToken | undefined;
+  if (root instanceof MappingToken) {
+    for (let i = 0; i < root.count; i++) {
+      const {key, value} = root.get(i);
+      if (key.toString().toLowerCase() === "runs" && value instanceof MappingToken) {
+        runsMapping = value;
+        break;
+      }
+    }
+  }
+
+  // Check if runs.using already exists - if so, no scaffolding needed
+  if (runsMapping) {
+    for (let i = 0; i < runsMapping.count; i++) {
+      const {key} = runsMapping.get(i);
+      if (key.toString().toLowerCase() === "using") {
+        return [];
+      }
+    }
+  }
+
+  // Show "_USING" variants directly inside `runs`
+  const runsMappingIndex = runsMapping ? path.indexOf(runsMapping) : -1;
+  const isDirectlyInsideRuns = runsMappingIndex !== -1 && runsMappingIndex === path.length - 1;
+  if (isDirectlyInsideRuns) {
+    return [
+      createSnippetCompletion(
+        "Node.js Action",
+        "Scaffold a Node.js action",
+        ACTION_SNIPPET_NODEJS_USING,
+        position,
+        "1_nodejs"
+      ),
+      createSnippetCompletion(
+        "Composite Action",
+        "Scaffold a composite action",
+        ACTION_SNIPPET_COMPOSITE_USING,
+        position,
+        "2_composite"
+      ),
+      createSnippetCompletion(
+        "Docker Action",
+        "Scaffold a Docker action",
+        ACTION_SNIPPET_DOCKER_USING,
+        position,
+        "3_docker"
+      )
+    ];
+  }
+
+  // Not at root or `runs` already exists?
+  const isAtRoot = path.length === 0 || (path.length === 1 && path[0] === root);
+  if (!isAtRoot || runsMapping) {
+    return [];
+  }
+
+  // Determine which variant to show based on existing root keys
+  let hasNameOrDescription = false;
+  if (root instanceof MappingToken) {
+    for (let i = 0; i < root.count; i++) {
+      const keyStr = root.get(i).key.toString().toLowerCase();
+      if (keyStr === "name" || keyStr === "description") {
+        hasNameOrDescription = true;
+        break;
+      }
+    }
+  }
+
+  // Show "_RUNS" variants (inputs, outputs, and runs block)
+  if (hasNameOrDescription) {
+    return [
+      createSnippetCompletion(
+        "Node.js Action",
+        "Scaffold a Node.js action",
+        ACTION_SNIPPET_NODEJS_RUNS,
+        position,
+        "1_nodejs"
+      ),
+      createSnippetCompletion(
+        "Composite Action",
+        "Scaffold a composite action",
+        ACTION_SNIPPET_COMPOSITE_RUNS,
+        position,
+        "2_composite"
+      ),
+      createSnippetCompletion(
+        "Docker Action",
+        "Scaffold a Docker action",
+        ACTION_SNIPPET_DOCKER_RUNS,
+        position,
+        "3_docker"
+      )
+    ];
+  }
+
+  // Show "_FULL" variants (complete scaffold)
+  return [
+    createSnippetCompletion(
+      "Node.js Action",
+      "Scaffold a complete Node.js action",
+      ACTION_SNIPPET_NODEJS_FULL,
+      position,
+      "1_nodejs"
+    ),
+    createSnippetCompletion(
+      "Composite Action",
+      "Scaffold a complete composite action",
+      ACTION_SNIPPET_COMPOSITE_FULL,
+      position,
+      "2_composite"
+    ),
+    createSnippetCompletion(
+      "Docker Action",
+      "Scaffold a complete Docker action",
+      ACTION_SNIPPET_DOCKER_FULL,
+      position,
+      "3_docker"
+    )
+  ];
+}
+
+/**
+ * Creates a snippet completion item.
+ */
+function createSnippetCompletion(
+  label: string,
+  description: string,
+  snippetText: string,
+  position: Position,
+  sortText: string
+): CompletionItem {
+  return {
+    label,
+    kind: CompletionItemKind.Snippet,
+    documentation: {
+      kind: "markdown",
+      value: description
+    },
+    insertTextFormat: InsertTextFormat.Snippet,
+    sortText,
+    textEdit: TextEdit.insert(position, snippetText)
+  };
+}

languageservice/src/complete.expressions.test.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
-import {data, DescriptionDictionary} from "@actions/expressions";
+import {data, DescriptionDictionary, FeatureFlags} from "@actions/expressions";
 import {CompletionItem, CompletionItemKind} from "vscode-languageserver-types";
 import {complete, getExpressionInput} from "./complete.js";
 import {ContextProviderConfig} from "./context-providers/config.js";
@@ -68,12 +68,16 @@ describe("expressions", () => {
   describe("top-level auto-complete", () => {
     it("single region", async () => {
       const input = "run-name: ${{ | }}";
-      const result = await complete(...getPositionFromCursor(input));
+      const result = await complete(...getPositionFromCursor(input), {
+        contextProviderConfig,
+        featureFlags: new FeatureFlags({allowCaseFunction: true})
+      });
 
       expect(result.map(x => x.label)).toEqual([
         "github",
         "inputs",
         "vars",
+        "case",
         "contains",
         "endsWith",
         "format",
@@ -108,12 +112,16 @@ describe("expressions", () => {
 
     it("single region with existing input", async () => {
       const input = "run-name: ${{ g| }}";
-      const result = await complete(...getPositionFromCursor(input), {contextProviderConfig});
+      const result = await complete(...getPositionFromCursor(input), {
+        contextProviderConfig,
+        featureFlags: new FeatureFlags({allowCaseFunction: true})
+      });
 
       expect(result.map(x => x.label)).toEqual([
         "github",
         "inputs",
         "vars",
+        "case",
         "contains",
         "endsWith",
         "format",
@@ -126,12 +134,16 @@ describe("expressions", () => {
 
     it("single region with existing condition", async () => {
       const input = "run-name: ${{ g| == 'test' }}";
-      const result = await complete(...getPositionFromCursor(input), {contextProviderConfig});
+      const result = await complete(...getPositionFromCursor(input), {
+        contextProviderConfig,
+        featureFlags: new FeatureFlags({allowCaseFunction: true})
+      });
 
       expect(result.map(x => x.label)).toEqual([
         "github",
         "inputs",
         "vars",
+        "case",
         "contains",
         "endsWith",
         "format",
@@ -144,12 +156,16 @@ describe("expressions", () => {
 
     it("multiple regions with partial function", async () => {
       const input = "run-name: Run a ${{ inputs.test }} one-line script ${{ from|('test') == inputs.name }}";
-      const result = await complete(...getPositionFromCursor(input), {contextProviderConfig});
+      const result = await complete(...getPositionFromCursor(input), {
+        contextProviderConfig,
+        featureFlags: new FeatureFlags({allowCaseFunction: true})
+      });
 
       expect(result.map(x => x.label)).toEqual([
         "github",
         "inputs",
         "vars",
+        "case",
         "contains",
         "endsWith",
         "format",
@@ -162,12 +178,16 @@ describe("expressions", () => {
 
     it("multiple regions - first region", async () => {
       const input = "run-name: test-${{ git| == 1 }}-${{ github.event }}";
-      const result = await complete(...getPositionFromCursor(input), {contextProviderConfig});
+      const result = await complete(...getPositionFromCursor(input), {
+        contextProviderConfig,
+        featureFlags: new FeatureFlags({allowCaseFunction: true})
+      });
 
       expect(result.map(x => x.label)).toEqual([
         "github",
         "inputs",
         "vars",
+        "case",
         "contains",
         "endsWith",
         "format",
@@ -180,12 +200,16 @@ describe("expressions", () => {
 
     it("multiple regions", async () => {
       const input = "run-name: test-${{ github }}-${{ | }}";
-      const result = await complete(...getPositionFromCursor(input), {contextProviderConfig});
+      const result = await complete(...getPositionFromCursor(input), {
+        contextProviderConfig,
+        featureFlags: new FeatureFlags({allowCaseFunction: true})
+      });
 
       expect(result.map(x => x.label)).toEqual([
         "github",
         "inputs",
         "vars",
+        "case",
         "contains",
         "endsWith",
         "format",
@@ -1126,7 +1150,10 @@ jobs:
         run: echo hi
 `;
 
-      const result = await complete(...getPositionFromCursor(input), {contextProviderConfig});
+      const result = await complete(...getPositionFromCursor(input), {
+        contextProviderConfig,
+        featureFlags: new FeatureFlags({allowCaseFunction: true})
+      });
       expect(result.map(x => x.label)).toEqual([
         "env",
         "github",
@@ -1139,6 +1166,7 @@ jobs:
         "steps",
         "strategy",
         "vars",
+        "case",
         "contains",
         "endsWith",
         "format",

languageservice/src/complete.test.ts

@@ -6,6 +6,7 @@ import {getPositionFromCursor} from "./test-utils/cursor-position.js";
 import {TestLogger} from "./test-utils/logger.js";
 import {clearCache} from "./utils/workflow-cache.js";
 import {ValueProviderConfig, ValueProviderKind} from "./value-providers/config.js";
+import {FeatureFlags} from "@actions/expressions/features";
 
 registerLogger(new TestLogger());
 
@@ -465,7 +466,7 @@ jobs:
       ]);
 
       // One-of (scalar variant)
-      const concurrencyScalar = result.find(x => x.label === "concurrency" && x.detail === undefined);
+      const concurrencyScalar = result.find(x => x.label === "concurrency" && x.labelDetails === undefined);
       expect(concurrencyScalar?.textEdit?.newText).toEqual("concurrency: ");
     });
 
@@ -489,7 +490,7 @@ jobs:
       ]);
 
       // One-of (scalar variant)
-      const concurrencyScalar = result.find(x => x.label === "concurrency" && x.detail === undefined);
+      const concurrencyScalar = result.find(x => x.label === "concurrency" && x.labelDetails === undefined);
       expect(concurrencyScalar?.textEdit?.newText).toEqual("concurrency: ");
     });
   });
@@ -530,7 +531,7 @@ jobs:
     const result = await complete(...getPositionFromCursor(input));
 
     // Scalar variant inserts "types: "
-    const scalarVariant = result.find(x => x.label === "types" && x.detail === undefined);
+    const scalarVariant = result.find(x => x.label === "types" && x.labelDetails === undefined);
     expect(scalarVariant?.textEdit?.newText).toEqual("types: ");
   });
 
@@ -586,8 +587,8 @@ jobs:
 
     // Should have both check_run (scalar) and check_run with detail "full syntax"
     const checkRunVariants = result.filter(x => x.label === "check_run");
-    expect(checkRunVariants.some(x => x.detail === undefined)).toBe(true);
-    expect(checkRunVariants.some(x => x.detail === "full syntax")).toBe(true);
+    expect(checkRunVariants.some(x => x.labelDetails === undefined)).toBe(true);
+    expect(checkRunVariants.some(x => x.labelDetails?.description === "full syntax")).toBe(true);
   });
 
   it("shows all three variants for scalar+sequence+mapping one-of", async () => {
@@ -602,9 +603,9 @@ jobs:
     // Should have runs-on (scalar), runs-on with detail "list", and runs-on with detail "full syntax"
     const runsOnVariants = result.filter(x => x.label === "runs-on");
     expect(runsOnVariants.length).toBe(3);
-    expect(runsOnVariants.some(x => x.detail === undefined)).toBe(true);
-    expect(runsOnVariants.some(x => x.detail === "list")).toBe(true);
-    expect(runsOnVariants.some(x => x.detail === "full syntax")).toBe(true);
+    expect(runsOnVariants.some(x => x.labelDetails === undefined)).toBe(true);
+    expect(runsOnVariants.some(x => x.labelDetails?.description === "list")).toBe(true);
+    expect(runsOnVariants.some(x => x.labelDetails?.description === "full syntax")).toBe(true);
   });
 
   it("generates correct insertText for one-of variants in parent mode", async () => {
@@ -619,13 +620,17 @@ jobs:
     const runsOnVariants = result.filter(x => x.label === "runs-on");
 
     // Scalar: just key with colon and space
-    expect(runsOnVariants.find(x => x.detail === undefined)?.textEdit?.newText).toEqual("runs-on: ");
+    expect(runsOnVariants.find(x => x.labelDetails === undefined)?.textEdit?.newText).toEqual("runs-on: ");
 
     // Sequence: key with colon, newline, and list item
-    expect(runsOnVariants.find(x => x.detail === "list")?.textEdit?.newText).toEqual("runs-on:\n  - ");
+    expect(runsOnVariants.find(x => x.labelDetails?.description === "list")?.textEdit?.newText).toEqual(
+      "runs-on:\n  - "
+    );
 
     // Mapping: key with colon, newline, and indentation for nested keys
-    expect(runsOnVariants.find(x => x.detail === "full syntax")?.textEdit?.newText).toEqual("runs-on:\n  ");
+    expect(runsOnVariants.find(x => x.labelDetails?.description === "full syntax")?.textEdit?.newText).toEqual(
+      "runs-on:\n  "
+    );
   });
 
   it("generates correct insertText for one-of variants in parent mode", async () => {
@@ -654,11 +659,11 @@ jobs:
     const runsOnVariants = result.filter(x => x.label === "runs-on");
 
     // Scalar: no sortText needed (sorts naturally first)
-    expect(runsOnVariants.find(x => x.detail === undefined)?.sortText).toBeUndefined();
+    expect(runsOnVariants.find(x => x.labelDetails === undefined)?.sortText).toBeUndefined();
 
     // Sequence and mapping: sortText controls ordering
-    expect(runsOnVariants.find(x => x.detail === "list")?.sortText).toEqual("runs-on 1");
-    expect(runsOnVariants.find(x => x.detail === "full syntax")?.sortText).toEqual("runs-on 2");
+    expect(runsOnVariants.find(x => x.labelDetails?.description === "list")?.sortText).toEqual("runs-on 1");
+    expect(runsOnVariants.find(x => x.labelDetails?.description === "full syntax")?.sortText).toEqual("runs-on 2");
   });
 
   it("scalar event completion inserts inline without newline", async () => {
@@ -672,13 +677,13 @@ jobs:
     const push = result.find(x => x.label === "push");
     expect(push?.textEdit?.newText).toEqual("push");
 
-    const checkRun = result.find(x => x.label === "check_run" && x.detail === undefined);
+    const checkRun = result.find(x => x.label === "check_run" && x.labelDetails === undefined);
     expect(checkRun?.textEdit?.newText).toEqual("check_run");
 
     // Full syntax form should NOT be shown in Key mode - it requires a newline
     // which is confusing when typing inline. Users who want the mapping form
     // can use `on (full syntax)` at the parent level.
-    expect(result.find(x => x.label === "check_run" && x.detail === "full syntax")).toBeUndefined();
+    expect(result.find(x => x.label === "check_run" && x.labelDetails?.description === "full syntax")).toBeUndefined();
   });
 
   it("filters to sequence options when user has started a sequence", async () => {
@@ -719,16 +724,28 @@ jobs:
       expect(switchToList!.sortText).toEqual("zzz_switch_1");
       expect(switchToFull!.sortText).toEqual("zzz_switch_2");
 
-      // Escape hatches should have textEdit that restructures the YAML
+      // Escape hatches should have textEdit at cursor position (for VS Code filtering compatibility)
       const listEdit = switchToList!.textEdit as TextEdit;
       const fullEdit = switchToFull!.textEdit as TextEdit;
 
-      expect(listEdit.newText).toEqual("runs-on:\n  - ");
-      expect(fullEdit.newText).toEqual("runs-on:\n  ");
+      // Main textEdit inserts newline and indented content at cursor position
+      expect(listEdit.newText).toEqual("\n  - ");
+      expect(fullEdit.newText).toEqual("\n  ");
 
-      // TextEdit range should cover from key start to cursor position
-      expect(listEdit.range.start).toEqual({line: 3, character: 4});
-      expect(fullEdit.range.start).toEqual({line: 3, character: 4});
+      // TextEdit range should be at cursor position (empty range)
+      expect(listEdit.range.start).toEqual({line: 3, character: 13});
+      expect(listEdit.range.end).toEqual({line: 3, character: 13});
+      expect(fullEdit.range.start).toEqual({line: 3, character: 13});
+      expect(fullEdit.range.end).toEqual({line: 3, character: 13});
+
+      // additionalTextEdits should clean up the key portion
+      expect(switchToList!.additionalTextEdits).toHaveLength(1);
+      expect(switchToList!.additionalTextEdits![0].range.start).toEqual({line: 3, character: 4});
+      expect(switchToList!.additionalTextEdits![0].range.end).toEqual({line: 3, character: 13});
+      expect(switchToList!.additionalTextEdits![0].newText).toEqual("runs-on:");
+
+      expect(switchToFull!.additionalTextEdits).toHaveLength(1);
+      expect(switchToFull!.additionalTextEdits![0].newText).toEqual("runs-on:");
     });
 
     it("permissions shows only switch to full syntax (no sequence form)", async () => {
@@ -820,9 +837,16 @@ jobs:
 
       const switchToList = result.find(x => x.label === "(switch to list)");
       const textEdit = switchToList!.textEdit as TextEdit;
+      const additionalEdits = switchToList!.additionalTextEdits!;
 
-      // Applying this edit to "runs-on: " should produce "runs-on:\n  - "
-      expect(textEdit.newText).toEqual("runs-on:\n  - ");
+      // Main textEdit inserts newline content at cursor
+      expect(textEdit.newText).toEqual("\n  - ");
+
+      // additionalTextEdits replaces "runs-on: " with "runs-on:"
+      expect(additionalEdits).toHaveLength(1);
+      expect(additionalEdits[0].newText).toEqual("runs-on:");
+
+      // Combined result when applied: "runs-on:\n  - "
     });
   });
 
@@ -872,4 +896,32 @@ jobs:
       expect(result.some(x => x.label === "macos-latest")).toBe(true);
     });
   });
+
+  describe("expression completions", () => {
+    it("include case function when enabled", async () => {
+      const input = "on: push\njobs:\n  build:\n    runs-on: ${{ c|";
+      const result = await complete(...getPositionFromCursor(input), {
+        featureFlags: new FeatureFlags({allowCaseFunction: true})
+      });
+
+      expect(result).not.toBeUndefined();
+      // Expression completions starting with 'c': case, contains
+      const labels = result.map(x => x.label);
+      expect(labels).toContain("case");
+      expect(labels).toContain("contains");
+    });
+
+    it("exclude case function when disabled", async () => {
+      const input = "on: push\njobs:\n  build:\n    runs-on: ${{ c|";
+      const result = await complete(...getPositionFromCursor(input), {
+        featureFlags: new FeatureFlags({allowCaseFunction: false})
+      });
+
+      expect(result).not.toBeUndefined();
+      // Expression completions starting with 'c': contains
+      const labels = result.map(x => x.label);
+      expect(labels).not.toContain("case");
+      expect(labels).toContain("contains");
+    });
+  });
 });

languageservice/src/complete.ts

@@ -1,9 +1,11 @@
-import {complete as completeExpression, DescriptionDictionary} from "@actions/expressions";
+import {complete as completeExpression, DescriptionDictionary, FeatureFlags} from "@actions/expressions";
 import {CompletionItem as ExpressionCompletionItem} from "@actions/expressions/completion";
 import {isBasicExpression, isSequence, isString} from "@actions/workflow-parser";
+import {getActionSchema} from "@actions/workflow-parser/actions/action-schema";
 import {ErrorPolicy} from "@actions/workflow-parser/model/convert";
 import {DefinitionType} from "@actions/workflow-parser/templates/schema/definition-type";
 import {OneOfDefinition} from "@actions/workflow-parser/templates/schema/one-of-definition";
+import {TemplateSchema} from "@actions/workflow-parser/templates/schema/template-schema";
 import {OPEN_EXPRESSION} from "@actions/workflow-parser/templates/template-constants";
 import {TemplateToken} from "@actions/workflow-parser/templates/tokens/index";
 import {MappingToken} from "@actions/workflow-parser/templates/tokens/mapping-token";
@@ -14,17 +16,25 @@ import {FileProvider} from "@actions/workflow-parser/workflows/file-provider";
 import {getWorkflowSchema} from "@actions/workflow-parser/workflows/workflow-schema";
 import {Position, TextDocument} from "vscode-languageserver-textdocument";
 import {CompletionItem, CompletionItemKind, CompletionItemTag, Range, TextEdit} from "vscode-languageserver-types";
+import {filterActionRunsCompletions, getActionScaffoldingSnippets} from "./complete-action.js";
 import {ContextProviderConfig} from "./context-providers/config.js";
-import {getContext, Mode} from "./context-providers/default.js";
+import {getActionExpressionContext, getWorkflowExpressionContext, Mode} from "./context-providers/default.js";
+import {ActionContext, getActionContext} from "./context/action-context.js";
 import {getWorkflowContext, WorkflowContext} from "./context/workflow-context.js";
 import {validatorFunctions} from "./expression-validation/functions.js";
 import {error} from "./log.js";
+import {detectDocumentType} from "./utils/document-type.js";
 import {isPotentiallyExpression} from "./utils/expression-detection.js";
 import {findToken} from "./utils/find-token.js";
 import {guessIndentation} from "./utils/indentation-guesser.js";
 import {mapRange} from "./utils/range.js";
 import {isPlaceholder, transform} from "./utils/transform.js";
-import {fetchOrConvertWorkflowTemplate, fetchOrParseWorkflow} from "./utils/workflow-cache.js";
+import {
+  getOrConvertActionTemplate,
+  getOrConvertWorkflowTemplate,
+  getOrParseAction,
+  getOrParseWorkflow
+} from "./utils/workflow-cache.js";
 import {Value, ValueProviderConfig} from "./value-providers/config.js";
 import {defaultValueProviders} from "./value-providers/default.js";
 import {DefinitionValueMode, definitionValues, TokenStructure} from "./value-providers/definition.js";
@@ -45,6 +55,7 @@ export type CompletionConfig = {
   valueProviderConfig?: ValueProviderConfig;
   contextProviderConfig?: ContextProviderConfig;
   fileProvider?: FileProvider;
+  featureFlags?: FeatureFlags;
 };
 
 export async function complete(
@@ -68,47 +79,91 @@ export async function complete(
     content: newDoc.getText()
   };
 
-  const parsedWorkflow = fetchOrParseWorkflow(file, textDocument.uri, true);
-  if (!parsedWorkflow.value) {
+  // Determine document type - unknown defaults to workflow (backwards compatibility)
+  const isAction = detectDocumentType(textDocument.uri) === "action";
+
+  // Parse the document
+  const parsedTemplate = isAction
+    ? getOrParseAction(file, textDocument.uri, true)
+    : getOrParseWorkflow(file, textDocument.uri, true);
+  if (!parsedTemplate.value) {
     return [];
   }
 
-  const template = await fetchOrConvertWorkflowTemplate(
-    parsedWorkflow.context,
-    parsedWorkflow.value,
-    textDocument.uri,
-    config,
-    {
-      fetchReusableWorkflowDepth: config?.fileProvider ? 1 : 0,
-      errorPolicy: ErrorPolicy.TryConversion
-    }
-  );
+  const schema = isAction ? getActionSchema() : getWorkflowSchema();
+  const {token, keyToken, parent, path} = findToken(newPos, parsedTemplate.value);
 
-  const {token, keyToken, parent, path} = findToken(newPos, parsedWorkflow.value);
-  const workflowContext = getWorkflowContext(textDocument.uri, template, path);
+  // Build context for position-aware completions (e.g., steps.*, needs.*, inputs.*)
+  let workflowContext: WorkflowContext | undefined;
+  let actionContext: ActionContext | undefined;
+  if (isAction) {
+    const actionTemplate = getOrConvertActionTemplate(
+      parsedTemplate.context,
+      parsedTemplate.value,
+      textDocument.uri,
+      {errorPolicy: ErrorPolicy.TryConversion},
+      true
+    );
+    actionContext = getActionContext(textDocument.uri, actionTemplate, path);
+  } else {
+    const workflowTemplate = await getOrConvertWorkflowTemplate(
+      parsedTemplate.context,
+      parsedTemplate.value,
+      textDocument.uri,
+      config,
+      {
+        fetchReusableWorkflowDepth: config?.fileProvider ? 1 : 0,
+        errorPolicy: ErrorPolicy.TryConversion
+      },
+      true
+    );
+    workflowContext = workflowTemplate ? getWorkflowContext(textDocument.uri, workflowTemplate, path) : undefined;
+  }
 
-  // If we are inside an expression, take a different code-path. The workflow parser does not correctly create
-  // expression nodes for invalid expressions and during editing expressions are invalid most of the time.
-  if (token) {
-    if (isBasicExpression(token) || isPotentiallyExpression(token)) {
-      const allowedContext = token.definitionInfo?.allowedContext || [];
-      const context = await getContext(allowedContext, config?.contextProviderConfig, workflowContext, Mode.Completion);
+  // Expression completions
+  if (token && (isBasicExpression(token) || isPotentiallyExpression(token))) {
+    const allowedContext = token.definitionInfo?.allowedContext || [];
+    const context = isAction
+      ? getActionExpressionContext(allowedContext, config?.contextProviderConfig, actionContext, Mode.Completion)
+      : await getWorkflowExpressionContext(
+          allowedContext,
+          config?.contextProviderConfig,
+          workflowContext,
+          Mode.Completion
+        );
 
-      return getExpressionCompletionItems(token, context, newPos);
-    }
+    return getExpressionCompletionItems(token, context, newPos, config?.featureFlags);
   }
 
   const indentation = guessIndentation(newDoc, 2, true); // Use 2 spaces as default and most common for YAML
   const indentString = " ".repeat(indentation.tabSize);
 
-  const values = await getValues(token, keyToken, parent, config?.valueProviderConfig, workflowContext, indentString);
+  // YAML key/value completions
+  let values = await getValues(
+    token,
+    keyToken,
+    parent,
+    config?.valueProviderConfig,
+    workflowContext,
+    indentString,
+    schema
+  );
 
-  // Add escape hatch completions when completing an empty scalar value for a one-of field.
-  // These provide a way out of "dead end" situations where no scalar completions exist
-  // but alternative structural forms (list, mapping) are available.
-  const escapeHatches = getEscapeHatchCompletions(token, keyToken, indentString, newPos);
+  // Filter action.yml `runs:` completions based on `using:` value
+  if (isAction && parsedTemplate.value) {
+    values = filterActionRunsCompletions(values, path, parsedTemplate.value);
+  }
+
+  // Offer "(switch to list)" / "(switch to mapping)" when the schema allows alternative forms
+  const escapeHatches = getEscapeHatchCompletions(token, keyToken, indentString, newPos, schema);
   values.push(...escapeHatches);
 
+  // Get action scaffolding snippets if applicable
+  let actionSnippets: CompletionItem[] = [];
+  if (isAction && config?.featureFlags?.isEnabled("actionScaffoldingSnippets")) {
+    actionSnippets = getActionScaffoldingSnippets(parsedTemplate.value, path, position);
+  }
+
   // Figure out what text to replace when the user picks a completion.
   // For example, if they typed `runs-|` and pick `runs-on`, we need to replace `runs-`.
   let replaceRange: Range | undefined;
@@ -136,7 +191,8 @@ export async function complete(
     }
   }
 
-  return values.map(value => {
+  // Convert values to LSP CompletionItems
+  const completionItems = values.map(value => {
     const newText = value.insertText || value.label;
 
     // Escape hatches provide their own textEdit to restructure the YAML
@@ -149,9 +205,15 @@ export async function complete(
       textEdit = TextEdit.insert(position, newText);
     }
 
+    // Convert additionalTextEdits if present
+    let additionalTextEdits: TextEdit[] | undefined;
+    if (value.additionalTextEdits) {
+      additionalTextEdits = value.additionalTextEdits.map(edit => TextEdit.replace(edit.range, edit.newText));
+    }
+
     const item: CompletionItem = {
       label: value.label,
-      detail: value.detail,
+      labelDetails: value.labelDetail ? {description: value.labelDetail} : undefined,
       filterText: value.filterText,
       sortText: value.sortText,
       documentation: value.description && {
@@ -159,11 +221,15 @@ export async function complete(
         value: value.description
       },
       tags: value.deprecated ? [CompletionItemTag.Deprecated] : undefined,
-      textEdit
+      textEdit,
+      additionalTextEdits
     };
 
     return item;
   });
+
+  // Add action scaffolding snippets if available
+  return [...completionItems, ...actionSnippets];
 }
 
 /**
@@ -182,8 +248,9 @@ async function getValues(
   keyToken: TemplateToken | null,
   parent: TemplateToken | null,
   valueProviderConfig: ValueProviderConfig | undefined,
-  workflowContext: WorkflowContext,
-  indentation: string
+  workflowContext: WorkflowContext | undefined,
+  indentation: string,
+  schema: TemplateSchema
 ): Promise<Value[]> {
   if (!parent) {
     return [];
@@ -194,20 +261,23 @@ async function getValues(
   // Use the value providers from the parent if the current key is null
   const valueProviderToken = keyToken || parent;
 
-  const customValueProvider =
-    valueProviderToken?.definition?.key && valueProviderConfig?.[valueProviderToken.definition.key];
-  if (customValueProvider) {
-    const customValues = await customValueProvider.get(workflowContext, existingValues);
-    if (customValues) {
-      return filterAndSortCompletionOptions(customValues, existingValues);
+  // Value providers require workflow context - only use them for workflows
+  if (workflowContext) {
+    const customValueProvider =
+      valueProviderToken?.definition?.key && valueProviderConfig?.[valueProviderToken.definition.key];
+    if (customValueProvider) {
+      const customValues = await customValueProvider.get(workflowContext, existingValues);
+      if (customValues) {
+        return filterAndSortCompletionOptions(customValues, existingValues);
+      }
     }
-  }
 
-  const defaultValueProvider =
-    valueProviderToken?.definition?.key && defaultValueProviders[valueProviderToken.definition.key];
-  if (defaultValueProvider) {
-    const values = await defaultValueProvider.get(workflowContext, existingValues);
-    return filterAndSortCompletionOptions(values, existingValues);
+    const defaultValueProvider =
+      valueProviderToken?.definition?.key && defaultValueProviders[valueProviderToken.definition.key];
+    if (defaultValueProvider) {
+      const values = await defaultValueProvider.get(workflowContext, existingValues);
+      return filterAndSortCompletionOptions(values, existingValues);
+    }
   }
 
   // Use the definition if there are no value providers
@@ -224,7 +294,8 @@ async function getValues(
     def,
     indentation,
     keyToken ? DefinitionValueMode.Key : DefinitionValueMode.Parent,
-    tokenStructure
+    tokenStructure,
+    schema
   );
   return filterAndSortCompletionOptions(values, existingValues);
 }
@@ -284,7 +355,8 @@ function getEscapeHatchCompletions(
   token: TemplateToken | null,
   keyToken: TemplateToken | null,
   indentation: string,
-  position: Position
+  position: Position,
+  schema: TemplateSchema
 ): Value[] {
   // Only show escape hatches when value is empty
   const tokenStructure = getTokenStructure(token);
@@ -299,7 +371,6 @@ function getEscapeHatchCompletions(
 
   // Determine which structural types are available from the definition
   const def = keyToken.definition;
-  const schema = getWorkflowSchema();
   const buckets = {
     sequence: false,
     mapping: false
@@ -340,9 +411,19 @@ function getEscapeHatchCompletions(
     return [];
   }
 
-  // Calculate the range from key start to current position
-  // This covers "key: " so we can replace it with "key:\n  - " or "key:\n  "
-  const editRange = {
+  // For VS Code compatibility, we use a cursor-position range for the main textEdit
+  // and additionalTextEdits to clean up the key portion. This prevents VS Code from
+  // filtering out escape hatches based on the key text (e.g., "runs-on: ").
+  //
+  // Main textEdit: insert at cursor position (newline + indented content)
+  // additionalTextEdits: replace "key: " with "key:" (removes trailing space)
+  const cursorRange = {
+    start: {line: position.line, character: position.character},
+    end: {line: position.line, character: position.character}
+  };
+
+  // Range from key start to cursor - used to replace "key: " with "key:" in additionalTextEdits
+  const keyToCursorRange = {
     start: {line: keyRange.start.line - 1, character: keyRange.start.column - 1},
     end: {line: position.line, character: position.character}
   };
@@ -351,11 +432,16 @@ function getEscapeHatchCompletions(
     results.push({
       label: "(switch to list)",
       sortText: "zzz_switch_1",
-      filterText: keyName, // Allow filtering by key name
       textEdit: {
-        range: editRange,
-        newText: `${keyName}:\n${indentation}- `
-      }
+        range: cursorRange,
+        newText: `\n${indentation}- `
+      },
+      additionalTextEdits: [
+        {
+          range: keyToCursorRange,
+          newText: `${keyName}:`
+        }
+      ]
     });
   }
 
@@ -363,11 +449,16 @@ function getEscapeHatchCompletions(
     results.push({
       label: "(switch to mapping)",
       sortText: "zzz_switch_2",
-      filterText: keyName, // Allow filtering by key name
       textEdit: {
-        range: editRange,
-        newText: `${keyName}:\n${indentation}`
-      }
+        range: cursorRange,
+        newText: `\n${indentation}`
+      },
+      additionalTextEdits: [
+        {
+          range: keyToCursorRange,
+          newText: `${keyName}:`
+        }
+      ]
     });
   }
 
@@ -430,7 +521,8 @@ export function getExistingValues(token: TemplateToken | null, parent: TemplateT
 function getExpressionCompletionItems(
   token: TemplateToken,
   context: DescriptionDictionary,
-  pos: Position
+  pos: Position,
+  featureFlags?: FeatureFlags
 ): CompletionItem[] {
   if (!token.range) {
     return [];
@@ -449,7 +541,7 @@ function getExpressionCompletionItems(
   const expressionInput = (getExpressionInput(currentInput, cursorOffset) || "").trim();
 
   try {
-    return completeExpression(expressionInput, context, [], validatorFunctions).map(item =>
+    return completeExpression(expressionInput, context, [], validatorFunctions, featureFlags).map(item =>
       mapExpressionCompletionItem(item, currentInput[cursorOffset])
     );
   } catch (e) {

languageservice/src/context-providers/default.test.ts

@@ -1,8 +1,8 @@
 import {DescriptionDictionary} from "@actions/expressions";
 import {WorkflowContext} from "../context/workflow-context.js";
-import {getContext, Mode} from "./default.js";
+import {getWorkflowExpressionContext, Mode} from "./default.js";
 
-describe("getContext", () => {
+describe("getWorkflowExpressionContext", () => {
   const emptyWorkflowContext: WorkflowContext = {
     uri: "test.yaml",
     template: undefined
@@ -10,7 +10,7 @@ describe("getContext", () => {
 
   describe("when no contextProviderConfig is provided", () => {
     it("should mark secrets context as incomplete", async () => {
-      const result = await getContext(["secrets"], undefined, emptyWorkflowContext, Mode.Validation);
+      const result = await getWorkflowExpressionContext(["secrets"], undefined, emptyWorkflowContext, Mode.Validation);
 
       const secretsContext = result.get("secrets") as DescriptionDictionary;
       expect(secretsContext).toBeDefined();
@@ -18,7 +18,7 @@ describe("getContext", () => {
     });
 
     it("should mark vars context as incomplete", async () => {
-      const result = await getContext(["vars"], undefined, emptyWorkflowContext, Mode.Validation);
+      const result = await getWorkflowExpressionContext(["vars"], undefined, emptyWorkflowContext, Mode.Validation);
 
       const varsContext = result.get("vars") as DescriptionDictionary;
       expect(varsContext).toBeDefined();
@@ -26,7 +26,12 @@ describe("getContext", () => {
     });
 
     it("should not mark other contexts as incomplete", async () => {
-      const result = await getContext(["env", "github"], undefined, emptyWorkflowContext, Mode.Validation);
+      const result = await getWorkflowExpressionContext(
+        ["env", "github"],
+        undefined,
+        emptyWorkflowContext,
+        Mode.Validation
+      );
 
       const envContext = result.get("env") as DescriptionDictionary;
       const githubContext = result.get("github") as DescriptionDictionary;
@@ -48,7 +53,7 @@ describe("getContext", () => {
         getContext: () => Promise.resolve(providedContext)
       };
 
-      const result = await getContext(["secrets"], config, emptyWorkflowContext, Mode.Validation);
+      const result = await getWorkflowExpressionContext(["secrets"], config, emptyWorkflowContext, Mode.Validation);
 
       const secretsContext = result.get("secrets");
       expect(secretsContext).toBe(providedContext);
@@ -63,7 +68,7 @@ describe("getContext", () => {
         getContext: () => Promise.resolve(providedContext)
       };
 
-      const result = await getContext(["vars"], config, emptyWorkflowContext, Mode.Validation);
+      const result = await getWorkflowExpressionContext(["vars"], config, emptyWorkflowContext, Mode.Validation);
 
       const varsContext = result.get("vars");
       expect(varsContext).toBe(providedContext);
@@ -77,7 +82,7 @@ describe("getContext", () => {
         getContext: () => Promise.resolve(undefined)
       };
 
-      const result = await getContext(["secrets"], config, emptyWorkflowContext, Mode.Validation);
+      const result = await getWorkflowExpressionContext(["secrets"], config, emptyWorkflowContext, Mode.Validation);
 
       const secretsContext = result.get("secrets") as DescriptionDictionary;
       expect(secretsContext.complete).toBe(false);
@@ -88,7 +93,7 @@ describe("getContext", () => {
         getContext: () => Promise.resolve(undefined)
       };
 
-      const result = await getContext(["vars"], config, emptyWorkflowContext, Mode.Validation);
+      const result = await getWorkflowExpressionContext(["vars"], config, emptyWorkflowContext, Mode.Validation);
 
       const varsContext = result.get("vars") as DescriptionDictionary;
       expect(varsContext.complete).toBe(false);

languageservice/src/context-providers/default.ts

@@ -1,5 +1,6 @@
 import {data, DescriptionDictionary} from "@actions/expressions";
 import {Kind} from "@actions/expressions/data/expressiondata";
+import {ActionContext, getActionInputs, getActionStepIdsBefore} from "../context/action-context.js";
 import {WorkflowContext} from "../context/workflow-context.js";
 import {ContextProviderConfig} from "./config.js";
 import {getDescription, RootContext} from "./descriptions.js";
@@ -12,7 +13,6 @@ import {getMatrixContext} from "./matrix.js";
 import {getNeedsContext} from "./needs.js";
 import {getSecretsContext} from "./secrets.js";
 import {getStepsContext} from "./steps.js";
-import {getStrategyContext} from "./strategy.js";
 
 // ContextValue is the type of the value returned by a context provider
 // Null indicates that the context provider doesn't have any value to provide
@@ -24,10 +24,13 @@ export enum Mode {
   Hover
 }
 
-export async function getContext(
+/**
+ * Build expression context for workflow files (e.g., github.*, steps.*, needs.*)
+ */
+export async function getWorkflowExpressionContext(
   names: string[],
   config: ContextProviderConfig | undefined,
-  workflowContext: WorkflowContext,
+  workflowContext: WorkflowContext | undefined,
   mode: Mode
 ): Promise<DescriptionDictionary> {
   const context = new DescriptionDictionary();
@@ -41,7 +44,9 @@ export async function getContext(
       continue;
     }
 
-    const remoteValue = await config?.getContext(contextName, value, workflowContext, mode);
+    const remoteValue = workflowContext
+      ? await config?.getContext(contextName, value, workflowContext, mode)
+      : undefined;
     if (remoteValue) {
       value = remoteValue;
     } else if (contextName === "secrets" || contextName === "vars") {
@@ -57,61 +62,198 @@ export async function getContext(
   return context;
 }
 
-function getDefaultContext(name: string, workflowContext: WorkflowContext, mode: Mode): ContextValue | undefined {
+/**
+ * Maps context name to its provider (e.g., "steps" -> getStepsContext)
+ */
+function getDefaultContext(
+  name: string,
+  workflowContext: WorkflowContext | undefined,
+  mode: Mode
+): ContextValue | undefined {
   switch (name) {
     case "env":
-      return getEnvContext(workflowContext);
+      return workflowContext ? getEnvContext(workflowContext) : new DescriptionDictionary();
 
     case "github":
       return getGithubContext(workflowContext, mode);
 
     case "inputs":
-      return getInputsContext(workflowContext);
+      return workflowContext ? getInputsContext(workflowContext) : new DescriptionDictionary();
 
     case "reusableWorkflowJob":
     case "job":
-      return getJobContext(workflowContext);
+      return workflowContext ? getJobContext(workflowContext) : new DescriptionDictionary();
 
     case "jobs":
-      return getJobsContext(workflowContext);
+      return workflowContext ? getJobsContext(workflowContext) : new DescriptionDictionary();
 
     case "matrix":
-      return getMatrixContext(workflowContext, mode);
+      return workflowContext ? getMatrixContext(workflowContext, mode) : new DescriptionDictionary();
 
     case "needs":
-      return getNeedsContext(workflowContext);
+      return workflowContext ? getNeedsContext(workflowContext) : new DescriptionDictionary();
 
     case "runner":
-      return objectToDictionary({
-        arch: "X64",
-        debug: "1",
-        environment: "github-hosted",
-        name: "GitHub Actions 2",
-        os: "Linux",
-        temp: "/home/runner/work/_temp",
-        tool_cache: "/opt/hostedtoolcache",
-        workspace: "/home/runner/work/repo"
-      });
+      return getRunnerContext();
 
     case "secrets":
-      return getSecretsContext(workflowContext, mode);
+      return workflowContext ? getSecretsContext(workflowContext, mode) : new DescriptionDictionary();
 
     case "steps":
-      return getStepsContext(workflowContext);
+      return workflowContext ? getStepsContext(workflowContext) : new DescriptionDictionary();
 
     case "strategy":
-      return getStrategyContext(workflowContext);
+      return getStrategyContext();
   }
 
   return undefined;
 }
 
-function objectToDictionary(object: {[key: string]: string}): DescriptionDictionary {
-  const dictionary = new DescriptionDictionary();
+/**
+ * Returns the strategy context with default values (fail-fast, job-index, etc.)
+ */
+function getStrategyContext(): DescriptionDictionary {
+  // https://docs.github.com/en/actions/learn-github-actions/contexts#strategy-context
+  return new DescriptionDictionary(
+    {key: "fail-fast", value: new data.BooleanData(true), description: getDescription("strategy", "fail-fast")},
+    {key: "job-index", value: new data.NumberData(0), description: getDescription("strategy", "job-index")},
+    {key: "job-total", value: new data.NumberData(1), description: getDescription("strategy", "job-total")},
+    {key: "max-parallel", value: new data.NumberData(1), description: getDescription("strategy", "max-parallel")}
+  );
+}
 
-  for (const key in object) {
-    dictionary.add(key, new data.StringData(object[key]));
+/**
+ * Returns the runner context with environment info (arch, os, temp, workspace, etc.)
+ */
+function getRunnerContext(): DescriptionDictionary {
+  // https://docs.github.com/en/actions/learn-github-actions/contexts#runner-context
+  return new DescriptionDictionary(
+    {key: "arch", value: new data.StringData("X64"), description: getDescription("runner", "arch")},
+    {key: "debug", value: new data.StringData("1"), description: getDescription("runner", "debug")},
+    {
+      key: "environment",
+      value: new data.StringData("github-hosted"),
+      description: getDescription("runner", "environment")
+    },
+    {key: "name", value: new data.StringData("GitHub Actions 2"), description: getDescription("runner", "name")},
+    {key: "os", value: new data.StringData("Linux"), description: getDescription("runner", "os")},
+    {key: "temp", value: new data.StringData("/home/runner/work/_temp"), description: getDescription("runner", "temp")},
+    {
+      key: "tool_cache",
+      value: new data.StringData("/opt/hostedtoolcache"),
+      description: getDescription("runner", "tool_cache")
+    },
+    {
+      key: "workspace",
+      value: new data.StringData("/home/runner/work/repo"),
+      description: getDescription("runner", "workspace")
+    }
+  );
+}
+
+/**
+ * Get context for expression completion in action.yml files.
+ * Actions have a more limited set of contexts available compared to workflows.
+ */
+export function getActionExpressionContext(
+  names: string[],
+  config: ContextProviderConfig | undefined,
+  actionContext: ActionContext | undefined,
+  mode: Mode
+): DescriptionDictionary {
+  const context = new DescriptionDictionary();
+
+  for (const contextName of names) {
+    const value = getDefaultActionContext(contextName, actionContext, mode);
+    if (value) {
+      context.add(contextName, value, getDescription(RootContext, contextName));
+    }
   }
 
-  return dictionary;
+  return context;
+}
+
+/**
+ * Maps context name to its provider for action.yml files (e.g., "inputs" -> getActionInputsContext)
+ */
+function getDefaultActionContext(
+  name: string,
+  actionContext: ActionContext | undefined,
+  mode: Mode
+): ContextValue | undefined {
+  switch (name) {
+    case "inputs":
+      // Return empty dictionary if no context - still allows completion, just without specific input names
+      return actionContext ? getActionInputsContext(actionContext) : new DescriptionDictionary();
+
+    case "steps":
+      // Return empty dictionary if no context - still allows completion, just without specific step IDs
+      return actionContext ? getActionStepsContext(actionContext) : new DescriptionDictionary();
+
+    case "github":
+      // Use the same github context but without workflow-specific event info
+      // Actions inherit the event context from the calling workflow at runtime
+      return getGithubContext(undefined, mode);
+
+    case "runner":
+      return getRunnerContext();
+
+    case "env":
+      // Actions can access env but we don't have runtime values
+      return new DescriptionDictionary();
+
+    case "job": {
+      // https://docs.github.com/en/actions/learn-github-actions/contexts#job-context
+      const jobContext = new DescriptionDictionary();
+      jobContext.add("status", new data.StringData(""), getDescription("job", "status"));
+      jobContext.add("check_run_id", new data.StringData(""), getDescription("job", "check_run_id"));
+      const containerContext = new DescriptionDictionary();
+      containerContext.add("id", new data.StringData(""), getDescription("job", "container.id"));
+      containerContext.add("network", new data.StringData(""), getDescription("job", "container.network"));
+      jobContext.add("container", containerContext, getDescription("job", "container"));
+      jobContext.add("services", new DescriptionDictionary(), getDescription("job", "services"));
+      return jobContext;
+    }
+
+    case "strategy":
+      return getStrategyContext();
+
+    case "matrix":
+      // Actions can access matrix context at runtime
+      return new DescriptionDictionary();
+  }
+
+  return undefined;
+}
+
+/**
+ * Get inputs context for action files based on defined inputs
+ */
+function getActionInputsContext(actionContext: ActionContext): DescriptionDictionary {
+  const dict = new DescriptionDictionary();
+  const inputs = getActionInputs(actionContext.template);
+
+  for (const input of inputs) {
+    dict.add(input.id, new data.StringData(""), input.description || "");
+  }
+
+  return dict;
+}
+
+/**
+ * Get steps context for composite action files based on step IDs
+ */
+function getActionStepsContext(actionContext: ActionContext): DescriptionDictionary {
+  const dict = new DescriptionDictionary();
+  const stepIds = getActionStepIdsBefore(actionContext);
+
+  for (const stepId of stepIds) {
+    const stepDict = new DescriptionDictionary();
+    stepDict.add("outputs", new DescriptionDictionary(), getDescription("steps", "outputs"));
+    stepDict.add("outcome", new data.StringData("success"), getDescription("steps", "outcome"));
+    stepDict.add("conclusion", new data.StringData("success"), getDescription("steps", "conclusion"));
+    dict.add(stepId, stepDict, `Step: ${stepId}`);
+  }
+
+  return dict;
 }

languageservice/src/context-providers/descriptions.json

@@ -198,6 +198,35 @@
       "description": "The default working directory on the runner for steps, and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action."
     }
   },
+  "job": {
+    "container": {
+      "description": "Information about the job's container. For more information about containers, see \"[Running jobs in a container](https://docs.github.com/actions/using-jobs/running-jobs-in-a-container).\""
+    },
+    "container.id": {
+      "description": "The ID of the container."
+    },
+    "container.network": {
+      "description": "The ID of the container network. The runner creates the network used by all containers in a job."
+    },
+    "services": {
+      "description": "The service containers created for a job. For more information about service containers, see \"[Using service containers](https://docs.github.com/actions/using-containerized-services/about-service-containers).\""
+    },
+    "services.<service_id>.id": {
+      "description": "The ID of the service container."
+    },
+    "services.<service_id>.network": {
+      "description": "The ID of the service container network. The runner creates the network used by all containers in a job."
+    },
+    "services.<service_id>.ports": {
+      "description": "The exposed ports of the service container."
+    },
+    "status": {
+      "description": "The current status of the job. Possible values are `success`, `failure`, or `cancelled`."
+    },
+    "check_run_id": {
+      "description": "The unique identifier of the check run for this job."
+    }
+  },
   "secrets": {
     "GITHUB_TOKEN": {
       "description": "Automatically created token for each workflow run. For more information, see \"[Automatic token authentication](https://docs.github.com/actions/security-guides/automatic-token-authentication).\""

languageservice/src/context-providers/github.ts

@@ -7,7 +7,10 @@ import {getDescription} from "./descriptions.js";
 import {getEventPayload, getSupportedEventTypes} from "./events/eventPayloads.js";
 import {getInputsContext} from "./inputs.js";
 
-export function getGithubContext(workflowContext: WorkflowContext, mode: Mode): DescriptionDictionary {
+/**
+ * Returns the github context with properties like actor, ref, sha, event, etc.
+ */
+export function getGithubContext(workflowContext: WorkflowContext | undefined, mode: Mode): DescriptionDictionary {
   // https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
   const keys = [
     "action",
@@ -73,7 +76,10 @@ export function getGithubContext(workflowContext: WorkflowContext, mode: Mode):
   );
 }
 
-function getEventContext(workflowContext: WorkflowContext, mode: Mode): ExpressionData {
+/**
+ * Builds the github.event context based on workflow trigger configuration.
+ */
+function getEventContext(workflowContext: WorkflowContext | undefined, mode: Mode): ExpressionData {
   const d = new DescriptionDictionary();
   const eventsConfig = workflowContext?.template?.events;
 

languageservice/src/context-providers/job.test.ts

@@ -0,0 +1,176 @@
+import {DescriptionDictionary, isDescriptionDictionary} from "@actions/expressions";
+import {MappingToken} from "@actions/workflow-parser/templates/tokens/mapping-token";
+import {SequenceToken} from "@actions/workflow-parser/templates/tokens/sequence-token";
+import {StringToken} from "@actions/workflow-parser/templates/tokens/string-token";
+import {WorkflowContext} from "../context/workflow-context.js";
+import {getJobContext} from "./job.js";
+
+function stringToToken(value: string): StringToken {
+  return new StringToken(undefined, undefined, value, undefined);
+}
+
+describe("job context", () => {
+  it("returns empty context when no job", () => {
+    const workflowContext = {} as WorkflowContext;
+    const context = getJobContext(workflowContext);
+
+    // When there's no job, context is empty
+    expect(context.pairs().length).toBe(0);
+  });
+
+  it("returns status and check_run_id when job has no container or services", () => {
+    const workflowContext = {job: {}} as WorkflowContext;
+    const context = getJobContext(workflowContext);
+
+    expect(context.get("status")).toBeDefined();
+    expect(context.get("check_run_id")).toBeDefined();
+    expect(context.get("container")).toBeUndefined();
+    expect(context.get("services")).toBeUndefined();
+  });
+
+  describe("container context", () => {
+    it("includes container with id and network when container is defined", () => {
+      const containerToken = new MappingToken(undefined, undefined, undefined);
+      containerToken.add(stringToToken("image"), stringToToken("node:18"));
+
+      const workflowContext = {
+        job: {container: containerToken}
+      } as unknown as WorkflowContext;
+
+      const context = getJobContext(workflowContext);
+      const container = context.get("container");
+
+      expect(container).toBeDefined();
+      if (!container) return;
+      expect(isDescriptionDictionary(container)).toBe(true);
+
+      const containerDict = container as DescriptionDictionary;
+      expect(containerDict.get("id")).toBeDefined();
+      expect(containerDict.get("network")).toBeDefined();
+      expect(containerDict.get("ports")).toBeUndefined(); // job container has no ports
+    });
+
+    it("container has descriptions", () => {
+      const containerToken = new MappingToken(undefined, undefined, undefined);
+      containerToken.add(stringToToken("image"), stringToToken("node:18"));
+
+      const workflowContext = {
+        job: {container: containerToken}
+      } as unknown as WorkflowContext;
+
+      const context = getJobContext(workflowContext);
+
+      const containerDescription = context.getDescription("container");
+      expect(containerDescription).toBeDefined();
+
+      const containerDict = context.get("container") as DescriptionDictionary;
+      expect(containerDict.getDescription("id")).toBeDefined();
+      expect(containerDict.getDescription("network")).toBeDefined();
+    });
+  });
+
+  describe("services context", () => {
+    it("includes services with id, network, and ports", () => {
+      const redisToken = new MappingToken(undefined, undefined, undefined);
+      redisToken.add(stringToToken("image"), stringToToken("redis:latest"));
+
+      const servicesToken = new MappingToken(undefined, undefined, undefined);
+      servicesToken.add(stringToToken("redis"), redisToken);
+
+      const workflowContext = {
+        job: {services: servicesToken}
+      } as unknown as WorkflowContext;
+
+      const context = getJobContext(workflowContext);
+      const services = context.get("services");
+
+      expect(services).toBeDefined();
+      if (!services) return;
+      expect(isDescriptionDictionary(services)).toBe(true);
+
+      const servicesDict = services as DescriptionDictionary;
+      const redis = servicesDict.get("redis");
+      expect(redis).toBeDefined();
+      if (!redis) return;
+      expect(isDescriptionDictionary(redis)).toBe(true);
+
+      const redisDict = redis as DescriptionDictionary;
+      expect(redisDict.get("id")).toBeDefined();
+      expect(redisDict.get("network")).toBeDefined();
+      expect(redisDict.get("ports")).toBeDefined(); // services have ports
+    });
+
+    it("parses service ports in host:container format", () => {
+      const portsSequence = new SequenceToken(undefined, undefined, undefined);
+      portsSequence.add(stringToToken("6379:6379"));
+      portsSequence.add(stringToToken("8080:80"));
+
+      const redisToken = new MappingToken(undefined, undefined, undefined);
+      redisToken.add(stringToToken("image"), stringToToken("redis:latest"));
+      redisToken.add(stringToToken("ports"), portsSequence);
+
+      const servicesToken = new MappingToken(undefined, undefined, undefined);
+      servicesToken.add(stringToToken("redis"), redisToken);
+
+      const workflowContext = {
+        job: {services: servicesToken}
+      } as unknown as WorkflowContext;
+
+      const context = getJobContext(workflowContext);
+      const services = context.get("services") as DescriptionDictionary;
+      const redis = services.get("redis") as DescriptionDictionary;
+      const ports = redis.get("ports") as DescriptionDictionary;
+
+      // Container ports should be the keys (second part of host:container)
+      expect(ports.get("6379")).toBeDefined();
+      expect(ports.get("80")).toBeDefined();
+    });
+
+    it("parses service ports in single port format", () => {
+      const portsSequence = new SequenceToken(undefined, undefined, undefined);
+      portsSequence.add(stringToToken("6379"));
+
+      const redisToken = new MappingToken(undefined, undefined, undefined);
+      redisToken.add(stringToToken("image"), stringToToken("redis:latest"));
+      redisToken.add(stringToToken("ports"), portsSequence);
+
+      const servicesToken = new MappingToken(undefined, undefined, undefined);
+      servicesToken.add(stringToToken("redis"), redisToken);
+
+      const workflowContext = {
+        job: {services: servicesToken}
+      } as unknown as WorkflowContext;
+
+      const context = getJobContext(workflowContext);
+      const services = context.get("services") as DescriptionDictionary;
+      const redis = services.get("redis") as DescriptionDictionary;
+      const ports = redis.get("ports") as DescriptionDictionary;
+
+      // Single port format uses the port as the key
+      expect(ports.get("6379")).toBeDefined();
+    });
+
+    it("services have descriptions", () => {
+      const redisToken = new MappingToken(undefined, undefined, undefined);
+      redisToken.add(stringToToken("image"), stringToToken("redis:latest"));
+
+      const servicesToken = new MappingToken(undefined, undefined, undefined);
+      servicesToken.add(stringToToken("redis"), redisToken);
+
+      const workflowContext = {
+        job: {services: servicesToken}
+      } as unknown as WorkflowContext;
+
+      const context = getJobContext(workflowContext);
+
+      const servicesDescription = context.getDescription("services");
+      expect(servicesDescription).toBeDefined();
+
+      const services = context.get("services") as DescriptionDictionary;
+      const redis = services.get("redis") as DescriptionDictionary;
+      expect(redis.getDescription("id")).toBeDefined();
+      expect(redis.getDescription("network")).toBeDefined();
+      expect(redis.getDescription("ports")).toBeDefined();
+    });
+  });
+});

languageservice/src/context-providers/job.ts

@@ -2,7 +2,11 @@ import {data, DescriptionDictionary} from "@actions/expressions";
 import {isMapping, isSequence} from "@actions/workflow-parser";
 import {MappingToken} from "@actions/workflow-parser/templates/tokens/mapping-token";
 import {WorkflowContext} from "../context/workflow-context.js";
+import {getDescription} from "./descriptions.js";
 
+/**
+ * Returns the job context with container, services, status, and check_run_id.
+ */
 export function getJobContext(workflowContext: WorkflowContext): DescriptionDictionary {
   // https://docs.github.com/en/actions/learn-github-actions/contexts#job-context
   const jobContext = new DescriptionDictionary();
@@ -15,7 +19,7 @@ export function getJobContext(workflowContext: WorkflowContext): DescriptionDict
   const jobContainer = job.container;
   if (jobContainer && isMapping(jobContainer)) {
     const containerContext = createContainerContext(jobContainer, false);
-    jobContext.add("container", containerContext);
+    jobContext.add("container", containerContext, getDescription("job", "container"));
   }
 
   // Services
@@ -29,42 +33,48 @@ export function getJobContext(workflowContext: WorkflowContext): DescriptionDict
       const serviceContext = createContainerContext(service.value, true);
       servicesContext.add(service.key.toString(), serviceContext);
     }
-    jobContext.add("services", servicesContext);
+    jobContext.add("services", servicesContext, getDescription("job", "services"));
   }
 
   // Status
-  jobContext.add("status", new data.Null());
+  jobContext.add("status", new data.StringData(""), getDescription("job", "status"));
 
   // Check run ID
-  jobContext.add("check_run_id", new data.Null());
+  jobContext.add("check_run_id", new data.StringData(""), getDescription("job", "check_run_id"));
 
   return jobContext;
 }
 
-function createContainerContext(container: MappingToken, isServices: boolean): data.Dictionary {
-  const containerContext = new data.Dictionary();
-  for (const {key, value} of container) {
-    if (isSequence(value)) {
-      // service ports are the only thing that is part of the job context
-      if (key.toString() !== "ports") {
-        continue;
-      }
-      const ports = new data.Dictionary();
-      for (const item of value) {
-        // We can determine the context mapping fully only if the port is defined
-        // as a mapping (i.e. <port1>:<port2>), single ports are assigned randomly
-        const portParts = item.toString().split(":");
-        if (isServices && portParts.length === 2) {
-          ports.add(portParts[1], new data.StringData(portParts[0]));
-        } else {
-          // If the port isn't a mapping, just use null
-          ports.add(portParts[0], new data.Null());
+function createContainerContext(container: MappingToken, isServices: boolean): DescriptionDictionary {
+  const containerContext = new DescriptionDictionary();
+
+  // id and network are always available
+  containerContext.add(
+    "id",
+    new data.StringData(""),
+    getDescription("job", isServices ? "services.<service_id>.id" : "container.id")
+  );
+  containerContext.add(
+    "network",
+    new data.StringData(""),
+    getDescription("job", isServices ? "services.<service_id>.network" : "container.network")
+  );
+
+  // ports are only available for service containers (not job container)
+  if (isServices) {
+    const ports = new DescriptionDictionary();
+    for (const {key, value} of container) {
+      if (key.toString() === "ports" && isSequence(value)) {
+        for (const item of value) {
+          const portParts = item.toString().split(":");
+          // The key is the container port (second part if host:container format)
+          const containerPort = portParts.length === 2 ? portParts[1] : portParts[0];
+          ports.add(containerPort, new data.StringData(""));
         }
       }
-      containerContext.add(key.toString(), ports);
     }
+    containerContext.add("ports", ports, getDescription("job", "services.<service_id>.ports"));
   }
-  containerContext.add("id", new data.Null());
-  containerContext.add("network", new data.Null());
+
   return containerContext;
 }

languageservice/src/context-providers/strategy.test.ts

@@ -1,126 +0,0 @@
-import {data} from "@actions/expressions";
-import {Job} from "@actions/workflow-parser/model/workflow-template";
-import {BooleanToken} from "@actions/workflow-parser/templates/tokens/boolean-token";
-import {MappingToken} from "@actions/workflow-parser/templates/tokens/mapping-token";
-import {NumberToken} from "@actions/workflow-parser/templates/tokens/number-token";
-import {StringToken} from "@actions/workflow-parser/templates/tokens/string-token";
-import {TemplateToken} from "@actions/workflow-parser/templates/tokens/template-token";
-import {WorkflowContext} from "../context/workflow-context.js";
-import {getStrategyContext} from "./strategy.js";
-
-function stringToToken(value: string) {
-  return new StringToken(undefined, undefined, value, undefined);
-}
-
-function boolToToken(value: boolean) {
-  return new BooleanToken(undefined, undefined, value, undefined);
-}
-
-function numberToToken(value: number) {
-  return new NumberToken(undefined, undefined, value, undefined);
-}
-
-function contextFromStrategy(strategy?: TemplateToken) {
-  return {
-    job: {
-      strategy: strategy
-    }
-  } as WorkflowContext;
-}
-
-describe("strategy context", () => {
-  describe("no strategy defined", () => {
-    it("returns defaults when job is undefined", () => {
-      const workflowContext = {} as WorkflowContext;
-
-      const context = getStrategyContext(workflowContext);
-
-      expect(context.get("fail-fast")).toEqual(new data.BooleanData(true));
-      expect(context.get("job-index")).toEqual(new data.NumberData(0));
-      expect(context.get("job-total")).toEqual(new data.NumberData(1));
-      expect(context.get("max-parallel")).toEqual(new data.NumberData(1));
-    });
-
-    it("returns defaults when strategy is undefined", () => {
-      const job = {} as Job;
-      const workflowContext = {job} as WorkflowContext;
-
-      const context = getStrategyContext(workflowContext);
-
-      expect(context.get("fail-fast")).toEqual(new data.BooleanData(true));
-      expect(context.get("job-index")).toEqual(new data.NumberData(0));
-      expect(context.get("job-total")).toEqual(new data.NumberData(1));
-      expect(context.get("max-parallel")).toEqual(new data.NumberData(1));
-    });
-
-    it("returns defaults when strategy is not a mapping", () => {
-      const workflowContext = contextFromStrategy(stringToToken("hello"));
-
-      const context = getStrategyContext(workflowContext);
-
-      expect(context.get("fail-fast")).toEqual(new data.BooleanData(true));
-      expect(context.get("job-index")).toEqual(new data.NumberData(0));
-      expect(context.get("job-total")).toEqual(new data.NumberData(1));
-      expect(context.get("max-parallel")).toEqual(new data.NumberData(1));
-    });
-  });
-
-  describe("strategy defined with partial properties", () => {
-    it("uses specified fail-fast, defaults for others", () => {
-      const strategy = new MappingToken(undefined, undefined, undefined);
-      strategy.add(stringToToken("fail-fast"), boolToToken(false));
-      const workflowContext = contextFromStrategy(strategy);
-
-      const context = getStrategyContext(workflowContext);
-
-      expect(context.get("fail-fast")).toEqual(new data.BooleanData(false));
-      expect(context.get("job-index")).toEqual(new data.NumberData(0));
-      expect(context.get("job-total")).toEqual(new data.NumberData(1));
-      expect(context.get("max-parallel")).toEqual(new data.NumberData(1));
-    });
-
-    it("uses specified max-parallel, defaults for others", () => {
-      const strategy = new MappingToken(undefined, undefined, undefined);
-      strategy.add(stringToToken("max-parallel"), numberToToken(5));
-      const workflowContext = contextFromStrategy(strategy);
-
-      const context = getStrategyContext(workflowContext);
-
-      expect(context.get("fail-fast")).toEqual(new data.BooleanData(true));
-      expect(context.get("job-index")).toEqual(new data.NumberData(0));
-      expect(context.get("job-total")).toEqual(new data.NumberData(1));
-      expect(context.get("max-parallel")).toEqual(new data.NumberData(5));
-    });
-
-    it("only has matrix defined, all strategy properties use defaults", () => {
-      const strategy = new MappingToken(undefined, undefined, undefined);
-      const matrix = new MappingToken(undefined, undefined, undefined);
-      strategy.add(stringToToken("matrix"), matrix);
-      const workflowContext = contextFromStrategy(strategy);
-
-      const context = getStrategyContext(workflowContext);
-
-      expect(context.get("fail-fast")).toEqual(new data.BooleanData(true));
-      expect(context.get("job-index")).toEqual(new data.NumberData(0));
-      expect(context.get("job-total")).toEqual(new data.NumberData(1));
-      expect(context.get("max-parallel")).toEqual(new data.NumberData(1));
-    });
-  });
-
-  describe("strategy with all properties defined", () => {
-    it("uses all specified values", () => {
-      const strategy = new MappingToken(undefined, undefined, undefined);
-      strategy.add(stringToToken("fail-fast"), boolToToken(false));
-      strategy.add(stringToToken("max-parallel"), numberToToken(3));
-      const workflowContext = contextFromStrategy(strategy);
-
-      const context = getStrategyContext(workflowContext);
-
-      expect(context.get("fail-fast")).toEqual(new data.BooleanData(false));
-      // job-index and job-total are runtime values, not specified in YAML
-      expect(context.get("job-index")).toEqual(new data.NumberData(0));
-      expect(context.get("job-total")).toEqual(new data.NumberData(1));
-      expect(context.get("max-parallel")).toEqual(new data.NumberData(3));
-    });
-  });
-});

languageservice/src/context-providers/strategy.ts

@@ -1,49 +0,0 @@
-import {data, DescriptionDictionary} from "@actions/expressions";
-import {isMapping, isScalar, isString} from "@actions/workflow-parser";
-import {WorkflowContext} from "../context/workflow-context.js";
-import {scalarToData} from "../utils/scalar-to-data.js";
-
-// Default strategy values when no strategy block is defined
-const DEFAULT_STRATEGY = {
-  "fail-fast": new data.BooleanData(true),
-  "job-index": new data.NumberData(0),
-  "job-total": new data.NumberData(1),
-  "max-parallel": new data.NumberData(1)
-};
-
-export function getStrategyContext(workflowContext: WorkflowContext): DescriptionDictionary {
-  // https://docs.github.com/en/actions/learn-github-actions/contexts#strategy-context
-  const keys = ["fail-fast", "job-index", "job-total", "max-parallel"];
-
-  const strategy = workflowContext.job?.strategy ?? workflowContext.reusableWorkflowJob?.strategy;
-  if (!strategy || !isMapping(strategy)) {
-    // No strategy defined - return defaults that match runtime behavior
-    return new DescriptionDictionary(
-      ...keys.map(key => {
-        return {key, value: DEFAULT_STRATEGY[key as keyof typeof DEFAULT_STRATEGY]};
-      })
-    );
-  }
-
-  const strategyContext = new DescriptionDictionary();
-  for (const pair of strategy) {
-    if (!isString(pair.key)) {
-      continue;
-    }
-    if (!keys.includes(pair.key.value)) {
-      continue;
-    }
-
-    const value = isScalar(pair.value) ? scalarToData(pair.value) : new data.Null();
-    strategyContext.add(pair.key.value, value);
-  }
-
-  for (const key of keys) {
-    if (!strategyContext.get(key)) {
-      // Use default value for missing properties
-      strategyContext.add(key, DEFAULT_STRATEGY[key as keyof typeof DEFAULT_STRATEGY]);
-    }
-  }
-
-  return strategyContext;
-}

languageservice/src/context/action-context.ts

@@ -0,0 +1,122 @@
+import {isMapping} from "@actions/workflow-parser";
+import {ActionInputDefinition, ActionTemplate} from "@actions/workflow-parser/actions/action-template";
+import {Step} from "@actions/workflow-parser/model/workflow-template";
+import {MappingToken} from "@actions/workflow-parser/templates/tokens/mapping-token";
+import {SequenceToken} from "@actions/workflow-parser/templates/tokens/sequence-token";
+import {TemplateToken} from "@actions/workflow-parser/templates/tokens/template-token";
+
+/**
+ * Context information for an action.yml file, used to provide
+ * expression completion with action-specific values.
+ */
+export interface ActionContext {
+  uri: string;
+
+  /** The converted action template */
+  template: ActionTemplate | undefined;
+
+  /** If the context is for a position within a composite step, this will be the step */
+  step?: Step;
+}
+
+/**
+ * Build context from a converted action template and token path.
+ * Similar to getWorkflowContext but for action files.
+ */
+export function getActionContext(
+  uri: string,
+  template: ActionTemplate | undefined,
+  tokenPath: TemplateToken[]
+): ActionContext {
+  const context: ActionContext = {uri, template};
+  if (!template) {
+    return context;
+  }
+
+  // Only composite actions have steps
+  if (template.runs?.using !== "composite") {
+    return context;
+  }
+
+  const compositeRuns = template.runs;
+  if (!compositeRuns.steps?.length) {
+    return context;
+  }
+
+  // Find the current step from the token path
+  let stepsSequence: SequenceToken | undefined;
+  let stepToken: MappingToken | undefined;
+
+  for (const token of tokenPath) {
+    const defKey = token.definition?.key;
+    if (defKey === "composite-steps" && token instanceof SequenceToken) {
+      stepsSequence = token;
+    } else if ((defKey === "run-step" || defKey === "uses-step") && isMapping(token)) {
+      stepToken = token;
+    }
+  }
+
+  if (stepsSequence && stepToken) {
+    context.step = findStep(compositeRuns.steps, stepsSequence, stepToken);
+  }
+
+  return context;
+}
+
+/**
+ * Find the Step that corresponds to the given step token.
+ */
+function findStep(steps: Step[], stepsSequence: SequenceToken, stepToken: MappingToken): Step | undefined {
+  // Find the step by matching index in the sequence
+  let stepIndex = -1;
+  for (let i = 0; i < stepsSequence.count; i++) {
+    if (stepsSequence.get(i) === stepToken) {
+      stepIndex = i;
+      break;
+    }
+  }
+
+  if (stepIndex === -1 || stepIndex >= steps.length) {
+    return undefined;
+  }
+
+  return steps[stepIndex];
+}
+
+/**
+ * Get input definitions from the action template.
+ */
+export function getActionInputs(template: ActionTemplate | undefined): ActionInputDefinition[] {
+  return template?.inputs ?? [];
+}
+
+/**
+ * Get step IDs from composite action steps that appear before the current step.
+ * This is used for `steps.<id>` context completion - you can only reference
+ * steps that have already run.
+ */
+export function getActionStepIdsBefore(context: ActionContext): string[] {
+  const template = context.template;
+  if (!template || template.runs?.using !== "composite") {
+    return [];
+  }
+
+  const compositeRuns = template.runs;
+  const steps = compositeRuns.steps ?? [];
+  const currentStep = context.step;
+
+  const stepIds: string[] = [];
+  for (const step of steps) {
+    // Stop when we reach the current step
+    if (currentStep && step === currentStep) {
+      break;
+    }
+
+    // Only include steps with explicit IDs
+    if (step.id) {
+      stepIds.push(step.id);
+    }
+  }
+
+  return stepIds;
+}

languageservice/src/context/workflow-context.ts

@@ -6,6 +6,10 @@ import {SequenceToken} from "@actions/workflow-parser/templates/tokens/sequence-
 import {StringToken} from "@actions/workflow-parser/templates/tokens/string-token";
 import {TemplateToken} from "@actions/workflow-parser/templates/tokens/template-token";
 
+/**
+ * Represents the contextual position within a workflow file.
+ * Used to determine which expression contexts are available at a given location.
+ */
 export interface WorkflowContext {
   uri: string;
 
@@ -21,6 +25,12 @@ export interface WorkflowContext {
   step?: Step;
 }
 
+/**
+ * Builds a WorkflowContext by walking the token path to identify the current job and step.
+ * @param uri - The URI of the workflow file
+ * @param template - The parsed workflow template
+ * @param tokenPath - The path of tokens from root to the current position
+ */
 export function getWorkflowContext(
   uri: string,
   template: WorkflowTemplate | undefined,
@@ -73,6 +83,10 @@ export function getWorkflowContext(
   return context;
 }
 
+/**
+ * Finds a Step by matching the step token's position in the steps sequence.
+ * Steps may not have IDs, so we locate them by index rather than by identifier.
+ */
 function findStep(steps?: Step[], stepSequence?: SequenceToken, stepToken?: MappingToken): Step | undefined {
   if (!steps || !stepSequence || !stepToken) {
     return undefined;

languageservice/src/description-providers/reusable-job-inputs.ts

@@ -3,6 +3,9 @@ import {DESCRIPTION} from "@actions/workflow-parser/templates/template-constants
 import {WorkflowContext} from "../context/workflow-context.js";
 import {TokenResult} from "../utils/find-token.js";
 
+/**
+ * Checks if the token is an input value in a reusable workflow job's `with:` block.
+ */
 export function isReusableWorkflowJobInput(tokenResult: TokenResult): boolean {
   return (
     tokenResult.parent?.definition?.key === "workflow-job-with" &&
@@ -11,6 +14,11 @@ export function isReusableWorkflowJobInput(tokenResult: TokenResult): boolean {
   );
 }
 
+/**
+ * Gets the description of an input from a called reusable workflow.
+ * When a workflow calls another workflow with `uses:`, this fetches the input's
+ * description from the called workflow's `workflow_call.inputs` definitions.
+ */
 export function getReusableWorkflowInputDescription(
   workflowContext: WorkflowContext,
   tokenResult: TokenResult

languageservice/src/document-links.test.ts

@@ -129,4 +129,31 @@ jobs:
       }
     ]);
   });
+
+  it("links for actions in composite action", async () => {
+    const input = `name: My Composite Action
+description: A composite action with nested actions
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+    - run: echo "Hello"
+      shell: bash`;
+    const result = await documentLinks(createDocument("action.yml", input), undefined);
+    expect(result).toHaveLength(2);
+    expect(result[0].target).toBe("https://www.github.com/actions/checkout/tree/v4/");
+    expect(result[0].tooltip).toBe("Open action on GitHub");
+    expect(result[1].target).toBe("https://www.github.com/actions/setup-node/tree/v4/");
+  });
+
+  it("no links for non-composite action", async () => {
+    const input = `name: My Node Action
+description: A node action
+runs:
+  using: node20
+  main: index.js`;
+    const result = await documentLinks(createDocument("action.yml", input), undefined);
+    expect(result).toHaveLength(0);
+  });
 });

languageservice/src/document-links.ts

@@ -6,29 +6,82 @@ import {TextDocument} from "vscode-languageserver-textdocument";
 import {DocumentLink} from "vscode-languageserver-types";
 import * as vscodeURI from "vscode-uri";
 import {actionUrl, parseActionReference} from "./action.js";
+import {isActionDocument} from "./utils/document-type.js";
 import {mapRange} from "./utils/range.js";
-import {fetchOrConvertWorkflowTemplate, fetchOrParseWorkflow} from "./utils/workflow-cache.js";
+import {
+  getOrConvertActionTemplate,
+  getOrConvertWorkflowTemplate,
+  getOrParseAction,
+  getOrParseWorkflow
+} from "./utils/workflow-cache.js";
 
+/**
+ * Generates clickable links for action references and reusable workflows.
+ */
 export async function documentLinks(document: TextDocument, workspace: string | undefined): Promise<DocumentLink[]> {
   const file: File = {
     name: document.uri,
     content: document.getText()
   };
 
-  const parsedWorkflow = fetchOrParseWorkflow(file, document.uri);
+  return isActionDocument(document.uri)
+    ? actionDocumentLinks(file, document.uri)
+    : workflowDocumentLinks(file, document.uri, workspace);
+}
+
+/**
+ * Generates clickable links for action references in action.yml files.
+ */
+function actionDocumentLinks(file: File, uri: string): DocumentLink[] {
+  const parsedAction = getOrParseAction(file, uri);
+  if (!parsedAction?.value) {
+    return [];
+  }
+
+  const template = getOrConvertActionTemplate(parsedAction.context, parsedAction.value, uri, {
+    errorPolicy: ErrorPolicy.TryConversion
+  });
+
+  const links: DocumentLink[] = [];
+
+  // Only composite actions have steps
+  if (template?.runs?.using !== "composite") {
+    return links;
+  }
+
+  const steps = template.runs.steps ?? [];
+  for (const step of steps) {
+    if ("uses" in step) {
+      const actionRef = parseActionReference(step.uses.value);
+      if (!actionRef) {
+        continue;
+      }
+
+      const url = actionUrl(actionRef);
+
+      links.push({
+        range: mapRange(step.uses.range),
+        target: url,
+        tooltip: `Open action on GitHub`
+      });
+    }
+  }
+
+  return links;
+}
+
+/**
+ * Generates clickable links for action references and reusable workflows in workflow files.
+ */
+async function workflowDocumentLinks(file: File, uri: string, workspace: string | undefined): Promise<DocumentLink[]> {
+  const parsedWorkflow = getOrParseWorkflow(file, uri);
   if (!parsedWorkflow?.value) {
     return [];
   }
 
-  const template = await fetchOrConvertWorkflowTemplate(
-    parsedWorkflow.context,
-    parsedWorkflow.value,
-    document.uri,
-    undefined,
-    {
-      errorPolicy: ErrorPolicy.TryConversion
-    }
-  );
+  const template = await getOrConvertWorkflowTemplate(parsedWorkflow.context, parsedWorkflow.value, uri, undefined, {
+    errorPolicy: ErrorPolicy.TryConversion
+  });
 
   const links: DocumentLink[] = [];
 

languageservice/src/e2e.test.ts

@@ -22,7 +22,9 @@ describe("end-to-end", () => {
 
     expect(result).not.toBeUndefined();
     expect(result.length).toEqual(13);
-    const labelsWithDetails = result.map(x => (x.detail ? `${x.label} (${x.detail})` : x.label));
+    const labelsWithDetails = result.map(x =>
+      x.labelDetails?.description ? `${x.label} (${x.labelDetails.description})` : x.label
+    );
     expect(labelsWithDetails).toEqual([
       "concurrency",
       "concurrency (full syntax)",

languageservice/src/expression-hover/visitor.test.ts

@@ -3,7 +3,7 @@ import {convertWorkflowTemplate, parseWorkflow} from "@actions/workflow-parser";
 import {ErrorPolicy} from "@actions/workflow-parser/model/convert";
 import {File} from "@actions/workflow-parser/workflows/file";
 import {ContextProviderConfig} from "../context-providers/config.js";
-import {getContext, Mode} from "../context-providers/default.js";
+import {getWorkflowExpressionContext, Mode} from "../context-providers/default.js";
 import {getWorkflowContext} from "../context/workflow-context.js";
 import {validatorFunctions} from "../expression-validation/functions.js";
 import {nullTrace} from "../nulltrace.js";
@@ -116,7 +116,12 @@ async function hoverExpression(input: string) {
     errorPolicy: ErrorPolicy.TryConversion
   });
   const workflowContext = getWorkflowContext(td.uri, template, []);
-  const context = await getContext(allowedContext, contextProviderConfig, workflowContext, Mode.Completion);
+  const context = await getWorkflowExpressionContext(
+    allowedContext,
+    contextProviderConfig,
+    workflowContext,
+    Mode.Completion
+  );
 
   const l = new Lexer(td.getText());
   const lr = l.lex();

languageservice/src/hover-action.test.ts

@@ -0,0 +1,217 @@
+import {TextDocument} from "vscode-languageserver-textdocument";
+import {hover} from "./hover";
+
+describe("hover action files", () => {
+  function createActionDocument(
+    content: string,
+    uri = "file:///test/action.yml"
+  ): [TextDocument, {line: number; character: number}] {
+    // Parse cursor position and remove the | character
+    const cursorIndex = content.indexOf("|");
+    if (cursorIndex === -1) {
+      throw new Error("No cursor (|) found in content");
+    }
+    const newContent = content.substring(0, cursorIndex) + content.substring(cursorIndex + 1);
+    const doc = TextDocument.create(uri, "yaml", 1, newContent);
+    const position = doc.positionAt(cursorIndex);
+    return [doc, position];
+  }
+
+  describe("top-level keys", () => {
+    it("shows description for name key", async () => {
+      const [doc, position] = createActionDocument(`na|me: My Action
+description: Test
+runs:
+  using: node20
+  main: index.js`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("name");
+    });
+
+    it("shows description for description key", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+descrip|tion: Test
+runs:
+  using: node20
+  main: index.js`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("description");
+    });
+
+    it("shows description for runs key", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+ru|ns:
+  using: node20
+  main: index.js`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("runs");
+    });
+
+    it("shows description for author key", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+au|thor: Me
+runs:
+  using: node20
+  main: index.js`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("author");
+      expect(result?.contents).toContain("Documentation");
+    });
+  });
+
+  describe("runs properties", () => {
+    it("shows description for using key", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+runs:
+  us|ing: node20
+  main: index.js`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("runtime");
+    });
+
+    it("shows description for main key", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+runs:
+  using: node20
+  ma|in: index.js`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("main");
+    });
+  });
+
+  describe("inputs", () => {
+    it("shows description for inputs section", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+inp|uts:
+  my-input:
+    description: A test input
+runs:
+  using: node20
+  main: index.js`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("input");
+    });
+
+    it("shows description for required key", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+inputs:
+  my-input:
+    description: A test input
+    requ|ired: true
+runs:
+  using: node20
+  main: index.js`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("required");
+    });
+
+    it("shows allowed context for default value", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+inputs:
+  my-input:
+    description: A test input
+    def|ault: foo
+runs:
+  using: node20
+  main: index.js`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      // Input defaults can use expressions with github, strategy, matrix, job, runner contexts
+      expect(result?.contents).toContain("github");
+    });
+  });
+
+  describe("branding", () => {
+    it("shows description for branding section", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+runs:
+  using: node20
+  main: index.js
+brand|ing:
+  icon: activity
+  color: blue`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("brand");
+      expect(result?.contents).toContain("Documentation");
+    });
+
+    it("shows description for icon key", async () => {
+      const [doc, position] = createActionDocument(`name: My Action
+description: Test
+runs:
+  using: node20
+  main: index.js
+branding:
+  ic|on: activity
+  color: blue`);
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+      expect(result?.contents).toContain("icon");
+    });
+  });
+
+  describe("document type routing", () => {
+    it("routes action.yml to action hover", async () => {
+      const [doc, position] = createActionDocument(
+        `na|me: My Action
+description: Test
+runs:
+  using: node20
+  main: index.js`,
+        "file:///my-repo/action.yml"
+      );
+      const result = await hover(doc, position);
+
+      expect(result).not.toBeNull();
+    });
+
+    it("does not route workflow files to action hover", async () => {
+      const doc = TextDocument.create(
+        "file:///repo/.github/workflows/ci.yml",
+        "yaml",
+        1,
+        `name: CI
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hello`
+      );
+      // Hovering over 'name' in a workflow file should give workflow-specific info
+      const result = await hover(doc, {line: 0, character: 2});
+
+      // The workflow hover might not have description for workflow name,
+      // but it should not crash
+      expect(result === null || result.contents !== undefined).toBe(true);
+    });
+  });
+});

languageservice/src/hover.test.ts

@@ -110,8 +110,7 @@ jobs:
 `;
     const result = await hover(...getPositionFromCursor(input));
     expect(result).not.toBeUndefined();
-    // Cron description is now shown via diagnostics, not hover
-    expect(result?.contents).toEqual("");
+    expect(result?.contents).toEqual("Runs at 0 and 30 minutes past the hour, at 00:00 and 12:00");
   });
 
   it("on a cron mapping key", async () => {

languageservice/src/hover.ts

@@ -1,6 +1,9 @@
 import {data, DescriptionDictionary, 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";
+import {isString} from "@actions/workflow-parser";
+import {getCronDescription} from "@actions/workflow-parser/model/converter/cron";
 import {ErrorPolicy} from "@actions/workflow-parser/model/convert";
 import {splitAllowedContext} from "@actions/workflow-parser/templates/allowed-context";
 import {TemplateToken} from "@actions/workflow-parser/templates/tokens/template-token";
@@ -10,8 +13,9 @@ import {FileProvider} from "@actions/workflow-parser/workflows/file-provider";
 import {Position, TextDocument} from "vscode-languageserver-textdocument";
 import {Hover} from "vscode-languageserver-types";
 import {ContextProviderConfig} from "./context-providers/config.js";
-import {getContext, Mode} from "./context-providers/default.js";
+import {getActionExpressionContext, getWorkflowExpressionContext, Mode} from "./context-providers/default.js";
 import {getFunctionDescription} from "./context-providers/descriptions.js";
+import {ActionContext, getActionContext} from "./context/action-context.js";
 import {getWorkflowContext, WorkflowContext} from "./context/workflow-context.js";
 import {
   getReusableWorkflowInputDescription,
@@ -20,10 +24,12 @@ import {
 import {ExpressionPos, mapToExpressionPos} from "./expression-hover/expression-pos.js";
 import {HoverVisitor} from "./expression-hover/visitor.js";
 import {info} from "./log.js";
+import {nullTrace} from "./nulltrace.js";
+import {isActionDocument} from "./utils/document-type.js";
 import {isPotentiallyExpression} from "./utils/expression-detection.js";
 import {findToken} from "./utils/find-token.js";
 import {mapRange} from "./utils/range.js";
-import {fetchOrConvertWorkflowTemplate, fetchOrParseWorkflow} from "./utils/workflow-cache.js";
+import {getOrConvertActionTemplate, getOrConvertWorkflowTemplate, getOrParseWorkflow} from "./utils/workflow-cache.js";
 
 export type HoverConfig = {
   descriptionProvider?: DescriptionProvider;
@@ -32,79 +38,136 @@ export type HoverConfig = {
 };
 
 export type DescriptionProvider = {
-  getDescription(context: WorkflowContext, token: TemplateToken, path: TemplateToken[]): Promise<string | undefined>;
+  getDescription(
+    context: WorkflowContext | ActionContext,
+    token: TemplateToken,
+    path: TemplateToken[]
+  ): Promise<string | undefined>;
 };
 
+/**
+ * Returns hover information for the token at the given position.
+ */
 export async function hover(document: TextDocument, position: Position, config?: HoverConfig): Promise<Hover | null> {
   const file: File = {
     name: document.uri,
     content: document.getText()
   };
 
-  const parsedWorkflow = fetchOrParseWorkflow(file, document.uri);
-  if (!parsedWorkflow?.value) {
+  // Determine document type based on file path (action.yml vs workflow file)
+  const isAction = isActionDocument(document.uri);
+
+  // Parse document
+  const parsedTemplate = isAction ? parseAction(file, nullTrace) : getOrParseWorkflow(file, document.uri);
+  if (!parsedTemplate?.value) {
     return null;
   }
 
-  const template = await fetchOrConvertWorkflowTemplate(
-    parsedWorkflow.context,
-    parsedWorkflow.value,
-    document.uri,
-    config,
-    {
-      errorPolicy: ErrorPolicy.TryConversion,
-      fetchReusableWorkflowDepth: config?.fileProvider ? 1 : 0
-    }
-  );
-
-  const tokenResult = findToken(position, parsedWorkflow.value);
+  // Find the token at the cursor position
+  const tokenResult = findToken(position, parsedTemplate.value);
   const {token, keyToken, parent} = tokenResult;
   const tokenDefinitionInfo = (keyToken || parent || token)?.definitionInfo;
 
-  const workflowContext = getWorkflowContext(document.uri, template, tokenResult.path);
-  if (token && tokenDefinitionInfo) {
-    if (isBasicExpression(token) || isPotentiallyExpression(token)) {
-      info(`Calculating expression hover for token with definition ${tokenDefinitionInfo.definition.key}`);
-
-      const allowedContext = tokenDefinitionInfo.allowedContext || [];
-      const {namedContexts, functions} = splitAllowedContext(allowedContext);
-      const context = await getContext(namedContexts, config?.contextProviderConfig, workflowContext, Mode.Completion);
-
-      for (const func of functions) {
-        func.description = getFunctionDescription(func.name);
-      }
-
-      const exprPos = mapToExpressionPos(token, position);
-      if (exprPos) {
-        return expressionHover(exprPos, context, namedContexts, functions);
-      }
-    }
-  }
-
-  if (!token?.definition) {
+  // Early exit if there's nothing to provide hover for
+  const hoverToken = token || keyToken;
+  const isExpressionHover =
+    token && tokenDefinitionInfo && (isBasicExpression(token) || isPotentiallyExpression(token));
+  if (!isExpressionHover && !hoverToken?.definition) {
     return null;
   }
 
-  info(`Calculating hover for token with definition ${token.definition.key}`);
+  // Build document context (jobs, steps, inputs, etc.) from the parsed template
+  const documentContext = isAction
+    ? getActionContext(
+        document.uri,
+        getOrConvertActionTemplate(parsedTemplate.context, parsedTemplate.value, document.uri, {
+          errorPolicy: ErrorPolicy.TryConversion
+        }),
+        tokenResult.path
+      )
+    : getWorkflowContext(
+        document.uri,
+        await getOrConvertWorkflowTemplate(parsedTemplate.context, parsedTemplate.value, document.uri, config, {
+          errorPolicy: ErrorPolicy.TryConversion,
+          fetchReusableWorkflowDepth: config?.fileProvider ? 1 : 0
+        }),
+        tokenResult.path
+      );
 
-  if (tokenResult.parent && isReusableWorkflowJobInput(tokenResult)) {
-    let description = getReusableWorkflowInputDescription(workflowContext, tokenResult);
-    description = appendContext(description, token.definitionInfo?.allowedContext);
-    return {
-      contents: description,
-      range: mapRange(token.range)
-    } satisfies Hover;
+  // Expression hover
+  if (isExpressionHover) {
+    info(`Calculating expression hover for token with definition ${tokenDefinitionInfo.definition.key}`);
+
+    const allowedContext = tokenDefinitionInfo.allowedContext || [];
+    const {namedContexts, functions} = splitAllowedContext(allowedContext);
+
+    // Build expression context with named contexts (github, env, etc.) and their descriptions
+    const expressionContext = isAction
+      ? getActionExpressionContext(
+          namedContexts,
+          config?.contextProviderConfig,
+          documentContext as ActionContext,
+          Mode.Hover
+        )
+      : await getWorkflowExpressionContext(
+          namedContexts,
+          config?.contextProviderConfig,
+          documentContext as WorkflowContext,
+          Mode.Hover
+        );
+
+    // Populate function descriptions for hover display
+    for (const func of functions) {
+      func.description = getFunctionDescription(func.name);
+    }
+
+    // Convert document position to expression-relative position
+    const exprPos = mapToExpressionPos(token, position);
+    if (exprPos) {
+      // Find the expression element at the cursor and return its description
+      return expressionHover(exprPos, expressionContext, namedContexts, functions);
+    }
   }
 
-  let description = await getDescription(config, workflowContext, token, tokenResult.path);
-  description = appendContext(description, token.definitionInfo?.allowedContext);
+  if (!hoverToken?.definition) {
+    return null;
+  }
 
+  // Non-expression hover: show the schema description for the YAML key or value
+  info(`Calculating hover for token with definition ${hoverToken.definition.key}`);
+
+  // Check for cron expression hover
+  if (isString(hoverToken) && hoverToken.definition.key === "cron-pattern") {
+    const cronDescription = getCronDescription(hoverToken.value);
+    if (cronDescription) {
+      return {
+        contents: cronDescription,
+        range: mapRange(hoverToken.range)
+      };
+    }
+  }
+
+  let description: string;
+  if (!isAction && tokenResult.parent && isReusableWorkflowJobInput(tokenResult)) {
+    // Reusable workflow call: fetch the called workflow's input descriptions
+    description = getReusableWorkflowInputDescription(documentContext as WorkflowContext, tokenResult);
+  } else {
+    // Default: use custom provider or token's schema description
+    description =
+      (await getDescription(config, documentContext, hoverToken, tokenResult.path)) || hoverToken.description || "";
+  }
+
+  // Return hover with description and available expression contexts
   return {
-    contents: description,
-    range: mapRange(token.range)
+    contents: appendContext(description, hoverToken.definitionInfo?.allowedContext),
+    range: mapRange(hoverToken.range)
   } satisfies Hover;
 }
 
+/**
+ * Appends available expression contexts and functions to a hover description.
+ * For example: "Available expression contexts: `github`, `env`"
+ */
 function appendContext(description: string, allowedContext?: string[]) {
   if (!allowedContext || allowedContext.length == 0) {
     return description;
@@ -128,24 +191,30 @@ function appendContext(description: string, allowedContext?: string[]) {
   return `${description}${namedContextsString}${functionsString}`;
 }
 
+/**
+ * Gets a custom description from the configured description provider.
+ * Used to fetch rich descriptions like action input docs from GitHub repos.
+ */
 async function getDescription(
   config: HoverConfig | undefined,
-  workflowContext: WorkflowContext,
+  documentContext: WorkflowContext | ActionContext,
   token: TemplateToken,
   path: TemplateToken[]
-) {
-  const defaultDescription = token.description || "";
+): Promise<string | undefined> {
   if (!config?.descriptionProvider) {
-    return defaultDescription;
+    return undefined;
   }
 
-  const description = await config.descriptionProvider.getDescription(workflowContext, token, path);
-  return description || defaultDescription;
+  return await config.descriptionProvider.getDescription(documentContext, token, path);
 }
 
+/**
+ * Parses an expression and finds the element at the cursor position to show its description.
+ * For example, hovering over `github.actor` shows "The login of the user that triggered the workflow".
+ */
 function expressionHover(
   exprPos: ExpressionPos,
-  context: DescriptionDictionary,
+  expressionContext: DescriptionDictionary,
   namedContexts: string[],
   functions: FunctionInfo[]
 ): Hover | null {
@@ -165,7 +234,7 @@ function expressionHover(
         call: () => new data.Null()
       });
     }
-    const hv = new HoverVisitor(position, context, functionMap);
+    const hv = new HoverVisitor(position, expressionContext, functionMap);
     const hoverResult = hv.hover(expr);
     if (!hoverResult) {
       return null;

languageservice/src/index.ts

@@ -1,4 +1,4 @@
-export {complete} from "./complete.js";
+export {complete, CompletionConfig} from "./complete.js";
 export {ContextProviderConfig} from "./context-providers/config.js";
 export {documentLinks} from "./document-links.js";
 export {hover} from "./hover.js";

languageservice/src/inlay-hints.ts

@@ -4,7 +4,8 @@ import {TemplateToken} from "@actions/workflow-parser/templates/tokens/template-
 import {File} from "@actions/workflow-parser/workflows/file";
 import {TextDocument} from "vscode-languageserver-textdocument";
 import {InlayHint, InlayHintKind} from "vscode-languageserver-types";
-import {fetchOrParseWorkflow} from "./utils/workflow-cache.js";
+import {isActionDocument} from "./utils/document-type.js";
+import {getOrParseWorkflow} from "./utils/workflow-cache.js";
 
 /**
  * Returns inlay hints for a workflow document.
@@ -15,12 +16,17 @@ import {fetchOrParseWorkflow} from "./utils/workflow-cache.js";
  * @returns Array of inlay hints
  */
 export function getInlayHints(document: TextDocument): InlayHint[] {
+  // Inlay hints are only supported for workflow files (cron expressions)
+  if (isActionDocument(document.uri)) {
+    return [];
+  }
+
   const file: File = {
     name: document.uri,
     content: document.getText()
   };
 
-  const result = fetchOrParseWorkflow(file, document.uri);
+  const result = getOrParseWorkflow(file, document.uri);
   if (!result?.value) {
     return [];
   }

languageservice/src/utils/document-type.test.ts

@@ -0,0 +1,98 @@
+import {detectDocumentType, isActionDocument, isWorkflowDocument} from "./document-type";
+
+describe("detectDocumentType", () => {
+  describe("action files", () => {
+    it("detects action.yml", () => {
+      expect(detectDocumentType("/path/to/action.yml")).toBe("action");
+    });
+
+    it("detects action.yaml", () => {
+      expect(detectDocumentType("/path/to/action.yaml")).toBe("action");
+    });
+
+    it("detects action.yml with case insensitivity", () => {
+      expect(detectDocumentType("/path/to/ACTION.YML")).toBe("action");
+      expect(detectDocumentType("/path/to/Action.Yaml")).toBe("action");
+    });
+
+    it("detects nested action.yml", () => {
+      expect(detectDocumentType("/repo/.github/actions/my-action/action.yml")).toBe("action");
+    });
+
+    it("detects bare action.yml", () => {
+      expect(detectDocumentType("action.yml")).toBe("action");
+    });
+
+    it("handles Windows paths", () => {
+      expect(detectDocumentType("C:\\Users\\me\\action.yml")).toBe("action");
+      expect(detectDocumentType("C:\\repo\\.github\\actions\\my-action\\action.yml")).toBe("action");
+    });
+  });
+
+  describe("workflow files", () => {
+    it("detects workflow files in .github/workflows", () => {
+      expect(detectDocumentType("/repo/.github/workflows/ci.yml")).toBe("workflow");
+      expect(detectDocumentType("/repo/.github/workflows/build.yaml")).toBe("workflow");
+    });
+
+    it("detects workflow files in .github/workflows-lab", () => {
+      expect(detectDocumentType("/repo/.github/workflows-lab/ci.yml")).toBe("workflow");
+      expect(detectDocumentType("/repo/.github/workflows-lab/build.yaml")).toBe("workflow");
+    });
+
+    it("detects workflow files case insensitively", () => {
+      expect(detectDocumentType("/repo/.github/workflows/CI.YML")).toBe("workflow");
+    });
+
+    it("handles Windows paths for workflows", () => {
+      expect(detectDocumentType("C:\\repo\\.github\\workflows\\ci.yml")).toBe("workflow");
+      expect(detectDocumentType("C:\\repo\\.github\\workflows-lab\\ci.yml")).toBe("workflow");
+    });
+
+    it("workflow path takes precedence over action filename", () => {
+      // Edge case: action.yml inside .github/workflows should be treated as workflow
+      expect(detectDocumentType("/repo/.github/workflows/action.yml")).toBe("workflow");
+      expect(detectDocumentType("/repo/.github/workflows/action.yaml")).toBe("workflow");
+      expect(detectDocumentType("/repo/.github/workflows-lab/action.yml")).toBe("workflow");
+    });
+  });
+
+  describe("unknown files", () => {
+    it("returns unknown for other yaml files", () => {
+      expect(detectDocumentType("/path/to/config.yml")).toBe("unknown");
+      expect(detectDocumentType("/path/to/docker-compose.yaml")).toBe("unknown");
+    });
+
+    it("returns unknown for non-yaml files", () => {
+      expect(detectDocumentType("/path/to/file.txt")).toBe("unknown");
+    });
+  });
+});
+
+describe("isActionDocument", () => {
+  it("returns true for action files", () => {
+    expect(isActionDocument("/path/to/action.yml")).toBe(true);
+  });
+
+  it("returns false for workflow files", () => {
+    expect(isActionDocument("/repo/.github/workflows/ci.yml")).toBe(false);
+  });
+
+  it("returns false for unknown files", () => {
+    expect(isActionDocument("/path/to/config.yml")).toBe(false);
+  });
+});
+
+describe("isWorkflowDocument", () => {
+  it("returns true for workflow files", () => {
+    expect(isWorkflowDocument("/repo/.github/workflows/ci.yml")).toBe(true);
+  });
+
+  it("returns false for action files", () => {
+    expect(isWorkflowDocument("/path/to/action.yml")).toBe(false);
+  });
+
+  it("returns false for unknown files", () => {
+    expect(isWorkflowDocument("/path/to/config.yml")).toBe(false);
+  });
+});

languageservice/src/utils/document-type.ts

@@ -0,0 +1,48 @@
+/**
+ * Document type detection for workflow and action files.
+ * Detection is based on file path/name only - content heuristics are not used
+ * because files in non-standard locations wouldn't work as workflows/actions anyway.
+ */
+
+export type DocumentType = "workflow" | "action" | "unknown";
+
+/**
+ * Detects whether a document is a workflow file, action file, or unknown based on its URI.
+ *
+ * @param uri The document URI or file path
+ * @returns The detected document type
+ */
+export function detectDocumentType(uri: string): DocumentType {
+  // Normalize path separators
+  const normalizedUri = uri.replace(/\\/g, "/");
+
+  // Check for workflow file patterns FIRST (more specific path takes precedence)
+  // Matches: .github/workflows/*.yml or .github/workflows/*.yaml
+  // Also matches: .github/workflows-lab/*.yml or .github/workflows-lab/*.yaml
+  // This ensures .github/workflows/action.yml is treated as a workflow, not an action
+  if (/\.github\/workflows(-lab)?\/[^/]+\.ya?ml$/i.test(normalizedUri)) {
+    return "workflow";
+  }
+
+  // Check for action.yml/action.yaml patterns
+  // Matches: action.yml, action.yaml, .github/actions/my-action/action.yml, etc.
+  if (/\/action\.ya?ml$/i.test(normalizedUri) || /^action\.ya?ml$/i.test(normalizedUri)) {
+    return "action";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Check if a document is an action file
+ */
+export function isActionDocument(uri: string): boolean {
+  return detectDocumentType(uri) === "action";
+}
+
+/**
+ * Check if a document is a workflow file
+ */
+export function isWorkflowDocument(uri: string): boolean {
+  return detectDocumentType(uri) === "workflow";
+}

languageservice/src/utils/transform.ts

@@ -6,8 +6,24 @@ import {Range} from "vscode-languageserver-types";
 
 const PLACEHOLDER_KEY = "key";
 
-// Transform a document to work around YAML parsing issues
-// Based on `_transform` in https://github.com/cschleiden/github-actions-parser/blob/main/src/lib/parser/complete.ts#L311
+/**
+ * Transforms a document to make it valid YAML so the parser can understand
+ * the cursor position during auto-completion.
+ *
+ * When typing in an IDE, the document is usually invalid YAML:
+ * - `runs-on` without `:` isn't a valid key
+ * - Empty lines don't parse as anything
+ * - `- ` without a value isn't complete
+ *
+ * This function inserts placeholders to make the document parseable:
+ * - Empty line → inserts `key:` placeholder
+ * - Line without colon → appends `:`
+ * - Sequence item `- ` → inserts `key` after the dash
+ *
+ * Lines containing `${{` are skipped to avoid breaking multi-line strings.
+ *
+ * The `isPlaceholder()` helper filters out the fake entries from completions.
+ */
 export function transform(doc: TextDocument, pos: Position): [TextDocument, Position] {
   let offset = doc.offsetAt(pos);
 

languageservice/src/utils/workflow-cache.ts

@@ -1,4 +1,10 @@
-import {convertWorkflowTemplate, parseWorkflow, ParseWorkflowResult, WorkflowTemplate} from "@actions/workflow-parser";
+import {convertWorkflowTemplate, parseWorkflow, TemplateParseResult, WorkflowTemplate} from "@actions/workflow-parser";
+import {parseAction} from "@actions/workflow-parser/actions/action-parser";
+import {
+  ActionTemplate,
+  ActionTemplateConverterOptions,
+  convertActionTemplate
+} from "@actions/workflow-parser/actions/action-template";
 import {WorkflowTemplateConverterOptions} from "@actions/workflow-parser/model/convert";
 import {TemplateContext} from "@actions/workflow-parser/templates/template-context";
 import {TemplateToken} from "@actions/workflow-parser/templates/tokens/template-token";
@@ -7,28 +13,36 @@ import {File} from "@actions/workflow-parser/workflows/file";
 import {CompletionConfig} from "../complete.js";
 import {nullTrace} from "../nulltrace.js";
 
-const parsedWorkflowCache = new Map<string, ParseWorkflowResult>();
+const parsedWorkflowCache = new Map<string, TemplateParseResult>();
+const parsedActionCache = new Map<string, TemplateParseResult>();
 const workflowTemplateCache = new Map<string, WorkflowTemplate>();
+const actionTemplateCache = new Map<string, ActionTemplate>();
 
 export function clearCacheEntry(uri: string) {
   parsedWorkflowCache.delete(uri);
-  parsedWorkflowCache.delete(workflowKey(uri, true));
+  parsedWorkflowCache.delete(cacheKey(uri, true));
+  parsedActionCache.delete(uri);
+  parsedActionCache.delete(cacheKey(uri, true));
   workflowTemplateCache.delete(uri);
-  workflowTemplateCache.delete(workflowKey(uri, true));
+  workflowTemplateCache.delete(cacheKey(uri, true));
+  actionTemplateCache.delete(uri);
+  actionTemplateCache.delete(cacheKey(uri, true));
 }
 
 export function clearCache() {
   parsedWorkflowCache.clear();
+  parsedActionCache.clear();
   workflowTemplateCache.clear();
+  actionTemplateCache.clear();
 }
 
 /**
- * Parses a workflow file and caches the result
+ * Parses a workflow file, returning cached result if available
  * @param transformed Indicates whether the workflow has been transformed before parsing
- * @returns the {@link ParseWorkflowResult}
+ * @returns the {@link TemplateParseResult}
  */
-export function fetchOrParseWorkflow(file: File, uri: string, transformed = false): ParseWorkflowResult {
-  const key = workflowKey(uri, transformed);
+export function getOrParseWorkflow(file: File, uri: string, transformed = false): TemplateParseResult {
+  const key = cacheKey(uri, transformed);
   const cachedResult = parsedWorkflowCache.get(key);
   if (cachedResult) {
     return cachedResult;
@@ -39,11 +53,27 @@ export function fetchOrParseWorkflow(file: File, uri: string, transformed = fals
 }
 
 /**
- * Converts a workflow template and caches the result
+ * Parses an action file, returning cached result if available
+ * @param transformed Indicates whether the action has been transformed before parsing
+ * @returns the {@link TemplateParseResult}
+ */
+export function getOrParseAction(file: File, uri: string, transformed = false): TemplateParseResult {
+  const key = cacheKey(uri, transformed);
+  const cachedResult = parsedActionCache.get(key);
+  if (cachedResult) {
+    return cachedResult;
+  }
+  const result = parseAction(file, nullTrace);
+  parsedActionCache.set(key, result);
+  return result;
+}
+
+/**
+ * Converts a workflow template, returning cached result if available
  * @param transformed Indicates whether the workflow has been transformed before parsing
  * @returns the converted {@link WorkflowTemplate}
  */
-export async function fetchOrConvertWorkflowTemplate(
+export async function getOrConvertWorkflowTemplate(
   context: TemplateContext,
   template: TemplateToken,
   uri: string,
@@ -51,7 +81,7 @@ export async function fetchOrConvertWorkflowTemplate(
   options?: WorkflowTemplateConverterOptions,
   transformed = false
 ): Promise<WorkflowTemplate> {
-  const key = workflowKey(uri, transformed);
+  const key = cacheKey(uri, transformed);
   const cachedTemplate = workflowTemplateCache.get(key);
   if (cachedTemplate) {
     return cachedTemplate;
@@ -61,8 +91,30 @@ export async function fetchOrConvertWorkflowTemplate(
   return workflowTemplate;
 }
 
-// Use a separate cache key for transformed workflows
-function workflowKey(uri: string, transformed: boolean): string {
+/**
+ * Converts an action template, returning cached result if available
+ * @param transformed Indicates whether the action has been transformed before parsing
+ * @returns the converted {@link ActionTemplate}
+ */
+export function getOrConvertActionTemplate(
+  context: TemplateContext,
+  template: TemplateToken,
+  uri: string,
+  options?: ActionTemplateConverterOptions,
+  transformed = false
+): ActionTemplate {
+  const key = cacheKey(uri, transformed);
+  const cachedTemplate = actionTemplateCache.get(key);
+  if (cachedTemplate) {
+    return cachedTemplate;
+  }
+  const actionTemplate = convertActionTemplate(context, template, options);
+  actionTemplateCache.set(key, actionTemplate);
+  return actionTemplate;
+}
+
+// Use a separate cache key for transformed documents
+function cacheKey(uri: string, transformed: boolean): string {
   if (transformed) {
     return `transformed-${uri}`;
   }

languageservice/src/validate-action-reference.ts

@@ -0,0 +1,103 @@
+import {isMapping} from "@actions/workflow-parser";
+import {isActionStep} from "@actions/workflow-parser/model/type-guards";
+import {Step} from "@actions/workflow-parser/model/workflow-template";
+import {ScalarToken} from "@actions/workflow-parser/templates/tokens/scalar-token";
+import {TemplateToken} from "@actions/workflow-parser/templates/tokens/template-token";
+import {Diagnostic, DiagnosticSeverity} from "vscode-languageserver-types";
+import {parseActionReference} from "./action.js";
+import {mapRange} from "./utils/range.js";
+import {ValidationConfig} from "./validate.js";
+
+/**
+ * Validates action references in workflow steps, checking for valid inputs and required inputs.
+ */
+export async function validateActionReference(
+  diagnostics: Diagnostic[],
+  stepToken: TemplateToken,
+  step: Step | undefined,
+  config: ValidationConfig | undefined
+): Promise<void> {
+  if (!isMapping(stepToken) || !step || !isActionStep(step) || !config?.actionsMetadataProvider) {
+    return;
+  }
+
+  // Parse the action reference (e.g., "actions/checkout@v4" -> {owner, name, ref})
+  const action = parseActionReference(step.uses.value);
+  if (!action) {
+    return;
+  }
+
+  // Fetch the action's metadata (action.yml) to get input definitions
+  const actionMetadata = await config.actionsMetadataProvider.fetchActionMetadata(action);
+  if (actionMetadata === undefined) {
+    diagnostics.push({
+      severity: DiagnosticSeverity.Error,
+      range: mapRange(step.uses.range),
+      message: `Unable to resolve action \`${step.uses.value}\`, repository or version not found`
+    });
+    return;
+  }
+
+  // Find the "with" key in the step token to get the inputs passed to the action
+  let withKey: ScalarToken | undefined;
+  let withToken: TemplateToken | undefined;
+  for (const {key, value} of stepToken) {
+    if (key.toString() === "with") {
+      withKey = key;
+      withToken = value;
+      break;
+    }
+  }
+
+  // Collect the inputs provided in the step's "with" block
+  const stepInputs = new Map<string, ScalarToken>();
+  if (withToken && isMapping(withToken)) {
+    for (const {key} of withToken) {
+      stepInputs.set(key.toString(), key);
+    }
+  }
+
+  // Skip validation if the action doesn't define any inputs
+  const actionInputs = actionMetadata.inputs;
+  if (actionInputs === undefined) {
+    return;
+  }
+
+  // Check each provided input is valid and not deprecated
+  for (const [input, inputToken] of stepInputs) {
+    if (!actionInputs[input]) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        range: mapRange(inputToken.range),
+        message: `Invalid action input '${input}'`
+      });
+    }
+
+    const deprecationMessage = actionInputs[input]?.deprecationMessage;
+    if (deprecationMessage) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Warning,
+        range: mapRange(inputToken.range),
+        message: deprecationMessage
+      });
+    }
+  }
+
+  // Check for required inputs that weren't provided and don't have defaults
+  const missingRequiredInputs = Object.entries(actionInputs).filter(
+    ([inputName, input]) => input.required && !stepInputs.has(inputName) && input.default === undefined
+  );
+
+  // Report missing required inputs
+  if (missingRequiredInputs.length > 0) {
+    const message =
+      missingRequiredInputs.length === 1
+        ? `Missing required input \`${missingRequiredInputs[0][0]}\``
+        : `Missing required inputs: ${missingRequiredInputs.map(input => `\`${input[0]}\``).join(", ")}`;
+    diagnostics.push({
+      severity: DiagnosticSeverity.Error,
+      range: mapRange((withKey || stepToken).range), // Highlight the whole step if we don't have a with key
+      message: message
+    });
+  }
+}

languageservice/src/validate-action.test.ts

@@ -0,0 +1,530 @@
+import {TextDocument} from "vscode-languageserver-textdocument";
+import {validate} from "./validate";
+import {clearCache} from "./utils/workflow-cache.js";
+
+describe("validate action files", () => {
+  beforeEach(() => {
+    clearCache();
+  });
+
+  function createActionDocument(content: string, uri = "file:///test/action.yml"): TextDocument {
+    return TextDocument.create(uri, "yaml", 1, content);
+  }
+
+  describe("valid action files", () => {
+    it("validates a minimal composite action", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Does something
+runs:
+  using: composite
+  steps:
+    - run: echo "Hello"
+      shell: bash
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics).toEqual([]);
+    });
+
+    it("validates a node20 action", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: A JavaScript action
+runs:
+  using: node20
+  main: index.js
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics).toEqual([]);
+    });
+
+    it("validates a docker action", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: A Docker action
+runs:
+  using: docker
+  image: Dockerfile
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics).toEqual([]);
+    });
+
+    it("validates an action with inputs and outputs", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Action with I/O
+inputs:
+  name:
+    description: The name to greet
+    required: true
+  greeting:
+    description: The greeting
+    default: Hello
+outputs:
+  result:
+    description: The greeting result
+runs:
+  using: composite
+  steps:
+    - run: echo "$\{{ inputs.greeting }} $\{{ inputs.name }}"
+      shell: bash
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics).toEqual([]);
+    });
+
+    it("validates an action with branding", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Branded action
+branding:
+  icon: activity
+  color: blue
+runs:
+  using: node20
+  main: index.js
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics).toEqual([]);
+    });
+  });
+
+  describe("invalid action files", () => {
+    it("reports error for missing required name", async () => {
+      const doc = createActionDocument(`
+description: An action without a name
+runs:
+  using: composite
+  steps:
+    - run: echo "Hi"
+      shell: bash
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("name");
+    });
+
+    it("reports error for missing required description", async () => {
+      const doc = createActionDocument(`
+name: My Action
+runs:
+  using: composite
+  steps:
+    - run: echo "Hi"
+      shell: bash
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("description");
+    });
+
+    it("reports error for missing runs", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: An action without runs
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("runs");
+    });
+
+    it("reports error for missing using in runs", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Missing using
+runs:
+  main: index.js
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("using");
+    });
+
+    it("reports error for invalid branding icon", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Bad icon
+branding:
+  icon: not-a-real-icon
+  color: blue
+runs:
+  using: node20
+  main: index.js
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("not-a-real-icon");
+    });
+
+    it("reports error for invalid branding color", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Bad color
+branding:
+  icon: activity
+  color: pink
+runs:
+  using: node20
+  main: index.js
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("pink");
+    });
+
+    it("reports error for composite step missing shell", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Missing shell
+runs:
+  using: composite
+  steps:
+    - run: echo "Hi"
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("shell");
+    });
+
+    it("reports error for invalid YAML syntax", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Bad YAML
+runs:
+  using: composite
+  steps:
+    - run: |
+      echo "Bad indentation"
+      shell: bash
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("document type routing", () => {
+    it("routes action.yml to action validation", async () => {
+      const doc = createActionDocument(
+        `
+name: Test
+description: Test
+runs:
+  using: node20
+  main: index.js
+`,
+        "file:///my-repo/action.yml"
+      );
+      const diagnostics = await validate(doc);
+      expect(diagnostics).toEqual([]);
+    });
+
+    it("routes action.yaml to action validation", async () => {
+      const doc = createActionDocument(
+        `
+name: Test
+description: Test
+runs:
+  using: node20
+  main: index.js
+`,
+        "file:///my-repo/action.yaml"
+      );
+      const diagnostics = await validate(doc);
+      expect(diagnostics).toEqual([]);
+    });
+
+    it("routes nested action.yml to action validation", async () => {
+      const doc = createActionDocument(
+        `
+name: Test
+description: Test
+runs:
+  using: composite
+  steps:
+    - run: echo test
+      shell: bash
+`,
+        "file:///my-repo/.github/actions/my-action/action.yml"
+      );
+      const diagnostics = await validate(doc);
+      expect(diagnostics).toEqual([]);
+    });
+  });
+
+  describe("composite action step validation", () => {
+    it("validates action inputs in composite action uses steps", async () => {
+      const doc = createActionDocument(`
+name: My Composite Action
+description: A composite action with uses steps
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        invalid-input: value
+`);
+      const mockMetadataProvider = {
+        fetchActionMetadata: () =>
+          Promise.resolve({
+            name: "Checkout",
+            description: "Checkout a repo",
+            inputs: {
+              repository: {description: "Repository name", required: false},
+              ref: {description: "Branch or tag", required: false}
+            }
+          })
+      };
+      const diagnostics = await validate(doc, {actionsMetadataProvider: mockMetadataProvider});
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("invalid-input");
+    });
+
+    it("validates required inputs in composite action uses steps", async () => {
+      const doc = createActionDocument(`
+name: My Composite Action
+description: A composite action with uses steps
+runs:
+  using: composite
+  steps:
+    - uses: actions/some-action@v1
+`);
+      const mockMetadataProvider = {
+        fetchActionMetadata: () =>
+          Promise.resolve({
+            name: "Some Action",
+            description: "An action with required inputs",
+            inputs: {
+              "required-input": {description: "A required input", required: true}
+            }
+          })
+      };
+      const diagnostics = await validate(doc, {actionsMetadataProvider: mockMetadataProvider});
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("required-input");
+    });
+
+    it("reports unresolved action in composite action uses steps", async () => {
+      const doc = createActionDocument(`
+name: My Composite Action
+description: A composite action with uses steps
+runs:
+  using: composite
+  steps:
+    - uses: actions/nonexistent@v1
+`);
+      const mockMetadataProvider = {
+        fetchActionMetadata: () => Promise.resolve(undefined)
+      };
+      const diagnostics = await validate(doc, {actionsMetadataProvider: mockMetadataProvider});
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics[0].message).toContain("Unable to resolve action");
+    });
+
+    it("passes validation for valid composite action uses steps", async () => {
+      const doc = createActionDocument(`
+name: My Composite Action
+description: A composite action with uses steps
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        repository: owner/repo
+`);
+      const mockMetadataProvider = {
+        fetchActionMetadata: () =>
+          Promise.resolve({
+            name: "Checkout",
+            description: "Checkout a repo",
+            inputs: {
+              repository: {description: "Repository name", required: false},
+              ref: {description: "Branch or tag", required: false}
+            }
+          })
+      };
+      const diagnostics = await validate(doc, {actionsMetadataProvider: mockMetadataProvider});
+      expect(diagnostics).toEqual([]);
+    });
+  });
+
+  describe("invalid key combinations based on using type", () => {
+    it("reports error for node20 action with steps", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - node20 with steps
+runs:
+  using: node20
+  main: index.js
+  steps:
+    - run: echo "hello"
+      shell: bash
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      // Schema reports "Unexpected value 'steps'" for invalid keys
+      expect(diagnostics.some(d => d.message.includes("steps"))).toBe(true);
+    });
+
+    it("reports error for composite action with main", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - composite with main
+runs:
+  using: composite
+  steps:
+    - run: echo "hello"
+      shell: bash
+  main: index.js
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      // Schema reports "Unexpected value 'main'" for invalid keys
+      expect(diagnostics.some(d => d.message.includes("main"))).toBe(true);
+    });
+
+    it("reports error for docker action with steps", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - docker with steps
+runs:
+  using: docker
+  image: Dockerfile
+  steps:
+    - run: echo "hello"
+      shell: bash
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      // Schema reports "Unexpected value 'steps'" for invalid keys
+      expect(diagnostics.some(d => d.message.includes("steps"))).toBe(true);
+    });
+
+    it("reports error for docker action with main", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - docker with main
+runs:
+  using: docker
+  image: Dockerfile
+  main: index.js
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      // Schema reports "Unexpected value 'main'" for invalid keys
+      expect(diagnostics.some(d => d.message.includes("main"))).toBe(true);
+    });
+
+    it("reports error for node20 action missing main", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - node20 without main
+runs:
+  using: node20
+  pre: setup.js
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(diagnostics.some(d => d.message.includes("main"))).toBe(true);
+    });
+
+    it("reports error for node24 action missing main", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - node24 without main
+runs:
+  using: node24
+  pre: setup.js
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.some(d => d.message === "'main' is required for Node.js actions (using: node24)")).toBe(true);
+      // Should NOT have duplicate schema error
+      expect(diagnostics.filter(d => d.message.includes("main")).length).toBe(1);
+    });
+
+    it("reports error for node24 action with only using (no narrowing key)", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - node24 without main
+runs:
+  using: node24
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.some(d => d.message === "'main' is required for Node.js actions (using: node24)")).toBe(true);
+      // Should NOT have the generic "not enough info" schema error
+      expect(diagnostics.some(d => d.message.includes("There's not enough info"))).toBe(false);
+    });
+
+    it("reports error for composite action missing steps", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - composite without steps
+runs:
+  using: composite
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.some(d => d.message === "'steps' is required for composite actions (using: composite)")).toBe(
+        true
+      );
+      // Should NOT have duplicate schema error
+      expect(diagnostics.some(d => d.message.includes("There's not enough info"))).toBe(false);
+    });
+
+    it("reports error for docker action missing image", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - docker without image
+runs:
+  using: docker
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.some(d => d.message === "'image' is required for Docker actions (using: docker)")).toBe(true);
+      // Should NOT have duplicate schema error
+      expect(diagnostics.some(d => d.message.includes("There's not enough info"))).toBe(false);
+    });
+
+    it("reports error for docker action with entrypoint but missing image", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - docker without image
+runs:
+  using: docker
+  entrypoint: /entrypoint.sh
+`);
+      const diagnostics = await validate(doc);
+      expect(diagnostics.some(d => d.message === "'image' is required for Docker actions (using: docker)")).toBe(true);
+      // Should NOT have duplicate "Required property is missing: image" schema error
+      expect(diagnostics.filter(d => d.message.includes("image")).length).toBe(1);
+    });
+
+    it("lets schema handle missing using", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - no using
+runs:
+  main: index.js
+`);
+      const diagnostics = await validate(doc);
+      // Should have schema error about not enough info or unexpected value
+      expect(diagnostics.length).toBeGreaterThan(0);
+      // Should NOT have custom validation error (can't determine action type)
+      expect(diagnostics.some(d => d.message.includes("is required for"))).toBe(false);
+    });
+
+    it("lets schema handle invalid using value", async () => {
+      const doc = createActionDocument(`
+name: My Action
+description: Invalid - bad using value
+runs:
+  using: not-supported
+  main: index.js
+`);
+      const diagnostics = await validate(doc);
+      // Should have schema error about unexpected value
+      expect(diagnostics.length).toBeGreaterThan(0);
+      // Should NOT have custom validation error (unknown action type)
+      expect(diagnostics.some(d => d.message.includes("is required for"))).toBe(false);
+      expect(diagnostics.some(d => d.message.includes("is not valid for"))).toBe(false);
+    });
+  });
+});

languageservice/src/validate-action.ts

@@ -1,92 +1,269 @@
+/**
+ * Validation for action.yml / action.yaml manifest files
+ */
+
 import {isMapping} from "@actions/workflow-parser";
 import {isActionStep} from "@actions/workflow-parser/model/type-guards";
-import {Step} from "@actions/workflow-parser/model/workflow-template";
-import {ScalarToken} from "@actions/workflow-parser/templates/tokens/scalar-token";
+import {ErrorPolicy} from "@actions/workflow-parser/model/convert";
+import {MappingToken} from "@actions/workflow-parser/templates/tokens/mapping-token";
+import {SequenceToken} from "@actions/workflow-parser/templates/tokens/sequence-token";
 import {TemplateToken} from "@actions/workflow-parser/templates/tokens/template-token";
+import {TemplateValidationError} from "@actions/workflow-parser/templates/template-validation-error";
+import {File} from "@actions/workflow-parser/workflows/file";
+import {TextDocument} from "vscode-languageserver-textdocument";
 import {Diagnostic, DiagnosticSeverity} from "vscode-languageserver-types";
-import {parseActionReference} from "./action.js";
+import {error} from "./log.js";
 import {mapRange} from "./utils/range.js";
+import {getOrConvertActionTemplate, getOrParseAction} from "./utils/workflow-cache.js";
+import {validateActionReference} from "./validate-action-reference.js";
 import {ValidationConfig} from "./validate.js";
 
-export async function validateAction(
-  diagnostics: Diagnostic[],
-  stepToken: TemplateToken,
-  step: Step | undefined,
-  config: ValidationConfig | undefined
-): Promise<void> {
-  if (!isMapping(stepToken) || !step || !isActionStep(step) || !config?.actionsMetadataProvider) {
-    return;
+/**
+ * Valid keys for each action type under the `runs:` section.
+ * Source: https://github.com/actions/runner/blob/main/src/Runner.Worker/ActionManifestManager.cs
+ */
+const NODE_KEYS = new Set(["using", "main", "pre", "post", "pre-if", "post-if"]);
+const COMPOSITE_KEYS = new Set(["using", "steps"]);
+const DOCKER_KEYS = new Set([
+  "using",
+  "image",
+  "args",
+  "env",
+  "entrypoint",
+  "pre-entrypoint",
+  "pre-if",
+  "post-entrypoint",
+  "post-if"
+]);
+
+/**
+ * Required keys for each action type (besides 'using').
+ */
+const NODE_REQUIRED_KEYS = ["main"];
+const COMPOSITE_REQUIRED_KEYS = ["steps"];
+const DOCKER_REQUIRED_KEYS = ["image"];
+
+/**
+ * Validates an action.yml file
+ *
+ * @param textDocument Document to validate
+ * @param config Optional validation configuration for action metadata provider
+ * @returns Array of diagnostics
+ */
+export async function validateAction(textDocument: TextDocument, config?: ValidationConfig): Promise<Diagnostic[]> {
+  const file: File = {
+    name: textDocument.uri,
+    content: textDocument.getText()
+  };
+
+  const diagnostics: Diagnostic[] = [];
+
+  try {
+    // Parse and validate the action.yml against the schema
+    const result = getOrParseAction(file, textDocument.uri);
+    if (!result) {
+      return [];
+    }
+
+    // Get schema errors
+    const schemaErrors = result.context.errors.getErrors();
+
+    // Run custom runs key validation, which also filters redundant schema errors in place
+    if (result.value) {
+      diagnostics.push(...validateRunsKeysAndFilterErrors(result.value, schemaErrors));
+    }
+
+    // Map remaining schema errors to diagnostics
+    for (const err of schemaErrors) {
+      const range = mapRange(err.range);
+
+      // Determine severity based on error type
+      let severity: DiagnosticSeverity = DiagnosticSeverity.Error;
+
+      // Treat deprecation warnings as warnings
+      if (err.rawMessage.includes("deprecated")) {
+        severity = DiagnosticSeverity.Warning;
+      }
+
+      diagnostics.push({
+        message: err.rawMessage,
+        range,
+        severity
+      });
+    }
+
+    // Validate composite action steps if we have a parsed result
+    if (result.value) {
+      const template = getOrConvertActionTemplate(result.context, result.value, textDocument.uri, {
+        errorPolicy: ErrorPolicy.TryConversion
+      });
+
+      // Only composite actions have steps to validate
+      if (template?.runs?.using === "composite") {
+        const steps = template.runs.steps ?? [];
+
+        // Find the steps sequence token from the raw parsed result
+        const stepsSequence = findStepsSequence(result.value);
+        if (stepsSequence) {
+          // Validate each action step
+          for (let i = 0; i < steps.length; i++) {
+            const step = steps[i];
+            const stepToken = stepsSequence.get(i);
+
+            // Validate action references (inputs, required fields) for uses steps
+            if (isActionStep(step) && isMapping(stepToken)) {
+              await validateActionReference(diagnostics, stepToken, step, config);
+            }
+          }
+        }
+      }
+    }
+  } catch (e) {
+    error(`Unhandled error while validating action file: ${(e as Error).message}`);
   }
 
-  const action = parseActionReference(step.uses.value);
-  if (!action) {
-    return;
+  return diagnostics;
+}
+
+/**
+ * Find the steps sequence token from the raw action template.
+ * Traverses the token tree looking for the "composite-steps" definition.
+ */
+function findStepsSequence(root: TemplateToken): SequenceToken | undefined {
+  for (const [, token] of TemplateToken.traverse(root)) {
+    if (token.definition?.key === "composite-steps" && token instanceof SequenceToken) {
+      return token;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Validates that the keys under `runs:` are valid for the specified `using:` type.
+ * Also filters out schema errors (in place) that this validation replaces with more specific messages.
+ */
+function validateRunsKeysAndFilterErrors(
+  root: TemplateToken,
+  schemaErrors: TemplateValidationError[] // mutated: redundant errors are removed
+): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+
+  // Find the runs mapping from the root
+  let runsMapping: MappingToken | undefined;
+  if (root instanceof MappingToken) {
+    for (let i = 0; i < root.count; i++) {
+      const {key, value} = root.get(i);
+      if (key.toString().toLowerCase() === "runs" && value instanceof MappingToken) {
+        runsMapping = value;
+        break;
+      }
+    }
+  }
+  if (!runsMapping) {
+    return diagnostics;
   }
 
-  const actionMetadata = await config.actionsMetadataProvider.fetchActionMetadata(action);
-  if (actionMetadata === undefined) {
-    diagnostics.push({
-      severity: DiagnosticSeverity.Error,
-      range: mapRange(step.uses.range),
-      message: `Unable to resolve action \`${step.uses.value}\`, repository or version not found`
-    });
-    return;
-  }
-
-  let withKey: ScalarToken | undefined;
-  let withToken: TemplateToken | undefined;
-  for (const {key, value} of stepToken) {
-    if (key.toString() === "with") {
-      withKey = key;
-      withToken = value;
+  // Get the using value from the runs mapping
+  let usingValue: string | undefined;
+  for (let i = 0; i < runsMapping.count; i++) {
+    const {key, value} = runsMapping.get(i);
+    if (key.toString().toLowerCase() === "using") {
+      usingValue = value.toString();
       break;
     }
   }
-
-  const stepInputs = new Map<string, ScalarToken>();
-  if (withToken && isMapping(withToken)) {
-    for (const {key} of withToken) {
-      stepInputs.set(key.toString(), key);
-    }
+  if (!usingValue) {
+    return diagnostics; // No using value, let schema validation handle it
   }
 
-  const actionInputs = actionMetadata.inputs;
-  if (actionInputs === undefined) {
-    return;
+  // Determine allowed keys, required keys, and action type name
+  let allowedKeys: Set<string>;
+  let requiredKeys: string[];
+  let actionType: string;
+
+  if (usingValue.match(/^node\d+$/i)) {
+    allowedKeys = NODE_KEYS;
+    requiredKeys = NODE_REQUIRED_KEYS;
+    actionType = "Node.js";
+  } else if (usingValue.toLowerCase() === "composite") {
+    allowedKeys = COMPOSITE_KEYS;
+    requiredKeys = COMPOSITE_REQUIRED_KEYS;
+    actionType = "composite";
+  } else if (usingValue.toLowerCase() === "docker") {
+    allowedKeys = DOCKER_KEYS;
+    requiredKeys = DOCKER_REQUIRED_KEYS;
+    actionType = "Docker";
+  } else {
+    return diagnostics; // Unknown type, let schema validation handle it
   }
 
-  for (const [input, inputToken] of stepInputs) {
-    if (!actionInputs[input]) {
+  // Get all present keys
+  const presentKeys = new Set<string>();
+  for (let i = 0; i < runsMapping.count; i++) {
+    const {key} = runsMapping.get(i);
+    presentKeys.add(key.toString().toLowerCase());
+  }
+
+  // Check for invalid keys
+  for (let i = 0; i < runsMapping.count; i++) {
+    const {key} = runsMapping.get(i);
+    const keyStr = key.toString().toLowerCase();
+
+    if (!allowedKeys.has(keyStr)) {
       diagnostics.push({
         severity: DiagnosticSeverity.Error,
-        range: mapRange(inputToken.range),
-        message: `Invalid action input '${input}'`
+        range: mapRange(key.range),
+        message: `'${key.toString()}' is not valid for ${actionType} actions (using: ${usingValue})`
       });
     }
+  }
+
+  // Check for missing required keys
+  for (const requiredKey of requiredKeys) {
+    if (!presentKeys.has(requiredKey)) {
+      // Find the 'using' key to report the error location
+      let usingKeyRange = runsMapping.range;
+      for (let i = 0; i < runsMapping.count; i++) {
+        const {key} = runsMapping.get(i);
+        if (key.toString().toLowerCase() === "using") {
+          usingKeyRange = key.range;
+          break;
+        }
+      }
 
-    const deprecationMessage = actionInputs[input]?.deprecationMessage;
-    if (deprecationMessage) {
       diagnostics.push({
-        severity: DiagnosticSeverity.Warning,
-        range: mapRange(inputToken.range),
-        message: deprecationMessage
+        severity: DiagnosticSeverity.Error,
+        range: mapRange(usingKeyRange),
+        message: `'${requiredKey}' is required for ${actionType} actions (using: ${usingValue})`
       });
     }
   }
 
-  const missingRequiredInputs = Object.entries(actionInputs).filter(
-    ([inputName, input]) => input.required && !stepInputs.has(inputName) && input.default === undefined
-  );
+  // Remove schema errors that we're replacing with more specific messages (mutate in place)
+  for (let i = schemaErrors.length - 1; i >= 0; i--) {
+    const err = schemaErrors[i];
 
-  if (missingRequiredInputs.length > 0) {
-    const message =
-      missingRequiredInputs.length === 1
-        ? `Missing required input \`${missingRequiredInputs[0][0]}\``
-        : `Missing required inputs: ${missingRequiredInputs.map(input => `\`${input[0]}\``).join(", ")}`;
-    diagnostics.push({
-      severity: DiagnosticSeverity.Error,
-      range: mapRange((withKey || stepToken).range), // Highlight the whole step if we don't have a with key
-      message: message
-    });
+    // Keep errors not at the runs section start
+    if (
+      err.range?.start.line !== runsMapping.range?.start.line ||
+      err.range?.start.column !== runsMapping.range?.start.column
+    ) {
+      continue;
+    }
+
+    // Check if this is an error we're replacing
+    const isOneOfAmbiguity = err.rawMessage.startsWith("There's not enough info to determine");
+    const isRequiredKey = /^Required property is missing: (main|steps|image)$/.test(err.rawMessage);
+
+    if (!isOneOfAmbiguity && !isRequiredKey) {
+      continue; // Keep errors we're not replacing
+    }
+
+    // Remove only if we have custom diagnostics for this
+    if (diagnostics.length > 0) {
+      schemaErrors.splice(i, 1);
+    }
   }
+
+  return diagnostics;
 }

languageservice/src/validate-format-string.ts

@@ -0,0 +1,199 @@
+/**
+ * Format string validation for format() function calls.
+ * Port of Go's format_validator.go from actions-workflow-parser.
+ */
+
+import {Expr, FunctionCall, Literal, Binary, Unary, Logical, Grouping, IndexAccess} from "@actions/expressions/ast";
+import {Kind} from "@actions/expressions/data/expressiondata";
+
+/**
+ * Error types for format string validation
+ */
+export type FormatStringError =
+  | {type: "invalid-syntax"; message: string}
+  | {type: "arg-count-mismatch"; expected: number; provided: number};
+
+/**
+ * Validates a format string and returns the maximum placeholder index.
+ * Port of Go's validateFormatString from format_validator.go.
+ *
+ * @param formatString The format string to validate
+ * @returns { valid: boolean, maxArgIndex: number } where maxArgIndex is -1 if no placeholders
+ */
+export function validateFormatString(formatString: string): {valid: boolean; maxArgIndex: number} {
+  let maxIndex = -1;
+  let i = 0;
+
+  while (i < formatString.length) {
+    // Find next left brace
+    let lbrace = -1;
+    for (let j = i; j < formatString.length; j++) {
+      if (formatString[j] === "{") {
+        lbrace = j;
+        break;
+      }
+    }
+
+    // Find next right brace
+    let rbrace = -1;
+    for (let j = i; j < formatString.length; j++) {
+      if (formatString[j] === "}") {
+        rbrace = j;
+        break;
+      }
+    }
+
+    // No more braces
+    if (lbrace < 0 && rbrace < 0) {
+      break;
+    }
+
+    // Left brace comes first (or only left brace exists)
+    if (lbrace >= 0 && (rbrace < 0 || lbrace < rbrace)) {
+      // Check if it's escaped
+      if (lbrace + 1 < formatString.length && formatString[lbrace + 1] === "{") {
+        // Escaped left brace
+        i = lbrace + 2;
+        continue;
+      }
+
+      // This is a placeholder opening - find the closing brace
+      rbrace = -1;
+      for (let j = lbrace + 1; j < formatString.length; j++) {
+        if (formatString[j] === "}") {
+          rbrace = j;
+          break;
+        }
+      }
+
+      if (rbrace < 0) {
+        // Missing closing brace
+        return {valid: false, maxArgIndex: -1};
+      }
+
+      // Validate placeholder content (must be digits only)
+      if (rbrace === lbrace + 1) {
+        // Empty placeholder {}
+        return {valid: false, maxArgIndex: -1};
+      }
+
+      // Parse the index and validate it's all digits
+      let index = 0;
+      for (let j = lbrace + 1; j < rbrace; j++) {
+        const c = formatString[j];
+        if (c < "0" || c > "9") {
+          // Non-numeric character
+          return {valid: false, maxArgIndex: -1};
+        }
+        index = index * 10 + (c.charCodeAt(0) - "0".charCodeAt(0));
+      }
+
+      if (index > maxIndex) {
+        maxIndex = index;
+      }
+
+      i = rbrace + 1;
+      continue;
+    }
+
+    // Right brace comes first (or only right brace exists)
+    // Check if it's escaped
+    if (rbrace + 1 < formatString.length && formatString[rbrace + 1] === "}") {
+      // Escaped right brace
+      i = rbrace + 2;
+      continue;
+    }
+
+    // Unescaped right brace outside of placeholder
+    return {valid: false, maxArgIndex: -1};
+  }
+
+  return {valid: true, maxArgIndex: maxIndex};
+}
+
+/**
+ * Walks an expression AST to find and validate all format() function calls.
+ *
+ * @param expr The expression AST to validate
+ * @returns Array of validation errors found
+ */
+export function validateFormatCalls(expr: Expr): FormatStringError[] {
+  const errors: FormatStringError[] = [];
+  const stack: Expr[] = [expr];
+
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (!node) {
+      continue;
+    }
+
+    if (node instanceof FunctionCall) {
+      if (node.functionName.lexeme.toLowerCase() === "format") {
+        const error = validateSingleFormatCall(node);
+        if (error) {
+          errors.push(error);
+        }
+      }
+      // Push args for further processing (to find nested format calls)
+      for (const arg of node.args) {
+        stack.push(arg);
+      }
+    } else if (node instanceof Binary) {
+      stack.push(node.left, node.right);
+    } else if (node instanceof Unary) {
+      stack.push(node.expr);
+    } else if (node instanceof Logical) {
+      for (const arg of node.args) {
+        stack.push(arg);
+      }
+    } else if (node instanceof Grouping) {
+      stack.push(node.group);
+    } else if (node instanceof IndexAccess) {
+      stack.push(node.expr, node.index);
+    }
+    // Literal, ContextAccess - no children to process
+  }
+
+  return errors;
+}
+
+/**
+ * Validates a single format() function call.
+ *
+ * @param fc The FunctionCall AST node
+ * @returns Validation error if found, undefined if valid
+ */
+function validateSingleFormatCall(fc: FunctionCall): FormatStringError | undefined {
+  // Must have at least one argument (the format string)
+  if (fc.args.length < 1) {
+    return undefined;
+  }
+
+  // First argument must be a string literal
+  const firstArg = fc.args[0];
+  if (!(firstArg instanceof Literal) || firstArg.literal.kind !== Kind.String) {
+    return undefined; // Can't validate dynamic format strings
+  }
+
+  const formatString = firstArg.literal.coerceString();
+  const numArgs = fc.args.length - 1; // Subtract 1 for format string itself
+
+  const {valid, maxArgIndex} = validateFormatString(formatString);
+
+  if (!valid) {
+    return {
+      type: "invalid-syntax",
+      message: "Format string has invalid syntax (missing closing brace, unescaped braces, or invalid placeholder)"
+    };
+  }
+
+  if (maxArgIndex >= numArgs) {
+    return {
+      type: "arg-count-mismatch",
+      expected: maxArgIndex + 1, // Convert 0-based index to count
+      provided: numArgs
+    };
+  }
+
+  return undefined;
+}

languageservice/src/validate.block-scalar-warning.test.ts

@@ -0,0 +1,835 @@
+import {FeatureFlags} from "@actions/expressions";
+import {DiagnosticSeverity} from "vscode-languageserver-types";
+import {registerLogger} from "./log.js";
+import {createDocument} from "./test-utils/document.js";
+import {TestLogger} from "./test-utils/logger.js";
+import {clearCache} from "./utils/workflow-cache.js";
+import {validate, ValidationConfig} from "./validate.js";
+
+registerLogger(new TestLogger());
+
+const configWithFlag: ValidationConfig = {
+  featureFlags: new FeatureFlags({blockScalarChompingWarning: true})
+};
+
+beforeEach(() => {
+  clearCache();
+});
+
+describe("block scalar chomping - warning cases", () => {
+  describe("step-level env values", () => {
+    it("warns with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo $VAR
+        env:
+          VAR: |
+            \${{ matrix.value }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("does not warn with keep chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo $VAR
+        env:
+          VAR: |+
+            \${{ matrix.value }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("does not warn with strip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo $VAR
+        env:
+          VAR: |-
+            \${{ matrix.value }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("uses > indicator in warning message for folded scalars", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo $VAR
+        env:
+          VAR: >
+            \${{ matrix.value }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '>' implicitly adds a trailing newline that may be unintentional. Use '>-' to remove it, or '>+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("warns for plain string env value with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo $VAR
+        env:
+          VAR: |
+            hello world
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+  });
+
+  describe("job-level env values", () => {
+    it("warns with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MY_VAR: |
+        some value
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+  });
+
+  describe("workflow-level env values", () => {
+    it("warns with clip chomping", async () => {
+      const input = `
+on: push
+env:
+  GLOBAL_VAR: |
+    some value
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+  });
+
+  describe("container env values", () => {
+    it("warns with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: node:18
+      env:
+        CONTAINER_VAR: |
+          some value
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+  });
+
+  describe("service container env values", () => {
+    it("warns with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    services:
+      redis:
+        image: redis
+        env:
+          REDIS_PASSWORD: |
+            secret123
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+  });
+
+  describe("action input (with)", () => {
+    it("warns with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          script: |
+            \${{ matrix.value }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("does not warn with keep chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          script: |+
+            \${{ matrix.value }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("does not warn with strip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          script: |-
+            \${{ matrix.value }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+  });
+
+  describe("reusable workflow inputs (with)", () => {
+    it("warns with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  call-workflow:
+    uses: ./.github/workflows/reusable.yml
+    with:
+      my-input: |
+        some value
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+  });
+
+  describe("reusable workflow secrets", () => {
+    it("warns with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  call-workflow:
+    uses: ./.github/workflows/reusable.yml
+    secrets:
+      my-secret: |
+        \${{ secrets.TOKEN }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+  });
+
+  describe("job outputs", () => {
+    it("warns with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      my_output: |
+        \${{ steps.test.outputs.value }}
+    steps:
+      - id: test
+        run: echo "value=test" >> $GITHUB_OUTPUT
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("does not warn with strip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      my_output: |-
+        \${{ steps.test.outputs.value }}
+    steps:
+      - id: test
+        run: echo "value=test" >> $GITHUB_OUTPUT
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+  });
+
+  describe("matrix values", () => {
+    it("warns for matrix vector value with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        config:
+          - |
+            value1
+          - value2
+    steps:
+      - run: echo \${{ matrix.config }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("does not warn with strip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        config:
+          - |-
+            value1
+          - value2
+    steps:
+      - run: echo \${{ matrix.config }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("warns for matrix include value with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        include:
+          - os: |
+              windows-latest
+            special: true
+    steps:
+      - run: echo \${{ matrix.os }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("warns for matrix exclude value with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node: [16, 18]
+        exclude:
+          - os: |
+              windows-latest
+            node: 16
+    steps:
+      - run: echo \${{ matrix.os }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("warns for deeply nested matrix value with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        config:
+          - foo:
+              bar: |
+                baz
+    steps:
+      - run: echo \${{ matrix.config }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("warns for deeply nested matrix include value with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        include:
+          - os: ubuntu-latest
+            config:
+              nested: |
+                value
+    steps:
+      - run: echo \${{ matrix.config }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("warns for deeply nested matrix exclude value with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        exclude:
+          - os: windows-latest
+            config:
+              nested: |
+                value
+    steps:
+      - run: echo \${{ matrix.os }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+  });
+
+  describe("concurrency", () => {
+    it("warns for concurrency string with clip chomping", async () => {
+      const input = `
+on: push
+concurrency: |
+  my-group-\${{ github.ref }}
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("does not warn for concurrency with strip chomping", async () => {
+      const input = `
+on: push
+concurrency: |-
+  my-group-\${{ github.ref }}
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("warns for concurrency.group with clip chomping", async () => {
+      const input = `
+on: push
+concurrency:
+  group: |
+    my-group-\${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+
+    it("warns for job-level concurrency with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    concurrency: |
+      job-group-\${{ github.ref }}
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          message:
+            "Block scalar '|' implicitly adds a trailing newline that may be unintentional. Use '|-' to remove it, or '|+' to explicitly keep it.",
+          code: "block-scalar-chomping",
+          severity: DiagnosticSeverity.Warning
+        })
+      );
+    });
+  });
+});
+
+describe("block scalar chomping - no warning cases", () => {
+  describe("fields trimmed server-side", () => {
+    it("does not warn for job-if with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: |
+      github.ref == 'refs/heads/main'
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("does not warn for step-if with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo done
+        if: |
+          github.ref == 'refs/heads/main'
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("does not warn for runs-on with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: |
+      ubuntu-latest
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("does not warn for job name with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    name: |
+      My Job
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("does not warn for step name with clip chomping", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: |
+          My Step
+        run: echo done
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+  });
+
+  describe("run field (intentionally allowed)", () => {
+    it("does not warn for step run field", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          echo hello
+          echo world
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("does not warn for run field with expression", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          echo \${{ github.ref }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+  });
+
+  describe("non-block scalars", () => {
+    it("does not warn for quoted strings", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo $VAR
+        env:
+          VAR: "hello world"
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("does not warn for flow scalars", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo $VAR
+        env:
+          VAR: hello world
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+
+    it("does not warn for inline expressions", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo $VAR
+        env:
+          VAR: \${{ matrix.value }}
+`;
+      const result = await validate(createDocument("wf.yaml", input), configWithFlag);
+
+      expect(result.filter(d => d.code === "block-scalar-chomping")).toEqual([]);
+    });
+  });
+});

languageservice/src/validate.expressions-literal-text.test.ts

@@ -211,4 +211,104 @@ jobs:
       );
     });
   });
+
+  // https://github.com/github/vscode-github-actions/issues/542
+  describe("YAML-quoted expressions", () => {
+    it("allows double-quoted expression in job-if", async () => {
+      // Quotes are needed when the expression contains a colon
+      const input = `
+on: push
+jobs:
+  publish:
+    if: "\${{ startsWith(github.event.head_commit.message, 'chore: release') }}"
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hi
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+
+      expect(result).not.toContainEqual(
+        expect.objectContaining({
+          code: "expression-literal-text-in-condition"
+        })
+      );
+    });
+
+    it("allows single-quoted expression in job-if", async () => {
+      const input = `
+on: push
+jobs:
+  publish:
+    if: '\${{ startsWith(github.event.head_commit.message, "chore: release") }}'
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hi
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+
+      expect(result).not.toContainEqual(
+        expect.objectContaining({
+          code: "expression-literal-text-in-condition"
+        })
+      );
+    });
+
+    it("allows double-quoted expression in step-if", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - if: "\${{ contains(github.event.head_commit.message, 'skip: ci') }}"
+        run: echo hi
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+
+      expect(result).not.toContainEqual(
+        expect.objectContaining({
+          code: "expression-literal-text-in-condition"
+        })
+      );
+    });
+
+    it("still errors when there is actual literal text outside expression", async () => {
+      // Even with quotes, if there's literal text outside ${{ }}, it should error
+      const input = `
+on: push
+jobs:
+  build:
+    if: "push == \${{ github.event_name }}"
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hi
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          code: "expression-literal-text-in-condition"
+        })
+      );
+    });
+
+    it("errors on multiple expressions with literal text between them", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    if: "\${{ true }} and \${{ false }}"
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hi
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          code: "expression-literal-text-in-condition"
+        })
+      );
+    });
+  });
 });

languageservice/src/validate.format-string.test.ts

@@ -0,0 +1,273 @@
+import {DiagnosticSeverity} from "vscode-languageserver-types";
+import {createDocument} from "./test-utils/document.js";
+import {validate} from "./validate.js";
+import {clearCache} from "./utils/workflow-cache.js";
+import {validateFormatString} from "./validate-format-string.js";
+
+beforeEach(() => {
+  clearCache();
+});
+
+describe("format string validation", () => {
+  describe("validateFormatString unit tests", () => {
+    it("returns valid for simple placeholder", () => {
+      const result = validateFormatString("{0}");
+      expect(result).toEqual({valid: true, maxArgIndex: 0});
+    });
+
+    it("returns valid for multiple placeholders", () => {
+      const result = validateFormatString("{0} {1} {2}");
+      expect(result).toEqual({valid: true, maxArgIndex: 2});
+    });
+
+    it("returns valid for text with placeholder", () => {
+      const result = validateFormatString("hello {0} world");
+      expect(result).toEqual({valid: true, maxArgIndex: 0});
+    });
+
+    it("returns valid for escaped left braces", () => {
+      const result = validateFormatString("{{0}} {0}");
+      expect(result).toEqual({valid: true, maxArgIndex: 0});
+    });
+
+    it("returns valid for escaped right braces", () => {
+      const result = validateFormatString("{0}}}");
+      expect(result).toEqual({valid: true, maxArgIndex: 0});
+    });
+
+    it("returns valid for no placeholders", () => {
+      const result = validateFormatString("hello world");
+      expect(result).toEqual({valid: true, maxArgIndex: -1});
+    });
+
+    it("returns invalid for missing closing brace", () => {
+      const result = validateFormatString("{0");
+      expect(result).toEqual({valid: false, maxArgIndex: -1});
+    });
+
+    it("returns invalid for empty placeholder", () => {
+      const result = validateFormatString("{}");
+      expect(result).toEqual({valid: false, maxArgIndex: -1});
+    });
+
+    it("returns invalid for non-numeric placeholder", () => {
+      const result = validateFormatString("{abc}");
+      expect(result).toEqual({valid: false, maxArgIndex: -1});
+    });
+
+    it("returns invalid for unescaped closing brace", () => {
+      const result = validateFormatString("text } more");
+      expect(result).toEqual({valid: false, maxArgIndex: -1});
+    });
+
+    it("handles out-of-order placeholders", () => {
+      const result = validateFormatString("{2} {0} {1}");
+      expect(result).toEqual({valid: true, maxArgIndex: 2});
+    });
+
+    it("handles repeated placeholders", () => {
+      const result = validateFormatString("{0} {0} {0}");
+      expect(result).toEqual({valid: true, maxArgIndex: 0});
+    });
+  });
+
+  describe("InvalidFormatString workflow validation", () => {
+    it("errors on missing closing brace", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('{0', github.event_name) }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          code: "invalid-format-string",
+          severity: DiagnosticSeverity.Error
+        })
+      );
+    });
+
+    it("errors on empty braces", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('{}', github.event_name) }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          code: "invalid-format-string"
+        })
+      );
+    });
+
+    it("errors on non-numeric placeholder", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('{abc}', github.event_name) }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          code: "invalid-format-string"
+        })
+      );
+    });
+
+    it("allows valid format strings", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('{0} {1}', github.event_name, github.ref) }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      expect(result).not.toContainEqual(
+        expect.objectContaining({
+          code: "invalid-format-string"
+        })
+      );
+    });
+
+    it("allows escaped braces", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('{{0}} {0}', github.event_name) }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      expect(result).not.toContainEqual(
+        expect.objectContaining({
+          code: "invalid-format-string"
+        })
+      );
+    });
+  });
+
+  describe("FormatArgCountMismatch workflow validation", () => {
+    it("errors when placeholder exceeds arg count", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('{2}', 'arg0', 'arg1') }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          code: "format-arg-count-mismatch",
+          severity: DiagnosticSeverity.Error
+        })
+      );
+    });
+
+    it("errors when referencing arg 0 with no args", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('{0}') }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          code: "format-arg-count-mismatch"
+        })
+      );
+    });
+
+    it("allows when arg count matches", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('{0} {1} {2}', 'a', 'b', 'c') }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      expect(result).not.toContainEqual(
+        expect.objectContaining({
+          code: "format-arg-count-mismatch"
+        })
+      );
+    });
+
+    it("handles no placeholders correctly", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('hello world') }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      expect(result).not.toContainEqual(
+        expect.objectContaining({
+          code: "format-arg-count-mismatch"
+        })
+      );
+    });
+
+    it("skips validation for dynamic format strings", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format(env.FORMAT_STRING, 'arg') }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      // Should not have format errors since we can't validate dynamic strings
+      expect(result).not.toContainEqual(
+        expect.objectContaining({
+          code: "invalid-format-string"
+        })
+      );
+      expect(result).not.toContainEqual(
+        expect.objectContaining({
+          code: "format-arg-count-mismatch"
+        })
+      );
+    });
+
+    it("validates nested format calls", async () => {
+      const input = `
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ format('{0}', format('{2}', 'a')) }}
+`;
+      const result = await validate(createDocument("wf.yaml", input));
+      // The inner format call has an error
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          code: "format-arg-count-mismatch"
+        })
+      );
+    });
+  });
+});

languageservice/src/validate.ts

@@ -1,6 +1,6 @@
-import {Lexer, Parser, data} from "@actions/expressions";
+import {FeatureFlags, Lexer, Parser, data} from "@actions/expressions";
 import {Expr, FunctionCall, Literal, Logical} from "@actions/expressions/ast";
-import {ParseWorkflowResult, WorkflowTemplate, isBasicExpression, isMapping, isString} from "@actions/workflow-parser";
+import {TemplateParseResult, WorkflowTemplate, isBasicExpression, isMapping, isString} from "@actions/workflow-parser";
 import {ErrorPolicy} from "@actions/workflow-parser/model/convert";
 import {getCronDescription, hasCronIntervalLessThan5Minutes} from "@actions/workflow-parser/model/converter/cron";
 import {ensureStatusFunction} from "@actions/workflow-parser/model/converter/if-condition";
@@ -15,16 +15,19 @@ import {TextDocument} from "vscode-languageserver-textdocument";
 import {Diagnostic, DiagnosticSeverity, URI} from "vscode-languageserver-types";
 import {ActionMetadata, ActionReference} from "./action.js";
 import {ContextProviderConfig} from "./context-providers/config.js";
-import {Mode, getContext} from "./context-providers/default.js";
+import {Mode, getWorkflowExpressionContext} from "./context-providers/default.js";
 import {WorkflowContext, getWorkflowContext} from "./context/workflow-context.js";
 import {wrapDictionary} from "./expression-validation/error-dictionary.js";
 import {ValidationEvaluator} from "./expression-validation/evaluator.js";
 import {validatorFunctions} from "./expression-validation/functions.js";
 import {error} from "./log.js";
+import {isActionDocument} from "./utils/document-type.js";
 import {findToken} from "./utils/find-token.js";
 import {mapRange} from "./utils/range.js";
-import {fetchOrConvertWorkflowTemplate, fetchOrParseWorkflow} from "./utils/workflow-cache.js";
+import {getOrConvertWorkflowTemplate, getOrParseWorkflow} from "./utils/workflow-cache.js";
+import {validateActionReference} from "./validate-action-reference.js";
 import {validateAction} from "./validate-action.js";
+import {validateFormatCalls} from "./validate-format-string.js";
 import {ValueProviderConfig, ValueProviderKind} from "./value-providers/config.js";
 import {defaultValueProviders} from "./value-providers/default.js";
 
@@ -36,6 +39,7 @@ export type ValidationConfig = {
   contextProviderConfig?: ContextProviderConfig;
   actionsMetadataProvider?: ActionsMetadataProvider;
   fileProvider?: FileProvider;
+  featureFlags?: FeatureFlags;
 };
 
 export type ActionsMetadataProvider = {
@@ -43,12 +47,24 @@ export type ActionsMetadataProvider = {
 };
 
 /**
- * Validates a workflow file
+ * Validates a workflow or action file
  *
  * @param textDocument Document to validate
  * @returns Array of diagnostics
  */
 export async function validate(textDocument: TextDocument, config?: ValidationConfig): Promise<Diagnostic[]> {
+  return isActionDocument(textDocument.uri)
+    ? validateAction(textDocument, config)
+    : validateWorkflow(textDocument, config);
+}
+
+/**
+ * Validates a workflow file
+ *
+ * @param textDocument Document to validate
+ * @returns Array of diagnostics
+ */
+async function validateWorkflow(textDocument: TextDocument, config?: ValidationConfig): Promise<Diagnostic[]> {
   const file: File = {
     name: textDocument.uri,
     content: textDocument.getText()
@@ -57,20 +73,20 @@ export async function validate(textDocument: TextDocument, config?: ValidationCo
   const diagnostics: Diagnostic[] = [];
 
   try {
-    const result: ParseWorkflowResult | undefined = fetchOrParseWorkflow(file, textDocument.uri);
+    const result: TemplateParseResult | undefined = getOrParseWorkflow(file, textDocument.uri);
     if (!result) {
       return [];
     }
 
     if (result.value) {
       // Errors will be updated in the context. Attempt to do the conversion anyway in order to give the user more information
-      const template = await fetchOrConvertWorkflowTemplate(result.context, result.value, textDocument.uri, config, {
+      const template = await getOrConvertWorkflowTemplate(result.context, result.value, textDocument.uri, config, {
         fetchReusableWorkflowDepth: config?.fileProvider ? 1 : 0,
         errorPolicy: ErrorPolicy.TryConversion
       });
 
       // Validate expressions and value providers
-      await additionalValidations(diagnostics, textDocument.uri, template, result.value, config);
+      await additionalValidations(diagnostics, textDocument.uri, template, result.value, config, config?.featureFlags);
     }
 
     // For now map parser errors directly to diagnostics
@@ -94,9 +110,10 @@ async function additionalValidations(
   documentUri: URI,
   template: WorkflowTemplate,
   root: TemplateToken,
-  config?: ValidationConfig
+  config?: ValidationConfig,
+  featureFlags?: FeatureFlags
 ) {
-  for (const [parent, token, key] of TemplateToken.traverse(root)) {
+  for (const [parent, token, key, ancestors] of TemplateToken.traverse(root)) {
     // If  the token is a value in a pair, use the key definition for validation
     // If the token has a parent (map, sequence, etc), use this definition for validation
     const validationToken = key || parent || token;
@@ -114,7 +131,12 @@ async function additionalValidations(
       );
     }
 
-    // If this is a job-if, step-if, or snapshot-if field (which are strings that should be treated as expressions), validate it
+    // Validate block scalar chomping for expressions and strings
+    if (featureFlags?.isEnabled("blockScalarChompingWarning")) {
+      validateBlockScalarChomping(diagnostics, token, parent, key, ancestors);
+    }
+
+    // `if` conditions allow omitting ${{ }}, so validate strings in these fields as expressions
     const definitionKey = token.definition?.key;
     if (
       isString(token) &&
@@ -134,7 +156,9 @@ async function additionalValidations(
           finalCondition,
           token.definitionInfo,
           undefined,
-          token.source
+          token.source,
+          undefined,
+          token.blockScalarHeader
         );
 
         await validateExpression(
@@ -155,7 +179,7 @@ async function additionalValidations(
     // Validate action metadata (inputs, required fields) for regular steps
     if (token.definition?.key === "regular-step" && token.range) {
       const context = getProviderContext(documentUri, template, root, token.range);
-      await validateAction(diagnostics, token, context.step, config);
+      await validateActionReference(diagnostics, token, context.step, config);
     }
 
     // Validate job-level reusable workflow uses field format
@@ -180,7 +204,7 @@ async function additionalValidations(
     if (token.range && validationDefinition) {
       const defKey = validationDefinition.key;
       if (defKey === "step-with") {
-        // Action inputs should be validated already in validateAction
+        // Action inputs should be validated already in validateActionReference
         continue;
       }
 
@@ -721,7 +745,34 @@ async function validateExpression(
       continue;
     }
 
-    const context = await getContext(namedContexts, contextProviderConfig, workflowContext, Mode.Validation);
+    // Validate format() function calls
+    const formatErrors = validateFormatCalls(expr);
+    for (const formatError of formatErrors) {
+      if (formatError.type === "invalid-syntax") {
+        diagnostics.push({
+          message: `Invalid format string: ${formatError.message}`,
+          range: mapRange(expression.range),
+          severity: DiagnosticSeverity.Error,
+          code: "invalid-format-string"
+        });
+      } else if (formatError.type === "arg-count-mismatch") {
+        diagnostics.push({
+          message: `Format string references argument {${formatError.expected - 1}} but only ${
+            formatError.provided
+          } argument(s) provided`,
+          range: mapRange(expression.range),
+          severity: DiagnosticSeverity.Error,
+          code: "format-arg-count-mismatch"
+        });
+      }
+    }
+
+    const context = await getWorkflowExpressionContext(
+      namedContexts,
+      contextProviderConfig,
+      workflowContext,
+      Mode.Validation
+    );
 
     const e = new ValidationEvaluator(expr, wrapDictionary(context), validatorFunctions);
     e.validate();
@@ -803,3 +854,90 @@ function getStaticConcurrencyGroup(token: TemplateToken | undefined): StringToke
 
   return undefined;
 }
+
+/**
+ * Validates YAML block scalar chomping.
+ *
+ * Block scalars (| and >) implicitly add a trailing newline by default ("clip" chomping).
+ * This is often unintended by the workflow author and can cause unexpected behavior.
+ * This function warns on certain fields when clip chomping is used (implicit trailing newline)
+ * and suggests they explicitly use strip (|-) or keep (|+) to clarify intent.
+ *
+ * Only specific fields are validated - those where trailing newlines may cause
+ * issues but aren't automatically trimmed server-side. For example env, inputs, outputs, etc.
+ *
+ * Skipped fields:
+ * - run: Multi-line scripts commonly have trailing newlines
+ * - Fields trimmed server-side: name, uses, shell, if, etc.
+ */
+function validateBlockScalarChomping(
+  diagnostics: Diagnostic[],
+  token: TemplateToken,
+  parent: TemplateToken | undefined,
+  key: TemplateToken | undefined,
+  ancestors: TemplateToken[]
+): void {
+  // Not an expression or string?
+  if (!isBasicExpression(token) && !isString(token)) {
+    return;
+  }
+
+  // Not a block scalar?
+  const header = token.blockScalarHeader;
+  if (!header) {
+    return;
+  }
+
+  // Not "clip" chomp style?
+  if (header.includes("+") || header.includes("-")) {
+    return;
+  }
+
+  // Check if we should warn
+  let shouldWarn = false;
+  const parentDefinitionName = parent?.definition?.key;
+  const tokenDefinitionName = token.definition?.key;
+  const keyName = key && isString(key) ? key.value : undefined;
+  if (
+    parentDefinitionName &&
+    [
+      "workflow-env",
+      "job-env",
+      "step-env",
+      "container-env",
+      "step-with",
+      "job-outputs",
+      "workflow-job-with",
+      "workflow-job-secrets"
+    ].includes(parentDefinitionName)
+  ) {
+    // env, with, outputs, or secrets fields
+    shouldWarn = true;
+  } else if (
+    ancestors.some(ancestor => {
+      const ancestorKey = ancestor.definition?.key;
+      return ancestorKey === "matrix" || ancestorKey === "matrix-filter" || ancestorKey === "matrix-filter-item";
+    })
+  ) {
+    // Matrix values (vectors, include, exclude)
+    shouldWarn = true;
+  } else if (tokenDefinitionName && ["workflow-concurrency", "job-concurrency"].includes(tokenDefinitionName)) {
+    // Concurrency shorthand
+    shouldWarn = true;
+  } else if (keyName === "group" && parentDefinitionName === "concurrency-mapping") {
+    // Concurrency group field
+    shouldWarn = true;
+  }
+
+  if (!shouldWarn) {
+    return;
+  }
+
+  const blockIndicator = header.startsWith("|") ? "|" : ">";
+  diagnostics.push({
+    message: `Block scalar '${blockIndicator}' implicitly adds a trailing newline that may be unintentional. Use '${blockIndicator}-' to remove it, or '${blockIndicator}+' to explicitly keep it.`,
+    range: mapRange(token.range),
+    severity: DiagnosticSeverity.Warning,
+    code: "block-scalar-chomping"
+  });
+}

languageservice/src/value-providers/config.ts

@@ -7,8 +7,8 @@ export interface Value {
   /** Optional description to show when auto-completing */
   description?: string;
 
-  /** Optional detail shown after the label, e.g. type or kind information */
-  detail?: string;
+  /** Optional qualifier shown inline after the label, e.g. "full syntax" or "list" */
+  labelDetail?: string;
 
   /** Whether this value is deprecated */
   deprecated?: boolean;
@@ -27,6 +27,12 @@ export interface Value {
     range: {start: {line: number; character: number}; end: {line: number; character: number}};
     newText: string;
   };
+
+  /** Additional text edits to apply after the main edit (e.g., cleanup edits) */
+  additionalTextEdits?: {
+    range: {start: {line: number; character: number}; end: {line: number; character: number}};
+    newText: string;
+  }[];
 }
 
 export enum ValueProviderKind {

languageservice/src/value-providers/definition.ts

@@ -6,7 +6,7 @@ import {MappingDefinition} from "@actions/workflow-parser/templates/schema/mappi
 import {OneOfDefinition} from "@actions/workflow-parser/templates/schema/one-of-definition";
 import {SequenceDefinition} from "@actions/workflow-parser/templates/schema/sequence-definition";
 import {StringDefinition} from "@actions/workflow-parser/templates/schema/string-definition";
-import {getWorkflowSchema} from "@actions/workflow-parser/workflows/workflow-schema";
+import {TemplateSchema} from "@actions/workflow-parser/templates/schema/template-schema";
 import {Value} from "./config.js";
 import {stringsToValues} from "./strings-to-values.js";
 
@@ -47,21 +47,21 @@ export type TokenStructure = "scalar" | "sequence" | "mapping" | undefined;
  * @param tokenStructure - If provided, filters completions to only those matching
  *   the YAML structure the user has already started (e.g., only mapping keys if
  *   they've started a mapping)
+ * @param schema - The schema to use for definition lookups
  */
 export function definitionValues(
   def: Definition,
   indentation: string,
   mode: DefinitionValueMode,
-  tokenStructure?: TokenStructure
+  tokenStructure: TokenStructure | undefined,
+  schema: TemplateSchema
 ): Value[] {
-  const schema = getWorkflowSchema();
-
   if (def instanceof MappingDefinition) {
     return mappingValues(def, schema.definitions, indentation, mode);
   }
 
   if (def instanceof OneOfDefinition) {
-    return oneOfValues(def, schema.definitions, indentation, mode, tokenStructure);
+    return oneOfValues(def, schema.definitions, indentation, mode, tokenStructure, schema);
   }
 
   if (def instanceof BooleanDefinition) {
@@ -80,7 +80,7 @@ export function definitionValues(
   if (def instanceof SequenceDefinition) {
     const itemDef = schema.getDefinition(def.itemType);
     if (itemDef) {
-      return definitionValues(itemDef, indentation, mode);
+      return definitionValues(itemDef, indentation, mode, undefined, schema);
     }
   }
 
@@ -107,10 +107,14 @@ function mappingValues(
   for (const [key, value] of Object.entries(mappingDefinition.properties)) {
     let insertText: string | undefined;
 
-    let description: string | undefined;
+    // Prefer the property's own description (from the schema's property definition),
+    // fall back to the type definition's description if the property doesn't have one
+    let description: string | undefined = value.description;
     if (value.type) {
       const typeDef = definitions[value.type];
-      description = typeDef?.description;
+      if (!description) {
+        description = typeDef?.description;
+      }
 
       if (typeDef) {
         switch (typeDef.definitionType) {
@@ -177,7 +181,8 @@ function oneOfValues(
   definitions: {[key: string]: Definition},
   indentation: string,
   mode: DefinitionValueMode,
-  tokenStructure?: TokenStructure
+  tokenStructure: TokenStructure | undefined,
+  schema: TemplateSchema
 ): Value[] {
   const values: Value[] = [];
   for (const key of oneOfDefinition.oneOf) {
@@ -209,20 +214,20 @@ function oneOfValues(
       }
     }
 
-    values.push(...definitionValues(variantDef, indentation, mode, tokenStructure));
+    values.push(...definitionValues(variantDef, indentation, mode, tokenStructure, schema));
   }
   return distinctValues(values);
 }
 
 /**
- * Deduplicates values by label and detail.
- * Values with the same label but different details are preserved as distinct items.
+ * Deduplicates values by label and labelDetail.
+ * Values with the same label but different labelDetails are preserved as distinct items.
  */
 function distinctValues(values: Value[]): Value[] {
   const map = new Map<string, Value>();
   for (const value of values) {
-    // Include detail in the key to preserve variants with different details
-    const key = value.detail ? `${value.label}\0${value.detail}` : value.label;
+    // Include labelDetail in the key to preserve variants with different details
+    const key = value.labelDetail ? `${value.label}\0${value.labelDetail}` : value.label;
     map.set(key, value);
   }
   return Array.from(map.values());
@@ -325,7 +330,7 @@ function expandOneOfToCompletions(
     results.push({
       label: key,
       description,
-      detail: needsQualifier ? "list" : undefined,
+      labelDetail: needsQualifier ? "list" : undefined,
       insertText,
       sortText: needsQualifier ? `${key} 1` : undefined
     });
@@ -339,7 +344,7 @@ function expandOneOfToCompletions(
     results.push({
       label: key,
       description,
-      detail: needsQualifier ? "full syntax" : undefined,
+      labelDetail: needsQualifier ? "full syntax" : undefined,
       insertText,
       sortText: needsQualifier ? `${key} 2` : undefined
     });

lerna.json

@@ -6,5 +6,5 @@
     "languageservice",
     "languageserver"
   ],
-  "version": "0.3.30"
+  "version": "0.3.36"
 }

package-lock.json

@@ -136,7 +136,7 @@
     },
     "expressions": {
       "name": "@actions/expressions",
-      "version": "0.3.30",
+      "version": "0.3.36",
       "license": "MIT",
       "devDependencies": {
         "@types/jest": "^29.0.3",
@@ -396,11 +396,11 @@
     },
     "languageserver": {
       "name": "@actions/languageserver",
-      "version": "0.3.30",
+      "version": "0.3.36",
       "license": "MIT",
       "dependencies": {
-        "@actions/languageservice": "^0.3.30",
-        "@actions/workflow-parser": "^0.3.30",
+        "@actions/languageservice": "^0.3.36",
+        "@actions/workflow-parser": "^0.3.36",
         "@octokit/rest": "^21.1.1",
         "@octokit/types": "^9.0.0",
         "vscode-languageserver": "^8.0.2",
@@ -940,11 +940,11 @@
     },
     "languageservice": {
       "name": "@actions/languageservice",
-      "version": "0.3.30",
+      "version": "0.3.36",
       "license": "MIT",
       "dependencies": {
-        "@actions/expressions": "^0.3.30",
-        "@actions/workflow-parser": "^0.3.30",
+        "@actions/expressions": "^0.3.36",
+        "@actions/workflow-parser": "^0.3.36",
         "vscode-languageserver-textdocument": "^1.0.7",
         "vscode-languageserver-types": "^3.17.2",
         "vscode-uri": "^3.0.8",
@@ -13345,10 +13345,10 @@
     },
     "workflow-parser": {
       "name": "@actions/workflow-parser",
-      "version": "0.3.30",
+      "version": "0.3.36",
       "license": "MIT",
       "dependencies": {
-        "@actions/expressions": "^0.3.30",
+        "@actions/expressions": "^0.3.36",
         "cronstrue": "^2.21.0",
         "yaml": "^2.0.0-8"
       },

workflow-parser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actions/workflow-parser",
-  "version": "0.3.30",
+  "version": "0.3.36",
   "license": "MIT",
   "type": "module",
   "source": "./src/index.ts",
@@ -36,9 +36,9 @@
     "clean": "rimraf dist",
     "format": "prettier --write '**/*.ts'",
     "format-check": "prettier --check '**/*.ts'",
-    "lint": "eslint 'src/**/*.ts'",
+    "lint": "eslint --max-warnings 0 'src/**/*.ts'",
     "lint-fix": "eslint --fix 'src/**/*.ts'",
-    "minify-json": "node ../script/minify-json.js src/workflow-v1.0.json",
+    "minify-json": "node ../script/minify-json.js src/workflow-v1.0.json && node ../script/minify-json.js src/action-v1.0.json",
     "prebuild": "npm run minify-json",
     "prepublishOnly": "npm run build && npm run test",
     "pretest": "npm run minify-json",
@@ -48,7 +48,7 @@
     "watch": "tsc --build tsconfig.build.json --watch"
   },
   "dependencies": {
-    "@actions/expressions": "^0.3.30",
+    "@actions/expressions": "^0.3.36",
     "cronstrue": "^2.21.0",
     "yaml": "^2.0.0-8"
   },

workflow-parser/src/action-v1.0.json

@@ -0,0 +1,557 @@
+{
+  "definitions": {
+    "action-root": {
+      "description": "Action file",
+      "mapping": {
+        "properties": {
+          "name": "string",
+          "description": "string",
+          "inputs": "inputs",
+          "outputs": "outputs",
+          "runs": "runs"
+        },
+        "loose-key-type": "non-empty-string",
+        "loose-value-type": "any"
+      }
+    },
+    "action-root-strict": {
+      "description": "GitHub Action manifest file (action.yml/action.yaml) that defines an action's metadata, inputs, outputs, and execution configuration.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions)",
+      "mapping": {
+        "properties": {
+          "name": {
+            "type": "non-empty-string",
+            "required": true,
+            "description": "The name of your action. GitHub displays the name in the Actions tab to help visually identify actions in each job.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#name)"
+          },
+          "description": {
+            "type": "string",
+            "required": true,
+            "description": "A short description of the action. GitHub displays this description in the Actions Marketplace.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#description)"
+          },
+          "author": {
+            "type": "string",
+            "description": "The name of the action's author.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#author)"
+          },
+          "inputs": "inputs-strict",
+          "outputs": "outputs",
+          "runs": {
+            "type": "runs-strict",
+            "required": true
+          },
+          "branding": "branding"
+        }
+      }
+    },
+    "inputs": {
+      "mapping": {
+        "loose-key-type": "non-empty-string",
+        "loose-value-type": "input"
+      }
+    },
+    "inputs-strict": {
+      "description": "Input parameters allow you to specify data that the action expects to use during runtime. GitHub stores input parameters as environment variables. Inputs ids with uppercase letters are converted to lowercase during runtime.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#inputs)",
+      "mapping": {
+        "loose-key-type": "non-empty-string",
+        "loose-value-type": "input-strict"
+      }
+    },
+    "input": {
+      "mapping": {
+        "properties": {
+          "default": "input-default-context"
+        },
+        "loose-key-type": "non-empty-string",
+        "loose-value-type": "any"
+      }
+    },
+    "input-strict": {
+      "description": "An input parameter for this action.",
+      "mapping": {
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "A string description of the input parameter.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#inputsinput_iddescription)"
+          },
+          "required": {
+            "type": "boolean",
+            "description": "A boolean to indicate whether the action requires the input parameter. Set to true when the parameter is required.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#inputsinput_idrequired)"
+          },
+          "default": {
+            "type": "input-default-context",
+            "description": "A string representing the default value. The default value is used when an input parameter isn't specified in a workflow file.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#inputsinput_iddefault)"
+          },
+          "deprecationMessage": {
+            "type": "string",
+            "description": "A string shown to users using the deprecated input, warning them that the input is deprecated and mentioning any alternatives.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#inputsinput_iddeprecationmessage)"
+          }
+        },
+        "loose-key-type": "non-empty-string",
+        "loose-value-type": "any"
+      }
+    },
+    "input-default-context": {
+      "description": "A string representing the default value. The default value is used when an input parameter isn't specified in a workflow file.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#inputsinput_iddefault)",
+      "context": [
+        "github",
+        "strategy",
+        "matrix",
+        "job",
+        "runner",
+        "hashFiles(1,255)"
+      ],
+      "string": {}
+    },
+    "outputs": {
+      "description": "Output parameters allow you to declare data that an action sets. Actions that run later in a workflow can use the output data set in previously run actions.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-actions)",
+      "mapping": {
+        "loose-key-type": "non-empty-string",
+        "loose-value-type": "output-definition"
+      }
+    },
+    "output-definition": {
+      "description": "An output parameter for this action.",
+      "mapping": {
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "A string description of the output parameter.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#outputsoutput_iddescription)"
+          },
+          "value": {
+            "type": "output-value",
+            "description": "The value that the output parameter will be mapped to. You can set this to a string or an expression with context.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#outputsoutput_idvalue)"
+          }
+        }
+      }
+    },
+    "output-value": {
+      "description": "The value that the output parameter will be mapped to. You can set this to a string or an expression with context.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#outputsoutput_idvalue)",
+      "context": [
+        "github",
+        "strategy",
+        "matrix",
+        "steps",
+        "inputs",
+        "job",
+        "runner",
+        "env"
+      ],
+      "string": {}
+    },
+    "runs": {
+      "one-of": [
+        "container-runs",
+        "node-runs",
+        "composite-runs",
+        "plugin-runs"
+      ]
+    },
+    "runs-strict": {
+      "description": "Specifies whether this is a JavaScript action, a composite action, or a Docker container action and how the action is executed.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runs)",
+      "one-of": [
+        "container-runs-strict",
+        "node-runs-strict",
+        "composite-runs-strict"
+      ]
+    },
+    "plugin-runs": {
+      "mapping": {
+        "properties": {
+          "plugin": "non-empty-string"
+        }
+      }
+    },
+    "container-runs": {
+      "mapping": {
+        "properties": {
+          "using": "non-empty-string",
+          "image": "non-empty-string",
+          "entrypoint": "non-empty-string",
+          "args": "container-runs-args",
+          "env": "container-runs-env",
+          "pre-entrypoint": "non-empty-string",
+          "pre-if": "non-empty-string",
+          "post-entrypoint": "non-empty-string",
+          "post-if": "non-empty-string"
+        }
+      }
+    },
+    "container-runs-args": {
+      "description": "An array of strings that define the inputs for a Docker container. Inputs can include hardcoded strings. GitHub passes the args to the container's ENTRYPOINT when the container starts up.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsargs)",
+      "sequence": {
+        "item-type": "container-runs-context"
+      }
+    },
+    "container-runs-env": {
+      "description": "Specifies a key/value map of environment variables to set in the container environment.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsenv)",
+      "context": [
+        "inputs"
+      ],
+      "mapping": {
+        "loose-key-type": "non-empty-string",
+        "loose-value-type": "string"
+      }
+    },
+    "container-runs-context": {
+      "context": [
+        "inputs"
+      ],
+      "string": {}
+    },
+    "node-runs": {
+      "mapping": {
+        "properties": {
+          "using": "non-empty-string",
+          "main": "non-empty-string",
+          "pre": "non-empty-string",
+          "pre-if": "non-empty-string",
+          "post": "non-empty-string",
+          "post-if": "non-empty-string"
+        }
+      }
+    },
+    "composite-runs": {
+      "mapping": {
+        "properties": {
+          "using": "non-empty-string",
+          "steps": "composite-steps"
+        }
+      }
+    },
+    "container-runs-strict": {
+      "description": "Configuration for Docker container actions.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runs)",
+      "mapping": {
+        "properties": {
+          "using": {
+            "type": "using",
+            "required": true,
+            "description": "The runtime used to execute the action. Must be docker for Docker container actions.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsusing)"
+          },
+          "image": {
+            "type": "non-empty-string",
+            "required": true,
+            "description": "The Docker image to use as the container to run the action. The value can be the Docker base image name, a local Dockerfile in your repository, or a public image in Docker Hub or another registry.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsimage)"
+          },
+          "entrypoint": {
+            "type": "non-empty-string",
+            "description": "Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsentrypoint)"
+          },
+          "args": "container-runs-args",
+          "env": "container-runs-env",
+          "pre-entrypoint": {
+            "type": "non-empty-string",
+            "description": "Allows you to run a script before the entrypoint action begins.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runspre-entrypoint)"
+          },
+          "pre-if": {
+            "type": "non-empty-string",
+            "description": "Allows you to define conditions for the pre: action execution. The pre: action will only run if the conditions in pre-if are met. If not set, then pre-if defaults to always().\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runspre-if)"
+          },
+          "post-entrypoint": {
+            "type": "non-empty-string",
+            "description": "Allows you to run a cleanup script once the runs.entrypoint action has completed.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runspost-entrypoint)"
+          },
+          "post-if": {
+            "type": "non-empty-string",
+            "description": "Allows you to define conditions for the post: action execution. The post: action will only run if the conditions in post-if are met. If not set, then post-if defaults to always().\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runspost-if)"
+          }
+        }
+      }
+    },
+    "node-runs-strict": {
+      "description": "Configuration for JavaScript actions executed with Node.js.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runs)",
+      "mapping": {
+        "properties": {
+          "using": {
+            "type": "using",
+            "required": true,
+            "description": "The runtime used to execute the action. Use node20 or node24 for JavaScript actions.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsusing)"
+          },
+          "main": {
+            "type": "non-empty-string",
+            "required": true,
+            "description": "The file that contains your action code. The runtime specified in using executes this file.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsmain)"
+          },
+          "pre": {
+            "type": "non-empty-string",
+            "description": "Allows you to run a script at the start of a job, before the main: action begins. You can use pre: to run prerequisite setup scripts.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runspre)"
+          },
+          "pre-if": {
+            "type": "non-empty-string",
+            "description": "Allows you to define conditions for the pre: action execution. The pre: action will only run if the conditions in pre-if are met. If not set, then pre-if defaults to always().\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runspre-if)"
+          },
+          "post": {
+            "type": "non-empty-string",
+            "description": "Allows you to run a script at the end of a job, once the main: action has completed. You can use post: to run cleanup scripts.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runspost)"
+          },
+          "post-if": {
+            "type": "non-empty-string",
+            "description": "Allows you to define conditions for the post: action execution. The post: action will only run if the conditions in post-if are met. If not set, then post-if defaults to always().\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runspost-if)"
+          }
+        }
+      }
+    },
+    "composite-runs-strict": {
+      "description": "Configuration for composite actions that run multiple steps.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runs)",
+      "mapping": {
+        "properties": {
+          "using": {
+            "type": "using",
+            "required": true,
+            "description": "The runtime used to execute the action. Must be composite for composite actions.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsusing)"
+          },
+          "steps": {
+            "type": "composite-steps",
+            "required": true
+          }
+        }
+      }
+    },
+    "composite-steps": {
+      "description": "The steps that you plan to run in this action. These can be either run steps or uses steps.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runssteps)",
+      "sequence": {
+        "item-type": "composite-step"
+      }
+    },
+    "composite-step": {
+      "description": "A step within a composite action.",
+      "one-of": [
+        "run-step",
+        "uses-step"
+      ]
+    },
+    "run-step": {
+      "description": "Runs a command-line program using the operating system's shell.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsrun)",
+      "mapping": {
+        "properties": {
+          "name": {
+            "type": "string-steps-context",
+            "description": "A name for your step to display on GitHub.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsname)"
+          },
+          "id": {
+            "type": "non-empty-string",
+            "description": "A unique identifier for the step. You can use the id to reference the step in contexts.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsid)"
+          },
+          "if": {
+            "type": "step-if",
+            "description": "You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsif)"
+          },
+          "run": {
+            "type": "string-steps-context",
+            "required": true,
+            "description": "The command you want to run. This can be inline or a script in your action repository.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsrun)"
+          },
+          "shell": {
+            "type": "string-steps-context",
+            "required": true,
+            "description": "The shell where you want to run the command. Any shell supported by the runner can be used. Required if run is set.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsshell)"
+          },
+          "env": "step-env",
+          "continue-on-error": {
+            "type": "boolean-steps-context",
+            "description": "Prevents the action from failing when a step fails. Set to true to allow the action to pass when this step fails.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepscontinue-on-error)"
+          },
+          "working-directory": {
+            "type": "string-steps-context",
+            "description": "Specifies the working directory where the command is run.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsworking-directory)"
+          }
+        }
+      }
+    },
+    "uses-step": {
+      "description": "Runs another action as part of a step in your action.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsuses)",
+      "mapping": {
+        "properties": {
+          "name": {
+            "type": "string-steps-context",
+            "description": "A name for your step to display on GitHub.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsname)"
+          },
+          "id": {
+            "type": "non-empty-string",
+            "description": "A unique identifier for the step. You can use the id to reference the step in contexts.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsid)"
+          },
+          "if": {
+            "type": "step-if",
+            "description": "You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsif)"
+          },
+          "uses": {
+            "type": "non-empty-string",
+            "required": true,
+            "description": "Selects an action to run as part of a step in your action. An action is a reusable unit of code.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsuses)"
+          },
+          "with": "step-with",
+          "env": "step-env",
+          "continue-on-error": {
+            "type": "boolean-steps-context",
+            "description": "Prevents the action from failing when a step fails. Set to true to allow the action to pass when this step fails.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepscontinue-on-error)"
+          }
+        }
+      }
+    },
+    "string-steps-context": {
+      "context": [
+        "github",
+        "inputs",
+        "strategy",
+        "matrix",
+        "steps",
+        "job",
+        "runner",
+        "env",
+        "hashFiles(1,255)"
+      ],
+      "string": {}
+    },
+    "boolean-steps-context": {
+      "context": [
+        "github",
+        "inputs",
+        "strategy",
+        "matrix",
+        "steps",
+        "job",
+        "runner",
+        "env",
+        "hashFiles(1,255)"
+      ],
+      "boolean": {}
+    },
+    "step-env": {
+      "description": "Sets variables for steps to use in the runner environment. You can also set variables for the entire action.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsenv)",
+      "context": [
+        "github",
+        "inputs",
+        "strategy",
+        "matrix",
+        "steps",
+        "job",
+        "runner",
+        "env",
+        "hashFiles(1,255)"
+      ],
+      "mapping": {
+        "loose-key-type": "non-empty-string",
+        "loose-value-type": "string"
+      }
+    },
+    "step-if": {
+      "description": "You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsif)",
+      "context": [
+        "github",
+        "inputs",
+        "strategy",
+        "matrix",
+        "steps",
+        "job",
+        "runner",
+        "env",
+        "always(0,0)",
+        "failure(0,0)",
+        "cancelled(0,0)",
+        "success(0,0)",
+        "hashFiles(1,255)"
+      ],
+      "string": {}
+    },
+    "step-with": {
+      "description": "A map of the input parameters defined by the action. Each input parameter is a key/value pair.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#runsstepswith)",
+      "context": [
+        "github",
+        "inputs",
+        "strategy",
+        "matrix",
+        "steps",
+        "job",
+        "runner",
+        "env",
+        "hashFiles(1,255)"
+      ],
+      "mapping": {
+        "loose-key-type": "non-empty-string",
+        "loose-value-type": "string"
+      }
+    },
+    "branding": {
+      "description": "You can use a color and Feather icon to create a badge to personalize and distinguish your action in GitHub Marketplace.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#branding)",
+      "mapping": {
+        "properties": {
+          "icon": {
+            "type": "branding-icon",
+            "description": "The name of the v4.28.0 Feather icon to use.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#brandingicon)"
+          },
+          "color": {
+            "type": "branding-color",
+            "description": "The background color of the badge.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#brandingcolor)"
+          }
+        }
+      }
+    },
+    "branding-icon": {
+      "description": "The name of the v4.28.0 Feather icon to use. Brand icons are omitted as well as: coffee, columns, divide-circle, divide-square, divide, frown, hexagon, key, meh, mouse-pointer, smile, tool, x-octagon.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#brandingicon)",
+      "allowed-values": [
+        "activity", "airplay", "alert-circle", "alert-octagon", "alert-triangle",
+        "align-center", "align-justify", "align-left", "align-right", "anchor",
+        "aperture", "archive", "arrow-down-circle", "arrow-down-left", "arrow-down-right",
+        "arrow-down", "arrow-left-circle", "arrow-left", "arrow-right-circle", "arrow-right",
+        "arrow-up-circle", "arrow-up-left", "arrow-up-right", "arrow-up", "at-sign",
+        "award", "bar-chart-2", "bar-chart", "battery-charging", "battery",
+        "bell-off", "bell", "bluetooth", "bold", "book-open",
+        "book", "bookmark", "box", "briefcase", "calendar",
+        "camera-off", "camera", "cast", "check-circle", "check-square",
+        "check", "chevron-down", "chevron-left", "chevron-right", "chevron-up",
+        "chevrons-down", "chevrons-left", "chevrons-right", "chevrons-up", "circle",
+        "clipboard", "clock", "cloud-drizzle", "cloud-lightning", "cloud-off",
+        "cloud-rain", "cloud-snow", "cloud", "code", "command",
+        "compass", "copy", "corner-down-left", "corner-down-right", "corner-left-down",
+        "corner-left-up", "corner-right-down", "corner-right-up", "corner-up-left", "corner-up-right",
+        "cpu", "credit-card", "crop", "crosshair", "database",
+        "delete", "disc", "dollar-sign", "download-cloud", "download",
+        "droplet", "edit-2", "edit-3", "edit", "external-link",
+        "eye-off", "eye", "fast-forward", "feather", "file-minus",
+        "file-plus", "file-text", "file", "film", "filter",
+        "flag", "folder-minus", "folder-plus", "folder", "gift",
+        "git-branch", "git-commit", "git-merge", "git-pull-request", "globe",
+        "grid", "hard-drive", "hash", "headphones", "heart",
+        "help-circle", "home", "image", "inbox", "info",
+        "italic", "layers", "layout", "life-buoy", "link-2",
+        "link", "list", "loader", "lock", "log-in",
+        "log-out", "mail", "map-pin", "map", "maximize-2",
+        "maximize", "menu", "message-circle", "message-square", "mic-off",
+        "mic", "minimize-2", "minimize", "minus-circle", "minus-square",
+        "minus", "monitor", "moon", "more-horizontal", "more-vertical",
+        "move", "music", "navigation-2", "navigation", "octagon",
+        "package", "paperclip", "pause-circle", "pause", "percent",
+        "phone-call", "phone-forwarded", "phone-incoming", "phone-missed", "phone-off",
+        "phone-outgoing", "phone", "pie-chart", "play-circle", "play",
+        "plus-circle", "plus-square", "plus", "pocket", "power",
+        "printer", "radio", "refresh-ccw", "refresh-cw", "repeat",
+        "rewind", "rotate-ccw", "rotate-cw", "rss", "save",
+        "scissors", "search", "send", "server", "settings",
+        "share-2", "share", "shield-off", "shield", "shopping-bag",
+        "shopping-cart", "shuffle", "sidebar", "skip-back", "skip-forward",
+        "slash", "sliders", "smartphone", "speaker", "square",
+        "star", "stop-circle", "sun", "sunrise", "sunset",
+        "tablet", "tag", "target", "terminal", "thermometer",
+        "thumbs-down", "thumbs-up", "toggle-left", "toggle-right", "trash-2",
+        "trash", "trending-down", "trending-up", "triangle", "truck",
+        "tv", "type", "umbrella", "underline", "unlock",
+        "upload-cloud", "upload", "user-check", "user-minus", "user-plus",
+        "user-x", "user", "users", "video-off", "video",
+        "voicemail", "volume-1", "volume-2", "volume-x", "volume",
+        "watch", "wifi-off", "wifi", "wind", "x-circle",
+        "x-square", "x", "zap-off", "zap", "zoom-in", "zoom-out"
+      ]
+    },
+    "branding-color": {
+      "description": "The background color of the badge.\n\n[Documentation](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#brandingcolor)",
+      "allowed-values": ["white", "yellow", "blue", "green", "orange", "red", "purple", "gray-dark"]
+    },
+    "using": {
+      "description": "The runtime used to execute the action.",
+      "allowed-values": ["docker", "node12", "node16", "node20", "node24", "composite"]
+    },
+    "non-empty-string": {
+      "string": {
+        "require-non-empty": true
+      }
+    }
+  }
+}

workflow-parser/src/actions/action-constants.ts

@@ -0,0 +1 @@
+export const ACTION_ROOT = "action-root-strict";

workflow-parser/src/actions/action-parser.test.ts

@@ -0,0 +1,320 @@
+import {parseAction} from "./action-parser.js";
+import {convertActionTemplate} from "./action-template.js";
+import {nullTrace} from "../test-utils/null-trace.js";
+
+describe("parseAction", () => {
+  it("parses a minimal action.yml", () => {
+    const content = `
+name: My Action
+description: A simple action
+runs:
+  using: composite
+  steps:
+    - run: echo Hello
+      shell: bash`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    expect(result.context.errors.count).toBe(0);
+    expect(result.value).toBeDefined();
+  });
+
+  it("parses a JavaScript action", () => {
+    const content = `
+name: JS Action
+description: A JavaScript action
+runs:
+  using: node20
+  main: dist/index.js
+  pre: dist/setup.js
+  post: dist/cleanup.js`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    expect(result.context.errors.count).toBe(0);
+    expect(result.value).toBeDefined();
+  });
+
+  it("parses a Docker action", () => {
+    const content = `
+name: Docker Action
+description: A Docker action
+runs:
+  using: docker
+  image: Dockerfile
+  args:
+    - \${{ inputs.name }}
+  env:
+    DEBUG: "true"`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    expect(result.context.errors.count).toBe(0);
+    expect(result.value).toBeDefined();
+  });
+
+  it("parses action with inputs and outputs", () => {
+    const content = `
+name: Action with I/O
+description: Action with inputs and outputs
+inputs:
+  name:
+    description: The name to greet
+    required: true
+    default: World
+  verbose:
+    description: Enable verbose mode
+    required: false
+outputs:
+  greeting:
+    description: The greeting message
+    value: \${{ steps.greet.outputs.message }}
+runs:
+  using: composite
+  steps:
+    - id: greet
+      run: echo "::set-output name=message::Hello \${{ inputs.name }}"
+      shell: bash`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    expect(result.context.errors.count).toBe(0);
+    expect(result.value).toBeDefined();
+  });
+
+  it("parses action with branding", () => {
+    const content = `
+name: Branded Action
+description: Action with branding
+branding:
+  icon: award
+  color: blue
+runs:
+  using: composite
+  steps:
+    - run: echo Hello
+      shell: bash`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    expect(result.context.errors.count).toBe(0);
+    expect(result.value).toBeDefined();
+  });
+
+  it("reports error for invalid YAML", () => {
+    const content = `
+name: Invalid Action
+description: Action with bad YAML
+runs:
+  using: composite
+  steps:
+    - name: 'Hello \${{ fromJSON('test') }}'
+      run: echo test
+      shell: bash`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    expect(result.context.errors.count).toBeGreaterThan(0);
+    expect(result.value).toBeUndefined();
+  });
+
+  it("validates required fields", () => {
+    const content = `
+runs:
+  using: composite
+  steps:
+    - run: echo Hello
+      shell: bash`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    expect(result.context.errors.count).toBeGreaterThan(0);
+  });
+
+  it("validates shell is required for run steps", () => {
+    const content = `
+name: Missing Shell
+description: Action without shell in run step
+runs:
+  using: composite
+  steps:
+    - run: echo Hello`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    expect(result.context.errors.count).toBeGreaterThan(0);
+  });
+
+  it("validates branding icon values", () => {
+    const content = `
+name: Bad Icon
+description: Action with invalid branding icon
+branding:
+  icon: invalid-icon-name
+  color: blue
+runs:
+  using: composite
+  steps:
+    - run: echo Hello
+      shell: bash`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    // Should have error for invalid icon value
+    expect(result.context.errors.count).toBeGreaterThan(0);
+  });
+
+  it("validates branding color values", () => {
+    const content = `
+name: Bad Color
+description: Action with invalid branding color
+branding:
+  icon: award
+  color: pink
+runs:
+  using: composite
+  steps:
+    - run: echo Hello
+      shell: bash`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+
+    // Should have error for invalid color value
+    expect(result.context.errors.count).toBeGreaterThan(0);
+  });
+});
+
+describe("convertActionTemplate", () => {
+  it("converts a composite action", () => {
+    const content = `
+name: Composite Action
+description: A composite action
+author: Test Author
+inputs:
+  name:
+    description: The name
+    required: true
+    default: World
+outputs:
+  result:
+    description: The result
+    value: \${{ steps.main.outputs.result }}
+runs:
+  using: composite
+  steps:
+    - id: main
+      name: Main step
+      run: echo Hello \${{ inputs.name }}
+      shell: bash
+branding:
+  icon: star
+  color: green`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+    expect(result.value).toBeDefined();
+    if (!result.value) return;
+
+    const template = convertActionTemplate(result.context, result.value);
+
+    expect(template.name).toBe("Composite Action");
+    expect(template.description).toBe("A composite action");
+    expect(template.author).toBe("Test Author");
+    expect(template.inputs).toHaveLength(1);
+    expect(template.inputs?.[0].id).toBe("name");
+    expect(template.inputs?.[0].required).toBe(true);
+    expect(template.outputs).toHaveLength(1);
+    expect(template.outputs?.[0].id).toBe("result");
+    expect(template.runs.using).toBe("composite");
+    expect(template.branding?.icon).toBe("star");
+    expect(template.branding?.color).toBe("green");
+
+    if (template.runs.using === "composite") {
+      expect(template.runs.steps).toHaveLength(1);
+      expect("run" in template.runs.steps[0]).toBe(true);
+    }
+  });
+
+  it("converts a node action", () => {
+    const content = `
+name: Node Action
+description: A node action
+runs:
+  using: node20
+  main: dist/index.js
+  pre: dist/setup.js
+  pre-if: runner.os == 'Linux'
+  post: dist/cleanup.js
+  post-if: always()`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+    expect(result.value).toBeDefined();
+    if (!result.value) return;
+
+    const template = convertActionTemplate(result.context, result.value);
+
+    expect(template.runs.using).toBe("node20");
+    if (template.runs.using === "node20") {
+      expect(template.runs.main).toBe("dist/index.js");
+      expect(template.runs.pre).toBe("dist/setup.js");
+      expect(template.runs.preIf).toBe("runner.os == 'Linux'");
+      expect(template.runs.post).toBe("dist/cleanup.js");
+      expect(template.runs.postIf).toBe("always()");
+    }
+  });
+
+  it("converts a docker action", () => {
+    const content = `
+name: Docker Action
+description: A docker action
+runs:
+  using: docker
+  image: Dockerfile
+  entrypoint: /entrypoint.sh
+  args:
+    - --name
+    - \${{ inputs.name }}
+  env:
+    DEBUG: "true"`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+    expect(result.value).toBeDefined();
+    if (!result.value) return;
+
+    const template = convertActionTemplate(result.context, result.value);
+
+    expect(template.runs.using).toBe("docker");
+    if (template.runs.using === "docker") {
+      expect(template.runs.image).toBe("Dockerfile");
+      expect(template.runs.entrypoint).toBe("/entrypoint.sh");
+      expect(template.runs.args).toEqual(["--name", "${{ inputs.name }}"]);
+      expect(template.runs.env).toEqual({DEBUG: "true"});
+    }
+  });
+
+  it("converts uses steps in composite action", () => {
+    const content = `
+name: Composite with Uses
+description: Composite action with uses steps
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0`;
+
+    const result = parseAction({name: "action.yml", content}, nullTrace);
+    expect(result.value).toBeDefined();
+    if (!result.value) return;
+
+    const template = convertActionTemplate(result.context, result.value);
+
+    if (template.runs.using === "composite") {
+      expect(template.runs.steps).toHaveLength(1);
+      const step = template.runs.steps[0];
+      expect("uses" in step).toBe(true);
+      if ("uses" in step) {
+        expect(step.uses.value).toBe("actions/checkout@v4");
+      }
+    }
+  });
+});

workflow-parser/src/actions/action-parser.ts

@@ -0,0 +1,41 @@
+import {TemplateParseResult} from "../templates/template-parse-result.js";
+import {TemplateContext, TemplateValidationErrors} from "../templates/template-context.js";
+import * as templateReader from "../templates/template-reader.js";
+import {TraceWriter} from "../templates/trace-writer.js";
+import {File} from "../workflows/file.js";
+import {YamlObjectReader} from "../workflows/yaml-object-reader.js";
+import {ACTION_ROOT} from "./action-constants.js";
+import {getActionSchema} from "./action-schema.js";
+
+/**
+ * Parses an action.yml file and validates it against the action schema.
+ * Returns a TemplateParseResult containing the parsed template token tree
+ * and any validation errors found during parsing.
+ */
+export function parseAction(entryFile: File, trace: TraceWriter): TemplateParseResult;
+export function parseAction(entryFile: File, context: TemplateContext): TemplateParseResult;
+export function parseAction(entryFile: File, contextOrTrace: TraceWriter | TemplateContext): TemplateParseResult {
+  const context =
+    contextOrTrace instanceof TemplateContext
+      ? contextOrTrace
+      : new TemplateContext(new TemplateValidationErrors(), getActionSchema(), contextOrTrace);
+
+  const fileId = context.getFileId(entryFile.name);
+  const reader = new YamlObjectReader(fileId, entryFile.content);
+  if (reader.errors.length > 0) {
+    // The file is not valid YAML, template errors could be misleading
+    for (const err of reader.errors) {
+      context.error(fileId, err.message, err.range);
+    }
+    return {
+      context,
+      value: undefined
+    };
+  }
+  const result = templateReader.readTemplate(context, ACTION_ROOT, reader, fileId);
+
+  return <TemplateParseResult>{
+    context,
+    value: result
+  };
+}

workflow-parser/src/actions/action-schema.ts

@@ -0,0 +1,17 @@
+import {JSONObjectReader} from "../templates/json-object-reader.js";
+import {TemplateSchema} from "../templates/schema/index.js";
+import ActionSchema from "../action-v1.0.min.json";
+
+let schema: TemplateSchema;
+
+/**
+ * Returns the action.yml schema, lazily loading and caching it on first access.
+ * The schema defines the structure and validation rules for action manifest files.
+ */
+export function getActionSchema(): TemplateSchema {
+  if (schema === undefined) {
+    const json = JSON.stringify(ActionSchema);
+    schema = TemplateSchema.load(new JSONObjectReader(undefined, json));
+  }
+  return schema;
+}

workflow-parser/src/actions/action-template.ts

@@ -0,0 +1,550 @@
+import {
+  BasicExpressionToken,
+  MappingToken,
+  ScalarToken,
+  StringToken,
+  TemplateToken
+} from "../templates/tokens/index.js";
+import {TemplateContext} from "../templates/template-context.js";
+import {isBoolean, isMapping, isScalar, isSequence, isString} from "../templates/tokens/type-guards.js";
+import {ErrorPolicy} from "../model/convert.js";
+import {Step} from "../model/workflow-template.js";
+import {convertToIfCondition} from "../model/converter/if-condition.js";
+
+/**
+ * Represents a parsed and converted action.yml file
+ */
+export type ActionTemplate = {
+  name: string;
+  description: string;
+  author?: string;
+  inputs?: ActionInputDefinition[];
+  outputs?: ActionOutputDefinition[];
+  runs: ActionRuns;
+  branding?: ActionBranding;
+};
+
+/**
+ * Represents an input definition from the action.yml inputs section.
+ */
+export type ActionInputDefinition = {
+  id: string;
+  description?: string;
+  required?: boolean;
+  default?: ScalarToken;
+  deprecationMessage?: string;
+};
+
+/**
+ * Represents an output definition from the action.yml outputs section.
+ */
+export type ActionOutputDefinition = {
+  id: string;
+  description?: string;
+  value?: ScalarToken;
+};
+
+/**
+ * Union type representing the different ways an action can be executed.
+ */
+export type ActionRuns = ActionRunsComposite | ActionRunsNode | ActionRunsDocker;
+
+/**
+ * Configuration for composite actions that execute a sequence of steps.
+ */
+export type ActionRunsComposite = {
+  using: "composite";
+  steps: Step[];
+};
+
+/**
+ * Configuration for JavaScript actions that run in Node.js.
+ */
+export type ActionRunsNode = {
+  using: "node12" | "node16" | "node20" | "node24";
+  main: string;
+  pre?: string;
+  preIf?: string;
+  post?: string;
+  postIf?: string;
+};
+
+/**
+ * Configuration for Docker container actions.
+ */
+export type ActionRunsDocker = {
+  using: "docker";
+  image: string;
+  preEntrypoint?: string;
+  preIf?: string;
+  entrypoint?: string;
+  postEntrypoint?: string;
+  postIf?: string;
+  args?: string[];
+  env?: Record<string, string>;
+};
+
+/**
+ * Branding configuration for displaying the action in the GitHub Marketplace.
+ */
+export type ActionBranding = {
+  icon?: string;
+  color?: string;
+};
+
+export type ActionTemplateConverterOptions = {
+  /**
+   * The error policy to use when converting the action.
+   * By default, conversion will be skipped if there are errors in the {@link TemplateContext}.
+   */
+  errorPolicy?: ErrorPolicy;
+};
+
+/**
+ * Converts a parsed action template token into a typed ActionTemplate
+ */
+export function convertActionTemplate(
+  context: TemplateContext,
+  root: TemplateToken,
+  options?: ActionTemplateConverterOptions
+): ActionTemplate {
+  const result: Partial<ActionTemplate> = {};
+  const errorPolicy = options?.errorPolicy ?? ErrorPolicy.ReturnErrorsOnly;
+
+  // Skip conversion if there are parse errors (unless TryConversion is set)
+  if (context.errors.getErrors().length > 0 && errorPolicy === ErrorPolicy.ReturnErrorsOnly) {
+    return result as ActionTemplate;
+  }
+
+  if (!isMapping(root)) {
+    context.error(root, new Error("Action must be a mapping"));
+    return result as ActionTemplate;
+  }
+
+  for (const item of root) {
+    const key = item.key.assertString("action key");
+
+    switch (key.value) {
+      case "name":
+        if (isString(item.value)) {
+          result.name = item.value.value;
+        }
+        break;
+
+      case "description":
+        if (isString(item.value)) {
+          result.description = item.value.value;
+        }
+        break;
+
+      case "author":
+        if (isString(item.value)) {
+          result.author = item.value.value;
+        }
+        break;
+
+      case "inputs":
+        result.inputs = convertInputs(context, item.value);
+        break;
+
+      case "outputs":
+        result.outputs = convertOutputs(context, item.value);
+        break;
+
+      case "runs":
+        result.runs = convertRuns(context, item.value);
+        break;
+
+      case "branding":
+        result.branding = convertBranding(context, item.value);
+        break;
+    }
+  }
+
+  return result as ActionTemplate;
+}
+
+/**
+ * Converts the inputs mapping token into an array of ActionInputDefinition objects.
+ */
+function convertInputs(context: TemplateContext, token: TemplateToken): ActionInputDefinition[] {
+  const inputs: ActionInputDefinition[] = [];
+
+  if (!isMapping(token)) {
+    return inputs;
+  }
+
+  for (const item of token) {
+    const id = item.key.assertString("input id").value;
+    const input: ActionInputDefinition = {id};
+
+    if (isMapping(item.value)) {
+      for (const prop of item.value) {
+        const propKey = prop.key.assertString("input property").value;
+
+        switch (propKey) {
+          case "description":
+            if (isString(prop.value)) {
+              input.description = prop.value.value;
+            }
+            break;
+
+          case "required":
+            if (isBoolean(prop.value)) {
+              input.required = prop.value.value;
+            } else if (isString(prop.value)) {
+              input.required = prop.value.value === "true";
+            }
+            break;
+
+          case "default":
+            if (isScalar(prop.value)) {
+              input.default = prop.value;
+            }
+            break;
+
+          case "deprecationMessage":
+            if (isString(prop.value)) {
+              input.deprecationMessage = prop.value.value;
+            }
+            break;
+        }
+      }
+    }
+
+    inputs.push(input);
+  }
+
+  return inputs;
+}
+
+/**
+ * Converts the outputs mapping token into an array of ActionOutputDefinition objects.
+ */
+function convertOutputs(context: TemplateContext, token: TemplateToken): ActionOutputDefinition[] {
+  const outputs: ActionOutputDefinition[] = [];
+
+  if (!isMapping(token)) {
+    return outputs;
+  }
+
+  for (const item of token) {
+    const id = item.key.assertString("output id").value;
+    const output: ActionOutputDefinition = {id};
+
+    if (isMapping(item.value)) {
+      for (const prop of item.value) {
+        const propKey = prop.key.assertString("output property").value;
+
+        switch (propKey) {
+          case "description":
+            if (isString(prop.value)) {
+              output.description = prop.value.value;
+            }
+            break;
+
+          case "value":
+            if (isScalar(prop.value)) {
+              output.value = prop.value;
+            }
+            break;
+        }
+      }
+    }
+
+    outputs.push(output);
+  }
+
+  return outputs;
+}
+
+/**
+ * Converts the runs mapping token into the appropriate ActionRuns variant based on the 'using' value.
+ */
+function convertRuns(context: TemplateContext, token: TemplateToken): ActionRuns {
+  if (!isMapping(token)) {
+    return {using: "composite", steps: []};
+  }
+
+  let using: string | undefined;
+  let main: string | undefined;
+  let image: string | undefined;
+  let pre: string | undefined;
+  let preIf: string | undefined;
+  let post: string | undefined;
+  let postIf: string | undefined;
+  let preEntrypoint: string | undefined;
+  let entrypoint: string | undefined;
+  let postEntrypoint: string | undefined;
+  let args: string[] | undefined;
+  let env: Record<string, string> | undefined;
+  let steps: Step[] = [];
+
+  for (const item of token) {
+    const key = item.key.assertString("runs property").value;
+
+    switch (key) {
+      case "using":
+        if (isString(item.value)) {
+          using = item.value.value;
+        }
+        break;
+
+      case "main":
+        if (isString(item.value)) {
+          main = item.value.value;
+        }
+        break;
+
+      case "image":
+        if (isString(item.value)) {
+          image = item.value.value;
+        }
+        break;
+
+      case "pre":
+        if (isString(item.value)) {
+          pre = item.value.value;
+        }
+        break;
+
+      case "pre-if":
+        if (isString(item.value)) {
+          preIf = item.value.value;
+        }
+        break;
+
+      case "post":
+        if (isString(item.value)) {
+          post = item.value.value;
+        }
+        break;
+
+      case "post-if":
+        if (isString(item.value)) {
+          postIf = item.value.value;
+        }
+        break;
+
+      case "pre-entrypoint":
+        if (isString(item.value)) {
+          preEntrypoint = item.value.value;
+        }
+        break;
+
+      case "entrypoint":
+        if (isString(item.value)) {
+          entrypoint = item.value.value;
+        }
+        break;
+
+      case "post-entrypoint":
+        if (isString(item.value)) {
+          postEntrypoint = item.value.value;
+        }
+        break;
+
+      case "args":
+        if (isSequence(item.value)) {
+          args = [];
+          for (const arg of item.value) {
+            if (isScalar(arg)) {
+              args.push(arg.toString());
+            }
+          }
+        }
+        break;
+
+      case "env":
+        if (isMapping(item.value)) {
+          env = {};
+          for (const envItem of item.value) {
+            const envKey = envItem.key.assertString("env key").value;
+            if (isString(envItem.value)) {
+              env[envKey] = envItem.value.value;
+            }
+          }
+        }
+        break;
+
+      case "steps":
+        steps = convertSteps(context, item.value);
+        break;
+    }
+  }
+
+  // Determine the type of runs configuration
+  if (using === "composite") {
+    return {using: "composite", steps};
+  } else if (using === "docker" && image) {
+    return {
+      using: "docker",
+      image,
+      preEntrypoint,
+      preIf,
+      entrypoint,
+      postEntrypoint,
+      postIf,
+      args,
+      env
+    };
+  } else if ((using === "node12" || using === "node16" || using === "node20" || using === "node24") && main) {
+    return {
+      using,
+      main,
+      pre,
+      preIf,
+      post,
+      postIf
+    };
+  }
+
+  // Default fallback
+  return {using: "composite", steps: []};
+}
+
+/**
+ * Converts a steps sequence token into an array of Step objects for composite actions.
+ */
+function convertSteps(context: TemplateContext, token: TemplateToken): Step[] {
+  const steps: Step[] = [];
+
+  if (!isSequence(token)) {
+    return steps;
+  }
+
+  for (const stepToken of token) {
+    if (!isMapping(stepToken)) {
+      continue;
+    }
+
+    const step = convertStep(context, stepToken);
+    if (step) {
+      steps.push(step);
+    }
+  }
+
+  return steps;
+}
+
+/**
+ * Converts a single step mapping token into a Step object.
+ * Returns undefined if the step lacks both 'run' and 'uses' properties.
+ */
+function convertStep(context: TemplateContext, token: MappingToken): Step | undefined {
+  let id: string | undefined;
+  let name: ScalarToken | undefined;
+  let ifCondition: BasicExpressionToken | undefined;
+  let continueOnError: boolean | ScalarToken | undefined;
+  let env: MappingToken | undefined;
+  let run: ScalarToken | undefined;
+  let uses: StringToken | undefined;
+
+  for (const item of token) {
+    const key = item.key.assertString("step property").value;
+
+    switch (key) {
+      case "id":
+        if (isString(item.value)) {
+          id = item.value.value;
+        }
+        break;
+
+      case "name":
+        if (isScalar(item.value)) {
+          name = item.value;
+        }
+        break;
+
+      case "if":
+        ifCondition = convertToIfCondition(context, item.value);
+        break;
+
+      case "continue-on-error":
+        if (isBoolean(item.value)) {
+          continueOnError = item.value.value;
+        } else if (isScalar(item.value)) {
+          continueOnError = item.value;
+        }
+        break;
+
+      case "env":
+        if (isMapping(item.value)) {
+          env = item.value;
+        }
+        break;
+
+      case "run":
+        if (isScalar(item.value)) {
+          run = item.value;
+        }
+        break;
+
+      case "uses":
+        if (isString(item.value)) {
+          uses = item.value;
+        }
+        break;
+
+      // Note: shell, working-directory, and with are valid step properties
+      // but not currently tracked in the Step model
+    }
+  }
+
+  // Default if condition to success() like workflow steps
+  const defaultIf = new BasicExpressionToken(undefined, undefined, "success()", undefined, undefined, undefined);
+
+  // Produce Step type (same as workflow steps)
+  if (run) {
+    return {
+      id: id || "",
+      name,
+      if: ifCondition || defaultIf,
+      "continue-on-error": continueOnError,
+      env,
+      run
+    };
+  } else if (uses) {
+    return {
+      id: id || "",
+      name,
+      if: ifCondition || defaultIf,
+      "continue-on-error": continueOnError,
+      env,
+      uses
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Converts the branding mapping token into an ActionBranding object.
+ */
+function convertBranding(context: TemplateContext, token: TemplateToken): ActionBranding {
+  const branding: ActionBranding = {};
+
+  if (!isMapping(token)) {
+    return branding;
+  }
+
+  for (const item of token) {
+    const key = item.key.assertString("branding property").value;
+
+    switch (key) {
+      case "icon":
+        if (isString(item.value)) {
+          branding.icon = item.value.value;
+        }
+        break;
+
+      case "color":
+        if (isString(item.value)) {
+          branding.color = item.value.value;
+        }
+        break;
+    }
+  }
+
+  return branding;
+}

workflow-parser/src/actions/index.ts

@@ -0,0 +1,21 @@
+// Action parser and schema
+export {parseAction} from "./action-parser.js";
+export {getActionSchema} from "./action-schema.js";
+export {ACTION_ROOT} from "./action-constants.js";
+
+// Action template types and converter
+export {
+  ActionTemplate,
+  ActionTemplateConverterOptions,
+  ActionInputDefinition,
+  ActionOutputDefinition,
+  ActionRuns,
+  ActionRunsComposite,
+  ActionRunsNode,
+  ActionRunsDocker,
+  ActionBranding,
+  convertActionTemplate
+} from "./action-template.js";
+
+// Re-export Step from workflow-template for convenience
+export {Step, ActionStep, RunStep} from "../model/workflow-template.js";

workflow-parser/src/expressions.test.ts

@@ -201,4 +201,355 @@ jobs:
       throw new Error("expected if to be a string (will be converted to expression later)");
     }
   });
+
+  describe("Block scalar chomp style preservation", () => {
+    it("preserves clip chomping (|) for literal block scalar", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TEST: |
+        \${{ github.event_name }}
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const env = build.get(1).value.assertMapping("env");
+      const testToken = env.get(0).value;
+
+      if (!isBasicExpression(testToken)) {
+        throw new Error("expected TEST to be a basic expression");
+      }
+
+      expect(testToken.blockScalarHeader).toBe("|");
+    });
+
+    it("preserves strip chomping (|-) for literal block scalar", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TEST: |-
+        \${{ github.event_name }}
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const env = build.get(1).value.assertMapping("env");
+      const testToken = env.get(0).value;
+
+      if (!isBasicExpression(testToken)) {
+        throw new Error("expected TEST to be a basic expression");
+      }
+
+      expect(testToken.blockScalarHeader).toBe("|-");
+    });
+
+    it("preserves keep chomping (|+) for literal block scalar", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TEST: |+
+        \${{ github.event_name }}
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const env = build.get(1).value.assertMapping("env");
+      const testToken = env.get(0).value;
+
+      if (!isBasicExpression(testToken)) {
+        throw new Error("expected TEST to be a basic expression");
+      }
+
+      expect(testToken.blockScalarHeader).toBe("|+");
+    });
+
+    it("preserves folded clip (>) chomping", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TEST: >
+        \${{ github.event_name }}
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const env = build.get(1).value.assertMapping("env");
+      const testToken = env.get(0).value;
+
+      if (!isBasicExpression(testToken)) {
+        throw new Error("expected TEST to be a basic expression");
+      }
+
+      expect(testToken.blockScalarHeader).toBe(">");
+    });
+
+    it("preserves folded strip (>-) chomping", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TEST: >-
+        \${{ github.event_name }}
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const env = build.get(1).value.assertMapping("env");
+      const testToken = env.get(0).value;
+
+      if (!isBasicExpression(testToken)) {
+        throw new Error("expected TEST to be a basic expression");
+      }
+
+      expect(testToken.blockScalarHeader).toBe(">-");
+    });
+
+    it("preserves with explicit indent (|2)", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TEST: |2
+        \${{ github.event_name }}
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const env = build.get(1).value.assertMapping("env");
+      const testToken = env.get(0).value;
+
+      if (!isBasicExpression(testToken)) {
+        throw new Error("expected TEST to be a basic expression");
+      }
+
+      expect(testToken.blockScalarHeader).toBe("|2");
+    });
+
+    it("preserves with explicit indent and strip (|-2)", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TEST: |-2
+        \${{ github.event_name }}
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const env = build.get(1).value.assertMapping("env");
+      const testToken = env.get(0).value;
+
+      if (!isBasicExpression(testToken)) {
+        throw new Error("expected TEST to be a basic expression");
+      }
+
+      expect(testToken.blockScalarHeader).toBe("|-2");
+    });
+
+    it("handles flow scalars (no chomp info for inline)", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TEST: \${{ github.event_name }}
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const env = build.get(1).value.assertMapping("env");
+      const testToken = env.get(0).value;
+
+      if (!isBasicExpression(testToken)) {
+        throw new Error("expected TEST to be a basic expression");
+      }
+
+      expect(testToken.blockScalarHeader).toBeUndefined();
+    });
+
+    it("preserves block scalar info for format expressions with multiple sub-expressions", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TEST: |
+        Hello \${{ github.event_name }} World \${{ github.ref }}
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const env = build.get(1).value.assertMapping("env");
+      const testToken = env.get(0).value;
+
+      if (!isBasicExpression(testToken)) {
+        throw new Error("expected TEST to be a basic expression");
+      }
+
+      // The format expression should preserve the block scalar info
+      expect(testToken.blockScalarHeader).toBe("|");
+    });
+
+    it("preserves block scalar info on StringToken for isExpression fields", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: |
+      github.event_name == 'push'
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const ifToken = build.get(1).value;
+
+      // For isExpression fields without ${{ }}, the token is a StringToken
+      if (!isString(ifToken)) {
+        throw new Error("expected if to be a string");
+      }
+
+      expect(ifToken.blockScalarHeader).toBe("|");
+    });
+
+    it("preserves block scalar info on StringToken for isExpression fields with strip", () => {
+      const result = parseWorkflow(
+        {
+          name: "test.yaml",
+          content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: |-
+      github.event_name == 'push'
+    steps:
+      - run: echo hi`
+        },
+        nullTrace
+      );
+
+      expect(result.context.errors.getErrors()).toHaveLength(0);
+
+      const workflowRoot = result.value!.assertMapping("root")!;
+      const jobs = workflowRoot.get(1).value.assertMapping("jobs");
+      const build = jobs.get(0).value.assertMapping("job");
+      const ifToken = build.get(1).value;
+
+      if (!isString(ifToken)) {
+        throw new Error("expected if to be a string");
+      }
+
+      expect(ifToken.blockScalarHeader).toBe("|-");
+    });
+  });
 });

workflow-parser/src/index.ts

@@ -2,4 +2,5 @@ export {convertWorkflowTemplate} from "./model/convert.js";
 export {WorkflowTemplate} from "./model/workflow-template.js";
 export * from "./templates/tokens/type-guards.js";
 export {NoOperationTraceWriter, TraceWriter} from "./templates/trace-writer.js";
+export {TemplateParseResult} from "./templates/template-parse-result.js";
 export {parseWorkflow, ParseWorkflowResult} from "./workflows/workflow-parser.js";

workflow-parser/src/templates/template-parse-result.ts

@@ -0,0 +1,10 @@
+import {TemplateContext} from "./template-context.js";
+import {TemplateToken} from "./tokens/template-token.js";
+
+/**
+ * Result of parsing a template file (workflow or action)
+ */
+export interface TemplateParseResult {
+  context: TemplateContext;
+  value: TemplateToken | undefined;
+}

workflow-parser/src/templates/template-reader.ts

@@ -451,7 +451,13 @@ class TemplateReader {
     }
 
     const allowedContext = definitionInfo.allowedContext;
-    const raw = token.source || token.value;
+    const isSingleLine = token.range === undefined || token.range.start.line === token.range.end.line;
+
+    // For single-line strings, use token.value (without YAML quotes) for expression detection,
+    // because token.source includes quote characters that would be incorrectly detected as literal text.
+    // For multi-line block scalars, use token.source directly because it makes position calculation easier
+    // (no quote characters to handle, and token.source preserves the original line/column structure in YAML).
+    const raw = isSingleLine ? token.value : token.source ?? token.value;
 
     let startExpression: number = raw.indexOf(OPEN_EXPRESSION);
     if (startExpression < 0) {
@@ -496,14 +502,17 @@ class TemplateReader {
         );
 
         let tr = token.range!;
-        if (tr.start.line === tr.end.line) {
-          // If it's a single line expression, adjust the range to only cover the sub-expression
+        if (isSingleLine) {
+          // Single-line: Adjust the range to only cover the sub-expression.
+          // Calculate offset to account for YAML quote characters.
+          // For example, `"${{ expr }}"` has source with quotes, value without.
+          const offset = (token.source ?? raw).indexOf(OPEN_EXPRESSION) - raw.indexOf(OPEN_EXPRESSION);
           tr = {
-            start: {line: tr.start.line, column: tr.start.column + startExpression},
-            end: {line: tr.end.line, column: tr.start.column + endExpression + 1}
+            start: {line: tr.start.line, column: tr.start.column + startExpression + offset},
+            end: {line: tr.end.line, column: tr.start.column + endExpression + 1 + offset}
           };
         } else {
-          // Adjust the range to only cover the expression for multi-line strings
+          // Multi-line: Adjust the range to only cover the expression
           const startRaw = raw.substring(0, startExpression);
           const adjustedStartLine = startRaw.split("\n").length;
           const beginningOfLine = startRaw.lastIndexOf("\n");
@@ -604,7 +613,9 @@ class TemplateReader {
       `format('${format.join("")}'${args.join("")})`,
       definitionInfo,
       expressionTokens,
-      raw
+      raw,
+      undefined,
+      token.blockScalarHeader
     );
   }
 
@@ -686,7 +697,8 @@ class TemplateReader {
         definitionInfo,
         undefined,
         token.source,
-        expressionRange
+        expressionRange,
+        token.blockScalarHeader
       ),
       error: undefined
     };

workflow-parser/src/templates/tokens/basic-expression-token.ts

@@ -24,7 +24,19 @@ export class BasicExpressionToken extends ExpressionToken {
   public readonly expressionRange: TokenRange | undefined;
 
   /**
-   * @param originalExpressions If the basic expression was transformed from individual expressions, these will be the original ones
+   * The block scalar header (e.g., "|", "|-", "|+", ">", ">-", ">+") if parsed from a YAML block scalar.
+   */
+  public readonly blockScalarHeader: string | undefined;
+
+  /**
+   * @param file The file ID where this token originated
+   * @param range The range of the entire expression including `${{` and `}}`
+   * @param expression The expression string without `${{` and `}}` markers
+   * @param definitionInfo Schema definition info for this token
+   * @param originalExpressions If transformed from individual expressions (e.g., format()), these are the originals
+   * @param source The original source string from the YAML
+   * @param expressionRange The range of just the expression, excluding `${{` and `}}`
+   * @param blockScalarHeader The block scalar header (e.g., "|", "|-") if parsed from a YAML block scalar
    */
   public constructor(
     file: number | undefined,
@@ -33,13 +45,15 @@ export class BasicExpressionToken extends ExpressionToken {
     definitionInfo: DefinitionInfo | undefined,
     originalExpressions: BasicExpressionToken[] | undefined,
     source: string | undefined,
-    expressionRange?: TokenRange | undefined
+    expressionRange?: TokenRange | undefined,
+    blockScalarHeader?: string | undefined
   ) {
     super(TokenType.BasicExpression, file, range, undefined, definitionInfo);
     this.expr = expression;
     this.source = source;
     this.originalExpressions = originalExpressions;
     this.expressionRange = expressionRange;
+    this.blockScalarHeader = blockScalarHeader;
   }
 
   public get expression(): string {
@@ -55,7 +69,8 @@ export class BasicExpressionToken extends ExpressionToken {
           this.definitionInfo,
           this.originalExpressions,
           this.source,
-          this.expressionRange
+          this.expressionRange,
+          this.blockScalarHeader
         )
       : new BasicExpressionToken(
           this.file,
@@ -64,7 +79,8 @@ export class BasicExpressionToken extends ExpressionToken {
           this.definitionInfo,
           this.originalExpressions,
           this.source,
-          this.expressionRange
+          this.expressionRange,
+          this.blockScalarHeader
         );
   }
 

workflow-parser/src/templates/tokens/string-token.ts

@@ -6,23 +6,26 @@ import {TokenType} from "./types.js";
 export class StringToken extends LiteralToken {
   public readonly value: string;
   public readonly source: string | undefined;
+  public readonly blockScalarHeader: string | undefined;
 
   public constructor(
     file: number | undefined,
     range: TokenRange | undefined,
     value: string,
     definitionInfo: DefinitionInfo | undefined,
-    source?: string
+    source?: string,
+    blockScalarHeader?: string
   ) {
     super(TokenType.String, file, range, definitionInfo);
     this.value = value;
     this.source = source;
+    this.blockScalarHeader = blockScalarHeader;
   }
 
   public override clone(omitSource?: boolean): TemplateToken {
     return omitSource
-      ? new StringToken(undefined, undefined, this.value, this.definitionInfo, this.source)
-      : new StringToken(this.file, this.range, this.value, this.definitionInfo, this.source);
+      ? new StringToken(undefined, undefined, this.value, this.definitionInfo, this.source, this.blockScalarHeader)
+      : new StringToken(this.file, this.range, this.value, this.definitionInfo, this.source, this.blockScalarHeader);
   }
 
   public override toString(): string {

workflow-parser/src/templates/tokens/template-token.test.ts

@@ -1,11 +1,13 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion, @typescript-eslint/no-unnecessary-type-assertion */
 import {nullTrace} from "../../test-utils/null-trace.js";
 import {parseWorkflow} from "../../workflows/workflow-parser.js";
+import {MappingToken} from "./mapping-token.js";
+import {SequenceToken} from "./sequence-token.js";
 import {StringToken} from "./string-token.js";
 import {TemplateToken} from "./template-token.js";
 
 describe("traverse", () => {
-  it("returns parent token and key", () => {
+  it("returns parent token, key, and ancestors", () => {
     const workflow = parseWorkflow(
       {
         name: "wf.yaml",
@@ -18,19 +20,118 @@ describe("traverse", () => {
     const traverser = TemplateToken.traverse(root);
 
     // Root
-    expect(traverser.next()!.value).toEqual([undefined, root, undefined]);
+    const rootResult = traverser.next()!.value!;
+    expect(rootResult[0]).toBeUndefined();
+    expect(rootResult[1]).toBe(root);
+    expect(rootResult[2]).toBeUndefined();
+    expect(rootResult[3]).toEqual([]);
 
     // On
     const onResult = traverser.next().value!;
     expect(onResult[0]).toBe(root);
     expect(getValue(onResult[1])).toEqual("on");
     expect(onResult[2]).toBeUndefined();
+    expect(onResult[3]).toEqual([root]);
 
     // Push
     const pushResult = traverser.next().value!;
     expect(pushResult[0]).toBe(root);
     expect(getValue(pushResult[1])).toEqual("push");
     expect(getValue(pushResult[2])).toEqual("on");
+    expect(pushResult[3]).toEqual([root]);
+  });
+
+  it("returns ancestors for nested mappings", () => {
+    const workflow = parseWorkflow(
+      {
+        name: "wf.yaml",
+        content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest`
+      },
+      nullTrace
+    );
+
+    const root = workflow.value!;
+    const results = Array.from(TemplateToken.traverse(root));
+
+    // Find the "ubuntu-latest" token
+    const ubuntuResult = results.find(r => getValue(r[1]) === "ubuntu-latest")!;
+    expect(ubuntuResult).toBeDefined();
+
+    // Ancestors should be: root -> jobs mapping -> build mapping
+    const ancestors = ubuntuResult[3];
+    expect(ancestors.length).toBe(3);
+    expect(ancestors[0]).toBe(root);
+    expect(ancestors[1]).toBeInstanceOf(MappingToken); // jobs mapping
+    expect(ancestors[2]).toBeInstanceOf(MappingToken); // build mapping
+  });
+
+  it("returns ancestors for sequences", () => {
+    const workflow = parseWorkflow(
+      {
+        name: "wf.yaml",
+        content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hello`
+      },
+      nullTrace
+    );
+
+    const root = workflow.value!;
+    const results = Array.from(TemplateToken.traverse(root));
+
+    // Find the "echo hello" token
+    const echoResult = results.find(r => getValue(r[1]) === "echo hello")!;
+    expect(echoResult).toBeDefined();
+
+    // Ancestors should be: root -> jobs mapping -> build mapping -> steps sequence -> step mapping
+    const ancestors = echoResult[3];
+    expect(ancestors.length).toBe(5);
+    expect(ancestors[0]).toBe(root);
+    expect(ancestors[1]).toBeInstanceOf(MappingToken); // jobs mapping
+    expect(ancestors[2]).toBeInstanceOf(MappingToken); // build mapping
+    expect(ancestors[3]).toBeInstanceOf(SequenceToken); // steps sequence
+    expect(ancestors[4]).toBeInstanceOf(MappingToken); // step mapping
+  });
+
+  it("returns correct ancestors for matrix values", () => {
+    const workflow = parseWorkflow(
+      {
+        name: "wf.yaml",
+        content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [a, b]
+    steps:
+      - run: echo hi`
+      },
+      nullTrace
+    );
+
+    const root = workflow.value!;
+    const results = Array.from(TemplateToken.traverse(root));
+
+    // Find the "a" token (first matrix value)
+    const nodeValueResult = results.find(r => {
+      const token = r[1];
+      return token instanceof StringToken && token.value === "a";
+    })!;
+    expect(nodeValueResult).toBeDefined();
+
+    // Ancestors: root -> jobs mapping -> build mapping -> strategy mapping -> matrix mapping -> node sequence
+    const ancestors = nodeValueResult[3];
+    expect(ancestors.length).toBeGreaterThanOrEqual(5);
+    expect(ancestors[0]).toBe(root);
+    // Last ancestor should be the sequence containing [a, b]
+    expect(ancestors[ancestors.length - 1]).toBeInstanceOf(SequenceToken);
   });
 });
 

workflow-parser/src/templates/tokens/template-token.ts

@@ -185,14 +185,23 @@ export abstract class TemplateToken {
 
   /**
    * Returns all tokens (depth first)
-   * @param value The object to travese
+   * @param value The object to traverse
    * @param omitKeys Whether to omit mapping keys
+   * @yields A tuple of [parent, token, keyToken, ancestors] for each token in the tree
    */
   public static *traverse(
     value: TemplateToken,
     omitKeys?: boolean
-  ): Generator<[parent: TemplateToken | undefined, token: TemplateToken, keyToken: TemplateToken | undefined], void> {
-    yield [undefined, value, undefined];
+  ): Generator<
+    [
+      parent: TemplateToken | undefined,
+      token: TemplateToken,
+      keyToken: TemplateToken | undefined,
+      ancestors: TemplateToken[]
+    ],
+    void
+  > {
+    yield [undefined, value, undefined, []];
 
     switch (value.templateTokenType) {
       case TokenType.Sequence:
@@ -202,7 +211,7 @@ export abstract class TemplateToken {
         while (state.parent) {
           if (state.moveNext(omitKeys ?? false)) {
             value = state.current as TemplateToken;
-            yield [state.parent?.current, value, state.currentKey];
+            yield [state.parent?.current, value, state.currentKey, state.getAncestors()];
 
             switch (value.type) {
               case TokenType.Sequence:

workflow-parser/src/templates/tokens/traversal-state.ts

@@ -66,4 +66,19 @@ export class TraversalState {
         throw new Error(`Unexpected token type '${this._token.templateTokenType}' when traversing state`);
     }
   }
+
+  /**
+   * Returns the ancestor tokens from root to the current token's parent container.
+   */
+  public getAncestors(): TemplateToken[] {
+    const ancestors: TemplateToken[] = [];
+    let state: TraversalState | undefined = this.parent;
+    while (state) {
+      if (state.current) {
+        ancestors.unshift(state.current);
+      }
+      state = state.parent;
+    }
+    return ancestors;
+  }
 }

workflow-parser/src/workflows/workflow-parser.ts

@@ -1,19 +1,22 @@
+import {TemplateParseResult} from "../templates/template-parse-result.js";
 import {TemplateContext, TemplateValidationErrors} from "../templates/template-context.js";
 import * as templateReader from "../templates/template-reader.js";
-import {TemplateToken} from "../templates/tokens/template-token.js";
 import {TraceWriter} from "../templates/trace-writer.js";
 import {File} from "./file.js";
 import {WORKFLOW_ROOT} from "./workflow-constants.js";
 import {getWorkflowSchema} from "./workflow-schema.js";
 import {YamlObjectReader} from "./yaml-object-reader.js";
-export interface ParseWorkflowResult {
-  context: TemplateContext;
-  value: TemplateToken | undefined;
-}
 
-export function parseWorkflow(entryFile: File, trace: TraceWriter): ParseWorkflowResult;
-export function parseWorkflow(entryFile: File, context: TemplateContext): ParseWorkflowResult;
-export function parseWorkflow(entryFile: File, contextOrTrace: TraceWriter | TemplateContext): ParseWorkflowResult {
+/** @deprecated Use TemplateParseResult instead */
+export type ParseWorkflowResult = TemplateParseResult;
+
+/**
+ * Parses a GitHub Actions workflow YAML file and returns the parsed template result.
+ * Validates the workflow against the workflow schema and reports any errors.
+ */
+export function parseWorkflow(entryFile: File, trace: TraceWriter): TemplateParseResult;
+export function parseWorkflow(entryFile: File, context: TemplateContext): TemplateParseResult;
+export function parseWorkflow(entryFile: File, contextOrTrace: TraceWriter | TemplateContext): TemplateParseResult {
   const context =
     contextOrTrace instanceof TemplateContext
       ? contextOrTrace
@@ -33,7 +36,7 @@ export function parseWorkflow(entryFile: File, contextOrTrace: TraceWriter | Tem
   }
   const result = templateReader.readTemplate(context, WORKFLOW_ROOT, reader, fileId);
 
-  return <ParseWorkflowResult>{
+  return <TemplateParseResult>{
     context,
     value: result
   };