From 6dde0b554d613f60196c8ab237d880d7869cddad Mon Sep 17 00:00:00 2001 From: Josh Gross Date: Mon, 6 Mar 2023 14:44:18 -0500 Subject: [PATCH] Show action description on hover --- languageserver/src/description-provider.ts | 26 ++++++++- .../action-description.test.ts | 57 +++++++++++++++++++ .../action-description.ts | 23 ++++++++ .../action-input.test.ts | 54 ++---------------- .../src/test-utils/action-metadata.ts | 42 ++++++++++++++ languageservice/src/action.ts | 2 + 6 files changed, 153 insertions(+), 51 deletions(-) create mode 100644 languageserver/src/description-providers/action-description.test.ts create mode 100644 languageserver/src/description-providers/action-description.ts create mode 100644 languageserver/src/test-utils/action-metadata.ts diff --git a/languageserver/src/description-provider.ts b/languageserver/src/description-provider.ts index 128a1ee..58163ad 100644 --- a/languageserver/src/description-provider.ts +++ b/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"; +} diff --git a/languageserver/src/description-providers/action-description.test.ts b/languageserver/src/description-providers/action-description.test.ts new file mode 100644 index 0000000..91fc5df --- /dev/null +++ b/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(); + }); +}); diff --git a/languageserver/src/description-providers/action-description.ts b/languageserver/src/description-providers/action-description.ts new file mode 100644 index 0000000..8ca6d91 --- /dev/null +++ b/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 { + 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}`; +} diff --git a/languageserver/src/description-providers/action-input.test.ts b/languageserver/src/description-providers/action-input.test.ts index 9912982..0e2ce7d 100644 --- a/languageserver/src/description-providers/action-input.test.ts +++ b/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(); }); diff --git a/languageserver/src/test-utils/action-metadata.ts b/languageserver/src/test-utils/action-metadata.ts new file mode 100644 index 0000000..9be3868 --- /dev/null +++ b/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" + } +}; diff --git a/languageservice/src/action.ts b/languageservice/src/action.ts index b10a166..2512e69 100644 --- a/languageservice/src/action.ts +++ b/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; };