diff --git a/src/Config/ConfigData.php b/src/Config/ConfigData.php
index c841db0..0cfb46b 100644
--- a/src/Config/ConfigData.php
+++ b/src/Config/ConfigData.php
@@ -7,6 +7,7 @@
 final readonly class ConfigData
 {
     /**
+     * @param array<string, string> $projectRoots
      * @param list<SniffEntry> $sniffs
      * @param list<string> $includePaths
      * @param list<string> $excludePatterns
@@ -14,6 +15,7 @@
      * @param string $basePath
      */
     public function __construct(
+        private array $projectRoots,
         private array $sniffs,
         private array $includePaths,
         private array $excludePatterns,
@@ -22,6 +24,12 @@ public function __construct(
     ) {
     }
 
+    /** @return array<string, string> */
+    public function getProjectRoots(): array
+    {
+        return $this->projectRoots;
+    }
+
     /** @return list<SniffEntry> */
     public function getSniffs(): array
     {
diff --git a/src/Config/ConfigParser.php b/src/Config/ConfigParser.php
index 4db00e3..c1fdf82 100644
--- a/src/Config/ConfigParser.php
+++ b/src/Config/ConfigParser.php
@@ -67,20 +67,47 @@ private function parse(\SimpleXMLElement $root, string $basePath): ConfigData
         // Register the namespace for xpath queries.
         $root->registerXPathNamespace('d', self::NAMESPACE_URI);
 
-        $sniffs = $this->parseSniffs($root);
-        $includePaths = $this->parsePaths($root, $basePath);
-        $excludePatterns = $this->parseExcludePatterns($root);
-        $entityPaths = $this->parseEntityPaths($root, $basePath);
-
         return new ConfigData(
-            sniffs: $sniffs,
-            includePaths: $includePaths,
-            excludePatterns: $excludePatterns,
-            entityPaths: $entityPaths,
+            projectRoots: $this->parseProjectRoots($root, $basePath),
+            sniffs: $this->parseSniffs($root),
+            includePaths: $this->parsePaths($root, $basePath),
+            excludePatterns: $this->parseExcludePatterns($root),
+            entityPaths: $this->parseEntityPaths($root, $basePath),
             basePath: $basePath,
         );
     }
 
+    /**
+     * @return array<string, string>
+     * @throws ConfigParserException if the <project> element is missing or if
+     * the base path is not within any of the specified project roots.
+     */
+    private function parseProjectRoots(\SimpleXMLElement $root, string $basePath): array
+    {
+        if (!isset($root->project)) {
+            $name = basename($basePath);
+
+            return [
+                dirname($basePath) . '/' . $name => $name,
+                $basePath => $name,
+            ];
+        }
+
+        $directories = [];
+
+        foreach ($root->project->directory ?: [] as $directory) {
+            $directoryName = (string) $directory;
+            $directories[dirname($basePath) . '/' . $directoryName] = $directoryName;
+
+            if ($directory->attributes()->alias) {
+                $alias = (string) $directory->attributes()->alias;
+                $directories[dirname($basePath) . '/' . $alias] = $directoryName;
+            }
+        }
+
+        return $directories;
+    }
+
     /**
      * @return list<SniffEntry>
      * @throws ConfigParserException if required elements or attributes are missing.
diff --git a/src/Path/EntityResolver.php b/src/Path/EntityResolver.php
index 4ce0674..f505943 100644
--- a/src/Path/EntityResolver.php
+++ b/src/Path/EntityResolver.php
@@ -6,46 +6,57 @@
 
 final class EntityResolver
 {
-    /** @var list<string> */
-    private array $entityPaths;
-
     private string $extension;
 
     /**
+     * @param array<string, string> $projectRoots
      * @param list<string> $entityPaths
      */
-    public function __construct(array $entityPaths, string $extension = 'ent')
-    {
-        $this->entityPaths = $entityPaths;
+    public function __construct(
+        private readonly array $projectRoots,
+        private readonly array $entityPaths,
+        string $extension = 'ent'
+    ) {
         $this->extension = ltrim($extension, '.');
     }
 
     /**
-     * @return list<string>
-     * @throws \UnexpectedValueException if any of the entity paths is a directory that cannot be read.
+     * @return array<string, string>
+     * @throws \UnexpectedValueException if the directory cannot be read.
      */
     public function resolve(): array
     {
-        $files = [];
+        $entities = [];
 
         foreach ($this->entityPaths as $path) {
-            if (is_file($path) && str_ends_with($path, '.' . $this->extension)) {
-                $files[] = str_replace('\\', '/', $path);
-                continue;
+            foreach ($this->getEntityFiles($path) as $file) {
+                $entities += $this->resolveFile($file);
             }
+        }
 
-            if (!is_dir($path)) {
-                continue;
-            }
+        return $entities;
+    }
 
-            foreach ($this->scanDirectory($path) as $file) {
-                $files[] = $file;
-            }
+    /**
+     * @return list<string>
+     * @throws \UnexpectedValueException if the directory cannot be read.
+     */
+    private function getEntityFiles(string $path): array
+    {
+        if (is_file($path) && $this->isEntityFile($path)) {
+            return [$path];
         }
 
-        sort($files);
+        if (!is_dir($path)) {
+            return [];
+        }
+
+        return $this->scanDirectory($path);
+    }
 
-        return array_values(array_unique($files));
+    private function isEntityFile(string $path): bool
+    {
+        return str_ends_with($path, '.' . $this->extension);
     }
 
     /**
@@ -54,24 +65,119 @@ public function resolve(): array
      */
     private function scanDirectory(string $directory): array
     {
-        $found = [];
+        $files = [];
+
         $iterator = new \RecursiveIteratorIterator(
             new \RecursiveDirectoryIterator(
                 $directory,
-                \FilesystemIterator::SKIP_DOTS | \FilesystemIterator::UNIX_PATHS,
-            ),
+                \FilesystemIterator::SKIP_DOTS | \FilesystemIterator::UNIX_PATHS
+            )
         );
 
         /** @var \SplFileInfo $fileInfo */
         foreach ($iterator as $fileInfo) {
-            if (
-                $fileInfo->isFile()
-                && str_ends_with($fileInfo->getPathname(), '.' . $this->extension)
-            ) {
-                $found[] = str_replace('\\', '/', $fileInfo->getPathname());
+            if ($fileInfo->isFile() && $this->isEntityFile($fileInfo->getPathname())) {
+                $files[] = str_replace('\\', '/', $fileInfo->getPathname());
+            }
+        }
+
+        return $files;
+    }
+
+    /**
+     * @param array<string, bool> $visited
+     * @return array<string, string>
+     */
+    private function resolveFile(
+        string $filePath,
+        array &$visited = [],
+        ?string $originEntity = null
+    ): array {
+        if (isset($visited[$filePath]) || !is_readable($filePath)) {
+            return [];
+        }
+
+        $visited[$filePath] = true;
+
+        $content = file_get_contents($filePath);
+
+        if ($content === false) {
+            return []; // @codeCoverageIgnore
+        }
+
+        $entities = $this->extractEntities($content, $filePath, $visited);
+
+        if ($originEntity !== null) {
+            $entities[$originEntity] = $this->normalize($content);
+        }
+
+        return $entities;
+    }
+
+    /**
+     * @param array<string, bool> $visited
+     * @return array<string, string>
+     */
+    private function extractEntities(
+        string $content,
+        string $filePath,
+        array &$visited
+    ): array {
+        $result = [];
+
+        if (!str_contains($content, '<!ENTITY')) {
+            return $result;
+        }
+
+        if (
+            !preg_match_all(
+                '/<!ENTITY\s+(?:%\s*)?([A-Za-z0-9_\-:.]+)\s+(?:(SYSTEM)\s+)?(["\'])([\s\S]*?)\3\s*>/',
+                $content,
+                $matches,
+                PREG_SET_ORDER
+            )
+        ) {
+            return $result;
+        }
+
+        foreach ($matches as $match) {
+            $name = $match[1];
+            $type = $match[2] ?: null;
+            $value = trim($match[4]);
+
+            if ($type === 'SYSTEM') {
+                $resolvedPath = $this->resolvePath($filePath, $value);
+                $result += $this->resolveFile($resolvedPath, $visited, $name);
+
+                continue;
+            }
+
+            $result[$name] = $this->normalize($value);
+        }
+
+        return $result;
+    }
+
+    private function normalize(string $value): string
+    {
+        return preg_replace('/\s+/', ' ', trim($value)) ?: $value;
+    }
+
+    private function resolvePath(string $path, string $reference): string
+    {
+        foreach ($this->projectRoots as $root => $directory) {
+            if (!str_contains($reference, '/' . $directory . '/')) {
+                continue;
             }
+
+            [$prefix] = explode('/' . $directory . '/', $reference);
+            $reference = str_replace($prefix . '/' . $directory, $root, $reference);
+        }
+
+        if (str_starts_with($reference, '/')) {
+            return $reference;
         }
 
-        return $found;
+        return dirname($path) . DIRECTORY_SEPARATOR . $reference;
     }
 }
diff --git a/src/Path/PathMatcher.php b/src/Path/PathMatcher.php
index a2b80dd..146896f 100644
--- a/src/Path/PathMatcher.php
+++ b/src/Path/PathMatcher.php
@@ -6,19 +6,19 @@
 
 final readonly class PathMatcher
 {
-    /** @var list<string> */
-    private array $excludePatterns;
-
     /**
      * @param list<string> $excludePatterns
      */
-    public function __construct(array $excludePatterns)
-    {
-        $this->excludePatterns = $excludePatterns;
+    public function __construct(
+        private string $basePath,
+        private array $excludePatterns
+    ) {
     }
 
     public function isExcluded(string $filePath): bool
     {
+        $filePath = str_replace($this->basePath . '/', '', $filePath);
+
         // Normalize to forward slashes for consistent matching.
         $normalized = str_replace('\\', '/', $filePath);
 
diff --git a/src/Runner/EntityPreprocessor.php b/src/Runner/EntityPreprocessor.php
index 7f79803..a603684 100644
--- a/src/Runner/EntityPreprocessor.php
+++ b/src/Runner/EntityPreprocessor.php
@@ -7,38 +7,66 @@
 final class EntityPreprocessor
 {
     private const array PREDEFINED = ['amp', 'lt', 'gt', 'quot', 'apos'];
-    private const string ENTITY_PATTERN = '/&([a-zA-Z_][\w.\-]*);/';
-
-    private string $replacement;
-
-    public function __construct(string $replacement = '')
-    {
-        $this->replacement = $replacement;
+    private const string ENTITY_PATTERN = '&([a-zA-Z_][\w.\-]*);';
+    private const string XML_DECLARATION_PATTERN = '/<\?xml[^?]*\?>/i';
+
+    /**
+     * @param array<string, string> $entities
+     */
+    public function __construct(
+        private array $entities,
+    ) {
     }
 
-    public function process(string $xmlContent): string
+    public function process(string $xml): string
     {
-        return $this->neutralize(
-            $this->stripDoctype($xmlContent)
-        );
+        $xml = $this->stripDoctype($xml);
+
+        return $this->expandEntities($xml);
     }
 
-    public function neutralize(string $xmlContent): string
+    private function expandEntities(string $content): string
     {
-        return (string)preg_replace_callback(
-            self::ENTITY_PATTERN,
-            function (array $matches): string {
-                if (in_array($matches[1], self::PREDEFINED, true)) {
-                    return $matches[0]; // keep &amp; etc.
-                }
-
-                return $this->replacement;
-            },
-            $xmlContent,
-        );
+        $maxDepth = 20;
+
+        for ($i = 0; $i < $maxDepth; $i++) {
+            $changed = false;
+
+            $content = preg_replace_callback(
+                '/<!--[\s\S]*?-->|' . self::ENTITY_PATTERN . '/',
+                function (array $matches) use (&$changed): string {
+                    // If this is a comment, return as is
+                    if (str_starts_with($matches[0], '<!--')) {
+                        return $matches[0];
+                    }
+
+                    $name = $matches[1] ?? null;
+                    if (!$name || in_array($name, self::PREDEFINED, true)) {
+                        return $matches[0];
+                    }
+
+                    if (!isset($this->entities[$name])) {
+                        return $matches[0];
+                    }
+
+                    $changed = true;
+
+                    $value = $this->entities[$name];
+
+                    return $this->stripXmlDeclaration($value);
+                },
+                $content,
+            ) ?: $content;
+
+            if (!$changed) {
+                break;
+            }
+        }
+
+        return $content;
     }
 
-    public function stripDoctype(string $xmlContent): string
+    private function stripDoctype(string $xmlContent): string
     {
         $start = stripos($xmlContent, '<!DOCTYPE');
 
@@ -64,11 +92,8 @@ public function stripDoctype(string $xmlContent): string
             } elseif ($char === ']' && !$inSingleQuote && !$inDoubleQuote) {
                 $inBracket = false;
             } elseif ($char === '>' && !$inSingleQuote && !$inDoubleQuote && !$inBracket) {
-                // Found the end of the DOCTYPE.
-                $before = substr($xmlContent, 0, $start);
-                $after = substr($xmlContent, $pos + 1);
-
-                return $before . $after;
+                return substr($xmlContent, 0, $start)
+                    . substr($xmlContent, $pos + 1);
             }
 
             $pos++;
@@ -76,4 +101,9 @@ public function stripDoctype(string $xmlContent): string
 
         return $xmlContent;
     }
+
+    private function stripXmlDeclaration(string $xmlContent): string
+    {
+        return preg_replace(self::XML_DECLARATION_PATTERN, '', $xmlContent) ?: $xmlContent;
+    }
 }
diff --git a/src/Runner/SniffRunner.php b/src/Runner/SniffRunner.php
index 73fdfbc..4059d76 100644
--- a/src/Runner/SniffRunner.php
+++ b/src/Runner/SniffRunner.php
@@ -6,6 +6,7 @@
 
 use DocbookCS\Config\ConfigData;
 use DocbookCS\Config\SniffEntry;
+use DocbookCS\Path\EntityResolver;
 use DocbookCS\Path\PathLoader;
 use DocbookCS\Path\PathMatcher;
 use DocbookCS\Progress\NullProgress;
@@ -34,10 +35,13 @@ public function run(ConfigData $config, ?array $overridePaths = null, ?array $di
 
         $sniffs = $this->instantiateSniffs($config->getSniffs());
 
-        $matcher = new PathMatcher($config->getExcludePatterns());
+        $matcher = new PathMatcher($config->getBasePath(), $config->getExcludePatterns());
 
         $includePaths = $overridePaths ?? $config->getIncludePaths();
 
+        $entityResolver = new EntityResolver($config->getProjectRoots(), $config->getEntityPaths());
+        $entities = $entityResolver->resolve();
+
         $pathLoader = new PathLoader($includePaths, $matcher);
         $files = $pathLoader->loadPaths();
 
@@ -46,7 +50,7 @@ public function run(ConfigData $config, ?array $overridePaths = null, ?array $di
         }
 
         $report = new Report();
-        $preprocessor = new EntityPreprocessor();
+        $preprocessor = new EntityPreprocessor($entities);
         $processor = new XmlFileProcessor($sniffs, $preprocessor, $report);
 
         $total = count($files);
diff --git a/src/Runner/XmlFileProcessor.php b/src/Runner/XmlFileProcessor.php
index 2ab2f29..0904c12 100644
--- a/src/Runner/XmlFileProcessor.php
+++ b/src/Runner/XmlFileProcessor.php
@@ -26,7 +26,7 @@ public function __construct(
         ?Report $report = null,
     ) {
         $this->sniffs = $sniffs;
-        $this->preprocessor = $preprocessor ?? new EntityPreprocessor();
+        $this->preprocessor = $preprocessor ?? new EntityPreprocessor([]);
         $this->report = $report ?? new Report();
     }
 
diff --git a/src/Sniff/WhitespaceSniff.php b/src/Sniff/WhitespaceSniff.php
new file mode 100644
index 0000000..6f72852
--- /dev/null
+++ b/src/Sniff/WhitespaceSniff.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DocbookCS\Sniff;
+
+/**
+ * Detects whitespace and indentation issues in DocBook source files.
+ *
+ * The following violations are detected:
+ * - Trailing whitespace at the end of a line
+ * - Spaces used before tabs in indentation
+ * - Mixed use of tabs and spaces within indentation
+ */
+final class WhitespaceSniff extends AbstractSniff
+{
+    public function getCode(): string
+    {
+        return 'DocbookCS.Whitespace';
+    }
+
+    /** @throws \LogicException if an invalid severity level is configured */
+    public function process(\DOMDocument $document, string $content, string $filePath): array
+    {
+        $lines = explode(PHP_EOL, $content);
+        $pattern = '/([ \t]+$)|^(\t* +\t+|\t+ +\t*)|^( +)\t/';
+
+        $violations = [];
+        foreach ($lines as $lineNumber => $line) {
+            $lineNo = $lineNumber + 1;
+
+            if (preg_match($pattern, $line, $matches)) {
+                $message = match (true) {
+                    !empty($matches[1]) => 'Trailing whitespace detected.',
+                    !empty($matches[2]) || !empty($matches[3]) => 'Mixed tabs and spaces in indentation.',
+                    default => 'Inconsistent indentation.', // @codeCoverageIgnore
+                };
+
+                $violations[] = $this->createViolation($filePath, $lineNo, $message);
+            }
+        }
+
+        return $violations;
+    }
+}
diff --git a/tests/Unit/ApplicationTest.php b/tests/Unit/ApplicationTest.php
index 22c8664..6e24e79 100644
--- a/tests/Unit/ApplicationTest.php
+++ b/tests/Unit/ApplicationTest.php
@@ -10,6 +10,7 @@
 use DocbookCS\Config\ConfigParser;
 use DocbookCS\Config\ConfigParserException;
 use DocbookCS\Config\SniffEntry;
+use DocbookCS\Path\EntityResolver;
 use DocbookCS\Path\PathLoader;
 use DocbookCS\Path\PathMatcher;
 use DocbookCS\Progress\NullProgress;
@@ -44,6 +45,7 @@
 #[CoversClass(JsonReporter::class)]
 #[CoversClass(FileReport::class)]
 #[CoversClass(ExceptionNameSniff::class)]
+#[CoversClass(EntityResolver::class)]
 final class ApplicationTest extends TestCase
 {
     private const string FIXTURE_DIR = __DIR__ . '/../fixtures/application';
diff --git a/tests/Unit/Config/ConfigParserTest.php b/tests/Unit/Config/ConfigParserTest.php
index 001067f..df56a0b 100644
--- a/tests/Unit/Config/ConfigParserTest.php
+++ b/tests/Unit/Config/ConfigParserTest.php
@@ -31,6 +31,9 @@ public function itParsesAFullConfigFromString(): void
         $xml = <<<'XML'
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+    <project>
+        <directory alias="doc">en</directory>
+    </project>
     <sniffs>
         <sniff class="App\Sniffs\ParaSniff" />
         <sniff class="App\Sniffs\IdSniff">
@@ -54,6 +57,12 @@ public function itParsesAFullConfigFromString(): void
         $basePath = '/project/doc';
         $config = $this->parser->parseString($xml, $basePath);
 
+        // Project roots
+        $projectRoots = $config->getProjectRoots();
+        self::assertNotEmpty($projectRoots);
+        self::assertSame('en', $projectRoots['/project/en']);
+        self::assertSame('en', $projectRoots['/project/doc']);
+
         // Sniffs
         self::assertCount(2, $config->getSniffs());
         self::assertSame('App\Sniffs\ParaSniff', $config->getSniffs()[0]->getClassName());
@@ -85,6 +94,9 @@ public function itParsesMinimalConfig(): void
         $xml = <<<'XML'
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+    <project>
+        <directory>en</directory>
+    </project>
     <sniffs>
         <sniff class="App\Sniffs\ParaSniff" />
     </sniffs>
@@ -105,6 +117,9 @@ public function itResolvesAbsolutePathsAsIs(): void
         $xml = <<<'XML'
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+    <project>
+        <directory>en</directory>
+    </project>
     <sniffs>
         <sniff class="App\Sniffs\ParaSniff" />
     </sniffs>
@@ -143,6 +158,9 @@ public function itThrowsWhenSniffsElementIsMissing(): void
         $xml = <<<'XML'
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+    <project>
+        <directory>en</directory>
+    </project>
     <paths><path>foo/</path></paths>
 </docbookcs>
 XML;
@@ -159,6 +177,9 @@ public function itThrowsWhenSniffHasNoClassAttribute(): void
         $xml = <<<'XML'
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+    <project>
+        <directory>en</directory>
+    </project>
     <sniffs>
         <sniff />
     </sniffs>
@@ -177,6 +198,9 @@ public function itThrowsWhenPropertyHasNoNameAttribute(): void
         $xml = <<<'XML'
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+    <project>
+        <directory>en</directory>
+    </project>
     <sniffs>
         <sniff class="App\Sniffs\Foo">
             <property value="bar" />
@@ -211,6 +235,9 @@ public function itSkipsEmptyPathElements(): void
         $xml = <<<'XML'
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+    <project>
+        <directory>en</directory>
+    </project>
     <sniffs>
         <sniff class="App\Sniffs\ParaSniff" />
     </sniffs>
@@ -234,6 +261,9 @@ public function itSkipsEmptyEntityElements(): void
         $xml = <<<'XML'
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+    <project>
+        <directory>en</directory>
+    </project>
     <sniffs>
         <sniff class="App\Sniffs\ParaSniff" />
     </sniffs>
@@ -257,6 +287,9 @@ public function itRecognizesWindowsAbsolutePaths(): void
         $xml = <<<'XML'
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+    <project>
+        <directory>en</directory>
+    </project>
     <sniffs>
         <sniff class="App\Sniffs\ParaSniff" />
     </sniffs>
@@ -285,4 +318,30 @@ public function itThrowsWhenFileContainsInvalidXml(): void
 
         $this->parser->parseFile($fixturePath);
     }
+
+    #[Test]
+    public function itParsesProjectRootsWithAlias(): void
+    {
+        $xml = <<<'XML'
+<?xml version="1.0" encoding="UTF-8"?>
+<docbookcs>
+    <project>
+        <directory alias="doc">en</directory>
+        <directory alias="ref">reference</directory>
+    </project>
+    <sniffs>
+        <sniff class="App\Sniffs\ParaSniff" />
+    </sniffs>
+</docbookcs>
+XML;
+
+        $config = $this->parser->parseString($xml, '/project/doc');
+
+        $roots = $config->getProjectRoots();
+
+        self::assertSame('en', $roots['/project/en']);
+        self::assertSame('en', $roots['/project/doc']);
+        self::assertSame('reference', $roots['/project/reference']);
+        self::assertSame('reference', $roots['/project/ref']);
+    }
 }
diff --git a/tests/Unit/Path/EntityResolverTest.php b/tests/Unit/Path/EntityResolverTest.php
index ecf39cf..d3f3ebb 100644
--- a/tests/Unit/Path/EntityResolverTest.php
+++ b/tests/Unit/Path/EntityResolverTest.php
@@ -24,123 +24,221 @@ protected function setUp(): void
     }
 
     #[Test]
-    public function itReturnsEmptyArrayWhenNoPathsGiven(): void
+    public function itReturnsEmptyArrayWhenNoEntityPathsGiven(): void
     {
-        $resolver = new EntityResolver([]);
+        $resolver = new EntityResolver([], []);
 
         self::assertSame([], $resolver->resolve());
     }
 
     #[Test]
-    public function itFindsEntityFilesRecursively(): void
+    public function itSilentlySkipsNonexistentPaths(): void
     {
-        $resolver = new EntityResolver([$this->fixtureRoot]);
+        $resolver = new EntityResolver([], ['/nonexistent/path/that/does/not/exist']);
 
-        $files = $resolver->resolve();
+        self::assertSame([], $resolver->resolve());
+    }
 
-        self::assertNotEmpty($files);
+    #[Test]
+    public function itParsesSimpleEntityDeclarations(): void
+    {
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/global.ent']);
+        $entities = $resolver->resolve();
 
-        foreach ($files as $file) {
-            self::assertStringEndsWith('.ent', $file);
-        }
+        self::assertSame('Acme Widget', $entities['product']);
+        self::assertSame('1.0.0', $entities['version']);
     }
 
     #[Test]
-    public function itAcceptsSingleFilePath(): void
+    public function itNormalizesWhitespaceInValues(): void
     {
-        $singleFile = $this->fixtureRoot . '/global.ent';
-
-        if (!is_file($singleFile)) {
-            self::markTestSkipped('Fixture file not found.');
-        }
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/global.ent']);
+        $entities = $resolver->resolve();
 
-        $resolver = new EntityResolver([$singleFile]);
+        self::assertSame('hello world', $entities['greeting']);
+    }
 
-        $files = $resolver->resolve();
+    #[Test]
+    public function itHandlesParameterEntities(): void
+    {
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/quoted.ent']);
+        $entities = $resolver->resolve();
 
-        self::assertCount(1, $files);
-        self::assertStringContainsString('global.ent', $files[0]);
+        self::assertArrayHasKey('param_entity', $entities);
+        self::assertSame('param-value', $entities['param_entity']);
     }
 
     #[Test]
-    public function itIgnoresFilesWithWrongExtension(): void
+    public function itHandlesSingleQuotedValues(): void
     {
-        $xmlFile = $this->fixtureRoot . '/not_an_entity.xml';
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/quoted.ent']);
+        $entities = $resolver->resolve();
 
-        if (!is_file($xmlFile)) {
-            self::markTestSkipped('Fixture file not found.');
-        }
+        self::assertSame('single', $entities['single_quoted']);
+    }
 
-        $resolver = new EntityResolver([$xmlFile]);
+    #[Test]
+    public function itReturnsEmptyForFileWithoutEntityKeyword(): void
+    {
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/plain.ent']);
 
         self::assertSame([], $resolver->resolve());
     }
 
     #[Test]
-    public function itSilentlySkipsNonexistentPaths(): void
+    public function itReturnsEmptyWhenEntityKeywordPresentButNoMatches(): void
     {
-        $resolver = new EntityResolver(['/nonexistent/path']);
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/broken.ent']);
 
         self::assertSame([], $resolver->resolve());
     }
 
     #[Test]
-    public function itReturnsSortedDeduplicated(): void
+    public function itResolvesSystemEntitiesByRelativePath(): void
+    {
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/system/main.ent']);
+        $entities = $resolver->resolve();
+
+        self::assertArrayHasKey('inc', $entities);
+        self::assertArrayHasKey('child', $entities);
+        self::assertSame('child-value', $entities['child']);
+    }
+
+    #[Test]
+    public function itResolvesSystemEntitiesByAbsolutePath(): void
     {
-        $singleFile = $this->fixtureRoot . '/global.ent';
+        $included = $this->fixtureRoot . '/system/included.ent';
+
+        $tmpFile = $this->fixtureRoot . '/system/abs_main.ent';
+        file_put_contents($tmpFile, '<!ENTITY abs_inc SYSTEM "' . $included . '">');
 
-        if (!is_file($singleFile)) {
-            self::markTestSkipped('Fixture file not found.');
+        try {
+            $resolver = new EntityResolver([], [$tmpFile]);
+            $entities = $resolver->resolve();
+
+            self::assertArrayHasKey('child', $entities);
+            self::assertSame('child-value', $entities['child']);
+        } finally {
+            @unlink($tmpFile);
         }
+    }
+
+
+    #[Test]
+    public function itHandlesCircularSystemReferencesViaVisitedTracking(): void
+    {
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/circular/a.ent']);
+        $entities = $resolver->resolve();
+
+        self::assertIsArray($entities);
+        self::assertArrayHasKey('a_inc', $entities);
+    }
+
+    #[Test]
+    public function itSkipsUnreadableSystemTargets(): void
+    {
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/system/missing_target.ent']);
+        $entities = $resolver->resolve();
+
+        self::assertArrayNotHasKey('missing', $entities);
+    }
 
+    #[Test]
+    public function itResolvesPathsViaProjectRoots(): void
+    {
+        $realRoot = $this->fixtureRoot . '/project_root/real-root';
+
+        $resolver = new EntityResolver(
+            [$realRoot => 'virtual-dir'],
+            [$this->fixtureRoot . '/project_root/main.ent']
+        );
+
+        $entities = $resolver->resolve();
+
+        self::assertArrayHasKey('mapped', $entities);
+        self::assertSame('mapped-value', $entities['mapped']);
+    }
+
+    #[Test]
+    public function itLeavesReferenceUnchangedWhenProjectRootDirectoryNotMatched(): void
+    {
         $resolver = new EntityResolver(
-            [$singleFile, $this->fixtureRoot],
+            ['/some/unrelated/root' => 'unrelated-dir'],
+            [$this->fixtureRoot . '/system/main.ent']
         );
 
-        $files = $resolver->resolve();
+        $entities = $resolver->resolve();
 
-        $sorted = $files;
-        sort($sorted);
+        self::assertArrayHasKey('child', $entities);
+        self::assertSame('child-value', $entities['child']);
+    }
 
-        self::assertSame($sorted, $files);
-        self::assertSame(array_values(array_unique($files)), $files);
+    #[Test]
+    public function itFindsEntityFilesRecursivelyInDirectory(): void
+    {
+        $resolver = new EntityResolver([], [$this->fixtureRoot]);
+        $entities = $resolver->resolve();
+
+        self::assertArrayHasKey('product', $entities);
+        self::assertArrayHasKey('inner', $entities);
+        self::assertArrayNotHasKey('ignored', $entities);
+    }
+
+    #[Test]
+    public function itIgnoresFilesWithWrongExtension(): void
+    {
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/not_an_entity.xml']);
+
+        self::assertSame([], $resolver->resolve());
     }
 
     #[Test]
     public function itSupportsCustomExtension(): void
     {
-        $resolver = new EntityResolver([$this->fixtureRoot], 'xml');
+        $resolver = new EntityResolver(
+            [],
+            [$this->fixtureRoot . '/custom/custom.dtd'],
+            'dtd'
+        );
 
-        $files = $resolver->resolve();
+        $entities = $resolver->resolve();
 
-        foreach ($files as $file) {
-            self::assertStringEndsWith('.xml', $file);
-        }
+        self::assertSame('custom-value', $entities['custom_ent']);
     }
 
     #[Test]
     public function itStripsLeadingDotFromExtension(): void
     {
-        $resolver = new EntityResolver([$this->fixtureRoot], '.ent');
-
-        $files = $resolver->resolve();
+        $resolver = new EntityResolver(
+            [],
+            [$this->fixtureRoot . '/global.ent'],
+            '.ent'
+        );
 
-        self::assertNotEmpty($files);
+        $entities = $resolver->resolve();
 
-        foreach ($files as $file) {
-            self::assertStringEndsWith('.ent', $file);
-        }
+        self::assertSame('Acme Widget', $entities['product']);
     }
 
     #[Test]
-    public function itNormalizesBackslashesInPaths(): void
+    public function itPreservesFirstDefinitionOnDuplicateEntityNames(): void
     {
-        $resolver = new EntityResolver([$this->fixtureRoot]);
+        $resolver = new EntityResolver([], [
+            $this->fixtureRoot . '/duplicates/a_dup.ent',
+            $this->fixtureRoot . '/duplicates/b_dup.ent',
+        ]);
 
-        $files = $resolver->resolve();
+        $entities = $resolver->resolve();
 
-        foreach ($files as $file) {
-            self::assertStringNotContainsString('\\', $file);
-        }
+        self::assertSame('first', $entities['shared']);
+    }
+
+    #[Test]
+    public function itHandlesMultilineEntityValues(): void
+    {
+        $resolver = new EntityResolver([], [$this->fixtureRoot . '/multiline.ent']);
+        $entities = $resolver->resolve();
+
+        self::assertSame('line one line two line three', $entities['block']);
     }
 }
diff --git a/tests/Unit/Path/PathLoaderTest.php b/tests/Unit/Path/PathLoaderTest.php
index d458ccd..5a86056 100644
--- a/tests/Unit/Path/PathLoaderTest.php
+++ b/tests/Unit/Path/PathLoaderTest.php
@@ -26,7 +26,10 @@ protected function setUp(): void
     #[Test]
     public function itFindsXmlFilesRecursively(): void
     {
-        $matcher = new PathMatcher([]);
+        $basePath = realpath(self::FIXTURE_ROOT);
+        assert($basePath !== false);
+
+        $matcher = new PathMatcher($basePath, []);
         $loader = new PathLoader([self::FIXTURE_ROOT], $matcher);
 
         $files = $loader->loadPaths();
@@ -41,7 +44,10 @@ public function itFindsXmlFilesRecursively(): void
     #[Test]
     public function itExcludesMatchedFiles(): void
     {
-        $matcher = new PathMatcher(['*/skeleton.xml']);
+        $basePath = realpath(self::FIXTURE_ROOT);
+        assert($basePath !== false);
+
+        $matcher = new PathMatcher($basePath, ['*/skeleton.xml']);
         $loader = new PathLoader([self::FIXTURE_ROOT], $matcher);
 
         $files = $loader->loadPaths();
@@ -60,7 +66,10 @@ public function itAcceptsSingleFilePaths(): void
             self::markTestSkipped('Fixture file not found.');
         }
 
-        $matcher = new PathMatcher([]);
+        $basePath = realpath(self::FIXTURE_ROOT);
+        assert($basePath !== false);
+
+        $matcher = new PathMatcher($basePath, []);
         $loader = new PathLoader([$singleFile], $matcher);
 
         $files = $loader->loadPaths();
@@ -78,7 +87,10 @@ public function itIgnoresSingleFileWithWrongExtension(): void
             self::markTestSkipped('Fixture dummy.txt not found.');
         }
 
-        $matcher = new PathMatcher([]);
+        $basePath = realpath(self::FIXTURE_ROOT);
+        assert($basePath !== false);
+
+        $matcher = new PathMatcher($basePath, []);
         $loader = new PathLoader([$txtFile], $matcher);
 
         $files = $loader->loadPaths();
@@ -95,8 +107,11 @@ public function itSkipsBrokenSymlinksInDirectoryScan(): void
         // so this is one of the rare cases where runtime creation is justified.
         symlink(self::FIXTURE_ROOT . '/nonexistent_target', $link);
 
+        $basePath = realpath(self::FIXTURE_ROOT);
+        assert($basePath !== false);
+
         try {
-            $matcher = new PathMatcher([]);
+            $matcher = new PathMatcher($basePath, []);
             $loader = new PathLoader([self::FIXTURE_ROOT], $matcher);
 
             $files = $loader->loadPaths();
@@ -112,7 +127,10 @@ public function itSkipsBrokenSymlinksInDirectoryScan(): void
     #[Test]
     public function itSilentlySkipsNonexistentPaths(): void
     {
-        $matcher = new PathMatcher([]);
+        $basePath = realpath(self::FIXTURE_ROOT);
+        assert($basePath !== false);
+
+        $matcher = new PathMatcher($basePath, []);
         $loader = new PathLoader(['/nonexistent/path'], $matcher);
 
         $files = $loader->loadPaths();
@@ -123,7 +141,10 @@ public function itSilentlySkipsNonexistentPaths(): void
     #[Test]
     public function itReturnsSortedDeduplicated(): void
     {
-        $matcher = new PathMatcher([]);
+        $basePath = realpath(self::FIXTURE_ROOT);
+        assert($basePath !== false);
+
+        $matcher = new PathMatcher($basePath, []);
         $loader = new PathLoader(
             [self::FIXTURE_ROOT, self::FIXTURE_ROOT],
             $matcher,
diff --git a/tests/Unit/Path/PathMatcherTest.php b/tests/Unit/Path/PathMatcherTest.php
index 35783d5..9ed9f42 100644
--- a/tests/Unit/Path/PathMatcherTest.php
+++ b/tests/Unit/Path/PathMatcherTest.php
@@ -19,66 +19,89 @@ final class PathMatcherTest extends TestCase
     #[Test]
     #[DataProvider('exclusionProvider')]
     public function itMatchesExclusions(
+        string $basePath,
         array $patterns,
         string $filePath,
         bool $expectedExcluded,
     ): void {
-        $matcher = new PathMatcher($patterns);
+        $matcher = new PathMatcher($basePath, $patterns);
 
         self::assertIsList($patterns);
         self::assertSame($expectedExcluded, $matcher->isExcluded($filePath));
         self::assertSame(!$expectedExcluded, $matcher->isIncluded($filePath));
     }
 
-    /** @return iterable<string, array{list<string>, string, bool}> */
+    /** @return iterable<string, array{string, list<string>, string, bool}> */
     public static function exclusionProvider(): iterable
     {
-        yield 'wildcard matches skeleton.xml anywhere' => [
+        yield 'wildcard matches skeleton.xml in single subdirectory' => [
+            '/project/doc',
             ['*/skeleton.xml'],
             '/project/doc/reference/skeleton.xml',
             true,
         ];
 
         yield 'specific subdirectory pattern' => [
+            '/project',
             ['reference/*/versions.xml'],
-            'reference/strings/versions.xml',
+            '/project/reference/strings/versions.xml',
             true,
         ];
 
         yield 'non-matching pattern leaves file included' => [
+            '/project/doc',
             ['*/skeleton.xml'],
             '/project/doc/reference/strlen.xml',
             false,
         ];
 
         yield 'empty patterns exclude nothing' => [
+            '',
             [],
             '/any/path.xml',
             false,
         ];
 
         yield 'multiple patterns - first matches' => [
+            '/project',
             ['*/foo.xml', '*/bar.xml'],
             '/project/foo.xml',
-            true,
+            false,
         ];
 
-        yield 'multiple patterns - second matches' => [
-            ['*/foo.xml', '*/bar.xml'],
+        yield 'multiple patterns - basename fallback matches' => [
+            '/project',
+            ['foo.xml', 'bar.xml'],
             '/project/bar.xml',
             true,
         ];
 
+        yield 'multiple patterns - first basename matches' => [
+            '/project',
+            ['foo.xml', 'bar.xml'],
+            '/project/foo.xml',
+            true,
+        ];
+
         yield 'backslash paths are normalized' => [
-            ['*/skeleton.xml'],
+            'C:\\project\\doc',
+            ['*.xml'],
             'C:\\project\\doc\\skeleton.xml',
             true,
         ];
 
-        yield 'basename-only match when full path does not match' => [
+        yield 'basename-only pattern matches via fallback' => [
+            '/project/doc',
             ['skeleton.xml'],
             '/project/doc/reference/skeleton.xml',
             true,
         ];
+
+        yield 'deep wildcard matches across directories' => [
+            '/project/doc',
+            ['*/skeleton.xml'],
+            '/project/doc/a/b/skeleton.xml',
+            true,
+        ];
     }
 }
diff --git a/tests/Unit/Runner/EntityPreprocessorTest.php b/tests/Unit/Runner/EntityPreprocessorTest.php
index e144265..936b378 100644
--- a/tests/Unit/Runner/EntityPreprocessorTest.php
+++ b/tests/Unit/Runner/EntityPreprocessorTest.php
@@ -13,49 +13,53 @@
 #[CoversClass(EntityPreprocessor::class)]
 final class EntityPreprocessorTest extends TestCase
 {
-    private EntityPreprocessor $preprocessor;
-
-    protected function setUp(): void
-    {
-        $this->preprocessor = new EntityPreprocessor();
-    }
-
     #[Test]
     public function itPreservesPredefinedXmlEntities(): void
     {
+        $preprocessor = new EntityPreprocessor([]);
+
         $input = '<simpara>1 &lt; 2 &amp; 3 &gt; 0 &quot;hi&quot; &apos;yo&apos;</simpara>';
 
-        $result = $this->preprocessor->neutralize($input);
+        $result = $preprocessor->process($input);
 
         self::assertSame($input, $result);
     }
 
     #[Test]
-    public function itRemovesCustomEntities(): void
+    public function itExpandsKnownEntities(): void
     {
+        $preprocessor = new EntityPreprocessor([
+            'php.ini' => 'php.ini',
+            'configuration.file' => 'configuration file',
+        ]);
+
         $input = '<simpara>&php.ini; is a &configuration.file; thing.</simpara>';
 
-        $result = $this->preprocessor->neutralize($input);
+        $result = $preprocessor->process($input);
 
-        self::assertSame('<simpara> is a  thing.</simpara>', $result);
+        self::assertSame('<simpara>php.ini is a configuration file thing.</simpara>', $result);
     }
 
     #[Test]
-    public function itSubstitutesCustomReplacementString(): void
+    public function itLeavesUnknownEntitiesUnchanged(): void
     {
-        $preprocessor = new EntityPreprocessor('[ENTITY]');
+        $preprocessor = new EntityPreprocessor([]);
 
-        $result = $preprocessor->neutralize('<simpara>&php.ini; is important.</simpara>');
+        $input = '<simpara>&unknown.entity; stays.</simpara>';
 
-        self::assertSame('<simpara>[ENTITY] is important.</simpara>', $result);
+        $result = $preprocessor->process($input);
+
+        self::assertSame($input, $result);
     }
 
     #[Test]
     public function itPreservesNumericCharacterReferences(): void
     {
+        $preprocessor = new EntityPreprocessor([]);
+
         $input = '<simpara>&#169; &#x00A9;</simpara>';
 
-        $result = $this->preprocessor->neutralize($input);
+        $result = $preprocessor->process($input);
 
         self::assertSame($input, $result);
     }
@@ -63,53 +67,65 @@ public function itPreservesNumericCharacterReferences(): void
     #[Test]
     public function itHandlesMixedEntityTypes(): void
     {
+        $preprocessor = new EntityPreprocessor([
+            'custom.entity' => 'replaced',
+        ]);
+
         $input = '<simpara>&amp; &custom.entity; &#169; &lt;</simpara>';
 
-        $result = $this->preprocessor->neutralize($input);
+        $result = $preprocessor->process($input);
 
-        self::assertSame('<simpara>&amp;  &#169; &lt;</simpara>', $result);
+        self::assertSame('<simpara>&amp; replaced &#169; &lt;</simpara>', $result);
     }
 
     #[Test]
     public function itReturnsUnchangedContentWithNoEntities(): void
     {
+        $preprocessor = new EntityPreprocessor([]);
+
         $input = '<simpara>No entities here.</simpara>';
 
-        $result = $this->preprocessor->neutralize($input);
+        $result = $preprocessor->process($input);
 
         self::assertSame($input, $result);
     }
 
+    /** @param array<string, string> $entities */
     #[Test]
     #[DataProvider('entityNameProvider')]
-    public function itHandlesVariousEntityNameFormats(string $input, string $expected): void
+    public function itHandlesVariousEntityNameFormats(string $input, string $expected, array $entities): void
     {
-        $result = $this->preprocessor->neutralize($input);
+        $preprocessor = new EntityPreprocessor($entities);
+
+        $result = $preprocessor->process($input);
 
         self::assertSame($expected, $result);
     }
 
-    /** @return array<string, array{string, string}> */
+    /** @return array<string, array{string, string, array<string, string>}> */
     public static function entityNameProvider(): array
     {
         return [
-            'simple'           => ['&foo;', ''],
-            'dotted'           => ['&foo.bar;', ''],
-            'hyphenated'       => ['&foo-bar;', ''],
-            'underscored'      => ['&foo_bar;', ''],
-            'predefined amp'   => ['&amp;', '&amp;'],
-            'predefined lt'    => ['&lt;', '&lt;'],
-            'numeric decimal'  => ['&#8212;', '&#8212;'],
-            'numeric hex'      => ['&#x2014;', '&#x2014;'],
+            'simple' => ['&foo;', 'FOO', ['foo' => 'FOO']],
+            'dotted' => ['&foo.bar;', 'FOOBAR', ['foo.bar' => 'FOOBAR']],
+            'hyphenated' => ['&foo-bar;', 'FOOB', ['foo-bar' => 'FOOB']],
+            'underscored' => ['&foo_bar;', 'FB', ['foo_bar' => 'FB']],
+            'unknown' => ['&unknown;', '&unknown;', []],
+            'predefined amp' => ['&amp;', '&amp;', []],
+            'predefined lt' => ['&lt;', '&lt;', []],
+            'numeric decimal' => ['&#8212;', '&#8212;', []],
+            'numeric hex' => ['&#x2014;', '&#x2014;', []],
         ];
     }
 
     #[Test]
     public function itStripsSimpleDoctype(): void
     {
+        $preprocessor = new EntityPreprocessor([]);
+
         $input = '<?xml version="1.0"?><!DOCTYPE book SYSTEM "docbook.dtd"><book/>';
 
-        $result = $this->preprocessor->stripDoctype($input);
+        $result = $preprocessor->process($input);
 
         self::assertSame('<?xml version="1.0"?><book/>', $result);
     }
@@ -117,6 +133,8 @@ public function itStripsSimpleDoctype(): void
     #[Test]
     public function itStripsDoctypeWithInternalSubset(): void
     {
+        $preprocessor = new EntityPreprocessor([]);
+
         $input = <<<'XML'
 <?xml version="1.0"?>
 <!DOCTYPE book [
@@ -126,7 +144,7 @@ public function itStripsDoctypeWithInternalSubset(): void
 <book/>
 XML;
 
-        $result = $this->preprocessor->stripDoctype($input);
+        $result = $preprocessor->process($input);
 
         self::assertStringNotContainsString('DOCTYPE', $result);
         self::assertStringNotContainsString('ENTITY', $result);
@@ -136,9 +154,11 @@ public function itStripsDoctypeWithInternalSubset(): void
     #[Test]
     public function itLeavesContentUnchangedWhenNoDoctypePresent(): void
     {
+        $preprocessor = new EntityPreprocessor([]);
+
         $input = '<?xml version="1.0"?><book/>';
 
-        $result = $this->preprocessor->stripDoctype($input);
+        $result = $preprocessor->process($input);
 
         self::assertSame($input, $result);
     }
@@ -146,9 +166,11 @@ public function itLeavesContentUnchangedWhenNoDoctypePresent(): void
     #[Test]
     public function itStripsDoctypeContainingQuotedAngleBrackets(): void
     {
+        $preprocessor = new EntityPreprocessor([]);
+
         $input = '<!DOCTYPE book [ <!ENTITY x "<simpara>hi</simpara>"> ]><book/>';
 
-        $result = $this->preprocessor->stripDoctype($input);
+        $result = $preprocessor->process($input);
 
         self::assertSame('<book/>', $result);
     }
@@ -156,6 +178,11 @@ public function itStripsDoctypeContainingQuotedAngleBrackets(): void
     #[Test]
     public function itProducesParseableXmlFromFullPipeline(): void
     {
+        $preprocessor = new EntityPreprocessor([
+            'link.superglobals' => '<link linkend="language.variables.superglobals">superglobals</link>',
+            'php.ini' => 'php.ini',
+        ]);
+
         $input = <<<'XML'
 <?xml version="1.0"?>
 <!DOCTYPE chapter [
@@ -167,7 +194,7 @@ public function itProducesParseableXmlFromFullPipeline(): void
 </chapter>
 XML;
 
-        $result = $this->preprocessor->process($input);
+        $result = $preprocessor->process($input);
 
         $dom = new \DOMDocument();
         $loaded = $dom->loadXML($result);
@@ -176,8 +203,12 @@ public function itProducesParseableXmlFromFullPipeline(): void
     }
 
     #[Test]
-    public function itStripsDoctypeAndNeutralizesEntitiesInProcess(): void
+    public function itStripsDoctypeAndExpandsEntitiesInProcess(): void
     {
+        $preprocessor = new EntityPreprocessor([
+            'link.superglobals' => '<link>superglobals</link>',
+        ]);
+
         $input = <<<'XML'
 <?xml version="1.0"?>
 <!DOCTYPE chapter SYSTEM "docbook.dtd">
@@ -186,10 +217,11 @@ public function itStripsDoctypeAndNeutralizesEntitiesInProcess(): void
 </chapter>
 XML;
 
-        $result = $this->preprocessor->process($input);
+        $result = $preprocessor->process($input);
 
         self::assertStringNotContainsString('DOCTYPE', $result);
         self::assertStringNotContainsString('&link.superglobals;', $result);
+        self::assertStringContainsString('<link>superglobals</link>', $result);
         self::assertStringContainsString('&amp;', $result);
         self::assertStringContainsString('<chapter>', $result);
     }
@@ -197,10 +229,74 @@ public function itStripsDoctypeAndNeutralizesEntitiesInProcess(): void
     #[Test]
     public function itReturnsOriginalContentWhenDoctypeIsNotClosed(): void
     {
+        $preprocessor = new EntityPreprocessor([]);
+
         $input = '<!DOCTYPE book [ <!ENTITY foo "bar" ><book/>';
 
-        $result = $this->preprocessor->stripDoctype($input);
+        $result = $preprocessor->process($input);
 
+        // stripDoctype returns original when unclosed, then expandEntities runs but no known entities
         self::assertSame($input, $result);
     }
+
+    #[Test]
+    public function itResolvesNestedEntities(): void
+    {
+        $preprocessor = new EntityPreprocessor([
+            'inner' => 'INNER_VALUE',
+            'outer' => 'before &inner; after',
+        ]);
+
+        $input = '<root>&outer;</root>';
+
+        $result = $preprocessor->process($input);
+
+        self::assertSame('<root>before INNER_VALUE after</root>', $result);
+    }
+
+    #[Test]
+    public function itStripsXmlDeclarationFromExpandedEntityValues(): void
+    {
+        $preprocessor = new EntityPreprocessor([
+            'included' => '<?xml version="1.0" encoding="UTF-8"?><para>included content</para>',
+        ]);
+
+        $input = '<root>&included;</root>';
+
+        $result = $preprocessor->process($input);
+
+        self::assertStringNotContainsString('<?xml', $result);
+        self::assertStringContainsString('<para>included content</para>', $result);
+    }
+
+    #[Test]
+    public function itPreservesXmlComments(): void
+    {
+        $preprocessor = new EntityPreprocessor([
+            'foo' => 'expanded',
+        ]);
+
+        $input = '<root><!-- &foo; should not expand -->&foo;</root>';
+
+        $result = $preprocessor->process($input);
+
+        self::assertStringContainsString('<!-- &foo; should not expand -->', $result);
+        self::assertStringContainsString('expanded', $result);
+    }
+
+    #[Test]
+    public function itHandlesMaxDepthWithoutInfiniteLoop(): void
+    {
+        // Create a self-referencing entity (would loop forever without depth limit)
+        $preprocessor = new EntityPreprocessor([
+            'loop' => '&loop;',
+        ]);
+
+        $input = '<root>&loop;</root>';
+
+        // Should terminate without hanging due to the maxDepth guard
+        $result = $preprocessor->process($input);
+
+        self::assertIsString($result);
+    }
 }
diff --git a/tests/Unit/Runner/SniffRunnerTest.php b/tests/Unit/Runner/SniffRunnerTest.php
index 3646103..971803b 100644
--- a/tests/Unit/Runner/SniffRunnerTest.php
+++ b/tests/Unit/Runner/SniffRunnerTest.php
@@ -6,6 +6,7 @@
 
 use DocbookCS\Config\ConfigData;
 use DocbookCS\Config\SniffEntry;
+use DocbookCS\Path\EntityResolver;
 use DocbookCS\Path\PathLoader;
 use DocbookCS\Path\PathMatcher;
 use DocbookCS\Progress\NullProgress;
@@ -28,6 +29,7 @@
 #[CoversClass(PathMatcher::class)]
 #[CoversClass(NullProgress::class)]
 #[CoversClass(EntityPreprocessor::class)]
+#[CoversClass(EntityResolver::class)]
 #[CoversClass(XmlFileProcessor::class)]
 #[CoversClass(Report::class)]
 #[CoversClass(SniffEntry::class)]
@@ -41,6 +43,7 @@ final class SniffRunnerTest extends TestCase
     private function createConfig(array $sniffs = []): ConfigData
     {
         return new ConfigData(
+            [],
             $sniffs,
             [self::FIXTURE_DIR],
             [],
@@ -121,8 +124,7 @@ public function setProperty(string $name, string $value): void
             }
         };
 
-        $entry = new SniffEntry($sniff::class);
-        $config = $this->createConfig(sniffs: [$entry]);
+        $config = $this->createConfig(sniffs: [new SniffEntry($sniff::class)]);
 
         $runner = new SniffRunner();
         $report = $runner->run($config);
@@ -159,8 +161,7 @@ public function setProperty(string $name, string $value): void
             }
         };
 
-        $entry = new SniffEntry($sniff::class);
-        $config = $this->createConfig(sniffs: [$entry]);
+        $config = $this->createConfig(sniffs: [new SniffEntry($sniff::class)]);
 
         $runner = new SniffRunner();
         $report = $runner->run($config);
@@ -195,8 +196,7 @@ public function process(\DOMDocument $document, string $content, string $filePat
             }
         };
 
-        $entry = new SniffEntry($sniffClass::class, ['someProp' => 'someValue']);
-        $config = $this->createConfig(sniffs: [$entry]);
+        $config = $this->createConfig(sniffs: [new SniffEntry($sniffClass::class, ['someProp' => 'someValue'])]);
 
         $runner = new SniffRunner();
         $runner->run($config);
@@ -207,8 +207,7 @@ public function process(\DOMDocument $document, string $content, string $filePat
     #[Test]
     public function itThrowsWhenSniffClassDoesNotExist(): void
     {
-        $entry = new SniffEntry('NonExistent\\FakeSniff', []);
-        $config = $this->createConfig(sniffs: [$entry]);
+        $config = $this->createConfig(sniffs: [new SniffEntry('NonExistent\\FakeSniff')]);
 
         $runner = new SniffRunner();
 
@@ -221,8 +220,7 @@ public function itThrowsWhenSniffClassDoesNotExist(): void
     #[Test]
     public function itThrowsWhenClassDoesNotImplementSniffInterface(): void
     {
-        $entry = new SniffEntry(\stdClass::class, []);
-        $config = $this->createConfig(sniffs: [$entry]);
+        $config = $this->createConfig(sniffs: [new SniffEntry(\stdClass::class)]);
 
         $runner = new SniffRunner();
 
diff --git a/tests/Unit/Runner/XmlFileProcessorTest.php b/tests/Unit/Runner/XmlFileProcessorTest.php
index f35e3c4..83c0bab 100644
--- a/tests/Unit/Runner/XmlFileProcessorTest.php
+++ b/tests/Unit/Runner/XmlFileProcessorTest.php
@@ -8,8 +8,8 @@
 use DocbookCS\Report\Report;
 use DocbookCS\Report\Severity;
 use DocbookCS\Report\Violation;
-use DocbookCS\Runner\XmlFileProcessor;
 use DocbookCS\Runner\EntityPreprocessor;
+use DocbookCS\Runner\XmlFileProcessor;
 use DocbookCS\Sniff\SniffInterface;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
@@ -23,223 +23,184 @@
 final class XmlFileProcessorTest extends TestCase
 {
     #[Test]
-    public function itReportsParseErrorForInvalidXml(): void
+    public function itReportsParseErrors(): void
     {
-        $processor = new XmlFileProcessor([]);
+        $report = $this->processor()->processString('<broken><unclosed>', 'bad.xml');
 
-        $fileReport = $processor->processString('<broken><unclosed>', 'bad.xml');
-
-        self::assertTrue($fileReport->hasViolations());
-        self::assertStringContainsString(
-            'XML parse error',
-            $fileReport->getViolations()[0]->message,
-        );
+        $this->assertInternalError($report, 'XML parse error');
     }
 
     #[Test]
-    public function itReportsErrorForMissingFile(): void
+    public function itReportsMissingFiles(): void
     {
-        $processor = new XmlFileProcessor([]);
+        $report = $this->processor()->processFile('/nonexistent/path/file.xml');
 
-        $fileReport = $processor->processFile('/nonexistent/path/file.xml');
-
-        self::assertTrue($fileReport->hasViolations());
-        self::assertStringContainsString(
-            'Could not read file',
-            $fileReport->getViolations()[0]->message,
-        );
+        $this->assertInternalError($report, 'Could not read file');
     }
 
     #[Test]
-    public function itUsesReportPathInsteadOfFilePathWhenProvided(): void
+    public function itPrefersReportPathOverFilePath(): void
     {
-        $processor = new XmlFileProcessor([]);
-
-        $fileReport = $processor->processFile('/nonexistent/path/file.xml', [], 'relative/file.xml');
+        $report = $this->processor()->processFile(
+            '/nonexistent/path/file.xml',
+            [],
+            'relative/file.xml'
+        );
 
-        self::assertSame('relative/file.xml', $fileReport->filePath);
+        self::assertSame('relative/file.xml', $report->filePath);
     }
 
     #[Test]
-    public function itParsesCleanXmlWithNoViolations(): void
+    public function itAcceptsValidXmlWithoutViolations(): void
     {
-        $processor = new XmlFileProcessor([]);
-
-        $xml = <<<'XML'
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter>
-  <simpara>Simple text.</simpara>
-</chapter>
-XML;
+        $xml = $this->xml('<chapter><simpara>ok</simpara></chapter>');
 
-        $fileReport = $processor->processString($xml, 'clean.xml');
+        $report = $this->processor()->processString($xml);
 
-        self::assertFalse($fileReport->hasViolations());
+        self::assertFalse($report->hasViolations());
     }
 
     #[Test]
-    public function itNeutralizesEntitiesBeforeParsing(): void
+    public function itHandlesEntitiesWithoutParseErrors(): void
     {
-        $processor = new XmlFileProcessor([]);
+        $xml = $this->xml(
+            '<!DOCTYPE chapter SYSTEM "docbook.dtd">
+        <chapter>
+          <simpara>&link.superglobals; &php.ini; &amp;</simpara>
+        </chapter>'
+        );
 
-        $xml = <<<'XML'
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter SYSTEM "docbook.dtd">
-<chapter>
-  <simpara>&link.superglobals; are &php.ini; things and &amp; works.</simpara>
-</chapter>
-XML;
+        $processor = $this->processor([], new EntityPreprocessor([
+            'link.superglobals' => '',
+            'php.ini' => '',
+        ]));
 
-        $fileReport = $processor->processString($xml, 'entity-test.xml');
+        $report = $processor->processString($xml);
 
-        $parseErrors = array_filter(
-            $fileReport->getViolations(),
-            static fn($v) => $v->sniffCode === 'DocbookCS.Internal',
+        self::assertCount(
+            0,
+            array_filter(
+                $report->getViolations(),
+                fn($v) => $v->sniffCode === 'DocbookCS.Internal'
+            )
         );
-
-        self::assertCount(0, $parseErrors);
     }
 
     #[Test]
-    public function itAcceptsCustomPreprocessor(): void
+    public function itUsesCustomPreprocessor(): void
     {
-        $preprocessor = new EntityPreprocessor('[REPLACED]');
-        $processor    = new XmlFileProcessor([], $preprocessor);
+        $processor = $this->processor([], new EntityPreprocessor([
+            'custom.entity' => '[X]',
+        ]));
 
-        $xml = <<<'XML'
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter>
-  <simpara>&custom.entity; text.</simpara>
-</chapter>
-XML;
+        $xml = $this->xml('<chapter><simpara>&custom.entity;</simpara></chapter>');
 
-        $fileReport = $processor->processString($xml, 'custom.xml');
+        $report = $processor->processString($xml);
 
-        $parseErrors = array_filter(
-            $fileReport->getViolations(),
-            static fn($v) => $v->sniffCode === 'DocbookCS.Internal',
+        self::assertCount(
+            0,
+            array_filter(
+                $report->getViolations(),
+                fn($v) => $v->sniffCode === 'DocbookCS.Internal'
+            )
         );
-
-        self::assertCount(0, $parseErrors);
     }
 
     #[Test]
-    public function itReturnsZeroViolationsForEmptySniffList(): void
+    public function itReturnsZeroViolationsWithoutSniffs(): void
     {
-        $processor = new XmlFileProcessor([]);
-
-        $xml = <<<'XML'
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter><para>Hello.</para></chapter>
-XML;
+        $xml = $this->xml('<chapter><para>Hello</para></chapter>');
 
-        $fileReport = $processor->processString($xml, 'empty-sniffs.xml');
+        $report = $this->processor()->processString($xml);
 
-        self::assertSame(0, $fileReport->getViolationCount());
+        self::assertSame(0, $report->getViolationCount());
     }
 
     #[Test]
-    public function itReturnsAllViolationsWhenNoChangedLinesGiven(): void
+    public function itReturnsAllViolationsWithoutDiffFiltering(): void
     {
-        $sniff = $this->makeSniffWithViolationsAtLines([3, 5]);
-        $processor = new XmlFileProcessor([$sniff]);
-
-        $xml = <<<'XML'
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter>
-  <simpara>line 3</simpara>
-  <simpara>line 4</simpara>
-  <simpara>line 5</simpara>
-</chapter>
-XML;
+        $sniff = $this->sniff([3, 5]);
+
+        $xml = $this->xml(
+            '<chapter>
+          <simpara>3</simpara>
+          <simpara>4</simpara>
+          <simpara>5</simpara>
+        </chapter>'
+        );
 
-        $fileReport = $processor->processString($xml, 'all.xml');
+        $report = $this->processor([$sniff])->processString($xml);
 
-        self::assertSame(2, $fileReport->getViolationCount());
+        self::assertSame(2, $report->getViolationCount());
     }
 
     #[Test]
-    public function itFiltersViolationsToChangedLinesWhenDiffProvided(): void
+    public function itFiltersViolationsByChangedLines(): void
     {
-        $sniff = $this->makeSniffWithViolationsAtLines([3, 5]);
-        $processor = new XmlFileProcessor([$sniff]);
-
-        $xml = <<<'XML'
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter>
-  <simpara>line 3</simpara>
-  <simpara>line 4</simpara>
-  <simpara>line 5</simpara>
-</chapter>
-XML;
+        $sniff = $this->sniff([3, 5]);
+
+        $xml = $this->xml(
+            '<chapter>
+          <simpara>3</simpara>
+          <simpara>4</simpara>
+          <simpara>5</simpara>
+        </chapter>'
+        );
 
-        // Only line 3 changed — violation at line 5 should be suppressed.
-        $fileReport = $processor->processString($xml, 'filtered.xml', [3]);
+        $report = $this->processor([$sniff])->processString($xml, 'f.xml', [3]);
 
-        self::assertSame(1, $fileReport->getViolationCount());
-        self::assertSame(3, $fileReport->getViolations()[0]->line);
+        self::assertSame(1, $report->getViolationCount());
+        self::assertSame(3, $report->getViolations()[0]->line);
     }
 
     #[Test]
-    public function itIncludesViolationWhenChangedLineIsInsideElement(): void
+    public function itExpandsElementSpanForNestedChanges(): void
     {
-        // Violation is on the <para> opening tag (line 3), but the changed
-        // content is on line 4 (inside the element). The filtering must
-        // expand to the parent element's span.
-        $sniff = $this->makeSniffWithViolationsAtLines([3]);
-        $processor = new XmlFileProcessor([$sniff]);
-
-        $xml = <<<'XML'
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter>
-  <para>
-    content on line 4
-  </para>
-</chapter>
-XML;
+        $sniff = $this->sniff([3]);
+
+        $xml = $this->xml(
+            '<chapter>
+          <para>
+            <emphasis>
+              <literal>line 6</literal>
+            </emphasis>
+          </para>
+        </chapter>'
+        );
 
-        // Line 3 is the <para> opening; changed line is 4 (inside the element).
-        $fileReport = $processor->processString($xml, 'inner.xml', [4]);
+        $report = $this->processor([$sniff])->processString($xml, 'x.xml', [6]);
 
-        self::assertSame(1, $fileReport->getViolationCount());
-        self::assertSame(3, $fileReport->getViolations()[0]->line);
+        self::assertSame(1, $report->getViolationCount());
     }
 
     #[Test]
-    public function itSuppressesViolationWhenNoChangedLineIsInsideElement(): void
+    public function itIgnoresChangesOutsideElementSpan(): void
     {
-        // Violation at line 3 (<para>), but changed line is 7 (a different element).
-        $sniff = $this->makeSniffWithViolationsAtLines([3]);
-        $processor = new XmlFileProcessor([$sniff]);
+        $sniff = $this->sniff([3]);
 
-        $xml = <<<'XML'
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter>
-  <para>
-    content
-  </para>
-  <simpara>other element at line 7</simpara>
-</chapter>
-XML;
+        $xml = $this->xml(
+            '<chapter>
+          <para>text</para>
+          <simpara>line 7</simpara>
+        </chapter>'
+        );
 
-        $fileReport = $processor->processString($xml, 'suppress.xml', [7]);
+        $report = $this->processor([$sniff])->processString($xml, 'x.xml', [7]);
 
-        self::assertSame(0, $fileReport->getViolationCount());
+        self::assertSame(0, $report->getViolationCount());
     }
 
     #[Test]
-    public function itKeepsInternalErrorsRegardlessOfChangedLines(): void
+    public function itKeepsInternalErrorsEvenWithDiffFiltering(): void
     {
-        $processor = new XmlFileProcessor([]);
-
-        $fileReport = $processor->processFile('/nonexistent/path/file.xml', [42]);
+        $report = $this->processor()->processFile('/nonexistent/path/file.xml', [42]);
 
-        self::assertTrue($fileReport->hasViolations());
-        self::assertSame('DocbookCS.Internal', $fileReport->getViolations()[0]->sniffCode);
+        self::assertTrue($report->hasViolations());
+        self::assertSame('DocbookCS.Internal', $report->getViolations()[0]->sniffCode);
     }
 
     /** @param list<int> $lines */
-    private function makeSniffWithViolationsAtLines(array $lines): SniffInterface
+    private function sniff(array $lines): SniffInterface
     {
         return new class ($lines) implements SniffInterface {
             /** @param list<int> $lines */
@@ -260,9 +221,9 @@ public function process(\DOMDocument $document, string $content, string $filePat
                         filePath: $filePath,
                         line: $line,
                         message: "violation at line {$line}",
-                        severity: Severity::WARNING,
+                        severity: Severity::WARNING
                     ),
-                    $this->lines,
+                    $this->lines
                 );
             }
 
@@ -272,50 +233,27 @@ public function setProperty(string $name, string $value): void
         };
     }
 
-    #[Test]
-    public function itExpandsViolationSpanThroughDeeplyNestedElements(): void
+    /** @param list<SniffInterface> $sniffs */
+    private function processor(array $sniffs = [], ?EntityPreprocessor $pre = null): XmlFileProcessor
     {
-        $sniff = $this->makeSniffWithViolationsAtLines([3]);
-        $processor = new XmlFileProcessor([$sniff]);
-
-        $xml = <<<'XML'
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter>
-  <para>
-    <emphasis>
-      <literal>
-        deeply nested content on line 6
-      </literal>
-    </emphasis>
-  </para>
-</chapter>
-XML;
-
-        $fileReport = $processor->processString($xml, 'deep-nest.xml', [6]);
-
-        self::assertSame(1, $fileReport->getViolationCount());
-        self::assertSame(3, $fileReport->getViolations()[0]->line);
+        return new XmlFileProcessor(
+            $sniffs,
+            $pre ?? new EntityPreprocessor([]) // always pass array
+        );
     }
 
-    #[Test]
-    public function itDoesNotExpandSpanWhenNestedElementEndsBeforeMax(): void
+    private function xml(string $body): string
     {
-        $sniff = $this->makeSniffWithViolationsAtLines([3]);
-        $processor = new XmlFileProcessor([$sniff]);
-
-        $xml = <<<'XML'
+        return <<<XML
 <?xml version="1.0" encoding="UTF-8"?>
-<chapter>
-  <para>
-    <emphasis>short</emphasis>
-    text content stretching to line 5
-  </para>
-  <simpara>unrelated line 7</simpara>
-</chapter>
+$body
 XML;
+    }
 
-        $fileReport = $processor->processString($xml, 'shallow-nest.xml', [7]);
-
-        self::assertSame(0, $fileReport->getViolationCount());
+    private function assertInternalError(FileReport $report, string $messagePart): void
+    {
+        self::assertTrue($report->hasViolations());
+        self::assertSame('DocbookCS.Internal', $report->getViolations()[0]->sniffCode);
+        self::assertStringContainsString($messagePart, $report->getViolations()[0]->message);
     }
 }
diff --git a/tests/Unit/Sniff/WhitespaceSniffTest.php b/tests/Unit/Sniff/WhitespaceSniffTest.php
new file mode 100644
index 0000000..17d81c0
--- /dev/null
+++ b/tests/Unit/Sniff/WhitespaceSniffTest.php
@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DocbookCS\Tests\Unit\Sniff;
+
+use DocbookCS\Report\Violation;
+use DocbookCS\Sniff\WhitespaceSniff;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(WhitespaceSniff::class)]
+#[CoversClass(Violation::class)]
+final class WhitespaceSniffTest extends TestCase
+{
+    private function createDocument(string $xml): \DOMDocument
+    {
+        $doc = new \DOMDocument();
+        $doc->loadXML($xml);
+
+        return $doc;
+    }
+
+    #[Test]
+    public function itReturnsEmptyWhenNoViolations(): void
+    {
+        $content = "<root>" . PHP_EOL .
+            "    <tag>value</tag>" . PHP_EOL .
+            "</root>";
+
+        $doc = $this->createDocument($content);
+        $violations = (new WhitespaceSniff())->process($doc, $content, 'file.xml');
+
+        self::assertSame([], $violations);
+    }
+
+    #[Test]
+    public function itDetectsTrailingWhitespace(): void
+    {
+        $content = "<root> " . PHP_EOL .
+            "</root>";
+
+        $doc = $this->createDocument($content);
+        $violations = (new WhitespaceSniff())->process($doc, $content, 'file.xml');
+
+        self::assertCount(1, $violations);
+        self::assertSame('Trailing whitespace detected.', $violations[0]->message);
+        self::assertSame(1, $violations[0]->line);
+    }
+
+    #[Test]
+    public function itDetectsSpaceBeforeTab(): void
+    {
+        $content = "<root>" . PHP_EOL .
+            " \t<tag/>" . PHP_EOL .
+            "</root>";
+
+        $doc = $this->createDocument($content);
+        $violations = (new WhitespaceSniff())->process($doc, $content, 'file.xml');
+
+        self::assertCount(1, $violations);
+        self::assertSame('Mixed tabs and spaces in indentation.', $violations[0]->message);
+        self::assertSame(2, $violations[0]->line);
+    }
+
+    #[Test]
+    public function itDetectsMixedIndentationSpacesThenTabs(): void
+    {
+        $content = "<root>" . PHP_EOL .
+            "  \t<tag/>" . PHP_EOL .
+            "</root>";
+
+        $doc = $this->createDocument($content);
+        $violations = (new WhitespaceSniff())->process($doc, $content, 'file.xml');
+
+        self::assertCount(1, $violations);
+        self::assertSame('Mixed tabs and spaces in indentation.', $violations[0]->message);
+    }
+
+    #[Test]
+    public function itDetectsMixedIndentationTabsThenSpaces(): void
+    {
+        $content = "<root>" . PHP_EOL .
+            "\t  \t<tag/>" . PHP_EOL .
+            "</root>";
+
+        $doc = $this->createDocument($content);
+        $violations = (new WhitespaceSniff())->process($doc, $content, 'file.xml');
+
+        self::assertCount(1, $violations);
+        self::assertSame('Mixed tabs and spaces in indentation.', $violations[0]->message);
+    }
+
+    #[Test]
+    public function itHandlesMultipleViolations(): void
+    {
+        $content = "<root> " . PHP_EOL .
+            " \t<tag/>" . PHP_EOL .
+            "\t  \t<tag/>" . PHP_EOL .
+            "</root>";
+
+        $doc = $this->createDocument($content);
+        $violations = (new WhitespaceSniff())->process($doc, $content, 'file.xml');
+
+        self::assertCount(3, $violations);
+    }
+
+    #[Test]
+    public function itIncludesFilePathInViolation(): void
+    {
+        $content = "<root> " . PHP_EOL .
+            "</root>";
+
+        $doc = $this->createDocument($content);
+        $violations = (new WhitespaceSniff())->process($doc, $content, 'my-file.xml');
+
+        self::assertCount(1, $violations);
+        self::assertSame('my-file.xml', $violations[0]->filePath);
+    }
+}
diff --git a/tests/fixtures/entity_tree/broken.ent b/tests/fixtures/entity_tree/broken.ent
new file mode 100644
index 0000000..2cad3ee
--- /dev/null
+++ b/tests/fixtures/entity_tree/broken.ent
@@ -0,0 +1 @@
+<!ENTITY this is not valid syntax
diff --git a/tests/fixtures/entity_tree/circular/a.ent b/tests/fixtures/entity_tree/circular/a.ent
new file mode 100644
index 0000000..b9879c9
--- /dev/null
+++ b/tests/fixtures/entity_tree/circular/a.ent
@@ -0,0 +1 @@
+<!ENTITY a_inc SYSTEM "b.ent">
diff --git a/tests/fixtures/entity_tree/circular/b.ent b/tests/fixtures/entity_tree/circular/b.ent
new file mode 100644
index 0000000..3c0d653
--- /dev/null
+++ b/tests/fixtures/entity_tree/circular/b.ent
@@ -0,0 +1 @@
+<!ENTITY b_inc SYSTEM "a.ent">
diff --git a/tests/fixtures/entity_tree/custom/custom.dtd b/tests/fixtures/entity_tree/custom/custom.dtd
new file mode 100644
index 0000000..bc5df96
--- /dev/null
+++ b/tests/fixtures/entity_tree/custom/custom.dtd
@@ -0,0 +1 @@
+<!ENTITY custom_ent "custom-value">
diff --git a/tests/fixtures/entity_tree/duplicates/a_dup.ent b/tests/fixtures/entity_tree/duplicates/a_dup.ent
new file mode 100644
index 0000000..1057c32
--- /dev/null
+++ b/tests/fixtures/entity_tree/duplicates/a_dup.ent
@@ -0,0 +1 @@
+<!ENTITY shared "first">
diff --git a/tests/fixtures/entity_tree/duplicates/b_dup.ent b/tests/fixtures/entity_tree/duplicates/b_dup.ent
new file mode 100644
index 0000000..91528f8
--- /dev/null
+++ b/tests/fixtures/entity_tree/duplicates/b_dup.ent
@@ -0,0 +1 @@
+<!ENTITY shared "second">
diff --git a/tests/fixtures/entity_tree/global.ent b/tests/fixtures/entity_tree/global.ent
index 0df9c6c..51563f9 100644
--- a/tests/fixtures/entity_tree/global.ent
+++ b/tests/fixtures/entity_tree/global.ent
@@ -1 +1,3 @@
-<!ENTITY global.entity "Global entity value">
+<!ENTITY product "Acme Widget">
+<!ENTITY version "1.0.0">
+<!ENTITY greeting "  hello   world  ">
diff --git a/tests/fixtures/entity_tree/multiline.ent b/tests/fixtures/entity_tree/multiline.ent
new file mode 100644
index 0000000..9ca9d9c
--- /dev/null
+++ b/tests/fixtures/entity_tree/multiline.ent
@@ -0,0 +1,3 @@
+<!ENTITY block "line one
+line two
+line three">
diff --git a/tests/fixtures/entity_tree/nested/deep/inner.ent b/tests/fixtures/entity_tree/nested/deep/inner.ent
new file mode 100644
index 0000000..ec8cce3
--- /dev/null
+++ b/tests/fixtures/entity_tree/nested/deep/inner.ent
@@ -0,0 +1 @@
+<!ENTITY inner "inner-value">
diff --git a/tests/fixtures/entity_tree/not_an_entity.xml b/tests/fixtures/entity_tree/not_an_entity.xml
index dfa8d65..ee80ed7 100644
--- a/tests/fixtures/entity_tree/not_an_entity.xml
+++ b/tests/fixtures/entity_tree/not_an_entity.xml
@@ -1,2 +1 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<root/>
+<!ENTITY ignored "should-not-be-parsed">
diff --git a/tests/fixtures/entity_tree/plain.ent b/tests/fixtures/entity_tree/plain.ent
new file mode 100644
index 0000000..86724fc
--- /dev/null
+++ b/tests/fixtures/entity_tree/plain.ent
@@ -0,0 +1 @@
+<root>just some XML, no entities here</root>
diff --git a/tests/fixtures/entity_tree/project_root/main.ent b/tests/fixtures/entity_tree/project_root/main.ent
new file mode 100644
index 0000000..ea289a2
--- /dev/null
+++ b/tests/fixtures/entity_tree/project_root/main.ent
@@ -0,0 +1 @@
+<!ENTITY proj SYSTEM "/some/prefix/virtual-dir/included.ent">
diff --git a/tests/fixtures/entity_tree/project_root/real-root/included.ent b/tests/fixtures/entity_tree/project_root/real-root/included.ent
new file mode 100644
index 0000000..e4b1915
--- /dev/null
+++ b/tests/fixtures/entity_tree/project_root/real-root/included.ent
@@ -0,0 +1 @@
+<!ENTITY mapped "mapped-value">
diff --git a/tests/fixtures/entity_tree/quoted.ent b/tests/fixtures/entity_tree/quoted.ent
new file mode 100644
index 0000000..ba7fcfe
--- /dev/null
+++ b/tests/fixtures/entity_tree/quoted.ent
@@ -0,0 +1,2 @@
+<!ENTITY single_quoted 'single'>
+<!ENTITY % param_entity "param-value">
diff --git a/tests/fixtures/entity_tree/sub/nested.ent b/tests/fixtures/entity_tree/sub/nested.ent
deleted file mode 100644
index 1b69738..0000000
--- a/tests/fixtures/entity_tree/sub/nested.ent
+++ /dev/null
@@ -1 +0,0 @@
-<!ENTITY nested.entity "Nested entity value">
diff --git a/tests/fixtures/entity_tree/system/included.ent b/tests/fixtures/entity_tree/system/included.ent
new file mode 100644
index 0000000..82fb9a7
--- /dev/null
+++ b/tests/fixtures/entity_tree/system/included.ent
@@ -0,0 +1 @@
+<!ENTITY child "child-value">
diff --git a/tests/fixtures/entity_tree/system/main.ent b/tests/fixtures/entity_tree/system/main.ent
new file mode 100644
index 0000000..d3664dc
--- /dev/null
+++ b/tests/fixtures/entity_tree/system/main.ent
@@ -0,0 +1 @@
+<!ENTITY inc SYSTEM "included.ent">
diff --git a/tests/fixtures/entity_tree/system/missing_target.ent b/tests/fixtures/entity_tree/system/missing_target.ent
new file mode 100644
index 0000000..e8bc5f2
--- /dev/null
+++ b/tests/fixtures/entity_tree/system/missing_target.ent
@@ -0,0 +1 @@
+<!ENTITY missing SYSTEM "/path/does/not/exist/foo.ent">
diff --git a/tests/fixtures/valid_full.xml b/tests/fixtures/valid_full.xml
index fb748e2..09ec241 100644
--- a/tests/fixtures/valid_full.xml
+++ b/tests/fixtures/valid_full.xml
@@ -1,5 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <docbookcs>
+	<project>
+		<directory alias="doc-en">en</directory>
+		<directory>doc-base</directory>
+	</project>
 	<sniffs>
 		<sniff class="DocbookCS\Sniffs\ParaToSimparaSniff" />
 		<sniff class="DocbookCS\Sniffs\IdNamingSniff">