From aa412082719466c64d7e120ad99676a4499f5007 Mon Sep 17 00:00:00 2001 From: Joe Wu Date: Thu, 27 Feb 2025 14:25:56 -0800 Subject: [PATCH 1/3] First draft for updated READM.ME --- README.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 170 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b52bcd50..8f33bf4b 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,179 @@ A [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) implementation for the [Smithy IDL](https://smithy.io). +Smithy is a protocol-agnostic interface definition language and set of tools for generating clients, servers, and documentation for any programming language. + +## Features +The Smithy Language Server provides the following features: +* Code Completion +* Code Folding +* Code Hover Information +* Code Inlay Hints +* Code Navigation (Definition / Declaration) +* Document Symbol Support +* Document Formatting + +## Running the Language Server + +### Visual Studio Code Extension +For Visual Studio Code users, please install our official Visual Studio Code extension from the marketplace: + +[Smithy Extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=smithy.smithy-vscode-extension) + +### Neovim +For users who prefer Neovim, [Neovim lspconfig](https://github.com/neovim/nvim-lspconfig/tree/master) can be used to configure the Smithy Language Server. For detailed instruction, please check +the [Manual Setup (Neovim)](#neovim-jdk-21-is-required) section below. + +### Manual Setup +You can also run the language server manually. + +#### JAR Release (JDK 21 is required) +1. Download the latest release JAR from [release page](https://github.com/smithy-lang/smithy-language-server/releases). +2. Unzip the downloaded zip file. +3. Run the language server by executing the following command: + ```bash + java -jar /path/to/unziped/folder/smithy-language-server-0.x.x.jar [port-number] + // Usually the default port-number is set to 0 + ``` + +#### Neovim (JDK 21 is required) +1. Download the latest release JAR from [release page](https://github.com/smithy-lang/smithy-language-server/releases). +2. Unzip the downloaded zip file. +3. Check out the [Neovim lspconfig Guide](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#smithy_ls) and configure the `init.lua` + to setup the Smithy Language Server. A sample configuration would look like this: + + ```lua + -- init.lua + .... + + local lspconfig = require('lspconfig') + local smithy_jar_path = "/path/to/lsp/lib/smithy-language-server-0.x.x.jar" -- Adjust the path + + -- Configure the Smithy Language Server + lspconfig.smithy_ls.setup{ + -- Specify the command to start the Smithy Language Server + cmd = {"java", "-jar", smithy_jar_path, "0" } + } + + ... + ``` + +## Configuring the Language Server + +### Client-Side Configuration + +Configurations supported from client: + +| Field | Description | Type | Default | Options | +|-----------------------------|-------------------------------------------------------------------|:-------:|:---------------:|:------------------------------------:| +| Diagnostics:MinimumSeverity | Sets the minimum severity level for diagnostics. | string | "WARNING" | "WARNING", "NOTE", "DANGER", "ERROR" | +| Only Read On Save | When enabled, only reloads the model on file save. | boolean | false | false, true | +| +Configurations supported from Visual Studio Code: + +| Field | Description | Type | Default | Options | +|------------------------|-------------------------------------------------------------------|:-------:|:---------------:|:------------------------------------:| +| Max Number Of Problems | Controls the maximum number of problems produced by the server. | integer | 100 | N/A | +| Root Path | The root path of the Smithy project | string | null | Valid directory path | +| Trace:Server | Traces the communication between VS Code and the language server. | string | "verbose" | "verbose", "messages", "off" | +| Version | Version of the Smithy Language Server | string | current version | Valid Smithy Language Server version | +### Build File Configuration + +The Smithy Language Server can recognize two types of : `smithy-build.json` or `.smithy-project.json`. The build files help the server to locate the root path of +the Smithy project. + +Table of fields used by the Smithy Language Server from build files: + +| Field | Description | Type | +|-----------------|---------------------------------------------------------------------------------------------------------------------|:------:| +| sources | A list of relative files or directories that contain the models that are considered the source models of the build. | list | +| imports | A list of model files and directories to load when validating and building the model. | list | +| dependencies | A list of dependencies used to bring in model imports, build plugins, validators, transforms, and other extensions. | list | + +#### smithy-build.json +The Smithy Language Server fully supports `smithy-build.json` and resolve any `sources`, `imports`, and `dependencies` you specify in the config file. +Detailed documentation of `smithy-build.json` can be found from [Smithy:Using smithy-build.json](https://smithy.io/2.0/guides/smithy-build-json.html#using-smithy-build-json) + + +`smithy-build.json` config file example: + +```json +{ + "version": "1.0", + "sources": ["model"], + "imports": ["foo.json", "baz.json"], + "outputDirectory": "build/output", + "maven": { + "dependencies": ["software.amazon.smithy:smithy-aws-traits:1.26.1"], + "repositories": [ + { + "url": "https://example.com/maven", + "httpCredentials": "${MAVEN_USER}:${MAVEN_PASSWORD}" + } + ] + }, + "projections": { + "projection-name": { + "transforms": [ + { + "name": "transform-name", + "args": [ + "argument1", + "argument2", + "..." + ] + }, + { + "name": "other-transform" + } + ], + "plugins": { + "plugin-name": { + "plugin-config": "value" + }, + "...": {} + } + } + }, + "plugins": { + "plugin-name": { + "plugin-config": "value" + }, + "...": {} + } +} +``` + +#### .smithy-project.json + +`.smithy-project.json` is an alternative way to configure your Smithy project when the config is not specified in your `smithy-build.json`. +For projects using specific build tools(e.g., `smithy-gradle-plugin` ), you can configure `.smithy-project.json` to specify dependencies and other project settings. + +`.smithy-project.json` config file example: + +```json +{ + "sources": [ + "model", + "src/main/smithy" + ], + "imports": [ + "vendor/smithy-models" + ], + "dependencies": [ + { + "name": "smithy-test-traits", + "path": "./././/smithy-test-traits.jar" + } + ], + "outputDirectory": "/foo/bar" +} +``` + ## Security See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. ## License -This project is licensed under the Apache-2.0 License. - +This project is licensed under the Apache-2.0 License. \ No newline at end of file From d53eead13d64d3881150247f32cf3214d2aff36d Mon Sep 17 00:00:00 2001 From: Joe Wu Date: Thu, 13 Mar 2025 15:36:15 -0700 Subject: [PATCH 2/3] Address the comments --- README.md | 60 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 8f33bf4b..ab4fac9a 100644 --- a/README.md +++ b/README.md @@ -4,28 +4,45 @@ A [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) implementation for the [Smithy IDL](https://smithy.io). -Smithy is a protocol-agnostic interface definition language and set of tools for generating clients, servers, and documentation for any programming language. - ## Features The Smithy Language Server provides the following features: -* Code Completion -* Code Folding -* Code Hover Information -* Code Inlay Hints -* Code Navigation (Definition / Declaration) + +### For Smithy IDL +* Completion +* Diagnostics for Model Validation Event * Document Symbol Support -* Document Formatting +* Formatting +* Folding +* Hover Information +* Inlay Hints +* Navigation (Definition / Declaration) + +### For smithy-build.json +* Completion +* Diagnostics for Model Validation Event +* Hover Information ## Running the Language Server ### Visual Studio Code Extension -For Visual Studio Code users, please install our official Visual Studio Code extension from the marketplace: - +For Visual Studio Code users, please install our official Visual Studio Code extension from the marketplace: [Smithy Extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=smithy.smithy-vscode-extension) +Configurations supported from Visual Studio Code: + +| Field | Description | Type | Default | Options | +|------------------------|-------------------------------------------------------------------|:-------:|:---------------:|:------------------------------------:| +| Max Number Of Problems | Controls the maximum number of problems produced by the server. | integer | 100 | N/A | +| Root Path | The root path of the Smithy project | string | null | Valid directory path | +| Trace:Server | Traces the communication between VS Code and the language server. | string | "verbose" | "verbose", "messages", "off" | +| Version | Version of the Smithy Language Server | string | current version | Valid Smithy Language Server version | + + ### Neovim -For users who prefer Neovim, [Neovim lspconfig](https://github.com/neovim/nvim-lspconfig/tree/master) can be used to configure the Smithy Language Server. For detailed instruction, please check -the [Manual Setup (Neovim)](#neovim-jdk-21-is-required) section below. +[nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/tree/master) has a config for Smithy Language Server. +See [smithy_ls](https://github.com/neovim/nvim-lspconfig/blob/master/lua/lspconfig/configs/smithy_ls.lua). + +You will need to provide a command to run the language server, see [Manual Setup](#manual-setup). ### Manual Setup You can also run the language server manually. @@ -35,8 +52,8 @@ You can also run the language server manually. 2. Unzip the downloaded zip file. 3. Run the language server by executing the following command: ```bash - java -jar /path/to/unziped/folder/smithy-language-server-0.x.x.jar [port-number] - // Usually the default port-number is set to 0 + java -jar /path/to/unziped/folder/smithy-language-server-0.x.x.jar [--port-number ] + // [--port-number] is optional (the default port number is set to 0). ``` #### Neovim (JDK 21 is required) @@ -65,21 +82,10 @@ You can also run the language server manually. ### Client-Side Configuration -Configurations supported from client: - | Field | Description | Type | Default | Options | |-----------------------------|-------------------------------------------------------------------|:-------:|:---------------:|:------------------------------------:| -| Diagnostics:MinimumSeverity | Sets the minimum severity level for diagnostics. | string | "WARNING" | "WARNING", "NOTE", "DANGER", "ERROR" | -| Only Read On Save | When enabled, only reloads the model on file save. | boolean | false | false, true | -| -Configurations supported from Visual Studio Code: - -| Field | Description | Type | Default | Options | -|------------------------|-------------------------------------------------------------------|:-------:|:---------------:|:------------------------------------:| -| Max Number Of Problems | Controls the maximum number of problems produced by the server. | integer | 100 | N/A | -| Root Path | The root path of the Smithy project | string | null | Valid directory path | -| Trace:Server | Traces the communication between VS Code and the language server. | string | "verbose" | "verbose", "messages", "off" | -| Version | Version of the Smithy Language Server | string | current version | Valid Smithy Language Server version | +| diagnostics:minimumSeverity | Sets the minimum severity level for diagnostics. | string | "WARNING" | "WARNING", "NOTE", "DANGER", "ERROR" | + ### Build File Configuration The Smithy Language Server can recognize two types of : `smithy-build.json` or `.smithy-project.json`. The build files help the server to locate the root path of From 9b01183fce2df23b2337c3ce3ca9e5120d30f578 Mon Sep 17 00:00:00 2001 From: Joe Wu Date: Wed, 30 Apr 2025 13:19:44 -0700 Subject: [PATCH 3/3] Modify to reflect LSP's arugment parser update. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ab4fac9a..7e7d39c4 100644 --- a/README.md +++ b/README.md @@ -52,9 +52,9 @@ You can also run the language server manually. 2. Unzip the downloaded zip file. 3. Run the language server by executing the following command: ```bash - java -jar /path/to/unziped/folder/smithy-language-server-0.x.x.jar [--port-number ] - // [--port-number] is optional (the default port number is set to 0). - ``` + java -jar /path/to/unziped/folder/smithy-language-server-0.x.x.jar [--port | -p ] + // [--port | -p] is optional (port is set to 0 by default). + ``` #### Neovim (JDK 21 is required) 1. Download the latest release JAR from [release page](https://github.com/smithy-lang/smithy-language-server/releases).