@cyclonedx/cyclonedx-library 3.0.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyclonedx/cyclonedx-library",
-  "version": "3.0.0",
+  "version": "5.0.0",
   "description": "Core functionality of CycloneDX for JavaScript (Node.js or WebBrowser).",
   "license": "Apache-2.0",
   "keywords": [
@@ -77,25 +77,27 @@
     "xmlbuilder2": "^3.0.2"
   },
   "devDependencies": {
-    "@types/mocha": "^10.0.0",
+    "@types/mocha": "^10",
     "@types/node": "ts5.1",
-    "@types/spdx-expression-parse": "^3.0.2",
-    "c8": "^8.0.0",
+    "@types/spdx-expression-parse": "^3",
+    "c8": "^8",
     "deepmerge": "^4.2.2",
     "eslint": "^8.23.0",
-    "eslint-config-standard-with-typescript": "^35.0.0",
+    "eslint-config-standard": "^17.0.0",
+    "eslint-config-standard-with-typescript": "^37.0.0",
     "eslint-plugin-header": "^3.1.1",
     "eslint-plugin-jsdoc": "^46.2.0",
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "eslint-plugin-tsdoc": "^0.2.17",
     "mocha": "10.2.0",
     "npm-run-all": "^4.1.5",
-    "ts-loader": "9.4.3",
+    "ts-loader": "9.4.4",
     "typedoc": "^0.24.4",
     "typedoc-plugin-missing-exports": "^2.0.0",
-    "typescript": "5.1.5",
-    "webpack": "5.88.0",
-    "webpack-cli": "5.1.4"
+    "typescript": "5.1.6",
+    "webpack": "5.88.2",
+    "webpack-cli": "5.1.4",
+    "webpack-node-externals": "^3.0.0"
   },
   "browser": "./dist.web/lib.js",
   "types": "./dist.d/index.node.d.ts",

package/src/enums/index.ts

@@ -22,4 +22,5 @@ export * from './componentScope'
 export * from './componentType'
 export * from './externalReferenceType'
 export * from './hashAlogorithm'
+export * from './lifecyclePhase'
 export * as Vulnerability from './vulnerability'

package/src/enums/lifecyclePhase.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 enum LifecyclePhase {
+  Design = 'design',
+  PreBuild = 'pre-build',
+  Build = 'build',
+  PostBuild = 'post-build',
+  Operations = 'operations',
+  Discovery = 'discovery',
+  Decommission = 'decommission',
+}

package/src/models/index.ts

@@ -25,6 +25,7 @@ export * from './component'
 export * from './externalReference'
 export * from './hash'
 export * from './license'
+export * from './lifecycle'
 export * from './metadata'
 export * from './organizationalContact'
 export * from './organizationalEntity'

package/src/models/lifecycle.ts

@@ -0,0 +1,56 @@
+/*!
+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.
+*/
+
+import type { Comparable, Sortable } from '../_helpers/sortable'
+import type { LifecyclePhase } from '../enums'
+
+export interface OptionalNamedLifecycleProperties {
+  description?: NamedLifecycle['description']
+}
+
+export class NamedLifecycle implements Comparable<NamedLifecycle> {
+  name: string
+  description?: string
+
+  constructor (name: string, op: OptionalNamedLifecycleProperties = {}) {
+    this.name = name
+    this.description = op.description
+  }
+
+  compare (other: NamedLifecycle): number {
+    return this.name.localeCompare(other.name)
+  }
+}
+
+export type Lifecycle = LifecyclePhase | NamedLifecycle
+
+export class LifecycleRepository extends Set<Lifecycle> implements Sortable<Lifecycle> {
+  #compareItems (a: Lifecycle, b: Lifecycle): number {
+    if (a.constructor === b.constructor) {
+      return a instanceof NamedLifecycle
+        ? a.compare(b as NamedLifecycle)
+        : (a as string).localeCompare(b as string)
+    }
+    return a.constructor.name.localeCompare(b.constructor.name)
+  }
+
+  sorted (): Lifecycle[] {
+    return Array.from(this).sort(this.#compareItems)
+  }
+}

package/src/models/metadata.ts

@@ -18,12 +18,14 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
 import type { Component } from './component'
+import { LifecycleRepository } from './lifecycle'
 import { OrganizationalContactRepository } from './organizationalContact'
 import type { OrganizationalEntity } from './organizationalEntity'
 import { ToolRepository } from './tool'
 
 export interface OptionalMetadataProperties {
   timestamp?: Metadata['timestamp']
+  lifecycles?: Metadata['lifecycles']
   tools?: Metadata['tools']
   authors?: Metadata['authors']
   component?: Metadata['component']
@@ -33,6 +35,7 @@ export interface OptionalMetadataProperties {
 
 export class Metadata {
   timestamp?: Date
+  lifecycles: LifecycleRepository
   tools: ToolRepository
   authors: OrganizationalContactRepository
   component?: Component
@@ -41,6 +44,7 @@ export class Metadata {
 
   constructor (op: OptionalMetadataProperties = {}) {
     this.timestamp = op.timestamp
+    this.lifecycles = op.lifecycles ?? new LifecycleRepository()
     this.tools = op.tools ?? new ToolRepository()
     this.authors = op.authors ?? new OrganizationalContactRepository()
     this.component = op.component

package/src/serialize/json/normalize.ts

@@ -56,6 +56,10 @@ export class Factory {
     return new ComponentEvidenceNormalizer(this)
   }
 
+  makeForLifecycle (): LifecycleNormalizer {
+    return new LifecycleNormalizer(this)
+  }
+
   makeForTool (): ToolNormalizer {
     return new ToolNormalizer(this)
   }
@@ -201,6 +205,9 @@ export class MetadataNormalizer extends BaseJsonNormalizer<Models.Metadata> {
     const orgEntityNormalizer = this._factory.makeForOrganizationalEntity()
     return {
       timestamp: data.timestamp?.toISOString(),
+      lifecycles: this._factory.spec.supportsMetadataLifecycles && data.lifecycles.size > 0
+        ? this._factory.makeForLifecycle().normalizeIterable(data.lifecycles, options)
+        : undefined,
       tools: data.tools.size > 0
         ? this._factory.makeForTool().normalizeIterable(data.tools, options)
         : undefined,
@@ -220,6 +227,22 @@ export class MetadataNormalizer extends BaseJsonNormalizer<Models.Metadata> {
   }
 }
 
+export class LifecycleNormalizer extends BaseJsonNormalizer<Models.Lifecycle> {
+  normalize (data: Models.Lifecycle, options: NormalizerOptions): Normalized.Lifecycle {
+    return data instanceof Models.NamedLifecycle
+      ? { name: data.name, description: data.description }
+      : { phase: data }
+  }
+
+  normalizeIterable (data: SortableIterable<Models.Lifecycle>, options: NormalizerOptions): Normalized.Lifecycle[] {
+    return (
+      options.sortLists ?? false
+        ? data.sorted()
+        : Array.from(data)
+    ).map(lc => this.normalize(lc, options))
+  }
+}
+
 export class ToolNormalizer extends BaseJsonNormalizer<Models.Tool> {
   normalize (data: Models.Tool, options: NormalizerOptions): Normalized.Tool {
     return {

package/src/serialize/json/types.ts

@@ -87,6 +87,7 @@ export namespace Normalized {
 
   export interface Metadata {
     timestamp?: JsonSchema.DateTime
+    lifecycles?: Lifecycle[]
     tools?: Tool[]
     authors?: OrganizationalContact[]
     component?: Component
@@ -95,6 +96,17 @@ export namespace Normalized {
     licenses?: License[]
   }
 
+  export interface LifecyclePhase {
+    phase: Enums.LifecyclePhase
+  }
+
+  export interface NamedLifecycle {
+    name: string
+    description?: string
+  }
+
+  export type Lifecycle = LifecyclePhase | NamedLifecycle
+
   export interface Tool {
     vendor?: string
     name?: string

package/src/serialize/xml/normalize.ts

@@ -48,6 +48,10 @@ export class Factory {
     return new MetadataNormalizer(this)
   }
 
+  makeForLifecycle (): LifecycleNormalizer {
+    return new LifecycleNormalizer(this)
+  }
+
   makeForComponent (): ComponentNormalizer {
     return new ComponentNormalizer(this)
   }
@@ -220,6 +224,13 @@ export class BomNormalizer extends BaseXmlNormalizer<Models.Bom> {
 export class MetadataNormalizer extends BaseXmlNormalizer<Models.Metadata> {
   normalize (data: Models.Metadata, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     const orgEntityNormalizer = this._factory.makeForOrganizationalEntity()
+    const lifecycles: SimpleXml.Element | undefined = this._factory.spec.supportsMetadataLifecycles && data.lifecycles.size > 0
+      ? {
+          type: 'element',
+          name: 'lifecycles',
+          children: this._factory.makeForLifecycle().normalizeIterable(data.lifecycles, options, 'lifecycle')
+        }
+      : undefined
     const tools: SimpleXml.Element | undefined = data.tools.size > 0
       ? {
           type: 'element',
@@ -239,6 +250,7 @@ export class MetadataNormalizer extends BaseXmlNormalizer<Models.Metadata> {
       name: elementName,
       children: [
         makeOptionalDateTimeElement(data.timestamp, 'timestamp'),
+        lifecycles,
         tools,
         authors,
         data.component === undefined
@@ -255,6 +267,35 @@ export class MetadataNormalizer extends BaseXmlNormalizer<Models.Metadata> {
   }
 }
 
+export class LifecycleNormalizer extends BaseXmlNormalizer<Models.Lifecycle> {
+  normalize (data: Models.Lifecycle, options: NormalizerOptions, elementName: string): SimpleXml.Element {
+    return data instanceof Models.NamedLifecycle
+      ? {
+          type: 'element',
+          name: elementName,
+          children: [
+            makeTextElement(data.name, 'name'),
+            makeOptionalTextElement(data.description, 'description')
+          ].filter(isNotUndefined)
+        }
+      : {
+          type: 'element',
+          name: elementName,
+          children: [
+            makeTextElement(data, 'phase')
+          ]
+        }
+  }
+
+  normalizeIterable (data: SortableIterable<Models.Lifecycle>, options: NormalizerOptions, elementName: string): SimpleXml.Element[] {
+    return (
+      options.sortLists ?? false
+        ? data.sorted()
+        : Array.from(data)
+    ).map(t => this.normalize(t, options, elementName))
+  }
+}
+
 export class ToolNormalizer extends BaseXmlNormalizer<Models.Tool> {
   normalize (data: Models.Tool, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     const hashes: SimpleXml.Element | undefined = data.hashes.size > 0

package/src/spec.ts

@@ -51,6 +51,7 @@ export interface Protocol {
   supportsVulnerabilities: boolean
   supportsVulnerabilityRatingMethod: (rm: Vulnerability.RatingMethod | any) => boolean
   supportsComponentEvidence: boolean
+  supportsMetadataLifecycles: boolean
 }
 
 /**
@@ -71,6 +72,7 @@ class Spec implements Protocol {
   readonly #supportsProperties: boolean
   readonly #supportsVulnerabilities: boolean
   readonly #supportsComponentEvidence: boolean
+  readonly #supportsMetadataLifecycles: boolean
 
   constructor (
     version: Version,
@@ -85,7 +87,8 @@ class Spec implements Protocol {
     supportsProperties: boolean,
     supportsVulnerabilities: boolean,
     vulnerabilityRatingMethods: Iterable<Vulnerability.RatingMethod>,
-    supportsComponentEvidence: boolean
+    supportsComponentEvidence: boolean,
+    supportsMetadataLifecycles: boolean
   ) {
     this.#version = version
     this.#formats = new Set(formats)
@@ -100,6 +103,7 @@ class Spec implements Protocol {
     this.#supportsVulnerabilities = supportsVulnerabilities
     this.#vulnerabilityRatingMethods = new Set(vulnerabilityRatingMethods)
     this.#supportsComponentEvidence = supportsComponentEvidence
+    this.#supportsMetadataLifecycles = supportsMetadataLifecycles
   }
 
   get version (): Version {
@@ -155,6 +159,10 @@ class Spec implements Protocol {
   get supportsComponentEvidence (): boolean {
     return this.#supportsComponentEvidence
   }
+
+  get supportsMetadataLifecycles (): boolean {
+    return this.#supportsMetadataLifecycles
+  }
 }
 
 /** Specification v1.2 */
@@ -212,6 +220,7 @@ export const Spec1dot2: Readonly<Protocol> = Object.freeze(new Spec(
   false,
   false,
   [],
+  false,
   false
 ))
 
@@ -270,7 +279,8 @@ export const Spec1dot3: Readonly<Protocol> = Object.freeze(new Spec(
   true,
   false,
   [],
-  true
+  true,
+  false
 ))
 
 /** Specification v1.4 */
@@ -335,7 +345,8 @@ export const Spec1dot4: Readonly<Protocol> = Object.freeze(new Spec(
     Vulnerability.RatingMethod.OWASP,
     Vulnerability.RatingMethod.Other
   ],
-  true
+  true,
+  false
 ))
 
 /** Specification v1.5 */
@@ -429,6 +440,7 @@ export const Spec1dot5: Readonly<Protocol> = Object.freeze(new Spec(
     Vulnerability.RatingMethod.SSVC,
     Vulnerability.RatingMethod.Other
   ],
+  true,
   true
 ))
 

package/webpack.config.js

@@ -19,6 +19,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 
 const path = require('path')
 const deepmerge = require('deepmerge')
+const nodeExternals = require('webpack-node-externals')
 
 /* eslint-disable jsdoc/valid-types */
 
@@ -55,13 +56,8 @@ const configBase = {
       type: 'umd'
     }
   },
-  externals: {
-    ajv: 'ajv',
-    'ajv-formats': 'ajv-formats',
-    'ajv-formats-draft2019': 'ajv-formats-draft2019',
-    'packageurl-js': 'packageurl-js',
-    'spdx-expression-parse': 'spdx-expression-parse'
-  }
+  externalsPresets: { node: true },
+  externals: [nodeExternals()]
 }
 
 module.exports = [