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

[ivangsa]

AsyncAPI-Preview + Spectral for VSCode form a perfect combo interms 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 pourpose of this feature is to provide autofix refactoring for most common and standard spectral linting errors for asyncapi:
https://docs.stoplight.io/docs/spectral/1e63ffd0220f3-async-api-rules

Implementation

Phase One:

• Code Actions to be implemented and resolved inside this extension
• We will be supporting only standard spectral linting errors for asyncapi
• To compute json-path to source code and viceversa see
  https://github.com/stoplightio/yaml and https://github.com/stoplightio/json

Phase Two:

• Investigate how to load autofix rules from external files
• External autofix rule files could support also custom (non-standard) spectral linting rules

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[Savio629]

TO REMOVE STALE LABEL

[ankur0904]

@ivangsa
Hope you are doing well. I am writing to show interest in working on this issue under GSoC 2024.

As per my understanding of this issue. I conclude that

Our goal is: to provide auto-fix refactoring for the most common and standard spectral linting errors for Asyncapi.

As mentioned above, AsyncAPI-Preview + Spectral for VSCode is sufficient to achieve the functionality.

Spectral: It's an API style guide linter and enforcer. We can use Spectral rules to target API descriptions for quality improvement and enforce API style guides.

asyncapi-preview: It helps us to preview AsyncAPI documents inside VSCode.

Currently, I am exploring the Phase One of implementation.

Looking forward to working on this issue.

Thanks
Ankur

[nikhilkalburgi]

Hi @ivangsa,
My Short Investigation and Understanding of this issue so far is:
For Phase One:

1. Building codeActions to Apply QuickFixes:

   1. Following the example, a template can be created for this.

   2. Using Spectral Core API to fetch all the standard errors.

              import * as Spectral from '@stoplight/spectral';
              const spectral = new Spectral();
              spectral.setRules({ extends: "spectral:asyncapi" });
              const lintingResults = spectral.run(parsedYamlOrJSON);
              if (lintingResults.length > 0) {
                  // Handle linting errors
                    for (const result of lintingResults) {
                        autoFix(result, document, edit)
                    }
              }
      

2. Creating a file that contains all the QuickFix Rules for the Spectral Standard Linting Errors.

3. Building functions that handle the fixes based the rules defined in step 2.

        async function autoFix(error: any, document: vscode.TextDocument, edit: vscode.TextEditorEdit) {
        // Implement logic to fix the error for all the spectral linting rules
        }
   

For Phase Two:

1. Loading the Autofix rules from the file defined by the users for the Standard Linting Errors.

2. This file should also allow users to define the custom spectral errors which can be later parsed and submitted to the spectral API.

     // loadAutofixRules parses the file and separates the custom spectral rules from the autofix rules
     const customRules = loadAutofixRules('custom-rules-file','spectral');
     spectral.setRules({ extends: "spectral:asyncapi" , rules: { ...customRules } });
     // Lint the document using Spectral
     const lintingResults = spectral.run(parsedYaml);  
     . . .
   

3. The autoFix rules defined by the users here should override the file used in the step 3 of Phase One.

4. Modifying the autoFix Function:

     function autoFix(error: any, document: vscode.TextDocument, edit: vscode.TextEditorEdit) {
          if (<For Custom Errors>) {
            // Implement logic to fix custom error using the autofix rules in the user defined file
          } else {
            // Standard error using the autofix rules defined in the sourcecode file
          }
      }
   

Additionally, Adding Test Scripts to mock and test the autoFix Functions. For diagnosis, the spectral for VSCODE Extension can be used.

If you have some vacancy here, then I would like to further investigate and contribute to this Issue with the coming GSOC Implementation Phase along with the Markdown+Mermaid Preview Feature. For which may need your support to build the implementation plan.

[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 and find the fixing function. 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.