@createiq/bom-licenses

@createiq/bom-licenses

Take one or more CycloneDX SBOMs and generate license information for dependencies.

Justification

This is useful for collating dependencies from potentially multiple different generated CycloneDX BOMs, but publishing license information in a single place - e.g. putting both a backend and frontend repository's BOM together and putting attribution on a single page.

Usage

Example:

npx @createiq/bom-licenses \
    --output oss-licenses.json \
    frontend.bom.json backend.bom.json

All options:

   ____                      _       _          ___                           _ _
  / __ \  ___ _ __ ___  __ _| |_ ___(_) __ _   / / |__   ___  _ __ ___       | (_) ___ ___ _ __  ___  ___  ___
 / / _` |/ __| '__/ _ \/ _` | __/ _ \ |/ _` | / /| '_ \ / _ \| '_ ` _ \ _____| | |/ __/ _ \ '_ \/ __|/ _ \/ __|
| | (_| | (__| | |  __/ (_| | ||  __/ | (_| |/ / | |_) | (_) | | | | | |_____| | | (_|  __/ | | \__ \  __/\__ \
 \ \__,_|\___|_|  \___|\__,_|\__\___|_|\__, /_/  |_.__/ \___/|_| |_| |_|     |_|_|\___\___|_| |_|___/\___||___/
  \____/                                  |_|
Usage: bom-licenses [options] <input...>

Take one or more CycloneDX SBOMs and generate license information for dependencies

Arguments:
  input                             input BOM files to parse

Options:
  -V, --version                     output the version number
  -o, --output <file>               output file name (default: stdout)
  --output-basedir <directory>      output base directory (default: current working directory)
  --overrides <json>                license overrides, a JSON object of purl to a SPDX expression (e.g. { "pkg:maven/tyrex/tyrex@1.0.1": "EXOLAB" }) (default: {})
  --prefer <json>                   where packages have OR licenses, use the first one found in preference order (e.g. ["Unlicense", "MIT", "Apache-2.0"]) (default: [])
  --hash                            generate a hash of license (useful for inclusion in npm library to check whether it needs to be updated)
  --generate-npm-library <package>  generate an npm library with the license information
  --publish-npm-library             publish the generated npm library
  --publish-npm-library-dry-run     publish the generated npm library (dry run) (env: PUBLISH_NPM_LIBRARY_DRY_RUN)
  -h, --help                        display help for command

Using a configuration file

You can also specify options using a bom-licenses.config.(js|cjs|mjs|ts} file, which should have a single default object export. If you're using a ts file, you can use the BomLicensesConfig type to verify your config matches the type.

Configuration keys:

• file: (type: string) a reference to a single file BOM file (cannot be specified at the same time as files)
• files: (type: string[]) a reference to one or more BOM files (cannot be specified at the same time as file)
• output: (type: string, default -) the output file name for the licenses file, or - for STDOUT
• outputBasedir: (type: string, default current working directory) the directory to output files in
• overrides: (type: object) an object keyed with package-urls from the BOM pointing to SPDX license expressions
• prefer: (type: array) an array of SPDX license IDs to prefer where a dependency has multiple licenses
• hash: (type: boolean) whether to generate a sha256 hash of the output
• npmLibrary.name: (type: string) the package name of the npm library to output if this is set
• npmLibrary.publish: (type: boolean or 'dry-run') whether to publish the npm library

Contributing

The library uses Biome for linting and formatting, and Vitest for unit tests and benchmarking. It's worth ensuring that you have appropriate plugins for your development environment, particularly for Biome to avoid having to fix formatting issues late.

Releasing

Merge requests to the main branch should be reviewed by the team as normal but will not release a new version of the library to npm. This happens when merge requests are made to the prod branch, this should be an MR directly from main to prod and MUST include a bump to the version in package.json satisfying semver.