@cyclonedx/cyclonedx-library 1.2.0 → 1.3.2

package/src/builders/fromNodePackageJson.node.ts

@@ -29,7 +29,7 @@ import { PackageJson, splitNameGroup } from '../helpers/packageJson'
 export class ToolBuilder {
   readonly #extRefFactory: Factories.FromNodePackageJson.ExternalReferenceFactory
 
-  constructor (extRefFactory: Factories.FromNodePackageJson.ExternalReferenceFactory) {
+  constructor (extRefFactory: ToolBuilder['extRefFactory']) {
     this.#extRefFactory = extRefFactory
   }
 
@@ -58,8 +58,8 @@ export class ComponentBuilder {
   readonly #licenseFactory: Factories.LicenseFactory
 
   constructor (
-    extRefFactory: Factories.FromNodePackageJson.ExternalReferenceFactory,
-    licenseFactory: Factories.LicenseFactory
+    extRefFactory: ComponentBuilder['extRefFactory'],
+    licenseFactory: ComponentBuilder['licenseFactory']
   ) {
     this.#extRefFactory = extRefFactory
     this.#licenseFactory = licenseFactory

package/src/factories/license.ts

@@ -24,7 +24,7 @@ export class LicenseFactory {
   makeFromString (value: string): License {
     try {
       return this.makeExpression(value)
-    } catch (Error) {
+    } catch {
       return this.makeDisjunctive(value)
     }
   }
@@ -39,7 +39,7 @@ export class LicenseFactory {
   makeDisjunctive (value: string): DisjunctiveLicense {
     try {
       return this.makeDisjunctiveWithId(value)
-    } catch (error) {
+    } catch {
       return this.makeDisjunctiveWithName(value)
     }
   }

package/src/factories/packageUrl.ts

@@ -24,7 +24,7 @@ import { ExternalReferenceType } from '../enums'
 export class PackageUrlFactory {
   readonly #type: PackageURL['type']
 
-  constructor (type: PackageURL['type']) {
+  constructor (type: PackageUrlFactory['type']) {
     this.#type = type
   }
 

package/src/models/attachment.ts

@@ -29,7 +29,7 @@ export class Attachment {
   content: string
   encoding?: AttachmentEncoding
 
-  constructor (content: string, op: OptionalProperties = {}) {
+  constructor (content: Attachment['content'], op: OptionalProperties = {}) {
     this.contentType = op.contentType
     this.content = content
     this.encoding = op.encoding

package/src/models/bom.ts

@@ -45,7 +45,7 @@ export class Bom {
   // The dependency graph can be normalized on render-time, no need to store it in the bom model.
 
   /**
-   * @throws {TypeError} if {@see op.version} is not {@see PositiveInteger} nor {@see undefined}
+   * @throws {TypeError} if {@see op.version} is neither {@see PositiveInteger} nor {@see undefined}
    * @throws {TypeError} if {@see op.serialNumber} is neither {@see UrnUuid} nor {@see undefined}
    */
   constructor (op: OptionalProperties = {}) {

package/src/models/bomRef.ts

@@ -24,12 +24,12 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 export class BomRef {
   value?: string
 
-  constructor (value?: string) {
+  constructor (value?: BomRef['value']) {
     this.value = value
   }
 
   compare (other: BomRef): number {
-    return (this.toString()).localeCompare(other.toString())
+    return this.toString().localeCompare(other.toString())
   }
 
   toString (): string {

package/src/models/component.ts

@@ -27,6 +27,7 @@ import { OrganizationalEntity } from './organizationalEntity'
 import { ExternalReferenceRepository } from './externalReference'
 import { LicenseRepository } from './license'
 import { SWID } from './swid'
+import { PropertyRepository } from './property'
 import { Comparable, SortableSet } from '../helpers/sortableSet'
 import { treeIterator } from '../helpers/tree'
 
@@ -48,6 +49,7 @@ interface OptionalProperties {
   dependencies?: Component['dependencies']
   components?: Component['components']
   cpe?: Component['cpe']
+  properties?: Component['properties']
 }
 
 export class Component implements Comparable {
@@ -68,6 +70,7 @@ export class Component implements Comparable {
   version?: string
   dependencies: BomRefRepository
   components: ComponentRepository
+  properties: PropertyRepository
 
   /** @see bomRef */
   readonly #bomRef: BomRef
@@ -78,7 +81,7 @@ export class Component implements Comparable {
   /**
    * @throws {TypeError} if {@see op.cpe} is neither {@see CPE} nor {@see undefined}
    */
-  constructor (type: ComponentType, name: string, op: OptionalProperties = {}) {
+  constructor (type: Component['type'], name: Component['name'], op: OptionalProperties = {}) {
     this.#bomRef = new BomRef(op.bomRef)
     this.type = type
     this.name = name
@@ -98,6 +101,7 @@ export class Component implements Comparable {
     this.dependencies = op.dependencies ?? new BomRefRepository()
     this.components = op.components ?? new ComponentRepository()
     this.cpe = op.cpe
+    this.properties = op.properties ?? new PropertyRepository()
   }
 
   get bomRef (): BomRef {

package/src/models/externalReference.ts

@@ -29,7 +29,7 @@ export class ExternalReference implements Comparable {
   type: ExternalReferenceType
   comment?: string
 
-  constructor (url: URL | string, type: ExternalReferenceType, op: OptionalProperties = {}) {
+  constructor (url: ExternalReference['url'], type: ExternalReference['type'], op: OptionalProperties = {}) {
     this.url = url
     this.type = type
     this.comment = op.comment

package/src/models/index.ts

@@ -27,5 +27,6 @@ export * from './license'
 export * from './metadata'
 export * from './organizationalContact'
 export * from './organizationalEntity'
+export * from './property'
 export * from './swid'
 export * from './tool'

package/src/models/license.ts

@@ -35,7 +35,7 @@ export class LicenseExpression {
   /**
    * @throws {RangeError} if {@see expression} is not eligible({@see LicenseExpression.isEligibleExpression})
    */
-  constructor (expression: string) {
+  constructor (expression: LicenseExpression['expression']) {
     this.expression = expression
   }
 
@@ -68,7 +68,7 @@ export class NamedLicense {
   text?: Attachment
   url?: URL | string
 
-  constructor (name: string, op: NamedLicenseOptionalProperties = {}) {
+  constructor (name: NamedLicense['name'], op: NamedLicenseOptionalProperties = {}) {
     this.name = name
     this.text = op.text
     this.url = op.url
@@ -94,7 +94,7 @@ export class SpdxLicense {
   /**
    * @throws {RangeError} if {@see id} is not supported SPDX id({@see isSupportedSpdxId})
    */
-  constructor (id: SpdxId, op: SpdxLicenseOptionalProperties = {}) {
+  constructor (id: SpdxLicense['id'], op: SpdxLicenseOptionalProperties = {}) {
     this.id = id
     this.text = op.text
     this.url = op.url

package/src/models/property.ts

@@ -0,0 +1,42 @@
+/*!
+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 { Comparable, SortableSet } from '../helpers/sortableSet'
+
+/**
+ * @see {@link https://github.com/CycloneDX/cyclonedx-property-taxonomy property-taxonomy}
+ */
+export class Property implements Comparable {
+  name: string
+  value: string
+
+  constructor (name: Property['name'], value: Property['value']) {
+    this.name = name
+    this.value = value
+  }
+
+  compare (other: Property): number {
+    /* eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
+    return this.name.localeCompare(other.name) ||
+      this.value.localeCompare(other.value)
+  }
+}
+
+export class PropertyRepository extends SortableSet<Property> {
+}

package/src/models/swid.ts

@@ -45,7 +45,7 @@ export class SWID {
   /**
    * @throws {TypeError} if {@see op.tagVersion} is neither {@see NonNegativeInteger} nor {@see undefined}
    */
-  constructor (tagId: string, name: string, op: OptionalProperties = {}) {
+  constructor (tagId: SWID['tagId'], name: SWID['name'], op: OptionalProperties = {}) {
     this.tagId = tagId
     this.name = name
     this.version = op.version

package/src/serialize/baseSerializer.ts

@@ -17,7 +17,7 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
-import { Bom, BomRef } from '../models'
+import { Component, Bom, BomRef } from '../models'
 import { BomRefDiscriminator } from './bomRefDiscriminator'
 import { NormalizerOptions, Serializer, SerializerOptions } from './types'
 
@@ -38,12 +38,19 @@ export abstract class BaseSerializer<NormalizedBom> implements Serializer {
 
   #getAllBomRefs (bom: Bom): Iterable<BomRef> {
     const bomRefs = new Set<BomRef>()
+    function iterComponents (cs: Iterable<Component>): void {
+      for (const { bomRef, components } of cs) {
+        bomRefs.add(bomRef)
+        iterComponents(components)
+      }
+    }
+
     if (bom.metadata.component !== undefined) {
       bomRefs.add(bom.metadata.component.bomRef)
+      iterComponents(bom.metadata.component.components)
     }
-    for (const { bomRef } of bom.components) {
-      bomRefs.add(bomRef)
-    }
+    iterComponents(bom.components)
+
     return bomRefs.values()
   }
 

package/src/serialize/json/normalize.ts

@@ -28,7 +28,7 @@ import { treeIterator } from '../../helpers/tree'
 export class Factory {
   readonly #spec: Spec
 
-  constructor (spec: Spec) {
+  constructor (spec: Factory['spec']) {
     this.#spec = spec
   }
 
@@ -80,6 +80,10 @@ export class Factory {
     return new AttachmentNormalizer(this)
   }
 
+  makeForProperty (): PropertyNormalizer {
+    return new PropertyNormalizer(this)
+  }
+
   makeForDependencyGraph (): DependencyGraphNormalizer {
     return new DependencyGraphNormalizer(this)
   }
@@ -100,7 +104,7 @@ interface Normalizer {
 abstract class Base implements Normalizer {
   protected readonly _factory: Factory
 
-  constructor (factory: Factory) {
+  constructor (factory: Base['factory']) {
     this._factory = factory
   }
 
@@ -199,7 +203,8 @@ export class HashNormalizer extends Base {
       options.sortLists ?? false
         ? data.sorted()
         : Array.from(data)
-    ).map(h => this.normalize(h, options)
+    ).map(
+      h => this.normalize(h, options)
     ).filter(isNotUndefined)
   }
 }
@@ -276,6 +281,9 @@ export class ComponentNormalizer extends Base {
           externalReferences: data.externalReferences.size > 0
             ? this._factory.makeForExternalReference().normalizeRepository(data.externalReferences, options)
             : undefined,
+          properties: spec.supportsProperties(data) && data.properties.size > 0
+            ? this._factory.makeForProperty().normalizeRepository(data.properties, options)
+            : undefined,
           components: data.components.size > 0
             ? this.normalizeRepository(data.components, options)
             : undefined
@@ -288,7 +296,8 @@ export class ComponentNormalizer extends Base {
       options.sortLists ?? false
         ? data.sorted()
         : Array.from(data)
-    ).map(c => this.normalize(c, options)
+    ).map(
+      c => this.normalize(c, options)
     ).filter(isNotUndefined)
   }
 }
@@ -382,7 +391,8 @@ export class ExternalReferenceNormalizer extends Base {
       options.sortLists ?? false
         ? data.sorted()
         : Array.from(data)
-    ).map(r => this.normalize(r, options)
+    ).map(
+      r => this.normalize(r, options)
     ).filter(isNotUndefined)
   }
 }
@@ -397,6 +407,23 @@ export class AttachmentNormalizer extends Base {
   }
 }
 
+export class PropertyNormalizer extends Base {
+  normalize (data: Models.Property, options: NormalizerOptions): Normalized.Property {
+    return {
+      name: data.name,
+      value: data.value
+    }
+  }
+
+  normalizeRepository (data: Models.PropertyRepository, options: NormalizerOptions): Normalized.Property[] {
+    return (
+      options.sortLists ?? false
+        ? data.sorted()
+        : Array.from(data)
+    ).map(p => this.normalize(p, options))
+  }
+}
+
 export class DependencyGraphNormalizer extends Base {
   normalize (data: Models.Bom, options: NormalizerOptions): Normalized.Dependency[] | undefined {
     const allRefs = new Map<Models.BomRef, Models.BomRefRepository>()

package/src/serialize/json/types.ts

@@ -132,6 +132,7 @@ export namespace Normalized {
     modified?: boolean
     externalReferences?: ExternalReference[]
     components?: Component[]
+    properties?: Property[]
   }
 
   export interface NamedLicense {
@@ -179,6 +180,11 @@ export namespace Normalized {
     encoding?: Enums.AttachmentEncoding
   }
 
+  export interface Property {
+    name?: string
+    value?: string
+  }
+
   export interface Dependency {
     ref: RefType
     dependsOn?: RefType[]

package/src/serialize/jsonSerializer.ts

@@ -33,7 +33,7 @@ export class JsonSerializer extends BaseSerializer<Normalized.Bom> {
   /**
    * @throws {UnsupportedFormatError} if {@see normalizerFactory.spec} does not support {@see Format.JSON}.
    */
-  constructor (normalizerFactory: NormalizerFactory) {
+  constructor (normalizerFactory: JsonSerializer['normalizerFactory']) {
     if (!normalizerFactory.spec.supportsFormat(Format.JSON)) {
       throw new UnsupportedFormatError('Spec does not support JSON format.')
     }

package/src/serialize/xml/normalize.ts

@@ -28,7 +28,7 @@ import { treeIterator } from '../../helpers/tree'
 export class Factory {
   readonly #spec: Spec
 
-  constructor (spec: Spec) {
+  constructor (spec: Factory['spec']) {
     this.#spec = spec
   }
 
@@ -80,6 +80,10 @@ export class Factory {
     return new AttachmentNormalizer(this)
   }
 
+  makeForProperty (): PropertyNormalizer {
+    return new PropertyNormalizer(this)
+  }
+
   makeForDependencyGraph (): DependencyGraphNormalizer {
     return new DependencyGraphNormalizer(this)
   }
@@ -100,7 +104,7 @@ interface Normalizer {
 abstract class Base implements Normalizer {
   protected readonly _factory: Factory
 
-  constructor (factory: Factory) {
+  constructor (factory: Base['factory']) {
     this._factory = factory
   }
 
@@ -256,7 +260,8 @@ export class HashNormalizer extends Base {
       options.sortLists ?? false
         ? data.sorted()
         : Array.from(data)
-    ).map(h => this.normalize(h, options, elementName)
+    ).map(
+      h => this.normalize(h, options, elementName)
     ).filter(isNotUndefined)
   }
 }
@@ -340,6 +345,13 @@ export class ComponentNormalizer extends Base {
             .normalizeRepository(data.externalReferences, options, 'reference')
         }
       : undefined
+    const properties: SimpleXml.Element | undefined = spec.supportsProperties(data) && data.properties.size > 0
+      ? {
+          type: 'element',
+          name: 'properties',
+          children: this._factory.makeForProperty().normalizeRepository(data.properties, options, 'property')
+        }
+      : undefined
     const components: SimpleXml.Element | undefined = data.components.size > 0
       ? {
           type: 'element',
@@ -370,6 +382,7 @@ export class ComponentNormalizer extends Base {
         makeOptionalTextElement(data.purl, 'purl'),
         swid,
         extRefs,
+        properties,
         components
       ].filter(isNotUndefined)
     }
@@ -380,7 +393,8 @@ export class ComponentNormalizer extends Base {
       options.sortLists ?? false
         ? data.sorted()
         : Array.from(data)
-    ).map(c => this.normalize(c, options, elementName)
+    ).map(
+      c => this.normalize(c, options, elementName)
     ).filter(isNotUndefined)
   }
 }
@@ -498,7 +512,8 @@ export class ExternalReferenceNormalizer extends Base {
       options.sortLists ?? false
         ? data.sorted()
         : Array.from(data)
-    ).map(r => this.normalize(r, options, elementName)
+    ).map(
+      r => this.normalize(r, options, elementName)
     ).filter(isNotUndefined)
   }
 }
@@ -517,6 +532,27 @@ export class AttachmentNormalizer extends Base {
   }
 }
 
+export class PropertyNormalizer extends Base {
+  normalize (data: Models.Property, options: NormalizerOptions, elementName: string): SimpleXml.Element {
+    return {
+      type: 'element',
+      name: elementName,
+      attributes: {
+        name: data.name
+      },
+      children: data.value
+    }
+  }
+
+  normalizeRepository (data: Models.PropertyRepository, options: NormalizerOptions, elementName: string): SimpleXml.Element[] {
+    return (
+      options.sortLists ?? false
+        ? data.sorted()
+        : Array.from(data)
+    ).map(p => this.normalize(p, options, elementName))
+  }
+}
+
 export class DependencyGraphNormalizer extends Base {
   normalize (data: Models.Bom, options: NormalizerOptions, elementName: string): SimpleXml.Element | undefined {
     const allRefs = new Map<Models.BomRef, Models.BomRefRepository>()

package/src/serialize/xmlBaseSerializer.ts

@@ -33,7 +33,7 @@ export abstract class XmlBaseSerializer extends BaseSerializer<SimpleXml.Element
   /**
    * @throws {UnsupportedFormatError} if {@see normalizerFactory.spec} does not support {@see Format.XML}.
    */
-  constructor (normalizerFactory: NormalizerFactory) {
+  constructor (normalizerFactory: XmlBaseSerializer['normalizerFactory']) {
     if (!normalizerFactory.spec.supportsFormat(Format.JSON)) {
       throw new UnsupportedFormatError('Spec does not support JSON format.')
     }

package/src/spec.ts

@@ -37,28 +37,21 @@ export class UnsupportedFormatError extends Error {
 }
 
 export interface Protocol {
-  readonly version: Version
-
+  version: Version
   supportsFormat: (f: Format | any) => boolean
-
   supportsComponentType: (ct: ComponentType | any) => boolean
-
   supportsHashAlgorithm: (ha: HashAlgorithm | any) => boolean
-
   supportsHashValue: (hv: HashContent | any) => boolean
-
   supportsExternalReferenceType: (ert: ExternalReferenceType | any) => boolean
-
-  readonly supportsDependencyGraph: boolean
-
-  readonly supportsToolReferences: boolean
-
-  readonly requiresComponentVersion: boolean
+  supportsDependencyGraph: boolean
+  supportsToolReferences: boolean
+  requiresComponentVersion: boolean
+  supportsProperties: (model: any) => boolean
 }
 
 /**
- * @internal This class was never intended to be public,
- *           but it is a helper to get the exact spec-versions implemented according to {@see Protocol}.
+ * @internal This class was never intended to be public, but
+ *           it is a helper to get the exact spec-versions implemented according to {@see Protocol}.
  */
 class Spec implements Protocol {
   readonly #version: Version
@@ -70,6 +63,7 @@ class Spec implements Protocol {
   readonly #supportsDependencyGraph: boolean
   readonly #supportsToolReferences: boolean
   readonly #requiresComponentVersion: boolean
+  readonly #supportsProperties: boolean
 
   constructor (
     version: Version,
@@ -80,7 +74,8 @@ class Spec implements Protocol {
     externalReferenceTypes: Iterable<ExternalReferenceType>,
     supportsDependencyGraph: boolean,
     supportsToolReferences: boolean,
-    requiresComponentVersion: boolean
+    requiresComponentVersion: boolean,
+    supportsProperties: boolean
   ) {
     this.#version = version
     this.#formats = new Set(formats)
@@ -91,6 +86,7 @@ class Spec implements Protocol {
     this.#supportsDependencyGraph = supportsDependencyGraph
     this.#supportsToolReferences = supportsToolReferences
     this.#requiresComponentVersion = requiresComponentVersion
+    this.#supportsProperties = supportsProperties
   }
 
   get version (): Version {
@@ -129,6 +125,11 @@ class Spec implements Protocol {
   get requiresComponentVersion (): boolean {
     return this.#requiresComponentVersion
   }
+
+  supportsProperties (): boolean {
+    // currently a global allow/deny -- might work based on input, in the future
+    return this.#supportsProperties
+  }
 }
 
 /** Specification v1.2 */
@@ -182,7 +183,8 @@ export const Spec1dot2: Readonly<Protocol> = Object.freeze(new Spec(
   ],
   true,
   false,
-  true
+  true,
+  false
 ))
 
 /** Specification v1.3 */
@@ -236,6 +238,7 @@ export const Spec1dot3: Readonly<Protocol> = Object.freeze(new Spec(
   ],
   true,
   false,
+  true,
   true
 ))
 
@@ -291,11 +294,14 @@ export const Spec1dot4: Readonly<Protocol> = Object.freeze(new Spec(
   ],
   true,
   true,
-  false
+  false,
+  true
 ))
 
-export const SpecVersionDict = Object.freeze(Object.fromEntries([
-  [Version.v1dot2, Spec1dot2],
-  [Version.v1dot3, Spec1dot3],
-  [Version.v1dot4, Spec1dot4]
-]) as { [key in Version]?: Readonly<Protocol> })
+export const SpecVersionDict: { readonly [key in Version]?: Readonly<Protocol> } = Object.freeze(
+  Object.fromEntries([
+    [Version.v1dot2, Spec1dot2],
+    [Version.v1dot3, Spec1dot3],
+    [Version.v1dot4, Spec1dot4]
+  ])
+)