Initial implementation

README.md

@@ -1,3 +1,42 @@
 # Dhii - Service tools
 
-A set of tools for working with service providers.
+A set of tools for working with service providers that use [`ServiceInterface`](service-interface).
+
+## Analysis
+
+This package provides a set of analyzers that can detect various kinds of service-related issues, such as:
+
+* Circular dependencies
+* Dependencies that don't resolve to known services
+* Extensions that don't extend a known service
+
+**Usage**:
+
+```
+$analyzer = new CircularDependencyAnalyzer();
+$issues = $analyzer->analyze($factories, $extensions);
+
+foreach ($issues as $issue) {
+    $severity = $issue->getSeverity();
+    $message = $issue->getMessage();
+
+    switch ($severity) {
+        case Issue::WARNING: /* do something */
+        case Issue::ERROR:   /* do something */
+    }
+}
+```
+
+All the analyzers implement an [`AnalyzerInterface`](analyzer-interface). Container implementations can choose to
+accept an analyzer instance during construction or setup using this interface, and then perform analysis on the
+finished state of the container, after all [`ServiceProviderInterface`](service-provider) instances have been accepted.
+
+Whether a container takes action on the reported issues or not is left up to the implementation. However, it is
+strongly recommended that implementations take action according to the severity of the reported issues:
+
+* `Issue::WARNING` - these issues should be reported to the developer; execution may resume.
+* `Issue::ERROR` - these issues represent a fatal error waiting to happen; execution should probably stop.
+
+[service-interface]: https://github.com/Dhii/services-interface
+[analyzer-interface]: https://github.com/Dhii/service-tools/blob/initial/src/AnalyzerInterface.php
+[service-provider]: https://github.com/container-interop/service-provider/blob/master/src/ServiceProviderInterface.php

composer.json

@@ -16,7 +16,9 @@
     }
   ],
   "require": {
-    "php": "^7.2 | ^8.0"
+    "php": "^7.2 | ^8.0",
+    "dhii/services-interface": "0.1.x-dev",
+    "container-interop/service-provider": "dev-master"
   },
   "require-dev": {
     "phpunit/phpunit": "^8.0 | ^9.0",
@@ -38,5 +40,9 @@
     "branch-alias": {
       "dev-initial": "0.1.x-dev"
     }
+  },
+  "scripts": {
+    "phpcs": "vendor/bin/phpcs -s --runtime-set ignore_warnings_on_exit 1",
+    "psalm": "vendor/bin/psalm --show-info=true --threads=8 --diff"
   }
 }

src/AnalyzerInterface.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhii\Services\Tools;
+
+use Dhii\Services\ServiceInterface;
+
+interface AnalyzerInterface
+{
+    /**
+     * Analyzes a set of factories and extensions.
+     *
+     * @param array<callable|ServiceInterface> $factories  The list of factories to analyze.
+     * @param array<callable|ServiceInterface> $extensions The list of extensions to analyze.
+     *
+     * @return iterable<Issue> A list of issues found during analysis.
+     */
+    public function analyze(array $factories, array $extensions): iterable;
+}

src/Analyzers/AggregateAnalyzer.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dhii\Services\Tools\Analyzers;
+
+use Dhii\Services\Tools\AnalyzerInterface;
+
+/**
+ * An analyzer implementation that aggregates issues from multiple other analyzers.
+ */
+class AggregateAnalyzer implements AnalyzerInterface
+{
+    /** @var AnalyzerInterface[] */
+    protected $analyzers;
+
+    /**
+     * Constructor.
+     *
+     * @param AnalyzerInterface[] $analyzers The analyzers to aggregate.
+     */
+    public function __construct(array $analyzers)
+    {
+        $this->analyzers = $analyzers;
+    }
+
+    /** @inheritDoc */
+    public function analyze(array $factories, array $extensions): iterable
+    {
+        foreach ($this->analyzers as $analyzer) {
+            yield from $analyzer->analyze($factories, $extensions);
+        }
+    }
+}