Updated README and applies PHPStan fixes

Author: dantleech

README.md

@@ -3,18 +3,24 @@ Path Finder
 
 [![Build Status](https://travis-ci.org/phpactor/path-finder.svg?branch=master)](https://travis-ci.org/phpactor/path-finder)
 
-Library to infer paths from a given path where paths share the same "kernel"
-(common section of the path).
+Library to infer paths from a given path where paths share path segments.
 
-For example, infer unit test path from the source file, from a unit test to
-a bechmark, from the benchmark to the source file etc.
+For example, infer test paths for a given source file and vice-versa.
 
 Usage
 -----
 
 Path finder accepts a hash map of destinations and their schemas. The
-"kernel" is a place holder for the common path segment that all destinations
-share:
+placeholders can be used to identify common parts of the path.
+
+- The last placeholder is _greedy_ it will match all path segments until the
+  suffix.
+- Preceding placeholders will only match until the first path separator.
+
+Examples
+--------
+
+### Navigating between test files
 
 ```php
 $pathFinder = PathFinder::fromDestinations([
@@ -25,9 +31,25 @@ $pathFinder = PathFinder::fromDestinations([
 
 $targets = $pathFinder->targetsFor('lib/Acme/Post.php');
 
-var_dump($targets);
 // [
 //    'unit_test' => 'tests/Unit/Acme/PostTest.php',
 //    'benchmark' => 'benchmarks/Acme/PostBench.php',
 // ]
 ```
+
+### Navigating between files organized by domain/module
+
+```php
+$pathFinder = PathFinder::fromDestinations([
+    'source' => 'lib/<module>/<kernel>.php',
+    'unit_test' => 'tests/<module>Unit/<kernel>Test.php',
+    'benchmark' => 'benchmarks/<module>/<kernel>Bench.php',
+]);
+
+$targets = $pathFinder->targetsFor('lib/MyModule/Acme/Post.php');
+
+// [
+//    'unit_test' => 'tests/MyModule/Unit/Acme/PostTest.php',
+//    'benchmark' => 'benchmarks/MyMOdule/Acme/PostBench.php',
+// ]
+```

lib/PathFinder.php

@@ -12,23 +12,30 @@ class PathFinder
      */
     private $destinations = [];
 
+    /**
+     * @param array<string, Pattern> $destinations
+     */
     private function __construct(array $destinations)
     {
-        foreach ($destinations as $destinationName => $pattern) {
-            $this->add($destinationName, $pattern);
-        }
+        $this->destinations = $destinations;
     }
 
+    /**
+     * @param array<string, string> $destinations
+     */
     public static function fromDestinations(array $destinations): PathFinder
     {
-        return new self($destinations);
+        return new self(array_map(function (string $pattern) {
+            return Pattern::fromPattern($pattern);
+        }, $destinations));
     }
 
     /**
      * Return a hash map of destination names to paths representing
      * paths which relate to the given file path.
      *
      * @throws NoMatchingSourceException
+     * @return array<string,string>
      */
     public function destinationsFor(string $filePath): array
     {
@@ -48,11 +55,6 @@ public function destinationsFor(string $filePath): array
         return $destinations;
     }
 
-    private function add($destinationName, $pattern): void
-    {
-        $this->destinations[$destinationName] = Pattern::fromPattern($pattern);
-    }
-
     private function findSourcePattern(string $filePath): Pattern
     {
         foreach ($this->destinations as $name => $pattern) {

lib/Pattern.php

@@ -16,7 +16,7 @@ class Pattern
     private $regex;
 
     /**
-     * @var array
+     * @var array<string>
      */
     private $tokenNames;
 
@@ -25,6 +25,9 @@ class Pattern
      */
     private $pattern;
 
+    /**
+     * @param array<string> $tokenNames
+     */
     public function __construct(string $regex, string $pattern, array $tokenNames)
     {
         $this->regex = $regex;
@@ -59,16 +62,30 @@ public function fits(string $filePath): bool
         return (bool)preg_match($this->regex, Path::canonicalize($filePath));
     }
 
+    /**
+     * @return array<string, string>
+     */
     public function tokens(string $filePath): array
     {
         $filePath = Path::canonicalize($filePath);
-        preg_match($this->regex, $filePath, $matches);
-        return array_intersect_key($matches, array_combine($this->tokenNames, $this->tokenNames));
+
+        if (!preg_match($this->regex, $filePath, $matches)) {
+            throw new RuntimeException(sprintf(
+                'Error occurred performing regex on filepath "%s" with regex "%s"',
+                $filePath,
+                $this->regex
+            ));
+        }
+
+        return array_intersect_key($matches, (array)array_combine($this->tokenNames, $this->tokenNames));
     }
 
+    /**
+     * @param array<string,string> $tokens
+     */
     public function replaceTokens(array $tokens): string
     {
-        return strtr($this->pattern, array_combine(array_map(function (string $key) {
+        return strtr($this->pattern, (array)array_combine(array_map(function (string $key) {
             return '<' . $key . '>';
         }, array_keys($tokens)), array_values($tokens)));
     }

phpstan.neon

@@ -1,7 +1,5 @@
-includes:
-    - vendor/phpstan/phpstan/conf/config.level7.neon
-
 parameters:
+    level: 7
     inferPrivatePropertyTypeFromConstructor: true
     ignoreErrors:
 

tests/Unit/PathFinderTest.php

@@ -6,7 +6,6 @@
 use Phpactor\ClassFileConverter\Exception\NoPlaceHoldersException;
 use Phpactor\ClassFileConverter\PathFinder;
 use Phpactor\ClassFileConverter\Exception\NoMatchingSourceException;
-use RuntimeException;
 
 class PathFinderTest extends TestCase
 {