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..fd47859 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; @@ -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 { @@ -318,7 +357,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..208e413 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; @@ -23,6 +23,7 @@ use function getcwd; +use const DIRECTORY_SEPARATOR; use const PHP_BINARY; #[CoversClass(GitCommand::class)] @@ -66,7 +67,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 +76,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( @@ -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 { 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".', );