ComponentVersion became optional

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>

HISTORY.md

@@ -12,16 +12,19 @@ All notable changes to this project will be documented in this file.
 * Changed
   * Method `\CycloneDX\Core\Serialize\{DOM,JSON}\Normalizers\ExternalReferenceNormalizer::normalize` throw `DomainException` when `ExternalReference`'s type was not supported by the spec.  (via [#65])  
     This is considered a non-breaking change, because the behaviour was already documented in the API, even though there was no need for an implementation before.
+  * Class `\CycloneDX\Core\Models\Component`'s property `version` is optional now, to reflect CycloneDX v1.4. (via [#118])  
+    This affects constructor arguments, and affects methods `{get,set}Version()`.
 * Added
   * New class constant `\CycloneDX\Core\Spec\Version::V_1_4` for CycloneDX v1.4. (via [#65])
   * New class `\CycloneDX\Core\Spec\Spec14` to reflect CycloneDX v1.4. (via [#65])
-  * Support for CycloneDX v1.4 in `CycloneDX\Core\Validation\Validators\{Json,Xml}StrictValidator`. (via [#65])
+  * Support for CycloneDX v1.4 in `\CycloneDX\Core\Validation\Validators\{Json,Xml}StrictValidator`. (via [#65])
   * New methods in class `\CycloneDX\Core\Spec\Spec1{1,2,3}` (via [#65])
     * `::getSupportsExternalReferenceTypes()`
     * `::isSupportsExternalReferenceType()`
   * New class constant `CycloneDX\Core\Enums\ExternalReferenceType::RELEASE_NOTES` to reflect CycloneDX v1.4. (via [#65])
 
 [#65]: https://github.com/CycloneDX/cyclonedx-php-library/pull/65
+[#118]: https://github.com/CycloneDX/cyclonedx-php-library/pull/118
 
 ## 1.6.2 - 2022-09-12
 

src/Core/Models/Component.php

@@ -138,9 +138,7 @@ class Component
      * The component version. The version should ideally comply with semantic versioning
      * but is not enforced.
      *
-     * @var string
-     *
-     * @psalm-suppress PropertyNotSetInConstructor
+     * @var string|null
      */
     private $version;
 
@@ -303,15 +301,15 @@ public function setHashRepository(?HashRepository $hashRepository): self
         return $this;
     }
 
-    public function getVersion(): string
+    public function getVersion(): ?string
     {
         return $this->version;
     }
 
     /**
      * @return $this
      */
-    public function setVersion(string $version): self
+    public function setVersion(?string $version): self
     {
         $this->version = $version;
 
@@ -368,7 +366,7 @@ public function setExternalReferenceRepository(?ExternalReferenceRepository $ext
      *
      * @throws DomainException if type is unknown
      */
-    public function __construct(string $type, string $name, string $version)
+    public function __construct(string $type, string $name, ?string $version = null)
     {
         $this->setType($type);
         $this->setName($name);

src/Core/Serialize/DOM/Normalizers/ComponentNormalizer.php

@@ -58,7 +58,10 @@ public function normalize(Component $component): DOMElement
 
         $type = $component->getType();
         if (false === $spec->isSupportedComponentType($type)) {
-            $reportFQN = "$group/$name@$version";
+            $reportFQN = "$group/$name";
+            if (null !== $version) {
+                $reportFQN .= "@$version";
+            }
             throw new DomainException("Component '$reportFQN' has unsupported type: $type");
         }
 
@@ -80,7 +83,11 @@ public function normalize(Component $component): DOMElement
                 // publisher
                 $this->simpleDomSafeTextElement($document, 'group', $group),
                 $this->simpleDomSafeTextElement($document, 'name', $name),
-                $this->simpleDomSafeTextElement($document, 'version', $version),
+                $this->simpleDomSafeTextElement($document, 'version',
+                    null === $version && $spec->requiresComponentVersion()
+                        ? ''
+                        : $version
+                ),
                 $this->simpleDomSafeTextElement($document, 'description', $component->getDescription()),
                 // scope
                 $this->normalizeHashes($component->getHashRepository()),

src/Core/Serialize/JSON/Normalizers/ComponentNormalizer.php

@@ -54,7 +54,10 @@ public function normalize(Component $component): array
 
         $type = $component->getType();
         if (false === $spec->isSupportedComponentType($type)) {
-            $reportFQN = "$group/$name@$version";
+            $reportFQN = "$group/$name";
+            if (null !== $version) {
+                $reportFQN .= "@$version";
+            }
             throw new DomainException("Component '$reportFQN' has unsupported type: $type");
         }
 
@@ -67,7 +70,9 @@ public function normalize(Component $component): array
                 'bom-ref' => $bomRef,
                 'type' => $type,
                 'name' => $name,
-                'version' => $version,
+                'version' => null === $version && $spec->requiresComponentVersion()
+                    ? ''
+                    : $version,
                 'group' => $group,
                 'description' => $component->getDescription(),
                 'licenses' => $this->normalizeLicense($component->getLicense()),

src/Core/Spec/Spec11.php

@@ -103,4 +103,9 @@ public function supportsExternalReferenceHashes(): bool
     {
         return false;
     }
+
+    public function requiresComponentVersion(): bool
+    {
+        return true;
+    }
 }

src/Core/Spec/Spec12.php

@@ -111,4 +111,9 @@ public function supportsExternalReferenceHashes(): bool
     {
         return false;
     }
+
+    public function requiresComponentVersion(): bool
+    {
+        return true;
+    }
 }

src/Core/Spec/Spec13.php

@@ -111,4 +111,9 @@ public function supportsExternalReferenceHashes(): bool
     {
         return true;
     }
+
+    public function requiresComponentVersion(): bool
+    {
+        return true;
+    }
 }

src/Core/Spec/Spec14.php

@@ -115,4 +115,9 @@ public function supportsExternalReferenceHashes(): bool
     {
         return true;
     }
+
+    public function requiresComponentVersion(): bool
+    {
+        return false;
+    }
 }

src/Core/Spec/SpecInterface.php

@@ -102,4 +102,9 @@ public function isSupportsExternalReferenceType(string $referenceType): bool;
      * version < 1.3 does not support hashes in ExternalReference.
      */
     public function supportsExternalReferenceHashes(): bool;
+
+    /**
+     * version < 1.4 requires components to have a version, later it became optional.
+     */
+    public function requiresComponentVersion(): bool;
 }

tests/Core/Serialize/DOM/Normalizers/ComponentNormalizerTest.php

@@ -54,15 +54,15 @@ public function testNormalizeThrowsOnUnsupportedType(): void
             Component::class,
             [
                 'getName' => 'foo',
-                'getVersion' => 'some-version',
                 'getType' => 'FakeType',
             ]
         );
         $spec = $this->createMock(SpecInterface::class);
         $factory = $this->createConfiguredMock(NormalizerFactory::class, ['getSpec' => $spec]);
         $normalizer = new Normalizers\ComponentNormalizer($factory);
 
-        $spec->expects(self::once())->method('isSupportedComponentType')
+        $spec->expects(self::once())
+            ->method('isSupportedComponentType')
             ->with('FakeType')
             ->willReturn(false);
 
@@ -72,13 +72,16 @@ public function testNormalizeThrowsOnUnsupportedType(): void
         $normalizer->normalize($component);
     }
 
-    public function testNormalizeMinimal(): void
+    /**
+     * @dataProvider dbNormalizeMinimal
+     */
+    public function testNormalizeMinimal(string $expected, bool $requiresComponentVersion): void
     {
         $component = $this->createConfiguredMock(
             Component::class,
             [
                 'getName' => 'myName',
-                'getVersion' => 'some-version',
+                'getVersion' => null,
                 'getType' => 'FakeType',
                 'getGroup' => null,
                 'getDescription' => null,
@@ -94,16 +97,28 @@ public function testNormalizeMinimal(): void
         );
         $normalizer = new Normalizers\ComponentNormalizer($factory);
 
-        $spec->expects(self::once())->method('isSupportedComponentType')
+        $spec->expects(self::once())
+            ->method('isSupportedComponentType')
             ->with('FakeType')
             ->willReturn(true);
+        $spec->method('requiresComponentVersion')
+            ->willReturn($requiresComponentVersion);
 
-        $got = $normalizer->normalize($component);
+        $actual = $normalizer->normalize($component);
 
-        self::assertStringEqualsDomNode(
-            '<component type="FakeType"><name>myName</name><version>some-version</version></component>',
-            $got
-        );
+        self::assertStringEqualsDomNode($expected, $actual);
+    }
+
+    public function dbNormalizeMinimal(): \Generator
+    {
+        yield 'mandatory ComponentVersion' => [
+            '<component type="FakeType"><name>myName</name><version></version></component>',
+            true,
+        ];
+        yield 'optional ComponentVersion' => [
+            '<component type="FakeType"><name>myName</name></component>',
+            false,
+        ];
     }
 
     /**
@@ -148,13 +163,16 @@ public function testNormalizeFull(): void
         );
         $normalizer = new Normalizers\ComponentNormalizer($factory);
 
-        $spec->expects(self::once())->method('isSupportedComponentType')
+        $spec->expects(self::once())
+            ->method('isSupportedComponentType')
             ->with('FakeType')
             ->willReturn(true);
-        $licenseExpressionNormalizer->expects(self::once())->method('normalize')
+        $licenseExpressionNormalizer->expects(self::once())
+            ->method('normalize')
             ->with($component->getLicense())
             ->willReturn($factory->getDocument()->createElement('FakeLicense', 'dummy'));
-        $hashRepositoryNormalizer->expects(self::once())->method('normalize')
+        $hashRepositoryNormalizer->expects(self::once())
+            ->method('normalize')
             ->with($component->getHashRepository())
             ->willReturn([$factory->getDocument()->createElement('FakeHash', 'dummy')]);
 
@@ -185,7 +203,6 @@ public function testNormalizeUnsupportedLicenseExpression(): void
             Component::class,
             [
                 'getName' => 'myName',
-                'getVersion' => 'some-version',
                 'getType' => 'FakeType',
                 'getLicense' => $this->createConfiguredMock(LicenseExpression::class, ['getExpression' => 'myLicense']),
             ]
@@ -217,10 +234,12 @@ public function testNormalizeUnsupportedLicenseExpression(): void
             return true;
         };
 
-        $spec->expects(self::once())->method('isSupportedComponentType')
+        $spec->expects(self::once())
+            ->method('isSupportedComponentType')
             ->with('FakeType')
             ->willReturn(true);
-        $licenseNormalizer->expects(self::once())->method('normalize')
+        $licenseNormalizer->expects(self::once())
+            ->method('normalize')
             ->with($this->callback($transformedLicenseTest))
             ->willReturn([$factory->getDocument()->createElement('FakeLicense', 'dummy')]);
 
@@ -229,7 +248,6 @@ public function testNormalizeUnsupportedLicenseExpression(): void
         self::assertStringEqualsDomNode(
             '<component type="FakeType">'.
             '<name>myName</name>'.
-            '<version>some-version</version>'.
             '<licenses><FakeLicense>dummy</FakeLicense></licenses>'.
             '</component>',
             $got
@@ -242,7 +260,6 @@ public function testNormalizeDisjunctiveLicenses(): void
             Component::class,
             [
                 'getName' => 'myName',
-                'getVersion' => 'some-version',
                 'getType' => 'FakeType',
                 'getLicense' => $this->createConfiguredMock(DisjunctiveLicenseRepository::class, ['count' => 1]),
             ]
@@ -259,10 +276,12 @@ public function testNormalizeDisjunctiveLicenses(): void
         );
         $normalizer = new Normalizers\ComponentNormalizer($factory);
 
-        $spec->expects(self::once())->method('isSupportedComponentType')
+        $spec->expects(self::once())
+            ->method('isSupportedComponentType')
             ->with('FakeType')
             ->willReturn(true);
-        $licenseNormalizer->expects(self::once())->method('normalize')
+        $licenseNormalizer->expects(self::once())
+            ->method('normalize')
             ->with($component->getLicense())
             ->willReturn([$factory->getDocument()->createElement('FakeLicense', 'dummy')]);
 
@@ -271,7 +290,6 @@ public function testNormalizeDisjunctiveLicenses(): void
         self::assertStringEqualsDomNode(
             '<component type="FakeType">'.
             '<name>myName</name>'.
-            '<version>some-version</version>'.
             '<licenses><FakeLicense>dummy</FakeLicense></licenses>'.
             '</component>',
             $got
@@ -284,7 +302,6 @@ public function testNormalizeDisjunctiveLicensesEmpty(): void
             Component::class,
             [
                 'getName' => 'myName',
-                'getVersion' => 'some-version',
                 'getType' => 'FakeType',
                 'getLicense' => $this->createConfiguredMock(DisjunctiveLicenseRepository::class, ['count' => 0]),
             ]
@@ -301,17 +318,18 @@ public function testNormalizeDisjunctiveLicensesEmpty(): void
         );
         $normalizer = new Normalizers\ComponentNormalizer($factory);
 
-        $spec->expects(self::once())->method('isSupportedComponentType')
+        $spec->expects(self::once())
+            ->method('isSupportedComponentType')
             ->with('FakeType')
             ->willReturn(true);
-        $licenseNormalizer->expects(self::never())->method('normalize');
+        $licenseNormalizer->expects(self::never())
+            ->method('normalize');
 
         $got = $normalizer->normalize($component);
 
         self::assertStringEqualsDomNode(
             '<component type="FakeType">'.
             '<name>myName</name>'.
-            '<version>some-version</version>'.
             '</component>',
             $got
         );
@@ -325,7 +343,6 @@ public function testNormalizeExternalReferences(): void
             Component::class,
             [
                 'getName' => 'myName',
-                'getVersion' => 'some-version',
                 'getType' => 'FakeType',
                 'getExternalReferenceRepository' => $this->createConfiguredMock(ExternalReferenceRepository::class, ['count' => 1]),
             ]
@@ -342,7 +359,8 @@ public function testNormalizeExternalReferences(): void
         );
         $normalizer = new Normalizers\ComponentNormalizer($factory);
 
-        $spec->expects(self::once())->method('isSupportedComponentType')
+        $spec->expects(self::once())
+            ->method('isSupportedComponentType')
             ->with('FakeType')
             ->willReturn(true);
         $externalReferenceRepositoryNormalizer->expects(self::once())
@@ -355,7 +373,6 @@ public function testNormalizeExternalReferences(): void
         self::assertStringEqualsDomNode(
             '<component type="FakeType">'.
             '<name>myName</name>'.
-            '<version>some-version</version>'.
             '<externalReferences><FakeExternalReference>dummy</FakeExternalReference></externalReferences>'.
             '</component>',
             $actual
@@ -368,7 +385,6 @@ public function testNormalizeExternalReferencesOmitIfEmpty(): void
             Component::class,
             [
                 'getName' => 'myName',
-                'getVersion' => 'some-version',
                 'getType' => 'FakeType',
                 'getExternalReferenceRepository' => $this->createConfiguredMock(ExternalReferenceRepository::class, ['count' => 0]),
             ]
@@ -385,17 +401,18 @@ public function testNormalizeExternalReferencesOmitIfEmpty(): void
         );
         $normalizer = new Normalizers\ComponentNormalizer($factory);
 
-        $spec->expects(self::once())->method('isSupportedComponentType')
+        $spec->expects(self::once())
+            ->method('isSupportedComponentType')
             ->with('FakeType')
             ->willReturn(true);
-        $externalReferenceRepositoryNormalizer->expects(self::never())->method('normalize');
+        $externalReferenceRepositoryNormalizer->expects(self::never())
+            ->method('normalize');
 
         $actual = $normalizer->normalize($component);
 
         self::assertStringEqualsDomNode(
             '<component type="FakeType">'.
             '<name>myName</name>'.
-            '<version>some-version</version>'.
             '</component>',
             $actual
         );