- 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
npm run compile
compile all TS and JS code into the dist foldernpm run lint
run eslint on JS source codenpm run lint:fix
fix eslint issues found in JS source codenpm run test
run unit tests,verify coverage, and print coverage infonpm 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
- You can override the default backend url by setting another one in the EXHORT_URL environment variable.
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.
- 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.
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.
-
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 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.
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.