BC: make CycloneDX\Core\Spec\Spec internal (#345)

* BC: make `CycloneDX\Core\Spec\Spec` internal Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com> * docs Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com> * docs Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com> * history Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com> * history Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com> --------- Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>
CycloneDX · Aug 27, 2023 · aa16f71 · aa16f71
1 parent 3deade3
commit aa16f71
Show file tree

Hide file tree

Showing 46 changed files with 227 additions and 214 deletions.
diff --git a/HISTORY.md b/HISTORY.md
@@ -4,26 +4,32 @@ All notable changes to this project will be documented in this file.
 
 ## unreleased
 
+* BREAKING
+  * Interface `\CycloneDX\Core\Spec\Spec` was removed from public API ([#344] via [#345])  
+    This is only a breaking change if you custom-implemented this interface downstream; internal usage is non-breaking.  
+    This change was necessary, so that implementing more spec-features cause no breaking changes.
 * Style
   * Applied latest PHP Coding Standards (via [#341])
 
 [#341]: https://github.com/CycloneDX/cyclonedx-php-library/pull/341
+[#344]: https://github.com/CycloneDX/cyclonedx-php-library/issues/344
+[#345]: https://github.com/CycloneDX/cyclonedx-php-library/pull/345
 
 ## 2.3.0 - 2023-06-27
 
 Added support for [_CycloneDX_ Specification-1.5](https://github.com/CycloneDX/specification/releases/tag/1.5).
 
 * Changed
-  * Method `Core\Spec\SpecFactory::makeForVersion()` supports _CycloneDX_ Specification-1.5 now ([#193] via [#255])
-  * Classes `Core\Serialization\{DOM,JSON}\Normalizers\*` support _CycloneDX_ Specification-1.5 now ([#193] via [#255])
-  * Classes `Core\Validation\Validators\*` support _CycloneDX_ Specification-1.5 now ([#193] via [#255])
+  * Method `\CycloneDX\Core\Spec\SpecFactory::makeForVersion()` supports _CycloneDX_ Specification-1.5 now ([#193] via [#255])
+  * Classes `\CycloneDX\Core\Serialization\{DOM,JSON}\Normalizers\*` support _CycloneDX_ Specification-1.5 now ([#193] via [#255])
+  * Classes `\CycloneDX\Core\Validation\Validators\*` support _CycloneDX_ Specification-1.5 now ([#193] via [#255])
 * Added
-  * Namespace `Core\Enums`
+  * Namespace `\CycloneDX\Core\Enums`
     * Enum `ComponentType` got new cases ([#193] via [#255])  
       New: `Data`, `DeviceDriver`, `MachineLearningModel`, `Platform`
     * Enum `ExternalReferenceType` got new cases ([#193] via [#255])  
       New: `AdversaryModel`, `Attestation`, `CertificationReport`, `CodifiedInfrastructure`, `ComponentAnalysisReport`, `Configuration`, `DistributionIntake`, `DynamicAnalysisReport`, `Evidence`, `ExploitabilityStatement`, `Formulation`, `Log`, `MaturityReport`, `ModelCard`, `POAM`, `PentestReport`, `QualityMetrics`, `RiskAssessment`, `RuntimeAnalysisReport`, `SecurityContact`, `StaticAnalysisReport`, `ThreatModel`, `VulnerabilityAssertion`
-  * Namespace `Core\Spec`
+  * Namespace `\CycloneDX\Core\Spec`
     * New method `SpecFactory::make1dot5()` to reflect _CycloneDX_ Specification-1.5 ([#193] via [#255])
     * Enum `Version` got new case `v1dot5` to reflect _CycloneDX_ Specification-1.5 ([#193] via [#255])
 * Misc

diff --git a/src/Core/Serialization/DOM/NormalizerFactory.php b/src/Core/Serialization/DOM/NormalizerFactory.php
@@ -23,8 +23,8 @@
 
 namespace CycloneDX\Core\Serialization\DOM;
 
+use CycloneDX\Core\Spec\_SpecProtocol as Spec;
 use CycloneDX\Core\Spec\Format;
-use CycloneDX\Core\Spec\Spec;
 use DomainException;
 use DOMDocument;
 

diff --git a/src/Core/Serialization/JSON/NormalizerFactory.php b/src/Core/Serialization/JSON/NormalizerFactory.php
@@ -23,8 +23,8 @@
 
 namespace CycloneDX\Core\Serialization\JSON;
 
+use CycloneDX\Core\Spec\_SpecProtocol as Spec;
 use CycloneDX\Core\Spec\Format;
-use CycloneDX\Core\Spec\Spec;
 use DomainException;
 
 /**

diff --git a/src/Core/Spec/SpecFactory.php b/src/Core/Spec/SpecFactory.php
@@ -29,7 +29,7 @@
 use DomainException;
 
 /**
- * Factory for {@see \CycloneDX\Core\Spec\Spec Specification} objects.
+ * Factory for {@see \CycloneDX\Core\Spec\_SpecProtocol Specification} objects.
  */
 abstract class SpecFactory
 {
@@ -47,11 +47,11 @@ abstract class SpecFactory
     */
 
     /**
-     * Create the appropriate {@see \CycloneDX\Core\Spec\Spec Specification} based on {@see \CycloneDX\Core\Spec\Version}.
+     * Create the appropriate {@see \CycloneDX\Core\Spec\_SpecProtocol Specification} based on {@see \CycloneDX\Core\Spec\Version}.
      *
      * @throws DomainException when $version was unsupported
      */
-    public static function makeForVersion(Version $version): Spec
+    public static function makeForVersion(Version $version): _SpecProtocol
     {
         return match ($version) {
             Version::v1dot1 => self::make1dot1(),
@@ -65,9 +65,9 @@ public static function makeForVersion(Version $version): Spec
     }
 
     /**
-     * Create the {@see \CycloneDX\Core\Spec\Spec Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot1}.
+     * Create the {@see \CycloneDX\Core\Spec\_SpecProtocol Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot1}.
      */
-    public static function make1dot1(): Spec
+    public static function make1dot1(): _SpecProtocol
     {
         return new _Spec(
             Version::v1dot1,
@@ -125,9 +125,9 @@ public static function make1dot1(): Spec
     }
 
     /**
-     * Create the {@see \CycloneDX\Core\Spec\Spec Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot2}.
+     * Create the {@see \CycloneDX\Core\Spec\_SpecProtocol Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot2}.
      */
-    public static function make1dot2(): Spec
+    public static function make1dot2(): _SpecProtocol
     {
         return new _Spec(
             Version::v1dot2,
@@ -193,9 +193,9 @@ public static function make1dot2(): Spec
     }
 
     /**
-     * Create the {@see \CycloneDX\Core\Spec\Spec Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot3}.
+     * Create the {@see \CycloneDX\Core\Spec\_SpecProtocol Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot3}.
      */
-    public static function make1dot3(): Spec
+    public static function make1dot3(): _SpecProtocol
     {
         return new _Spec(
             Version::v1dot3,
@@ -264,9 +264,9 @@ public static function make1dot3(): Spec
     }
 
     /**
-     * Create the {@see \CycloneDX\Core\Spec\Spec Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot4}.
+     * Create the {@see \CycloneDX\Core\Spec\_SpecProtocol Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot4}.
      */
-    public static function make1dot4(): Spec
+    public static function make1dot4(): _SpecProtocol
     {
         return new _Spec(
             Version::v1dot4,
@@ -336,9 +336,9 @@ public static function make1dot4(): Spec
     }
 
     /**
-     * Create the {@see \CycloneDX\Core\Spec\Spec Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot5}.
+     * Create the {@see \CycloneDX\Core\Spec\_SpecProtocol Specification} based on {@see \CycloneDX\Core\Spec\Version::v1dot5}.
      */
-    public static function make1dot5(): Spec
+    public static function make1dot5(): _SpecProtocol
     {
         return new _Spec(
             Version::v1dot5,

diff --git a/src/Core/Spec/_Spec.php b/src/Core/Spec/_Spec.php
@@ -29,8 +29,9 @@
 use CycloneDX\Core\Spdx\LicenseIdentifiers;
 
 /**
- * This class is not for public use.
- * See {@see \CycloneDX\Core\Spec\SpecFactory Specification Factory} to get prepared instances.
+ * This class is not intended to be public API.
+ *
+ * This is a helper to get the exact spec-versions implemented according to {@see \CycloneDX\Core\Spec\_SpecProtocol Specification}.
  *
  * @internal as this class may be affected by breaking changes without notice
  *
@@ -40,7 +41,7 @@
  *
  * @author jkowalleck
  */
-class _Spec implements Spec
+class _Spec implements _SpecProtocol
 {
     /** @psalm-var list<string> */
     private array $lLicenseIdentifiers;

diff --git a/src/Core/Spec/Spec.php → src/Core/Spec/_SpecProtocol.php b/src/Core/Spec/Spec.php → src/Core/Spec/_SpecProtocol.php
@@ -28,11 +28,17 @@
 use CycloneDX\Core\Enums\HashAlgorithm;
 
 /**
+ * This interface is not intended to be public API.
+ *
  * See {@see \CycloneDX\Core\Spec\SpecFactory Specification Factory} to get prepared instances.
  *
+ * @internal as this interface  may be affected by breaking changes without notice
+ *
+ * @SuppressWarnings(PHPMD.CamelCaseClassName)
+ *
  * @author jkowalleck
  */
-interface Spec
+interface _SpecProtocol
 {
     public function getVersion(): Version;
 

diff --git a/src/Core/Validation/BaseValidator.php b/src/Core/Validation/BaseValidator.php
@@ -23,7 +23,7 @@
 
 namespace CycloneDX\Core\Validation;
 
-use CycloneDX\Core\Spec\Spec;
+use CycloneDX\Core\Spec\_SpecProtocol as Spec;
 
 /**
  * @author jkowalleck

diff --git a/tests/Core/Serialization/DOM/NormalizerFactoryTest.php b/tests/Core/Serialization/DOM/NormalizerFactoryTest.php
@@ -26,7 +26,7 @@
 use CycloneDX\Core\Serialization\DOM\_BaseNormalizer;
 use CycloneDX\Core\Serialization\DOM\NormalizerFactory;
 use CycloneDX\Core\Serialization\DOM\Normalizers;
-use CycloneDX\Core\Spec\Spec;
+use CycloneDX\Core\Spec\_SpecProtocol;
 use CycloneDX\Core\Spec\Version;
 use DomainException;
 use DOMDocument;
@@ -57,7 +57,7 @@ class NormalizerFactoryTest extends TestCase
     public function testConstructor(): NormalizerFactory
     {
         $spec = $this->createConfiguredMock(
-            Spec::class,
+            _SpecProtocol::class,
             [
                 'isSupportedFormat' => true,
             ]
@@ -73,7 +73,7 @@ public function testConstructor(): NormalizerFactory
     public function testConstructThrowsWhenUnsupported(): void
     {
         $spec = $this->createConfiguredMock(
-            Spec::class,
+            _SpecProtocol::class,
             [
                 'getVersion' => Version::v1dot4,
                 'isSupportedFormat' => false,

diff --git a/tests/Core/Serialization/DOM/Normalizers/BomNormalizerTest.php b/tests/Core/Serialization/DOM/Normalizers/BomNormalizerTest.php
@@ -34,7 +34,7 @@
 use CycloneDX\Core\Serialization\DOM\_BaseNormalizer;
 use CycloneDX\Core\Serialization\DOM\NormalizerFactory;
 use CycloneDX\Core\Serialization\DOM\Normalizers;
-use CycloneDX\Core\Spec\Spec;
+use CycloneDX\Core\Spec\_SpecProtocol;
 use CycloneDX\Core\Spec\Version;
 use CycloneDX\Tests\_traits\DomNodeAssertionTrait;
 use DOMDocument;
@@ -53,7 +53,7 @@ class BomNormalizerTest extends TestCase
 
     public function testNormalize(): void
     {
-        $spec = $this->createConfiguredMock(Spec::class, ['getVersion' => Version::v1dot2]);
+        $spec = $this->createConfiguredMock(_SpecProtocol::class, ['getVersion' => Version::v1dot2]);
         $factory = $this->createConfiguredMock(
             NormalizerFactory::class,
             [
@@ -82,7 +82,7 @@ public function testNormalize(): void
 
     public function testNormalizeComponents(): void
     {
-        $spec = $this->createConfiguredMock(Spec::class, ['getVersion' => Version::v1dot2]);
+        $spec = $this->createConfiguredMock(_SpecProtocol::class, ['getVersion' => Version::v1dot2]);
         $componentsNormalizer = $this->createMock(Normalizers\ComponentRepositoryNormalizer::class);
         $factory = $this->createConfiguredMock(
             NormalizerFactory::class,
@@ -121,7 +121,7 @@ public function testNormalizeComponents(): void
     public function testNormalizeMetadata(): void
     {
         $spec = $this->createConfiguredMock(
-            Spec::class,
+            _SpecProtocol::class,
             [
                 'getVersion' => Version::v1dot2,
                 'supportsMetadata' => true,
@@ -164,7 +164,7 @@ public function testNormalizeMetadata(): void
     public function testNormalizeMetadataNotSupported(): void
     {
         $spec = $this->createConfiguredMock(
-            Spec::class,
+            _SpecProtocol::class,
             [
                 'getVersion' => Version::v1dot2,
                 'supportsMetadata' => false,
@@ -209,7 +209,7 @@ public function testNormalizeMetadataNotSupported(): void
     public function testNormalizeDependencies(): void
     {
         $spec = $this->createConfiguredMock(
-            Spec::class,
+            _SpecProtocol::class,
             [
                 'getVersion' => Version::v1dot2,
                 'supportsDependencies' => true,
@@ -252,7 +252,7 @@ public function testNormalizeDependencies(): void
     public function testNormalizeDependenciesOmitWhenEmpty(): void
     {
         $spec = $this->createConfiguredMock(
-            Spec::class,
+            _SpecProtocol::class,
             [
                 'getVersion' => Version::v1dot2,
                 'supportsDependencies' => true,
@@ -298,7 +298,7 @@ public function testNormalizeDependenciesOmitWhenEmpty(): void
 
     public function testNormalizeExternalReferencesMergedIfUnsupportedMetadata(): void
     {
-        $spec = $this->createConfiguredMock(Spec::class, [
+        $spec = $this->createConfiguredMock(_SpecProtocol::class, [
             'getVersion' => Version::v1dot2,
             'supportsMetadata' => false,
         ]);
@@ -351,7 +351,7 @@ public function testNormalizeExternalReferencesMergedIfUnsupportedMetadata(): vo
 
     public function testNormalizeExternalReferencesOmittedWHenEmpty(): void
     {
-        $spec = $this->createConfiguredMock(Spec::class, [
+        $spec = $this->createConfiguredMock(_SpecProtocol::class, [
             'getVersion' => Version::v1dot2,
             'supportsMetadata' => false,
         ]);
@@ -400,7 +400,7 @@ public function testNormalizeProperties(): void
                 'getProperties' => $this->createConfiguredMock(PropertyRepository::class, ['count' => 2]),
             ]
         );
-        $spec = $this->createConfiguredMock(Spec::class, [
+        $spec = $this->createConfiguredMock(_SpecProtocol::class, [
             'getVersion' => Version::v1dot4,
             'supportsBomProperties' => true,
         ]);
@@ -439,7 +439,7 @@ public function testNormalizePropertiesOmitEmpty(): void
                 'getProperties' => $this->createConfiguredMock(PropertyRepository::class, ['count' => 0]),
             ]
         );
-        $spec = $this->createConfiguredMock(Spec::class, [
+        $spec = $this->createConfiguredMock(_SpecProtocol::class, [
             'getVersion' => Version::v1dot4,
             'supportsBomProperties' => true,
         ]);

diff --git a/tests/Core/Serialization/DOM/Normalizers/ComponentEvidenceNormalizerTest.php b/tests/Core/Serialization/DOM/Normalizers/ComponentEvidenceNormalizerTest.php
@@ -31,7 +31,7 @@
 use CycloneDX\Core\Serialization\DOM\_BaseNormalizer;
 use CycloneDX\Core\Serialization\DOM\NormalizerFactory;
 use CycloneDX\Core\Serialization\DOM\Normalizers;
-use CycloneDX\Core\Spec\Spec;
+use CycloneDX\Core\Spec\_SpecProtocol;
 use CycloneDX\Tests\_traits\DomNodeAssertionTrait;
 use DOMDocument;
 use PHPUnit\Framework\Attributes\CoversClass;
@@ -54,7 +54,7 @@ public function testNormalizeMinimal(): void
                 'getCopyright' => $this->createMock(CopyrightRepository::class),
             ]
         );
-        $spec = $this->createMock(Spec::class);
+        $spec = $this->createMock(_SpecProtocol::class);
         $factory = $this->createConfiguredMock(
             NormalizerFactory::class,
             ['getSpec' => $spec, 'getDocument' => new DOMDocument()]
@@ -75,7 +75,7 @@ public function testNormalizeFull(): void
                 'getCopyright' => $this->createConfiguredMock(CopyrightRepository::class, ['count' => 1, 'getItems' => ['some copyright']]),
             ]
         );
-        $spec = $this->createMock(Spec::class);
+        $spec = $this->createMock(_SpecProtocol::class);
         $licenseRepoNormalizer = $this->createMock(Normalizers\LicenseRepositoryNormalizer::class);
         $factory = $this->createConfiguredMock(
             NormalizerFactory::class,