Add Twig CS Fixer rule to detect GraphQL overfetching

.twig-cs-fixer.php

@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 use Ruudk\GraphQLCodeGenerator\Twig\GraphQLFormatterRule;
+use Ruudk\GraphQLCodeGenerator\Twig\GraphQLOverfetchingRule;
 use Ruudk\GraphQLCodeGenerator\Twig\GraphQLTokenParser;
 use TwigCsFixer\Config\Config;
 use TwigCsFixer\File\Finder;
@@ -13,6 +14,7 @@
 
 $ruleset->addStandard(new TwigCsFixer());
 $ruleset->addRule(new GraphQLFormatterRule());
+$ruleset->addRule(new GraphQLOverfetchingRule());
 
 $finder = Finder::create()
     ->in('tests');

README.md

@@ -657,6 +657,7 @@ Register `GraphQLFormatterRule` (and the `GraphQLTokenParser` so Twig CS Fixer u
 declare(strict_types=1);
 
 use Ruudk\GraphQLCodeGenerator\Twig\GraphQLFormatterRule;
+use Ruudk\GraphQLCodeGenerator\Twig\GraphQLOverfetchingRule;
 use Ruudk\GraphQLCodeGenerator\Twig\GraphQLTokenParser;
 use TwigCsFixer\Config\Config;
 use TwigCsFixer\File\Finder;
@@ -667,6 +668,7 @@ $ruleset = new Ruleset();
 
 $ruleset->addStandard(new TwigCsFixer());
 $ruleset->addRule(new GraphQLFormatterRule());
+$ruleset->addRule(new GraphQLOverfetchingRule());
 
 $finder = Finder::create()
     ->in('tests');

src/Twig/GraphQLOverfetchingRule.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ruudk\GraphQLCodeGenerator\Twig;
+
+use Override;
+use Ruudk\GraphQLCodeGenerator\Twig\Overfetching\OverfetchingAnalyzer;
+use TwigCsFixer\Rules\AbstractRule;
+use TwigCsFixer\Token\Token;
+use TwigCsFixer\Token\Tokens;
+
+/**
+ * Reports GraphQL over-fetching: fields selected in a `{% graphql %}` fragment
+ * that are never read back in the Twig template that declared it via
+ * `{% types %}`.
+ */
+final class GraphQLOverfetchingRule extends AbstractRule
+{
+    private readonly OverfetchingAnalyzer $analyzer;
+
+    /**
+     * @var array<string, true>
+     */
+    private array $analyzed = [];
+
+    public function __construct(
+        ?OverfetchingAnalyzer $analyzer = null,
+    ) {
+        $this->analyzer = $analyzer ?? new OverfetchingAnalyzer();
+    }
+
+    #[Override]
+    protected function process(int $tokenIndex, Tokens $tokens) : void
+    {
+        $token = $tokens->get($tokenIndex);
+
+        if ( ! $token->isMatching(Token::BLOCK_NAME_TYPE, 'types')) {
+            return;
+        }
+
+        $fileName = $token->getFilename();
+
+        if (isset($this->analyzed[$fileName])) {
+            return;
+        }
+
+        $this->analyzed[$fileName] = true;
+
+        $source = @file_get_contents($fileName);
+
+        if ($source === false) {
+            return;
+        }
+
+        foreach ($this->analyzer->analyze($source, $fileName) as $message) {
+            $this->addError($message, $token);
+        }
+    }
+}

src/Twig/Overfetching/Binding.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ruudk\GraphQLCodeGenerator\Twig\Overfetching;
+
+/**
+ * What a Twig variable currently points at: a generated class (and whether it
+ * is a list of them), or nothing we can resolve (`fqcn === null`).
+ */
+final readonly class Binding
+{
+    public function __construct(
+        public ?string $fqcn = null,
+        public bool $list = false,
+    ) {}
+
+    public static function unknown() : self
+    {
+        return new self();
+    }
+
+    /**
+     * The binding for the element produced when iterating this binding with
+     * `{% for %}`.
+     */
+    public function element() : self
+    {
+        return new self($this->fqcn, false);
+    }
+}