Skip to content

refactor(exception): gather the six failures into one Exception bucket - #7

Merged
tyrsson merged 2 commits into
1.0.xfrom
tyrsson-exception-bucket-rename
Nov 13, 2026
Merged

tyrsson merged 2 commits into
1.0.xfrom
tyrsson-exception-bucket-rename

Conversation

@tyrsson

@tyrsson tyrsson commented Nov 13, 2026

Copy link
Copy Markdown
Member

What moved

The six inherited exception classes now live in one bucket at the package root,
CommonDoc\Aggregate\Exception, and each name ends with the Exception suffix. This is a move
and a rename only: same final class ... extends RuntimeException, same readonly properties, same
private constructors, same named constructors, same reason codes, same messages.

Before After
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 and catch clause moved with them. The four
dedicated tests moved to test/unit/Exception under the CommonDocTest\Aggregate\Exception
namespace, and each test file was renamed to match its class.

src/Build/ReasonCode.php is deliberately unchanged. Its cases (InvalidSiteConfig,
MissingCname, MissingDocDirectory, SourceUnavailable) are reason vocabulary recorded in the
report, not class references.

Reference-line edits in three shared files

src/Build/SiteBuild.php, src/Console/BuildCommand.php and test/unit/BuildCommandTest.php
carry reference-only edits, because the code does not compile otherwise: two imports, one @throws
line, one catch type, and the matching test references. Behaviour is unchanged, including the
exit-2 blocked path in BuildCommand.

Gates

Run once on the final tree. All clean, with no new baseline entries and no suppressions:

  • mago lint --ignore-baseline: no issues found
  • mago format --check: all files already formatted (core.autocrlf is false, so this is meaningful)
  • mago analyze: no issues found
  • mago guard: no issues found
  • Unit suite: 357 tests, 736 assertions
  • Integration suite: 1 test, 1 assertion

Both counts are identical to the pre-change baseline recorded on the parent commit, so the move
changed nothing observable.

The rule this satisfies

The guard rule requiring the Exception suffix and the Exception directory now exists in
webware/webware-tools as of 1.0.0-rc.12, merged in PR #78 at commit
7bad0a74c9d4b743a12c1a50f33973e6533ca17c. That is why mago guard is green here rather than
silent about these classes.

Overlap with PR #6

This branch and tyrsson-discovery-of-projects (PR #6) both edit src/Build/SiteBuild.php,
src/Console/BuildCommand.php and test/unit/BuildCommandTest.php. Whichever lands second needs a
rebase; the overlap is known and is being sequenced on the owner side. src/Discovery/ is not
touched by this branch at all.

Naming proof

A grep over the package finds no class, interface, trait or enum declaration ending in
Exception outside src/Exception/, and every class inside src/Exception/ carries the suffix. A
case-sensitive grep for the six old bare class identifiers returns only the four ReasonCode enum
cases.

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>
@codecov

codecov Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

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>
@tyrsson
tyrsson merged commit d5b2d77 into 1.0.x Nov 13, 2026
23 checks passed
@tyrsson
tyrsson deleted the tyrsson-exception-bucket-rename branch November 13, 2026 06:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant