refactor: improve docblocks for changelog classes and interfaces & add tests

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

src/Changelog/BootstrapResult.php

@@ -24,9 +24,11 @@
 final readonly class BootstrapResult
 {
     /**
-     * @param bool $configCreated
-     * @param bool $changelogCreated
-     * @param bool $unreleasedCreated
+     * Creates a new instance of `BootstrapResult`.
+     *
+     * @param bool $configCreated indicates whether the configuration file was created during bootstrap
+     * @param bool $changelogCreated Indicates whether the changelog file was created during bootstrap
+     * @param bool $unreleasedCreated Indicates whether the unreleased changelog file was created during bootstrap
      */
     public function __construct(
         public bool $configCreated,

src/Changelog/Bootstrapper.php

@@ -21,7 +21,6 @@
 use Symfony\Component\Filesystem\Filesystem;
 use Symfony\Component\Filesystem\Path;
 
-use function Safe\file_get_contents;
 use function rtrim;
 use function str_contains;
 use function str_replace;
@@ -34,51 +33,50 @@
 final readonly class Bootstrapper implements BootstrapperInterface
 {
     /**
-     * @param Filesystem|null $filesystem
-     * @param HistoryGeneratorInterface|null $historyGenerator
-     * @param KeepAChangelogConfigRenderer|null $configRenderer
+     * Initializes the `Bootstrapper` with optional dependencies.
+     *
+     * @param Filesystem $filesystem filesystem instance for file operations, allowing for easier testing and potential customization
+     * @param HistoryGeneratorInterface $historyGenerator history generator instance for generating changelog history
+     * @param KeepAChangelogConfigRenderer $configRenderer config renderer instance for rendering keep-a-changelog configuration
      */
     public function __construct(
-        private ?Filesystem $filesystem = null,
-        private ?HistoryGeneratorInterface $historyGenerator = null,
-        private ?KeepAChangelogConfigRenderer $configRenderer = null,
+        private Filesystem $filesystem = new Filesystem(),
+        private HistoryGeneratorInterface $historyGenerator = new HistoryGenerator(),
+        private KeepAChangelogConfigRenderer $configRenderer = new KeepAChangelogConfigRenderer(),
     ) {}
 
     /**
+     * Bootstraps changelog automation assets in the given working directory.
+     *
      * @param string $workingDirectory
      *
      * @return BootstrapResult
      */
     public function bootstrap(string $workingDirectory): BootstrapResult
     {
-        $filesystem = $this->filesystem ?? new Filesystem();
         $configPath = Path::join($workingDirectory, '.keep-a-changelog.ini');
         $changelogPath = Path::join($workingDirectory, 'CHANGELOG.md');
 
         $configCreated = false;
         $changelogCreated = false;
         $unreleasedCreated = false;
 
-        if (! $filesystem->exists($configPath)) {
-            $filesystem->dumpFile($configPath, ($this->configRenderer ?? new KeepAChangelogConfigRenderer())->render());
+        if (! $this->filesystem->exists($configPath)) {
+            $this->filesystem->dumpFile($configPath, $this->configRenderer->render());
             $configCreated = true;
         }
 
-        if (! $filesystem->exists($changelogPath)) {
-            $filesystem->dumpFile(
-                $changelogPath,
-                ($this->historyGenerator ?? new HistoryGenerator())
-                    ->generate($workingDirectory),
-            );
+        if (! $this->filesystem->exists($changelogPath)) {
+            $this->filesystem->dumpFile($changelogPath, $this->historyGenerator->generate($workingDirectory));
             $changelogCreated = true;
 
             return new BootstrapResult($configCreated, $changelogCreated, $unreleasedCreated);
         }
 
-        $contents = file_get_contents($changelogPath);
+        $contents = $this->filesystem->readFile($changelogPath);
 
         if (! str_contains($contents, '## Unreleased - ')) {
-            $filesystem->dumpFile($changelogPath, $this->prependUnreleasedSection($contents));
+            $this->filesystem->dumpFile($changelogPath, $this->prependUnreleasedSection($contents));
             $unreleasedCreated = true;
         }
 

src/Changelog/BootstrapperInterface.php

@@ -20,10 +20,17 @@
 
 /**
  * Bootstraps repository-local changelog automation artifacts.
+ *
+ * The BootstrapperInterface defines a contract for bootstrapping changelog automation assets in a given working directory.
+ * Implementations of this interface are MUST setup necessary files, configurations, or other resources required to enable
+ * changelog automation in a repository. The bootstrap method takes a working directory as input and returns a BootstrapResult
+ * indicating the outcome of the bootstrapping process.
  */
 interface BootstrapperInterface
 {
     /**
+     * Bootstraps changelog automation assets in the given working directory.
+     *
      * @param string $workingDirectory
      *
      * @return BootstrapResult

src/Changelog/CommitClassifier.php

@@ -30,9 +30,11 @@
 final readonly class CommitClassifier implements CommitClassifierInterface
 {
     /**
-     * @param string $subject
+     * Classifies a commit subject into a changelog section based on conventional prefixes and keywords.
      *
-     * @return string
+     * @param string $subject commit subject to classify
+     *
+     * @return string Changelog section name (e.g., "Added", "Changed", "Deprecated", "Removed", "Fixed", "Security", or "Uncategorized").
      */
     public function classify(string $subject): string
     {
@@ -64,9 +66,11 @@ public function classify(string $subject): string
     }
 
     /**
-     * @param string $subject
+     * Normalizes a commit subject by stripping conventional prefixes, tags, and extra whitespace, while preserving the core message.
+     *
+     * @param string $subject commit subject to normalize
      *
-     * @return string
+     * @return string normalized commit subject
      */
     public function normalize(string $subject): string
     {

src/Changelog/CommitClassifierInterface.php

@@ -20,20 +20,37 @@
 
 /**
  * Maps raw commit subjects to Keep a Changelog sections.
+ *
+ * The CommitClassifierInterface defines a contract for classifying commit subjects into specific changelog
+ * sections based on conventional prefixes and keywords.
+ *
+ * Implementations of this interface MUST analyze commit subjects and determine the appropriate
+ * changelog section (e.g., "Added", "Changed", "Deprecated", "Removed", "Fixed", "Security", or "Uncategorized") based
+ * on recognized patterns such as "fix:", "feat:", "docs:", "chore:", and security-related keywords.
  */
 interface CommitClassifierInterface
 {
     /**
-     * @param string $subject
+     * Classifies a commit subject into a changelog section based on conventional prefixes and keywords.
+     *
+     * The classification logic SHOULD recognize common patterns such as "fix:", "feat:", "docs:", "chore:",
+     * and security-related keywords, while also allowing for free-form subjects to be categorized under a default section.
      *
-     * @return string
+     * @param string $subject commit subject to classify
+     *
+     * @return string Changelog section name (e.g., "Added", "Changed", "Deprecated", "Removed", "Fixed", "Security", or "Uncategorized").
      */
     public function classify(string $subject): string;
 
     /**
-     * @param string $subject
+     * Normalizes a commit subject by stripping conventional prefixes, tags, and extra whitespace, while preserving the core message.
+     *
+     * The normalization process SHOULD remove any conventional commit type indicators (e.g., "fix:", "feat:", "docs:")
+     * and scope annotations (e.g., "(api)"),
+     *
+     * @param string $subject commit subject to normalize
      *
-     * @return string
+     * @return string normalized commit subject
      */
     public function normalize(string $subject): string;
 }

src/Changelog/GitProcessRunner.php

@@ -28,10 +28,12 @@
 final readonly class GitProcessRunner implements GitProcessRunnerInterface
 {
     /**
-     * @param list<string> $command
-     * @param string $workingDirectory
+     * Executes a git command in the specified working directory and returns the trimmed output.
      *
-     * @return string
+     * @param list<string> $command Git command to execute (e.g., ['git', 'log', '--oneline']).
+     * @param string $workingDirectory Directory in which to execute the command (e.g., repository root).
+     *
+     * @return string trimmed output from the executed command
      */
     public function run(array $command, string $workingDirectory): string
     {

src/Changelog/GitProcessRunnerInterface.php

@@ -20,16 +20,25 @@
 
 /**
  * Executes git-aware shell commands for changelog automation services.
+ *
+ * The GitProcessRunnerInterface defines a contract for executing git-related commands in the context of changelog automation.
+ * Implementations of this interface MUST run specified git commands in a given working directory and return the trimmed output.
+ * The run method takes a list of command arguments and a working directory as input, and it returns the output from the executed command,
+ * allowing changelog automation services to interact with git repositories effectively.
  */
 interface GitProcessRunnerInterface
 {
     /**
      * Runs a command in the provided working directory and returns stdout.
      *
-     * @param list<string> $command
-     * @param string $workingDirectory
+     * The method SHOULD execute the given command and return the trimmed output.
+     * The implementation MUST handle any necessary process execution and error handling,
+     * ensuring that the command is executed in the context of the specified working directory.
+     *
+     * @param list<string> $command Git command to execute (e.g., ['git', 'log', '--oneline']).
+     * @param string $workingDirectory Directory in which to execute the command (e.g., repository root).
      *
-     * @return string
+     * @return string trimmed output from the executed command
      */
     public function run(array $command, string $workingDirectory): string;
 }

src/Changelog/GitReleaseCollector.php

@@ -32,16 +32,20 @@
 final readonly class GitReleaseCollector implements GitReleaseCollectorInterface
 {
     /**
-     * @param GitProcessRunnerInterface $gitProcessRunner
+     * Initializes the GitReleaseCollector with a GitProcessRunner for executing git commands.
+     *
+     * @param GitProcessRunnerInterface $gitProcessRunner git process runner for executing git commands
      */
     public function __construct(
         private GitProcessRunnerInterface $gitProcessRunner = new GitProcessRunner()
     ) {}
 
     /**
-     * @param string $workingDirectory
+     * Collects release information from git tags in the specified working directory.
+     *
+     * @param string $workingDirectory Directory in which to execute git commands (e.g., repository root).
      *
-     * @return list<array{version: string, tag: string, date: string, commits: list<string>}>
+     * @return list<array{version: string, tag: string, date: string, commits: list<string>}> list of releases with version, tag, date, and associated commit subjects
      */
     public function collect(string $workingDirectory): array
     {
@@ -90,10 +94,12 @@ public function collect(string $workingDirectory): array
     }
 
     /**
-     * @param string $workingDirectory
-     * @param string $range
+     * Collects commit subjects for a given git range in the specified working directory.
      *
-     * @return list<string>
+     * @param string $workingDirectory Directory in which to execute git commands (e.g., repository root).
+     * @param string $range Git range to collect commits from (e.g., 'v1.0.0..v1.1.0' or 'v1.0.0').
+     *
+     * @return list<string> list of commit subjects for the specified range, excluding merges and ignored subjects
      */
     private function collectCommitSubjects(string $workingDirectory, string $range): array
     {
@@ -116,9 +122,11 @@ private function collectCommitSubjects(string $workingDirectory, string $range):
     }
 
     /**
-     * @param string $subject
+     * Determines whether a commit subject should be ignored based on common patterns (e.g., merge commits, wiki updates).
+     *
+     * @param string $subject commit subject to evaluate for ignoring
      *
-     * @return bool
+     * @return bool True if the subject should be ignored (e.g., empty, merge commits, wiki updates); false otherwise.
      */
     private function shouldIgnore(string $subject): bool
     {

src/Changelog/GitReleaseCollectorInterface.php

@@ -20,13 +20,22 @@
 
 /**
  * Discovers released tags and the commit subjects they contain.
+ *
+ * The GitReleaseCollectorInterface defines a contract for collecting release information from git tags in a specified working directory.
+ * Implementations of this interface are responsible for executing git commands to read tags and their associated commit subjects, building
+ * a structured list of releases that includes version, tag name, creation date, and commit
  */
 interface GitReleaseCollectorInterface
 {
     /**
-     * @param string $workingDirectory
+     * Collects release information from git tags in the specified working directory.
+     *
+     * The method SHOULD read git tags and their associated commit subjects to build a structured list of releases.
+     * Each release entry MUST include the version, tag name, creation date, and a list of commit subjects that are part of that release.
+     *
+     * @param string $workingDirectory Directory in which to execute git commands (e.g., repository root).
      *
-     * @return list<array{version: string, tag: string, date: string, commits: list<string>}>
+     * @return list<array{version: string, tag: string, date: string, commits: list<string>}> list of releases with version, tag, date, and associated commit subjects
      */
     public function collect(string $workingDirectory): array;
 }

src/Changelog/HistoryGenerator.php

@@ -26,14 +26,16 @@
 final readonly class HistoryGenerator implements HistoryGeneratorInterface
 {
     /**
-     * @param GitReleaseCollectorInterface $gitReleaseCollector
-     * @param CommitClassifierInterface $commitClassifier
-     * @param MarkdownRenderer|null $markdownRenderer
+     * Initializes the `HistoryGenerator` with optional dependencies.
+     *
+     * @param GitReleaseCollectorInterface $gitReleaseCollector git release collector instance for collecting release metadata and commit subjects
+     * @param CommitClassifierInterface $commitClassifier commit classifier instance for classifying and normalizing commit subjects into changelog sections
+     * @param MarkdownRenderer $markdownRenderer markdown renderer instance for rendering the final changelog markdown from structured release and commit data
      */
     public function __construct(
         private GitReleaseCollectorInterface $gitReleaseCollector = new GitReleaseCollector(),
         private CommitClassifierInterface $commitClassifier = new CommitClassifier(),
-        private ?MarkdownRenderer $markdownRenderer = null,
+        private MarkdownRenderer $markdownRenderer = new MarkdownRenderer(),
     ) {}
 
     /**
@@ -65,7 +67,6 @@ public function generate(string $workingDirectory): string
             ];
         }
 
-        return ($this->markdownRenderer ?? new MarkdownRenderer())
-            ->render($releases);
+        return $this->markdownRenderer->render($releases);
     }
 }