CONTRIBUTING.md

Contributing to exhort-javascript-api

• Fork the repository
• Create a new branch
• Commit your changes
• Commits must be signed-off (see Certificate of Origin)
• Create a pull request against the main branch
• Pull request titles must adhere the Conventional Commits specification

Development

NPM Scripts

• npm run compile compile all TS and JS code into the dist folder
• npm run lint run eslint on JS source code
• npm run lint:fix fix eslint issues found in JS source code
• npm run test run unit tests,verify coverage, and print coverage info
• npm run tests run unit tests (no coverage)
• npm run tests:rep run unit tests and save the test results as unit-tests-result.json (for ci)
• npm run gen:backend generate the Backend types from its OpenAPI as TS spec in the generated/backend folder

Good to know

• You can override the default backend url by setting another one in the EXHORT_URL environment variable.

OpenAPI Specifications

We use our Backend's OpenAPI spec file for generating types used for deserialization of the Backend's API responses.
The generated classes files are TypeScript files generated in the generated/backend. Which is skipped when calculating coverage thresholds. Avoid writing code in this folder.
When the Backend's spec file is modified, we need to manually run the npm run gen:backend script. We only generate types.

Code Walkthrough

• index.js is the ESM Module starting point. It exports 2 functions: componentAnalysis and stackAnalysis. As well as the AnalysisReport type imported from the Backend's generated classes.
• cli.js is the starting point of the CLI Script, also used when installed as a Global Package. It describes two commands: component and stack. Use the help command to get more info.
• analysis.js exports two functions for communicating to the Backend. The requestComponent and requestStack functions.
• provider.js hosts the utility function for matching Providers based on the manifest type. New providers needs to be listed here.
• providers folder is where we place Providers. A Provider is basically 3 functions per supported ecosystem. The isSupported, provideComponent, and provideStack functions help determine the appropriate provider, which will provide data that we can send to the Backend using analysis.js. See the Adding a Provider section.
  • java_maven.js is the provider for the Java Maven ecosystem.

Types

This code is meant to be used as an ESM module for both JavaScript and TypeScript. So make sure you add type declarations if needed.
Note the sources are in JavaScript, and the generated Backend types are in TypeScript. Both will be compiled as an ESM Module including declarations (x.d.ts) in the ignored dist using the npm run compile script and the tsconfig.json configuration file. Also note the TypeScript files are excluded from both linting and coverage.

Adding a Provider

• Add the new provider code in a designated file in the providers' folder. A Provider exports 3 functions:

  • isSupported takes a manifest name as a string, i.e. pom.xml and returns true if it's supported by this provider.
  • provideComponent takes the manifest's content as a string and returns the ecosystem name, the content for the request body, and the content's type.
  • provideStack takes the manifest's path as a string and the ecosystem name, the content for the request body, and the content's type.

  The data returning from the provideX functions, will be passed on to the analysis.js for sending to the Backend. Use java_maven.js as an example to get you started.

• Import the new Provider and list in the in availableProviders array in provider.js.

• Update the choices configuration for the manifest-name positional argument in cli.js.

• Add Integration Test scenarios for the added provider in integration/scenarios. Use the java scenarios as an example.

• Update the documentation. This document and README.md.

Integration Tests

Integration tests are performed with a bash script executing node scripts.
In integration/run_its.sh we start with a function called match taking 2 arguments:

• $1 is a file name for the holding the expected result (scenarios)
• $2 is a command execution for evaluation (testers)

The match function will match the content of the file to the output of the command. Typically, test cases in integration/run_its.sh will invoke the match function with a scenario from the integration/scenarios and a node command invoking one of the node scripts in integration/testers.

We have 3 testers:

• integration/testers/cli is a package.json used for installing the ESM module. Invoking the CLI Script is done against the @RHEcosystemAppEng/exhort-javascript-api/dist/src/cli.js in the tester's node_modules.
• integration/testers/javascript is a javascript script invoking the ESM module.
• integration/testers/typescript is a typescript script invoking the ESM module.

Run integration tests from the project's root:

Don't forget to run npm run compile before running the integration tests.

(cd integration/ && bash ./run_its.sh)

Integration tests are executed against a mocked Backend server.
If you need to run against the actual Backend server, use the EXHORT_ITS_USE_REAL_API environment variable:

(cd integration/ && EXHORT_ITS_USE_REAL_API=true bash ./run_its.sh)

The mocked server implementation is integration/server/mock_server.js. See the integration/server/mock_server_config.json for configuring the mock server.

Certificate of Origin

By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution. See the DCO file for details.