Skip to main content

Retrieves

Retrieves is the product responsible for the VSCode plugin. This product communicates with the Integrates API to get live vulnerability data and mark it on the users' editors.

Internals

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

    When telemetry is enabled, it reports/logs debugging information to Bugsnag, where developers can consume it to improve exception handling and improve the program's logic to protect against crashes. It communicates with the Fluid Attacks Platform through the API in order to fetch Vulnerability information and autofix data when requested.

  2. The application is divided in two sections:

    • extension (entrypoint: src/extension.ts), which is the main part of the application. This section 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), which uses React and houses the webviews (Finding description, Suggested autofix, ToE Lines, etc...). These webviews and the extension proper communicate through message handlers. See this link for more information. Webpack also bundles this section.

Tooling

Helpful tools for extension development:

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 or None. You will need to have Node v21 installed beforehand.

Open the editor on the base folder /universe/integrates/retrieves and from a terminal on 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 bump the version number in the package.json file present 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, meaning:

  • 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 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 an 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).