Harden quality gates and finalize mutation coverage

.github/workflows/duplication.yml

@@ -11,7 +11,6 @@ on:
 jobs:
   duplication:
     runs-on: ubuntu-latest
-    continue-on-error: true
     steps:
       - uses: actions/checkout@v6
       - name: Detect minimum PHP from composer.json

.github/workflows/mutation.yml

@@ -5,6 +5,8 @@ name: mutation
 
 on:
   pull_request:
+  push:
+    branches: [main]
 
 jobs:
   mutation:

.github/workflows/test-integration.yml

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 LibreSign
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: test-integration
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Detect minimum PHP from composer.json
+        id: php_min
+        run: |
+          php_version=$(grep -Po '"php"\s*:\s*"\K[^"]+' composer.json | grep -Eo '[0-9]+\.[0-9]+' | head -n1)
+          [[ -n "$php_version" ]] || { echo "Could not determine minimum PHP version"; exit 1; }
+          echo "version=$php_version" >> "$GITHUB_OUTPUT"
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ steps.php_min.outputs.version }}
+      - run: composer install --no-interaction --prefer-dist
+      - run: composer bin phpunit install --no-interaction --prefer-dist
+      - run: composer run test:integration

composer.json

@@ -57,7 +57,7 @@
     "psalm": "vendor-bin/psalm/vendor/vimeo/psalm/psalm --no-progress",
     "phpmd": "vendor-bin/phpmd/vendor/phpmd/phpmd/src/bin/phpmd src,tests text phpmd.xml",
     "psalm:update-baseline": "vendor-bin/psalm/vendor/vimeo/psalm/psalm --set-baseline=psalm-baseline.xml",
-    "duplication:check": "vendor-bin/phpcpd/vendor/sebastian/phpcpd/phpcpd --min-lines=8 --min-tokens=70 --exclude vendor --exclude tests/Fixtures --exclude tests/Snapshots src tests",
+    "duplication:check": "vendor-bin/phpcpd/vendor/sebastian/phpcpd/phpcpd --min-lines=6 --min-tokens=50 --exclude vendor --exclude tests/Fixtures --exclude tests/Snapshots src tests",
     "composer:validate": "composer validate --strict",
     "composer:normalize:check": "vendor-bin/qa/vendor/ergebnis/composer-normalize/bin/composer-normalize --dry-run",
     "bc:check": "vendor-bin/qa/vendor/roave/backward-compatibility-check/bin/roave-backward-compatibility-check --from=origin/main --to=HEAD",
@@ -69,6 +69,7 @@
     "sh:security": "shellcheck scripts/*.sh",
     "profile:xdebug": "XDEBUG_MODE=profile php benchmarks/profile.php",
     "test:unit": "vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit --testsuite unit",
+    "test:integration": "vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit --testsuite integration",
     "test:coverage": "XDEBUG_MODE=coverage vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit --coverage-text --coverage-clover=build/coverage/clover.xml",
     "mutation:test": "vendor-bin/mutation/vendor/infection/infection/bin/infection --threads=max",
     "performance:check": "php benchmarks/compiler-benchmark.php",

infection.json5

@@ -12,8 +12,8 @@
   "phpUnit": {
     "customPath": "vendor-bin/phpunit/vendor/bin/phpunit"
   },
-  "minMsi": 75,
-  "minCoveredMsi": 82,
+  "minMsi": 100,
+  "minCoveredMsi": 100,
   "testFramework": "phpunit",
   "timeout": 120
 }

phpunit.xml.dist

@@ -2,7 +2,13 @@
 <phpunit bootstrap="vendor/autoload.php"
          colors="true"
          cacheDirectory="build/.phpunit-cache"
-         beStrictAboutTestsThatDoNotTestAnything="true">
+         beStrictAboutTestsThatDoNotTestAnything="true"
+         failOnDeprecation="true"
+         failOnIncomplete="true"
+         failOnNotice="true"
+         failOnRisky="true"
+         failOnSkipped="true"
+         failOnWarning="true">
     <testsuites>
         <testsuite name="unit">
             <directory>tests/Unit</directory>

psalm.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!-- SPDX-FileCopyrightText: 2026 LibreSign -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
-<psalm errorLevel="3"
+<psalm errorLevel="1"
        resolveFromConfigFile="true"
        findUnusedBaselineEntry="true"
        findUnusedCode="false">

src/Html/SubsetHtmlParser.php

@@ -7,6 +7,7 @@
 
 namespace LibreSign\XObjectTemplate\Html;
 
+use DOMAttr;
 use DOMDocument;
 use DOMElement;
 use DOMNode;
@@ -58,7 +59,7 @@ public function parse(string $html): array
         }
 
         $nodes = [];
-        foreach ($body->childNodes as $child) {
+        foreach ($this->iterateChildNodes($body) as $child) {
             $parsed = $this->parseDomNode($child, '');
             if ($parsed !== null) {
                 $nodes[] = $parsed;
@@ -92,7 +93,7 @@ private function parseElementNode(DOMElement $node, string $inheritedStyle): Nod
         }
 
         $children = [];
-        foreach ($node->childNodes as $childNode) {
+        foreach ($this->iterateChildNodes($node) as $childNode) {
             $child = $this->parseDomNode($childNode, $effectiveStyle);
             if ($child !== null) {
                 $children[] = $child;
@@ -128,16 +129,40 @@ private function parseTextNode(DOMNode $node, string $inheritedStyle): ?Node
     private function collectAttributes(DOMElement $node): array
     {
         $attributes = [];
-        $nodeAttrs = $node->attributes;
-        if ($nodeAttrs !== null) {
-            foreach ($nodeAttrs as $attribute) {
-                $attributes[$attribute->name] = trim($attribute->value);
-            }
+        foreach ($this->iterateAttributes($node) as $attribute) {
+            $attributes[$attribute->name] = trim($attribute->value);
         }
 
         return $attributes;
     }
 
+    /**
+     * @return \Generator<int, DOMNode>
+     */
+    private function iterateChildNodes(DOMNode $node): \Generator
+    {
+        /** @var DOMNode $child */
+        foreach ($node->childNodes as $child) {
+            yield $child;
+        }
+    }
+
+    /**
+     * @return \Generator<int, DOMAttr>
+     */
+    private function iterateAttributes(DOMElement $node): \Generator
+    {
+        $attributes = $node->attributes;
+        if ($attributes === null) {
+            return;
+        }
+
+        /** @var DOMAttr $attribute */
+        foreach ($attributes as $attribute) {
+            yield $attribute;
+        }
+    }
+
     private function mergeStyle(string $inheritedStyle, string $ownStyle): string
     {
         $inheritedStyle = $this->filterInheritableStyle($inheritedStyle);

src/Layout/StructuredLayoutRenderer.php

@@ -274,13 +274,15 @@ private function renderBlockContainer(
             );
         }
 
-        $renderedHeight = $localClipBox === null
-            ? $this->boxResolver->resolveAutoContainerHeight($box['height'], $padding, $contentHeight)
-            : $this->boxResolver->resolveFixedContainerHeight($box['height'], $padding, $contentHeight);
-
-        $this->appendDecoration($style, $box, $renderedHeight, $canvasHeight, $decorations);
-
-        return $renderedHeight;
+        return $this->finalizeContainerRendering(
+            $style,
+            $box,
+            $padding,
+            $contentHeight,
+            $localClipBox,
+            $canvasHeight,
+            $decorations,
+        );
     }
 
     /**
@@ -324,12 +326,15 @@ private function renderFlexContainer(
         );
 
         if ($items === []) {
-            $renderedHeight = $localClipBox === null
-                ? $this->boxResolver->resolveAutoContainerHeight($box['height'], $padding, 0.0)
-                : $this->boxResolver->resolveFixedContainerHeight($box['height'], $padding, 0.0);
-            $this->appendDecoration($style, $box, $renderedHeight, $canvasHeight, $decorations);
-
-            return $renderedHeight;
+            return $this->finalizeContainerRendering(
+                $style,
+                $box,
+                $padding,
+                0.0,
+                $localClipBox,
+                $canvasHeight,
+                $decorations,
+            );
         }
 
         $metrics = $this->flexPlanner->calculateMetrics($items, $direction, $justifyContent, $gap, $contentBox);
@@ -359,9 +364,37 @@ private function renderFlexContainer(
         }
 
         $contentHeight = $direction === 'row' ? $metrics['crossAxisSize'] : $metrics['totalMainAxisSize'];
+
+        return $this->finalizeContainerRendering(
+            $style,
+            $box,
+            $padding,
+            $contentHeight,
+            $localClipBox,
+            $canvasHeight,
+            $decorations,
+        );
+    }
+
+    /**
+     * @param array{x: float, y: float, width: float, height: float} $box
+        * @param array{top: float, right: float, bottom: float, left: float} $padding
+     * @param list<LayoutDecoration> $decorations
+     * @param array{x: float, y: float, width: float, height: float}|null $localClipBox
+     */
+    private function finalizeContainerRendering(
+        StyleMap $style,
+        array $box,
+        array $padding,
+        float $contentHeight,
+        ?array $localClipBox,
+        float $canvasHeight,
+        array &$decorations,
+    ): float {
         $renderedHeight = $localClipBox === null
             ? $this->boxResolver->resolveAutoContainerHeight($box['height'], $padding, $contentHeight)
             : $this->boxResolver->resolveFixedContainerHeight($box['height'], $padding, $contentHeight);
+
         $this->appendDecoration($style, $box, $renderedHeight, $canvasHeight, $decorations);
 
         return $renderedHeight;

src/Pdf/CompileResultResourceExtractor.php

@@ -0,0 +1,61 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreSign
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreSign\XObjectTemplate\Pdf;
+
+use InvalidArgumentException;
+use LibreSign\XObjectTemplate\Dto\CompileResult;
+
+/** @internal */
+class CompileResultResourceExtractor
+{
+    /**
+     * @return array<string, array<string, mixed>>
+     */
+    public function extract(CompileResult $result, string $resourceType, string $itemMessageTemplate): array
+    {
+        if (!array_key_exists($resourceType, $result->resources)) {
+            return [];
+        }
+
+        /** @var mixed $rawResources */
+        $rawResources = $result->resources[$resourceType];
+        $resources = $this->requireStringKeyedArray(
+            $rawResources,
+            sprintf('%s resources must be an array.', $resourceType),
+        );
+
+        $normalizedResources = [];
+        foreach (array_keys($resources) as $alias) {
+            $normalizedResources[$alias] = $this->requireStringKeyedArray(
+                $resources[$alias],
+                sprintf($itemMessageTemplate, $alias),
+            );
+        }
+
+        return $normalizedResources;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function requireStringKeyedArray(mixed $value, string $message): array
+    {
+        if (!is_array($value)) {
+            throw new InvalidArgumentException($message);
+        }
+
+        foreach (array_keys($value) as $key) {
+            if (!is_string($key)) {
+                throw new InvalidArgumentException($message);
+            }
+        }
+
+        /** @var array<string, mixed> $value */
+        return $value;
+    }
+}

src/Pdf/Png/PhpPngHeaderUnpacker.php

@@ -0,0 +1,29 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreSign
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreSign\XObjectTemplate\Pdf\Png;
+
+/** @internal */
+final class PhpPngHeaderUnpacker implements PngHeaderUnpackerInterface
+{
+    private const HEADER_BYTES = 13;
+
+    public function unpack(string $data): array|false
+    {
+        if (strlen($data) < self::HEADER_BYTES) {
+            return false;
+        }
+
+        /** @var array{width: int, height: int, bitDepth: int, colorType: int, compression: int, filter: int, interlace: int} $header */
+        $header = unpack(
+            'Nwidth/Nheight/CbitDepth/CcolorType/Ccompression/Cfilter/Cinterlace',
+            $data,
+        );
+
+        return $header;
+    }
+}

src/Pdf/Png/PhpPngScanlineCompressor.php

@@ -0,0 +1,17 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreSign
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreSign\XObjectTemplate\Pdf\Png;
+
+/** @internal */
+final class PhpPngScanlineCompressor implements PngScanlineCompressorInterface
+{
+    public function compress(string $scanlines): string|false
+    {
+        return gzcompress($scanlines);
+    }
+}

src/Pdf/Png/PngColorTypeDescription.php

@@ -18,10 +18,6 @@
     /** @var positive-int */
     public int $bytesPerPixel;
 
-    /**
-     * @param 1|3 $colorCount
-     * @param positive-int $bytesPerPixel
-     */
     public function __construct(
         public string $colorSpace,
         int $colorCount,

src/Pdf/Png/PngHeaderUnpackerInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreSign
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreSign\XObjectTemplate\Pdf\Png;
+
+/** @internal */
+interface PngHeaderUnpackerInterface
+{
+    /**
+     * @return array{
+     *     width: int,
+     *     height: int,
+     *     bitDepth: int,
+     *     colorType: int,
+     *     compression: int,
+     *     filter: int,
+     *     interlace: int
+     * }|false
+     */
+    public function unpack(string $data): array|false;
+}