AsyncAPI: Add "Autofix" feature for common linting errors (w/ spectral)

[AceTheCreator]

AsyncAPI-Preview + Spectral for VSCode form a perfect combo in terms of UX/DX for asyncapi editing:

with this extension, you can navigate and preview your API definition
while Spectral for VSCode provides inline and listed linting error for common and even custom mistakes
VSCode comes with an API for providing quick/autofixes for linting errors (see https://code.visualstudio.com/docs/editor/refactoring https://code.visualstudio.com/api/references/vscode-api#CodeActionProvider and https://github.com/microsoft/vscode-extension-samples/tree/main/code-actions-sample for an example)

The purpose of this feature is to provide auto-fix refactoring for the most common and standard spectral linting errors for asyncapi:
https://docs.stoplight.io/docs/spectral/1e63ffd0220f3-async-api-rules

Learn more here asyncapi/vs-asyncapi-preview#160

Mentor/s:
@ivangsa

Project Repo:
https://github.com/asyncapi/vs-asyncapi-preview

Expected Difficulty:
Easy-Medium

Expected Time Commitment:
175 Hour

[fmvilas]

Love this one 👍

[AdityaSingh-02]

Hii @ivangsa

Hello! I'm Aditya Singh, a Computer Science undergraduate from India with a passion for open-source contributions. Previously, I had the opportunity to participate in Google Summer of Code at Rocket.chat, which was an enriching experience. This season, I'm eager to channel my skills and knowledge into contributing to AsyncAPI. This project has captured my interest and I would love to build this VS code extension, and I'm excited about the potential impact I can make by contributing to AsyncAPI. I'm looking forward to contributing and making some impact...

X- https://twitter.com/Go_D_Aditya

[FelicixAwe]

Hi, @ivangsa. I think this idea is interesting and would like to work on this one. Without further ado, I tried to write some codes for practice. Based on my understanding, we need to get those linting errors before applying any autofix. Below are two ways I figured could be possible solutions for retrieving error messages from spectral in phase 1:

1. Migrate spectral linting into extension
   According to spectral APIs, we can import spectral and initialize it for running spectral linting to get linting error messages.

2. Retrieve diagnostics thru VSCode API vscode.languages.getDiagnostics
   As vs code provides this API, we can use it to fetch errors.

Personally I prefer the second way as we already have a spectral extension out there so don't need to bother ourselves to integrate its functions into our own (also I could be wrong). Another reason I thought the second way is practical is because vscode provides API such as vscode.workspace.onDidChangeTextDocument which is consistent with a setting in Spectral: Spectral: Run -> onSave. Hence the whole workflow is clear that when Spectral running to give some errors, we can listen to this event and fetch them.

If anyone has any comments on this, welcome to discuss together!

P.S. Do we have any issue tagged "first issues" for this project?

[AdityaSingh-02]

Hii @ivangsa

Hello! I'm Aditya Singh, a Computer Science undergraduate from India with a passion for open-source contributions. Previously, I had the opportunity to participate in Google Summer of Code at Rocket.chat, which was an enriching experience. This season, I'm eager to channel my skills and knowledge into contributing to AsyncAPI. This project has captured my interest and I would love to build this VS code extension, and I'm excited about the potential impact I can make by contributing to AsyncAPI. I'm looking forward to contributing and making some impact...

X- https://twitter.com/Go_D_Aditya

1. What interests you most about this project?

I'm particularly drawn to the "AsyncAPI: Add 'Autofix' feature for common linting errors (w/ spectral)" project for several reasons. Firstly, the opportunity to work on an open-source project like AsyncAPI excites me, especially because it's at the intersection of API design and tooling, which are areas I'm passionate about. Additionally, the prospect of developing a VS Code extension to enhance the linting experience using Spectral is intriguing.

2. As mentors and project coordinators, how can we get the best out of you?

With prior experience in GSOC with Rocket.chat I value open lines of communication with mentors and project coordinators to discuss goals, expectations, and any challenges that may arise throughout the project. Additionally, I thrive in an environment that encourages creativity and problem-solving, where I can explore different approaches and technologies to achieve project objectives

3. Is there anything that you’ll be studying or working on whilst working alongside us?

While working on this project, I anticipate delving deeper into Spectral and understanding its capabilities for linting AsyncAPI documents. Additionally, I'll be exploring the intricacies of developing VS Code extensions and integrating them seamlessly into developers' workflows.
I have hands on practice working with TypeScript which is an essential for building VS Code Extensions.

4. We'd love to hear a bit about your work preferences, e.g. how you keep yourself organized, what tools you use, etc.?

In terms of organization, I rely heavily on project management tools like Notion to keep track of tasks, deadlines, and progress. I find that breaking down larger tasks into smaller, manageable chunks helps maintain focus and momentum.

For development, I prefer using modern tools and frameworks that streamline the development process and enhance collaboration. I'm comfortable working with Git for version control and GitHub for managing repositories and collaborating with teammates. Visual Studio Code is my go-to editor for its versatility and extensive ecosystem of extensions.

5. Regarding a weekly schedule with clear milestones and deliverables, here's a suggested outline:

• Week 1: Set up the development environment for building the VS Code extension.
• Week 2-3: Implement basic linting functionality for detecting common errors in AsyncAPI documents.
• Week 4-5: Develop the autofix feature to automatically correct identified linting errors.
• Week 6-8: Conduct thorough testing and debugging to ensure the extension's reliability and performance.
• Week 9-10: Fine-tune the user experience and address any usability issues or edge cases.
• Week 11-12: Document the extension's features, usage instructions, and contribute to community outreach and support.

Throughout the project, I'll maintain regular communication with mentors and provide updates on progress, challenges, and any adjustments to the schedule as necessary.

[FelicixAwe]

Hi, @ivangsa. I think this idea is interesting and would like to work on this one. Without further ado, I tried to write some codes for practice. Based on my understanding, we need to get those linting errors before applying any autofix. Below are two ways I figured could be possible solutions for retrieving error messages from spectral in phase 1:

1. Migrate spectral linting into extension
   According to spectral APIs, we can import spectral and initialize it for running spectral linting to get linting error messages.
2. Retrieve diagnostics thru VSCode API vscode.languages.getDiagnostics
   As vs code provides this API, we can use it to fetch errors.

Personally I prefer the second way as we already have a spectral extension out there so don't need to bother ourselves to integrate its functions into our own (also I could be wrong). Another reason I thought the second way is practical is because vscode provides API such as vscode.workspace.onDidChangeTextDocument which is consistent with a setting in Spectral: Spectral: Run -> onSave. Hence the whole workflow is clear that when Spectral running to give some errors, we can listen to this event and fetch them.

If anyone has any comments on this, welcome to discuss together!

P.S. Do we have any issue tagged "first issues" for this project?

vscode.CodeActionContext class provides diagnostic info containing message, code, range, and severity.

code is consistent with asyncAPI ruleset defined in @stoplight/spectral-rulesets. spectral-vscode imports ruleset from this package as well.

For phase 2: how to implement autofix feature,
I read the source code of spectral-vscode, spectual , and eslint, I think:

1. import from @stoplight/spectral-rulesets to set up rulesetMaps of rule metadata, we can use "code" from diagnostic as indexing the rule.
2. Inspired by @stoplight/spectral-rulesets and eslint's ruleset, we can define the function for "fixing" the problem in the definition of rulesets. Hence when any problems are found by spectral, we can easily indexing the corresponding rule in ruleMap, finding the fixing function and writing unit tests. Also giving options to determine if autofix is available or not.

Other things to note: when applying the fixing, sort the problems as their text range to avoid conflicts.