-
Notifications
You must be signed in to change notification settings - Fork 7
VSCode Plugin Implementation Notes
Per issue #176, this wiki page is set-up containing information about possible AaC features and capabilities leveraging VSCode plugins, and what it would take to bring that functionality to AaC.
The VSCode team have a great article with some good practices for creating VSCode plugins.
This section focuses on what capabilities VSCode Plugins provide and how we might leverage those capabilities for AaC users.
Allows users to execute an action or command quickly via the F1 menu.
Could be used to allow users to execute AaC commands such as validating, linting, or even generating PlantUML diagrams from the AaC file currently open in the editor window.
Allows plugins to expose their own configuration options so that users can personalize their extension experience.
Could be used to allow the user to personalize their AaC plugins and tools experience. This could leveraged for default output directories for AaC generation commands, verbosity output level, etc.
Allows plugins to add custom keybindings/keyboard shortcuts.
Would likely be used in conjunction with the language server for features like calling validation, formatting, etc on the document or selected text.
Extensions can add extra menu items for specific contexts. The list of conditions for context menus can be found here. Read more about the menus api here.
Would likely be used in conjunction with the language server for features like validation, formatting, references, implementations, etc.
Allows notifications to fire off a small message to alert or prompt the user.
Could be used to notify users of state change (AaC command results), plugin crash messages, etc. Less is more for notifications.
Allows a user to provide user input.
Could be used to supply user input to AaC commands and AaC plugin commands. Could also be leveraged for quick-searching AaC files for root keys, definition names, etc.
VSCode provides a file picker interface for selecting files and folders.
Would be useful for any user file IO interactions, like selecting architecture files to open, select generated output destinations, etc.
Provides progress bars for long-running commands.
Could be useful for visualizing the progress of long-running commands, but we don't currently have any sufficiently complex or large enough plugins or source sets that would require us implement a progress bar.
VSCode plugins can also extend the "workbench" UI which includes the:
- Title Bar
- Activity Bar
- Side Bar
- Panel
- Editor Group
- Status Bar
The lefthand menu of icons, known as the activity bar (see A), can have additional views provided by plugins.
A dedicated view for AaC would be a great choice to group the AaC plugin UI functionality.
When an icon on the activity bar is selected, it opens the side bar menu (see B) which contains any number of views.
These views can be leveraged to provide the user information in typically a hierarchical tree view or as a list. These views would be great for presenting the user with the list of AaC definitions and models (validation status), actively installed plugins, available AaC commands, etc.
Additional panels (see D) can be inserted alongside the .
At the bottom of the editor is the status bar, typically used for ongoing status for functions such as linting, language server processing, formatting, etc. (see E)
This would be great to leverage with the language server. As noted in the section regarding progress bars, this would be great to leverage when we see longer AaC usecases where reporting status would improve the UX.
The editor group consists of Webviews, highly customizeable windows/tabs built using HTML/CSS/JS. (see C)
Webviews have extensive customization and potential, but they could be used for drag-and-drop editors, charts and visualizations, customized editors,
Tasks are a great interface for incorporating 3rd party tools into VSCode extensions.
Tasks would be one avenue of integrating AaC into a VSCode plugin, but that would require the user also install the AaC python package in the development environment in order to use the plugin which may be off-putting.
The task provider can compute available tasks and provide a dynamically calculated list of tasks to the user. (see)
The task provider would complement the Tasks wonderfully by using the results of the AaC plugin's to drive the Tasks that the user can select from. This would allow us to bypass hardcoding tasks and it would fit perfectly with the python plugin model.
The technical requirements for implementing a VSCode plugin.
VSCode Plugins are built using Javascript or Typescript, and so it is the only language option.
The VSCode plugin leverages NodeJS, and it expects an opinionated javascript/typescript project structure, not dissimilar to how our AaC repository is very python centric. We would need to either adopt a multiproject structure in the repository, or create a new AaC VSCode plugin project.
The largest impact for project-per-repository would be managing multiple github repositories, and any extra corporate red tape that comes with it. A multi-project repository is very easy to operate in given good, explicit, and upfront documentation about the structure and any scripts that are used to alleviate the complexities of the project. (Things like comprehensive building/testing/deploying via scripts instead of per project commands).
The technical considerations for implementing a VSCode plugin.
VSCode extensions need be designed with virtual workspaces in mind or they could suffer error conditions resulting from relying on local files, inadequate filesystem IO abstraction, and require synchronous file access, etc. See the VSCode team's notes.
Virtual workspaces will certainly have an impact on our team as working in a remote environment such as Gitpod, connecting over SSH, and running in a container would require the AaC plugin to adequately support the virtual workspace, which may conflict with the need for a local AaC package installation or the installation of AaC plugins. This should be investigated further. See the referenced notes on how to test plugins in a virtual environment. (Debugging them in gitpod should also be sufficient)
Alongside deploying VSCode plugins to the Visual Studio Code Marketplace, we should also deploy the plugin to the Open-VSX Registry. Open-VSX is an eclipse foundation open-source alternative to the Visual Studio Code Marketplace because Microsoft prevents 3rd parties from using the marketplace per their TOS. Supporting and deploying the plugin to Open-VSX is also self-serving as Open-VSX is the registry used by gitpod instances.
The strategy for plugins leveraging 3rd party tools appears to be that of leaving it to the user to properly configure their workspace. For AaC, this would mean the user must have a python3.9+ environment and download the aac package via pip. That's the same strategy Microsoft uses with their Python plugin and the formatting tool black. We also see the same strategy for (Benten the CWL language server plugin)[https://github.com/rabix/benten#using-pipx] and the (fortran language server)[https://github.com/hansec/fortran-language-server#installation]
The VSCode Plugin would need to integrate with the AaC package either via Tasks or the Language Server (or both). Tasks would be the perferred API for executing non linting AaC features like code generation, and can be implemented easily via a Task Provider. The Language server should handle the linting and long-running watching processes.
As of now, it appears that at a high-level we would need to:
- Create a VSCode Plugin
- Implement a process executor for AaC
- Implement a Task Provider
- Use AaC command results to drive available tasks
- Update user documentation to include plugin installation steps, including downloading the AaC package.
Depending on the limitations with the language server implementation, the above should be