PackageUrlFactory::makeFromComponent() - checksums and download_url (#146)

Factory for `PackageURL` from `Models.Component` can handle additional data sources:
    * `Models.Component.hashes` map -> `PackageURL.qualifiers.checksum` list
    * `Models.Component.externalReferences[distribution].url` -> `PackageURL.qualifiers.download_url`
    * Method `Factories.PackageUrlFactory.makeFromComponent()` got a new optional parameter `sort`,
      to indicate whether to go the extra mile and bring hashes and qualifiers in alphabetical order.  
      This feature switch is related to reproducible builds.

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

Author: jkowalleck

HISTORY.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 ## unreleased
 
 * Added
-  * Getters/properties that represent the corresponding parameters of class constructor. (via [#145])
+  * New getters/properties that represent the corresponding parameters of class constructor. (via [#145])
     * `Builders.FromPackageJson.ComponentBuilder.extRefFactory`,  
       `Builders.FromPackageJson.ComponentBuilder.licenseFactory`
     * `Builders.FromPackageJson.ToolBuilder.extRefFactory`
@@ -14,8 +14,15 @@ All notable changes to this project will be documented in this file.
     * `Serialize.JsonSerializer.normalizerFactory`
     * `Serialize.XmlBaseSerializer.normalizerFactory`,  
       `Serialize.XmlSerializer.normalizerFactory`
+  * Factory for `PackageURL` from `Models.Component` can handle additional data sources, now. (via [#146])
+    * `Models.Component.hashes` map -> `PackageURL.qualifiers.checksum` list
+    * `Models.Component.externalReferences[distribution].url` -> `PackageURL.qualifiers.download_url`
+    * Method `Factories.PackageUrlFactory.makeFromComponent()` got a new optional param `sort`,
+      to indicate whether to go the extra mile and bring hashes and qualifiers in alphabetical order.  
+      This feature switch is related to reproducible builds.
 
 [#145]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/145
+[#146]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/146
 
 ## 1.1.0 - 2022-07-29
 

package.json

@@ -18,7 +18,7 @@
   "homepage": "https://github.com/CycloneDX/cyclonedx-javascript-library#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/CycloneDX/cyclonedx-javascript-library.git"
+    "url": "git+https://github.com/CycloneDX/cyclonedx-javascript-library.git"
   },
   "bugs": {
     "url": "https://github.com/CycloneDX/cyclonedx-javascript-library/issues"

src/factories/packageUrl.ts

@@ -32,18 +32,37 @@ export class PackageUrlFactory {
     return this.#type
   }
 
-  makeFromComponent (component: Component): PackageURL | undefined {
+  makeFromComponent (component: Component, sort: boolean = false): PackageURL | undefined {
+    /**
+     * For the list/spec of the well-known keys, see
+     * {@link https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst#known-qualifiers-keyvalue-pairs}
+     */
     const qualifiers: PackageURL['qualifiers'] = {}
     let subpath: PackageURL['subpath']
 
-    for (const e of component.externalReferences) {
-      if (e.type === ExternalReferenceType.VCS) {
-        [qualifiers.vcs_url, subpath] = e.url.toString().split('#', 2)
-        break
+    const extRefs = component.externalReferences
+    for (const extRef of (sort ? extRefs.sorted() : extRefs)) {
+      switch (extRef.type) {
+        case ExternalReferenceType.VCS:
+          [qualifiers.vcs_url, subpath] = extRef.url.toString().split('#', 2)
+          break
+        case ExternalReferenceType.Distribution:
+          qualifiers.download_url = extRef.url.toString()
+          break
       }
     }
 
+    const hashes = component.hashes
+    if (hashes.size > 0) {
+      qualifiers.checksum = Array.from(
+        sort ? hashes.sorted() : hashes,
+        ([hashAlgo, hashCont]) => `${hashAlgo.toLowerCase()}:${hashCont.toLowerCase()}`
+      ).join(',')
+    }
+
     try {
+      // Do not beautify the parameters here, because that is in the domain of PackageURL and its representation.
+      // No need to convert an empty `subpath` string to `undefined` and such.
       return new PackageURL(
         this.#type,
         component.group,

tests/README.md

@@ -9,6 +9,11 @@ instead of the source(`src/`).
 Test files must follow the pattern `**.{spec,test}.[cm]?js`,
 to be picked up.
 
+## Snapshots
+
+Some tests check against snapshots.  
+To update these, set the env var `CJL_TEST_UPDATE_SNAPSHOTS` to a non-falsy value.
+
 ## Run node tests
 
 Test runner is `mocha`,

tests/integration/Factories.PackageUrlFactory.test.js

@@ -41,7 +41,9 @@ suite('Factories.PackageUrlFactory', () => {
         ''
       )
       const expected = undefined
+
       const actual = sut.makeFromComponent(component)
+
       assert.strictEqual(actual, expected)
     })
 
@@ -58,38 +60,109 @@ suite('Factories.PackageUrlFactory', () => {
         }
       )
       const expected = new PackageURL('testing', `@group-${salt}`, `name-${salt}`, `v1+${salt}`, {}, undefined)
+
+      const actual = sut.makeFromComponent(component)
+
+      assert.deepStrictEqual(actual, expected)
+    })
+
+    test('extRef[vcs] -> qualifiers.vcs-url without subpath', () => {
+      const component = new Models.Component(
+        Enums.ComponentType.Library,
+        `name-${salt}`,
+        {
+          externalReferences: new Models.ExternalReferenceRepository([
+            new Models.ExternalReference('git+https://foo.bar/repo.git', Enums.ExternalReferenceType.VCS)
+          ])
+        }
+      )
+      const expected = new PackageURL('testing', undefined, `name-${salt}`, undefined, { vcs_url: 'git+https://foo.bar/repo.git' }, undefined)
+
       const actual = sut.makeFromComponent(component)
+
       assert.deepStrictEqual(actual, expected)
     })
 
-    test('vcs-url without subpath', () => {
+    test('extRef[vcs] -> qualifiers.vcs-url with subpath', () => {
       const component = new Models.Component(
         Enums.ComponentType.Library,
         `name-${salt}`,
         {
           externalReferences: new Models.ExternalReferenceRepository([
-            new Models.ExternalReference('git://foo.bar', Enums.ExternalReferenceType.VCS)
+            new Models.ExternalReference('git+https://foo.bar/repo.git#sub/path', Enums.ExternalReferenceType.VCS)
           ])
         }
       )
-      const expected = new PackageURL('testing', undefined, `name-${salt}`, undefined, { vcs_url: 'git://foo.bar' }, undefined)
+      const expected = new PackageURL('testing', undefined, `name-${salt}`, undefined, { vcs_url: 'git+https://foo.bar/repo.git' }, 'sub/path')
+
       const actual = sut.makeFromComponent(component)
+
       assert.deepStrictEqual(actual, expected)
     })
 
-    test('vcs-url with subpath', () => {
+    test('extRef[distribution] -> qualifiers.download_url', () => {
       const component = new Models.Component(
         Enums.ComponentType.Library,
         `name-${salt}`,
         {
           externalReferences: new Models.ExternalReferenceRepository([
-            new Models.ExternalReference('git://foo.bar#sub/path', Enums.ExternalReferenceType.VCS)
+            new Models.ExternalReference('https://foo.bar/download', Enums.ExternalReferenceType.Distribution)
           ])
         }
       )
-      const expected = new PackageURL('testing', undefined, `name-${salt}`, undefined, { vcs_url: 'git://foo.bar' }, 'sub/path')
+      const expected = new PackageURL('testing', undefined, `name-${salt}`, undefined, { download_url: 'https://foo.bar/download' }, undefined)
+
       const actual = sut.makeFromComponent(component)
+
       assert.deepStrictEqual(actual, expected)
     })
+
+    test('hashes -> qualifiers.checksum', () => {
+      const component = new Models.Component(
+        Enums.ComponentType.Library,
+        `name-${salt}`,
+        {
+          hashes: new Models.HashRepository([
+            [Enums.HashAlgorithm['SHA-256'], 'C3AB8FF13720E8AD9047DD39466B3C8974E592C2FA383D4A3960714CAEF0C4F2']
+          ])
+        }
+      )
+      const expected = new PackageURL('testing', undefined, `name-${salt}`, undefined, { checksum: 'sha-256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2' }, undefined)
+
+      const actual = sut.makeFromComponent(component)
+
+      assert.deepStrictEqual(actual, expected)
+    })
+
+    test('sorted', () => {
+      const component = new Models.Component(
+        Enums.ComponentType.Library,
+        'name',
+        {
+          externalReferences: new Models.ExternalReferenceRepository([
+            new Models.ExternalReference('git+https://foo.bar/repo.git', Enums.ExternalReferenceType.VCS),
+            new Models.ExternalReference('https://foo.bar/download', Enums.ExternalReferenceType.Distribution)
+          ]),
+          hashes: new Models.HashRepository([
+            [Enums.HashAlgorithm['SHA-256'], 'C3AB8FF13720E8AD9047DD39466B3C8974E592C2FA383D4A3960714CAEF0C4F2'],
+            [Enums.HashAlgorithm.BLAKE3, 'aa51dcd43d5c6c5203ee16906fd6b35db298b9b2e1de3fce81811d4806b76b7d']
+          ])
+        }
+      )
+      const expectedObject = new PackageURL('testing', undefined, 'name', undefined,
+        {
+          // expect sorted hash list
+          checksum: 'blake3:aa51dcd43d5c6c5203ee16906fd6b35db298b9b2e1de3fce81811d4806b76b7d,sha-256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2',
+          download_url: 'https://foo.bar/download',
+          vcs_url: 'git+https://foo.bar/repo.git'
+        }, undefined)
+      // expect objet's keys in alphabetical oder, expect sorted hash list
+      const expectedString = 'pkg:testing/name?checksum=blake3:aa51dcd43d5c6c5203ee16906fd6b35db298b9b2e1de3fce81811d4806b76b7d,sha-256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2&download_url=https://foo.bar/download&vcs_url=git+https://foo.bar/repo.git'
+
+      const actual = sut.makeFromComponent(component, true)
+
+      assert.deepStrictEqual(actual, expectedObject)
+      assert.deepStrictEqual(actual.toString(), expectedString)
+    })
   })
 })