Retrieves

Retrieves is the product responsible for the VSCode plugin. It communicates with the Integrates API to fetch live vulnerability data and mark it in users' editors.

Internals

1. Retrieves is written in Typescript with React used for the Webview section. Webpack bundles the code deployed to the marketplace.

   When telemetry is enabled, debugging information is reported/logged to Bugsnag, where developers can use it to improve exception handling and enhance the program's logic to prevent crashes. It communicates with the Fluid Attacks Platform through the API to retrieve Vulnerability information and autofix data upon request.

2. The application is divided into two sections:

   • Extension (entrypoint: src/extension.ts): This is the main part of the application, which also consumes the Integrates API and interfaces with the vscode library to mark vulnerabilities and populate the sidebar. Webpack bundles this section.
   • Webview (entrypoint: src/webview/App.tsx): This uses React and hosts the webviews (Finding description, Suggested autofix, ToE Lines, etc...). These webviews and the extension communicate through message handlers. For more information, refer to this link. Webpack also bundles this section.

Tooling

Helpful tools for extension development:

• tsl problem matcher
• Jest Runner
• ESLint
• Prettier

Getting started

Follow the steps in the Development Environment section of our documentation.

When prompted for an AWS role, choose dev, and when prompted for a Development Environment, pick any option or None. You will need to have Node v21 installed beforehand.

Open the editor in the base folder /universe/integrates/retrieves and from a terminal in the same folder run:

npm install

To view the changes reflected as you edit the code:

• For extension: Launch the Extension Development Host by pressing F5; this will bundle the code and launch Webpack in watch mode. Despite Webpack's hot reloading, some changes may require a manual reload of the Extension Host to be reflected.
• For webview: Follow the steps above, and the new changes to the code will be immediately reflected thanks to Webpack dev server's hot reloading.

Versioning

To publish your changes to the VSCode marketplace, you must increment the version number in the package.json file located in the Retrieves base folder. Otherwise, the change will be merged to trunk, but the publication/deployment process will be skipped.

Retrieves follows the MAJOR.MINOR.PATCH scheme for versioning:

• MAJOR: Breaking changes.
• MINOR: Backward compatible changes.
• PATCH: Bugfixes.

For more info, see the semver documentation.

Linting

Retrieves uses ESLint and Prettier to enforce compliance with a defined coding style.

To view linting issues globally, you can run:

  npm run lint

or

  m . /integrates/retrieves/lint

Testing

Unit tests

Retrieves uses Jest as a test runner and MSW to mock API responses for unit tests.

To execute the test cases on your computer, you can run:

  npm run test

or

  m . /integrates/retrieves/test

To execute test cases individually, you can install the Jest Runner extension and run or debug the tests from the UI.

E2E tests

Retrieves supports end-to-end testing trough a web technology for serving VSCode locally called code-server. This way, cypress can be used as the testing framework. When executed, these tests run a standalone server of VSCode accessible in the browser at: http://localhost:9090. Retrieves e2e tests run with a user access token with access to VBD roots under Makimachi > Asgard: bwapp and WebGoat .

Execute headless e2e tests with:

  m .  /integrates/retrieves/test/e2e run

Or, if you wish to run them interactively with the Cypress GUI:

  m .  /integrates/retrieves/test/e2e open

note

If running e2e tests locally, make sure you have a running integrates instance (m . /integrates).