Improved usage detection across includes, extends and embeds.

README.md

@@ -48,7 +48,7 @@ Tips: You can use multiple _exclude_ parameters.
 
 By default TwigCS will output all lines that have violations regardless of whether they match the severity level
 specified or not. If you only want to see violations that are greater than or equal to the severity level you've specified
-you can use the `--display` option. For example. 
+you can use the `--display` option. For example.
 
 ```bash
 twigcs /path/to/views --severity error --display blocking
@@ -86,7 +86,7 @@ You can create a class implementing `RulesetInterface` and supply it as a `--rul
 twigcs /path/to/views --ruleset \MyApp\TwigCsRuleset
 ```
 
-*Note:* `twigcs` needs to be used via composer and the ruleset class must be reachable via composer's autoloader for this feature to work.
+_Note:_ `twigcs` needs to be used via composer and the ruleset class must be reachable via composer's autoloader for this feature to work.
 Also note that depending on your shell, you might need to escape backslashes in the fully qualified class name:
 
 ```bash
@@ -148,6 +148,43 @@ If you explicitly supply a path to the CLI, it will be added to the list of lint
 twigcs ~/dirC # This will lint ~/dirA, ~/dirB and ~/dirC using the configuration file of the current directory.
 ```
 
+## Template resolution
+
+Using file based configuration, you can provide a way for twigcs to resolve template. This enables better unused variable/macro detection. Here's the
+simplest example when you have only one directory of templates.
+
+```php
+<?php
+
+use FriendsOfTwig\Twigcs\TemplateResolver\FileResolver;
+
+return \FriendsOfTwig\Twigcs\Config\Config::create()
+    // ...
+    ->setTemplateResolver(new FileResolver(__DIR__))
+    ->setRuleSet(FriendsOfTwig\Twigcs\Ruleset\Official::class)
+;
+```
+
+Here is a more complex example that uses a chain resolver and a namespaced resolver to handle vendor templates:
+
+```
+<?php
+
+use FriendsOfTwig\Twigcs\TemplateResolver;
+
+return \FriendsOfTwig\Twigcs\Config\Config::create()
+    ->setFinder($finder)
+    ->setTemplateResolver(new TemplateResolver\ChainResolver([
+        new TemplateResolver\FileResolver(__DIR__ . '/templates'),
+        new TemplateResolver\NamespacedResolver([
+            'acme' =>  new TemplateResolver\FileResolver(__DIR__ . '/vendor/Acme/AcmeLib/templates')
+        ]),
+    ]))
+;
+```
+
+This handles twig namespaces of the form `@acme/<templatepath>`.
+
 ## Upgrading
 
 If you're upgrading from 3.x to 4.x or later, please read the [upgrade guide](doc/upgrade.md).

src/Config/Config.php

@@ -3,24 +3,28 @@
 namespace FriendsOfTwig\Twigcs\Config;
 
 use FriendsOfTwig\Twigcs\Ruleset\Official;
+use FriendsOfTwig\Twigcs\TemplateResolver\NullResolver;
+use FriendsOfTwig\Twigcs\TemplateResolver\TemplateResolverInterface;
 
 /**
  * Special thanks to https://github.com/c33s/twigcs/ which this feature was inspired from.
  */
 class Config implements ConfigInterface
 {
-    private $name;
-    private $finders;
-    private $severity = 'warning';
-    private $reporter = 'console';
-    private $ruleset = Official::class;
-    private $specificRulesets = [];
+    private string $name;
+    private array $finders;
+    private ?TemplateResolverInterface $loader;
+    private string $severity = 'warning';
+    private string $reporter = 'console';
+    private string $ruleset = Official::class;
+    private array $specificRulesets = [];
     private $display = ConfigInterface::DISPLAY_ALL;
 
-    public function __construct($name = 'default')
+    public function __construct(string $name = 'default')
     {
         $this->name = $name;
         $this->finders = [];
+        $this->loader = new NullResolver();
     }
 
     /**
@@ -136,6 +140,24 @@ public function setRuleset(string $ruleSet): self
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function getTemplateResolver(): TemplateResolverInterface
+    {
+        return $this->loader;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setTemplateResolver(TemplateResolverInterface $loader): self
+    {
+        $this->loader = $loader;
+
+        return $this;
+    }
+
     public function getSpecificRulesets(): array
     {
         return $this->specificRulesets;

src/Config/ConfigInterface.php

@@ -2,6 +2,8 @@
 
 namespace FriendsOfTwig\Twigcs\Config;
 
+use FriendsOfTwig\Twigcs\TemplateResolver\TemplateResolverInterface;
+
 /**
  * Special thanks to https://github.com/c33s/twigcs/ which this feature was inspired from.
  *
@@ -62,4 +64,11 @@ public function getSpecificRuleSets(): array;
      * @return self
      */
     public function setSpecificRuleSets(array $ruleSet);
+
+    public function getTemplateResolver(): TemplateResolverInterface;
+
+    /**
+     * @return self
+     */
+    public function setTemplateResolver(TemplateResolverInterface $loader);
 }

src/Config/ConfigResolver.php

@@ -5,6 +5,7 @@
 use FriendsOfTwig\Twigcs\Container;
 use FriendsOfTwig\Twigcs\Finder\TemplateFinder;
 use FriendsOfTwig\Twigcs\Ruleset\RulesetInterface;
+use FriendsOfTwig\Twigcs\Ruleset\TemplateResolverAwareInterface;
 use FriendsOfTwig\Twigcs\Validator\Violation;
 use Symfony\Component\Filesystem\Filesystem;
 use function fnmatch;
@@ -117,7 +118,13 @@ public function getRuleset(string $file)
             throw new \InvalidArgumentException('Ruleset class must implement '.RulesetInterface::class);
         }
 
-        return new $rulesetClassName($this->options['twig-version']);
+        $instance = new $rulesetClassName($this->options['twig-version']);
+
+        if ($instance instanceof TemplateResolverAwareInterface) {
+            $instance->setTemplateResolver($this->config->getTemplateResolver());
+        }
+
+        return $instance;
     }
 
     /**

src/Container.php

@@ -7,9 +7,9 @@
 use FriendsOfTwig\Twigcs\Reporter\CsvReporter;
 use FriendsOfTwig\Twigcs\Reporter\EmacsReporter;
 use FriendsOfTwig\Twigcs\Reporter\GithubActionReporter;
+use FriendsOfTwig\Twigcs\Reporter\JsonReporter;
 use FriendsOfTwig\Twigcs\Reporter\JUnitReporter;
 use FriendsOfTwig\Twigcs\Validator\Validator;
-use FriendsOfTwig\Twigcs\Reporter\JsonReporter;
 
 class Container extends \ArrayObject
 {

src/RegEngine/RulesetBuilder.php

@@ -287,7 +287,7 @@ public function build(): array
             ['<➀embed➊$➋ignore missing➌with➍&➎only➁>', $this
                 ->argTag()
                 ->delegate('$', 'expr')
-                ->delegate('&', 'hash')
+                ->delegate('&', 'with')
                 ->enforceSize('➊', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the source.')
                 ->enforceSize('➋', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the "ignore missing".')
                 ->enforceSize('➌', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the "with".')
@@ -309,15 +309,15 @@ public function build(): array
             ],
             ['<➀embed➊$➌with➍&➎only➁>', $this
                 ->argTag()
-                ->delegate('$', 'expr')->delegate('&', 'hash')
+                ->delegate('$', 'expr')->delegate('&', 'with')
                 ->enforceSize('➊', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the source.')
                 ->enforceSize('➌', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the "with".')
                 ->enforceSize('➍', $this->config['from']['before_source'], 'There should be %quantity% space(s) after the "with".')
                 ->enforceSize('➎', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the "only".'),
             ],
             ['<➀embed➊$➌with➍&➁>', $this
                 ->argTag()
-                ->delegate('$', 'expr')->delegate('&', 'hash')
+                ->delegate('$', 'expr')->delegate('&', 'with')
                 ->enforceSize('➊', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the source.')
                 ->enforceSize('➌', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the "with".')
                 ->enforceSize('➍', $this->config['from']['before_source'], 'There should be %quantity% space(s) after the "with".'),
@@ -338,7 +338,7 @@ public function build(): array
             ['<➀include➊$➋ignore missing➌with➍&➎only➁>', $this
                 ->argTag()
                 ->delegate('$', 'expr')
-                ->delegate('&', 'hash')
+                ->delegate('&', 'with')
                 ->enforceSize('➊', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the source.')
                 ->enforceSize('➋', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the "ignore missing".')
                 ->enforceSize('➌', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the "with".')
@@ -361,7 +361,7 @@ public function build(): array
             ['<➀include➊$➌with➍&➎only➁>', $this
                 ->argTag()
                 ->delegate('$', 'expr')
-                ->delegate('&', 'hash')
+                ->delegate('&', 'with')
                 ->enforceSize('➊', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the source.')
                 ->enforceSize('➌', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the "with".')
                 ->enforceSize('➍', $this->config['from']['before_source'], 'There should be %quantity% space(s) after the "with".')
@@ -370,7 +370,7 @@ public function build(): array
             ['<➀include➊$➌with➍&➁>', $this
                 ->argTag()
                 ->delegate('$', 'expr')
-                ->delegate('&', 'hash')
+                ->delegate('&', 'with')
                 ->enforceSize('➊', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the source.')
                 ->enforceSize('➌', $this->config['from']['before_source'], 'There should be %quantity% space(s) before the "with".')
                 ->enforceSize('➍', $this->config['from']['before_source'], 'There should be %quantity% space(s) after the "with".'),
@@ -695,11 +695,16 @@ public function build(): array
             ],
         ]);
 
+        $with = $this->using(self::OP_VARS, [
+            ['$', $this->handle()->noop()],
+        ]);
+
         return [
             'expr' => array_merge($tags, $ops, $fallback),
             'list' => $list,
             'argsList' => $argsList,
             'hash' => array_merge($hash, $hashFallback),
+            'with' => array_merge($hash, $with),
             'imports' => $imports,
             'arrayOrSlice' => array_merge($slice, $array),
         ];

src/Rule/AbstractRule.php

@@ -4,6 +4,7 @@
 
 use FriendsOfTwig\Twigcs\TwigPort\Token;
 use FriendsOfTwig\Twigcs\TwigPort\TokenStream;
+use FriendsOfTwig\Twigcs\Util\StreamNavigator;
 use FriendsOfTwig\Twigcs\Validator\Violation;
 
 /**
@@ -19,10 +20,7 @@ abstract class AbstractRule
      */
     protected $severity;
 
-    /**
-     * @param int $severity
-     */
-    public function __construct($severity)
+    public function __construct(int $severity)
     {
         $this->severity = $severity;
     }
@@ -34,109 +32,31 @@ public function collect(): array
 
     public function createViolation(string $filename, int $line, int $column, string $reason): Violation
     {
-        return new Violation($filename, $line, $column, $reason, $this->severity, get_called_class());
+        return new Violation($filename, $line, $column, $reason, $this->severity, static::class);
     }
 
-    /**
-     * @param int $skip
-     *
-     * @return Token|null
-     */
-    protected function getPreviousSignificantToken(TokenStream $tokens, $skip = 0)
+    protected function getPreviousSignificantToken(TokenStream $tokens, int $skip = 0): ?Token
     {
-        $i = 1;
-        $token = null;
-
-        while ($token = $tokens->look(-$i)) {
-            if (!in_array($token->getType(), [Token::WHITESPACE_TYPE, Token::NEWLINE_TYPE], true)) {
-                if (0 === $skip) {
-                    return $token;
-                }
-
-                --$skip;
-            }
-
-            ++$i;
-        }
-
-        return null;
+        return StreamNavigator::getPreviousSignificantToken($tokens, $skip);
     }
 
-    /**
-     * @param int $skip
-     *
-     * @return Token|null
-     */
-    protected function getNextSignificantToken(TokenStream $tokens, $skip = 0)
+    protected function getNextSignificantToken(TokenStream $tokens, int $skip = 0): ?Token
     {
-        $i = 1;
-        $token = null;
-
-        while ($token = $tokens->look($i)) {
-            if (!in_array($token->getType(), [Token::WHITESPACE_TYPE, Token::NEWLINE_TYPE], true)) {
-                if (0 === $skip) {
-                    return $token;
-                }
-
-                --$skip;
-            }
-
-            ++$i;
-        }
-
-        return null;
+        return StreamNavigator::getNextSignificantToken($tokens, $skip);
     }
 
     protected function skipTo(TokenStream $tokens, int $tokenType, string $tokenValue = null)
     {
-        while (!$tokens->isEOF()) {
-            $continue = $tokens->getCurrent()->getType() !== $tokenType;
-
-            if (null !== $tokenValue) {
-                $continue |= $tokens->getCurrent()->getValue() !== $tokenValue;
-            }
-
-            if (!$continue) {
-                return;
-            }
-
-            $tokens->next();
-        }
+        return StreamNavigator::skipTo($tokens, $tokenType, $tokenValue);
     }
 
     protected function skipToOneOf(TokenStream $tokens, array $possibilities)
     {
-        while (!$tokens->isEOF()) {
-            foreach ($possibilities as $possibility) {
-                $tokenValue = $possibility['value'] ?? null;
-                $tokenType = $possibility['type'] ?? null;
-                $found = true;
-
-                if ($tokenType) {
-                    $found &= $tokenType === $tokens->getCurrent()->getType();
-                }
-
-                if ($tokenValue) {
-                    $found &= $tokenValue === $tokens->getCurrent()->getValue();
-                }
-
-                if ($found) {
-                    return;
-                }
-            }
-
-            $tokens->next();
-        }
+        return StreamNavigator::skipToOneOf($tokens, $possibilities);
     }
 
     protected function skip(TokenStream $tokens, int $amount)
     {
-        while (!$tokens->isEOF()) {
-            --$amount;
-            $tokens->next();
-            if (0 === $amount) {
-                return;
-            }
-        }
+        return StreamNavigator::skip($tokens, $amount);
     }
 }