actions/languageservice

This package contains the logic for the GitHub Actions workflows language server.

Installation

The package contains TypeScript types and compiled ECMAScript modules.

npm install @actions/languageservice

Usage

Basic usage

Concepts

The language service features use three sources of information:

• a built-in static schema for the workflow YAML file
• 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. For example, the contents of the github.event context for a given workflow file.

Validation

Validate a workflow file, returns an array of Diagnostic objects.

const config: ValidationConfig = {
  valueProviderConfig: valueProviders(sessionToken, repoContext, cache),
  contextProviderConfig: contextProviders(sessionToken, repoContext, cache),
};

const result = await validate(textDocument, config); // result is an array of `Diagnostic`

Hover

Get information when hovering over a token in the workflow file.

import {hover} from "@actions/languageservice";

const document = {
  uri: "file:///path/to/file",
  getText: () => "on: push\n  jobs:\n    build:\n      runs-on: ubuntu-latest\n      steps:\n        - run: echo hello"
};

const hover = await hover(document, {line: 0, character: 1}); // { contents: { kind: "markdown", value: "The event that triggers the workflow" } }

Auto-completion

import {complete} from "@actions/languageservice";

const document = {
  uri: "file:///path/to/file",
  getText: () => `on: 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - run: echo hello`
};

// Trigger completion for `on: |`
const suggestions = await complete(document, {line: 0, character: 4});

will return

[{
  "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

See CONTRIBUTING.md at the root of the repository for general guidelines and recommendations.

If you do want to contribute, please run prettier to format your code and add unit tests as appropriate before submitting your PR.

Build

npm run build

or to watch for changes

npm run watch

Test

npm test

or to watch for changes and run tests:

npm run test-watch

Lint

npm run format-check

License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.