From c147cbb21c86b48623ea1076fff84db43fac01bb Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Fri, 30 Oct 2026 11:39:03 -0300 Subject: [PATCH 1/2] feat: add docblocks for constructors across multiple classes to enhance code clarity. --- CHANGELOG.md | 1 + src/Config/InstalledPackages.php | 2 ++ src/Config/ProjectConfig.php | 2 ++ src/Config/ProjectContext.php | 2 ++ src/Config/ProviderPackage.php | 2 ++ src/Console/Command/AbstractScaffoldCommand.php | 6 +++--- src/Console/ComposerIoWriter.php | 2 ++ src/Console/SymfonyOutputWriter.php | 2 ++ src/Manifest/FileMapping.php | 2 ++ src/Manifest/ManifestLoader.php | 2 ++ src/Merge/MergeResult.php | 2 ++ src/Scaffold/ExpectedState.php | 2 ++ src/Scaffold/FileApplier.php | 2 ++ src/Scaffold/Lock/LockFile.php | 2 ++ src/Scaffold/Modes/ApplyResult.php | 2 ++ src/Scaffold/ScaffoldRunner.php | 2 ++ src/Scaffold/Scaffolder.php | 2 ++ src/Services/ApplyPreview.php | 2 ++ 18 files changed, 36 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6bf2656..2960925 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - feat!: rename package to `php-forge/scaffold` with namespace `PHPForge\Scaffold`; update `require`, `allow-plugins` and class references. - feat!: overhaul sync, merge modes and CLI; enforce strict manifests and locks; support Console 8 and drop Composer runtime dependency. +- feat: add docblocks for constructors across multiple classes to enhance code clarity. ## 0.2.0 July 04, 2026 diff --git a/src/Config/InstalledPackages.php b/src/Config/InstalledPackages.php index 17e5474..33358be 100644 --- a/src/Config/InstalledPackages.php +++ b/src/Config/InstalledPackages.php @@ -18,6 +18,8 @@ final readonly class InstalledPackages { /** + * Creates an installed-package view from normalized Composer metadata. + * * @param array|null $packages Installed packages keyed by * name, with their pretty version and absolute install path, or `null` when the installed packages are unknown. */ diff --git a/src/Config/ProjectConfig.php b/src/Config/ProjectConfig.php index a9cea7b..83f30e7 100644 --- a/src/Config/ProjectConfig.php +++ b/src/Config/ProjectConfig.php @@ -21,6 +21,8 @@ final readonly class ProjectConfig { /** + * Creates consumer settings from normalized scaffold and vendor-directory values. + * * @param list $allowedPackages Package names allowed to write scaffold files, in declaration order. * @param bool $auto Whether the Composer hooks scaffold automatically. * @param int $ignoredEntries Number of non-string `allowed-packages` entries that were ignored. diff --git a/src/Config/ProjectContext.php b/src/Config/ProjectContext.php index e698028..4936ae6 100644 --- a/src/Config/ProjectContext.php +++ b/src/Config/ProjectContext.php @@ -18,6 +18,8 @@ final readonly class ProjectContext { /** + * Creates a project context from its resolved filesystem and Composer metadata. + * * @param string $projectRoot Absolute path to the project root. * @param string $vendorDir Absolute path to the Composer vendor directory. * @param ProjectConfig $config Consumer settings from the project `composer.json`. diff --git a/src/Config/ProviderPackage.php b/src/Config/ProviderPackage.php index d55812d..fb94e6c 100644 --- a/src/Config/ProviderPackage.php +++ b/src/Config/ProviderPackage.php @@ -10,6 +10,8 @@ final readonly class ProviderPackage { /** + * Creates an installed provider descriptor. + * * @param string $name Composer package name. * @param string $prettyVersion Installed version recorded in `scaffold-lock.json`. * @param string|null $installPath Absolute install path, or `null` for a package without files, such as a diff --git a/src/Console/Command/AbstractScaffoldCommand.php b/src/Console/Command/AbstractScaffoldCommand.php index 30209aa..a63051c 100644 --- a/src/Console/Command/AbstractScaffoldCommand.php +++ b/src/Console/Command/AbstractScaffoldCommand.php @@ -36,13 +36,13 @@ abstract class AbstractScaffoldCommand extends Command abstract protected function handle(InputInterface $input, SymfonyOutputWriter $out, string $projectRoot): int; /** - * Validates the input, resolves the project root and runs {@see self::handle()}. + * Validates the input, resolves the project root and runs {@see AbstractScaffoldCommand::handle()}. * * @param InputInterface $input Command input that may carry the global `--working-dir` option. * @param OutputInterface $output Console output that receives the command output and the error messages. * - * @return int Exit code of {@see self::handle()}; `1` when the project root is not found or a runtime error is - * reported; `2` when the input is invalid. + * @return int Exit code of {@see AbstractScaffoldCommand::handle()}; `1` when the project root is not found or a + * runtime error is reported; `2` when the input is invalid. */ final protected function execute(InputInterface $input, OutputInterface $output): int { diff --git a/src/Console/ComposerIoWriter.php b/src/Console/ComposerIoWriter.php index e6acae5..76961b2 100644 --- a/src/Console/ComposerIoWriter.php +++ b/src/Console/ComposerIoWriter.php @@ -12,6 +12,8 @@ final readonly class ComposerIoWriter implements OutputWriter { /** + * Creates a writer for Composer IO. + * * @param IOInterface $io Composer IO that receives the messages. */ public function __construct(private IOInterface $io) {} diff --git a/src/Console/SymfonyOutputWriter.php b/src/Console/SymfonyOutputWriter.php index 25c84ae..bdb0611 100644 --- a/src/Console/SymfonyOutputWriter.php +++ b/src/Console/SymfonyOutputWriter.php @@ -13,6 +13,8 @@ final readonly class SymfonyOutputWriter implements OutputWriter { /** + * Creates a writer for a Symfony Console output. + * * @param OutputInterface $output Console output that receives the messages and, through its error output when it * is a {@see \Symfony\Component\Console\Output\ConsoleOutputInterface}, the standard error messages. */ diff --git a/src/Manifest/FileMapping.php b/src/Manifest/FileMapping.php index 74b5357..0c88f8a 100644 --- a/src/Manifest/FileMapping.php +++ b/src/Manifest/FileMapping.php @@ -12,6 +12,8 @@ final readonly class FileMapping { /** + * Creates a provider file mapping. + * * @param string $destination Destination path relative to the project root, using forward slashes. * @param string $source Source path relative to the provider root, using forward slashes. * @param FileMode $mode Write mode applied to the destination. diff --git a/src/Manifest/ManifestLoader.php b/src/Manifest/ManifestLoader.php index 0d458ee..7e6c423 100644 --- a/src/Manifest/ManifestLoader.php +++ b/src/Manifest/ManifestLoader.php @@ -21,6 +21,8 @@ final readonly class ManifestLoader { /** + * Creates a loader with its schema validator and mapping expander. + * * @param ManifestSchema $schema Validates the manifest. * @param ManifestExpander $expander Expands the validated manifest into file mappings. */ diff --git a/src/Merge/MergeResult.php b/src/Merge/MergeResult.php index ba1d6d6..d55b875 100644 --- a/src/Merge/MergeResult.php +++ b/src/Merge/MergeResult.php @@ -10,6 +10,8 @@ final readonly class MergeResult { /** + * Creates the result of a merge operation. + * * @param string $content Merged content; byte-identical to the consumer when `$changed` is `false`. * @param bool $changed Whether `$content` differs from the consumer content. */ diff --git a/src/Scaffold/ExpectedState.php b/src/Scaffold/ExpectedState.php index fc33e56..2b6e98d 100644 --- a/src/Scaffold/ExpectedState.php +++ b/src/Scaffold/ExpectedState.php @@ -28,6 +28,8 @@ private const int ORPHAN_LIST_LIMIT = 10; /** + * Creates an expected state from merged mappings and provider diagnostics. + * * @param array $mappings Expected mappings keyed by destination. * @param list $failedProviders Allowed and installed providers whose manifest could not be loaded. * @param list $warnings Messages about provider roots and manifests, prefixed with `[scaffold]`. diff --git a/src/Scaffold/FileApplier.php b/src/Scaffold/FileApplier.php index eed6e49..b3b4239 100644 --- a/src/Scaffold/FileApplier.php +++ b/src/Scaffold/FileApplier.php @@ -19,6 +19,8 @@ final readonly class FileApplier { /** + * Creates an applier for validated provider mappings. + * * @param ProjectConfig $config Consumer settings that list the providers allowed to write files. * @param PathValidator $pathValidator Validates destinations and sources. * @param OutputWriter $out Output sink that receives mode warnings on stderr. diff --git a/src/Scaffold/Lock/LockFile.php b/src/Scaffold/Lock/LockFile.php index bd43570..71f0127 100644 --- a/src/Scaffold/Lock/LockFile.php +++ b/src/Scaffold/Lock/LockFile.php @@ -70,6 +70,8 @@ final class LockFile private array|null $unknownKeys = null; /** + * Creates a lock-file store for a project. + * * @param string $projectRoot Absolute path to the project root that holds `scaffold-lock.json`. */ public function __construct(private readonly string $projectRoot) {} diff --git a/src/Scaffold/Modes/ApplyResult.php b/src/Scaffold/Modes/ApplyResult.php index f4cd08b..877ecd7 100644 --- a/src/Scaffold/Modes/ApplyResult.php +++ b/src/Scaffold/Modes/ApplyResult.php @@ -10,6 +10,8 @@ final readonly class ApplyResult { /** + * Creates the result of applying a file mapping. + * * @param ApplyOutcome $outcome Whether the destination was written or left unchanged. * @param string $newHash Hash of the destination after the operation, or an empty string when a user-modified * destination was skipped. diff --git a/src/Scaffold/ScaffoldRunner.php b/src/Scaffold/ScaffoldRunner.php index 35ed413..138e61c 100644 --- a/src/Scaffold/ScaffoldRunner.php +++ b/src/Scaffold/ScaffoldRunner.php @@ -46,6 +46,8 @@ private array $modes; /** + * Creates a runner and its mode implementations. + * * @param ManifestLoader $loader Loads provider manifests into file mappings. * @param FileApplier $applier Validates and applies each mapping. * @param LockFile $lockFile Lock file of the project. diff --git a/src/Scaffold/Scaffolder.php b/src/Scaffold/Scaffolder.php index d60f173..4203476 100644 --- a/src/Scaffold/Scaffolder.php +++ b/src/Scaffold/Scaffolder.php @@ -17,6 +17,8 @@ final readonly class Scaffolder { /** + * Creates the Composer adapter for a scaffold run. + * * @param ManifestLoader $loader Loads provider manifests into file mappings. * @param FileApplier $applier Validates and applies each mapping. * @param LockFile $lockFile Lock file of the project. diff --git a/src/Services/ApplyPreview.php b/src/Services/ApplyPreview.php index 9536490..d02a245 100644 --- a/src/Services/ApplyPreview.php +++ b/src/Services/ApplyPreview.php @@ -17,6 +17,8 @@ final readonly class ApplyPreview { /** + * Creates a preview of applying a provider mapping. + * * @param FileMapping $mapping Mapping that would be applied. * @param bool $exists Whether the destination exists on disk. * @param string $current Destination content on disk; an empty string when the destination does not exist. From 4b858e756c7423c61190a990f406d9a933df941d Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Fri, 30 Oct 2026 11:59:56 -0300 Subject: [PATCH 2/2] Apply fixed Coderabbitai review. --- src/Config/InstalledPackages.php | 2 +- src/Config/ProjectConfig.php | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Config/InstalledPackages.php b/src/Config/InstalledPackages.php index 33358be..dcb38d8 100644 --- a/src/Config/InstalledPackages.php +++ b/src/Config/InstalledPackages.php @@ -18,7 +18,7 @@ final readonly class InstalledPackages { /** - * Creates an installed-package view from normalized Composer metadata. + * Creates an installed-package view from normalized Composer metadata, or an unknown view from `null`. * * @param array|null $packages Installed packages keyed by * name, with their pretty version and absolute install path, or `null` when the installed packages are unknown. diff --git a/src/Config/ProjectConfig.php b/src/Config/ProjectConfig.php index 83f30e7..5e6ac1b 100644 --- a/src/Config/ProjectConfig.php +++ b/src/Config/ProjectConfig.php @@ -21,7 +21,7 @@ final readonly class ProjectConfig { /** - * Creates consumer settings from normalized scaffold and vendor-directory values. + * Creates consumer settings from scaffold configuration and the configured vendor-directory value. * * @param list $allowedPackages Package names allowed to write scaffold files, in declaration order. * @param bool $auto Whether the Composer hooks scaffold automatically.