refactor: classify release plan failures

src/Application/Console/Command/ReleasePlanCommand.php

@@ -4,12 +4,14 @@
 
 namespace LibreCode\ReleaseTool\Application\Console\Command;
 
-use DomainException;
-use InvalidArgumentException;
 use LibreCode\ReleaseTool\Application\Configuration\ConsumerConfigContextValidator;
 use LibreCode\ReleaseTool\Application\Configuration\ConsumerConfigLoader;
 use LibreCode\ReleaseTool\Application\Configuration\NoopConsumerConfigContextValidator;
+use LibreCode\ReleaseTool\Application\Release\Exception\InvalidReleasePlanRequest;
+use LibreCode\ReleaseTool\Application\Release\Exception\ReleasePlanConfigurationFailure;
+use LibreCode\ReleaseTool\Application\Release\Exception\ReleasePlanRuleViolation;
 use LibreCode\ReleaseTool\Application\Release\ReleasePlanning;
+use LibreCode\ReleaseTool\Application\Release\ReleasePlanUseCase;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
@@ -21,12 +23,15 @@ final class ReleasePlanCommand extends Command
 {
     public const int EXIT_NOT_READY = 3;
 
+    private readonly ReleasePlanUseCase $useCase;
+
     public function __construct(
-        private readonly ReleasePlanning $planner,
-        private readonly ConsumerConfigLoader $configLoader = new ConsumerConfigLoader(),
-        private readonly ConsumerConfigContextValidator $contextValidator = new NoopConsumerConfigContextValidator(),
+        ReleasePlanning $planner,
+        ConsumerConfigLoader $configLoader = new ConsumerConfigLoader(),
+        ConsumerConfigContextValidator $contextValidator = new NoopConsumerConfigContextValidator(),
         private readonly ReleasePlanOutputPublisher $publisher = new ReleasePlanOutputPublisher(),
     ) {
+        $this->useCase = new ReleasePlanUseCase($planner, $configLoader, $contextValidator);
         parent::__construct();
     }
 
@@ -55,11 +60,9 @@ protected function execute(InputInterface $input, OutputInterface $output): int
     {
         try {
             $request = ReleasePlanCommandRequest::fromInput($input);
-            $config = $this->configLoader->load($request->configPath);
-            $this->contextValidator->validate($config, $request->root);
-            $plan = $this->planner->plan($config, $request->planInput);
+            $plan = $this->useCase->execute($request->configPath, $request->root, $request->planInput);
             $this->publisher->publish($plan, $request->output, $output);
-        } catch (InvalidArgumentException|DomainException $exception) {
+        } catch (InvalidReleasePlanRequest|ReleasePlanConfigurationFailure|ReleasePlanRuleViolation $exception) {
             return $this->error($output, $input, $exception->getMessage());
         }
 

src/Application/Console/Command/ReleasePlanCommandRequest.php

@@ -4,7 +4,7 @@
 
 namespace LibreCode\ReleaseTool\Application\Console\Command;
 
-use InvalidArgumentException;
+use LibreCode\ReleaseTool\Application\Release\Exception\InvalidReleasePlanRequest;
 use LibreCode\ReleaseTool\Application\Release\PlanReleaseInput;
 use LibreCode\ReleaseTool\Domain\Security\ReleaseMode;
 use LibreCode\ReleaseTool\Domain\Version\ReleaseChannel;
@@ -43,7 +43,7 @@ private static function requiredString(InputInterface $input, string $name): str
     {
         $value = self::optionalString($input->getOption($name));
         if ($value === null) {
-            throw new InvalidArgumentException(sprintf('--%s is required.', $name));
+            throw new InvalidReleasePlanRequest(sprintf('--%s is required.', $name));
         }
 
         return $value;
@@ -63,7 +63,7 @@ private static function enumOption(
         $value = (string) $input->getOption($name);
         $resolved = $enum::tryFrom($value);
         if ($resolved === null) {
-            throw new InvalidArgumentException(sprintf('Invalid --%s; expected %s.', $name, $expected));
+            throw new InvalidReleasePlanRequest(sprintf('Invalid --%s; expected %s.', $name, $expected));
         }
 
         return $resolved;

src/Application/Release/Exception/InvalidReleasePlanRequest.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LibreCode\ReleaseTool\Application\Release\Exception;
+
+final class InvalidReleasePlanRequest extends \InvalidArgumentException
+{
+}

src/Application/Release/Exception/ReleasePlanConfigurationFailure.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LibreCode\ReleaseTool\Application\Release\Exception;
+
+final class ReleasePlanConfigurationFailure extends \InvalidArgumentException
+{
+}

src/Application/Release/Exception/ReleasePlanRuleViolation.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LibreCode\ReleaseTool\Application\Release\Exception;
+
+final class ReleasePlanRuleViolation extends \DomainException
+{
+}

src/Application/Release/Port/GitRepository.php

@@ -19,6 +19,8 @@ public function isAncestor(string $ancestorSha, string $descendantSha): bool;
 
     public function tagExists(string $tag): bool;
 
+    public function fileExists(string $sha, string $path): bool;
+
     public function readFile(string $sha, string $path): string;
 
     public function commitDate(string $sha): string;

src/Application/Release/ReleasePlanUseCase.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LibreCode\ReleaseTool\Application\Release;
+
+use InvalidArgumentException;
+use LibreCode\ReleaseTool\Application\Configuration\ConsumerConfigContextValidator;
+use LibreCode\ReleaseTool\Application\Configuration\ConsumerConfigLoader;
+use LibreCode\ReleaseTool\Application\Release\Exception\ReleasePlanConfigurationFailure;
+use LibreCode\ReleaseTool\Domain\Release\ReleasePlan;
+
+final readonly class ReleasePlanUseCase
+{
+    public function __construct(
+        private ReleasePlanning $planner,
+        private ConsumerConfigLoader $configLoader,
+        private ConsumerConfigContextValidator $contextValidator,
+    ) {
+    }
+
+    public function execute(string $configPath, string $root, PlanReleaseInput $input): ReleasePlan
+    {
+        try {
+            $config = $this->configLoader->load($configPath);
+            $this->contextValidator->validate($config, $root);
+        } catch (InvalidArgumentException $exception) {
+            throw new ReleasePlanConfigurationFailure($exception->getMessage(), 0, $exception);
+        }
+
+        return $this->planner->plan($config, $input);
+    }
+}

src/Application/Release/ReleasePlanner.php

@@ -4,7 +4,7 @@
 
 namespace LibreCode\ReleaseTool\Application\Release;
 
-use DomainException;
+use LibreCode\ReleaseTool\Application\Release\Exception\ReleasePlanRuleViolation;
 use LibreCode\ReleaseTool\Application\Release\Port\GitHubRepository;
 use LibreCode\ReleaseTool\Application\Release\Port\GitRepository;
 use LibreCode\ReleaseTool\Application\Release\Port\ReleaseMetadataReader;
@@ -42,7 +42,7 @@ public function plan(ConsumerConfig $config, PlanReleaseInput $input): ReleasePl
         $branchHead = $this->git->branchHead($input->branch);
         $baseSha = $input->ref !== null ? $this->git->resolve($input->ref) : $branchHead;
         if (!$this->git->isAncestor($baseSha, $branchHead)) {
-            throw new DomainException('Planning ref must be equal to or an ancestor of the selected branch head.');
+            throw new ReleasePlanRuleViolation('Planning ref must be equal to or an ancestor of the selected branch head.');
         }
 
         $repository = $this->repositoryIdentity($config);
@@ -52,7 +52,7 @@ public function plan(ConsumerConfig $config, PlanReleaseInput $input): ReleasePl
 
         $previous = $this->git->previousRelease($baseSha, $config->tagPrefix, $config->initialRef);
         if (!$this->git->isAncestor($previous->sha, $baseSha)) {
-            throw new DomainException('Previous release baseline is not an ancestor of the planning base.');
+            throw new ReleasePlanRuleViolation('Previous release baseline is not an ancestor of the planning base.');
         }
 
         [$activity, $activityData, $warnings] = $this->releaseActivity(
@@ -62,27 +62,23 @@ public function plan(ConsumerConfig $config, PlanReleaseInput $input): ReleasePl
             $baseSha,
         );
         if (!$activity->hasReleasableActivity()) {
-            throw new DomainException('No releasable activity exists after the previous release.');
+            throw new ReleasePlanRuleViolation('No releasable activity exists after the previous release.');
         }
 
         $proposed = $this->proposedVersion($config, $metadata->version, $activity, $input);
         if ($proposed->major !== $appMajor) {
-            throw new DomainException('A release plan cannot change the app major implicitly.');
+            throw new ReleasePlanRuleViolation('A release plan cannot change the app major implicitly.');
         }
 
         $targetTag = $config->tagPrefix . (string) $proposed;
         if ($this->git->tagExists($targetTag) || $this->github->releaseExists($repository, $targetTag)) {
-            throw new DomainException(sprintf('Target tag or release already exists: %s', $targetTag));
+            throw new ReleasePlanRuleViolation(sprintf('Target tag or release already exists: %s', $targetTag));
         }
 
         $changelogTarget = str_replace('{major}', (string) $appMajor, $config->changelogPath);
-        try {
-            $this->git->readFile($baseSha, $changelogTarget);
-        } catch (\Throwable $exception) {
-            throw new DomainException(
+        if (!$this->git->fileExists($baseSha, $changelogTarget)) {
+            throw new ReleasePlanRuleViolation(
                 sprintf('Configured changelog target does not exist at planning base: %s', $changelogTarget),
-                0,
-                $exception,
             );
         }
 
@@ -181,12 +177,12 @@ private function repositoryIdentity(ConsumerConfig $config): string
         $repository = $config->repository ?? $gitRepository ?? $environmentRepository;
 
         if ($repository === null) {
-            throw new DomainException('Repository identity is unavailable; configure repository explicitly.');
+            throw new ReleasePlanRuleViolation('Repository identity is unavailable; configure repository explicitly.');
         }
 
         foreach ([$gitRepository, $environmentRepository] as $candidate) {
             if ($candidate !== null && strcasecmp($repository, $candidate) !== 0) {
-                throw new DomainException(sprintf(
+                throw new ReleasePlanRuleViolation(sprintf(
                     'Repository identity mismatch: configured %s, observed %s.',
                     $repository,
                     $candidate,
@@ -383,8 +379,12 @@ private function proposedVersion(
             $value = substr($value, strlen($config->tagPrefix));
         }
 
-        $override = Version::parse($value);
-        $this->versionTransitions->validateOverride($current, $override, $input->channel);
+        try {
+            $override = Version::parse($value);
+            $this->versionTransitions->validateOverride($current, $override, $input->channel);
+        } catch (\InvalidArgumentException $exception) {
+            throw new ReleasePlanRuleViolation($exception->getMessage(), 0, $exception);
+        }
 
         return $override;
     }

src/Infrastructure/Git/LocalGitRepository.php

@@ -83,6 +83,20 @@ public function tagExists(string $tag): bool
         return $process->getExitCode() === 0;
     }
 
+    public function fileExists(string $sha, string $path): bool
+    {
+        $process = new Process(['git', 'ls-tree', '--name-only', $sha, '--', $path], $this->root);
+        $process->run();
+
+        if (!$process->isSuccessful()) {
+            throw new DomainException(
+                trim($process->getErrorOutput()) ?: sprintf('Unable to inspect file %s at %s.', $path, $sha),
+            );
+        }
+
+        return trim($process->getOutput()) !== '';
+    }
+
     public function readFile(string $sha, string $path): string
     {
         return $this->run(['git', 'show', $sha . ':' . $path]);