Models.Properties & Models.Component.properties (#151)

models for Properties & component.properties

  * Models for `Property`, `PropertyRepository`.
  * JSON- and XML-Normalizers for `Models.Property`, `Models.PropertyRepository`.
  * New property `Models.Component.properties`.

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

Author: jkowalleck

HISTORY.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ## unreleased
 
+* Added
+  * Models for `Property` and `PropertyRepository`. (via [#151]) 
+  * JSON- and XML-Normalizer for `Models.Property`, `Models.PropertyRepository`. (via [#151])
+  * New property `Models.Component.properties`. (via [#151])
+
+[#151]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/151
+
 ## 1.2.0 - 2022-08-01
 
 * Added

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 {

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'

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> {
+}

src/serialize/json/normalize.ts

@@ -80,6 +80,10 @@ export class Factory {
     return new AttachmentNormalizer(this)
   }
 
+  makeForProperty (): PropertyNormalizer {
+    return new PropertyNormalizer(this)
+  }
+
   makeForDependencyGraph (): DependencyGraphNormalizer {
     return new DependencyGraphNormalizer(this)
   }
@@ -278,6 +282,9 @@ export class ComponentNormalizer extends Base {
             : undefined,
           components: data.components.size > 0
             ? this.normalizeRepository(data.components, options)
+            : undefined,
+          properties: data.properties.size > 0
+            ? this._factory.makeForProperty().normalizeRepository(data.properties, options)
             : undefined
         }
       : undefined
@@ -397,6 +404,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>()

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[]

src/serialize/xml/normalize.ts

@@ -80,6 +80,10 @@ export class Factory {
     return new AttachmentNormalizer(this)
   }
 
+  makeForProperty (): PropertyNormalizer {
+    return new PropertyNormalizer(this)
+  }
+
   makeForDependencyGraph (): DependencyGraphNormalizer {
     return new DependencyGraphNormalizer(this)
   }
@@ -347,6 +351,13 @@ export class ComponentNormalizer extends Base {
           children: this.normalizeRepository(data.components, options, 'component')
         }
       : undefined
+    const properties: SimpleXml.Element | undefined = data.properties.size > 0
+      ? {
+          type: 'element',
+          name: 'properties',
+          children: this._factory.makeForProperty().normalizeRepository(data.properties, options, 'property')
+        }
+      : undefined
     return {
       type: 'element',
       name: elementName,
@@ -370,7 +381,8 @@ export class ComponentNormalizer extends Base {
         makeOptionalTextElement(data.purl, 'purl'),
         swid,
         extRefs,
-        components
+        components,
+        properties
       ].filter(isNotUndefined)
     }
   }
@@ -517,6 +529,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>()

tests/_data/models.js

@@ -186,5 +186,15 @@ module.exports.createComplexStructure = function () {
       bomRef: 'SomeFrameworkBundle'
     })))
 
+  bom.components.add(new Models.Component(
+    Enums.ComponentType.Library, 'component-with-properties', {
+      bomRef: 'ComponentWithProperties',
+      properties: new Models.PropertyRepository([
+        new Models.Property('internal:testing:prop-Z', 'value Z'),
+        new Models.Property('internal:testing:prop-Z', 'value B'),
+        new Models.Property('internal:testing:prop-A', 'value A')
+      ])
+    }))
+
   return bom
 }