[FEATURE] Support smithy-vscode extension

[sperka]

Describe the feature

To create a projen-managed artifact that is generated when one uses a smithy-api-gateway-XXX-project in order to support smithy vscode extension and not to fail with validations that could be easily avoided.

Use Case

In the current form, smithy-vscode extension is constantly failing with the error of not recognizing aws.protocols#restJson1 trait:

Caused by: software.amazon.smithy.model.validation.ValidatedResultException: Result contained ERROR severity validation events: 
[ERROR] my.namespace#MyService: Unable to resolve trait `aws.protocols#restJson1`. If this is a custom trait, then it must be defined before it can be used in a model. | Model ....

This becomes annoying after some time.

Proposed Solution

As the README says, a smithy-build.json should be present in the root of the project.

Generating a smithy-build.json with the following content in the root of the project solves the issue mentioned above:

{
  "version": "2.0",
  "maven": {
    "dependencies": [
      "software.amazon.smithy:smithy-cli:1.24.0",
      "software.amazon.smithy:smithy-model:1.24.0",
      "software.amazon.smithy:smithy-openapi:1.24.0",
      "software.amazon.smithy:smithy-aws-traits:1.24.0"
    ],
    "repositories": [{ "url": "https://repo1.maven.org/maven2/" }]
  },
  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"npx projen\"."
}

NOTE: the dependencies can be generated based on the smithy project's settings in the PDK project. More specifically, all the dependencies that are present in packages/project-name/smithy-build/build.gradle's dependencies section, can be added to the "root" smithy-build.json. This won't have any effect generating the API project.

Additionally, based on the smithy-vscode codebase, there is a way of defining a rootPath for the extension: source. It would be ideal to generate a .smithy/smithy-build.json file, but unfortunately at this point smithyLsp.rootPath in .vscode/settings.json results in Unknown Configuration Setting and the value is not picked up by the Smithy language server.

Other Information

No response

Acknowledgements

• [X] I may be able to implement this feature request
• [ ] This feature might incur a breaking change

PDK version used

0.11.2

What languages will this feature affect?

Typescript

Environment details (OS name and version, etc.)

MacOS 12.5.1

[cogwirrel]

Thanks for the feature request!

Currently the smithy-build.json file is written to the smithy-build folder of the SmithyApiGatewayXXXProject's outdir - I suppose for it to be in the "root" of a project it would depend on whether or not it's parented by a monorepo.

For a standalone project it'd be fairly strightforward to move the smithy-build.json file to the project outdir rather than the smithy-build folder, and add the dependencies.

I suppose a SmithyApiGatewayXXXProject could technically mutate the parent project for the monorepo case to add a root smithy-build.json but we'd need to think about how to handle "clashes" if a user has multiple Smithy projects. It's also a bit of an unexpected side-effect if we do that.

The built in SmithyBuild component doesn't seem to accept the maven props so without a change to projen one may need to create it using JsonFile, eg:

const monorepo = new NxMonorepoProject(...);

new JsonFile(monorepo, 'smithy-build.json', {
  obj: {
    maven: ...
  },
});

[cogwirrel]

On a related note it'd be useful to also support the Smithy intellij plugin: https://github.com/iancaffey/smithy-intellij-plugin - though I'm not sure how it resolves dependencies yet :)

[agdimech]

my 2 cents:

Vscode plugins are notorious for not supporting monorepos. I think it would probably be safer to just symlink the smithy-build.json into the root as a manual step instead (when onboarding to vscode plugin), given this is more a limitation of the plugin than the generated code itself.

[cogwirrel]

Given that a subproject writing a file outside of it's project bounds would be an unexpected side-effect, I think it's best that we let users define their own root smithy-build.json file on the monorepo as mentioned in the comment above, if they do wish to get the vscode extension working.

I think the best documentation is actually this GitHub issue, and as this is a little niche I don't think it's worth updating the open-api-gateway package docs.

Closing this for now. If the vscode extension ever supports a non-root smithy-build.json we can look at sending a PR to projen to add the maven object as a property to that, and likewise exposing it in the smithyBuildOptions in SmithyApiGatewayXXXProjects.