Skip to content

Commit 807a659

Browse files
TomerFiTomerFi
authored
docs: update readme and contributing (#13)
* docs: update README Signed-off-by: Tomer Figenblat <[email protected]> * docs: added contribution guidelines Signed-off-by: Tomer Figenblat <[email protected]> --------- Signed-off-by: Tomer Figenblat <[email protected]>
1 parent 9f45144 commit 807a659

File tree

2 files changed

+215
-2
lines changed

2 files changed

+215
-2
lines changed

‎CONTRIBUTING.md‎

Lines changed: 79 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,79 @@
1-
# WIP
1+
# Contributing to *crda-javascript-api*<br/>![nodejs-version][10]
2+
3+
* Fork the repository
4+
* Create a new branch
5+
* Commit your changes
6+
* Commits <strong>must</strong> be signed-off (see [Certificate of Origin](#certificate-of-origin))
7+
* Create a pull request against the main branch
8+
* Pull request titles <strong>must</strong> adhere the [Conventional Commits specification][0]
9+
10+
## Development
11+
12+
### NPM Scripts
13+
14+
* `npm run compile` compile all _TS_ and _JS_ code into the _dist_ folder
15+
* `npm run lint` run eslint on _JS_ source code
16+
* `npm run lint:fix` fix eslint issues found in _JS_ source code
17+
* `npm run test` run unit tests,verify coverage, and print coverage info
18+
* `npm run tests` run unit tests (no coverage)
19+
* `npm run tests:rep` run unit tests and save the test results as _unit-tests-result.json_ (for ci)
20+
* `npm run gen:backend` generate the _Backend_ types from its _OpenAPI_ as _TS_ spec in the _generated/backend_ folder
21+
22+
### OpenAPI Specifications
23+
24+
We use our [Backend's OpenAPI spec file][1] for generating types used for deserialization of the Backend's
25+
API responses.<br/>
26+
The generated classes files are _TypeScript_ files generated in the [generated/backend](generated/backend).
27+
Which is skipped when calculating coverage thresholds. **Avoid writing code in this folder.**<br/>
28+
When the [Backend's spec file][1] is modified, we need to **manually** run the `npm run gen:backend` script.
29+
We only generate types.
30+
31+
### Code Walkthrough
32+
33+
* [index.js](src/index.js) is the _ESM Module_ starting point. It exports 2 functions: _componentAnalysis_ and _stackAnalysis_.
34+
As well as the _AnalysisReport_ type imported from the _Backend_'s generated classes.
35+
* [cli.js](src/cli.js) is the starting point of the _CLI Script_, also used when installed as a _Global Package_.
36+
It describes two commands: _component_ and _stack_. Use the _help_ command to get more info.
37+
* [analysis.js](src/analysis.js) exports two functions for communicating to the _Backend_.
38+
The _requestComponent_ and _requestStack_ functions.
39+
* [provider.js](src/provider.js) hosts the utility function for matching _Providers_ based on the manifest type.
40+
New providers needs to be listed here.
41+
* [providers](src/providers) folder is where we place _Providers_. A _Provider_ is basically 3 functions per supported ecosystem.
42+
The _isSupported_, _provideComponent_, and _provideStack_ functions help determine the appropriate provider,
43+
which will provide data that we can send to the _Backend_ using _analysis.js_. See the [Adding a Provider](#adding-a-provider) section.
44+
* [java_maven.js](src/providers/java_maven.js) is the provider for the _Java_ _Maven_ ecosystem.
45+
46+
#### Types
47+
48+
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.<br/>
49+
Note the [sources](src) are in _JavaScript_, and the [generated](generated/backend) _Backend_ types are in _TypeScript_.
50+
Both will be compiled as an _ESM Module_ including declarations (_x.d.ts_) in the ignored _dist_ using the `npm run compile` script
51+
and the [tsconfig.json](tsconfig.json) configuration file. Also note the _TypeScript_ files are excluded from both linting and coverage.
52+
53+
#### Adding a Provider
54+
55+
* Add the new provider code in a designated file in the [providers'](src/providers) folder.
56+
A _Provider_ exports 3 functions:
57+
* _isSupported_ takes a manifest name as a string, i.e. _pom.xml_ and returns _true_ if it's supported by this provider.
58+
* _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.
59+
* _provideStack_ takes the **manifest's path** as a string and the ecosystem name, the content for the request body, and the content's type.
60+
61+
The data returning from the _provideX_ functions, will be passed on to the [analysis.js](src/analysis.js) for sending to the _Backend_.
62+
Use [java_maven.js](src/providers/java_maven.js) as an example to get you started.
63+
* Import the new _Provider_ and list in the in _availableProviders_ array in [provider.js](src/provider.js).
64+
* Update the _choices_ configuration for the _manifest-name_ positional argument in [cli.js](src/cli.js).
65+
* Update the documentation. This document and [README.md](README.md).
66+
67+
## Certificate of Origin
68+
69+
By contributing to this project you agree to the Developer Certificate of
70+
Origin (DCO). This document was created by the Linux Kernel community and is a
71+
simple statement that you, as a contributor, have the legal right to make the
72+
contribution. See the [DCO](DCO) file for details.
73+
74+
<!-- Real links -->
75+
[0]: https://www.conventionalcommits.org/en/v1.0.0/
76+
[1]: https://github.com/RHEcosystemAppEng/crda-backend/blob/main/src/main/resources/META-INF/openapi.yaml
77+
78+
<!-- Badge links -->
79+
[10]: https://badgen.net/badge/NodeJS%20Version/18/68a063

‎README.md‎

Lines changed: 136 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,136 @@
1-
# WIP
1+
# CodeReady Dependency Analytics JavaScript API<br/>![latest-no-snapshot][0] ![latest-snapshot][1]
2+
3+
> This project is still a WIP. Currently, only Java's Maven ecosystem is implemented.
4+
5+
The _Crda JavaScript API_ module is deployed to _GitHub Package Registry_.
6+
7+
Looking for our Java API? Try [Crda Java API](https://github.com/RHEcosystemAppEng/crda-java-api).
8+
9+
<details>
10+
<summary>Click here for configuring <em>GHPR</em> and gaining access to the <em>crda-javascript-api</em> module.</summary>
11+
12+
<h3>Create your token</h3>
13+
<p>
14+
Create a
15+
<a href="https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages#authenticating-to-github-packages">token</a>
16+
with the <strong>read:packages</strong> scope<br/>
17+
18+
> Based on
19+
> <a href="https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages">GitHub documentation</a>,
20+
> In <em>Actions</em> you can use <em>GITHUB_TOKEN</em>
21+
22+
</p>
23+
24+
<h3>Configure <em>GHPR</em> access for <em>NPM</em></h3>
25+
26+
<p>
27+
28+
Add the following line to the <em>.npmrc</em> file in your user home:<br/>
29+
See [GH Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token)
30+
31+
```text
32+
//npm.pkg.github.com/:_authToken=<your-ghp-token-goes-here>
33+
```
34+
35+
</p>
36+
37+
</details>
38+
39+
<h3>Usage</h3>
40+
<p>
41+
Instruct <em>NPM</em> to look in <em>GHPR</em> for the <em>RHEcosystemAppEng</em> namespace.<br/>
42+
Add <code>@RHEcosystemAppEng:registry=https://npm.pkg.github.com</code> to <em>.npmrc</em> in either the project root or user home:
43+
44+
```shell
45+
echo "@RHEcosystemAppEng:registry=https://npm.pkg.github.com" >> .npmrc
46+
```
47+
48+
</p>
49+
50+
<ul>
51+
52+
<li>Use as ECM Module</li>
53+
<p>
54+
55+
```shell
56+
npm install @RHEcosystemAppEng/crda-javascript-api
57+
```
58+
59+
```javascript
60+
import crda from '@RHEcosystemAppEng/crda-javascript-api'
61+
import fs from 'node:fs'
62+
63+
// Get stack analysis in JSON format
64+
let jsonStackAnalysis = await crda.stackAnalysis('/path/to/pom.xml')
65+
// Get stack analysis in HTML format (string)
66+
let htmlStackAnalysis = await crda.stackAnalysis('/path/to/pom.xml', true)
67+
68+
// Get component analysis in JSON format
69+
let buffer = fs.readFileSync('/path/to/pom.xml')
70+
let jsonComponentAnalysis = await crda.componentAnalysis('pom.xml', buffer.toString())
71+
72+
```
73+
74+
</p>
75+
76+
<li>Use as CLI Script</li>
77+
<p>
78+
79+
```shell
80+
$ npx @RHEcosystemAppEng/crda-javascript-api help
81+
82+
Usage: crda-javascript-api {component|stack}
83+
84+
Commands:
85+
crda-javascript-api stack </path/to/manifest> [--html|--summary] produce stack report for manifest path
86+
crda-javascript-api component <manifest-name> <manifest-content> [--summary] produce component report for a manifest type and content
87+
88+
Options:
89+
--help Show help [boolean]
90+
```
91+
92+
```shell
93+
# get stack analysis in json format
94+
$ npx @RHEcosystemAppEng/crda-javascript-api stack /path/to/pom.xml
95+
96+
# get stack analysis in json format (summary only)
97+
$ npx @RHEcosystemAppEng/crda-javascript-api stack /path/to/pom.xml --summary
98+
99+
# get stack analysis in html format format
100+
$ npx @RHEcosystemAppEng/crda-javascript-api stack /path/to/pom.xml --html
101+
102+
# get component analysis
103+
$ npx @RHEcosystemAppEng/crda-javascript-api component pom.xml "$(</path/to/pom.xml)"
104+
```
105+
106+
</p>
107+
108+
<li>Use as Global Binary</li>
109+
110+
<p>
111+
112+
```shell
113+
npm install --global @RHEcosystemAppEng/crda-javascript-api
114+
```
115+
116+
```shell
117+
# get stack analysis in json format
118+
$ crda-javascript-api stack /path/to/pom.xml
119+
120+
# get stack analysis in json format (summary only)
121+
$ crda-javascript-api stack /path/to/pom.xml --summary
122+
123+
# get stack analysis in html format format
124+
$ crda-javascript-api stack /path/to/pom.xml --html
125+
126+
# get component analysis
127+
$ crda-javascript-api component pom.xml "$(</path/to/pom.xml)"
128+
```
129+
130+
</p>
131+
132+
</ul>
133+
134+
<!-- Badge links -->
135+
[0]: https://img.shields.io/github/v/release/RHEcosystemAppEng/crda-javascript-api?color=green&label=latest
136+
[1]: https://img.shields.io/github/v/release/RHEcosystemAppEng/crda-javascript-api?color=yellow&include_prereleases&label=early-access

0 commit comments

Comments
 (0)