Feature/improvement 25

.gitattributes

@@ -1,15 +1,21 @@
+.github export-ignore
+benchmarks export-ignore
+docs export-ignore
+examples export-ignore
+tests export-ignore
+
 .editorconfig export-ignore
+.gitattributes export-ignore
 .gitignore export-ignore
-tests export-ignore
-docs export-ignore
-.github export-ignore
 .readthedocs.yaml export-ignore
 captainhook.json export-ignore
+pest.xml export-ignore
+phpbench.json export-ignore
+phpcs.xml.dist export-ignore
+phpstan.neon.dist export-ignore
 phpunit.xml export-ignore
 pint.json export-ignore
-rector.php export-ignore
-.gitattributes export-ignore
 psalm.xml export-ignore
-pest.xml export-ignore
+rector.php export-ignore
 
-*  text eol=lf
+* text eol=lf

.github/scripts/composer-audit-guard.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+$command = 'composer audit --format=json --no-interaction --abandoned=report';
+
+$descriptorSpec = [
+    0 => ['pipe', 'r'],
+    1 => ['pipe', 'w'],
+    2 => ['pipe', 'w'],
+];
+
+$process = proc_open($command, $descriptorSpec, $pipes);
+
+if (! \is_resource($process)) {
+    fwrite(STDERR, "Failed to start composer audit process.\n");
+    exit(1);
+}
+
+fclose($pipes[0]);
+$stdout = stream_get_contents($pipes[1]) ?: '';
+$stderr = stream_get_contents($pipes[2]) ?: '';
+fclose($pipes[1]);
+fclose($pipes[2]);
+
+$exitCode = proc_close($process);
+
+/** @var array<string,mixed>|null $decoded */
+$decoded = json_decode($stdout, true);
+
+if (! \is_array($decoded)) {
+    fwrite(STDERR, "Unable to parse composer audit JSON output.\n");
+    if (trim($stdout) !== '') {
+        fwrite(STDERR, $stdout . "\n");
+    }
+    if (trim($stderr) !== '') {
+        fwrite(STDERR, $stderr . "\n");
+    }
+
+    exit($exitCode !== 0 ? $exitCode : 1);
+}
+
+$advisories = $decoded['advisories'] ?? [];
+$abandoned = $decoded['abandoned'] ?? [];
+
+$advisoryCount = 0;
+
+if (\is_array($advisories)) {
+    foreach ($advisories as $entries) {
+        if (\is_array($entries)) {
+            $advisoryCount += \count($entries);
+        }
+    }
+}
+
+$abandonedPackages = [];
+
+if (\is_array($abandoned)) {
+    foreach ($abandoned as $package => $replacement) {
+        if (\is_string($package) && $package !== '') {
+            $abandonedPackages[$package] = $replacement;
+        }
+    }
+}
+
+echo sprintf(
+    "Composer audit summary: %d advisories, %d abandoned packages.\n",
+    $advisoryCount,
+    \count($abandonedPackages),
+);
+
+if ($abandonedPackages !== []) {
+    fwrite(STDERR, "Warning: abandoned packages detected (non-blocking):\n");
+    foreach ($abandonedPackages as $package => $replacement) {
+        $target = \is_string($replacement) && $replacement !== '' ? $replacement : 'none';
+        fwrite(STDERR, sprintf(" - %s (replacement: %s)\n", $package, $target));
+    }
+}
+
+if ($advisoryCount > 0) {
+    fwrite(STDERR, "Security vulnerabilities detected by composer audit.\n");
+    exit(1);
+}
+
+exit(0);

.github/scripts/phpstan-sarif.php

@@ -0,0 +1,178 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Convert PHPStan JSON output to SARIF 2.1.0 for GitHub Code Scanning upload.
+ *
+ * Usage:
+ *   php .github/scripts/phpstan-sarif.php <phpstan-json> [sarif-output]
+ */
+
+$argv = $_SERVER['argv'] ?? [];
+$input = $argv[1] ?? '';
+$output = $argv[2] ?? 'phpstan-results.sarif';
+
+if (! is_string($input) || $input === '') {
+    fwrite(STDERR, "Error: missing input file.\n");
+    fwrite(STDERR, "Usage: php .github/scripts/phpstan-sarif.php <phpstan-json> [sarif-output]\n");
+    exit(2);
+}
+
+if (! is_file($input) || ! is_readable($input)) {
+    fwrite(STDERR, "Error: input file not found or unreadable: {$input}\n");
+    exit(2);
+}
+
+$raw = file_get_contents($input);
+if ($raw === false) {
+    fwrite(STDERR, "Error: failed to read input file: {$input}\n");
+    exit(2);
+}
+
+$decoded = json_decode($raw, true);
+if (! is_array($decoded)) {
+    fwrite(STDERR, "Error: input is not valid JSON.\n");
+    exit(2);
+}
+
+/**
+ * @return non-empty-string
+ */
+function normalizeUri(string $path): string
+{
+    $normalized = str_replace('\\', '/', $path);
+    $cwd = getcwd();
+
+    if (is_string($cwd) && $cwd !== '') {
+        $cwd = rtrim(str_replace('\\', '/', $cwd), '/');
+
+        if (preg_match('/^[A-Za-z]:\//', $normalized) === 1) {
+            if (stripos($normalized, $cwd . '/') === 0) {
+                $normalized = substr($normalized, strlen($cwd) + 1);
+            }
+        } elseif (str_starts_with($normalized, '/')) {
+            if (str_starts_with($normalized, $cwd . '/')) {
+                $normalized = substr($normalized, strlen($cwd) + 1);
+            }
+        }
+    }
+
+    $normalized = ltrim($normalized, './');
+
+    return $normalized === '' ? 'unknown.php' : $normalized;
+}
+
+$results = [];
+$rules = [];
+
+$globalErrors = $decoded['errors'] ?? [];
+if (is_array($globalErrors)) {
+    foreach ($globalErrors as $error) {
+        if (! is_string($error) || $error === '') {
+            continue;
+        }
+
+        $ruleId = 'phpstan.internal';
+        $rules[$ruleId] = true;
+        $results[] = [
+            'ruleId' => $ruleId,
+            'level' => 'error',
+            'message' => [
+                'text' => $error,
+            ],
+        ];
+    }
+}
+
+$files = $decoded['files'] ?? [];
+if (is_array($files)) {
+    foreach ($files as $filePath => $fileData) {
+        if (! is_string($filePath) || ! is_array($fileData)) {
+            continue;
+        }
+
+        $messages = $fileData['messages'] ?? [];
+        if (! is_array($messages)) {
+            continue;
+        }
+
+        foreach ($messages as $messageData) {
+            if (! is_array($messageData)) {
+                continue;
+            }
+
+            $messageText = (string) ($messageData['message'] ?? 'PHPStan issue');
+            $line = (int) ($messageData['line'] ?? 1);
+            $identifier = (string) ($messageData['identifier'] ?? '');
+            $ruleId = $identifier !== '' ? $identifier : 'phpstan.issue';
+
+            if ($line < 1) {
+                $line = 1;
+            }
+
+            $rules[$ruleId] = true;
+            $results[] = [
+                'ruleId' => $ruleId,
+                'level' => 'error',
+                'message' => [
+                    'text' => $messageText,
+                ],
+                'locations' => [[
+                    'physicalLocation' => [
+                        'artifactLocation' => [
+                            'uri' => normalizeUri($filePath),
+                        ],
+                        'region' => [
+                            'startLine' => $line,
+                        ],
+                    ],
+                ]],
+            ];
+        }
+    }
+}
+
+$ruleDescriptors = [];
+$ruleIds = array_keys($rules);
+sort($ruleIds);
+
+foreach ($ruleIds as $ruleId) {
+    $ruleDescriptors[] = [
+        'id' => $ruleId,
+        'name' => $ruleId,
+        'shortDescription' => [
+            'text' => $ruleId,
+        ],
+    ];
+}
+
+$sarif = [
+    '$schema' => 'https://json.schemastore.org/sarif-2.1.0.json',
+    'version' => '2.1.0',
+    'runs' => [[
+        'tool' => [
+            'driver' => [
+                'name' => 'PHPStan',
+                'informationUri' => 'https://phpstan.org/',
+                'rules' => $ruleDescriptors,
+            ],
+        ],
+        'results' => $results,
+    ]],
+];
+
+$encoded = json_encode($sarif, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+if (! is_string($encoded)) {
+    fwrite(STDERR, "Error: failed to encode SARIF JSON.\n");
+    exit(2);
+}
+
+$written = file_put_contents($output, $encoded . PHP_EOL);
+if ($written === false) {
+    fwrite(STDERR, "Error: failed to write output file: {$output}\n");
+    exit(2);
+}
+
+fwrite(STDOUT, sprintf("SARIF generated: %s (%d findings)\n", $output, count($results)));
+exit(0);