diff --git a/browser-playground/package.json b/browser-playground/package.json index 6d712dc..067a069 100644 --- a/browser-playground/package.json +++ b/browser-playground/package.json @@ -1,12 +1,12 @@ { "name": "browser-playground", - "version": "0.1.155", + "version": "0.1.157", "description": "", "private": true, "main": "index.js", "type": "module", "dependencies": { - "@github/actions-languageserver": "^0.1.155", + "@github/actions-languageserver": "^0.1.157", "monaco-editor-webpack-plugin": "^7.0.1", "monaco-editor-workers": "^0.34.2", "monaco-languageclient": "^4.0.3", diff --git a/expressions/package.json b/expressions/package.json index f323aff..8f1613b 100755 --- a/expressions/package.json +++ b/expressions/package.json @@ -1,6 +1,6 @@ { "name": "@github/actions-expressions", - "version": "0.1.155", + "version": "0.1.157", "license": "MIT", "type": "module", "source": "./src/index.ts", diff --git a/languageserver/package.json b/languageserver/package.json index 1c44bec..cfb19f8 100644 --- a/languageserver/package.json +++ b/languageserver/package.json @@ -1,6 +1,6 @@ { "name": "@github/actions-languageserver", - "version": "0.1.155", + "version": "0.1.157", "description": "Language server for GitHub Actions", "license": "MIT", "type": "module", @@ -38,8 +38,8 @@ "watch": "tsc --build tsconfig.build.json --watch" }, "dependencies": { - "@github/actions-languageservice": "^0.1.155", - "@github/actions-workflow-parser": "^0.1.155", + "@github/actions-languageservice": "^0.1.157", + "@github/actions-workflow-parser": "^0.1.157", "@octokit/rest": "^19.0.7", "vscode-languageserver": "^8.0.2", "vscode-languageserver-textdocument": "^1.0.7", diff --git a/languageserver/src/description-provider.ts b/languageserver/src/description-provider.ts index 128a1ee..3a8403a 100644 --- a/languageserver/src/description-provider.ts +++ b/languageserver/src/description-provider.ts @@ -2,17 +2,22 @@ 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 {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 (parent.definition?.key === "step-with") { return await getActionInputDescription(client, cache, context.step, token); } + + if (parent.definition?.key === "step-uses") { + return await getActionDescription(client, cache, context.step); + } }; return { 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..72a0bd8 --- /dev/null +++ b/languageserver/src/description-providers/action-description.test.ts @@ -0,0 +1,59 @@ +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**](https://www.github.com/actions/checkout/tree/v3/)\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..cd0866b --- /dev/null +++ b/languageserver/src/description-providers/action-description.ts @@ -0,0 +1,23 @@ +import {actionUrl, 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}**](${actionUrl(action)})\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/package.json b/languageservice/package.json index df13f14..9aa131b 100644 --- a/languageservice/package.json +++ b/languageservice/package.json @@ -1,6 +1,6 @@ { "name": "@github/actions-languageservice", - "version": "0.1.155", + "version": "0.1.157", "description": "Language service for GitHub Actions", "license": "MIT", "type": "module", @@ -39,8 +39,8 @@ "watch": "tsc --build tsconfig.build.json --watch" }, "dependencies": { - "@github/actions-expressions": "^0.1.155", - "@github/actions-workflow-parser": "^0.1.155", + "@github/actions-expressions": "^0.1.157", + "@github/actions-workflow-parser": "^0.1.157", "vscode-languageserver-textdocument": "^1.0.7", "vscode-languageserver-types": "^3.17.2", "yaml": "^2.1.1" diff --git a/languageservice/src/action.ts b/languageservice/src/action.ts index b10a166..8aa6e8b 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; }; @@ -63,3 +65,10 @@ export function actionIdentifier(ref: ActionReference): string { } return `${ref.owner}/${ref.name}/${ref.ref}`; } + +export function actionUrl(actionRef: ActionReference): string { + // TODO: Support base uri for GHES + const gitHubBaseUri = "https://www.github.com/"; + + return `${gitHubBaseUri}${actionRef.owner}/${actionRef.name}/tree/${actionRef.ref}/${actionRef.path || ""}`; +} diff --git a/languageservice/src/complete.test.ts b/languageservice/src/complete.test.ts index dc468cc..f2520d4 100644 --- a/languageservice/src/complete.test.ts +++ b/languageservice/src/complete.test.ts @@ -338,6 +338,24 @@ jobs: expect(result).toHaveLength(16); }); + it("complete from behind a colon will replace it", async () => { + const input = ` +on: push +jobs: + one: + runs-on: ubuntu-latest + |: + - uses: actions/checkout@v2 +`; + const result = await complete(...getPositionFromCursor(input)); + expect(result).toHaveLength(16); + let textEdit = result[0].textEdit as TextEdit; + expect(textEdit.range).toEqual({ + start: {line: 5, character: 4}, + end: {line: 5, character: 5} + }); + }); + it("well known mapping keys have descriptions", async () => { const input = ` o| diff --git a/languageservice/src/complete.ts b/languageservice/src/complete.ts index 8f355f7..96393a6 100644 --- a/languageservice/src/complete.ts +++ b/languageservice/src/complete.ts @@ -103,7 +103,19 @@ export async function complete( // Get the length of the current word const val = line.match(/[\w_-]*$/)?.[0].length || 0; - replaceRange = Range.create({line: position.line, character: position.character - val}, position); + // Check if we need to remove a trailing colon + const charAfterPos = textDocument.getText({ + start: {line: position.line, character: position.character}, + end: {line: position.line, character: position.character + 1} + }); + if (charAfterPos === ":") { + replaceRange = Range.create( + {line: position.line, character: position.character - val}, + {line: position.line, character: position.character + 1} + ); + } else { + replaceRange = Range.create({line: position.line, character: position.character - val}, position); + } } return values.map(value => { diff --git a/languageservice/src/document-links.ts b/languageservice/src/document-links.ts index a78ff9f..4eff46f 100644 --- a/languageservice/src/document-links.ts +++ b/languageservice/src/document-links.ts @@ -3,7 +3,7 @@ import {isJob} from "@github/actions-workflow-parser/model/type-guards"; import {File} from "@github/actions-workflow-parser/workflows/file"; import {TextDocument} from "vscode-languageserver-textdocument"; import {DocumentLink} from "vscode-languageserver-types"; -import {parseActionReference} from "./action"; +import {actionUrl, parseActionReference} from "./action"; import {mapRange} from "./utils/range"; import {fetchOrParseWorkflow, fetchOrConvertWorkflowTemplate} from "./utils/workflow-cache"; @@ -25,9 +25,6 @@ export async function documentLinks(document: TextDocument): Promise