docs: note to packageJson-like structure normalization (#518)

Made it clear, that `{Builders,Factories}.{FromNodePackageJson,FromPackageJson}.*` functionality is to be run on already normalized structures.  
Normalization should be done downstream, for example via [`normalize-package-data`](https://www.npmjs.com/package/normalize-package-data).


Signed-off-by: Jan Kowalleck <[email protected]>

Author: jkowalleck

HISTORY.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 ## unreleased
 
+## 1.12.0 -  2023-03-02
+
+* Docs
+  * Made it clear, that `{Builders,Factories}.{FromNodePackageJson,FromPackageJson}.*` functionality is to be run on already normalized structures. ([#517] via [#518])  
+    Normalization should be done downstream, for example via [`normalize-package-data`](https://www.npmjs.com/package/normalize-package-data).
+
+[#517]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/517
+[#518]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/518
+
 ## 1.11.0 - 2023-02-02
 
 * Added

src/_helpers/packageJson.ts

@@ -28,8 +28,9 @@ export function splitNameGroup (data: string): [string, string?] {
 }
 
 /**
- * @see {@link https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/package.json | PackageJson spec}
- * @see {@link https://docs.npmjs.com/cli/v8/configuring-npm/package-json | PackageJson description}
+ * Intended to represent [normalized](https://www.npmjs.com/package/normalize-package-data) data structures
+ * based on [PackageJson spec](https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/package.json)
+ * and [PackageJson description](https://docs.npmjs.com/cli/v9/configuring-npm/package-json).
  */
 export interface PackageJson {
   name?: string

src/builders/fromNodePackageJson.node.ts

@@ -20,7 +20,10 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 /**
  * Node-specifics.
  *
- * @see [PackageJson spec](https://docs.npmjs.com/cli/v8/configuring-npm/package-json)
+ * Intended to run on [normalized](https://www.npmjs.com/package/normalize-package-data) data structures
+ * based on [PackageJson spec](https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/package.json)
+ * and [PackageJson description](https://docs.npmjs.com/cli/v9/configuring-npm/package-json).
+ * Normalization should be done downstream.
  */
 
 import type { PackageJson } from '../_helpers/packageJson'
@@ -94,19 +97,19 @@ export class ComponentBuilder {
       return undefined
     }
 
-    /* see https://docs.npmjs.com/cli/v8/configuring-npm/package-json#author */
+    /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#author */
     const author = typeof data.author === 'string'
       ? data.author
       : (typeof data.author?.name === 'string'
           ? data.author.name
           : undefined)
 
-    /* see https://docs.npmjs.com/cli/v8/configuring-npm/package-json#description-1 */
+    /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#description-1 */
     const description = typeof data.description === 'string'
       ? data.description
       : undefined
 
-    /* see https://docs.npmjs.com/cli/v8/configuring-npm/package-json#version */
+    /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#version */
     const version = typeof data.version === 'string'
       ? data.version
       : undefined
@@ -115,7 +118,7 @@ export class ComponentBuilder {
 
     const licenses = new Models.LicenseRepository()
     if (typeof data.license === 'string') {
-      /* see https://docs.npmjs.com/cli/v8/configuring-npm/package-json#license */
+      /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#license */
       licenses.add(this.#licenseFactory.makeFromString(data.license))
     }
     if (Array.isArray(data.licenses)) {

src/factories/fromNodePackageJson.node.ts

@@ -20,7 +20,10 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 /**
  * Node-specifics.
  *
- * @see [PackageJson spec](https://docs.npmjs.com/cli/v8/configuring-npm/package-json)
+ * Intended to run on [normalized](https://www.npmjs.com/package/normalize-package-data) data structures
+ * based on [PackageJson spec](https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/package.json)
+ * and [PackageJson description](https://docs.npmjs.com/cli/v9/configuring-npm/package-json).
+ * Normalization should be done downstream.
  */
 
 import type { PackageURL } from 'packageurl-js'
@@ -47,7 +50,7 @@ export class ExternalReferenceFactory {
   }
 
   makeVcs (data: PackageJson): Models.ExternalReference | undefined {
-    /* see https://docs.npmjs.com/cli/v8/configuring-npm/package-json#repositoryc */
+    /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#repositoryc */
     const repository = data.repository
     let url
     let comment: string | undefined
@@ -69,7 +72,7 @@ export class ExternalReferenceFactory {
   }
 
   makeHomepage (data: PackageJson): Models.ExternalReference | undefined {
-    /* see https://docs.npmjs.com/cli/v8/configuring-npm/package-json#homepage */
+    /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#homepage */
     const url = data.homepage
     return typeof url === 'string' && url.length > 0
       ? new Models.ExternalReference(
@@ -79,7 +82,7 @@ export class ExternalReferenceFactory {
   }
 
   makeIssueTracker (data: PackageJson): Models.ExternalReference | undefined {
-    /* see https://docs.npmjs.com/cli/v8/configuring-npm/package-json#bugs */
+    /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bugs */
     const bugs = data.bugs
     let url
     let comment: string | undefined