Allow programmatic usage of SBOM builder

[skhokhlov]

Is your feature request related to a problem? Please describe.

I would like to use this tool for SBOM generation of our npm projects for further processing. Calling it via CLI is not the most convent option of doing this. Right now importing of BomBuilder, TreeBuilder, etc. is explicitly prohibited https://github.com/CycloneDX/cyclonedx-node-npm/blob/main/package.json#L87

Describe the solution you'd like

It would be great to have a public API for SBOM building

[jkowalleck]

as the readme says: https://github.com/CycloneDX/cyclonedx-node-npm#internals

This tool does not expose any additional public API or classes - all code is intended to be internal and might change without any notice during version upgrades.

Current symbols are for internal use only, they are designed to serve the purpose of this CLI tool. Nothing more.
I just do not have the capacity to architect and maintain a well-thought, universal, stable API for the job of SBOM building from npm sources.

The only thing this tool provides is a well-thought, stable CLI.
Only its SBOM result is directly sent to stdout (everything else on stderror), so you can grab it easily for further programmatic use.
Do you see an issue there? DO you need an example how to do that?

[jkowalleck]

untested example on how to call the CLI programmatically from a nodejs script:

const { execFileSync } = require('child_process');
const sbom = JSON.parse(execFileSync(process.execPath, [
    '.../path/to/this/package/bin/cyclonedx-npm-cli.js',
    '--output-format', 'JSON', 
    '--output-file', '-',
    // additional CLI args
  ], { encoding: 'utf8' }));

[jkowalleck]

tested above example and found it misbehaving for large results with small streams.
here is a fix: #1145

and there is also an updated version of the HOW TO:

cyclonedx-node-npm/src/index.ts

Lines 23 to 30 in 6e99181

	const { execFileSync } = require('child_process')
	const BUFFER_MAX_LENGTH = require('buffer').constants.MAX_LENGTH
	const sbom = JSON.parse(execFileSync(process.execPath, [
	'../path/to/this/module/bin/cyclonedx-npm-cli.js',
	'--output-format', 'JSON',
	'--output-file', '-'
	// additional CLI args
	], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'buffer', maxBuffer: BUFFER_MAX_LENGTH }))