Merge pull request #9 from cspray/task/remove-initializer

Remove Initializer, rename get/set methods

Author: cspray

.github/workflows/testing.yml

@@ -2,9 +2,9 @@ name: 'Unit Tests & Static Analysis'
 
 on:
   push:
-    branches: [ main ]
+    branches: [ release-1.x, release-2.x ]
   pull_request:
-    branches: [ main ]
+    branches: [ release-1.x, release-2.x ]
 
 jobs:
   continuous-integration:

.gitignore

@@ -1,3 +1,4 @@
 .phpunit.cache
 .phpunit.result.cache
+architectural-decisions.xml.bak
 vendor/

README.md

@@ -39,18 +39,19 @@ namespace Acme\ArchitecturalDecisions;
 use Cspray\ArchitecturalDecision\DecisionStatus;
 use Cspray\ArchitecturalDecision\DocBlockArchitecturalDecision;
 use Attribute;
+use DateTimeImmutable;
 
 /**
  * Explain the decision and its potential business impact. 
  */
 #[Attribute]
 final class MyFirstDecision extends DocBlockArchitecturalDecision {
 
-    public function getDate() : string {
-        return '2022-07-19';
+    public function date() : DateTimeImmutable {
+        return new DateTimeImmutable('2022-07-19');
     }
 
-    public function getStatus() : string|DecisionStatus {
+    public function status() : string|DecisionStatus {
         return DecisionStatus::Draft;
     }
 
@@ -67,7 +68,7 @@ If successful a file named `architectural-decisions.xml` will be generated and s
 
 ### Setting Custom Meta Data
 
-There might be additional information you'd like to include with an ArchitecturalDecisionRecord that doesn't fit into the contents of the decision. Perhaps it is additional data that can be used with static analysis. Perhaps you like to include information about who authored the decision or some other meta-data. You can implement the `ArchitecturalDecisionRecord::setMetaData(DOMElement $meta)` method to add whatever data you'd like to the generated XML document. Please review the [DOMDocument]() documentation for how to appropriately add elements and attribute to the `<meta>` element.
+There might be additional information you'd like to include with an ArchitecturalDecisionRecord that doesn't fit into the contents of the decision. Perhaps it is additional data that can be used with static analysis. Perhaps you like to include information about who authored the decision or some other meta-data. You can implement the `ArchitecturalDecisionRecord::setMetaData(DOMElement $meta)` method to add whatever data you'd like to the generated XML document. Please review the [DOMDocument](https://www.php.net/domdocument) documentation for how to appropriately add elements and attribute to the `<meta>` element.
 
 ## Example XML Document
 

bin/architectural-decisions

@@ -3,7 +3,6 @@
 
 use Cspray\AnnotatedTarget\PhpParserAnnotatedTargetParser;
 use Cspray\ArchitecturalDecision\ArchitecturalDecisionAttributeGatherer;
-use Cspray\ArchitecturalDecision\Initializer;
 use Cspray\ArchitecturalDecision\SourceArchitecturalDecisionAttributeRegistry;
 use Cspray\ArchitecturalDecision\XmlDocumentGenerator;
 
@@ -35,25 +34,13 @@ foreach (new RecursiveIteratorIterator(new RecursiveArrayIterator($composerDirs)
     $paths[] = $rootDir . '/' . $composerDir;
 }
 
-$initializers = $composer['extra']['$architecturalDecision']['initializers'] ?? [];
+$additionalScanPaths = $composer['extra']['$architecturalDecision']['additionalScanPaths'] ?? [];
 
-foreach ($initializers as $initializerClass) {
-    $initializerClass = (string) $initializerClass;
-    if (!class_exists($initializerClass)) {
-        echo 'Your configured initializer ' . $initializerClass . ' is not an autoloadable class.';
-        exit(255);
-    }
-
-    if (!is_subclass_of($initializerClass, Initializer::class)) {
-        echo 'Your configured initializer ' . $initializerClass . ' MUST extend ' . Initializer::class;
-        exit(255);
-    }
-
-    $initializer = new $initializerClass();
-    $paths = [...$paths, ...$initializer->getAdditionalScanPaths()];
+foreach ($additionalScanPaths as $additionalScanPath) {
+    $paths[] = $rootDir . '/' . $additionalScanPath;
 }
 
-$attributes = (new SourceArchitecturalDecisionAttributeRegistry($paths))->getArchitecturalDecisionAttributes();
+$attributes = (new SourceArchitecturalDecisionAttributeRegistry($paths))->architecturalDecisionAttributes();
 if (count($attributes) === 0) {
     echo 'You must implement an ArchitecturalDecisionRecord in your codebase before running this command!';
     exit(255);

src/ArchitecturalDecisionAttributeGatherer.php

@@ -21,7 +21,7 @@ public function __construct(private readonly AnnotatedTargetParser $annotatedTar
     /**
      * @return list<ObjectType>
      */
-    public function getRegisteredAttributes() : array {
+    public function registeredAttributes() : array {
         return $this->attributeTypes;
     }
 

src/ArchitecturalDecisionAttributeRegistry.php

@@ -9,6 +9,6 @@ interface ArchitecturalDecisionAttributeRegistry {
     /**
      * @return list<ObjectType>
      */
-    public function getArchitecturalDecisionAttributes() : array;
+    public function architecturalDecisionAttributes() : array;
 
 }

src/ArchitecturalDecisionRecord.php

@@ -5,6 +5,7 @@
 use Cspray\ArchitecturalDecision\ArchitecturalDecisionRecords\ExplicitArchitecturalDecisionStatus;
 use Cspray\ArchitecturalDecision\ArchitecturalDecisionRecords\PreferCustomArchitecturalDecisionOverGeneric;
 use Cspray\ArchitecturalDecision\ArchitecturalDecisionRecords\UsingAttributesForArchitecturalDecisions;
+use DateTimeImmutable;
 use DOMElement;
 
 #[ExplicitArchitecturalDecisionStatus]
@@ -14,14 +15,14 @@ interface ArchitecturalDecisionRecord {
 
     const SCHEMA = 'https://architectural-decision.cspray.io/schema/architectural-decision.xsd';
 
-    public function getId() : string;
+    public function id() : string;
 
-    public function getDate() : string;
+    public function date() : DateTimeImmutable;
 
-    public function getStatus() : string|DecisionStatus;
+    public function status() : string|DecisionStatus;
 
-    public function getContents() : string;
+    public function contents() : string;
 
-    public function setMetaData(DOMElement $meta) : void;
+    public function addMetaData(DOMElement $meta) : void;
 
 }

src/ArchitecturalDecisionRecords/ExplicitArchitecturalDecisionStatus.php

@@ -5,6 +5,8 @@
 use Attribute;
 use Cspray\ArchitecturalDecision\DecisionStatus;
 use Cspray\ArchitecturalDecision\DocBlockArchitecturalDecision;
+use DateTimeImmutable;
+use DateTimeZone;
 
 /**
  * # Explicit Architectural Decision Status
@@ -37,11 +39,11 @@
 #[Attribute(Attribute::TARGET_CLASS)]
 final class ExplicitArchitecturalDecisionStatus extends DocBlockArchitecturalDecision {
 
-    public function getDate() : string {
-        return '2022-07-19';
+    public function date() : DateTimeImmutable {
+        return new DateTimeImmutable('2022-07-19', new DateTimeZone('America/New_York'));
     }
 
-    public function getStatus() : DecisionStatus {
+    public function status() : DecisionStatus {
         return DecisionStatus::Accepted;
     }
 }

src/ArchitecturalDecisionRecords/PreferCustomArchitecturalDecisionOverGeneric.php

@@ -5,6 +5,7 @@
 use Attribute;
 use Cspray\ArchitecturalDecision\DecisionStatus;
 use Cspray\ArchitecturalDecision\DocBlockArchitecturalDecision;
+use DateTimeImmutable;
 
 /**
  * # Prefer Custom ArchitecturalDecisionRecord Over Generic
@@ -85,11 +86,11 @@
 #[Attribute(Attribute::TARGET_CLASS)]
 final class PreferCustomArchitecturalDecisionOverGeneric extends DocBlockArchitecturalDecision {
 
-    public function getDate() : string {
-        return '2022-07-19';
+    public function date() : DateTimeImmutable {
+        return new DateTimeImmutable('2022-07-19', new \DateTimeZone('America/New_York'));
     }
 
-    public function getStatus() : DecisionStatus {
+    public function status() : DecisionStatus {
         return DecisionStatus::Accepted;
     }
 }

src/ArchitecturalDecisionRecords/UsingAttributesForArchitecturalDecisions.php

@@ -5,6 +5,7 @@
 use Attribute;
 use Cspray\ArchitecturalDecision\DecisionStatus;
 use Cspray\ArchitecturalDecision\DocBlockArchitecturalDecision;
+use DateTimeImmutable;
 
 /**
  * # Use Attributes for Architectural Decisions
@@ -15,11 +16,11 @@
  */
 #[Attribute(Attribute::TARGET_ALL)]
 final class UsingAttributesForArchitecturalDecisions extends DocBlockArchitecturalDecision {
-    public function getDate() : string {
-        return '2022-07-19';
+    public function date() : DateTimeImmutable {
+        return new DateTimeImmutable('2022-07-19', new \DateTimeZone('America/New_York'));
     }
 
-    public function getStatus() : DecisionStatus {
+    public function status() : DecisionStatus {
         return DecisionStatus::Accepted;
     }
 }

src/DocBlockArchitecturalDecision.php

@@ -9,12 +9,12 @@ abstract class DocBlockArchitecturalDecision implements ArchitecturalDecisionRec
 
     private ?string $contents = null;
 
-    public function getId() : string {
+    public function id() : string {
         $parts = explode('\\', static::class);
         return array_pop($parts);
     }
 
-    final public function getContents() : string {
+    final public function contents() : string {
         if (!isset($this->contents)) {
             $reflection = new \ReflectionClass(static::class);
             $content = $reflection->getDocComment();
@@ -37,7 +37,7 @@ final public function getContents() : string {
         return $this->contents;
     }
 
-    public function setMetaData(DOMElement $meta) : void {
+    public function addMetaData(DOMElement $meta) : void {
         // noop, override to set your custom meta data
     }
 }

src/Initializer.php

@@ -26,7 +26,7 @@ public function __construct(
         $this->parser = (new ParserFactory())->createForNewestSupportedVersion();
     }
 
-    public function getArchitecturalDecisionAttributes() : array {
+    public function architecturalDecisionAttributes() : array {
         $gatherer = new class extends NodeVisitorAbstract {
 
             /**

src/SourceArchitecturalDecisionAttributeRegistry.php

@@ -25,7 +25,7 @@ public function generateDocument(string $file, array $scanDirs) : void {
         /** @var array<class-string, array{attribute: ArchitecturalDecisionRecord, targets: list<AnnotatedTarget>}> $decisionAnnotations */
         $decisionAnnotations = [];
 
-        foreach ($this->gatherer->getRegisteredAttributes() as $attributeType) {
+        foreach ($this->gatherer->registeredAttributes() as $attributeType) {
             /** @psalm-var class-string $type */
             $type = $attributeType->getName();
             $decisionAnnotations[$type] = [
@@ -55,14 +55,14 @@ public function generateDocument(string $file, array $scanDirs) : void {
                 $decisionElement = $dom->createElementNS(ArchitecturalDecisionRecord::SCHEMA, 'architecturalDecision')
             );
 
-            $decisionElement->setAttribute('id', $attribute->getId());
+            $decisionElement->setAttribute('id', $attribute->id());
             $decisionElement->setAttribute('attribute', $attribute::class);
 
             $decisionElement->appendChild(
-                $dom->createElementNS(ArchitecturalDecisionRecord::SCHEMA, 'date', $attribute->getDate())
+                $dom->createElementNS(ArchitecturalDecisionRecord::SCHEMA, 'date', $attribute->date()->format('Y-m-d'))
             );
 
-            $status = $attribute->getStatus();
+            $status = $attribute->status();
             if ($status instanceof DecisionStatus) {
                 $status = $status->value;
             }
@@ -75,7 +75,7 @@ public function generateDocument(string $file, array $scanDirs) : void {
             );
 
             $contentsNode->appendChild(
-                $contentsNode->ownerDocument->createCDATASection($attribute->getContents())
+                $contentsNode->ownerDocument->createCDATASection($attribute->contents())
             );
 
             if ($decisionAnnotation['targets'] !== []) {
@@ -158,7 +158,7 @@ public function generateDocument(string $file, array $scanDirs) : void {
                 $meta = $dom->createElementNS(ArchitecturalDecisionRecord::SCHEMA, 'meta')
             );
 
-            $attribute->setMetaData($meta);
+            $attribute->addMetaData($meta);
         }
 
         $dom->schemaValidate(dirname(__DIR__) . '/architectural-decision.xsd');

src/XmlDocumentGenerator.php

@@ -24,13 +24,13 @@ public function testGetContentsReturnsDocBlock() : void {
 displayed in the CLI tool explaining the reason for the Architectural Decision.
 DOC;
 
-        self::assertSame($expected, $subject->getContents());
+        self::assertSame($expected, $subject->contents());
     }
 
     public function testGetTitleReturnsConstructorArgument() : void {
         $subject = new StubDocBlockArchitecturalDecision();
 
-        self::assertSame('stub-attr-id', $subject->getId());
+        self::assertSame('stub-attr-id', $subject->id());
     }
 
     public function testGetContentsMissingDocBlockThrowsException() : void {
@@ -39,7 +39,7 @@ public function testGetContentsMissingDocBlockThrowsException() : void {
         self::expectException(MissingDocBlock::class);
         self::expectExceptionMessage('Expected to find a DocBlock associated with ' . MissingDocBlockArchitecturalDecision::class);
 
-        $subject->getContents();
+        $subject->contents();
     }
 
 }

tests/DocBlockArchitecturalDecisionTest.php

@@ -18,7 +18,7 @@ final class SourceArchitecturalDecisionAttributeRegistryTest extends TestCase {
     public function testSourceDirectoryContainsAttributes() : void {
         $subject = new SourceArchitecturalDecisionAttributeRegistry([__DIR__]);
 
-        $attributes = $subject->getArchitecturalDecisionAttributes();
+        $attributes = $subject->architecturalDecisionAttributes();
 
         self::assertCount(4, $attributes);
 

tests/SourceArchitecturalDecisionAttributeRegistryTest.php

@@ -4,22 +4,23 @@
 
 use Attribute;
 use Cspray\ArchitecturalDecision\DocBlockArchitecturalDecision;
+use DateTimeImmutable;
 
 /**
  * Another doc block.
  */
 #[Attribute(Attribute::TARGET_ALL)]
 final class AnotherDocBlockArchitecturalDecision extends DocBlockArchitecturalDecision {
 
-    public function getId() : string {
+    public function id() : string {
         return 'Another DocBlock';
     }
 
-    public function getDate() : string {
-        return '1984-01-01';
+    public function date() : DateTimeImmutable {
+        return new DateTimeImmutable('1984-01-01', new \DateTimeZone('America/New_York'));
     }
 
-    public function getStatus() : string {
+    public function status() : string {
         return 'Draft';
     }
 }

tests/Stub/Adr/AnotherDocBlockArchitecturalDecision.php

@@ -15,15 +15,15 @@
 #[Attribute(Attribute::TARGET_ALL)]
 final class StubDocBlockArchitecturalDecision extends DocBlockArchitecturalDecision {
 
-    public function getId() : string {
+    public function id() : string {
         return 'stub-attr-id';
     }
 
-    public function getDate() : string {
-        return '2022-01-01';
+    public function date() : \DateTimeImmutable {
+        return new \DateTimeImmutable('2022-01-01', new \DateTimeZone('America/New_York'));
     }
 
-    public function getStatus() : DecisionStatus {
+    public function status() : DecisionStatus {
         return DecisionStatus::Accepted;
     }
 }