fix(output): activate tool JSON output for codeclimate/sarif via reports config or CLI flag

Test · claude · Test · commit 139854692625 · 2026-05-08T09:59:27.000Z
Pre-3.3.2 setStructuredFormat(true) only fired when --format=codeclimate|sarif.
Reports requested via flows.options.reports.&lt;X&gt; or --report-X=PATH left tools
emitting human text, and every parser (phpstan, phpcs, phpmd, psalm,
parallel-lint — all do json_decode over stdout) returned []. The codeclimate
or sarif payload came out empty.

Fix detects whether a codeclimate/sarif payload will be produced via any
path (primary --format, config reports, CLI report flag) and propagates the
flag accordingly. Reuses collectReportTargets() so CLI &gt; config precedence
and --no-reports semantics stay consistent.

Adds 16-row decision-table unit matrix and 3 release tests against the .phar:
phpstan via reports config, phpstan via --report-sarif CLI, and a multi-tool
flow (phpcs+phpmd) confirming the bypass affected every tool, not just
phpstan.

Also includes FEAT-13 (--fast-dirty execution mode) in v3.4 ROADMAP.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -398,6 +398,69 @@ Output JSON:
 
 **Score**: 6.5/10. Coste muy bajo (reusa lógica de filterJobForMode, sin ejecución), valor real en monorepos y CI orquestado. Encaja con la línea de "data-driven" de v3.3.
 
+### FEAT-13 · `--fast-dirty` — modo de ejecución sobre el working tree completo
+
+**Casos de uso reales**:
+
+1. **Hooks de IA agentic** (Claude Code, Cursor, Cline, Copilot agent…). El agente toca ficheros y queremos aplicar el **mismo** flow que en precommit, con `--format=json` para ahorrar tokens. Hoy los ficheros no están en stage → `--fast` los pierde, `--fast-branch` analiza demasiado, y la única salida es un script bash de ~10 líneas en cada hook que computa la lista y la pasa por `--files`. El QA debería ser uno: el flow del hook humano es el flow del hook IA.
+
+2. **Dev en revisión intermedia sin commitear**. Patrón estándar de desarrollo iterativo: "voy a revisar lo que llevo antes de commitear". Hoy o haces `git add -A && githooks flow qa --fast` (ensucia el stage) o te escribes el `--files` a mano. Ambas son fricción.
+
+**Hueco que rellena**:
+
+| Modo | Set | Para |
+|---|---|---|
+| `--fast` | staged | precommit |
+| `--fast-branch` | branch diff vs main + staged | CI feature branch |
+| `--fast-dirty` | HEAD diff (staged+unstaged) ∪ untracked | hooks IA, revisión intermedia |
+| full | paths completos | CI main/release |
+
+**Definición precisa del set**:
+
+```bash
+{ git diff --name-only --diff-filter=ACMR HEAD
+  git ls-files --others --exclude-standard
+} | sort -u
+```
+
+Tracked modificados vs HEAD (staged o no) ∪ untracked no ignorados.
+
+**Decisiones del diseño**:
+
+| Decisión | Valor |
+|---|---|
+| Nombre del flag | `--fast-dirty` (idiomático git: "dirty working tree" es término oficial; corto; sin ambigüedad con `--fast` que cubre solo staged) |
+| Implementación | `ExecutionContext::getWorktreeDiffFilesLazy()` análogo a `getBranchDiffFilesLazy()`; nuevo variant `ExecutionMode::FAST_DIRTY`; reconocer `fast-dirty` en `EffectiveOptionsResolver` |
+| Fallback | Tree limpio → todos los jobs accelerable skip, exit 0. NO cae a full (sería sorprendente y rompería el caso "git status limpio tras commit") |
+| Mutuamente excluyente con | `--fast`, `--fast-branch`, `--files`, `--files-from` (todos definen el set) |
+| Compatible con | `--exclude-pattern`, `--format`, `--report-json`, `--output`, `--fail-fast`, `--processes`, budgets |
+| Untracked | **Incluidos**. Documentar en docs que si hay scratch files en paths cubiertos, usar `.gitignore` o `--exclude-pattern`. Sin código nuevo (`--no-untracked` solo si aparece reporte real) |
+| Coexistencia con `--files-from=-` (stdin) | El stdin sigue funcionando, tiene su caso de uso (input arbitrario externo). FEAT-13 cubre el caso "set canónico del working tree" con semántica nombrada y testeada, sin pipa |
+
+**Composición con FEAT-1** (`only-files` / `exclude-files`):
+
+Dos niveles ortogonales — admisión (FEAT-1) y filtrado de input (modo + `paths` del job). FEAT-1 debe leer del set unificado vía `ExecutionContext::getFilteredFiles()`, no hardcodear por modo: si lo hace, FEAT-13 compone gratis.
+
+- **Skip por only-files**: dirty `src/AppB/User.php`, job con `only-files: ['src/AppA/**']` → `skipped: true, skipReason: "no files match only-files"`.
+- **Admisión + filtrado**: dirty `src/AppA/Foo.php` + `src/AppB/Bar.php`, job accelerable con `only-files: ['src/AppA/**']` y `paths: ['src/AppA']` → admite; al binario solo `src/AppA/Foo.php` (intersección con `paths`).
+- **Non-accelerable admitido**: dirty `composer.lock`, job non-accelerable con `only-files: ['composer.lock']` → corre la suite entera (FEAT-1 solo admite, no recorta input).
+
+Test matrix de FEAT-1 debe incluir un caso por modo accelerable, no solo `--fast`.
+
+**Tests obligatorios**:
+- Unit: cómputo del set (tree limpio, solo unstaged, solo untracked, mezcla, dentro de un git worktree real, repo con submodules).
+- Integration: flow run con working tree dirty, jobs accelerable y non-accelerable.
+- Mutua exclusión con `--fast`/`--fast-branch`/`--files`/`--files-from`.
+
+**Out of scope**:
+- Distinguir tracked dirty vs untracked vía flag (esperar reporte real de "scratch indeseado analizado").
+- Modo "fast-vs-upstream" (commits locales no en remote) para pre-push hooks; es un caso distinto, no encaja en este modo.
+- Aplicar `--fast-dirty` por defecto a hooks específicos (decisión del usuario en config).
+
+**Score**: 7/10. Coste bajo (~1 día código + tests, patrón ya existe en `getBranchDiffFilesLazy`); dos casos confirmados (uno con viento de cola fuerte: agentic IA en 2026); self-contained; aditivo. No bloquea ni depende de FEAT-1/2/3.
+
+**Por qué v3.4 y no "Pendiente de análisis"**: coste tan bajo que no compite con el resto del bloque en planning, y el caso agentic-IA tiene timing — retrasarlo a v3.5 cede el espacio a otra herramienta.
+
 ### Validación de commit messages como tipo nativo (`commit-msg`)
 
 Tipo de job nativo que valida el subject del commit con reglas declarativas (`min-length`, `max-length`, `pattern`, `forbid-trailing-period`, `subject-case`, `forbid-empty`, `merge-allowed`) y preset `conventional-commits`. Se cablea al hook git `commit-msg`. Movido el 2026-04-28: a nivel funcional v3.3 ya cumple el objetivo del usuario (multi-flow + multi-reporte + budgets); commit-msg pasa a "nice-to-have" sin urgencia. **Spec de diseño ya redactada** en `spec/spec-design-commit-message-validation.md` (~620 líneas, 17 AC, 34 REQ): cuando se reabra, la implementación arranca directa de ahí.
diff --git a/app/Commands/Concerns/FormatsOutput.php b/app/Commands/Concerns/FormatsOutput.php
@@ -57,9 +57,6 @@ private function applyFormat(FlowExecutor $executor, ?FlowPlan $plan = null): vo
 
         if ($isStructured) {
             $handler = $this->resolveProgressHandler();
-            if ($format === 'codeclimate' || $format === 'sarif') {
-                $executor->setStructuredFormat(true);
-            }
         } elseif (
             $plan === null
             || $plan->getOptions()->getProcesses() <= 1
@@ -72,13 +69,43 @@ private function applyFormat(FlowExecutor $executor, ?FlowPlan $plan = null): vo
             $handler = new DashboardOutputHandler();
         }
 
+        if ($this->needsToolJsonOutput($format, $plan)) {
+            $executor->setStructuredFormat(true);
+        }
+
         // CI decorator only for text format — structured formats write clean output
         if (!$isStructured) {
             $handler = $this->wrapWithCIDecorator($handler);
         }
         $executor->setOutputHandler($handler);
     }
 
+    /**
+     * Whether tool-level JSON output (e.g. phpstan `--error-format=json`,
+     * psalm `--output-format=json`) must be requested at runtime.
+     *
+     * Codeclimate and SARIF formatters parse each tool's stdout to extract
+     * issues. If the tools emit human text, the parsers find no JSON and
+     * the report comes out empty. The flag must be on whenever a codeclimate
+     * or sarif payload will be generated, regardless of how it was requested:
+     *
+     *   - `--format=codeclimate|sarif` (primary output).
+     *   - `reports.codeclimate` / `reports.sarif` in config (multi-report).
+     *   - `--report-codeclimate=PATH` / `--report-sarif=PATH` on CLI.
+     *
+     * `collectReportTargets()` already resolves CLI > config precedence and
+     * honours `--no-reports` (which suppresses config but not CLI flags).
+     */
+    private function needsToolJsonOutput(string $format, ?FlowPlan $plan): bool
+    {
+        if ($format === 'codeclimate' || $format === 'sarif') {
+            return true;
+        }
+        $options = $plan !== null ? $plan->getOptions() : null;
+        $reports = $this->collectReportTargets($options);
+        return isset($reports['codeclimate']) || isset($reports['sarif']);
+    }
+
     /**
      * Wrap handler with CI decorator if auto-detected and not disabled.
      */
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.2]
+
+### Fixed
+
+- Code Climate and SARIF reports requested via `flows.options.reports.codeclimate` / `reports.sarif` in config or via `--report-codeclimate=PATH` / `--report-sarif=PATH` CLI flags came out empty (`[]` / no findings) when the primary `--format` was anything other than `codeclimate` / `sarif`. The flag that asks each tool for JSON output only activated on `--format=codeclimate|sarif`, so every tool ran with its default human-text format and the report parsers (which all do `json_decode()` over stdout) found nothing to extract. Affects every tool with a JSON-dependent parser: PHPStan (`--error-format=json`), PHPCS (`--report=json`), PHPMD (positional `json` format), Psalm (`--output-format=json`) and parallel-lint (`--json`). Fixed: tool-level JSON output is now requested whenever a codeclimate or sarif payload will be produced, regardless of how it was requested.
+
 ## [3.3.1]
 
 ### Fixed
diff --git a/tests/System/Release/V32FeaturesReleaseTest.php b/tests/System/Release/V32FeaturesReleaseTest.php
@@ -586,6 +586,157 @@ public function conf_check_warns_when_cores_conflicts_with_native_flag()
         $this->assertStringContainsString("'cores' overrides 'parallel'", $output);
     }
 
+    // ========================================================================
+    // BUG-16 regression: codeclimate/sarif reports requested via reports.<X>
+    // config or --report-X CLI must trigger tool-level JSON output. Pre-3.3.2,
+    // structuredFormat activated only on --format=codeclimate|sarif, so phpstan
+    // ran with text output and the parser produced []. These tests exercise the
+    // .phar end-to-end with phpstan against a file that has a real error so the
+    // empty-payload regression cannot slip back into a release.
+    // ========================================================================
+
+    /** @test */
+    public function bug16_reports_codeclimate_in_config_captures_phpstan_issues_without_format_flag()
+    {
+        $srcDir = self::TESTS_PATH . '/src';
+        @mkdir($srcDir, 0777, true);
+        $phpstanFile = $this->phpFileBuilder->buildWithErrors([\Tests\Utils\PhpFileBuilder::PHPSTAN]);
+        file_put_contents("$srcDir/Bad.php", $phpstanFile);
+
+        $reportPath = self::TESTS_PATH . '/qa-cc.json';
+        @unlink($reportPath);
+
+        $this->configurationFileBuilder
+            ->setV3GlobalOptions(['reports' => ['codeclimate' => $reportPath]])
+            ->setV3Flows(['qa' => ['jobs' => ['phpstan_src']]])
+            ->setV3Jobs([
+                'phpstan_src' => ['type' => 'phpstan', 'level' => 0, 'paths' => [$srcDir]],
+            ]);
+        file_put_contents($this->configPath, $this->configurationFileBuilder->buildV3Php());
+
+        // No --format. Pre-fix, this triggered the bug: phpstan ran with text
+        // output and the codeclimate file was '[]'.
+        shell_exec("$this->githooks flow qa --config=$this->configPath 2>/dev/null");
+
+        $this->assertFileExists($reportPath);
+        $decoded = json_decode((string) file_get_contents($reportPath), true);
+        $this->assertIsArray($decoded);
+        $this->assertNotEmpty(
+            $decoded,
+            'codeclimate report must contain phpstan issues; an empty array means structuredFormat was not propagated'
+        );
+
+        $hasPhpstanIssue = false;
+        foreach ($decoded as $issue) {
+            if (
+                ($issue['check_name'] ?? '') === 'phpstan'
+                || strpos($issue['check_name'] ?? '', '.') !== false
+            ) {
+                $hasPhpstanIssue = true;
+                break;
+            }
+        }
+        $this->assertTrue($hasPhpstanIssue, 'codeclimate payload must include at least one phpstan issue');
+
+        @unlink($reportPath);
+    }
+
+    /** @test */
+    public function bug16_reports_codeclimate_in_config_captures_issues_from_all_tool_types()
+    {
+        // Same bug, different surface: pre-fix the bypass affected EVERY tool
+        // whose parser depends on JSON tool output (phpcs, phpmd, phpstan,
+        // psalm, parallel-lint — all of them). Verifies that activating
+        // structuredFormat reaches each Job's applyStructuredOutputFormat()
+        // through the Phar build, not just phpstan.
+        $srcDir = self::TESTS_PATH . '/src';
+        @mkdir($srcDir, 0777, true);
+        // Build a single file with phpcs + phpmd violations.
+        // (phpstan is tested in the previous case; combining all here keeps
+        // the assertion focused on "more than one tool reports".)
+        $multiToolFile = $this->phpFileBuilder->buildWithErrors([
+            \Tests\Utils\PhpFileBuilder::PHPCS,
+            \Tests\Utils\PhpFileBuilder::PHPMD,
+        ]);
+        file_put_contents("$srcDir/Bad.php", $multiToolFile);
+
+        $reportPath = self::TESTS_PATH . '/qa-cc.json';
+        @unlink($reportPath);
+
+        $this->configurationFileBuilder
+            ->setV3GlobalOptions(['reports' => ['codeclimate' => $reportPath]])
+            ->setV3Flows(['qa' => ['jobs' => ['phpcs_src', 'phpmd_src']]])
+            ->setV3Jobs([
+                'phpcs_src' => ['type' => 'phpcs', 'standard' => 'PSR12', 'paths' => [$srcDir]],
+                'phpmd_src' => ['type' => 'phpmd', 'paths' => [$srcDir]],
+            ]);
+        file_put_contents($this->configPath, $this->configurationFileBuilder->buildV3Php());
+
+        shell_exec("$this->githooks flow qa --config=$this->configPath 2>/dev/null");
+
+        $this->assertFileExists($reportPath);
+        $decoded = json_decode((string) file_get_contents($reportPath), true);
+        $this->assertIsArray($decoded);
+        $this->assertNotEmpty(
+            $decoded,
+            'codeclimate report must contain issues from at least one tool; empty means structuredFormat was not propagated'
+        );
+
+        // At least one of each tool must have produced an issue: pre-fix every
+        // tool's stdout was text and json_decode returned null, so neither
+        // would appear in the payload.
+        $tools = [];
+        foreach ($decoded as $issue) {
+            $check = (string) ($issue['check_name'] ?? '');
+            if (strpos($check, 'Squiz.') === 0 || strpos($check, 'PSR12.') === 0 || strpos($check, 'Generic.') === 0) {
+                $tools['phpcs'] = true;
+            }
+            // phpmd uses bare rule names like 'ExcessiveParameterList', 'ShortVariable'
+            if ($check !== '' && strpos($check, '.') === false && $check !== 'phpstan') {
+                $tools['phpmd'] = true;
+            }
+        }
+        $this->assertArrayHasKey('phpcs', $tools, 'codeclimate payload must include at least one phpcs issue (Squiz/PSR12/Generic.* prefix)');
+        $this->assertArrayHasKey('phpmd', $tools, 'codeclimate payload must include at least one phpmd issue (bare rule name)');
+
+        @unlink($reportPath);
+    }
+
+    /** @test */
+    public function bug16_cli_report_sarif_captures_phpstan_issues_without_format_flag()
+    {
+        $srcDir = self::TESTS_PATH . '/src';
+        @mkdir($srcDir, 0777, true);
+        $phpstanFile = $this->phpFileBuilder->buildWithErrors([\Tests\Utils\PhpFileBuilder::PHPSTAN]);
+        file_put_contents("$srcDir/Bad.php", $phpstanFile);
+
+        $reportPath = self::TESTS_PATH . '/qa.sarif';
+        @unlink($reportPath);
+
+        $this->configurationFileBuilder
+            ->setV3Flows(['qa' => ['jobs' => ['phpstan_src']]])
+            ->setV3Jobs([
+                'phpstan_src' => ['type' => 'phpstan', 'level' => 0, 'paths' => [$srcDir]],
+            ]);
+        file_put_contents($this->configPath, $this->configurationFileBuilder->buildV3Php());
+
+        // CLI flag without --format. Pre-fix, structuredFormat stayed false and
+        // SARIF.runs[0].results was empty.
+        shell_exec("$this->githooks flow qa --report-sarif=$reportPath --config=$this->configPath 2>/dev/null");
+
+        $this->assertFileExists($reportPath);
+        $decoded = json_decode((string) file_get_contents($reportPath), true);
+        $this->assertIsArray($decoded);
+        $this->assertSame('2.1.0', $decoded['version'] ?? null);
+        $results = $decoded['runs'][0]['results'] ?? [];
+        $this->assertNotEmpty(
+            $results,
+            'SARIF runs[0].results must contain phpstan findings; empty means structuredFormat was not propagated'
+        );
+
+        @unlink($reportPath);
+    }
+
     /** @test */
     public function dashboard_falls_back_to_streaming_when_stdout_is_not_a_tty()
     {
diff --git a/tests/Unit/Output/FormatsOutputTraitTest.php b/tests/Unit/Output/FormatsOutputTraitTest.php
