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

Mentors:
@ivangsa

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

Expected Difficulty:
Easy-Medium

Expected Time Commitment:
175 Hour

[Devanshu-17]

Hi @jansche @AceTheCreator,

I am Devanshu, a Postman Student Expert and an AIML Enthusiast.

From what I can understand, we need to Add an "Autofix" feature for common linting errors in AsyncAPI using Spectral. I believe it is a great idea and can greatly improve the developer experience.

I can think of few possible steps to implement this feature:

1. We can use the VSCode API to create a CodeActionProvider that provides a quick-fix for each identified linting error. The quick-fix should modify the API definition to fix the error.

2. Test the autofix feature by creating test cases for each identified linting error and verifying that the feature can automatically fix the error.

3. Integrate the autofix feature into the AsyncAPI-Preview extension and make it available to users.

And last but not the least, document the autofix feature and its usage.

[IllTamer]

Hey there 👋. I'm Poz Chou, a junior student from China.

I am a Minecraft community developer with 3 years of experience. I am committed to becoming a Full Stack engineer and just finished an internship in the last winter vacation.

I am good at using Java, GO, and TypeScript to solve problems. I like to learn and implement some application layer protocols (such as I have long maintained a robot based on the ONBOT protocol). I have also participated in some other open source events, such as GLCC (like Chinese GSOC).

I am very interested in this project. Once I start working, I promise to spend at least 25+ hours per week. At last, I really want to write a suitable proposal for this project. Is there anything I need to pay special attention? @jansche @AceTheCreator

[victormanuelfrancodev]

@jansche @AceTheCreator @IllTamer
Hi everybody.

I'm a FullStack developer, my strong skill is on mobile (swift, kotlin, Java, dart) but I'm feel confortable working with TypeScript or other languages like to C#,Python or JavaScript.
I have been involved in startup projects for a long time, but this time I would like to do something with a big company and I think it's a good time to do it
I'm interesting in this project because I would like to implement my knowledge with the programming of interpreters

I can spend some to 18 hrs per week.

[ivangsa]

Hi I'm @ivangsa the mentor for this proposal

These are some challenges we'll need to solve to implement this:

• Understand VSCode CodeActionProvider, it's important for our implementation to be efficient and not to block the UI while calculating which different fixes would be available for a given error
• Another challenge is to analyse Spectral rules for AsyncAPI and for which one it makes sense provide an autofix, some of them would be more obvious than other (i.ex a "missing description" should be easy to add, or a "potentially unused schema" should be easy to remove from the document)
• If we are going to edit (programatically) the user source code we need to respect as much as possible its current preferences: indentation style, quotation style... And edit only relevant parts of the document, and never reformat the whole document...
• As we categorise Spectral rules for AsyncAPI, we also need to create a file format to hold auto fixes for those rules: this file format should include all info necessary to perform the refactoring
• Also, sometimes the refactoring may require lookup information in the current document. We should take this into account and support it in the autofixes file format. (JSON-Path or similar for dynamic expressions)
• The biggest challenge of all, and maybe for a second stage/phase, would be to allow javascript functions and custom auto fix files. I know this is difficult but Spectral is already doing this for their custom rules, and we could get inspiration on how they do it.

Of all this challenges I would like to highlight the need to have a good set of utility methods (our internal framework) for editing/modifying documents:

• Adding a new property or nested object on a given JSONPath
• Removing a property or nested object
• Updating a property or nested object
• Appending a new property o nested object to an existing array
• And all the above should work either the target JSONPath already exists or we need to create it.

To compute json-path to source code and vice versa we could use:
https://github.com/stoplightio/yaml and https://github.com/stoplightio/json

Hope you all are doing well!!

We will talk about this later!!

Happy coding!! ❤️

[AceTheCreator]

Hey folks, I think it's high time y'all signup for the program via the website(https://summerofcode.withgoogle.com/) and start submitting your proposals officially before the deadline date @victormanuelfrancodev @IllTamer @Devanshu-17

[pragya-20]

Hi there!
My name is Pragya Bhardwaj, and I am a Software Developer based in India. I specialize in working with Javascript, JSON, React, and React Native, and have experience developing software applications using these technologies. I personally use ESLint for linting purposes along with Prettier for formatting.
I have gone through the project description and what I understand is that we are going to build a linter for AsyncAPI to start with, it highlights common errors such as someone declaring a variable twice or forgetting a semicolon and so on. Please correct me if my understanding is not quite right.
@ivangsa, I read your mentioned pointers and I understand the complexity of the task but I want to contribute to implementing this feature and am eager to work with the team.
Can you please guide me to pick good first issues related to this item, it will be helpful if you can provide me a link for that.

Thanks!

[Engeniusam]

Hello Folks,

My name Samuel Macharia, a student at Baraton University specializing in Frontend Software Engineering. I am also a Technical Writer and blogger. I have also 3-months newbie experience in open-source hence am an advocate for open-source contribution. I am also a postman student expert about to graduate to a postman student leader. I work with the MERN stack technologies.

I understand that AsyncAPI is a specification for designing and documenting asynchronous APIs. Linting is the process of analyzing code to find potential issues and errors. Spectral is a linting tool that allows developers to define rules to check the syntax and structure of AsyncAPI documents.

The project idea suggests adding an "Autofix" feature to Spectral for common linting errors in AsyncAPI documents. The Autofix feature would automatically correct these errors in the document without requiring manual intervention. This could save time and effort for developers who are working with AsyncAPI documents.

For example, if an AsyncAPI document contains an invalid property name or a missing required field, Spectral could identify the error and suggest a fix. The Autofix feature could then automatically correct the error by updating the property name or adding the missing field.

Overall, this project idea aims to improve the user experience for developers working with AsyncAPI documents by making it easier to identify and fix common linting errors.

I stand to be corrected.

I am delighted to be part of this team and eagerly waiting to contribute to this top-tier developers project.

Thank you.

[benjagm]

Closed as completed as part of 2023 edition.