From 265907bfa09ee4d28bcaf9f442ad44763885a5b9 Mon Sep 17 00:00:00 2001 From: Christopher Schleiden Date: Tue, 28 Feb 2023 15:18:40 -0800 Subject: [PATCH 1/5] Add readme for workflow-parser --- workflow-parser/README.md | 79 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 workflow-parser/README.md diff --git a/workflow-parser/README.md b/workflow-parser/README.md new file mode 100644 index 0000000..5045e00 --- /dev/null +++ b/workflow-parser/README.md @@ -0,0 +1,79 @@ +# actions/workflow-parser + +`@actions/workflow-parser` is a library to parse GitHub Actions [workflows](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions). + +## Installation + +The [package](https://www.npmjs.com/package/@actions/workflow-parser) contains TypeScript types and compiled ECMAScript modules. + +```bash +npm install @actions/workflow-parser +``` + +## Usage + +The parser is driven by a custom schema defined in [`worflows-v1.0.json`](./src/workflow-v1.0.json). + +### Simple example + +`parseWorkflow` parses the workflow YAML into an intermediate representation and validates that it conforms to the schema. Any parsing errors are returned in the `errors` property of the result context. + +```typescript +var trace: TraceWriter; + +const result = parseWorkflow( + { + name: "test.yaml", + content: `on: push +jobs: + build: + runs-on: ubuntu-latest + steps: + - run: echo 'hello'` + }, + trace +); +``` + +`convertWorkflowTemplate` then takes that intermediate representation and converts it to a [`WorkflowTemplate`](./src/workflow-template.ts) object, which is a more convenient representation for working with workflows. + +```typescript +const workflowTemplate = await convertWorkflowTemplate(result.context, result.value); + +// workflowTemplate.jobs[0].id === "build" +// workflowTemplate.jobs[0].steps[0].run === "echo 'hello'" +``` + +### Build + +```bash +npm run build +``` + +or to watch for changes + +```bash +npm run watch +``` + +### Test + +```bash +npm test +``` + +or to watch for changes and run tests: + +```bash +npm run test-watch +``` + +### Lint + +```bash +npm run format-check +``` + +## License + +This project is licensed under the terms of the MIT open source license. Please refer to [MIT](../LICENSE) for the full terms. From 5854c87825b2bd768f8ac522cec0e2f3110e3a54 Mon Sep 17 00:00:00 2001 From: Christopher Schleiden Date: Tue, 28 Feb 2023 15:18:55 -0800 Subject: [PATCH 2/5] Adjust package names --- expressions/README.md | 4 ++-- languageserver/README.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/expressions/README.md b/expressions/README.md index b2a15ad..2076ada 100644 --- a/expressions/README.md +++ b/expressions/README.md @@ -1,6 +1,6 @@ -# actions-expressions +# actions/expressions -`actions-expressions` is a library to parse and evaluate GitHub Actions [expressions](https://docs.github.com/actions/learn-github-actions/expressions). +`@actions/expressions` is a library to parse and evaluate GitHub Actions [expressions](https://docs.github.com/actions/learn-github-actions/expressions). ## Installation diff --git a/languageserver/README.md b/languageserver/README.md index 9c0cbf3..6698e5c 100644 --- a/languageserver/README.md +++ b/languageserver/README.md @@ -1,4 +1,4 @@ -# actions-languageserver +# actions/languageserver `actions-languageserver` hosts the `actions-languageservice` and makes it available via the [language server protocol](https://microsoft.github.io/language-server-protocol/) (LSP) as a standalone language server. From bb91f52176e170b8c892d28cb6b5bcf947ef399c Mon Sep 17 00:00:00 2001 From: Christopher Schleiden Date: Tue, 28 Feb 2023 15:25:01 -0800 Subject: [PATCH 3/5] Expand language service readme --- languageservice/README.md | 43 ++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/languageservice/README.md b/languageservice/README.md index f853365..f10f61c 100644 --- a/languageservice/README.md +++ b/languageservice/README.md @@ -1,4 +1,4 @@ -# actions-languageservice +# actions/languageservice This package contains the logic for the GitHub Actions workflows language server. @@ -22,14 +22,6 @@ The language service features use three sources of information: * _value providers_ which can dynamically add values to the schema, for example, the list of available labels for a repository when validating `runs-on`. * _context providers_ which can dynamically provide available contexts used in [expressions](https://docs.github.com/actions/reference/context-and-expression-syntax-for-github-actions#about-contexts-and-expressions). For example, the contents of the `github.event` context for a given workflow file. -##### Value Providers - -TODO - -##### Context Providers - -TODO - #### Validation Validate a workflow file, returns an array of [`Diagnostic`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnostic) objects. @@ -60,7 +52,38 @@ const hover = await hover(document, {line: 0, character: 1}); // { contents: { k #### Auto-completion -TODO +```typescript +import {complete} from "@actions/languageservice"; + +const document = { + uri: "file:///path/to/file", + getText: () => "on: \n jobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - run: echo hello" +}; + +// Trigger completion for `on: |` +const suggestions = await complete(document, {line: 0, character: 4}); +``` + +will return + +```jsonc +[{ + "documentation": { + "kind": "markdown", + "value": "Runs your workflow when branch protection rules in the workflow repository are changed.", + }, + "label": "branch_protection_rule", + "textEdit": { + "newText": "branch_protection_rule", + "range": { + "end": {"character": 4, "line": 0,}, + "start": {"character": 4, "line": 0}, + }, + }, +}, +//... other events +] +``` ## Contributing From a93db03989c03513125a60ad41d84006c517681d Mon Sep 17 00:00:00 2001 From: Christopher Schleiden Date: Tue, 28 Feb 2023 15:28:13 -0800 Subject: [PATCH 4/5] Add Contribution section for parser readme --- workflow-parser/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/workflow-parser/README.md b/workflow-parser/README.md index 5045e00..e480668 100644 --- a/workflow-parser/README.md +++ b/workflow-parser/README.md @@ -44,6 +44,14 @@ const workflowTemplate = await convertWorkflowTemplate(result.context, result.va // workflowTemplate.jobs[0].steps[0].run === "echo 'hello'" ``` +## Contributing + +See [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository for general guidelines and recommendations. + +Similar to [`actions/expressions](../expressions/), this project is just one of multiple implementations of the GitHub Actions workflow parser. We therefore cannot accept contributions that significantly modify the schema or the overall behavior of the parser. If you would like to propose changes to Actions itself, please use our [Community Forum](https://github.com/community/community/discussions/categories/actions-and-packages). + +If you do want to contribute, please run [prettier](https://prettier.io/) to format your code and add unit tests as appropriate before submitting your PR. [./testdata](./testdata) contains test cases that all implementations should pass, please also make sure those tests are still passing. + ### Build ```bash From 6bbd3dda95952c0c78aa37045b34fa7b2c0f70a4 Mon Sep 17 00:00:00 2001 From: Christopher Schleiden Date: Wed, 1 Mar 2023 08:19:17 -0800 Subject: [PATCH 5/5] Expand newlines Co-authored-by: Jacob Wallraff --- languageservice/README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/languageservice/README.md b/languageservice/README.md index f10f61c..76a6072 100644 --- a/languageservice/README.md +++ b/languageservice/README.md @@ -57,7 +57,12 @@ import {complete} from "@actions/languageservice"; const document = { uri: "file:///path/to/file", - getText: () => "on: \n jobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - run: echo hello" + getText: () => `on: +jobs: + build: + runs-on: ubuntu-latest + steps: + - run: echo hello` }; // Trigger completion for `on: |`