Merge branch 'main' into 243

Author: njoubert-cleverage

CHANGELOG.md

@@ -4,9 +4,14 @@ Latest
 ## Changes
 * [#197](https://github.com/cleverage/process-bundle/issues/197) Add missing tests: every Task and Transformer is now covered by unit tests. Remove the obsolete `tests.old` directory.
 * [#143](https://github.com/cleverage/process-bundle/issues/143) Improve PHPStan configuration: remove all `ignoreErrors` and `@phpstan-ignore` comments (report unmatched ignored errors again), add missing iterable value types and generic types in PHPDoc, remove unreachable code in AbstractIterableOutputTask and InputAggregatorTask.
+* [#143](https://github.com/cleverage/process-bundle/issues/143) Improve PHPStan level from 6 to 7, and fix the level 8 errors that do not require a signature change (the remaining ones, due to nullable return types such as `AbstractConfigurableTask::getOptions(): ?array`, will be fixed in v6.0). Default to a `ContextualOptionResolver` in ProcessState and to a property accessor in ConditionTrait when none is set.
 
 ## Fixes
 * [#143](https://github.com/cleverage/process-bundle/issues/143) Fix InputIteratorTask: an `\IteratorAggregate` input whose `getIterator()` does not return an `\Iterator` (e.g. another `\IteratorAggregate`) is iterated instead of failing with a `TypeError`. Update documentation, add tests.
+* [#143](https://github.com/cleverage/process-bundle/issues/143) Fix level 8 edge cases failing with a `TypeError` or an `Error`: `CsvResource` rejects a blank header line and checks `ftell()`, XpathEvaluatorTransformer throws an explicit `\UnexpectedValueException` on an invalid query (with the libxml messages), a namespace node to unwrap or a node without document, SlugifyTransformer on a value that cannot be transliterated, `ProcessState::getContext()` returns `[]` until the context is defined, GenericTransformer and TransformerTrait throw a `\LogicException` when not initialized, IterableBatchTask and JsonStreamReaderTask can be flushed / iterated before their first execution, RegistryCompilerPass checks its configuration, SubprocessInstance checks the PHP executable. Update documentation, add tests.
+* [#239](https://github.com/cleverage/process-bundle/issues/239) Fix PropertyGetterTask: catch any `\Throwable`, so that the `TypeError` of the property accessor on a scalar input is set on the state (with the `property` error context) and handled according to the task `error_strategy` instead of escaping it. Update documentation, add tests.
+* [#241](https://github.com/cleverage/process-bundle/issues/241) Fix CsvWriterTask: a non-array input throws the documented `\UnexpectedValueException` instead of a `TypeError` when `headers` is `null`, and the CSV tasks release their file on `finalize()` so that the task can be executed again. Update documentation, add tests.
+* [#240](https://github.com/cleverage/process-bundle/issues/240) Fix FileMoverTask: with `autoincrement`, the suffix was computed on the whole path (a dot in a directory name was taken as the extension, making the move fail for a file without extension) and an existing numeric suffix of the file name was replaced (`report-2024.csv` became `report-1.csv`). The suffix is now appended to the file name only (`report-2024-1.csv`, `file-1`, `.env-1`). Update documentation, add tests.
 * [#243](https://github.com/cleverage/process-bundle/issues/243) Fix RecursivePropertySetterTransformer: a `\stdClass` item without the property was replaced by a copy in the output, so the input object was not modified; the property is now added to the item itself. Update documentation, add tests.
 
 v5.1

docs/reference/tasks/csv_reader_task.md

@@ -70,7 +70,8 @@ Notes
 -----
 
 * Each line must contain exactly as many columns as there are headers, otherwise an `\UnexpectedValueException` is thrown.
-* A UTF-8 BOM is removed from the first header when headers are read from the file.
+* A UTF-8 BOM is removed from the first header when headers are read from the file. If the first line is blank, an
+  `\UnexpectedValueException` is thrown.
 * `csv_file` and `csv_line` are added to the error context of the process.
 * The file is closed once fully read: if the task is executed again (e.g. for a new input), the file is read again
   from its beginning.

docs/reference/tasks/csv_writer_task.md

@@ -76,5 +76,6 @@ Notes
 * `{date}` is replaced by `Ymd`, `{date_time}` by `Ymd_His`, `{timestamp}` by the Unix timestamp and `{unique_token}`
   by a `uniqid()` value.
 * The parent directory of the file is created if needed.
+* An input that is not an `array` throws an `\UnexpectedValueException`.
 * Each input must contain every header key (extra keys are not allowed: the number of columns must match the number of
   headers), otherwise an `\UnexpectedValueException` is thrown. Columns are written in the headers order.

docs/reference/tasks/file_mover_task.md

@@ -26,7 +26,7 @@ Options
 |-----------------|----------|:--------:|---------|--------------------------------------------------------------------------------------------------------------------------|
 | `destination`   | `string` |  **X**   |         | Destination path. If it is an existing directory, the original file name is kept                                         |
 | `overwrite`     | `bool`   |          | `false` | Allow overwriting an existing file at destination (otherwise an exception is thrown)                                     |
-| `autoincrement` | `bool`   |          | `false` | If the destination file exists, add or increment a numeric suffix before the extension (e.g. `file-1.csv`, `file-2.csv`) |
+| `autoincrement` | `bool`   |          | `false` | If the destination file exists, append the first free numeric suffix to the file name, before its extension (e.g. `file-1.csv`, `file-2.csv`) |
 
 Examples
 --------
@@ -46,3 +46,6 @@ Notes
 -----
 
 * Underlying method is Symfony `Filesystem::rename()`.
+* With `autoincrement`, only the file name is changed (never the directory part), and the suffix is always appended to
+  the original name: `report-2024.csv` becomes `report-2024-1.csv`, `file` becomes `file-1`, `archive.tar.gz` becomes
+  `archive.tar-1.gz` and a hidden file `.env` becomes `.env-1`.

docs/reference/tasks/property_getter_task.md

@@ -21,8 +21,8 @@ Possible outputs
 
 `mixed`: the value read at the `property` path.
 
-If the value cannot be read, the exception is set on the state (with the `property` added to the error context) and
-handled according to the task `error_strategy`.
+If the value cannot be read (including a `\TypeError` of the property accessor, e.g. on a scalar input), the exception
+is set on the state (with the `property` added to the error context) and handled according to the task `error_strategy`.
 
 Options
 -------

docs/reference/transformers/slugify_transformer.md

@@ -58,3 +58,5 @@ Notes
 An invalid `transliterator` identifier (rejected by `\Transliterator::create()`), or an option that is not a string,
 raises an `InvalidOptionsException` when the options are resolved, i.e. when the transformer is configured, not on the
 first transformed value.
+
+A value that cannot be transliterated (e.g. invalid UTF-8) throws an `\UnexpectedValueException`.

docs/reference/transformers/xpath_evaluator_transformer.md

@@ -17,7 +17,8 @@ Transformer reference
 Accepted inputs
 ---------------
 
-`\DOMNode` (including `\DOMDocument`). Any other value throws an `\UnexpectedValueException`.
+`\DOMNode` (including `\DOMDocument`). Any other value, a node that does not belong to a document or an invalid xpath
+query throws an `\UnexpectedValueException`.
 
 Possible outputs
 ----------------

phpstan.neon

@@ -1,5 +1,5 @@
 parameters:
-    level: 6
+    level: 7
     paths:
         - src
         - tests

src/Command/ListProcessCommand.php

@@ -125,6 +125,6 @@ protected function padMessage(string $message, int $length = 80): string
 
     protected function filterOutTags(string $string): string
     {
-        return preg_replace('/<[^<>]*>/', '', $string);
+        return preg_replace('/<[^<>]*>/', '', $string) ?? $string;
     }
 }

src/Command/ProcessHelpCommand.php

@@ -107,12 +107,13 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $totalBranches = \count($taskList);
         for ($i = 0; $i < $totalBranches; ++$i) {
             // Find the best task to display
-            $nextTaskCode = $this->findBestNextTask($branches, $remainingTasks, $process);
+            // A numeric task code may be returned as an integer array key
+            $nextTaskCode = (string) $this->findBestNextTask($branches, $remainingTasks, $process);
 
             $this->resolveBranchOutput($branches, $nextTaskCode, $process, $output);
 
             // Remove the task from the remaining list
-            $remainingTasks = array_filter($remainingTasks, static fn ($task): bool => $task !== $nextTaskCode);
+            $remainingTasks = array_values(array_filter($remainingTasks, static fn ($task): bool => $task !== $nextTaskCode));
         }
 
         $branches = array_filter($branches);
@@ -127,8 +128,8 @@ protected function execute(InputInterface $input, OutputInterface $output): int
     /**
      * Try to find a best candidate for next display.
      *
-     * @param array<string|null> $branches
-     * @param list<string>       $taskList
+     * @param array<int, string|null> $branches
+     * @param list<string>            $taskList
      */
     protected function findBestNextTask(
         array $branches,
@@ -227,7 +228,7 @@ protected function getTaskChildrenCount(TaskConfiguration $task): int
     /**
      * Merge needed branches, display a task node, split following needed branches.
      *
-     * @param array<string|null> $branches
+     * @param array<int, string|null> $branches
      */
     protected function resolveBranchOutput(
         array &$branches,
@@ -293,7 +294,12 @@ protected function resolveBranchOutput(
 
             $origin = array_shift($branchesToMerge);
             $final = $gapFrom;
-            $branches[$origin] = $taskCode;
+            if (null === $origin) {
+                // No previous branch found (an error has been displayed): open a new branch
+                $branches[] = $taskCode;
+            } else {
+                $branches[$origin] = $taskCode;
+            }
         }
 
         // Merge branches
@@ -377,6 +383,9 @@ static function ($taskCode, $i) use ($gapBranches, $origin, $final, $branches):
             $this->writeBranches($output, $branches);
             array_shift($nextTasks);
             $origin = array_search($taskCode, $branches, true);
+            if (false === $origin) {
+                throw new \UnexpectedValueException("Task '{$taskCode}' is not in any branch");
+            }
             $expandBranches = [];
             foreach ($nextTasks as $nextTask) {
                 $index = array_search(null, $branches, true);
@@ -448,7 +457,7 @@ static function ($branchTask, $i) use ($origin, $branches, $gapBranches, $final)
     }
 
     /**
-     * @param array<string|null>      $branches
+     * @param array<int, string|null> $branches
      * @param string|iterable<string> $comment
      */
     protected function writeBranches(