Merge pull request #70 from yoeunes/dev

Introduces advanced regex analysis, tolerant parsing, and PSR caching

Author: yoeunes

README.md

@@ -173,9 +173,18 @@ use RegexParser\Regex;
 $analysis = Regex::create()->analyzeReDoS('/(a+)+b/');
 echo $analysis->severity->value; // critical/high/...
 echo $analysis->score; // 0-10
+$isOkForRoutes = !$analysis->exceedsThreshold(\RegexParser\ReDoS\ReDoSSeverity::HIGH);
+$isOkForUserInput = !$analysis->exceedsThreshold(\RegexParser\ReDoS\ReDoSSeverity::LOW);
+
+// IDE-friendly tolerant parsing: returns partial AST + errors list instead of throwing.
+$result = Regex::create()->parseTolerant('/(a+/');
+var_dump($result->hasErrors()); // true
+echo $result->errors[0]->getMessage(); // e.g. "Unclosed group"
 ```
 
-Severity levels: SAFE, LOW, MEDIUM, HIGH, CRITICAL (2^n worst cases).
+Severity levels: SAFE, LOW, MEDIUM, UNKNOWN, HIGH, CRITICAL (2^n worst cases; UNKNOWN means analysis could not complete safely).
+
+Limitations: heuristic/static only; quantified alternations with complex character classes may still warn conservatively, and deeply recursive backreference/subroutine patterns can evade detection. Treat `UNKNOWN` as a signal to fail closed.
 
 ---
 
@@ -208,6 +217,22 @@ $regex = Regex::create(['cache' => __DIR__ . '/var/cache/regex']);
 $ast = $regex->parse('/[A-Z][a-z]+/');
 ```
 
+Or plug your app cache (PSR-6/16) for shared keys:
+
+```php
+use RegexParser\Regex;
+use RegexParser\Cache\PsrCacheAdapter;
+use RegexParser\Cache\PsrSimpleCacheAdapter;
+
+// PSR-6 (CacheItemPoolInterface)
+$cache = new PsrCacheAdapter($yourPool, prefix: 'route_login_');
+$regex = Regex::create(['cache' => $cache]);
+
+// PSR-16 (SimpleCache)
+$cache = new PsrSimpleCacheAdapter($yourSimpleCache, prefix: 'constraint_user_email_');
+$regex = Regex::create(['cache' => $cache]);
+```
+
 Pass a writable directory string to `Regex::create(['cache' => '/path'])` or a custom `CacheInterface` implementation. Use `null` (default) to disable.
 
 ---

bin/regex-analyze

@@ -0,0 +1,51 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the RegexParser package.
+ *
+ * (c) Younes ENNAJI <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require __DIR__.'/../vendor/autoload.php';
+
+use RegexParser\Exception\LexerException;
+use RegexParser\Exception\ParserException;
+use RegexParser\Regex;
+
+if ($argc < 2) {
+    fwrite(STDERR, "Usage: regex-analyze '/pattern/flags'\n");
+    exit(1);
+}
+
+$pattern = $argv[1];
+$regex = Regex::create();
+
+try {
+    $ast = $regex->parse($pattern);
+    $validation = $regex->validate($pattern);
+    $analysis = $regex->analyzeReDoS($pattern);
+    $explain = $regex->explain($pattern);
+
+    echo "Pattern: {$pattern}\n";
+    echo "Parse: OK\n";
+    echo "Validation: ".($validation->isValid ? 'OK' : 'INVALID')."\n";
+    if (!$validation->isValid && null !== $validation->error) {
+        echo "Error: {$validation->error}\n";
+    }
+    echo "ReDoS severity: {$analysis->severity->value}\n";
+    echo "ReDoS score: {$analysis->score}\n";
+    if ($analysis->error) {
+        echo "ReDoS error: {$analysis->error}\n";
+    }
+    echo "\nExplanation:\n";
+    echo $explain."\n";
+} catch (LexerException|ParserException $e) {
+    fwrite(STDERR, "Error: {$e->getMessage()}\n");
+    exit(1);
+}

composer.json

@@ -23,7 +23,9 @@
         "symfony/config": "^8.0",
         "symfony/http-foundation": "^8.0",
         "symfony/routing": "^8.0",
-        "symfony/validator": "^8.0"
+        "symfony/validator": "^8.0",
+        "psr/cache": "^3.0",
+        "psr/simple-cache": "^3.0"
     },
     "autoload": {
         "psr-4": {
@@ -48,6 +50,8 @@
         }
     },
     "suggest": {
+        "psr/cache": "To share AST cache via PSR-6 pools.",
+        "psr/simple-cache": "To share AST cache via PSR-16 caches.",
         "phpstan/phpstan": "To run static analysis and detect invalid regex patterns.",
         "phpstan/extension-installer": "To automatically enable the PHPStan rule for regex validation.",
         "rector/rector": "To automatically refactor and optimize regex patterns."

phpstan.dist.neon

@@ -10,6 +10,9 @@ parameters:
 
     treatPhpDocTypesAsCertain: false
 
+    regexParser:
+        redosThreshold: critical
+
     paths:
         - bin
         - config

rector/Rule/PHPUnit/PreferStaticPHPUnitAssertRector.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the RegexParser package.
+ *
+ * (c) Younes ENNAJI <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace RegexParser\Rector\Rule\PHPUnit;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\MethodCall;
+use PhpParser\Node\Expr\StaticCall;
+use PHPUnit\Framework\Assert;
+use Rector\PHPUnit\CodeQuality\NodeAnalyser\AssertMethodAnalyzer;
+use Rector\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+/**
+ * Converts PHPUnit assertions from $this->assert*() and static::assert*() to explicit Assert::assert*() static calls.
+ */
+class PreferStaticPHPUnitAssertRector extends AbstractRector
+{
+    public function __construct(private AssertMethodAnalyzer $assertMethodAnalyzer) {}
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition(
+            'Changes PHPUnit assertion calls from $this->assert*() or static::assert*() to explicit Assert::assert*() static calls.',
+            [
+                new CodeSample(
+                    <<<'CODE_SAMPLE'
+                        use PHPUnit\Framework\TestCase;
+
+                        final class SomeTest extends TestCase {
+                            public function testSomething() {
+                                $this->assertEquals(1, 2);
+                                static::assertSame('foo', 'bar');
+                            }
+                        }
+                        CODE_SAMPLE,
+                    <<<'CODE_SAMPLE'
+                        use PHPUnit\Framework\TestCase;
+                        use PHPUnit\Framework\Assert;
+
+                        final class SomeTest extends TestCase {
+                            public function testSomething() {
+                                Assert::assertEquals(1, 2);
+                                Assert::assertSame('foo', 'bar');
+                            }
+                        }
+                        CODE_SAMPLE
+                ),
+            ],
+        );
+    }
+
+    public function getNodeTypes(): array
+    {
+        return [MethodCall::class, StaticCall::class];
+    }
+
+    /**
+     * @param MethodCall|StaticCall $node
+     */
+    public function refactor(Node $node): ?Node
+    {
+        if ($node->isFirstClassCallable()) {
+            return null;
+        }
+
+        if ($node instanceof MethodCall && !$this->assertMethodAnalyzer->detectTestCaseCallForStatic($node)) {
+            return null;
+        }
+
+        if ($node instanceof StaticCall && !$this->assertMethodAnalyzer->detectTestCaseCall($node)) {
+            return null;
+        }
+
+        $methodName = $this->getName($node->name);
+        if (null === $methodName || !str_starts_with($methodName, 'assert')) {
+            return null;
+        }
+
+        return $this->nodeFactory->createStaticCall(
+            Assert::class,
+            $methodName,
+            $node->getArgs(),
+        );
+    }
+}

src/Bridge/PHPStan/PregValidationRule.php

@@ -216,9 +216,10 @@ private function exceedsThreshold(ReDoSSeverity $severity): bool
         $currentLevel = match ($severity) {
             ReDoSSeverity::SAFE => 0,
             ReDoSSeverity::LOW => 1,
-            ReDoSSeverity::MEDIUM => 2,
-            ReDoSSeverity::HIGH => 3,
-            ReDoSSeverity::CRITICAL => 4,
+            ReDoSSeverity::UNKNOWN => 2,
+            ReDoSSeverity::MEDIUM => 3,
+            ReDoSSeverity::HIGH => 4,
+            ReDoSSeverity::CRITICAL => 5,
         };
 
         $thresholdLevel = match ($this->redosThreshold) {

src/Cache/FilesystemCache.php

@@ -22,6 +22,7 @@ public function __construct(string $directory, private string $extension = '.php
         $this->directory = rtrim($directory, '\\/');
     }
 
+    #[\Override]
     public function generateKey(string $regex): string
     {
         $hash = hash('sha256', $regex);
@@ -37,6 +38,7 @@ public function generateKey(string $regex): string
         );
     }
 
+    #[\Override]
     public function write(string $key, string $content): void
     {
         $directory = \dirname($key);
@@ -70,6 +72,7 @@ public function write(string $key, string $content): void
         }
     }
 
+    #[\Override]
     public function load(string $key): mixed
     {
         if (!is_file($key)) {
@@ -84,11 +87,13 @@ public function load(string $key): mixed
         }
     }
 
+    #[\Override]
     public function getTimestamp(string $key): int
     {
         return is_file($key) ? (int) filemtime($key) : 0;
     }
 
+    #[\Override]
     public function clear(?string $regex = null): void
     {
         if (null !== $regex) {

src/Cache/NullCache.php

@@ -13,24 +13,29 @@
 
 namespace RegexParser\Cache;
 
-class NullCache implements RemovableCacheInterface
+readonly class NullCache implements RemovableCacheInterface
 {
+    #[\Override]
     public function generateKey(string $regex): string
     {
         return hash('sha256', $regex);
     }
 
+    #[\Override]
     public function write(string $key, string $content): void {}
 
+    #[\Override]
     public function load(string $key): mixed
     {
         return null;
     }
 
+    #[\Override]
     public function getTimestamp(string $key): int
     {
         return 0;
     }
 
+    #[\Override]
     public function clear(?string $regex = null): void {}
 }

src/Cache/PsrCacheAdapter.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the RegexParser package.
+ *
+ * (c) Younes ENNAJI <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace RegexParser\Cache;
+
+use Psr\Cache\CacheItemPoolInterface;
+
+/**
+ * PSR-6 bridge for AST caching.
+ *
+ * Uses the configured pool to store serialized AST payloads.
+ */
+final readonly class PsrCacheAdapter implements RemovableCacheInterface
+{
+    public function __construct(
+        private CacheItemPoolInterface $pool,
+        private string $prefix = 'regex_',
+        private ?\Closure $keyFactory = null
+    ) {}
+
+    public function generateKey(string $regex): string
+    {
+        if (null !== $this->keyFactory) {
+            $custom = ($this->keyFactory)($regex);
+
+            return $this->prefix.(\is_string($custom) ? $custom : hash('sha256', serialize($custom)));
+        }
+
+        return $this->prefix.hash('sha256', $regex);
+    }
+
+    public function write(string $key, string $content): void
+    {
+        $item = $this->pool->getItem($key);
+        $item->set($content);
+        $this->pool->save($item);
+    }
+
+    public function load(string $key): mixed
+    {
+        $item = $this->pool->getItem($key);
+
+        return $item->isHit() ? $item->get() : null;
+    }
+
+    public function getTimestamp(string $key): int
+    {
+        // PSR-6 does not expose timestamps; return 0 (unknown).
+        return 0;
+    }
+
+    public function clear(?string $regex = null): void
+    {
+        if (null !== $regex) {
+            $this->pool->deleteItem($this->generateKey($regex));
+
+            return;
+        }
+
+        $this->pool->clear();
+    }
+}