Show action description on hover

languageserver/src/description-provider.ts

@@ -2,20 +2,40 @@ import {DescriptionProvider} from "@github/actions-languageservice/hover";
 import {Octokit} from "@octokit/rest";
 import {getActionInputDescription} from "./description-providers/action-input";
 import {TTLCache} from "./utils/cache";
+import {isString} from "@github/actions-workflow-parser/templates/tokens/type-guards";
+import {TemplateToken} from "@github/actions-workflow-parser/templates/tokens/template-token";
+import {getActionDescription} from "./description-providers/action-description";
 
 export function descriptionProvider(client: Octokit | undefined, cache: TTLCache): DescriptionProvider {
   const getDescription: DescriptionProvider["getDescription"] = async (context, token, path) => {
-    if (!client) {
+    if (!client || !context.step) {
       return undefined;
     }
 
-    const parent = path[path.length - 1];
-    if (context.step && parent.definition?.key === "step-with") {
+    if (isStepInput(path)) {
       return await getActionInputDescription(client, cache, context.step, token);
     }
+
+    if (isStepUses(path)) {
+      return await getActionDescription(client, cache, context.step);
+    }
   };
 
   return {
     getDescription
   };
 }
+
+function isStepInput(path: TemplateToken[]): boolean {
+  const parent = path[path.length - 1];
+  return parent.definition?.key === "step-with";
+}
+
+function isStepUses(path: TemplateToken[]): boolean {
+  if (path.length < 2) {
+    return false;
+  }
+  const parent = path[path.length - 1];
+  const grandparent = path[path.length - 2];
+  return isString(parent) && parent.value === "uses" && grandparent.definition?.key === "regular-step";
+}

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

@@ -0,0 +1,57 @@
+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";
+
+const workflow = `
+name: Hello World
+on: workflow_dispatch
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+`;
+
+async function getDescription(mock: fetchMock.FetchMockSandbox) {
+  const workflowContext = await createWorkflowContext(workflow, "build", 0);
+
+  return await getActionDescription(
+    new Octokit({
+      request: {
+        fetch: mock
+      }
+    }),
+    new TTLCache(),
+    workflowContext.step!
+  );
+}
+
+describe("action descriptions", () => {
+  it("actions/checkout description", async () => {
+    const mock = fetchMock
+      .sandbox()
+      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", actionsCheckoutMetadata);
+
+    expect(await getDescription(mock)).toEqual("**Checkout**\n\nCheckout a Git repository at a particular version");
+  });
+
+  it("action does not exist", async () => {
+    const mock = fetchMock
+      .sandbox()
+      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", 404)
+      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yaml?ref=v3", 404);
+
+    expect(await getDescription(mock)).toBeUndefined();
+  });
+
+  it("invalid metadata", async () => {
+    const mock = fetchMock
+      .sandbox()
+      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", {});
+
+    expect(await getDescription(mock)).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,23 @@
+import {parseActionReference} from "@github/actions-languageservice/action";
+import {isActionStep} from "@github/actions-workflow-parser/model/type-guards";
+import {Step} from "@github/actions-workflow-parser/model/workflow-template";
+import {Octokit} from "@octokit/rest";
+import {fetchActionMetadata} from "../utils/action-metadata";
+import {TTLCache} from "../utils/cache";
+
+export async function getActionDescription(client: Octokit, cache: TTLCache, step: Step): Promise<string | undefined> {
+  if (!isActionStep(step)) {
+    return undefined;
+  }
+  const action = parseActionReference(step.uses.value);
+  if (!action) {
+    return undefined;
+  }
+
+  const metadata = await fetchActionMetadata(client, cache, action);
+  if (!metadata?.name || !metadata?.description) {
+    return undefined;
+  }
+
+  return `**${metadata.name}**\n\n${metadata.description}`;
+}

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

@@ -5,6 +5,7 @@ import fetchMock from "fetch-mock";
 import {createWorkflowContext} from "../test-utils/workflow-context";
 import {TTLCache} from "../utils/cache";
 import {getActionInputDescription} from "./action-input";
+import {actionsCheckoutMetadata} from "../test-utils/action-metadata";
 
 const workflow = `
 name: Hello World
@@ -16,49 +17,6 @@ jobs:
     - uses: actions/checkout@v3
 `;
 
-// A simplified version of the action.yml file from actions/checkout
-const actionMetadataContent = `
-name: 'Checkout'
-description: 'Checkout a Git repository at a particular version'
-inputs:
-  repository:
-    description: Repository name with owner. For example, actions/checkout
-    default: \${{ github.repository }}
-  ref:
-    description: The branch, tag or SHA to checkout.
-    required: true
-  token:
-    description: Personal access token (PAT) used to fetch the repository.
-    default: \${{ github.token }}
-  repo:
-    description: 'Repository name with owner. For example, actions/checkout'
-    deprecationMessage: 'Use repository instead'
-runs:
-  using: node16
-  main: dist/index.js
-  post: dist/index.js
-`;
-
-// Based on https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3
-const actionMetadata = {
-  name: "action.yml",
-  path: "action.yml",
-  sha: "cab09ebd3a964aba67b57f9727f5f6fff1372b04",
-  size: 3649,
-  url: "https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3",
-  html_url: "https://github.com/actions/checkout/blob/v3/action.yml",
-  git_url: "https://api.github.com/repos/actions/checkout/git/blobs/cab09ebd3a964aba67b57f9727f5f6fff1372b04",
-  download_url: "https://raw.githubusercontent.com/actions/checkout/v3/action.yml",
-  type: "file",
-  content: Buffer.from(actionMetadataContent).toString("base64"),
-  encoding: "base64",
-  _links: {
-    self: "https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3",
-    git: "https://api.github.com/repos/actions/checkout/git/blobs/cab09ebd3a964aba67b57f9727f5f6fff1372b04",
-    html: "https://github.com/actions/checkout/blob/v3/action.yml"
-  }
-};
-
 async function getDescription(input: string, mock: fetchMock.FetchMockSandbox) {
   const workflowContext = await createWorkflowContext(workflow, "build", 0);
 
@@ -74,11 +32,11 @@ async function getDescription(input: string, mock: fetchMock.FetchMockSandbox) {
   );
 }
 
-describe("action descriptions", () => {
+describe("action input descriptions", () => {
   it("optional input", async () => {
     const mock = fetchMock
       .sandbox()
-      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", actionMetadata);
+      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", actionsCheckoutMetadata);
 
     expect(await getDescription("repository", mock)).toEqual(
       "Repository name with owner. For example, actions/checkout"
@@ -88,7 +46,7 @@ describe("action descriptions", () => {
   it("required input", async () => {
     const mock = fetchMock
       .sandbox()
-      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", actionMetadata);
+      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", actionsCheckoutMetadata);
 
     expect(await getDescription("ref", mock)).toEqual("The branch, tag or SHA to checkout.\n\n**Required**");
   });
@@ -96,7 +54,7 @@ describe("action descriptions", () => {
   it("deprecated input", async () => {
     const mock = fetchMock
       .sandbox()
-      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", actionMetadata);
+      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", actionsCheckoutMetadata);
 
     expect(await getDescription("repo", mock)).toEqual(
       "Repository name with owner. For example, actions/checkout\n\n**Deprecated**"
@@ -106,7 +64,7 @@ describe("action descriptions", () => {
   it("invalid input", async () => {
     const mock = fetchMock
       .sandbox()
-      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", actionMetadata);
+      .getOnce("https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3", actionsCheckoutMetadata);
 
     expect(await getDescription("typo", mock)).toBeUndefined();
   });

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

@@ -0,0 +1,42 @@
+// A simplified version of the action.yml file from actions/checkout
+const checkoutMetadataContent = `
+name: 'Checkout'
+description: 'Checkout a Git repository at a particular version'
+inputs:
+  repository:
+    description: Repository name with owner. For example, actions/checkout
+    default: \${{ github.repository }}
+  ref:
+    description: The branch, tag or SHA to checkout.
+    required: true
+  token:
+    description: Personal access token (PAT) used to fetch the repository.
+    default: \${{ github.token }}
+  repo:
+    description: 'Repository name with owner. For example, actions/checkout'
+    deprecationMessage: 'Use repository instead'
+runs:
+  using: node16
+  main: dist/index.js
+  post: dist/index.js
+`;
+
+// Based on https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3
+export const actionsCheckoutMetadata = {
+  name: "action.yml",
+  path: "action.yml",
+  sha: "cab09ebd3a964aba67b57f9727f5f6fff1372b04",
+  size: 3649,
+  url: "https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3",
+  html_url: "https://github.com/actions/checkout/blob/v3/action.yml",
+  git_url: "https://api.github.com/repos/actions/checkout/git/blobs/cab09ebd3a964aba67b57f9727f5f6fff1372b04",
+  download_url: "https://raw.githubusercontent.com/actions/checkout/v3/action.yml",
+  type: "file",
+  content: Buffer.from(checkoutMetadataContent).toString("base64"),
+  encoding: "base64",
+  _links: {
+    self: "https://api.github.com/repos/actions/checkout/contents/action.yml?ref=v3",
+    git: "https://api.github.com/repos/actions/checkout/git/blobs/cab09ebd3a964aba67b57f9727f5f6fff1372b04",
+    html: "https://github.com/actions/checkout/blob/v3/action.yml"
+  }
+};

languageservice/src/action.ts

@@ -1,5 +1,7 @@
 // https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions
 export type ActionMetadata = {
+  name: string;
+  description: string;
   inputs?: ActionInputs;
   outputs?: ActionOutputs;
 };