refactor(cli): route stderr emissions through EmitsStderr trait

Direct fwrite(STDERR, ...) calls (BUG-5/12/14) leaked into the phpunit
test runner output because PHPUnit does not capture stderr. With many
files and process tests the suite output became dozens of "Report
written to:", "--files takes precedence", "all input files are invalid"
lines mixed with the dot/F/E progress.

New trait EmitsStderr exposes \$this->emitStderr(\$message) that:
- In production (\$this->output is an OutputStyle wrapping Symfony
  ConsoleOutput which implements ConsoleOutputInterface): writes to
  the dedicated error stream via getErrorOutput()->writeln().
- In tests (\$this->artisan spins up an OutputStyle around BufferedOutput
  which does NOT implement ConsoleOutputInterface): the message is
  silently dropped, keeping the run output clean.

Tests that need to assert on a stderr message can drive the command
with a real ConsoleOutput or a double overriding emitStderr().

Each Command applies the trait directly — the consumer traits
(FormatsOutput, ResolvesInputFiles) only call \$this->emitStderr()
without using EmitsStderr themselves, because mixing two consumer
traits into the same Command would otherwise raise the trait
diamond-collision error.

Printer::deprecationWarning is removed (CheckConfigurationFileCommand
now formats and routes the message itself via the trait). The two
remaining fwrite(STDERR, ...) sites in src/Execution/ are pre-existing
and don't fire under the test suite.

Suite: 2091 / 2091 green, no stderr noise in phpunit output.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Test

app/Commands/CacheClearCommand.php

@@ -7,6 +7,7 @@
 use LaravelZero\Framework\Commands\Command;
 use RecursiveDirectoryIterator;
 use RecursiveIteratorIterator;
+use Wtyd\GitHooks\App\Commands\Concerns\EmitsStderr;
 use Wtyd\GitHooks\Configuration\ConfigurationParser;
 use Wtyd\GitHooks\Configuration\ConfigurationResult;
 use Wtyd\GitHooks\Configuration\JobConfiguration;
@@ -15,6 +16,8 @@
 
 class CacheClearCommand extends Command
 {
+    use EmitsStderr;
+
     protected $signature = 'cache:clear
                             {names?* : Job or flow names to clear (all if omitted)}
                             {--config= : Path to configuration file}';
@@ -69,7 +72,7 @@ public function handle(): int
             return $hasErrors ? 1 : 0;
         } catch (GitHooksExceptionInterface $e) {
             // To STDERR so --format=json/junit/sarif/codeclimate stdout stays clean (BUG-5).
-            fwrite(STDERR, $e->getMessage() . "\n");
+            $this->emitStderr($e->getMessage());
             return 1;
         }
     }

app/Commands/CheckConfigurationFileCommand.php

@@ -3,6 +3,7 @@
 namespace Wtyd\GitHooks\App\Commands;
 
 use LaravelZero\Framework\Commands\Command;
+use Wtyd\GitHooks\App\Commands\Concerns\EmitsStderr;
 use Wtyd\GitHooks\Configuration\ConfigurationParser;
 use Wtyd\GitHooks\Configuration\ConfigurationResult;
 use Wtyd\GitHooks\Jobs\JobRegistry;
@@ -19,6 +20,8 @@
 
 class CheckConfigurationFileCommand extends Command
 {
+    use EmitsStderr;
+
     protected $signature = 'conf:check  {--config= : Path to configuration file}';
     protected $description = 'Check that the configuration file exists and that it is in the proper format.';
 
@@ -227,7 +230,7 @@ protected function handleV3(ConfigurationResult $config): int
         foreach ($config->getValidation()->getDeprecations() as $deprecation) {
             $message = $deprecation->getWarningMessage();
             $deprecationMessages[$message] = true;
-            $this->printer->deprecationWarning($message);
+            $this->emitStderr("⚠️  $message");
         }
         foreach ($config->getValidation()->getWarnings() as $warning) {
             if (isset($deprecationMessages[$warning])) {

app/Commands/Concerns/EmitsStderr.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wtyd\GitHooks\App\Commands\Concerns;
+
+use Symfony\Component\Console\Output\ConsoleOutputInterface;
+
+/**
+ * Route advisories, deprecation warnings and exception messages to the
+ * console's STDERR stream while staying silent inside test buffers.
+ *
+ * Production: $this->output is an Illuminate\Console\OutputStyle wrapping a
+ * Symfony\Component\Console\Output\ConsoleOutput; we ask it for its
+ * dedicated stderr stream via getErrorOutput() so the message lands on
+ * fd 2, respects --no-ansi, and stays out of the JSON/JUnit/SARIF payload
+ * on stdout (BUG-5/12/14).
+ *
+ * Tests: Illuminate's $this->artisan() builds an OutputStyle around a
+ * BufferedOutput which does not implement ConsoleOutputInterface. Routing
+ * to the buffer would surface the message on stdout (back to square one);
+ * dropping it keeps the phpunit run output clean. Tests that need to
+ * assert on a stderr message must drive the command with a real
+ * ConsoleOutput or a double that overrides emitStderr().
+ */
+trait EmitsStderr
+{
+    /**
+     * @SuppressWarnings(PHPMD.UnusedPrivateMethod) used by classes that consume the trait
+     */
+    protected function emitStderr(string $message): void
+    {
+        $output = $this->output->getOutput();
+        if ($output instanceof ConsoleOutputInterface) {
+            $output->getErrorOutput()->writeln($message);
+        }
+    }
+}

app/Commands/Concerns/FormatsOutput.php

@@ -26,8 +26,15 @@
 /**
  * Shared logic for commands that support --format and multi-report --report-* flags.
  */
+/**
+ * Consumer Commands MUST also `use EmitsStderr;` so the trait's call to
+ * `$this->emitStderr(...)` resolves. We don't `use EmitsStderr` here to
+ * avoid the diamond-collision PHP raises when a Command also uses
+ * ResolvesInputFiles (which would also bring its own copy of the trait).
+ */
 trait FormatsOutput
 {
+
     /**
      * Select the output handler based on format and execution context.
      *
@@ -342,7 +349,7 @@ private function writeStructuredPayload(string $content): void
      */
     protected function emitReportWrittenNotice(string $path): void
     {
-        fwrite(STDERR, "Report written to: $path\n");
+        $this->emitStderr("Report written to: $path");
     }
 
     /**

app/Commands/Concerns/ResolvesInputFiles.php

@@ -18,8 +18,15 @@
  * @property InputFilesResolver $inputFilesResolver  Provided by the consumer
  *           command via constructor injection.
  */
+/**
+ * Consumer Commands MUST also `use EmitsStderr;` so the trait's calls to
+ * `$this->emitStderr(...)` resolve. We don't `use EmitsStderr` here to avoid
+ * the diamond-collision PHP raises when a Command also uses FormatsOutput
+ * (which would also bring its own copy of the trait).
+ */
 trait ResolvesInputFiles
 {
+
     /**
      * Returns null when none of the input-files flags are present. Otherwise
      * returns the resolved object after emitting any informational warnings.
@@ -52,16 +59,16 @@ private function resolveInputFilesFlags(bool $printModeHeader = false): ?InputFi
         // Advisories about input files go to STDERR so --format=json/junit/sarif/codeclimate
         // stdout stays a clean, parseable payload (BUG-5).
         foreach ($resolution->getInvalid() as $invalid) {
-            fwrite(STDERR, "⚠️  file '$invalid' does not exist, skipping\n");
+            $this->emitStderr("⚠️  file '$invalid' does not exist, skipping");
         }
         if ($resolution->isBomDetected()) {
-            fwrite(STDERR, "⚠️  --files-from: UTF-8 BOM detected and stripped\n");
+            $this->emitStderr('⚠️  --files-from: UTF-8 BOM detected and stripped');
         }
 
         if ($this->option('fast') || $this->option('fast-branch')) {
             $other   = $this->option('fast') ? '--fast' : '--fast-branch';
             $primary = is_string($files) && $files !== '' ? '--files' : '--files-from';
-            fwrite(STDERR, "⚠️  $primary takes precedence over $other ($other ignored)\n");
+            $this->emitStderr("⚠️  $primary takes precedence over $other ($other ignored)");
         }
 
         if ($printModeHeader && (strval($this->option('format')) === '' || $this->option('format') === null)) {

app/Commands/FlowCommand.php

@@ -7,6 +7,7 @@
 use LaravelZero\Framework\Commands\Command;
 use Wtyd\GitHooks\App\Commands\Concerns\EmitsConditionsHeader;
 use Wtyd\GitHooks\App\Commands\Concerns\EmitsConfigWarnings;
+use Wtyd\GitHooks\App\Commands\Concerns\EmitsStderr;
 use Wtyd\GitHooks\App\Commands\Concerns\FormatsOutput;
 use Wtyd\GitHooks\App\Commands\Concerns\ResolvesAllocatorFlag;
 use Wtyd\GitHooks\App\Commands\Concerns\ResolvesInputFiles;
@@ -28,6 +29,7 @@ class FlowCommand extends Command
 {
     use EmitsConditionsHeader;
     use EmitsConfigWarnings;
+    use EmitsStderr;
     use FormatsOutput;
     use ResolvesAllocatorFlag;
     use ResolvesInputFiles;
@@ -222,7 +224,7 @@ public function handle(): int
             return $result->isSuccess() ? 0 : 1;
         } catch (GitHooksExceptionInterface $e) {
             // To STDERR so --format=json/junit/sarif/codeclimate stdout stays clean (BUG-5).
-            fwrite(STDERR, $e->getMessage() . "\n");
+            $this->emitStderr($e->getMessage());
             return 1;
         }
     }

app/Commands/FlowsCommand.php

@@ -7,6 +7,7 @@
 use LaravelZero\Framework\Commands\Command;
 use Wtyd\GitHooks\App\Commands\Concerns\EmitsConditionsHeader;
 use Wtyd\GitHooks\App\Commands\Concerns\EmitsConfigWarnings;
+use Wtyd\GitHooks\App\Commands\Concerns\EmitsStderr;
 use Wtyd\GitHooks\App\Commands\Concerns\FormatsOutput;
 use Wtyd\GitHooks\App\Commands\Concerns\ResolvesAllocatorFlag;
 use Wtyd\GitHooks\App\Commands\Concerns\ResolvesInputFiles;
@@ -41,6 +42,7 @@ class FlowsCommand extends Command
 {
     use EmitsConditionsHeader;
     use EmitsConfigWarnings;
+    use EmitsStderr;
     use FormatsOutput;
     use ResolvesAllocatorFlag;
     use ResolvesInputFiles;
@@ -233,7 +235,7 @@ public function handle(): int
             return $result->isSuccess() ? 0 : 1;
         } catch (GitHooksExceptionInterface $e) {
             // To STDERR so --format=json/junit/sarif/codeclimate stdout stays clean (BUG-5).
-            fwrite(STDERR, $e->getMessage() . "\n");
+            $this->emitStderr($e->getMessage());
             return 1;
         }
     }
@@ -375,10 +377,9 @@ private function emitIgnoredOptionsWarning(
 
         // REQ-018 advisory: route to stderr so pipelines capturing stdout
         // (CI, --format=json, scripted tooling) don't pick up the message.
-        fwrite(
-            STDERR,
+        $this->emitStderr(
             "⚠️  Options declared in '" . implode("', '", $ignored) . "' are ignored in multi-flow runs."
-            . "\n  Effective options come from flows.options + CLI; see header below.\n"
+            . "\n  Effective options come from flows.options + CLI; see header below."
         );
     }
 

app/Commands/JobCommand.php

@@ -16,6 +16,7 @@
 };
 use Wtyd\GitHooks\App\Commands\Concerns\EmitsConditionsHeader;
 use Wtyd\GitHooks\App\Commands\Concerns\EmitsConfigWarnings;
+use Wtyd\GitHooks\App\Commands\Concerns\EmitsStderr;
 use Wtyd\GitHooks\App\Commands\Concerns\FormatsOutput;
 use Wtyd\GitHooks\App\Commands\Concerns\ResolvesAllocatorFlag;
 use Wtyd\GitHooks\App\Commands\Concerns\ResolvesInputFiles;
@@ -30,6 +31,7 @@ class JobCommand extends Command
 {
     use EmitsConditionsHeader;
     use EmitsConfigWarnings;
+    use EmitsStderr;
     use FormatsOutput;
     use ResolvesAllocatorFlag;
     use ResolvesInputFiles;
@@ -211,7 +213,7 @@ public function handle(): int
             return $result->isSuccess() ? 0 : 1;
         } catch (GitHooksExceptionInterface $e) {
             // To STDERR so --format=json/junit/sarif/codeclimate stdout stays clean (BUG-5).
-            fwrite(STDERR, $e->getMessage() . "\n");
+            $this->emitStderr($e->getMessage());
             return 1;
         }
     }

src/Utils/Printer.php

@@ -21,17 +21,6 @@ public function resultWarning(string $message): void
         $this->warning($message);
     }
 
-    /**
-     * Deprecation notices go to STDERR so consumers parsing stdout (CI pipes,
-     * --format=json/junit/sarif/codeclimate, scripted tooling) don't pick up
-     * the human-facing message. Structured payloads expose the same data via
-     * the `deprecations[]` block; this method is purely for the operator
-     * looking at the terminal.
-     */
-    public function deprecationWarning(string $message): void
-    {
-        fwrite(STDERR, "⚠️ \e[43m\e[30m{$message}\033[0m\n");
-    }
     public function resultError(string $message): void
     {
         echo "❌ ";