Experimental include and embed support for variable usage detection

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/Rule/UnusedMacro.php

@@ -3,22 +3,31 @@
 namespace FriendsOfTwig\Twigcs\Rule;
 
 use FriendsOfTwig\Twigcs\Scope\ScopeBuilder;
+use FriendsOfTwig\Twigcs\TemplateResolver\NullResolver;
+use FriendsOfTwig\Twigcs\TemplateResolver\TemplateResolverInterface;
 use FriendsOfTwig\Twigcs\TwigPort\TokenStream;
 
 class UnusedMacro extends AbstractRule implements RuleInterface
 {
+    public function __construct(int $severity, TemplateResolverInterface $loader = null)
+    {
+        $this->loader = $loader ?: new NullResolver();
+
+        parent::__construct($severity);
+    }
+
     /**
      * {@inheritdoc}
      */
     public function check(TokenStream $tokens)
     {
-        $builder = ScopeBuilder::createMacroScopeBuilder();
+        $builder = ScopeBuilder::createMacroScopeBuilder($this->loader);
 
         $root = $builder->build($tokens);
 
         $violations = [];
 
-        foreach ($root->flatten()->getUnusedDeclarations() as $declaration) {
+        foreach ($root->flatten()->getRootUnusedDeclarations() as $declaration) {
             $token = $declaration->getToken();
 
             $violations[] = $this->createViolation(

src/Rule/UnusedVariable.php

@@ -3,22 +3,31 @@
 namespace FriendsOfTwig\Twigcs\Rule;
 
 use FriendsOfTwig\Twigcs\Scope\ScopeBuilder;
+use FriendsOfTwig\Twigcs\TemplateResolver\NullResolver;
+use FriendsOfTwig\Twigcs\TemplateResolver\TemplateResolverInterface;
 use FriendsOfTwig\Twigcs\TwigPort\TokenStream;
 
 class UnusedVariable extends AbstractRule implements RuleInterface
 {
+    public function __construct(int $severity, TemplateResolverInterface $loader = null)
+    {
+        $this->loader = $loader ?: new NullResolver();
+
+        parent::__construct($severity);
+    }
+
     /**
      * {@inheritdoc}
      */
     public function check(TokenStream $tokens)
     {
-        $builder = ScopeBuilder::createVariableScopeBuilder();
+        $builder = ScopeBuilder::createVariableScopeBuilder($this->loader);
 
         $root = $builder->build($tokens);
 
         $violations = [];
 
-        foreach ($root->flatten()->getUnusedDeclarations() as $declaration) {
+        foreach ($root->flatten()->getRootUnusedDeclarations() as $declaration) {
             $token = $declaration->getToken();
 
             $violations[] = $this->createViolation(

src/Ruleset/Official.php

@@ -5,20 +5,25 @@
 use FriendsOfTwig\Twigcs\RegEngine\RulesetBuilder;
 use FriendsOfTwig\Twigcs\RegEngine\RulesetConfigurator;
 use FriendsOfTwig\Twigcs\Rule;
+use FriendsOfTwig\Twigcs\TemplateResolver\NullResolver;
+use FriendsOfTwig\Twigcs\TemplateResolver\TemplateResolverInterface;
 use FriendsOfTwig\Twigcs\Validator\Violation;
 
 /**
  * The official twigcs ruleset, based on http://twig.sensiolabs.org/doc/coding_standards.html.
  *
  * @author Tristan Maindron <tmaindron@gmail.com>
  */
-class Official implements RulesetInterface
+class Official implements RulesetInterface, TemplateResolverAwareInterface
 {
     private $twigMajorVersion;
 
+    private TemplateResolverInterface $resolver;
+
     public function __construct(int $twigMajorVersion)
     {
         $this->twigMajorVersion = $twigMajorVersion;
+        $this->resolver = new NullResolver();
     }
 
     /**
@@ -34,8 +39,13 @@ public function getRules()
             new Rule\LowerCaseVariable(Violation::SEVERITY_ERROR),
             new Rule\RegEngineRule(Violation::SEVERITY_ERROR, $builder->build()),
             new Rule\TrailingSpace(Violation::SEVERITY_ERROR),
-            new Rule\UnusedMacro(Violation::SEVERITY_WARNING),
-            new Rule\UnusedVariable(Violation::SEVERITY_WARNING),
+            new Rule\UnusedMacro(Violation::SEVERITY_WARNING, $this->resolver),
+            new Rule\UnusedVariable(Violation::SEVERITY_WARNING, $this->resolver),
         ];
     }
+
+    public function setTemplateResolver(TemplateResolverInterface $resolver)
+    {
+        $this->resolver = $resolver;
+    }
 }

src/Ruleset/RulesetInterface.php

@@ -4,6 +4,9 @@
 
 use FriendsOfTwig\Twigcs\Rule\RuleInterface;
 
+/**
+ * @author Tristan Maindron <tmaindron@gmail.com>
+ */
 interface RulesetInterface
 {
     public function __construct(int $twigMajorVersion);

src/Ruleset/TemplateResolverAwareInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace FriendsOfTwig\Twigcs\Ruleset;
+
+use FriendsOfTwig\Twigcs\TemplateResolver\TemplateResolverInterface;
+
+/**
+ * @author Tristan Maindron <tmaindron@gmail.com>
+ */
+interface TemplateResolverAwareInterface
+{
+    public function setTemplateResolver(TemplateResolverInterface $resolver);
+}

src/Scope/Declaration.php

@@ -16,10 +16,16 @@ class Declaration
      */
     private $token;
 
-    public function __construct(string $name, Token $token)
+    /**
+     * @var Scope
+     */
+    private $origin;
+
+    public function __construct(string $name, Token $token, Scope $origin)
     {
         $this->name = $name;
         $this->token = $token;
+        $this->origin = $origin;
     }
 
     public function getName(): string
@@ -32,6 +38,11 @@ public function getToken(): Token
         return $this->token;
     }
 
+    public function getOrigin(): Scope
+    {
+        return $this->origin;
+    }
+
     public function __toString()
     {
         return sprintf('declaration of %s', $this->name);

src/Scope/FlattenedScope.php

@@ -76,6 +76,23 @@ public function getQueue(): array
         return $this->queue;
     }
 
+    public function getRootUnusedDeclarations(): array
+    {
+        $unused = $this->getUnusedDeclarations();
+
+        $unused = array_filter($unused, function (Declaration $declaration) {
+            $scope = $declaration->getOrigin();
+
+            while ('file' !== $scope->getType() && $scope->getParent()) {
+                $scope = $scope->getParent();
+            }
+
+            return 'root' === $scope->getName();
+        });
+
+        return $unused;
+    }
+
     public function getUnusedDeclarations(): array
     {
         $unused = [];