fix(execution): reinterpret tools' empty-input failures as skipped (BUG-1)

Test · claude · Test · commit 1a1cece02036 · 2026-05-12T10:55:36.000Z
PHPStan and PHPCS exit non-zero when their internal exclusion lists
(excludePaths.analyse / --ignore) strip every input file, breaking
pipelines on mono-domain MRs where the wrapper feeds them files that
match a job's paths but fall entirely inside the tool's own exclusions.

Each accelerable Job now declares isEmptyInputTolerated(exitCode, output)
mirroring the existing isFixApplied() pattern. JobExecutor and FlowExecutor
reinterpret matching results as JobResult::skipped with skipReason, emit
onJobSkipped instead of onJobError, and bypass threshold evaluation —
the tool didn't do real work, so comparing its near-zero duration against
warn-after/fail-after would be meaningless.

PhpstanJob: exit==1 + "No files found to analyse".
PhpcsJob: exit in {1,2,3,16} + "All specified files were excluded" /
"No files were checked" (defensive across PHPCS 3.x and the PHPCSStandards
fork; the marker check is what actually decides).

PHPMD already tolerates this natively (exit 0 on empty set); the other
accelerable tools (parallel-lint, psalm, rector, php-cs-fixer) silently
ignore non-matching inputs and need no override.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -2,6 +2,12 @@
 
 All notable changes to this project are documented here.
 
+## [3.3.3]
+
+### Fixed
+
+- **Fast-branch / fast no longer fail with spurious "no files" errors when a job's tool config strips every input via its internal exclusion list.** Repro: a branch only touches files in one domain (e.g. `src/Gas/...`); the wrapper hands those files to a job whose `.neon` declares `excludePaths.analyse: [src/Gas]` (PHPStan) or whose `--ignore` CSV covers them (PHPCS). The tool then drops 100 % of the input and exits non-zero with `[ERROR] No files found to analyse.` (PHPStan, exit 1) or `ERROR: All specified files were excluded or did not match filtering rules.` (PHPCS, exit 16 on older versions and the PHPCSStandards fork). Before this fix the wrapper reported the job as failed, breaking mono-domain MRs (observed in consumer projects with per-domain flow structure). Each accelerable Job now declares an empty-input tolerance heuristic via `isEmptyInputTolerated(int $exitCode, string $output): bool` (mirror of the existing `isFixApplied()` pattern). `PhpstanJob` recognises `exit === 1` + `No files found to analyse`; `PhpcsJob` recognises `exit ∈ {1,2,3,16}` + `All specified files were excluded` / `No files were checked` (defensive across PHPCS 3.x and the PHPCSStandards fork). When tolerated, the JobResult is reinterpreted as `skipped: true` with `skipReason` instead of `success: false`, and the OutputHandler emits `onJobSkipped` rather than `onJobError`. Threshold evaluation is also bypassed for tolerated jobs — the tool didn't do real work, so comparing its near-zero duration against `warn-after`/`fail-after` would be meaningless. PHPMD already tolerates this case natively (`exit 0` when its `--exclude` empties the set); the other accelerable tools (parallel-lint, psalm, rector, php-cs-fixer) silently ignore non-matching inputs and do not need an override.
+
 ## [3.3.2] ⚠️ Do not use — broken release
 
 **This release is functionally identical to 3.3.1.** The git tag `v3.3.2` was published against a master commit whose bundled `.phar` binaries (`builds/githooks`, `builds/php7.4/githooks`) had never been updated from the `rc-3.3.2` branch where CI compiled them. Since GitHooks runs as a standalone `.phar`, installing `wtyd/githooks:3.3.2` ships the v3.3.1 binary under the v3.3.2 tag name. The fixes listed below are present in the source code of the tag but **not** in the executed binary.
diff --git a/src/Execution/FlowExecutor.php b/src/Execution/FlowExecutor.php
@@ -669,6 +669,12 @@ private function collectResult(array $entry): JobResult
         return $this->buildResult($entry['job'], $entry['process'], $entry['start']);
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity) Aggregates exit-code, fix-applied,
+     *   empty-input tolerance, ignoreErrorsOnExit, threshold and output dispatch in
+     *   a single pass; each branch corresponds to one independent outcome of a single job.
+     * @SuppressWarnings(PHPMD.NPathComplexity) Same reason.
+     */
     private function buildResult(JobAbstract $job, Process $process, float $start): JobResult
     {
         $elapsed = $this->now() - $start;
@@ -677,7 +683,8 @@ private function buildResult(JobAbstract $job, Process $process, float $start):
         $stdout = $process->getOutput();
         $output = $stdout . $process->getErrorOutput();
         $fixApplied = $job->isFixApplied($exitCode);
-        $success = $exitCode === 0 || $fixApplied;
+        $emptyInputTolerated = $job->isEmptyInputTolerated($exitCode, $output);
+        $success = $exitCode === 0 || $fixApplied || $emptyInputTolerated;
 
         if ($job->isIgnoreErrorsOnExit() && !$success) {
             $success = true;
@@ -688,7 +695,14 @@ private function buildResult(JobAbstract $job, Process $process, float $start):
             $this->gitStager->stageTrackedFiles();
         }
 
-        [$thresholdState, $thresholdReason, $warnAfter, $failAfter] = $this->evaluateThreshold($job, $elapsed);
+        // Skip threshold for empty-input-tolerated jobs: the tool didn't do real
+        // work, comparing its (near-zero) duration against warn-after/fail-after
+        // would be meaningless and could fail a legitimate skip.
+        if ($emptyInputTolerated) {
+            [$thresholdState, $thresholdReason, $warnAfter, $failAfter] = [JobResult::THRESHOLD_NONE, null, null, null];
+        } else {
+            [$thresholdState, $thresholdReason, $warnAfter, $failAfter] = $this->evaluateThreshold($job, $elapsed);
+        }
 
         // Per-job FAIL by threshold flips OK→KO ONLY when the tool itself succeeded;
         // if the tool already failed (KO real), the threshold is informational and
@@ -697,9 +711,13 @@ private function buildResult(JobAbstract $job, Process $process, float $start):
             $success = false;
         }
 
+        $skipReason = null;
         $displayName = $job->getDisplayName();
 
-        if ($success) {
+        if ($emptyInputTolerated) {
+            $skipReason = 'tool reported no input files after applying internal exclusions';
+            $this->outputHandler->onJobSkipped($displayName, $skipReason);
+        } elseif ($success) {
             $this->outputHandler->onJobSuccess($displayName, $time);
         } else {
             $this->outputHandler->onJobError($displayName, $time, $output);
@@ -717,8 +735,8 @@ private function buildResult(JobAbstract $job, Process $process, float $start):
             $job->getType(),
             $exitCode,
             $job->getConfiguredPaths(),
-            false,
-            null,
+            $emptyInputTolerated,
+            $skipReason,
             $stdout,
             $this->buildPerJobInputFiles($job),
             $elapsed,
diff --git a/src/Execution/JobExecutor.php b/src/Execution/JobExecutor.php
@@ -33,16 +33,23 @@ public function execute(JobAbstract $job): JobResult
         $stdout = $process->getOutput();
         $output = $stdout . $process->getErrorOutput();
         $fixApplied = $job->isFixApplied($exitCode);
+        $emptyInputTolerated = $job->isEmptyInputTolerated($exitCode, $output);
 
-        $success = $exitCode === 0 || $fixApplied;
+        $success = $exitCode === 0 || $fixApplied || $emptyInputTolerated;
 
         if ($job->isIgnoreErrorsOnExit() && !$success) {
             $success = true;
         }
 
+        $skipReason = $emptyInputTolerated
+            ? 'tool reported no input files after applying internal exclusions'
+            : null;
+
         $displayName = $job->getDisplayName();
 
-        if ($success) {
+        if ($emptyInputTolerated) {
+            $this->printer->warning("$displayName - SKIP. Time: $time ($skipReason)");
+        } elseif ($success) {
             $this->printer->success("$displayName - OK. Time: $time");
         } else {
             $this->printer->error("$displayName - KO. Time: $time");
@@ -63,8 +70,8 @@ public function execute(JobAbstract $job): JobResult
             $job->getType(),
             $exitCode,
             $job->getConfiguredPaths(),
-            false,
-            null,
+            $emptyInputTolerated,
+            $skipReason,
             $stdout
         );
     }
diff --git a/src/Jobs/JobAbstract.php b/src/Jobs/JobAbstract.php
@@ -395,6 +395,23 @@ public function isFixApplied(int $exitCode): bool
         return false;
     }
 
+    /**
+     * Whether a non-zero exit code reflects the tool refusing to operate
+     * on an empty input set (everything the wrapper passed got dropped by
+     * the tool's internal exclusions). Subclasses override to recognise
+     * the tool-specific exit code + output signature.
+     *
+     * When this returns true, the executor reinterprets the JobResult as
+     * skipped rather than failed: the tool didn't fail — it had nothing to do.
+     *
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter) Default implementation
+     *   ignores both arguments; subclasses inspect them.
+     */
+    public function isEmptyInputTolerated(int $exitCode, string $output): bool
+    {
+        return false;
+    }
+
     /**
      * Whether this tool type supports structured output parsing (JSON).
      */
diff --git a/src/Jobs/PhpcsJob.php b/src/Jobs/PhpcsJob.php
@@ -10,6 +10,26 @@ class PhpcsJob extends JobAbstract
 {
     public const SUPPORTS_FAST = true;
 
+    /**
+     * PHPCS variants of "every input was excluded" — observed across versions
+     * (Squizlabs 2.x → 3.x and the PHPCSStandards fork). Both phrases have
+     * appeared as stdout when `--ignore` (CLI) or `<exclude-pattern>` (ruleset)
+     * filters out 100% of the files passed as arguments.
+     */
+    private const EMPTY_INPUT_MARKERS = [
+        'All specified files were excluded',
+        'No files were checked',
+    ];
+
+    /**
+     * Defensive exit-code set: PHPCS 3.13.x (the version we vendor) returns 0
+     * silently when --ignore drops every input; older versions and the
+     * PHPCSStandards fork return 16. We accept the {1,2,3,16} range so a future
+     * version bump doesn't silently regress — the marker check below is what
+     * actually decides whether the failure is real or "nothing to do".
+     */
+    private const EMPTY_INPUT_EXIT_CODES = [1, 2, 3, 16];
+
     protected const ARGUMENT_MAP = [
         'standard'         => ['flag' => '--standard', 'type' => 'value'],
         'ignore'           => ['flag' => '--ignore', 'type' => 'csv'],
@@ -88,6 +108,19 @@ public function getThreadCapability(): ?ThreadCapability
         return new ThreadCapability('parallel', $current);
     }
 
+    public function isEmptyInputTolerated(int $exitCode, string $output): bool
+    {
+        if (!in_array($exitCode, self::EMPTY_INPUT_EXIT_CODES, true)) {
+            return false;
+        }
+        foreach (self::EMPTY_INPUT_MARKERS as $marker) {
+            if (strpos($output, $marker) !== false) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     public function applyThreadLimit(int $threads): void
     {
         $this->args['parallel'] = $threads;
diff --git a/src/Jobs/PhpstanJob.php b/src/Jobs/PhpstanJob.php
@@ -11,6 +11,14 @@ class PhpstanJob extends JobAbstract
 {
     public const SUPPORTS_FAST = true;
 
+    /**
+     * PHPStan emits this on stderr when every input file is filtered out by
+     * `excludePaths.analyse` of the active config. The wrapper concatenates
+     * stderr after stdout in JobExecutor/FlowExecutor before consulting
+     * isEmptyInputTolerated(), so a single str_contains over $output is enough.
+     */
+    private const EMPTY_INPUT_MARKER = 'No files found to analyse';
+
     protected const ARGUMENT_MAP = [
         'config'             => ['flag' => '-c', 'type' => 'value', 'separator' => ' '],
         'level'              => ['flag' => '-l', 'type' => 'value', 'separator' => ' '],
@@ -49,6 +57,11 @@ public function getThreadCapability(): ?ThreadCapability
         return new ThreadCapability('_phpstan_internal', $workers, 1, false);
     }
 
+    public function isEmptyInputTolerated(int $exitCode, string $output): bool
+    {
+        return $exitCode === 1 && strpos($output, self::EMPTY_INPUT_MARKER) !== false;
+    }
+
     /**
      * Public accessor for the worker count declared in the .neon. Used by
      * cross-flow validators (ConfigurationParser) that must compare the
diff --git a/tests/System/Release/EmptyInputToleranceReleaseTest.php b/tests/System/Release/EmptyInputToleranceReleaseTest.php
@@ -0,0 +1,91 @@
+<?php
+
+namespace Tests\System\Release;
+
+use Tests\ReleaseTestCase;
+
+/**
+ * @group release
+ *
+ * BUG-1: when a job's tool config strips every input via its internal
+ * exclusion list (`excludePaths.analyse` for PHPStan, `--ignore` for PHPCS),
+ * the tool exits non-zero with a recognisable marker. The .phar must
+ * reinterpret that as `skipped: true` instead of failing the flow.
+ *
+ * This test ships a `.neon` whose `excludePaths.analyse` covers the very file
+ * the job is asked to analyse. Without the fix, PHPStan returns exit 1 +
+ * "[ERROR] No files found to analyse." and the job is reported as failed.
+ * With the fix, the JSON output reports `skipped: true` and `success: true`.
+ */
+class EmptyInputToleranceReleaseTest extends ReleaseTestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        // A valid PHP file in src/. The .neon will exclude src/ entirely, so
+        // PHPStan will report "No files found to analyse" with exit 1.
+        file_put_contents(
+            self::TESTS_PATH . '/src/File.php',
+            $this->phpFileBuilder->build()
+        );
+
+        $qaDir = self::TESTS_PATH . '/qa';
+        if (!is_dir($qaDir)) {
+            mkdir($qaDir, 0777, true);
+        }
+
+        // .neon paths are relative to the .neon itself.
+        // From testsDir/qa/, "../src" points to testsDir/src.
+        file_put_contents(
+            "$qaDir/phpstan-exclude-all.neon",
+            "parameters:\n    level: 0\n    paths:\n        - ../src\n    excludePaths:\n        analyse:\n            - ../src\n"
+        );
+    }
+
+    /** @test */
+    public function phpstan_job_with_all_inputs_excluded_is_reported_as_skipped_in_json()
+    {
+        // Build a v3-style githooks.php declaring a single phpstan job that
+        // analyses testsDir/src — and whose .neon excludes that path entirely.
+        // Without the BUG-1 fix this returns failed; with the fix it returns skipped.
+        $githooksPhp = $this->configurationFileBuilder
+            ->enableV3Mode()
+            ->setV3Hooks([])
+            ->setV3Flows([])
+            ->setV3Jobs([
+                'phpstan_excl' => [
+                    'type'             => 'phpstan',
+                    'executable-path'  => 'vendor/bin/phpstan',
+                    'config'           => self::TESTS_PATH . '/qa/phpstan-exclude-all.neon',
+                    'paths'            => [self::TESTS_PATH . '/src'],
+                    'level'            => 0,
+                ],
+            ])
+            ->buildV3Php();
+
+        // ReleaseTestCase::tearDown() cleans this up.
+        file_put_contents('githooks.php', $githooksPhp);
+
+        $output = [];
+        $exitCode = 1;
+        exec("$this->githooks job phpstan_excl --format=json 2>/dev/null", $output, $exitCode);
+        $json = implode("\n", $output);
+
+        $this->assertSame(0, $exitCode, "githooks job exit code (raw output:\n$json)");
+
+        $decoded = json_decode($json, true);
+        $this->assertIsArray($decoded, "JSON output must parse (raw:\n$json)");
+        $this->assertArrayHasKey('jobs', $decoded);
+        $this->assertCount(1, $decoded['jobs']);
+
+        $job = $decoded['jobs'][0];
+        $this->assertSame('phpstan_excl', $job['name']);
+        $this->assertTrue(
+            $job['skipped'] ?? false,
+            "Job must be reported as skipped — raw job entry:\n" . json_encode($job, JSON_PRETTY_PRINT)
+        );
+        $this->assertTrue($job['success'] ?? false, 'Skipped jobs do not fail the flow');
+        $this->assertNotEmpty($job['skipReason'] ?? '', 'skipReason must be populated');
+    }
+}
diff --git a/tests/Unit/Execution/FlowExecutorEmptyInputTest.php b/tests/Unit/Execution/FlowExecutorEmptyInputTest.php
diff --git a/tests/Unit/Jobs/PhpcsJobTest.php b/tests/Unit/Jobs/PhpcsJobTest.php
diff --git a/tests/Unit/Jobs/PhpstanJobTest.php b/tests/Unit/Jobs/PhpstanJobTest.php
