Merge pull request #105 from github/cschleiden/readmes

Add READMEs to packages
2023-01-25 09:29:39 -08:00
parent 61f3d953e2 2b1747d131
commit 5c167773b8
5 changed files with 295 additions and 13 deletions
@@ -7,7 +7,7 @@
 The [package](https://www.npmjs.com/package/@actions/expressions) contains TypeScript types and compiled ECMAScript modules.

 ```bash
-npm install @github/actions-expressions
+npm install @actions/expressions
 ```

 ## Usage
@@ -54,7 +54,7 @@ console.log(result.coerceString()) // true

 ## Contributing

-See also [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository.
+See [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository for general guidelines and recommendations.

 This project is just one of multiple implementations of the GitHub Actions Expressions language. We therefore cannot accept contributions that add new language features or significantly change the behavior of existing language features. If you would like to propose a change to the language itself, please use our [Community Forum](https://github.com/community/community/discussions/categories/actions-and-packages).

@@ -63,31 +63,31 @@ If you do want to contribute, please run [prettier](https://prettier.io/) to for
 ### Build

 ```bash
-$ npm run build
+npm run build
 ```

 or to watch for changes

 ```bash
-$ npm run watch
+npm run watch
 ```

 ### Test

 ```bash
-$ npm test
+npm test
 ```

 or to watch for changes and run tests:

 ```bash
-$ npm run test-watch
+npm run test-watch
 ```

 ### Lint

 ```bash
-$ npm run format-check
+npm run format-check
 ```

 ## License
@@ -1 +1,134 @@
-This wraps the GitHub Actions language service and makes it available via the [language server protocol](https://microsoft.github.io/language-server-protocol/) (LSP).
+# 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.
+
+## Installation
+
+The [package](https://www.npmjs.com/package/@actions/languageserver) contains TypeScript types and compiled ECMAScript modules.
+
+```bash
+npm install @actions/languageserver
+```
+
+## Usage
+
+### Basic usage using `vscode-languageserver-node`
+
+For the server, import the module. It detects whether it's running in a Node.js environment or a web worker and initializes the appropriate connection.
+
+`server.ts`:
+
+```typescript
+import "@actions/languageserver";
+```
+
+For the client, create a new `LanguageClient` pointing to the server module.
+
+`client.ts`:
+
+```typescript
+import {LanguageClient, ServerOptions, TransportKind} from "vscode-languageclient/node";
+
+const debugOptions = {execArgv: ["--nolazy", "--inspect=6010"]};
+
+const clientOptions: LanguageClientOptions = {
+  documentSelector: [{
+    pattern: "**/.github/workflows/*.{yaml,yml}"
+  }]
+};
+
+const serverModule = context.asAbsolutePath(path.join("dist", "server.js"));
+const serverOptions: ServerOptions = {
+  run: {module: serverModule, transport: TransportKind.ipc},
+  debug: {
+    module: serverModule,
+    transport: TransportKind.ipc,
+    options: debugOptions
+  }
+};
+
+const client = new LanguageClient("actions-language", "GitHub Actions Language Server", serverOptions, clientOptions);
+```
+
+### From a web worker
+
+See [../browser-playground](../browser-playground) for an example implementation that hosts the language server in a web worker.
+
+### Providing advanced functionality
+
+The language server accepts initialization options that can be used to configure additional functionality. If you pass in a github.com `sessionToken`, the language service will use data from github.com to perform additional validations and provide additional auto-completion suggestions.
+
+```typescript
+export interface InitializationOptions {
+  /**
+   * GitHub token that will be used to retrieve additional information from github.com
+   *
+   * Requires the `repo` and `workflow` scopes
+   */
+  sessionToken?: string;
+
+  /**
+   * List of repositories that the language server should be aware of
+   */
+  repos?: RepositoryContext[];
+
+  /**
+   * Desired log level
+   */
+  logLevel?: LogLevel;
+}
+```
+
+pass the `initializationOptions` to the `LanguageClient` when establishing the connection:
+
+```typescript
+const clientOptions: LanguageClientOptions = {
+  documentSelector: [{
+    pattern: "**/.github/workflows/*.{yaml,yml}"
+  }],
+  initializationOptions: initializationOptions
+};
+
+const client = new LanguageClient("actions-language", "GitHub Actions Language Server", serverOptions, clientOptions);
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository for general guidelines and recommendations.
+
+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.
+
+### 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.
+
@@ -2,17 +2,42 @@ import {LogLevel} from "@github/actions-languageservice/log";
 export {LogLevel} from "@github/actions-languageservice/log";

 export interface InitializationOptions {
+  /**
+   * GitHub token that will be used to retrieve additional information from github.com
+   *
+   * Requires the `repo` and `workflow` scopes
+   */
  sessionToken?: string;

+  /**
+   * List of repositories that the language server should be aware of
+   */
  repos?: RepositoryContext[];

+  /**
+   * Desired log level
+   */
  logLevel?: LogLevel;
 }

 export interface RepositoryContext {
+  /**
+   * Repository ID
+   */
  id: number;
+
+  /**
+   * Repository owner
+   */
  owner: string;
+
+  /**
+   * Repository name
+   */
  name: string;

+  /**
+   * Local workspace uri
+   */
  workspaceUri: string;
 }
@@ -1 +1,103 @@
-This contains the logic for the GitHub Actions workflows language server.
+# actions-languageservice
+
+This package contains the logic for the GitHub Actions workflows language server.
+
+## Installation
+
+The [package](https://www.npmjs.com/package/@actions/languageservice) contains TypeScript types and compiled ECMAScript modules.
+
+```bash
+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](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.
+
+```typescript
+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](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_hover) over a token in the workflow file.
+
+```typescript
+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
+
+TODO
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository for general guidelines and recommendations.
+
+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.
+
+### 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.
@@ -1,9 +1,31 @@
-## Development
+# browser-playground

-Install dependencies locally, unfortunately via the workspace is not enough to run `webpack-dev-server`. Then
+This is a web-based playground hosting the [language server](../actions-languageserver/) in a web worker connected to an instance of the [Monaco](https://microsoft.github.io/monaco-editor/) editor. You can try it at https://actions.github.com/languageservices.
+
+## Contributing
+
+### Build and run
+
+Even though the package is part of the `npm` workspace, it needs its dependencies to be installed locally in order to run `webpack-dev-server`. To do so, run:

 ```bash
-$ npm start
+npm i --workspaces=false
 ```

-to serve the app at `localhost:8080`.
+then
+
+```bash
+npm start
+```
+
+to build and serve the app at `localhost:8080`.
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository for general guidelines and recommendations.
+
+If you do want to contribute, please run [prettier](https://prettier.io/) to format your code before submitting your PR.
+
+## License
+
+This project is licensed under the terms of the MIT open source license. Please refer to [MIT](../LICENSE) for the full terms.