[console] Suppress structured progress preambles

coisa · coisa · commit 37b5ba1f1b01 · 2026-05-01T16:40:28.000-03:00
diff --git a/src/Console/Command/CodeStyleCommand.php b/src/Console/Command/CodeStyleCommand.php
@@ -121,7 +121,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $fix = (bool) $input->getOption('fix');
         $progress = ! $jsonOutput && (bool) $input->getOption('progress');
 
-        $this->logger->info('Running code style checks and fixes...');
+        $this->intermediateInfo('Running code style checks and fixes...', $input);
 
         $composerUpdate = $this->processBuilder
             ->withArgument('--lock')
diff --git a/src/Console/Command/DependenciesCommand.php b/src/Console/Command/DependenciesCommand.php
@@ -150,11 +150,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             );
         }
 
-        if (! $jsonOutput) {
-            $this->logger->info('Running dependency analysis...', [
-                'input' => $input,
-            ]);
-        }
+        $this->intermediateInfo('Running dependency analysis...', $input);
 
         $this->processQueue->add(
             process: $this->getComposerDependencyAnalyserCommand($input),
diff --git a/src/Console/Command/DocsCommand.php b/src/Console/Command/DocsCommand.php
@@ -155,9 +155,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $template = DevToolsPathResolver::getPreferredVendorPath(self::DEFAULT_TEMPLATE);
         }
 
-        $this->logger->info('Generating API documentation...', [
-            'input' => $input,
-        ]);
+        $this->intermediateInfo('Generating API documentation...', $input);
 
         if (
             ! $projectCapabilities->hasGuideDirectory()
diff --git a/src/Console/Command/MetricsCommand.php b/src/Console/Command/MetricsCommand.php
@@ -135,9 +135,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $exclude = (string) $input->getOption('exclude');
         $junit = $input->getOption('junit');
 
-        $this->logger->info('Running code metrics analysis...', [
-            'input' => $input,
-        ]);
+        $this->intermediateInfo('Running code metrics analysis...', $input);
 
         $processBuilder = $this->processBuilder
             ->withArgument('--ansi')
diff --git a/src/Console/Command/PhpDocCommand.php b/src/Console/Command/PhpDocCommand.php
@@ -152,11 +152,9 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $progress = ! $jsonOutput && (bool) $input->getOption('progress');
         $cacheEnabled = $this->isCacheEnabled($input);
 
-        $this->logger->info('Checking and fixing PHPDocs...', [
-            'input' => $input,
-        ]);
+        $this->intermediateInfo('Checking and fixing PHPDocs...', $input);
 
-        $this->ensureDocHeaderExists();
+        $this->ensureDocHeaderExists($input);
 
         $processBuilder = $this->processBuilder
             ->withArgument('--ansi')
@@ -231,9 +229,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int
      * The method MUST query the local filesystem. If the file is missing, it SHOULD copy
      * the tool template into the root folder.
      *
+     * @param InputInterface $input the originating command input
+     *
      * @return void
      */
-    private function ensureDocHeaderExists(): void
+    private function ensureDocHeaderExists(InputInterface $input): void
     {
         $support = $this->composer->getSupport();
 
@@ -265,6 +265,6 @@ private function ensureDocHeaderExists(): void
             return;
         }
 
-        $this->logger->info('Created .docheader from repository template.');
+        $this->intermediateInfo('Created .docheader from repository template.', $input);
     }
 }
diff --git a/src/Console/Command/RefactorCommand.php b/src/Console/Command/RefactorCommand.php
@@ -120,9 +120,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $fix = (bool) $input->getOption('fix');
         $progress = ! $jsonOutput && (bool) $input->getOption('progress');
 
-        $this->logger->info('Running Rector for code refactoring...', [
-            'input' => $input,
-        ]);
+        $this->intermediateInfo('Running Rector for code refactoring...', $input);
 
         $processBuilder = $this->processBuilder
             ->withArgument('--ansi')
diff --git a/src/Console/Command/ReportsCommand.php b/src/Console/Command/ReportsCommand.php
@@ -129,9 +129,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $coveragePath = (string) $input->getOption('coverage');
         $metricsPath = (string) $input->getOption('metrics');
 
-        $this->logger->info('Generating frontpage for Fast Forward documentation...', [
-            'input' => $input,
-        ]);
+        $this->intermediateInfo('Generating frontpage for Fast Forward documentation...', $input);
 
         $docsBuilder = $this->processBuilder
             ->withArgument('--target', $target);
diff --git a/src/Console/Command/StandardsCommand.php b/src/Console/Command/StandardsCommand.php
@@ -109,9 +109,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $commands = [];
         $fix = (bool) $input->getOption('fix');
 
-        $this->logger->info('Running code standards checks...', [
-            'input' => $input,
-        ]);
+        $this->intermediateInfo('Running code standards checks...', $input);
 
         foreach (['refactor', 'phpdoc', 'code-style', 'reports'] as $command) {
             $commands[] = $command;
diff --git a/src/Console/Command/SyncCommand.php b/src/Console/Command/SyncCommand.php
@@ -112,9 +112,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         ];
         $allowDetached = ! $dryRun && ! $check && ! $interactive;
 
-        $this->logger->info('Starting dev-tools synchronization...', [
-            'input' => $input,
-        ]);
+        $this->intermediateInfo('Starting dev-tools synchronization...', $input);
 
         $this->queueDevToolsCommand(['update-composer-json', ...$modeArguments], false, $jsonOutput, $prettyJsonOutput);
         $this->queueDevToolsCommand(['funding', ...$modeArguments], false, $jsonOutput, $prettyJsonOutput);
diff --git a/src/Console/Command/Traits/LogsCommandResults.php b/src/Console/Command/Traits/LogsCommandResults.php
@@ -34,6 +34,28 @@ trait LogsCommandResults
 {
     use HasCommandLogger;
 
+    /**
+     * Logs a non-terminal informational message unless structured JSON output is active.
+     *
+     * @param string $message the progress message
+     * @param InputInterface $input the originating command input
+     * @param array<string, mixed> $context optional extra log context
+     *
+     * @return void
+     */
+    private function intermediateInfo(string $message, InputInterface $input, array $context = []): void
+    {
+        if (method_exists($this, 'isJsonOutput') && $this->isJsonOutput($input)) {
+            return;
+        }
+
+        $this->getLogger()
+            ->info($message, [
+                'input' => $input,
+                ...$context,
+            ]);
+    }
+
     /**
      * Logs an informational command message at notice level.
      *
diff --git a/src/Console/Command/WikiCommand.php b/src/Console/Command/WikiCommand.php
@@ -140,11 +140,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             return $this->initializeWikiSubmodule($input, $target, $processOutput);
         }
 
-        if (! $jsonOutput) {
-            $this->logger->info('Generating wiki documentation...', [
-                'input' => $input,
-            ]);
-        }
+        $this->intermediateInfo('Generating wiki documentation...', $input);
 
         $projectCapabilities = $this->projectCapabilitiesResolver->resolve(wikiTarget: $target);
 
diff --git a/tests/Console/Command/CodeStyleCommandTest.php b/tests/Console/Command/CodeStyleCommandTest.php
@@ -122,7 +122,9 @@ public function executeWillReturnSuccessWhenProcessQueueSucceeds(): void
         $this->processQueue->run(Argument::type('object'))
             ->willReturn(CodeStyleCommand::SUCCESS)
             ->shouldBeCalled();
-        $this->logger->info('Running code style checks and fixes...')
+        $this->logger->info('Running code style checks and fixes...', Argument::that(
+            fn(array $context): bool => $this->input->reveal() === $context['input']
+        ))
             ->shouldBeCalled();
         $this->logger->log(
             'info',
@@ -147,7 +149,9 @@ public function executeWillReturnFailureWhenProcessQueueFails(): void
         $this->processQueue->run(Argument::type('object'))
             ->willReturn(CodeStyleCommand::FAILURE)
             ->shouldBeCalled();
-        $this->logger->info('Running code style checks and fixes...')
+        $this->logger->info('Running code style checks and fixes...', Argument::that(
+            fn(array $context): bool => $this->input->reveal() === $context['input']
+        ))
             ->shouldBeCalled();
         $this->logger->error(
             'Code style checks failed.',
@@ -180,8 +184,8 @@ public function executeWillCaptureBufferedOutputWhenJsonIsRequested(): void
         $this->processQueue->run(Argument::type('object'))
             ->willReturn(CodeStyleCommand::SUCCESS)
             ->shouldBeCalled();
-        $this->logger->info('Running code style checks and fixes...')
-            ->shouldBeCalled();
+        $this->logger->info(Argument::cetera())
+            ->shouldNotBeCalled();
         $this->logger->log(
             'info',
             'Code style checks completed successfully.',
diff --git a/tests/Console/Command/DependenciesCommandTest.php b/tests/Console/Command/DependenciesCommandTest.php
@@ -174,6 +174,32 @@ public function executeWillIgnoreJackFailuresWhenMaxOutdatedIsDisabled(): void
         self::assertSame(DependenciesCommand::SUCCESS, $this->executeCommand());
     }
 
+    /**
+     * @return void
+     */
+    #[Test]
+    public function executeWillSuppressProgressLogWhenJsonIsRequested(): void
+    {
+        $this->input->getOption('json')
+            ->willReturn(true);
+        $this->input->getOption('pretty-json')
+            ->willReturn(false);
+        $this->processQueue->add(Argument::type(Process::class), false, Argument::cetera())->shouldBeCalledTimes(4);
+        $this->processQueue->run(Argument::type(OutputInterface::class))
+            ->willReturn(DependenciesCommand::SUCCESS)
+            ->shouldBeCalledOnce();
+        $this->logger->info(Argument::cetera())
+            ->shouldNotBeCalled();
+        $this->logger->log(
+            'info',
+            'Dependency analysis completed successfully.',
+            Argument::that(static fn(array $context): bool => $context['input'] instanceof InputInterface
+                && $context['output'] instanceof OutputInterface),
+        )->shouldBeCalledOnce();
+
+        self::assertSame(DependenciesCommand::SUCCESS, $this->executeCommand());
+    }
+
     /**
      * @return void
      */
diff --git a/tests/Console/Command/DocsCommandTest.php b/tests/Console/Command/DocsCommandTest.php
@@ -286,6 +286,38 @@ public function executeWillReturnSuccessWhenProcessQueueSucceeds(): void
         self::assertSame(DocsCommand::SUCCESS, $this->executeCommand());
     }
 
+    /**
+     * @return void
+     */
+    #[Test]
+    public function executeWillSuppressProgressLogWhenJsonIsRequested(): void
+    {
+        $this->input->getOption('json')
+            ->willReturn(true);
+        $this->input->getOption('pretty-json')
+            ->willReturn(false);
+        $this->filesystem->dumpFile('phpdocumentor.xml', '<phpdocumentor />', '/repo/.dev-tools/cache/phpdoc')
+            ->shouldBeCalled();
+        $this->processBuilder->withArgument('--cache-folder', '/repo/.dev-tools/cache/phpdoc')
+            ->willReturn($this->processBuilder->reveal())
+            ->shouldBeCalled();
+        $this->processQueue->add($this->process->reveal(), Argument::cetera())
+            ->shouldBeCalled();
+        $this->processQueue->run(Argument::type(OutputInterface::class))
+            ->willReturn(DocsCommand::SUCCESS)
+            ->shouldBeCalled();
+        $this->logger->info(Argument::cetera())
+            ->shouldNotBeCalled();
+        $this->logger->log(
+            'info',
+            'API documentation generated successfully.',
+            Argument::that(static fn(array $context): bool => $context['input'] instanceof InputInterface
+                && $context['output'] instanceof OutputInterface),
+        )->shouldBeCalled();
+
+        self::assertSame(DocsCommand::SUCCESS, $this->executeCommand());
+    }
+
     /**
      * @return void
      */
diff --git a/tests/Console/Command/MetricsCommandTest.php b/tests/Console/Command/MetricsCommandTest.php
@@ -186,6 +186,14 @@ public function executeWillRunPhpMetricsInQuietModeWhenJsonIsRequested(): void
         $this->processQueue->run(Argument::type(OutputInterface::class))
             ->willReturn(MetricsCommand::SUCCESS)
             ->shouldBeCalled();
+        $this->logger->info(Argument::cetera())
+            ->shouldNotBeCalled();
+        $this->logger->log(
+            'info',
+            'Code metrics analysis completed successfully.',
+            Argument::that(static fn(array $context): bool => $context['input'] instanceof InputInterface
+                && $context['output'] instanceof OutputInterface),
+        )->shouldBeCalled();
 
         self::assertSame(MetricsCommand::SUCCESS, $this->executeCommand());
     }
diff --git a/tests/Console/Command/PhpDocCommandTest.php b/tests/Console/Command/PhpDocCommandTest.php
@@ -201,7 +201,9 @@ public function executeWillCreateDocHeaderAndRunPhpDocProcesses(): void
             static fn(array $context): bool => $context['input'] instanceof InputInterface
         ))
             ->shouldBeCalled();
-        $this->logger->info('Created .docheader from repository template.')
+        $this->logger->info('Created .docheader from repository template.', Argument::that(
+            static fn(array $context): bool => $context['input'] instanceof InputInterface
+        ))
             ->shouldBeCalled();
         $this->logger->log(
             'info',
@@ -289,6 +291,14 @@ public function executeWillRequestStructuredOutputAndDisableProgressWhenJsonIsRe
         $this->processQueue->run(Argument::type(OutputInterface::class))
             ->willReturn(PhpDocCommand::SUCCESS)
             ->shouldBeCalled();
+        $this->logger->info(Argument::cetera())
+            ->shouldNotBeCalled();
+        $this->logger->log(
+            'info',
+            'PHPDoc checks completed successfully.',
+            Argument::that(static fn(array $context): bool => $context['input'] instanceof InputInterface
+                && $context['output'] instanceof OutputInterface),
+        )->shouldBeCalled();
 
         self::assertSame(PhpDocCommand::SUCCESS, $this->invokeExecute());
     }
diff --git a/tests/Console/Command/RefactorCommandTest.php b/tests/Console/Command/RefactorCommandTest.php
@@ -174,6 +174,14 @@ public function executeWillRequestJsonOutputAndDisableProgressWhenJsonIsRequeste
         $this->processQueue->run(Argument::type(OutputInterface::class))
             ->willReturn(RefactorCommand::SUCCESS)
             ->shouldBeCalled();
+        $this->logger->info(Argument::cetera())
+            ->shouldNotBeCalled();
+        $this->logger->log(
+            'info',
+            'Code refactoring checks completed successfully.',
+            Argument::that(static fn(array $context): bool => $context['input'] instanceof InputInterface
+                && $context['output'] instanceof OutputInterface),
+        )->shouldBeCalled();
 
         self::assertSame(RefactorCommand::SUCCESS, $this->executeCommand());
     }
diff --git a/tests/Console/Command/ReportsCommandTest.php b/tests/Console/Command/ReportsCommandTest.php
@@ -152,10 +152,8 @@ public function executeWillCaptureBufferedOutputWhenJsonIsRequested(): void
         $this->processQueue->run(Argument::type('object'))
             ->willReturn(ReportsCommand::FAILURE)
             ->shouldBeCalledOnce();
-        $this->logger->info('Generating frontpage for Fast Forward documentation...', Argument::that(
-            static fn(array $context): bool => $context['input'] instanceof InputInterface
-        ))
-            ->shouldBeCalled();
+        $this->logger->info(Argument::cetera())
+            ->shouldNotBeCalled();
         $this->logger->error(
             'Documentation reports generation failed.',
             Argument::that(static fn(array $context): bool => $context['input'] instanceof InputInterface
diff --git a/tests/Console/Command/StandardsCommandTest.php b/tests/Console/Command/StandardsCommandTest.php
@@ -177,6 +177,37 @@ public function executeWithCacheWillForwardCacheOnlyToCacheAwareNestedCommands()
         self::assertSame(StandardsCommand::SUCCESS, $this->invokeExecute());
     }
 
+    /**
+     * @return void
+     */
+    #[Test]
+    public function executeWillSuppressProgressLogWhenJsonIsRequested(): void
+    {
+        $this->input->getOption('json')
+            ->willReturn(true);
+        $this->input->getOption('pretty-json')
+            ->willReturn(false);
+        $this->processBuilder->withArgument('--json')
+            ->willReturn($this->processBuilder->reveal())
+            ->shouldBeCalledTimes(4);
+        $this->processQueue->add(Argument::type(Process::class), Argument::cetera())
+            ->shouldBeCalledTimes(4);
+        $this->processQueue->run(Argument::type(OutputInterface::class))
+            ->willReturn(StandardsCommand::SUCCESS)
+            ->shouldBeCalledOnce();
+        $this->logger->info(Argument::cetera())
+            ->shouldNotBeCalled();
+        $this->logger->log(
+            'info',
+            'Code standards checks completed successfully.',
+            Argument::that(static fn(array $context): bool => $context['input'] instanceof InputInterface
+                && $context['output'] instanceof OutputInterface
+                && ['refactor', 'phpdoc', 'code-style', 'reports'] === $context['commands']),
+        )->shouldBeCalled();
+
+        self::assertSame(StandardsCommand::SUCCESS, $this->invokeExecute());
+    }
+
     /**
      * @return void
      */
diff --git a/tests/Console/Command/SyncCommandTest.php b/tests/Console/Command/SyncCommandTest.php
@@ -164,10 +164,8 @@ public function executeWillPropagateJsonOutputFormatToSubCommands(): void
         $this->processQueue->run(Argument::type('object'))
             ->willReturn(SyncCommand::SUCCESS)
             ->shouldBeCalledOnce();
-        $this->logger->info('Starting dev-tools synchronization...', Argument::that(
-            static fn(array $context): bool => $context['input'] instanceof InputInterface
-        ))
-            ->shouldBeCalled();
+        $this->logger->info(Argument::cetera())
+            ->shouldNotBeCalled();
         $this->logger->log(
             'info',
             'Dev-tools synchronization completed successfully.',
diff --git a/tests/Console/Command/WikiCommandTest.php b/tests/Console/Command/WikiCommandTest.php

Original file line number	Diff line number	Diff line change
`@@ -155,9 +155,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int`
`155`	`155`	`$template = DevToolsPathResolver::getPreferredVendorPath(self::DEFAULT_TEMPLATE);`
`156`	`156`	`}`
`157`	`157`
`158`		`- $this->logger->info('Generating API documentation...', [`
`159`		`- 'input' => $input,`
`160`		`- ]);`
	`158`	`+ $this->intermediateInfo('Generating API documentation...', $input);`
`161`	`159`
`162`	`160`	`if (`
`163`	`161`	`! $projectCapabilities->hasGuideDirectory()`
Original file line number	Diff line number	Diff line change
`@@ -152,11 +152,9 @@ protected function execute(InputInterface $input, OutputInterface $output): int`
`152`	`152`	`$progress = ! $jsonOutput && (bool) $input->getOption('progress');`
`153`	`153`	`$cacheEnabled = $this->isCacheEnabled($input);`
`154`	`154`
`155`		`- $this->logger->info('Checking and fixing PHPDocs...', [`
`156`		`- 'input' => $input,`
`157`		`- ]);`
	`155`	`+ $this->intermediateInfo('Checking and fixing PHPDocs...', $input);`
`158`	`156`
`159`		`- $this->ensureDocHeaderExists();`
	`157`	`+ $this->ensureDocHeaderExists($input);`
`160`	`158`
`161`	`159`	`$processBuilder = $this->processBuilder`
`162`	`160`	`->withArgument('--ansi')`
`@@ -231,9 +229,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int`
`231`	`229`	`* The method MUST query the local filesystem. If the file is missing, it SHOULD copy`
`232`	`230`	`* the tool template into the root folder.`
`233`	`231`	`*`
	`232`	`+ * @param InputInterface $input the originating command input`
	`233`	`+ *`
`234`	`234`	`* @return void`
`235`	`235`	`*/`
`236`		`- private function ensureDocHeaderExists(): void`
	`236`	`+ private function ensureDocHeaderExists(InputInterface $input): void`
`237`	`237`	`{`
`238`	`238`	`$support = $this->composer->getSupport();`
`239`	`239`
`@@ -265,6 +265,6 @@ private function ensureDocHeaderExists(): void`
`265`	`265`	`return;`
`266`	`266`	`}`
`267`	`267`
`268`		`- $this->logger->info('Created .docheader from repository template.');`
	`268`	`+ $this->intermediateInfo('Created .docheader from repository template.', $input);`
`269`	`269`	`}`
`270`	`270`	`}`