From 7789501cbf46a37bae00ffe00769bc743d62b270 Mon Sep 17 00:00:00 2001 From: Joey Smith Date: Fri, 13 Nov 2026 00:16:31 -0600 Subject: [PATCH 1/2] refactor(exception): gather the six failures into one Exception bucket All six failures now live in CommonDoc\Aggregate\Exception and end with the Exception suffix, matching the owner rule that every exception carries the suffix and lives in the Exception directory. Moved and renamed, bodies unchanged: - src/Config/InvalidSiteConfig.php -> src/Exception/InvalidSiteConfigException.php - src/Output/MissingCname.php -> src/Exception/MissingCnameException.php - src/Render/UnaddressableDocument.php -> src/Exception/UnaddressableDocumentException.php - src/Source/GitFailure.php -> src/Exception/GitFailureException.php - src/Source/MissingDocDirectory.php -> src/Exception/MissingDocDirectoryException.php - src/Source/SourceUnavailable.php -> src/Exception/SourceUnavailableException.php Every import, @throws docblock, throw statement, catch clause and test moves with them. ReasonCode enum cases keep their names: they are reason vocabulary, not classes. The dedicated tests moved to test/unit/Exception under CommonDocTest\Aggregate\Exception. No behaviour change. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/Build/ProjectBuild.php | 8 +++--- src/Build/SiteBuild.php | 4 +-- src/Config/Section.php | 22 ++++++++-------- src/Config/SiteConfigReader.php | 25 ++++++++++--------- src/Console/BuildCommand.php | 8 +++--- .../GitFailureException.php} | 4 +-- .../InvalidSiteConfigException.php} | 4 +-- .../MissingCnameException.php} | 5 ++-- .../MissingDocDirectoryException.php} | 4 +-- .../SourceUnavailableException.php} | 4 +-- .../UnaddressableDocumentException.php} | 4 +-- src/Output/CnameFile.php | 7 +++--- src/Render/TargetRenderer.php | 9 ++++--- src/Source/GitCandidates.php | 14 ++++++----- src/Source/GitCheckout.php | 16 ++++++------ src/Source/GitCommand.php | 7 +++--- src/Source/GitDocuments.php | 10 +++++--- src/Source/GitReferences.php | 7 +++--- src/Source/GitRunnerInterface.php | 4 ++- src/Source/GitSource.php | 12 +++++---- src/Source/SourceInterface.php | 10 +++++--- src/Version/Strategy.php | 6 ++--- test/unit/Build/SiteBuildTest.php | 10 ++++---- test/unit/BuildCommandTest.php | 10 ++++---- test/unit/Config/SectionTest.php | 4 +-- test/unit/Config/SiteConfigReaderTest.php | 4 +-- .../GitFailureExceptionTest.php} | 20 +++++++-------- .../InvalidSiteConfigExceptionTest.php} | 14 +++++------ .../MissingDocDirectoryExceptionTest.php} | 12 ++++----- .../SourceUnavailableExceptionTest.php} | 12 ++++----- test/unit/Output/CnameFileTest.php | 8 +++--- test/unit/Render/TargetRendererTest.php | 8 +++--- test/unit/Source/GitCandidatesTest.php | 4 +-- test/unit/Source/GitCheckoutTest.php | 10 ++++---- test/unit/Source/GitCommandTest.php | 6 ++--- test/unit/Source/GitDocumentsTest.php | 4 +-- test/unit/Source/GitReferencesTest.php | 6 ++--- test/unit/Support/GitRunner.php | 8 +++--- test/unit/Version/StrategyTest.php | 6 ++--- 39 files changed, 180 insertions(+), 160 deletions(-) rename src/{Source/GitFailure.php => Exception/GitFailureException.php} (95%) rename src/{Config/InvalidSiteConfig.php => Exception/InvalidSiteConfigException.php} (92%) rename src/{Output/MissingCname.php => Exception/MissingCnameException.php} (91%) rename src/{Source/MissingDocDirectory.php => Exception/MissingDocDirectoryException.php} (91%) rename src/{Source/SourceUnavailable.php => Exception/SourceUnavailableException.php} (92%) rename src/{Render/UnaddressableDocument.php => Exception/UnaddressableDocumentException.php} (93%) rename test/unit/{Source/GitFailureTest.php => Exception/GitFailureExceptionTest.php} (82%) rename test/unit/{Config/InvalidSiteConfigTest.php => Exception/InvalidSiteConfigExceptionTest.php} (78%) rename test/unit/{Source/MissingDocDirectoryTest.php => Exception/MissingDocDirectoryExceptionTest.php} (79%) rename test/unit/{Source/SourceUnavailableTest.php => Exception/SourceUnavailableExceptionTest.php} (81%) diff --git a/src/Build/ProjectBuild.php b/src/Build/ProjectBuild.php index 19af913..2de56cf 100644 --- a/src/Build/ProjectBuild.php +++ b/src/Build/ProjectBuild.php @@ -5,10 +5,10 @@ namespace CommonDoc\Aggregate\Build; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Render\SiteRendererInterface; -use CommonDoc\Aggregate\Source\MissingDocDirectory; use CommonDoc\Aggregate\Source\SourceInterface; -use CommonDoc\Aggregate\Source\SourceUnavailable; use CommonDoc\Aggregate\Version\Strategy; use CommonDoc\Aggregate\Version\StrategyFactory; use CommonDoc\Aggregate\Version\Target; @@ -43,7 +43,7 @@ public function outcome(Project $project, Strategy $strategy): ProjectOutcome $targets = $this->strategies ->create($strategy, $project) ->resolve($this->source->candidates($project)); - } catch (SourceUnavailable $sourceUnavailable) { + } catch (SourceUnavailableException $sourceUnavailable) { return ProjectOutcome::failed($project, $sourceUnavailable->reasonCode); } @@ -68,7 +68,7 @@ private function render(Project $project, array $targets): ProjectOutcome foreach ($targets as $target) { try { $documents = $this->source->documents($target); - } catch (MissingDocDirectory|SourceUnavailable $unavailable) { + } catch (MissingDocDirectoryException|SourceUnavailableException $unavailable) { $reasons[] = $unavailable->reasonCode; continue; diff --git a/src/Build/SiteBuild.php b/src/Build/SiteBuild.php index 83c5da0..623b5fe 100644 --- a/src/Build/SiteBuild.php +++ b/src/Build/SiteBuild.php @@ -7,8 +7,8 @@ use CommonDoc\Aggregate\Config\SiteConfig; use CommonDoc\Aggregate\Discovery\Project; use CommonDoc\Aggregate\Discovery\ProjectSourceInterface; +use CommonDoc\Aggregate\Exception\MissingCnameException; use CommonDoc\Aggregate\Output\CnameFile; -use CommonDoc\Aggregate\Output\MissingCname; use CommonDoc\Aggregate\Output\OutputTree; use CommonDoc\Aggregate\Render\SiteRendererInterface; use CommonDoc\Aggregate\Report\ReportFile; @@ -46,7 +46,7 @@ public function __construct( * * @throws InvalidArgumentException When the output tree, the totals or the report path refuse the build * @throws JsonException When the report cannot be encoded - * @throws MissingCname When the site address file does not hold the configured hostname + * @throws MissingCnameException When the site address file does not hold the configured hostname * @throws RuntimeException When the output tree or the report cannot be written * @throws TemplateExceptionInterface When a page cannot be rendered */ diff --git a/src/Config/Section.php b/src/Config/Section.php index 82d418a..82ec427 100644 --- a/src/Config/Section.php +++ b/src/Config/Section.php @@ -14,6 +14,8 @@ namespace CommonDoc\Aggregate\Config; +use CommonDoc\Aggregate\Exception\InvalidSiteConfigException; + use function array_key_exists; use function array_keys; use function array_map; @@ -50,26 +52,26 @@ public function keys(): array } /** - * @throws InvalidSiteConfig When the key is absent or does not hold an object + * @throws InvalidSiteConfigException When the key is absent or does not hold an object */ public function object(string $key): self { if (! array_key_exists($key, $this->members)) { - throw InvalidSiteConfig::at($this->pathFor($key), 'is required.'); + throw InvalidSiteConfigException::at($this->pathFor($key), 'is required.'); } /** @var mixed $value */ $value = $this->members[$key]; if (! is_array($value)) { - throw InvalidSiteConfig::at($this->pathFor($key), 'must be an object.'); + throw InvalidSiteConfigException::at($this->pathFor($key), 'must be an object.'); } return new self($value, $this->pathFor($key)); } /** - * @throws InvalidSiteConfig When the key is present but does not hold an object + * @throws InvalidSiteConfigException When the key is present but does not hold an object */ public function optionalObject(string $key): ?self { @@ -79,7 +81,7 @@ public function optionalObject(string $key): ?self /** * @return non-empty-string|null * - * @throws InvalidSiteConfig When the key is present but does not hold a non-empty string + * @throws InvalidSiteConfigException When the key is present but does not hold a non-empty string */ public function optionalString(string $key): ?string { @@ -97,7 +99,7 @@ public function pathFor(string $key): string /** * @param list $allowed * - * @throws InvalidSiteConfig When the section carries a key the schema does not declare + * @throws InvalidSiteConfigException When the section carries a key the schema does not declare */ public function rejectUnknownKeys(array $allowed): void { @@ -106,26 +108,26 @@ public function rejectUnknownKeys(array $allowed): void continue; } - throw InvalidSiteConfig::at($this->pathFor((string) $key), 'is not a known key.'); + throw InvalidSiteConfigException::at($this->pathFor((string) $key), 'is not a known key.'); } } /** * @return non-empty-string * - * @throws InvalidSiteConfig When the key is absent or does not hold a non-empty string + * @throws InvalidSiteConfigException When the key is absent or does not hold a non-empty string */ public function string(string $key): string { if (! array_key_exists($key, $this->members)) { - throw InvalidSiteConfig::at($this->pathFor($key), 'is required.'); + throw InvalidSiteConfigException::at($this->pathFor($key), 'is required.'); } /** @var mixed $value */ $value = $this->members[$key]; if (! is_string($value) || '' === $value) { - throw InvalidSiteConfig::at($this->pathFor($key), 'must be a non-empty string.'); + throw InvalidSiteConfigException::at($this->pathFor($key), 'must be a non-empty string.'); } return $value; diff --git a/src/Config/SiteConfigReader.php b/src/Config/SiteConfigReader.php index 492577c..fef1e20 100644 --- a/src/Config/SiteConfigReader.php +++ b/src/Config/SiteConfigReader.php @@ -14,6 +14,7 @@ namespace CommonDoc\Aggregate\Config; +use CommonDoc\Aggregate\Exception\InvalidSiteConfigException; use CommonDoc\Aggregate\Version\Strategy; use JsonException; @@ -48,7 +49,7 @@ final class SiteConfigReader private const string CACHE_DIRECTORY_DEFAULT = '.cache/multi-repo'; /** - * @throws InvalidSiteConfig When the file cannot be read or does not satisfy the schema + * @throws InvalidSiteConfigException When the file cannot be read or does not satisfy the schema */ public function read(string $path): SiteConfig { @@ -96,21 +97,21 @@ public function read(string $path): SiteConfig /** * @return array * - * @throws InvalidSiteConfig When the file cannot be read or does not hold JSON + * @throws InvalidSiteConfigException When the file cannot be read or does not hold JSON */ private function decode(string $path): array { $contents = is_readable($path) ? file_get_contents($path) : false; if (false === $contents) { - throw InvalidSiteConfig::at('site.json', sprintf('"%s" cannot be read.', $path)); + throw InvalidSiteConfigException::at('site.json', sprintf('"%s" cannot be read.', $path)); } try { /** @var mixed $decoded */ $decoded = json_decode($contents, associative: true, depth: 512, flags: JSON_THROW_ON_ERROR); } catch (JsonException $exception) { - throw InvalidSiteConfig::at('site.json', sprintf( + throw InvalidSiteConfigException::at('site.json', sprintf( '"%s" is not valid JSON: %s', $path, $exception->getMessage(), @@ -118,7 +119,7 @@ private function decode(string $path): array } if (! is_array($decoded)) { - throw InvalidSiteConfig::at('site.json', 'the file does not hold a JSON object.'); + throw InvalidSiteConfigException::at('site.json', 'the file does not hold a JSON object.'); } return $decoded; @@ -129,12 +130,12 @@ private function decode(string $path): array * * @return non-empty-string * - * @throws InvalidSiteConfig When the value is not a bare host name + * @throws InvalidSiteConfigException When the value is not a bare host name */ private function hostname(string $configured): string { if (preg_match(self::HOSTNAME_PATTERN, $configured) !== 1) { - throw InvalidSiteConfig::at( + throw InvalidSiteConfigException::at( 'site.hostname', sprintf('"%s" is not a bare host name without a scheme or a slash.', $configured), ); @@ -153,7 +154,7 @@ private function resolved(string $path, string $base): string } /** - * @throws InvalidSiteConfig When the configured strategy is not a member + * @throws InvalidSiteConfigException When the configured strategy is not a member */ private function strategy(Section $root): Strategy { @@ -173,7 +174,7 @@ private function strategy(Section $root): Strategy /** * @return array * - * @throws InvalidSiteConfig When a mapped template is not a readable file + * @throws InvalidSiteConfigException When a mapped template is not a readable file */ private function templateMap(Section $root, string $base): array { @@ -198,7 +199,7 @@ private function templateMap(Section $root, string $base): array $resolved = $this->resolved($templatePath, $base); if (! is_file($resolved) || ! is_readable($resolved)) { - throw InvalidSiteConfig::at( + throw InvalidSiteConfigException::at( $map->pathFor($name), sprintf('"%s" is not a readable file.', $resolved), ); @@ -215,12 +216,12 @@ private function templateMap(Section $root, string $base): array * * @return non-empty-string * - * @throws InvalidSiteConfig When the value is not an environment variable name + * @throws InvalidSiteConfigException When the value is not an environment variable name */ private function tokenVariable(string $configured): string { if (preg_match(self::TOKEN_ENV_VAR_PATTERN, $configured) !== 1) { - throw InvalidSiteConfig::at( + throw InvalidSiteConfigException::at( 'organization.tokenEnvVar', sprintf('"%s" is not an environment variable name.', $configured), ); diff --git a/src/Console/BuildCommand.php b/src/Console/BuildCommand.php index dc74c5e..16bbc36 100644 --- a/src/Console/BuildCommand.php +++ b/src/Console/BuildCommand.php @@ -16,9 +16,9 @@ use CommonDoc\Aggregate\Build\BuildReport; use CommonDoc\Aggregate\Build\SiteBuildFactoryInterface; -use CommonDoc\Aggregate\Config\InvalidSiteConfig; use CommonDoc\Aggregate\Config\SiteConfigReader; -use CommonDoc\Aggregate\Output\MissingCname; +use CommonDoc\Aggregate\Exception\InvalidSiteConfigException; +use CommonDoc\Aggregate\Exception\MissingCnameException; use CommonDoc\Aggregate\Report\ReportFile; use CommonDoc\Aggregate\Report\ReportFileFactoryInterface; use InvalidArgumentException; @@ -90,7 +90,7 @@ protected function configure(): void * @throws ExceptionInterface When an option cannot be read * @throws InvalidArgumentException When the report path or the report itself is refused * @throws JsonException When the report cannot be encoded as JSON - * @throws MissingCname When the site address file does not hold the configured hostname + * @throws MissingCnameException When the site address file does not hold the configured hostname * @throws RuntimeException When the output tree or the report cannot be written * @throws AlreadyInitializedException When the markdown environment has already been configured * @throws TemplateExceptionInterface When a page cannot be rendered @@ -106,7 +106,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int try { $config = $this->reader->read($path); - } catch (InvalidSiteConfig $invalid) { + } catch (InvalidSiteConfigException $invalid) { $this->errorsOf($output)->writeln(sprintf('%s', $invalid->getMessage())); return self::EXIT_BLOCKED; diff --git a/src/Source/GitFailure.php b/src/Exception/GitFailureException.php similarity index 95% rename from src/Source/GitFailure.php rename to src/Exception/GitFailureException.php index b0ef1aa..e7a18c5 100644 --- a/src/Source/GitFailure.php +++ b/src/Exception/GitFailureException.php @@ -12,7 +12,7 @@ * file that was distributed with this source code. */ -namespace CommonDoc\Aggregate\Source; +namespace CommonDoc\Aggregate\Exception; use RuntimeException; @@ -28,7 +28,7 @@ * where a credential would travel. Diagnostics are trimmed and truncated so a remote that echoes a * long page cannot turn a failure into an unreadable report. */ -final class GitFailure extends RuntimeException +final class GitFailureException extends RuntimeException { private const int DIAGNOSTIC_LIMIT = 400; diff --git a/src/Config/InvalidSiteConfig.php b/src/Exception/InvalidSiteConfigException.php similarity index 92% rename from src/Config/InvalidSiteConfig.php rename to src/Exception/InvalidSiteConfigException.php index 2f27991..0a44ef4 100644 --- a/src/Config/InvalidSiteConfig.php +++ b/src/Exception/InvalidSiteConfigException.php @@ -12,7 +12,7 @@ * file that was distributed with this source code. */ -namespace CommonDoc\Aggregate\Config; +namespace CommonDoc\Aggregate\Exception; use CommonDoc\Aggregate\Build\ReasonCode; use RuntimeException; @@ -27,7 +27,7 @@ * has to deduce the vocabulary from the message. Configuration is read before anything is rendered, * so this always exits blocked and never produces a report. */ -final class InvalidSiteConfig extends RuntimeException +final class InvalidSiteConfigException extends RuntimeException { private function __construct( public readonly string $key, diff --git a/src/Output/MissingCname.php b/src/Exception/MissingCnameException.php similarity index 91% rename from src/Output/MissingCname.php rename to src/Exception/MissingCnameException.php index 36f26f6..1b9255b 100644 --- a/src/Output/MissingCname.php +++ b/src/Exception/MissingCnameException.php @@ -12,9 +12,10 @@ * file that was distributed with this source code. */ -namespace CommonDoc\Aggregate\Output; +namespace CommonDoc\Aggregate\Exception; use CommonDoc\Aggregate\Build\ReasonCode; +use CommonDoc\Aggregate\Output\CnameFile; use RuntimeException; use function sprintf; @@ -27,7 +28,7 @@ * travels with the exception so the report and the process exit code cannot disagree about why the * build stopped. */ -final class MissingCname extends RuntimeException +final class MissingCnameException extends RuntimeException { private function __construct( public readonly ReasonCode $reasonCode, diff --git a/src/Source/MissingDocDirectory.php b/src/Exception/MissingDocDirectoryException.php similarity index 91% rename from src/Source/MissingDocDirectory.php rename to src/Exception/MissingDocDirectoryException.php index 85c28f2..7c58f08 100644 --- a/src/Source/MissingDocDirectory.php +++ b/src/Exception/MissingDocDirectoryException.php @@ -12,7 +12,7 @@ * file that was distributed with this source code. */ -namespace CommonDoc\Aggregate\Source; +namespace CommonDoc\Aggregate\Exception; use CommonDoc\Aggregate\Build\ReasonCode; use CommonDoc\Aggregate\Discovery\Project; @@ -26,7 +26,7 @@ * This is a defect in the project rather than in the build, so it carries its own reason code: the * repository custom property names a directory that the resolved ref does not have. */ -final class MissingDocDirectory extends RuntimeException +final class MissingDocDirectoryException extends RuntimeException { private function __construct( public readonly ReasonCode $reasonCode, diff --git a/src/Source/SourceUnavailable.php b/src/Exception/SourceUnavailableException.php similarity index 92% rename from src/Source/SourceUnavailable.php rename to src/Exception/SourceUnavailableException.php index de91b6d..6beac0e 100644 --- a/src/Source/SourceUnavailable.php +++ b/src/Exception/SourceUnavailableException.php @@ -12,7 +12,7 @@ * file that was distributed with this source code. */ -namespace CommonDoc\Aggregate\Source; +namespace CommonDoc\Aggregate\Exception; use CommonDoc\Aggregate\Build\ReasonCode; use CommonDoc\Aggregate\Discovery\Project; @@ -27,7 +27,7 @@ * The reason code travels with the exception so the report and the process exit code cannot disagree * about why the project was skipped. */ -final class SourceUnavailable extends RuntimeException +final class SourceUnavailableException extends RuntimeException { private function __construct( public readonly ReasonCode $reasonCode, diff --git a/src/Render/UnaddressableDocument.php b/src/Exception/UnaddressableDocumentException.php similarity index 93% rename from src/Render/UnaddressableDocument.php rename to src/Exception/UnaddressableDocumentException.php index 0411975..321d6c1 100644 --- a/src/Render/UnaddressableDocument.php +++ b/src/Exception/UnaddressableDocumentException.php @@ -12,7 +12,7 @@ * file that was distributed with this source code. */ -namespace CommonDoc\Aggregate\Render; +namespace CommonDoc\Aggregate\Exception; use CommonDoc\Aggregate\Build\ReasonCode; use CommonDoc\Aggregate\Version\Target; @@ -31,7 +31,7 @@ * The reason code is carried rather than assumed by the caller, so the report cannot disagree with * what happened. */ -final class UnaddressableDocument extends RuntimeException +final class UnaddressableDocumentException extends RuntimeException { private function __construct( public readonly ReasonCode $reasonCode, diff --git a/src/Output/CnameFile.php b/src/Output/CnameFile.php index 2066543..b533af9 100644 --- a/src/Output/CnameFile.php +++ b/src/Output/CnameFile.php @@ -14,6 +14,7 @@ namespace CommonDoc\Aggregate\Output; +use CommonDoc\Aggregate\Exception\MissingCnameException; use InvalidArgumentException; use RuntimeException; @@ -87,12 +88,12 @@ public function hostname(): string /** * @throws InvalidArgumentException When the tree refuses the file name * @throws RuntimeException When the file cannot be read - * @throws MissingCname When the file is absent or does not hold the configured hostname + * @throws MissingCnameException When the file is absent or does not hold the configured hostname */ public function verify(): void { if (! $this->tree->exists(relativePath: self::NAME)) { - throw MissingCname::absent(); + throw MissingCnameException::absent(); } $actual = $this->tree->read(relativePath: self::NAME); @@ -103,7 +104,7 @@ public function verify(): void characters: self::TRAILING, ) !== $this->hostname ) { - throw MissingCname::mismatched( + throw MissingCnameException::mismatched( expected: $this->hostname, actual : $actual, ); diff --git a/src/Render/TargetRenderer.php b/src/Render/TargetRenderer.php index 93df68b..ceb2835 100644 --- a/src/Render/TargetRenderer.php +++ b/src/Render/TargetRenderer.php @@ -17,9 +17,10 @@ use CommonDoc\Aggregate\Build\PageResult; use CommonDoc\Aggregate\Build\PageStatus; use CommonDoc\Aggregate\Build\ReasonCode; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; +use CommonDoc\Aggregate\Exception\UnaddressableDocumentException; use CommonDoc\Aggregate\Output\OutputTree; use CommonDoc\Aggregate\Source\SourceInterface; -use CommonDoc\Aggregate\Source\SourceUnavailable; use CommonDoc\Aggregate\Version\Target; use CommonDoc\View\Page; use CommonDoc\View\PageContext; @@ -165,7 +166,7 @@ public function render(Target $target, array $documents): array foreach ($addresses as $documentPath => $address) { $prepared[] = [$documentPath, $address, $this->source->contents($target, $documentPath)]; } - } catch (SourceUnavailable|UnaddressableDocument) { + } catch (SourceUnavailableException|UnaddressableDocumentException) { return self::failed($documents); } @@ -195,7 +196,7 @@ public function render(Target $target, array $documents): array * * @return array * - * @throws UnaddressableDocument When one document cannot name a page + * @throws UnaddressableDocumentException When one document cannot name a page */ private function addressesOf(Target $target, array $documents): array { @@ -208,7 +209,7 @@ private function addressesOf(Target $target, array $documents): array documentPath: $documentPath, ); } catch (InvalidArgumentException) { - throw UnaddressableDocument::at($target, $documentPath); + throw UnaddressableDocumentException::at($target, $documentPath); } } diff --git a/src/Source/GitCandidates.php b/src/Source/GitCandidates.php index 89a9a6a..cf40cf5 100644 --- a/src/Source/GitCandidates.php +++ b/src/Source/GitCandidates.php @@ -15,6 +15,8 @@ namespace CommonDoc\Aggregate\Source; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Version\Strategy; use function sprintf; @@ -37,8 +39,8 @@ public function __construct( /** * @return list * - * @throws SourceUnavailable When the candidates cannot be listed - * @throws MissingDocDirectory When the documentation directory is absent at the default branch + * @throws SourceUnavailableException When the candidates cannot be listed + * @throws MissingDocDirectoryException When the documentation directory is absent at the default branch */ public function names(Project $project): array { @@ -50,8 +52,8 @@ public function names(Project $project): array /** * @return list * - * @throws SourceUnavailable When the default branch cannot be listed - * @throws MissingDocDirectory When the documentation directory is absent at the default branch + * @throws SourceUnavailableException When the default branch cannot be listed + * @throws MissingDocDirectoryException When the documentation directory is absent at the default branch */ private function directoryNames(Project $project): array { @@ -74,7 +76,7 @@ private function directoryNames(Project $project): array $names = TreeOutput::directories(TreeOutput::paths($listing, $root)); if ([] === $names) { - throw MissingDocDirectory::at($project, $ref); + throw MissingDocDirectoryException::at($project, $ref); } return $names; @@ -83,7 +85,7 @@ private function directoryNames(Project $project): array /** * @return list * - * @throws SourceUnavailable When the remote cannot be listed + * @throws SourceUnavailableException When the remote cannot be listed */ private function referenceNames(Project $project): array { diff --git a/src/Source/GitCheckout.php b/src/Source/GitCheckout.php index 13afbd7..e795077 100644 --- a/src/Source/GitCheckout.php +++ b/src/Source/GitCheckout.php @@ -15,6 +15,8 @@ namespace CommonDoc\Aggregate\Source; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\GitFailureException; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use InvalidArgumentException; use function array_key_exists; @@ -65,7 +67,7 @@ public function __construct( } /** - * @throws SourceUnavailable When the checkout cannot be prepared + * @throws SourceUnavailableException When the checkout cannot be prepared */ public function directory(Project $project): string { @@ -105,7 +107,7 @@ public function directory(Project $project): string * * @param list $arguments * - * @throws SourceUnavailable When git cannot be started or exits with a non-zero code + * @throws SourceUnavailableException When git cannot be started or exits with a non-zero code */ public function run(Project $project, string $directory, array $arguments): string { @@ -114,8 +116,8 @@ public function run(Project $project, string $directory, array $arguments): stri arguments : $arguments, workingDirectory: $directory, ); - } catch (GitFailure $failure) { - throw SourceUnavailable::for( + } catch (GitFailureException $failure) { + throw SourceUnavailableException::for( project : $project, reason : $failure->getMessage(), previous: $failure, @@ -140,7 +142,7 @@ public function urlOf(Project $project): string } /** - * @throws SourceUnavailable When the cache directory cannot be created + * @throws SourceUnavailableException When the cache directory cannot be created */ private function create(Project $project, string $directory): void { @@ -153,7 +155,7 @@ private function create(Project $project, string $directory): void ) && ! is_dir($directory) ) { - throw SourceUnavailable::for( + throw SourceUnavailableException::for( project: $project, reason: sprintf('The cache directory "%s" could not be created.', $directory), ); @@ -177,7 +179,7 @@ private function create(Project $project, string $directory): void } /** - * @throws SourceUnavailable When the remote cannot be repointed + * @throws SourceUnavailableException When the remote cannot be repointed */ private function update(Project $project, string $directory): void { diff --git a/src/Source/GitCommand.php b/src/Source/GitCommand.php index 06f05c9..c4d301e 100644 --- a/src/Source/GitCommand.php +++ b/src/Source/GitCommand.php @@ -14,6 +14,7 @@ namespace CommonDoc\Aggregate\Source; +use CommonDoc\Aggregate\Exception\GitFailureException; use Override; use Symfony\Component\Process\Exception\ExceptionInterface; use Symfony\Component\Process\Process; @@ -44,7 +45,7 @@ public function __construct( * @param string $workingDirectory A directory the caller has resolved or created * @param array $environment Added to the environment of this invocation only * - * @throws GitFailure When git cannot be started or exits with a non-zero code + * @throws GitFailureException When git cannot be started or exits with a non-zero code */ #[Override] public function run(array $arguments, string $workingDirectory, array $environment = []): string @@ -60,7 +61,7 @@ public function run(array $arguments, string $workingDirectory, array $environme $process->run(); if (! $process->isSuccessful()) { - throw GitFailure::failed( + throw GitFailureException::failed( arguments : $arguments, exitCode : $process->getExitCode(), diagnostic: $process->getErrorOutput(), @@ -69,7 +70,7 @@ public function run(array $arguments, string $workingDirectory, array $environme return $process->getOutput(); } catch (ExceptionInterface $exception) { - throw GitFailure::didNotRun( + throw GitFailureException::didNotRun( arguments : $arguments, diagnostic: $exception->getMessage(), ); diff --git a/src/Source/GitDocuments.php b/src/Source/GitDocuments.php index 84d8fac..7f6c824 100644 --- a/src/Source/GitDocuments.php +++ b/src/Source/GitDocuments.php @@ -14,6 +14,8 @@ namespace CommonDoc\Aggregate\Source; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Version\Strategy; use CommonDoc\Aggregate\Version\Target; @@ -36,7 +38,7 @@ public function __construct( /** * @param non-empty-string $documentPath A path previously returned by {@see self::paths()} * - * @throws SourceUnavailable When the document cannot be read + * @throws SourceUnavailableException When the document cannot be read */ public function contents(Target $target, string $documentPath): string { @@ -64,8 +66,8 @@ public function contents(Target $target, string $documentPath): string /** * @return list Paths relative to the target's source root * - * @throws SourceUnavailable When the tree cannot be listed - * @throws MissingDocDirectory When the source root is absent at the ref + * @throws SourceUnavailableException When the tree cannot be listed + * @throws MissingDocDirectoryException When the source root is absent at the ref */ public function paths(Target $target): array { @@ -95,7 +97,7 @@ public function paths(Target $target): array $paths = TreeOutput::documents(TreeOutput::paths($listing, $root)); if ([] === $paths) { - throw MissingDocDirectory::at($project, $ref); + throw MissingDocDirectoryException::at($project, $ref); } return $paths; diff --git a/src/Source/GitReferences.php b/src/Source/GitReferences.php index af33250..4787ee0 100644 --- a/src/Source/GitReferences.php +++ b/src/Source/GitReferences.php @@ -15,6 +15,7 @@ namespace CommonDoc\Aggregate\Source; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Version\Strategy; use CommonDoc\Aggregate\Version\Target; @@ -48,7 +49,7 @@ public function __construct( /** * @return non-empty-string * - * @throws SourceUnavailable When the default branch cannot be determined + * @throws SourceUnavailableException When the default branch cannot be determined */ public function defaultRef(Project $project): string { @@ -84,7 +85,7 @@ public function defaultRef(Project $project): string return $this->defaults[$project->sitePath] = sprintf('%s%s', self::REMOTE, $branch); } - throw SourceUnavailable::for( + throw SourceUnavailableException::for( project: $project, reason: sprintf('The default branch of "%s" could not be determined.', $project->sitePath), ); @@ -93,7 +94,7 @@ public function defaultRef(Project $project): string /** * @return non-empty-string * - * @throws SourceUnavailable When a tree corpus needs the default branch and it is unavailable + * @throws SourceUnavailableException When a tree corpus needs the default branch and it is unavailable */ public function refFor(Target $target, Strategy $strategy): string { diff --git a/src/Source/GitRunnerInterface.php b/src/Source/GitRunnerInterface.php index d1eb6c8..d0b5404 100644 --- a/src/Source/GitRunnerInterface.php +++ b/src/Source/GitRunnerInterface.php @@ -14,6 +14,8 @@ namespace CommonDoc\Aggregate\Source; +use CommonDoc\Aggregate\Exception\GitFailureException; + /** * The process seam every git read passes through. * @@ -31,7 +33,7 @@ interface GitRunnerInterface * @param string $workingDirectory A directory the caller has resolved or created * @param array $environment Added to the environment of this invocation only * - * @throws GitFailure When the command cannot be run or exits with a non-zero code + * @throws GitFailureException When the command cannot be run or exits with a non-zero code */ public function run(array $arguments, string $workingDirectory, array $environment = []): string; } diff --git a/src/Source/GitSource.php b/src/Source/GitSource.php index 411469b..622406f 100644 --- a/src/Source/GitSource.php +++ b/src/Source/GitSource.php @@ -15,6 +15,8 @@ namespace CommonDoc\Aggregate\Source; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Version\Target; use Override; @@ -35,8 +37,8 @@ public function __construct( /** * @return list * - * @throws SourceUnavailable When the candidates cannot be listed - * @throws MissingDocDirectory When the documentation directory is absent at the default branch + * @throws SourceUnavailableException When the candidates cannot be listed + * @throws MissingDocDirectoryException When the documentation directory is absent at the default branch */ #[Override] public function candidates(Project $project): array @@ -45,7 +47,7 @@ public function candidates(Project $project): array } /** - * @throws SourceUnavailable When the document cannot be read + * @throws SourceUnavailableException When the document cannot be read */ #[Override] public function contents(Target $target, string $documentPath): string @@ -59,8 +61,8 @@ public function contents(Target $target, string $documentPath): string /** * @return list * - * @throws SourceUnavailable When the sources cannot be read - * @throws MissingDocDirectory When the declared documentation directory is absent at the ref + * @throws SourceUnavailableException When the sources cannot be read + * @throws MissingDocDirectoryException When the declared documentation directory is absent at the ref */ #[Override] public function documents(Target $target): array diff --git a/src/Source/SourceInterface.php b/src/Source/SourceInterface.php index 524c17f..f6169b2 100644 --- a/src/Source/SourceInterface.php +++ b/src/Source/SourceInterface.php @@ -15,6 +15,8 @@ namespace CommonDoc\Aggregate\Source; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Version\Target; /** @@ -34,7 +36,7 @@ interface SourceInterface * * @return list Names without a reference prefix, unordered and possibly duplicated * - * @throws SourceUnavailable When the candidates cannot be listed + * @throws SourceUnavailableException When the candidates cannot be listed */ public function candidates(Project $project): array; @@ -43,7 +45,7 @@ public function candidates(Project $project): array; * * @param non-empty-string $documentPath A path previously returned by {@see self::documents()} * - * @throws SourceUnavailable When the document cannot be read + * @throws SourceUnavailableException When the document cannot be read */ public function contents(Target $target, string $documentPath): string; @@ -56,8 +58,8 @@ public function contents(Target $target, string $documentPath): string; * * @return list * - * @throws SourceUnavailable When the sources cannot be read - * @throws MissingDocDirectory When the declared documentation directory is absent at the ref + * @throws SourceUnavailableException When the sources cannot be read + * @throws MissingDocDirectoryException When the declared documentation directory is absent at the ref */ public function documents(Target $target): array; } diff --git a/src/Version/Strategy.php b/src/Version/Strategy.php index 7940dfb..0e598b1 100644 --- a/src/Version/Strategy.php +++ b/src/Version/Strategy.php @@ -14,7 +14,7 @@ namespace CommonDoc\Aggregate\Version; -use CommonDoc\Aggregate\Config\InvalidSiteConfig; +use CommonDoc\Aggregate\Exception\InvalidSiteConfigException; use function sprintf; @@ -38,12 +38,12 @@ public static function default(): self } /** - * @throws InvalidSiteConfig When the configured value names no member + * @throws InvalidSiteConfigException When the configured value names no member */ public static function fromConfig(string $configured): self { return ( - self::tryFrom($configured) ?? throw InvalidSiteConfig::at( + self::tryFrom($configured) ?? throw InvalidSiteConfigException::at( 'versions.strategy', sprintf('"%s" is not one of "ref" or "tree".', $configured), ) diff --git a/test/unit/Build/SiteBuildTest.php b/test/unit/Build/SiteBuildTest.php index 4159b78..12c6eba 100644 --- a/test/unit/Build/SiteBuildTest.php +++ b/test/unit/Build/SiteBuildTest.php @@ -21,9 +21,9 @@ use CommonDoc\Aggregate\Config\SiteConfig; use CommonDoc\Aggregate\Discovery\Project; use CommonDoc\Aggregate\Discovery\ProjectSourceInterface; -use CommonDoc\Aggregate\Source\MissingDocDirectory; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Source\SourceInterface; -use CommonDoc\Aggregate\Source\SourceUnavailable; use CommonDoc\Aggregate\Version\Strategy; use CommonDoc\Aggregate\Version\StrategyFactory; use CommonDoc\Aggregate\Version\Target; @@ -379,7 +379,7 @@ private function source(array $candidates, array $unavailable, array $missing): ->willReturnCallback( static function (Project $project) use ($candidates, $unavailable): array { if (in_array($project->sitePath, $unavailable, strict: true)) { - throw SourceUnavailable::for($project, 'the repository is unreachable'); + throw SourceUnavailableException::for($project, 'the repository is unreachable'); } return $candidates[$project->sitePath] ?? []; @@ -391,11 +391,11 @@ static function (Project $project) use ($candidates, $unavailable): array { ->willReturnCallback( static function (Target $target) use ($unavailable, $missing): array { if (in_array($target->project->sitePath, $unavailable, strict: true)) { - throw SourceUnavailable::for($target->project, 'the repository is unreachable'); + throw SourceUnavailableException::for($target->project, 'the repository is unreachable'); } if (in_array($target->version, $missing, strict: true)) { - throw MissingDocDirectory::at($target->project, $target->version); + throw MissingDocDirectoryException::at($target->project, $target->version); } return ['index.md']; diff --git a/test/unit/BuildCommandTest.php b/test/unit/BuildCommandTest.php index 945c230..9f075a1 100644 --- a/test/unit/BuildCommandTest.php +++ b/test/unit/BuildCommandTest.php @@ -16,12 +16,12 @@ use CommonDoc\Aggregate\Console\BuildCommand; use CommonDoc\Aggregate\Discovery\Project; use CommonDoc\Aggregate\Discovery\ProjectSourceInterface; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Render\SiteRendererFactoryInterface; use CommonDoc\Aggregate\Report\ReportFileFactory; -use CommonDoc\Aggregate\Source\MissingDocDirectory; use CommonDoc\Aggregate\Source\SourceFactoryInterface; use CommonDoc\Aggregate\Source\SourceInterface; -use CommonDoc\Aggregate\Source\SourceUnavailable; use CommonDoc\Aggregate\Version\StrategyFactory; use CommonDoc\Aggregate\Version\Target; use CommonDocTest\Aggregate\Support\SiteRenderer; @@ -227,7 +227,7 @@ private function sources(array $candidates, array $unavailable, array $missing): ->willReturnCallback( static function (Project $project) use ($candidates, $unavailable): array { if (in_array($project->sitePath, $unavailable, strict: true)) { - throw SourceUnavailable::for($project, 'the repository is unreachable'); + throw SourceUnavailableException::for($project, 'the repository is unreachable'); } return $candidates[$project->sitePath] ?? []; @@ -239,11 +239,11 @@ static function (Project $project) use ($candidates, $unavailable): array { ->willReturnCallback( static function (Target $target) use ($unavailable, $missing): array { if (in_array($target->project->sitePath, $unavailable, strict: true)) { - throw SourceUnavailable::for($target->project, 'the repository is unreachable'); + throw SourceUnavailableException::for($target->project, 'the repository is unreachable'); } if (in_array($target->version, $missing, strict: true)) { - throw MissingDocDirectory::at($target->project, $target->version); + throw MissingDocDirectoryException::at($target->project, $target->version); } return ['index.md']; diff --git a/test/unit/Config/SectionTest.php b/test/unit/Config/SectionTest.php index f39020d..06c05a5 100644 --- a/test/unit/Config/SectionTest.php +++ b/test/unit/Config/SectionTest.php @@ -15,8 +15,8 @@ namespace CommonDocTest\Aggregate\Config; use CommonDoc\Aggregate\Build\ReasonCode; -use CommonDoc\Aggregate\Config\InvalidSiteConfig; use CommonDoc\Aggregate\Config\Section; +use CommonDoc\Aggregate\Exception\InvalidSiteConfigException; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\CoversMethod; use PHPUnit\Framework\Attributes\Test; @@ -160,7 +160,7 @@ private function assertRejected(string $key, callable $action): void { try { $action(); - } catch (InvalidSiteConfig $exception) { + } catch (InvalidSiteConfigException $exception) { static::assertSame($key, $exception->key); static::assertSame(ReasonCode::InvalidSiteConfig, $exception->reasonCode); diff --git a/test/unit/Config/SiteConfigReaderTest.php b/test/unit/Config/SiteConfigReaderTest.php index 0f0c8ca..dfe4115 100644 --- a/test/unit/Config/SiteConfigReaderTest.php +++ b/test/unit/Config/SiteConfigReaderTest.php @@ -15,9 +15,9 @@ namespace CommonDocTest\Aggregate\Config; use CommonDoc\Aggregate\Build\ReasonCode; -use CommonDoc\Aggregate\Config\InvalidSiteConfig; use CommonDoc\Aggregate\Config\SiteConfig; use CommonDoc\Aggregate\Config\SiteConfigReader; +use CommonDoc\Aggregate\Exception\InvalidSiteConfigException; use CommonDoc\Aggregate\Version\Strategy; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\CoversMethod; @@ -318,7 +318,7 @@ private function assertRejected(string $key, callable $action): void { try { $action(); - } catch (InvalidSiteConfig $exception) { + } catch (InvalidSiteConfigException $exception) { static::assertSame($key, $exception->key); static::assertSame(ReasonCode::InvalidSiteConfig, $exception->reasonCode); diff --git a/test/unit/Source/GitFailureTest.php b/test/unit/Exception/GitFailureExceptionTest.php similarity index 82% rename from test/unit/Source/GitFailureTest.php rename to test/unit/Exception/GitFailureExceptionTest.php index 4271683..89a82fc 100644 --- a/test/unit/Source/GitFailureTest.php +++ b/test/unit/Exception/GitFailureExceptionTest.php @@ -12,9 +12,9 @@ * file that was distributed with this source code. */ -namespace CommonDocTest\Aggregate\Source; +namespace CommonDocTest\Aggregate\Exception; -use CommonDoc\Aggregate\Source\GitFailure; +use CommonDoc\Aggregate\Exception\GitFailureException; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\CoversMethod; use PHPUnit\Framework\Attributes\Test; @@ -24,15 +24,15 @@ use function str_repeat; use function strlen; -#[CoversClass(GitFailure::class)] -#[CoversMethod(GitFailure::class, 'didNotRun')] -#[CoversMethod(GitFailure::class, 'failed')] -final class GitFailureTest extends TestCase +#[CoversClass(GitFailureException::class)] +#[CoversMethod(GitFailureException::class, 'didNotRun')] +#[CoversMethod(GitFailureException::class, 'failed')] +final class GitFailureExceptionTest extends TestCase { #[Test] public function namesTheArgumentsAndTheExitCodeOfAFailedCommand(): void { - $failure = GitFailure::failed( + $failure = GitFailureException::failed( arguments : ['ls-remote', '--heads', 'https://example.test/repository.git'], exitCode : 128, diagnostic: "fatal: repository not found\n", @@ -49,7 +49,7 @@ public function namesTheArgumentsAndTheExitCodeOfAFailedCommand(): void #[Test] public function reportsACommandThatNeverRanWithoutAnExitCode(): void { - $failure = GitFailure::didNotRun( + $failure = GitFailureException::didNotRun( arguments : ['init'], diagnostic: 'the binary is absent', ); @@ -61,7 +61,7 @@ public function reportsACommandThatNeverRanWithoutAnExitCode(): void #[Test] public function saysSoWhenTheCommandReportedNoDiagnostic(): void { - $failure = GitFailure::failed( + $failure = GitFailureException::failed( arguments : ['fetch'], exitCode : 1, diagnostic: " \n", @@ -73,7 +73,7 @@ public function saysSoWhenTheCommandReportedNoDiagnostic(): void #[Test] public function truncatesADiagnosticThatWouldSwampTheReport(): void { - $failure = GitFailure::failed( + $failure = GitFailureException::failed( arguments : ['fetch'], exitCode : 1, diagnostic: str_repeat( diff --git a/test/unit/Config/InvalidSiteConfigTest.php b/test/unit/Exception/InvalidSiteConfigExceptionTest.php similarity index 78% rename from test/unit/Config/InvalidSiteConfigTest.php rename to test/unit/Exception/InvalidSiteConfigExceptionTest.php index ef24661..729ea3f 100644 --- a/test/unit/Config/InvalidSiteConfigTest.php +++ b/test/unit/Exception/InvalidSiteConfigExceptionTest.php @@ -12,23 +12,23 @@ * file that was distributed with this source code. */ -namespace CommonDocTest\Aggregate\Config; +namespace CommonDocTest\Aggregate\Exception; use CommonDoc\Aggregate\Build\ReasonCode; -use CommonDoc\Aggregate\Config\InvalidSiteConfig; +use CommonDoc\Aggregate\Exception\InvalidSiteConfigException; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\CoversMethod; use PHPUnit\Framework\Attributes\Test; use PHPUnit\Framework\TestCase; use RuntimeException; -#[CoversClass(InvalidSiteConfig::class)] -#[CoversMethod(InvalidSiteConfig::class, 'at')] -final class InvalidSiteConfigTest extends TestCase +#[CoversClass(InvalidSiteConfigException::class)] +#[CoversMethod(InvalidSiteConfigException::class, 'at')] +final class InvalidSiteConfigExceptionTest extends TestCase { - private static function config(): InvalidSiteConfig + private static function config(): InvalidSiteConfigException { - return InvalidSiteConfig::at( + return InvalidSiteConfigException::at( key : 'organization', reason: 'it must be a non-empty string.', ); diff --git a/test/unit/Source/MissingDocDirectoryTest.php b/test/unit/Exception/MissingDocDirectoryExceptionTest.php similarity index 79% rename from test/unit/Source/MissingDocDirectoryTest.php rename to test/unit/Exception/MissingDocDirectoryExceptionTest.php index 60e666f..b3a689c 100644 --- a/test/unit/Source/MissingDocDirectoryTest.php +++ b/test/unit/Exception/MissingDocDirectoryExceptionTest.php @@ -12,24 +12,24 @@ * file that was distributed with this source code. */ -namespace CommonDocTest\Aggregate\Source; +namespace CommonDocTest\Aggregate\Exception; use CommonDoc\Aggregate\Build\ReasonCode; use CommonDoc\Aggregate\Discovery\Project; -use CommonDoc\Aggregate\Source\MissingDocDirectory; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\CoversMethod; use PHPUnit\Framework\Attributes\Test; use PHPUnit\Framework\TestCase; -#[CoversClass(MissingDocDirectory::class)] -#[CoversMethod(MissingDocDirectory::class, 'at')] -final class MissingDocDirectoryTest extends TestCase +#[CoversClass(MissingDocDirectoryException::class)] +#[CoversMethod(MissingDocDirectoryException::class, 'at')] +final class MissingDocDirectoryExceptionTest extends TestCase { #[Test] public function namesTheDirectoryTheProjectAndTheRef(): void { - $failure = MissingDocDirectory::at( + $failure = MissingDocDirectoryException::at( project: new Project( name : 'aggregate-renderer', owner : 'common-doc', diff --git a/test/unit/Source/SourceUnavailableTest.php b/test/unit/Exception/SourceUnavailableExceptionTest.php similarity index 81% rename from test/unit/Source/SourceUnavailableTest.php rename to test/unit/Exception/SourceUnavailableExceptionTest.php index ff33140..33ce564 100644 --- a/test/unit/Source/SourceUnavailableTest.php +++ b/test/unit/Exception/SourceUnavailableExceptionTest.php @@ -12,26 +12,26 @@ * file that was distributed with this source code. */ -namespace CommonDocTest\Aggregate\Source; +namespace CommonDocTest\Aggregate\Exception; use CommonDoc\Aggregate\Build\ReasonCode; use CommonDoc\Aggregate\Discovery\Project; -use CommonDoc\Aggregate\Source\SourceUnavailable; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\CoversMethod; use PHPUnit\Framework\Attributes\Test; use PHPUnit\Framework\TestCase; use RuntimeException; -#[CoversClass(SourceUnavailable::class)] -#[CoversMethod(SourceUnavailable::class, 'for')] -final class SourceUnavailableTest extends TestCase +#[CoversClass(SourceUnavailableException::class)] +#[CoversMethod(SourceUnavailableException::class, 'for')] +final class SourceUnavailableExceptionTest extends TestCase { #[Test] public function carriesTheReasonCodeAndNamesTheProject(): void { $previous = new RuntimeException('the remote refused the connection'); - $failure = SourceUnavailable::for( + $failure = SourceUnavailableException::for( project : new Project( name : 'aggregate-renderer', owner : 'common-doc', diff --git a/test/unit/Output/CnameFileTest.php b/test/unit/Output/CnameFileTest.php index fe63aab..4437062 100644 --- a/test/unit/Output/CnameFileTest.php +++ b/test/unit/Output/CnameFileTest.php @@ -15,8 +15,8 @@ namespace CommonDocTest\Aggregate\Output; use CommonDoc\Aggregate\Build\ReasonCode; +use CommonDoc\Aggregate\Exception\MissingCnameException; use CommonDoc\Aggregate\Output\CnameFile; -use CommonDoc\Aggregate\Output\MissingCname; use CommonDoc\Aggregate\Output\OutputTree; use InvalidArgumentException; use PHPUnit\Framework\Attributes\CoversClass; @@ -37,7 +37,7 @@ use const DIRECTORY_SEPARATOR; #[CoversClass(CnameFile::class)] -#[CoversClass(MissingCname::class)] +#[CoversClass(MissingCnameException::class)] #[CoversMethod(CnameFile::class, '__construct')] #[CoversMethod(CnameFile::class, 'contents')] #[CoversMethod(CnameFile::class, 'hostname')] @@ -89,7 +89,7 @@ public function reportsAFileThatHoldsAnotherHostname(): void try { $this->cname(hostname: 'docs.example.org')->verify(); - } catch (MissingCname $missing) { + } catch (MissingCnameException $missing) { static::assertSame(ReasonCode::MissingCname, $missing->reasonCode); static::assertStringContainsString('other.example.org', $missing->getMessage()); @@ -106,7 +106,7 @@ public function reportsAnAbsentFileAsMissing(): void try { $this->cname(hostname: 'docs.example.org')->verify(); - } catch (MissingCname $missing) { + } catch (MissingCnameException $missing) { static::assertSame(ReasonCode::MissingCname, $missing->reasonCode); static::assertStringContainsString('is absent', $missing->getMessage()); diff --git a/test/unit/Render/TargetRendererTest.php b/test/unit/Render/TargetRendererTest.php index 4f44825..1aff4cf 100644 --- a/test/unit/Render/TargetRendererTest.php +++ b/test/unit/Render/TargetRendererTest.php @@ -17,12 +17,12 @@ use CommonDoc\Aggregate\Build\PageStatus; use CommonDoc\Aggregate\Build\ReasonCode; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\UnaddressableDocumentException; use CommonDoc\Aggregate\Output\OutputTree; use CommonDoc\Aggregate\Render\DocumentReader; use CommonDoc\Aggregate\Render\DocumentRenderer; use CommonDoc\Aggregate\Render\PageAddressFactory; use CommonDoc\Aggregate\Render\TargetRenderer; -use CommonDoc\Aggregate\Render\UnaddressableDocument; use CommonDoc\Aggregate\Render\ViewFactory; use CommonDoc\Aggregate\Source\SourceInterface; use CommonDoc\Aggregate\Version\Target; @@ -45,11 +45,11 @@ use function is_file; #[CoversClass(TargetRenderer::class)] -#[CoversClass(UnaddressableDocument::class)] +#[CoversClass(UnaddressableDocumentException::class)] #[CoversClass(DocumentReader::class)] #[CoversMethod(TargetRenderer::class, '__construct')] #[CoversMethod(TargetRenderer::class, 'render')] -#[CoversMethod(UnaddressableDocument::class, 'at')] +#[CoversMethod(UnaddressableDocumentException::class, 'at')] #[CoversMethod(DocumentReader::class, 'read')] final class TargetRendererTest extends TestCase { @@ -264,7 +264,7 @@ public function returnsNoResultsForATargetWithoutDocuments(): void #[Test] public function theExceptionNamesTheVersionAndTheDocumentThatCouldNotBeAddressed(): void { - $exception = UnaddressableDocument::at($this->target(), '../escape.md'); + $exception = UnaddressableDocumentException::at($this->target(), '../escape.md'); static::assertSame(ReasonCode::RenderFailed, $exception->reasonCode); static::assertStringContainsString('2.0', $exception->getMessage()); diff --git a/test/unit/Source/GitCandidatesTest.php b/test/unit/Source/GitCandidatesTest.php index ada2ecf..47abc0f 100644 --- a/test/unit/Source/GitCandidatesTest.php +++ b/test/unit/Source/GitCandidatesTest.php @@ -15,10 +15,10 @@ namespace CommonDocTest\Aggregate\Source; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; use CommonDoc\Aggregate\Source\GitCandidates; use CommonDoc\Aggregate\Source\GitCheckout; use CommonDoc\Aggregate\Source\GitReferences; -use CommonDoc\Aggregate\Source\MissingDocDirectory; use CommonDoc\Aggregate\Version\Strategy; use CommonDocTest\Aggregate\Support\GitRunner; use CommonDocTest\Aggregate\Support\TemporaryDirectory; @@ -80,7 +80,7 @@ public function reportsATreeCorpusWithoutADocumentationDirectory(): void { $runner = $this->runner()->returning("ref: refs/heads/main\tHEAD\n")->returning(''); - $this->expectException(MissingDocDirectory::class); + $this->expectException(MissingDocDirectoryException::class); $this->candidates($runner, Strategy::Tree)->names($this->project()); } diff --git a/test/unit/Source/GitCheckoutTest.php b/test/unit/Source/GitCheckoutTest.php index f73f3b1..ad671a1 100644 --- a/test/unit/Source/GitCheckoutTest.php +++ b/test/unit/Source/GitCheckoutTest.php @@ -16,9 +16,9 @@ use CommonDoc\Aggregate\Build\ReasonCode; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\GitFailureException; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Source\GitCheckout; -use CommonDoc\Aggregate\Source\GitFailure; -use CommonDoc\Aggregate\Source\SourceUnavailable; use CommonDocTest\Aggregate\Support\GitRunner; use CommonDocTest\Aggregate\Support\TemporaryDirectory; use InvalidArgumentException; @@ -153,7 +153,7 @@ public function reportsACacheDirectoryThatCannotBeCreated(): void try { $checkout->directory($this->project()); - } catch (SourceUnavailable $failure) { + } catch (SourceUnavailableException $failure) { static::assertSame(ReasonCode::SourceUnavailable, $failure->reasonCode); static::assertStringContainsString( sprintf( @@ -175,7 +175,7 @@ public function reportsACacheDirectoryThatCannotBeCreated(): void public function reportsAFailedCommandAsAnUnavailableSource(): void { $runner = new GitRunner(); - $runner->failing(GitFailure::failed( + $runner->failing(GitFailureException::failed( arguments : ['init', '--quiet'], exitCode : 128, diagnostic: 'boom', @@ -188,7 +188,7 @@ public function reportsAFailedCommandAsAnUnavailableSource(): void try { $checkout->directory($this->project()); - } catch (SourceUnavailable $failure) { + } catch (SourceUnavailableException $failure) { static::assertSame(ReasonCode::SourceUnavailable, $failure->reasonCode); return; diff --git a/test/unit/Source/GitCommandTest.php b/test/unit/Source/GitCommandTest.php index 3089e78..c4ae20b 100644 --- a/test/unit/Source/GitCommandTest.php +++ b/test/unit/Source/GitCommandTest.php @@ -14,8 +14,8 @@ namespace CommonDocTest\Aggregate\Source; +use CommonDoc\Aggregate\Exception\GitFailureException; use CommonDoc\Aggregate\Source\GitCommand; -use CommonDoc\Aggregate\Source\GitFailure; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\CoversMethod; use PHPUnit\Framework\Attributes\Test; @@ -66,7 +66,7 @@ public function reportsABinaryThatCannotBeStartedAsAFailure(): void ); static::fail('A binary that does not exist must not produce an answer.'); - } catch (GitFailure $failure) { + } catch (GitFailureException $failure) { static::assertStringContainsString('The git command "git status"', $failure->getMessage()); static::assertStringContainsString('git-command-that-does-not-exist', $failure->getMessage()); } @@ -75,7 +75,7 @@ public function reportsABinaryThatCannotBeStartedAsAFailure(): void #[Test] public function reportsANonZeroExitAsAFailure(): void { - $this->expectException(GitFailure::class); + $this->expectException(GitFailureException::class); $this->expectExceptionMessageMatches('/exited with 3: .*the command failed/s'); self::command()->run( diff --git a/test/unit/Source/GitDocumentsTest.php b/test/unit/Source/GitDocumentsTest.php index 1e6a895..291ad6d 100644 --- a/test/unit/Source/GitDocumentsTest.php +++ b/test/unit/Source/GitDocumentsTest.php @@ -15,10 +15,10 @@ namespace CommonDocTest\Aggregate\Source; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\MissingDocDirectoryException; use CommonDoc\Aggregate\Source\GitCheckout; use CommonDoc\Aggregate\Source\GitDocuments; use CommonDoc\Aggregate\Source\GitReferences; -use CommonDoc\Aggregate\Source\MissingDocDirectory; use CommonDoc\Aggregate\Version\Strategy; use CommonDoc\Aggregate\Version\Target; use CommonDocTest\Aggregate\Support\GitRunner; @@ -93,7 +93,7 @@ public function readsOneDocumentAtTheReferenceRatherThanTheBranchTip(): void #[Test] public function reportsATargetWithoutDocuments(): void { - $this->expectException(MissingDocDirectory::class); + $this->expectException(MissingDocDirectoryException::class); $this->documents($this->runner()->returning(''), Strategy::Ref)->paths($this->target('1.0')); } diff --git a/test/unit/Source/GitReferencesTest.php b/test/unit/Source/GitReferencesTest.php index 5e5ef47..294e509 100644 --- a/test/unit/Source/GitReferencesTest.php +++ b/test/unit/Source/GitReferencesTest.php @@ -16,9 +16,9 @@ use CommonDoc\Aggregate\Build\ReasonCode; use CommonDoc\Aggregate\Discovery\Project; +use CommonDoc\Aggregate\Exception\SourceUnavailableException; use CommonDoc\Aggregate\Source\GitCheckout; use CommonDoc\Aggregate\Source\GitReferences; -use CommonDoc\Aggregate\Source\SourceUnavailable; use CommonDoc\Aggregate\Version\Strategy; use CommonDoc\Aggregate\Version\Target; use CommonDocTest\Aggregate\Support\GitRunner; @@ -121,7 +121,7 @@ public function reportsASourceThatNamesNoDefaultBranch(): void try { $this->references($runner)->defaultRef($this->project()); - } catch (SourceUnavailable $failure) { + } catch (SourceUnavailableException $failure) { static::assertSame(ReasonCode::SourceUnavailable, $failure->reasonCode); return; @@ -137,7 +137,7 @@ public function requiresTheSymbolicReferenceToStartItsLine(): void try { $this->references($runner)->defaultRef($this->project()); - } catch (SourceUnavailable $failure) { + } catch (SourceUnavailableException $failure) { static::assertSame(ReasonCode::SourceUnavailable, $failure->reasonCode); return; diff --git a/test/unit/Support/GitRunner.php b/test/unit/Support/GitRunner.php index 3e59ecf..4169220 100644 --- a/test/unit/Support/GitRunner.php +++ b/test/unit/Support/GitRunner.php @@ -14,7 +14,7 @@ namespace CommonDocTest\Aggregate\Support; -use CommonDoc\Aggregate\Source\GitFailure; +use CommonDoc\Aggregate\Exception\GitFailureException; use CommonDoc\Aggregate\Source\GitRunnerInterface; use function array_shift; @@ -30,10 +30,10 @@ final class GitRunner implements GitRunnerInterface /** @var list, workingDirectory: string}> */ public array $calls = []; - /** @var list */ + /** @var list */ private array $responses = []; - public function failing(GitFailure $failure): self + public function failing(GitFailureException $failure): self { $this->responses[] = $failure; @@ -57,7 +57,7 @@ public function run(array $arguments, string $workingDirectory, array $environme $response = array_shift($this->responses); - if ($response instanceof GitFailure) { + if ($response instanceof GitFailureException) { throw $response; } diff --git a/test/unit/Version/StrategyTest.php b/test/unit/Version/StrategyTest.php index dc3c9d5..4deda23 100644 --- a/test/unit/Version/StrategyTest.php +++ b/test/unit/Version/StrategyTest.php @@ -15,7 +15,7 @@ namespace CommonDocTest\Aggregate\Version; use CommonDoc\Aggregate\Build\ReasonCode; -use CommonDoc\Aggregate\Config\InvalidSiteConfig; +use CommonDoc\Aggregate\Exception\InvalidSiteConfigException; use CommonDoc\Aggregate\Version\Strategy; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\CoversMethod; @@ -52,7 +52,7 @@ public function recordsTheReasonCodeForARejectedValue(): void Strategy::fromConfig('Tree'); static::fail('A value outside the two members must not be accepted.'); - } catch (InvalidSiteConfig $exception) { + } catch (InvalidSiteConfigException $exception) { static::assertSame('versions.strategy', $exception->key); static::assertSame(ReasonCode::InvalidSiteConfig, $exception->reasonCode); } @@ -61,7 +61,7 @@ public function recordsTheReasonCodeForARejectedValue(): void #[Test] public function rejectsAValueThatNamesNoMember(): void { - $this->expectException(InvalidSiteConfig::class); + $this->expectException(InvalidSiteConfigException::class); $this->expectExceptionMessage( 'Invalid site configuration at "versions.strategy": "git" is not one of "ref" or "tree".', ); From a20b60d0035ae686f7a0c0d310f6433eb9cb9827 Mon Sep 17 00:00:00 2001 From: Joey Smith Date: Fri, 13 Nov 2026 00:23:48 -0600 Subject: [PATCH 2/2] Cover the renamed throw paths that codecov/patch flagged The exception rename rewrote three throw lines that had no test behind them, so they entered the patch as uncovered lines. Cover each one and assert the message, because the class name inside the message is what the rename changed. - SiteConfigReaderTest: a configuration file that cannot be read, and a configuration file whose contents are not a JSON object. - GitCommandTest: a working directory that does not exist, which makes the process impossible to start and therefore emits the "could not be run" diagnostic rather than the non-zero-exit one. Reached through a real process start attempt because GitCommand constructs its own Symfony Process; the existing suite already drives real subprocesses this way. Unit suite 360 tests / 747 assertions (was 357 / 736). Integration unchanged at 1 / 1. All four mago gates clean, baselines untouched. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- test/unit/Config/SiteConfigReaderTest.php | 39 +++++++++++++++++++++++ test/unit/Source/GitCommandTest.php | 22 +++++++++++++ 2 files changed, 61 insertions(+) diff --git a/test/unit/Config/SiteConfigReaderTest.php b/test/unit/Config/SiteConfigReaderTest.php index dfe4115..fd47859 100644 --- a/test/unit/Config/SiteConfigReaderTest.php +++ b/test/unit/Config/SiteConfigReaderTest.php @@ -150,6 +150,45 @@ public function rejectsADocumentNestedWithinTheDecodingDepthByItsUnknownTopLevel $this->assertRejected('a', static fn(): SiteConfig => new SiteConfigReader()->read($path)); } + #[Test] + public function rejectsAFileThatCannotBeRead(): void + { + $path = $this->directory . DIRECTORY_SEPARATOR . 'absent.json'; + + try { + new SiteConfigReader()->read($path); + + static::fail('A configuration file that cannot be read must not be accepted.'); + } catch (InvalidSiteConfigException $exception) { + static::assertSame('site.json', $exception->key); + static::assertSame(ReasonCode::InvalidSiteConfig, $exception->reasonCode); + static::assertSame( + sprintf('Invalid site configuration at "site.json": "%s" cannot be read.', $path), + $exception->getMessage(), + ); + } + } + + #[Test] + public function rejectsAFileThatDoesNotHoldAJsonObject(): void + { + $path = $this->directory . DIRECTORY_SEPARATOR . 'site.json'; + file_put_contents($path, data: '42'); + + try { + new SiteConfigReader()->read($path); + + static::fail('A configuration file must hold a JSON object.'); + } catch (InvalidSiteConfigException $exception) { + static::assertSame('site.json', $exception->key); + static::assertSame(ReasonCode::InvalidSiteConfig, $exception->reasonCode); + static::assertSame( + 'Invalid site configuration at "site.json": the file does not hold a JSON object.', + $exception->getMessage(), + ); + } + } + #[Test] public function rejectsAFileThatIsNotValidJson(): void { diff --git a/test/unit/Source/GitCommandTest.php b/test/unit/Source/GitCommandTest.php index c4ae20b..208e413 100644 --- a/test/unit/Source/GitCommandTest.php +++ b/test/unit/Source/GitCommandTest.php @@ -23,6 +23,7 @@ use function getcwd; +use const DIRECTORY_SEPARATOR; use const PHP_BINARY; #[CoversClass(GitCommand::class)] @@ -84,6 +85,27 @@ public function reportsANonZeroExitAsAFailure(): void ); } + #[Test] + public function reportsAWorkingDirectoryThatDoesNotExistAsACommandThatCouldNotRun(): void + { + $absent = self::workingDirectory() . DIRECTORY_SEPARATOR . 'absent-directory'; + + try { + self::command()->run( + arguments : ['status'], + workingDirectory: $absent, + ); + + static::fail('A working directory that does not exist must not produce an answer.'); + } catch (GitFailureException $failure) { + static::assertStringStartsWith( + 'The git command "git status" could not be run: ', + $failure->getMessage(), + ); + static::assertStringContainsString($absent, $failure->getMessage()); + } + } + #[Test] public function returnsTheOutputOfTheCommandUnchanged(): void {