Skip to content

Commit

Permalink
docs: reorganize responsibilities and capabilities sections
Browse files Browse the repository at this point in the history 
Reorganizes the responsibilities and capabilities sections for better clarity and organization, as requested in issue #485

Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com>
  • Loading branch information
@HmbleCreator
HmbleCreator authored Oct 22, 2024
1 parent 75aff7d commit 87cefee
Showing 1 changed file with 173 additions and 73 deletions.
246 changes: 173 additions & 73 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

[![shield_npm-version]][link_npm]
[![shield_rtfd]][link_rtfd]
[![shield_gh-workflow-test]][link_gh_workflow_test]
[![shield_gh-workflow-test]][link_gh-workflow-test]
[![shield_coverage]][link_codacy]
[![shield_ossf-best-practices]][link_ossf_best_practices]
[![shield_ossf-best-practices]][link_ossf-best-practices]
[![shield_license]][license_file]
[![shield_website]][link_website]
[![shield_slack]][link_slack]
Expand All @@ -13,48 +13,54 @@

----

Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or _WebBrowsers_), written in _TypeScript_ and compiled for the target.
Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or _WebBrowsers_),
written in _TypeScript_ and compiled for the target.

## Responsibilities

* Provide a general-purpose _JavaScript_-implementation of [_CycloneDX_][link_website] for _Node.js_ and _WebBrowsers_.
* Provide typing for said implementation, so developers and dev-tools can rely on it.
* Provide data models to work with _CycloneDX_.
* Provide JSON- and XML-normalizers that:
* Support all shipped data models.
* Respect any injected [_CycloneDX_ Specification][CycloneDX-spec] and generate valid output according to it.
* Can be configured to generate reproducible/deterministic output.
* Can prepare data structures for JSON- and XML-serialization.
* Serialization:
* Provide a universal JSON-serializer for all target environments.
* Provide an XML-serializer for all target environments.
* Support the downstream implementation of custom XML-serializers tailored to specific environments by providing an abstract base class that takes care of normalization and BomRef-discrimination. This is done because there is no universal XML support in _JavaScript_.
* Provide formal JSON- and XML-validators according to [_CycloneDX_ Specification][CycloneDX-spec] (currently for _Node.js_ only).
The CycloneDX JavaScript Library is responsible for:

* Providing a general purpose JavaScript implementation of CycloneDX for Node.js and WebBrowsers
* Providing comprehensive TypeScript typings for developer tooling support
* Implementing core CycloneDX data models
* Providing JSON and XML normalizers that:
* Support all shipped data models
* Respect injected CycloneDX Specifications and generate valid output
* Can be configured for reproducible/deterministic output
* Prepare data structures for JSON and XML serialization
* Handling serialization through:
* Universal JSON serializer for all target environments
* XML serializer for all target environments
* Support for custom XML serializer implementations via abstract base class
* Providing formal JSON and XML validators according to CycloneDX Specification (Node.js only)

## Capabilities

* **Enums** for the following use cases:
* `AttachmentEncoding`
* `ComponentScope`
* `ComponentType`
* `ExternalReferenceType`
* `HashAlgorithm`
* **Vulnerability** related:
* `AffectStatus`
* `AnalysisJustification`
* `AnalysisResponse`
* `AnalysisState`
* `RatingMethod`
* `Severity`

* **Data Models** for the following use cases:
The library provides:

### Enums
* `AttachmentEncoding`
* `ComponentScope`
* `ComponentType`
* `ExternalReferenceType`
* `HashAlgorithm`
* Vulnerability-related:
* `AffectStatus`
* `AnalysisJustification`
* `AnalysisResponse`
* `AnalysisState`
* `RatingMethod`
* `Severity`

### Data Models
* Core Models:
* `Attachment`
* `Bom`
* `BomLink`, `BomLinkDocument`, `BomLinkElement`
* `BomRef`, `BomRefRepository`
* `Component`, `ComponentRepository`, `ComponentEvidence`
* `ExternalReference`, `ExternalReferenceRepository`
* `Hash`, `HashContent`, `HashDictionary`
* `Hash`, `HashContent`, `HashDictionary`
* `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository`
* `Metadata`
* `OrganizationalContact`, `OrganizationalContactRepository`
Expand All @@ -63,52 +69,146 @@ Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or
* `SWID`
* `Tool`, `ToolRepository`

* **Vulnerability** related:
- `Advisory`, `AdvisoryRepository`
- AffectedSingleVersion, AffectedVersionRange, AffectedVersionRepository
- Analysis
- Credits
- Rating, RatingRepository
- Reference, ReferenceRepository
- Source
- Vulnerability, VulnerabilityRepository

* **Utilities** for the following use cases:
* Generate valid random SerialNumbers for Bom.serialNumber.

* **Factories** for the following use cases:
* Create data models from any license descriptor string.
* Create PackageURL from Component data models.
* Specific to _Node.js_: create data models from PackageJson-like data structures and derived data.

* **Builders** for the following use cases:
* Specific to _Node.js_: create deep data models Tool or Component from PackageJson-like data structures.

* **Implementation of the [_CycloneDX_ Specification][CycloneDX-spec]** for the following versions:
* `1.6`
* `1.5`
* `1.4`
* `1.3`
* `1.2`

* **Normalizers** that convert data models to JSON structures.

* **Normalizers** that convert data models to XML structures.

* **Universal serializer** that converts Bom data models to JSON string.

* **Specific Serializer** that converts Bom data models to XML string:
- Specific to _WebBrowsers_: implementation utilizes browser-specific document generators and printers.
- Specific to _Node.js_: implementation utilizes [optional dependencies](#optional-dependencies) as described below.

* **Formal validators** for JSON string and XML string (currently for _Node.js_ only).
Requires [optional dependencies](#optional-dependencies) as described below.
* Vulnerability Models:
* `Advisory`, `AdvisoryRepository`
* `Affect`, `AffectRepository`, `AffectedSingleVersion`, `AffectedVersionRange`, `AffectedVersionRepository`
* `Analysis`
* `Credits`
* `Rating`, `RatingRepository`
* `Reference`, `ReferenceRepository`
* `Source`
* `Vulnerability`, `VulnerabilityRepository`

### Utilities
* SerialNumber generation for `Bom.serialNumber`
* License descriptor string parsing
* PackageURL generation from Component models
* Node.js-specific utilities for PackageJson handling

### CycloneDX Specification Support
* Version 1.6
* Version 1.5
* Version 1.4
* Version 1.3
* Version 1.2

## Installation

This package and the build results are available for _npm_, _pnpm_, and _yarn_:
This package and the build results are available for _npm_, _pnpm_ and _yarn_:

```shell
npm i -S @cyclonedx/cyclonedx-library
pnpm add @cyclonedx/cyclonedx-library
yarn add @cyclonedx/cyclonedx-library
```

You can install the package from source,
which will build automatically on installation:

```shell
npm i -S github:CycloneDX/cyclonedx-javascript-library
pnpm add github:CycloneDX/cyclonedx-javascript-library
yarn add @cyclonedx/cyclonedx-library@github:CycloneDX/cyclonedx-javascript-library # only with yarn-2
```

## Optional Dependencies

Some dependencies are optional.
See the shipped `package.json` for version constraints.

* Serialization to XML on _Node.js_ requires any of:
* [`xmlbuilder2`](https://www.npmjs.com/package/xmlbuilder2)
* Validation of JSON on _Node.js_ requires all of:
* [`ajv`](https://www.npmjs.com/package/ajv)
* [`ajv-formats`](https://www.npmjs.com/package/ajv-formats)
* [`ajv-formats-draft2019`](https://www.npmjs.com/package/ajv-formats-draft2019)
* Validation of XML on _Node.js_ requires all of:
* [`libxmljs2`](https://www.npmjs.com/package/libxmljs2)
* the system might need to meet the requirements for [`node-gyp`](https://github.com/TooTallNate/node-gyp#installation), in certain cases.

## Usage

See extended [examples].

### As _Node.js_ package

```javascript
const CDX = require('@cyclonedx/cyclonedx-library')

const bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
CDX.Enums.ComponentType.Application,
'MyProject'
)
const componentA = new CDX.Models.Component(
CDX.Enums.ComponentType.Library,
'myComponentA',
)
bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)
```

### In _WebBrowsers_

```html
<script src="path-to-this-package/dist.web/lib.js"></script>
<script type="application/javascript">
const CDX = CycloneDX_library
let bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
CDX.Enums.ComponentType.Application,
'MyProject'
)
const componentA = new CDX.Models.Component(
CDX.Enums.ComponentType.Library,
'myComponentA',
)
bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)
</script>
```

## API documentation

We ship annotated type definitions, so that your IDE and tools may pick up the documentation when you use this library downstream.

There are also pre-rendered documentations hosted on [readthedocs][link_rtfd].

## Development & Contributing

Feel free to open issues, bug reports or pull requests.
See the [CONTRIBUTING][contributing_file] file for details.

## License

Permission to modify and redistribute is granted under the terms of the Apache 2.0 license.
See the [LICENSE][license_file] file for the full license.

[CycloneDX-spec]: https://github.com/CycloneDX/specification/#readme

[license_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/LICENSE
[contributing_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/CONTRIBUTING.md
[examples]: https://github.com/CycloneDX/cyclonedx-javascript-library/tree/main/examples/README.md
[link_rtfd]: https://cyclonedx-javascript-library.readthedocs.io

[shield_npm-version]: https://img.shields.io/npm/v/%40cyclonedx%2fcyclonedx-library/latest?label=npm&logo=npm&logoColor=white "npm"
[shield_rtfd]: https://img.shields.io/readthedocs/cyclonedx-javascript-library?logo=readthedocs&logoColor=white "Read the Docs"
[shield_gh-workflow-test]: https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-javascript-library/nodejs.yml?branch=main&logo=GitHub&logoColor=white "tests"
[shield_coverage]: https://img.shields.io/codacy/coverage/ae6c086b53d54653ad5077b12ec22264?logo=Codacy&logoColor=white "test coverage"
[shield_ossf-best-practices]: https://img.shields.io/cii/percentage/7883?label=OpenSSF%20best%20practices "OpenSSF best practices"
[shield_license]: https://img.shields.io/github/license/CycloneDX/cyclonedx-javascript-library?logo=open%20source%20initiative&logoColor=white "license"
[shield_website]: https://img.shields.io/badge/https://-cyclonedx.org-blue.svg "homepage"
[shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join"
[shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion"
[shield_twitter-follow]: https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white "twitter follow"

[link_website]: https://cyclonedx.org/
[link_npm]: https://www.npmjs.com/package/%40cyclonedx/cyclonedx-library

[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-javascript-library/actions/workflows/nodejs.yml?query=branch%3Amain
[link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-javascript-library/dashboard
[link_ossf-best-practices]: https://www.bestpractices.dev/projects/7883
[link_slack]: https://cyclonedx.org/slack/invite
[link_discussion]: https://groups.io/g/CycloneDX
[link_twitter]: https://twitter.com/CycloneDX_Spec

0 comments on commit 87cefee

Please sign in to comment.