feat: license acknowledgement (#1052)

fixes #1051


## Changed
  * Serializers and `License`-Normalizers will take license acknowledgement into account ([#1051] via [#1052])
## Added:
  * Namespace `Enums` 
    * New enum `LicenseAcknowledgement` ([#1051] via [#1052])
  * Namespace `Models`
    * Class `LicenseExpression` got new property `acknowledgement` ([#1051]
via [#1052])
    * Class `NamedLicense` got new property `acknowledgement` ([#1051] via [#1052])
    * Class `SpdxLicense` got new property `acknowledgement` ([#1051] via [#1052])

[#1051]: #1051
[#1052]: #1052

---------

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

Author: jkowalleck

.github/workflows/nodejs.yml

@@ -117,7 +117,7 @@ jobs:
           - "14.0.0"  # lowest supported
         os:
           - ubuntu-latest
-          - macos-latest
+          - macos-13 # macos-latest has issues with node14
           - windows-latest
     timeout-minutes: 10
     steps:

HISTORY.md

@@ -6,6 +6,19 @@ All notable changes to this project will be documented in this file.
 
 <!-- add unreleased items here -->
 
+* Changed
+  * Serializers and `License`-Normalizers will take license acknowledgement into account ([#1051] via [#1052])
+* Added:
+  * Namespace `Enums` 
+    * New enum `LicenseAcknowledgement` ([#1051] via [#1052])
+  * Namespace `Models`
+    * Class `LicenseExpression` got new property `acknowledgement` ([#1051] via [#1052])
+    * Class `NamedLicense`      got new property `acknowledgement` ([#1051] via [#1052])
+    * Class `SpdxLicense`       got new property `acknowledgement` ([#1051] via [#1052])
+
+[#1051]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/1051
+[#1052]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/1052
+
 ## 6.5.1 -- 2024-04-16
 
 * Dependencies

src/builders/fromNodePackageJson.node.ts

@@ -47,7 +47,7 @@ export class ToolBuilder {
   }
 
   // Current implementation does not return `undefined` yet, but it is an option for future implementation.
-  // To prevent breaking changes, it is declared to return `undefined`.
+  // To prevent future breaking changes, it is declared to return `undefined`.
   makeTool (data: PackageJson): Models.Tool | undefined {
     const [name, vendor] = typeof data.name === 'string'
       ? splitNameGroup(data.name)

src/enums/index.ts

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

src/enums/licenseAcknowledgement.ts

@@ -0,0 +1,23 @@
+/*!
+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 LicenseAcknowledgement {
+  Declared = 'declared',
+  Concluded = 'concluded',
+}

src/models/license.ts

@@ -18,6 +18,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
 import type { Sortable } from '../_helpers/sortable'
+import type { LicenseAcknowledgement } from '../enums'
 import type { SpdxId } from '../spdx'
 import type { Attachment } from './attachment'
 
@@ -31,6 +32,7 @@ import type { Attachment } from './attachment'
 export class LicenseExpression {
   /** @see {@link expression} */
   #expression!: string
+  acknowledgement?: LicenseAcknowledgement
 
   /**
    * @throws {@link RangeError} if `expression` is empty string
@@ -59,10 +61,12 @@ export class LicenseExpression {
 }
 
 class DisjunctiveLicenseBase {
+  acknowledgement?: LicenseAcknowledgement
   text?: Attachment
   #url?: URL | string
 
   constructor (op: OptionalDisjunctiveLicenseProperties = {}) {
+    this.acknowledgement = op.acknowledgement
     this.text = op.text
     this.url = op.url
   }
@@ -79,6 +83,7 @@ class DisjunctiveLicenseBase {
 }
 
 interface OptionalDisjunctiveLicenseProperties {
+  acknowledgement?: DisjunctiveLicenseBase['acknowledgement']
   text?: DisjunctiveLicenseBase['text']
   url?: DisjunctiveLicenseBase['url']
 }

src/serialize/json/normalize.ts

@@ -452,6 +452,9 @@ export class LicenseNormalizer extends BaseJsonNormalizer<Models.License> {
     return {
       license: {
         name: data.name,
+        acknowledgement: this._factory.spec.supportsLicenseAcknowledgement
+          ? data.acknowledgement
+          : undefined,
         text: data.text === undefined
           ? undefined
           : this._factory.makeForAttachment().normalize(data.text, options),
@@ -467,6 +470,9 @@ export class LicenseNormalizer extends BaseJsonNormalizer<Models.License> {
     return {
       license: {
         id: data.id,
+        acknowledgement: this._factory.spec.supportsLicenseAcknowledgement
+          ? data.acknowledgement
+          : undefined,
         text: data.text === undefined
           ? undefined
           : this._factory.makeForAttachment().normalize(data.text, options),
@@ -479,7 +485,10 @@ export class LicenseNormalizer extends BaseJsonNormalizer<Models.License> {
 
   #normalizeLicenseExpression (data: Models.LicenseExpression): Normalized.LicenseExpression {
     return {
-      expression: data.expression
+      expression: data.expression,
+      acknowledgement: this._factory.spec.supportsLicenseAcknowledgement
+        ? data.acknowledgement
+        : undefined
     }
   }
 

src/serialize/json/types.ts

@@ -170,6 +170,7 @@ export namespace Normalized {
   export interface NamedLicense {
     license: {
       name: string
+      acknowledgement?: Enums.LicenseAcknowledgement
       text?: Attachment
       url?: string
     }
@@ -179,13 +180,15 @@ export namespace Normalized {
     license: {
       /* see http://cyclonedx.org/schema/spdx */
       id: SpdxId
+      acknowledgement?: Enums.LicenseAcknowledgement
       text?: Attachment
       url?: string
     }
   }
 
   export interface LicenseExpression {
     expression: string
+    acknowledgement?: Enums.LicenseAcknowledgement
   }
 
   export type License = NamedLicense | SpdxLicense | LicenseExpression

src/serialize/xml/normalize.ts

@@ -578,6 +578,11 @@ export class LicenseNormalizer extends BaseXmlNormalizer<Models.License> {
     return {
       type: 'element',
       name: 'license',
+      attributes: {
+        acknowledgement: this._factory.spec.supportsLicenseAcknowledgement
+          ? data.acknowledgement
+          : undefined
+      },
       children: [
         makeTextElement(data.name, 'name'),
         data.text === undefined
@@ -595,6 +600,11 @@ export class LicenseNormalizer extends BaseXmlNormalizer<Models.License> {
     return {
       type: 'element',
       name: 'license',
+      attributes: {
+        acknowledgement: this._factory.spec.supportsLicenseAcknowledgement
+          ? data.acknowledgement
+          : undefined
+      },
       children: [
         makeTextElement(data.id, 'id'),
         data.text === undefined
@@ -608,7 +618,13 @@ export class LicenseNormalizer extends BaseXmlNormalizer<Models.License> {
   }
 
   #normalizeLicenseExpression (data: Models.LicenseExpression): SimpleXml.Element {
-    return makeTextElement(data.expression, 'expression')
+    const elem = makeTextElement(data.expression, 'expression')
+    elem.attributes = {
+      acknowledgement: this._factory.spec.supportsLicenseAcknowledgement
+        ? data.acknowledgement
+        : undefined
+    }
+    return elem
   }
 
   /**

src/spec/_protocol.ts

@@ -46,6 +46,7 @@ export interface _SpecProtocol {
   supportsMetadataLicenses: boolean
   supportsMetadataProperties: boolean
   supportsExternalReferenceHashes: boolean
+  supportsLicenseAcknowledgement: boolean
 }
 
 /**
@@ -73,6 +74,7 @@ export class _Spec implements _SpecProtocol {
   readonly #supportsMetadataLicenses: boolean
   readonly #supportsMetadataProperties: boolean
   readonly #supportsExternalReferenceHashes: boolean
+  readonly #supportsLicenseAcknowledgement: boolean
 
   constructor (
     version: Version,
@@ -91,7 +93,8 @@ export class _Spec implements _SpecProtocol {
     supportsMetadataLifecycles: boolean,
     supportsMetadataLicenses: boolean,
     supportsMetadataProperties: boolean,
-    supportsExternalReferenceHashes: boolean
+    supportsExternalReferenceHashes: boolean,
+    supportsLicenseAcknowledgement: boolean
   ) {
     this.#version = version
     this.#formats = new Set(formats)
@@ -110,6 +113,7 @@ export class _Spec implements _SpecProtocol {
     this.#supportsMetadataLicenses = supportsMetadataLicenses
     this.#supportsMetadataProperties = supportsMetadataProperties
     this.#supportsExternalReferenceHashes = supportsExternalReferenceHashes
+    this.#supportsLicenseAcknowledgement = supportsLicenseAcknowledgement
   }
 
   get version (): Version {
@@ -186,4 +190,8 @@ export class _Spec implements _SpecProtocol {
   get supportsExternalReferenceHashes (): boolean {
     return this.#supportsExternalReferenceHashes
   }
+
+  get supportsLicenseAcknowledgement (): boolean {
+    return this.#supportsLicenseAcknowledgement
+  }
 }