feat: Moved non‑standard implementations to Contrib area

HISTORY.md

@@ -6,6 +6,31 @@ All notable changes to this project will be documented in this file.
 
 <!-- add unreleased items here -->
 
+* Added
+  * New entry point for `/Contrib` and known submodules (via [#1343])  
+    See `package.json::exports` for details.
+* Changed
+  * 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.
+* Refactored
+  * 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`
+
+[#1344]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/1344
+[#1343]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/1343
+
 ## 9.2.0 -- 2025-10-22
 
 * Added

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": {

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

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.  

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.

src/builders/fromNodePackageJson.node.ts → 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'

src/factories/fromNodePackageJson.node.ts → 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 })

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

src/utils/npmjsUtility.node.ts → 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".

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'

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

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

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.

src/factories/license.ts → 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 {

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