diff --git a/HISTORY.md b/HISTORY.md index 24f8d1d9d..5ef2c26aa 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -6,6 +6,27 @@ All notable changes to this project will be documented in this file. +* Added + * New entry points for `/Contrib` and known submodules (via [#1343]) + See `package.json::exports` for details. +* Changes + * Moved non‑standard implementations to Contrib area ([#1344] via [#1343]) +* Deprecated + * Certain exports have been deprecated; downstream imports should be updated to the new locations ([#1344] via [#1343]) + Note: the symbols themselves remain supported. See documentation and the "Refactored" section below for details. +* Refactor + * The following symbols were moved. ([#1344] via [#1343]) + The symbols are still import-able through their old location. + * **OLD** -> **NEW** + * `Builders.FromNodePackageJson` -> `Contrib.FromNodePackageJson.Builders` + * `Factories.FromNodePackageJson` -> `Contrib.FromNodePackageJson.Factories` + * `Factories.LicenseFactory` -> `Contrib.License.Factories.LicenseFactory` + * `Factories.PackageUrlFactory` -> `Contrib.PackageUrl.Factories.PackageUrlFactory` + * `Types.assertNodePackageJson` -> `Contrib.FromNodePackageJson.Types.assertNodePackageJson` + * `Types.isNodePackageJson` -> `Contrib.FromNodePackageJson.Types.isNodePackageJson` + * `Types.NodePackageJson` -> `Contrib.FromNodePackageJson.Types.NodePackageJson` + * `Utils.LicenseUtility` -> `Contrib.License.Utils` + * `Utils.NpmjsUtility` -> `Contrib.FromNodePackageJson.Utils` * Style * Applied latest code style (via [#1341]) * Build @@ -13,6 +34,8 @@ All notable changes to this project will be documented in this file. [#1340]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/1340 [#1341]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/1341 +[#1343]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/1343 +[#1344]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/1344 ## 9.2.0 -- 2025-10-22 diff --git a/examples/node/javascript/example.cjs b/examples/node/javascript/example.cjs index e4838ecb5..d8751e559 100644 --- a/examples/node/javascript/example.cjs +++ b/examples/node/javascript/example.cjs @@ -22,8 +22,8 @@ Copyright (c) OWASP Foundation. All Rights Reserved. const CDX = require('@cyclonedx/cyclonedx-library') // full Library is available as `CDX`, now -const lFac = new CDX.Factories.LicenseFactory() -const purlFac = new CDX.Factories.PackageUrlFactory('generic') +const lFac = new CDX.Contrib.License.Factories.LicenseFactory() +const purlFac = new CDX.Contrib.PackageUrl.Factories.PackageUrlFactory('generic') const bom = new CDX.Models.Bom() bom.metadata.component = new CDX.Models.Component( diff --git a/examples/node/javascript/example.mjs b/examples/node/javascript/example.mjs index 0e634d341..16e1e6dde 100644 --- a/examples/node/javascript/example.mjs +++ b/examples/node/javascript/example.mjs @@ -22,8 +22,8 @@ Copyright (c) OWASP Foundation. All Rights Reserved. import * as CDX from '@cyclonedx/cyclonedx-library' // full Library is available as `CDX`, now -const lFac = new CDX.Factories.LicenseFactory() -const purlFac = new CDX.Factories.PackageUrlFactory('generic') +const lFac = new CDX.Contrib.License.Factories.LicenseFactory() +const purlFac = new CDX.Contrib.PackageUrl.Factories.PackageUrlFactory('generic') const bom = new CDX.Models.Bom() bom.metadata.component = new CDX.Models.Component( diff --git a/examples/node/javascript/package.json b/examples/node/javascript/package.json index 36869a5e5..28458d277 100644 --- a/examples/node/javascript/package.json +++ b/examples/node/javascript/package.json @@ -6,7 +6,7 @@ "node": ">=20.18.0" }, "dependencies": { - "@cyclonedx/cyclonedx-library": "file:../../..", + "@cyclonedx/cyclonedx-library": "../../..", "xmlbuilder2": "^3.0.2||^4.0.0" }, "optionalDependencies": { diff --git a/examples/node/typescript/example.cjs/src/example.ts b/examples/node/typescript/example.cjs/src/example.ts index 2485be992..79816ad14 100644 --- a/examples/node/typescript/example.cjs/src/example.ts +++ b/examples/node/typescript/example.cjs/src/example.ts @@ -22,8 +22,8 @@ Copyright (c) OWASP Foundation. All Rights Reserved. import * as CDX from '@cyclonedx/cyclonedx-library' // full Library is available as `CDX`, now -const lFac = new CDX.Factories.LicenseFactory() -const purlFac = new CDX.Factories.PackageUrlFactory('generic') +const lFac = new CDX.Contrib.License.Factories.LicenseFactory() +const purlFac = new CDX.Contrib.PackageUrl.Factories.PackageUrlFactory('generic') const bom = new CDX.Models.Bom() bom.metadata.component = new CDX.Models.Component( diff --git a/examples/node/typescript/example.mjs/src/example.ts b/examples/node/typescript/example.mjs/src/example.ts index 72b1f5c6d..ea0f3373d 100644 --- a/examples/node/typescript/example.mjs/src/example.ts +++ b/examples/node/typescript/example.mjs/src/example.ts @@ -22,8 +22,8 @@ Copyright (c) OWASP Foundation. All Rights Reserved. import * as CDX from '@cyclonedx/cyclonedx-library' // full Library is available as `CDX`, now -const lFac = new CDX.Factories.LicenseFactory() -const purlFac = new CDX.Factories.PackageUrlFactory('generic') +const lFac = new CDX.Contrib.License.Factories.LicenseFactory() +const purlFac = new CDX.Contrib.PackageUrl.Factories.PackageUrlFactory('generic') const bom = new CDX.Models.Bom() bom.metadata.component = new CDX.Models.Component( diff --git a/examples/web/parcel/src/app.js b/examples/web/parcel/src/app.js index 24c36bca1..0a024b70a 100644 --- a/examples/web/parcel/src/app.js +++ b/examples/web/parcel/src/app.js @@ -22,8 +22,8 @@ Copyright (c) OWASP Foundation. All Rights Reserved. const CDX = require('@cyclonedx/cyclonedx-library') // full Library is available as `CDX`, now -const lFac = new CDX.Factories.LicenseFactory() -const purlFac = new CDX.Factories.PackageUrlFactory('generic') +const lFac = new CDX.Contrib.License.Factories.LicenseFactory() +const purlFac = new CDX.Contrib.PackageUrl.Factories.PackageUrlFactory('generic') const bom = new CDX.Models.Bom() bom.metadata.component = new CDX.Models.Component( diff --git a/examples/web/webpack/src/index.js b/examples/web/webpack/src/index.js index 24c36bca1..0a024b70a 100644 --- a/examples/web/webpack/src/index.js +++ b/examples/web/webpack/src/index.js @@ -22,8 +22,8 @@ Copyright (c) OWASP Foundation. All Rights Reserved. const CDX = require('@cyclonedx/cyclonedx-library') // full Library is available as `CDX`, now -const lFac = new CDX.Factories.LicenseFactory() -const purlFac = new CDX.Factories.PackageUrlFactory('generic') +const lFac = new CDX.Contrib.License.Factories.LicenseFactory() +const purlFac = new CDX.Contrib.PackageUrl.Factories.PackageUrlFactory('generic') const bom = new CDX.Models.Bom() bom.metadata.component = new CDX.Models.Component( diff --git a/package.json b/package.json index 9683c942e..71d9102b1 100644 --- a/package.json +++ b/package.json @@ -182,6 +182,22 @@ "./Validation": { "types": "./dist.d/validation/index.node.d.ts", "default": "./dist.node/validation/index.node.js" + }, + "./Contrib": { + "types": "./dist.d/contrib/index.node.d.ts", + "default": "./dist.node/contrib/index.node.js" + }, + "./Contrib/FromNodePackageJson": { + "types": "./dist.d/contrib/fromNodePackageJson/index.node.d.ts", + "default": "./dist.node/contrib/fromNodePackageJson/index.node.js" + }, + "./Contrib/License": { + "types": "./dist.d/contrib/license/index.node.d.ts", + "default": "./dist.node/contrib/license/index.node.js" + }, + "./Contrib/PackageUrl": { + "types": "./dist.d/contrib/packageUrl/index.d.ts", + "default": "./dist.node/contrib/packageUrl/index.js" } }, "directories": { diff --git a/src/builders/index.node.ts b/src/builders/index.node.ts index 12bdce998..7ce7055ea 100644 --- a/src/builders/index.node.ts +++ b/src/builders/index.node.ts @@ -17,4 +17,18 @@ SPDX-License-Identifier: Apache-2.0 Copyright (c) OWASP Foundation. All Rights Reserved. */ -export * as FromNodePackageJson from './fromNodePackageJson.node' +import * as _FromNodePackageJson from '../contrib/fromNodePackageJson/builders' + + +// region deprecated re-exports + +/** + * Deprecated — Alias of {@link Contrib.FromNodePackageJson.Builders}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.FromNodePackageJson.Builders` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export const FromNodePackageJson = _FromNodePackageJson + +// endregion deprecated re-exports diff --git a/src/contrib/README.md b/src/contrib/README.md new file mode 100644 index 000000000..aff5230ef --- /dev/null +++ b/src/contrib/README.md @@ -0,0 +1,20 @@ +# CycloneDX Contrib Extensions + +This directory contains community-contributed functionality that extends the capabilities of the CycloneDX core library. +Unlike the modules in `../`, these features are not part of the official CycloneDX specification and may vary in stability, scope, or compatibility. + +## Contents +- Utilities, helpers, and experimental features developed by the community +- Optional add-ons that may facilitate or enhance use of the CycloneDX core library +- Code that evolves independently of the CycloneDX specification + +## Notes +- Contrib modules are optional and not required for strict compliance with the CycloneDX standard. +- They may change more frequently than the core and are not guaranteed to follow the same versioning rules. +- Users should evaluate these modules carefully and consult documentation or source comments for details. + +## Contributing +Contributions are welcome. To add an extension: +1. Follow the contribution guidelines in the main repository. +2. Place your code in a clearly named subfolder or file under `contrib/`. +3. Provide documentation and tests to ensure clarity and maintainability. diff --git a/src/utils/bomUtility.ts b/src/contrib/bom/utils.ts similarity index 100% rename from src/utils/bomUtility.ts rename to src/contrib/bom/utils.ts diff --git a/src/contrib/fromNodePackageJson/_helpers/README.md b/src/contrib/fromNodePackageJson/_helpers/README.md new file mode 100644 index 000000000..32444f4d7 --- /dev/null +++ b/src/contrib/fromNodePackageJson/_helpers/README.md @@ -0,0 +1,6 @@ +# Helpers + +These are _internal_ helpers, that are not intended to be exported/published. + +The helpers SHALL **NOT** be marked as `@internal`, so that TypeScript might pick up on them and still render definitions for them. +The internal defined interfaces, classes, functions are required for proper type checking downstream, but SHOULD NOT be utilized/called downstream. diff --git a/src/_helpers/gitUrl.ts b/src/contrib/fromNodePackageJson/_helpers/gitUrl.ts similarity index 100% rename from src/_helpers/gitUrl.ts rename to src/contrib/fromNodePackageJson/_helpers/gitUrl.ts diff --git a/src/_helpers/packageJson.ts b/src/contrib/fromNodePackageJson/_helpers/packageJson.ts similarity index 100% rename from src/_helpers/packageJson.ts rename to src/contrib/fromNodePackageJson/_helpers/packageJson.ts diff --git a/src/builders/fromNodePackageJson.node.ts b/src/contrib/fromNodePackageJson/builders.ts similarity index 81% rename from src/builders/fromNodePackageJson.node.ts rename to src/contrib/fromNodePackageJson/builders.ts index db0a88d80..938b831d6 100644 --- a/src/builders/fromNodePackageJson.node.ts +++ b/src/contrib/fromNodePackageJson/builders.ts @@ -26,26 +26,27 @@ Copyright (c) OWASP Foundation. All Rights Reserved. * Normalization should be done downstream, for example via [`normalize-package-data`](https://www.npmjs.com/package/normalize-package-data). */ -import { splitNameGroup } from '../_helpers/packageJson' -import { ComponentType } from '../enums/componentType' -import type * as Factories from '../factories/index.node' -import { Component } from '../models/component' -import { ExternalReferenceRepository } from '../models/externalReference' -import { LicenseRepository } from '../models/license' -import { Tool } from '../models/tool' -import type { NodePackageJson } from '../types/nodePackageJson' +import { ComponentType } from '../../enums/componentType' +import { Component } from '../../models/component' +import { ExternalReferenceRepository } from '../../models/externalReference' +import { LicenseRepository } from '../../models/license' +import { Tool } from '../../models/tool' +import type { LicenseFactory } from '../license/factories' +import { splitNameGroup } from './_helpers/packageJson' +import type { ExternalReferenceFactory } from './factories' +import type { NodePackageJson } from './types' /** * Node-specific ToolBuilder. */ export class ToolBuilder { - readonly #extRefFactory: Factories.FromNodePackageJson.ExternalReferenceFactory + readonly #extRefFactory: ExternalReferenceFactory constructor (extRefFactory: ToolBuilder['extRefFactory']) { this.#extRefFactory = extRefFactory } - get extRefFactory (): Factories.FromNodePackageJson.ExternalReferenceFactory { + get extRefFactory (): ExternalReferenceFactory { return this.#extRefFactory } @@ -71,8 +72,8 @@ export class ToolBuilder { * Node-specific ComponentBuilder. */ export class ComponentBuilder { - readonly #extRefFactory: Factories.FromNodePackageJson.ExternalReferenceFactory - readonly #licenseFactory: Factories.LicenseFactory + readonly #extRefFactory: ExternalReferenceFactory + readonly #licenseFactory: LicenseFactory constructor ( extRefFactory: ComponentBuilder['extRefFactory'], @@ -82,11 +83,11 @@ export class ComponentBuilder { this.#licenseFactory = licenseFactory } - get extRefFactory (): Factories.FromNodePackageJson.ExternalReferenceFactory { + get extRefFactory (): ExternalReferenceFactory { return this.#extRefFactory } - get licenseFactory (): Factories.LicenseFactory { + get licenseFactory (): LicenseFactory { return this.#licenseFactory } @@ -104,8 +105,8 @@ export class ComponentBuilder { const author = typeof data.author === 'string' ? data.author : (typeof data.author?.name === 'string' - ? data.author.name - : undefined) + ? data.author.name + : undefined) /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#description-1 */ const description = typeof data.description === 'string' diff --git a/src/factories/fromNodePackageJson.node.ts b/src/contrib/fromNodePackageJson/factories.ts similarity index 92% rename from src/factories/fromNodePackageJson.node.ts rename to src/contrib/fromNodePackageJson/factories.ts index 580a2722d..d47b62c48 100644 --- a/src/factories/fromNodePackageJson.node.ts +++ b/src/contrib/fromNodePackageJson/factories.ts @@ -29,16 +29,16 @@ Copyright (c) OWASP Foundation. All Rights Reserved. import type { PackageURL } from 'packageurl-js' import { PurlQualifierNames } from 'packageurl-js' -import { tryCanonicalizeGitUrl } from "../_helpers/gitUrl" -import { isNotUndefined } from '../_helpers/notUndefined' -import { ExternalReferenceType } from '../enums/externalReferenceType' -import { HashAlgorithm } from "../enums/hashAlogorithm"; -import type { Component } from '../models/component' -import { ExternalReference } from '../models/externalReference' -import { HashDictionary } from '../models/hash' -import type { NodePackageJson } from '../types/nodePackageJson' -import { defaultRegistryMatcher, parsePackageIntegrity } from '../utils/npmjsUtility.node' -import { PackageUrlFactory as PlainPackageUrlFactory } from './packageUrl' +import { isNotUndefined } from '../../_helpers/notUndefined' +import { ExternalReferenceType } from '../../enums/externalReferenceType' +import { HashAlgorithm } from '../../enums/hashAlogorithm' +import type { Component } from '../../models/component' +import { ExternalReference } from '../../models/externalReference' +import { HashDictionary } from '../../models/hash' +import { PackageUrlFactory as PlainPackageUrlFactory } from '../packageUrl/factories' +import { tryCanonicalizeGitUrl } from './_helpers/gitUrl' +import type { NodePackageJson } from './types' +import { defaultRegistryMatcher, parsePackageIntegrity } from './utils' /** * Node-specific ExternalReferenceFactory. @@ -122,7 +122,7 @@ export class ExternalReferenceFactory { } catch { /* pass */ } } if (typeof shasum === 'string' && shasum.length === 40) { - hashes.set(HashAlgorithm["SHA-1"], shasum) + hashes.set(HashAlgorithm['SHA-1'], shasum) comment += ' and property "dist.shasum"' } return new ExternalReference(tarball, ExternalReferenceType.Distribution, { hashes, comment }) diff --git a/src/contrib/fromNodePackageJson/index.node.ts b/src/contrib/fromNodePackageJson/index.node.ts new file mode 100644 index 000000000..a31e7f04d --- /dev/null +++ b/src/contrib/fromNodePackageJson/index.node.ts @@ -0,0 +1,34 @@ +/*! +This file is part of CycloneDX JavaScript Library. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +Copyright (c) OWASP Foundation. All Rights Reserved. +*/ + +/** + * Node-specifics. + * + * Intended to run on normalized data structures + * based on [PackageJson spec](https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/package.json) + * and explained by [PackageJson description](https://docs.npmjs.com/cli/v9/configuring-npm/package-json). + * Normalization should be done downstream, for example via [`normalize-package-data`](https://www.npmjs.com/package/normalize-package-data). + */ + +export * as Builders from './builders' +export * as Factories from './factories' +export * as Types from './types' +export * as Utils from './utils' + +// do not export the _helpers, they are for internal use only diff --git a/src/types/nodePackageJson.ts b/src/contrib/fromNodePackageJson/types.ts similarity index 100% rename from src/types/nodePackageJson.ts rename to src/contrib/fromNodePackageJson/types.ts diff --git a/src/utils/npmjsUtility.node.ts b/src/contrib/fromNodePackageJson/utils.ts similarity index 98% rename from src/utils/npmjsUtility.node.ts rename to src/contrib/fromNodePackageJson/utils.ts index 14208cf0b..48834e3af 100644 --- a/src/utils/npmjsUtility.node.ts +++ b/src/contrib/fromNodePackageJson/utils.ts @@ -17,7 +17,7 @@ SPDX-License-Identifier: Apache-2.0 Copyright (c) OWASP Foundation. All Rights Reserved. */ -import {HashAlgorithm} from '../enums/hashAlogorithm' +import {HashAlgorithm} from '../../enums/hashAlogorithm' /** * See {@link https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json#packages | package lock docs} for "integrity". diff --git a/src/contrib/index.common.ts b/src/contrib/index.common.ts new file mode 100644 index 000000000..d5cd24c32 --- /dev/null +++ b/src/contrib/index.common.ts @@ -0,0 +1,24 @@ +/*! +This file is part of CycloneDX JavaScript Library. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +Copyright (c) OWASP Foundation. All Rights Reserved. +*/ + +/** + * Some features in this library are marked as contrib. These are community-provided extensions and are not part of the official standard. They are optional and may evolve independently from the core. + */ + +export * as PackageUrl from './packageUrl' diff --git a/src/contrib/index.node.ts b/src/contrib/index.node.ts new file mode 100644 index 000000000..cf2d278c7 --- /dev/null +++ b/src/contrib/index.node.ts @@ -0,0 +1,31 @@ +/*! +This file is part of CycloneDX JavaScript Library. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +Copyright (c) OWASP Foundation. All Rights Reserved. +*/ + +/** + * Some features in this library are marked as contrib. These are community-provided extensions and are not part of the official standard. They are optional and may evolve independently from the core. + */ + +export * from './index.common' + +// region node-specifics + +export * as FromNodePackageJson from './fromNodePackageJson/index.node' +export * as License from './license/index.node' + +// endregion node-specifics diff --git a/src/contrib/index.web.ts b/src/contrib/index.web.ts new file mode 100644 index 000000000..b73ddbfee --- /dev/null +++ b/src/contrib/index.web.ts @@ -0,0 +1,30 @@ +/*! +This file is part of CycloneDX JavaScript Library. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +Copyright (c) OWASP Foundation. All Rights Reserved. +*/ + +/** + * Some features in this library are marked as contrib. These are community-provided extensions and are not part of the official standard. They are optional and may evolve independently from the core. + */ + +export * from './index.common' + +// region web-specifics + +export * as License from './license/index.web' + +// endregion web-specifics diff --git a/src/contrib/license/_helpers/README.md b/src/contrib/license/_helpers/README.md new file mode 100644 index 000000000..32444f4d7 --- /dev/null +++ b/src/contrib/license/_helpers/README.md @@ -0,0 +1,6 @@ +# Helpers + +These are _internal_ helpers, that are not intended to be exported/published. + +The helpers SHALL **NOT** be marked as `@internal`, so that TypeScript might pick up on them and still render definitions for them. +The internal defined interfaces, classes, functions are required for proper type checking downstream, but SHOULD NOT be utilized/called downstream. diff --git a/src/_helpers/mime.node.ts b/src/contrib/license/_helpers/mime.node.ts similarity index 100% rename from src/_helpers/mime.node.ts rename to src/contrib/license/_helpers/mime.node.ts diff --git a/src/factories/license.ts b/src/contrib/license/factories.ts similarity index 92% rename from src/factories/license.ts rename to src/contrib/license/factories.ts index 7bf773914..c218f5bf8 100644 --- a/src/factories/license.ts +++ b/src/contrib/license/factories.ts @@ -17,9 +17,9 @@ SPDX-License-Identifier: Apache-2.0 Copyright (c) OWASP Foundation. All Rights Reserved. */ -import type { DisjunctiveLicense, License } from '../models/license' -import { LicenseExpression, NamedLicense, SpdxLicense } from '../models/license' -import { fixupSpdxId, isValidSpdxLicenseExpression } from '../spdx' +import type { DisjunctiveLicense, License } from '../../models/license' +import { LicenseExpression, NamedLicense, SpdxLicense } from '../../models/license' +import { fixupSpdxId, isValidSpdxLicenseExpression } from '../../spdx' export class LicenseFactory { makeFromString (value: string): License { diff --git a/src/contrib/license/index.common.ts b/src/contrib/license/index.common.ts new file mode 100644 index 000000000..1ad0f01ad --- /dev/null +++ b/src/contrib/license/index.common.ts @@ -0,0 +1,22 @@ +/*! +This file is part of CycloneDX JavaScript Library. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +Copyright (c) OWASP Foundation. All Rights Reserved. +*/ + +export * as Factories from './factories' + +// do not export the _helpers, they are for internal use only diff --git a/src/contrib/license/index.node.ts b/src/contrib/license/index.node.ts new file mode 100644 index 000000000..49334588a --- /dev/null +++ b/src/contrib/license/index.node.ts @@ -0,0 +1,28 @@ +/*! +This file is part of CycloneDX JavaScript Library. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +Copyright (c) OWASP Foundation. All Rights Reserved. +*/ + +export * from './index.common' + +// region node-specifics + +export * as Utils from './utils.node' + +// endregion node-specifics + +// do not export the _helpers, they are for internal use only diff --git a/src/contrib/license/index.web.ts b/src/contrib/license/index.web.ts new file mode 100644 index 000000000..c9f1f7de5 --- /dev/null +++ b/src/contrib/license/index.web.ts @@ -0,0 +1,28 @@ +/*! +This file is part of CycloneDX JavaScript Library. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +Copyright (c) OWASP Foundation. All Rights Reserved. +*/ + +export * from './index.common' + +// region web-specifics + +// nothing. yet ... + +// endregion web-specifics + +// do not export the _helpers, they are for internal use only diff --git a/src/utils/licenseUtility.node.ts b/src/contrib/license/utils.node.ts similarity index 95% rename from src/utils/licenseUtility.node.ts rename to src/contrib/license/utils.node.ts index e6b66462e..0e7b4b48a 100644 --- a/src/utils/licenseUtility.node.ts +++ b/src/contrib/license/utils.node.ts @@ -26,9 +26,9 @@ Copyright (c) OWASP Foundation. All Rights Reserved. import type { Stats } from 'node:fs' -import { guessMimeTypeForLicenseFile } from '../_helpers/mime.node' -import { AttachmentEncoding } from '../enums/attachmentEncoding' -import { Attachment } from '../models/attachment' +import { AttachmentEncoding } from '../../enums/attachmentEncoding' +import { Attachment } from '../../models/attachment' +import { guessMimeTypeForLicenseFile } from './_helpers/mime.node' export interface FsUtils

{ readdirSync: (path: P ) => P[] diff --git a/src/factories/packageUrl.ts b/src/contrib/packageUrl/factories.ts similarity index 95% rename from src/factories/packageUrl.ts rename to src/contrib/packageUrl/factories.ts index 069e01f72..8db56d2ff 100644 --- a/src/factories/packageUrl.ts +++ b/src/contrib/packageUrl/factories.ts @@ -19,8 +19,8 @@ Copyright (c) OWASP Foundation. All Rights Reserved. import { PackageURL, PurlQualifierNames } from 'packageurl-js' -import { ExternalReferenceType } from '../enums/externalReferenceType' -import type { Component } from '../models/component' +import { ExternalReferenceType } from '../../enums/externalReferenceType' +import type { Component } from '../../models/component' export class PackageUrlFactory { readonly #type: PurlType diff --git a/src/contrib/packageUrl/index.ts b/src/contrib/packageUrl/index.ts new file mode 100644 index 000000000..e898d6e94 --- /dev/null +++ b/src/contrib/packageUrl/index.ts @@ -0,0 +1,20 @@ +/*! +This file is part of CycloneDX JavaScript Library. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +SPDX-License-Identifier: Apache-2.0 +Copyright (c) OWASP Foundation. All Rights Reserved. +*/ + +export * as Factories from './factories' diff --git a/src/factories/index.common.ts b/src/factories/index.common.ts index dab3e01e5..5569bc76a 100644 --- a/src/factories/index.common.ts +++ b/src/factories/index.common.ts @@ -17,7 +17,28 @@ SPDX-License-Identifier: Apache-2.0 Copyright (c) OWASP Foundation. All Rights Reserved. */ -// not everything is public, yet +import {LicenseFactory as _LicenseFactory} from '../contrib/license/factories' +import {PackageUrlFactory as _PackageUrlFactory} from '../contrib/packageUrl/factories' -export * from './license' -export * from './packageUrl' + +// region deprecated re-exports + +/** + * Deprecated — Alias of {@link Contrib.License.Factories.LicenseFactory}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.License.Factories.LicenseFactory` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export const LicenseFactory = _LicenseFactory + +/** + * Deprecated — Alias of {@link Contrib.PackageUrl.Factories.PackageUrlFactory}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.PackageUrl.Factories.PackageUrlFactory` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export const PackageUrlFactory = _PackageUrlFactory + +// endregion deprecated re-exports diff --git a/src/factories/index.node.ts b/src/factories/index.node.ts index 872de4f2f..99f79a102 100644 --- a/src/factories/index.node.ts +++ b/src/factories/index.node.ts @@ -17,10 +17,23 @@ SPDX-License-Identifier: Apache-2.0 Copyright (c) OWASP Foundation. All Rights Reserved. */ +import * as _FromNodePackageJson from '../contrib/fromNodePackageJson/factories' + export * from './index.common' // region node-specifics -export * as FromNodePackageJson from './fromNodePackageJson.node' +// region deprecated re-exports + +/** + * Deprecated — Alias of {@link Contrib.FromNodePackageJson.Factories}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.FromNodePackageJson.Factories` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export const FromNodePackageJson = _FromNodePackageJson + +// endregion deprecated re-exports // endregion node-specifics diff --git a/src/index.common.ts b/src/index.common.ts index 3c9dc9913..4fc31c771 100644 --- a/src/index.common.ts +++ b/src/index.common.ts @@ -22,4 +22,5 @@ export * as Models from './models' export * as SPDX from './spdx' export * as Spec from './spec' export * as Types from './types' + // do not export the _helpers, they are for internal use only diff --git a/src/index.node.ts b/src/index.node.ts index cace8af4e..d3343da92 100644 --- a/src/index.node.ts +++ b/src/index.node.ts @@ -25,9 +25,13 @@ export * from './index.common' // region node-specifics +/** @deprecated next */ export * as Builders from './builders/index.node' +export * as Contrib from './contrib/index.node' +/** @deprecated next */ export * as Factories from './factories/index.node' export * as Serialize from './serialize/index.node' +/** @deprecated next */ export * as Utils from './utils/index.node' export * as Validation from './validation/index.node' @@ -39,3 +43,6 @@ export * as Validation from './validation/index.node' export * as _Resources from './resources.node' // endregion node-specifics + +// do not export the _helpers, they are for internal use only + diff --git a/src/index.web.ts b/src/index.web.ts index f4efdf3d6..a64a69fa7 100644 --- a/src/index.web.ts +++ b/src/index.web.ts @@ -21,9 +21,15 @@ export * from './index.common' // region web-specifics +export * as Contrib from './contrib/index.web' +/** @deprecated next */ export * as Factories from './factories/index.web' export * as Serialize from './serialize/index.web' +/** @deprecated next */ export * as Utils from './utils/index.web' export * as Validation from './validation/index.web' // endregion web-specifics + +// do not export the _helpers, they are for internal use only + diff --git a/src/types/index.ts b/src/types/index.ts index 2f2e2f09f..5a9c94979 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -17,10 +17,45 @@ SPDX-License-Identifier: Apache-2.0 Copyright (c) OWASP Foundation. All Rights Reserved. */ +import { + assertNodePackageJson as _assertNodePackageJson, + isNodePackageJson as _isNodePackageJson, + type NodePackageJson as _NodePackageJson +} from '../contrib/fromNodePackageJson/types' + + export * from './cpe' export * from './cwe' export * from './integer' export * from './mimeType' -// yes, this is node-specific, but who cares - these are just types -export * from './nodePackageJson' +// region deprecated re-exports + +/** + * Deprecated — Alias of {@link Contrib.FromNodePackageJson.Types.NodePackageJson}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.FromNodePackageJson.Types.NodePackageJson` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export type NodePackageJson = _NodePackageJson + +/** + * Deprecated — Alias of {@link Contrib.FromNodePackageJson.Types.assertNodePackageJson}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.FromNodePackageJson.Types.assertNodePackageJson` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export const assertNodePackageJson = _assertNodePackageJson + +/** + * Deprecated — Alias of {@link Contrib.FromNodePackageJson.Types.isNodePackageJson}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.FromNodePackageJson.Types.isNodePackageJson` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export const isNodePackageJson = _isNodePackageJson + +// endregion deprecated re-exports diff --git a/src/utils/index.common.ts b/src/utils/index.common.ts index 813a9470a..bdefa3d43 100644 --- a/src/utils/index.common.ts +++ b/src/utils/index.common.ts @@ -17,4 +17,18 @@ SPDX-License-Identifier: Apache-2.0 Copyright (c) OWASP Foundation. All Rights Reserved. */ -export * as BomUtility from './bomUtility' +// region deprecated re-exports + +import * as _BomUtils from "../contrib/bom/utils"; + +/** + * Deprecated — Alias of {@link Contrib.Bom.Utils}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.Bom.Utils` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export const BomUtility = _BomUtils + +// endregion deprecated re-exports + diff --git a/src/utils/index.node.ts b/src/utils/index.node.ts index de45da246..fbd9dbd99 100644 --- a/src/utils/index.node.ts +++ b/src/utils/index.node.ts @@ -17,11 +17,34 @@ SPDX-License-Identifier: Apache-2.0 Copyright (c) OWASP Foundation. All Rights Reserved. */ +import * as _NpmjsUtility from '../contrib/fromNodePackageJson/utils' +import * as _LicenseUtility from '../contrib/license/utils.node' + + export * from './index.common' // region node-specifics -export * as LicenseUtility from './licenseUtility.node' -export * as NpmjsUtility from './npmjsUtility.node' +// region deprecated re-exports + +/** + * Deprecated — Alias of {@link Contrib.FromNodePackageJson.Utils}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.FromNodePackageJson.Utils` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export const NpmjsUtility = _NpmjsUtility + +/** + * Deprecated — Alias of {@link Contrib.License.Utils}. + * + * @deprecated This re-export location is deprecated. + * Import `Contrib.License.Utils` instead. + * The exported symbol itself is NOT deprecated - only this import path. + */ +export const LicenseUtility = _LicenseUtility + +// endregion deprecated re-exports // endregion node-specifics diff --git a/tests/unit/internals/helpers.mime.node.spec.js b/tests/contrib/license/unit/internals/helpers.mime.node.spec.js similarity index 94% rename from tests/unit/internals/helpers.mime.node.spec.js rename to tests/contrib/license/unit/internals/helpers.mime.node.spec.js index a4e31426d..f4d6f6923 100644 --- a/tests/unit/internals/helpers.mime.node.spec.js +++ b/tests/contrib/license/unit/internals/helpers.mime.node.spec.js @@ -23,7 +23,7 @@ const { suite, test } = require('mocha') const { guessMimeTypeForLicenseFile -} = require('../../../dist.node/_helpers/mime.node.js') +} = require('../../../../../dist.node/contrib/license/_helpers/mime.node') suite('unit: internals: helpers.mime.getMimeForLicenseFile', () => { for (const [fileName, expected] of [