Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion specs/001-aggregate-renderer/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,12 +133,13 @@ src/
├── Console/
│ └── BuildCommand.php # site:build, human summary or --json
├── Discovery/
│ ├── DiscoveryFailed.php # Discovery failure with a reason code
│ ├── GitHubProjectSource.php # Org repositories and doc-target property
│ ├── Project.php # Readonly discovered project
│ ├── ProjectSourceInterface.php # all(): list<Project>
│ ├── SitePath.php # Derives a site path from a repository name
│ └── Token.php # Reads the token from its environment variable at use
├── Exception/
│ └── DiscoveryException.php # Discovery failure with a reason code
├── Output/
│ ├── CnameFile.php # Writes and verifies the site address file
│ └── OutputTree.php # Resets, writes and reads output paths
Expand Down
4 changes: 2 additions & 2 deletions src/Build/Container/SiteBuildFactoryFactory.php
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
namespace CommonDoc\Aggregate\Build\Container;

use CommonDoc\Aggregate\Build\SiteBuildFactory;
use CommonDoc\Aggregate\Discovery\ProjectSourceInterface;
use CommonDoc\Aggregate\Discovery\ProjectSourceFactoryInterface;
use CommonDoc\Aggregate\Render\SiteRendererFactoryInterface;
use CommonDoc\Aggregate\Source\SourceFactoryInterface;
use CommonDoc\Aggregate\Version\StrategyFactory;
Expand Down Expand Up @@ -49,7 +49,7 @@ public function __invoke(
?array $options = null,
): SiteBuildFactory {
return new SiteBuildFactory(
discovery : $container->get(ProjectSourceInterface::class),
projects : $container->get(ProjectSourceFactoryInterface::class),
sources : $container->get(SourceFactoryInterface::class),
strategies: $container->get(StrategyFactory::class),
renderers : $container->get(SiteRendererFactoryInterface::class),
Expand Down
2 changes: 2 additions & 0 deletions src/Build/SiteBuild.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
use CommonDoc\Aggregate\Config\SiteConfig;
use CommonDoc\Aggregate\Discovery\Project;
use CommonDoc\Aggregate\Discovery\ProjectSourceInterface;
use CommonDoc\Aggregate\Exception\DiscoveryException;
use CommonDoc\Aggregate\Exception\MissingCnameException;
use CommonDoc\Aggregate\Output\CnameFile;
use CommonDoc\Aggregate\Output\OutputTree;
Expand Down Expand Up @@ -49,6 +50,7 @@
* @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
* @throws DiscoveryException When no project could be discovered at all
*/
public function build(SiteConfig $config): BuildReport
{
Expand All @@ -66,14 +68,14 @@
array_push($rendered, ...$outcome->targets);
}

usort($rendered, Target::compare(...));

Check warning on line 71 in src/Build/SiteBuild.php

View workflow job for this annotation

GitHub Actions / Mutation testing

Escaped Mutant for Mutator "FunctionCallRemoval": @@ @@ array_push($rendered, ...$outcome->targets); } - usort($rendered, Target::compare(...)); + $this->renderer->writeSiteIndex($rendered); $this->renderer->writeNotFoundPage();

Check warning on line 71 in src/Build/SiteBuild.php

View workflow job for this annotation

GitHub Actions / Mutation testing

Escaped Mutant for Mutator "FunctionCallRemoval": @@ @@ array_push($rendered, ...$outcome->targets); } - usort($rendered, Target::compare(...)); + $this->renderer->writeSiteIndex($rendered); $this->renderer->writeNotFoundPage();

$this->renderer->writeSiteIndex($rendered);
$this->renderer->writeNotFoundPage();

$cname = new CnameFile($tree, $config->hostname);
$cname->write();
$cname->verify();

Check warning on line 78 in src/Build/SiteBuild.php

View workflow job for this annotation

GitHub Actions / Mutation testing

Escaped Mutant for Mutator "MethodCallRemoval": @@ @@ $cname = new CnameFile($tree, $config->hostname); $cname->write(); - $cname->verify(); + $totals = Total::of($results); $report = new BuildReport(

Check warning on line 78 in src/Build/SiteBuild.php

View workflow job for this annotation

GitHub Actions / Mutation testing

Escaped Mutant for Mutator "MethodCallRemoval": @@ @@ $cname = new CnameFile($tree, $config->hostname); $cname->write(); - $cname->verify(); + $totals = Total::of($results); $report = new BuildReport(

$totals = Total::of($results);
$report = new BuildReport(
Expand Down
9 changes: 5 additions & 4 deletions src/Build/SiteBuildFactory.php
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
namespace CommonDoc\Aggregate\Build;

use CommonDoc\Aggregate\Config\SiteConfig;
use CommonDoc\Aggregate\Discovery\ProjectSourceInterface;
use CommonDoc\Aggregate\Discovery\ProjectSourceFactoryInterface;
use CommonDoc\Aggregate\Render\SiteRendererFactoryInterface;
use CommonDoc\Aggregate\Source\SourceFactoryInterface;
use CommonDoc\Aggregate\Version\StrategyFactory;
Expand All @@ -30,12 +30,13 @@
* The source is built once here and handed to both the renderer and the project build, so a project
* is listed and then read against one checkout cache. Everything the build needs that does not come
* from the configuration is injected, so this is the only class that knows the order in which the
* pieces fit together.
* pieces fit together. Discovery is the one seam that is itself a factory, because the organization
* it lists belongs to the configuration and therefore cannot be known when the container is built.
*/
final readonly class SiteBuildFactory implements SiteBuildFactoryInterface
{
public function __construct(
private ProjectSourceInterface $discovery,
private ProjectSourceFactoryInterface $projects,
private SourceFactoryInterface $sources,
private StrategyFactory $strategies,
private SiteRendererFactoryInterface $renderers,
Expand All @@ -56,7 +57,7 @@ public function create(SiteConfig $config): SiteBuild
);

return new SiteBuild(
discovery : $this->discovery,
discovery : $this->projects->create(config: $config),
renderer : $renderer,
projectBuild: new ProjectBuild(
source : $source,
Expand Down
36 changes: 21 additions & 15 deletions src/ConfigProvider.php
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,9 @@
use CommonDoc\Aggregate\Config\SiteConfigReader;
use CommonDoc\Aggregate\Console\BuildCommand;
use CommonDoc\Aggregate\Console\Container\BuildCommandFactory;
use CommonDoc\Aggregate\Discovery\ProjectSourceInterface;
use CommonDoc\Aggregate\Discovery\Container\GitHubProjectSourceFactoryFactory;
use CommonDoc\Aggregate\Discovery\GitHubProjectSourceFactory;
use CommonDoc\Aggregate\Discovery\ProjectSourceFactoryInterface;
use CommonDoc\Aggregate\Render\SiteRendererFactory;
use CommonDoc\Aggregate\Render\SiteRendererFactoryInterface;
use CommonDoc\Aggregate\Render\ViewFactory;
Expand All @@ -39,9 +41,11 @@
*
* Everything registered here is either configuration-free or a factory that needs the configuration
* to build its product, because the output tree, the git source and the renderer all depend on
* values that only exist once `site.json` has been read. Discovery is deliberately absent: this
* package does not yet ship a project source, so a consumer must register one against
* {@see ProjectSourceInterface} before the command can be built.
* values that only exist once `site.json` has been read. Discovery follows the same rule: the
* organization it lists and the variable holding the token live in the configuration, so the
* container supplies the HTTP seams and {@see ProjectSourceFactoryInterface} turns them into a
* source per build. The PSR-18 client is the one service this package cannot register for a
* consumer, so a site that never builds still resolves everything else.
*
* @internal
*/
Expand All @@ -61,19 +65,21 @@ public function getDependencies(): array
{
return [
'aliases' => [
ReportFileFactoryInterface::class => ReportFileFactory::class,
SiteBuildFactoryInterface::class => SiteBuildFactory::class,
SiteRendererFactoryInterface::class => SiteRendererFactory::class,
SourceFactoryInterface::class => SourceFactory::class,
ProjectSourceFactoryInterface::class => GitHubProjectSourceFactory::class,
ReportFileFactoryInterface::class => ReportFileFactory::class,
SiteBuildFactoryInterface::class => SiteBuildFactory::class,
SiteRendererFactoryInterface::class => SiteRendererFactory::class,
SourceFactoryInterface::class => SourceFactory::class,
],
'factories' => [
BuildCommand::class => BuildCommandFactory::class,
ReportFileFactory::class => InvokableFactory::class,
SiteBuildFactory::class => SiteBuildFactoryFactory::class,
SiteConfigReader::class => InvokableFactory::class,
SiteRendererFactory::class => InvokableFactory::class,
SourceFactory::class => InvokableFactory::class,
StrategyFactory::class => InvokableFactory::class,
BuildCommand::class => BuildCommandFactory::class,
GitHubProjectSourceFactory::class => GitHubProjectSourceFactoryFactory::class,
ReportFileFactory::class => InvokableFactory::class,
SiteBuildFactory::class => SiteBuildFactoryFactory::class,
SiteConfigReader::class => InvokableFactory::class,
SiteRendererFactory::class => InvokableFactory::class,
SourceFactory::class => InvokableFactory::class,
StrategyFactory::class => InvokableFactory::class,
],
];
}
Expand Down
13 changes: 11 additions & 2 deletions src/Console/BuildCommand.php
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
use CommonDoc\Aggregate\Build\BuildReport;
use CommonDoc\Aggregate\Build\SiteBuildFactoryInterface;
use CommonDoc\Aggregate\Config\SiteConfigReader;
use CommonDoc\Aggregate\Exception\DiscoveryException;
use CommonDoc\Aggregate\Exception\InvalidSiteConfigException;
use CommonDoc\Aggregate\Exception\MissingCnameException;
use CommonDoc\Aggregate\Report\ReportFile;
Expand All @@ -42,7 +43,9 @@
*
* Configuration is read before anything is built, so an unusable `site.json` exits 2 with a diagnostic
* and no report is written: a report describes a build, and a build that never started has nothing to
* describe. Every other outcome is the report's own exit code, which is why the command never decides
* describe. Discovery is the second thing that can block a run before rendering, for the same reason
* and with the same exit code: no token and no boundary mean no project was read, so there is nothing
* to report. Every other outcome is the report's own exit code, which is why the command never decides
* an exit code of its own.
*/
#[AsCommand(name: self::NAME, description: 'Render the aggregate documentation site.')]
Expand Down Expand Up @@ -112,7 +115,13 @@
return self::EXIT_BLOCKED;
}

$report = $this->builds->create(config: $config)->build(config: $config);
try {
$report = $this->builds->create(config: $config)->build(config: $config);
} catch (DiscoveryException $failed) {
$this->errorsOf($output)->writeln(sprintf('<error>%s</error>', $failed->getMessage()));

return self::EXIT_BLOCKED;
}

if (true === $input->getOption('json')) {
$this->writeJson($output, $this->reports->create(config: $config), $report);
Expand Down Expand Up @@ -143,7 +152,7 @@
$output->writeln(sprintf(
'site:build: %d pages in %d projects (%d ok, %d partial, %d failed, %d skipped)',
$report->totals->pages,
$report->totals->ok + $report->totals->partial + $report->totals->failed + $report->totals->skipped,

Check warning on line 155 in src/Console/BuildCommand.php

View workflow job for this annotation

GitHub Actions / Mutation testing

Escaped Mutant for Mutator "Plus": @@ @@ $output->writeln(sprintf( 'site:build: %d pages in %d projects (%d ok, %d partial, %d failed, %d skipped)', $report->totals->pages, - $report->totals->ok + $report->totals->partial + $report->totals->failed + $report->totals->skipped, + $report->totals->ok + $report->totals->partial + $report->totals->failed - $report->totals->skipped, $report->totals->ok, $report->totals->partial, $report->totals->failed,

Check warning on line 155 in src/Console/BuildCommand.php

View workflow job for this annotation

GitHub Actions / Mutation testing

Escaped Mutant for Mutator "Plus": @@ @@ $output->writeln(sprintf( 'site:build: %d pages in %d projects (%d ok, %d partial, %d failed, %d skipped)', $report->totals->pages, - $report->totals->ok + $report->totals->partial + $report->totals->failed + $report->totals->skipped, + $report->totals->ok + $report->totals->partial + $report->totals->failed - $report->totals->skipped, $report->totals->ok, $report->totals->partial, $report->totals->failed,
$report->totals->ok,
$report->totals->partial,
$report->totals->failed,
Expand Down
53 changes: 53 additions & 0 deletions src/Discovery/Container/GitHubProjectSourceFactoryFactory.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
<?php

declare(strict_types=1);

/**
* This file is part of the common-doc/aggregate-renderer package.
*
* Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
* and contributors.
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/

namespace CommonDoc\Aggregate\Discovery\Container;

use CommonDoc\Aggregate\Discovery\GitHubProjectSourceFactory;
use Laminas\ServiceManager\Factory\FactoryInterface;
use Override;
use Psr\Container\ContainerExceptionInterface;
use Psr\Container\ContainerInterface;
use Psr\Container\NotFoundExceptionInterface;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;

/**
* Builds the GitHub project source factory from the HTTP seams a consumer registered.
*
* The client is the one seam this package cannot supply: a PSR-18 implementation is a consumer
* choice, so a missing registration is reported as a missing service when the command is built
* rather than as a fatal error later. The request factory has an invokable default from
* laminas-diactoros, a dependency this package already carries.
*/
final readonly class GitHubProjectSourceFactoryFactory implements FactoryInterface
{
/**
* @param ?array<mixed> $options
*
* @throws ContainerExceptionInterface When a service cannot be created
* @throws NotFoundExceptionInterface When a service is not registered
*/
#[Override]
public function __invoke(
ContainerInterface $container,
string $requestedName,
?array $options = null,
): GitHubProjectSourceFactory {
return new GitHubProjectSourceFactory(
client : $container->get(ClientInterface::class),
requests: $container->get(RequestFactoryInterface::class),
);
}
}
53 changes: 53 additions & 0 deletions src/Discovery/DocTarget.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
<?php

declare(strict_types=1);

/**
* This file is part of the common-doc/aggregate-renderer package.
*
* Copyright (c) 2026 Joey Smith <jsmith@webinertia.net>
* and contributors.
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/

namespace CommonDoc\Aggregate\Discovery;

use function array_find;
use function is_string;
use function trim;

/**
* The `doc-target` repository custom property, which is the whole onboarding surface: a repository
* carrying a non-empty value is onboarded and a repository carrying anything else is not.
*
* @internal
*/
final class DocTarget
{
public const string PROPERTY = 'doc-target';

private function __construct() {}

/**
* @param list<array<string, mixed>> $properties the property list a repository answers with
*/
public static function from(array $properties): ?string
{
$property = array_find(
$properties,
/** @param array<string, mixed> $entry */
static fn(array $entry): bool => self::PROPERTY === ($entry['property_name'] ?? null),
);

if (null === $property) {
return null;

Check warning on line 45 in src/Discovery/DocTarget.php

View workflow job for this annotation

GitHub Actions / Mutation testing

Escaped Mutant for Mutator "ReturnRemoval": @@ @@ ); if (null === $property) { - return null; + } /** @var mixed $value */

Check warning on line 45 in src/Discovery/DocTarget.php

View workflow job for this annotation

GitHub Actions / Mutation testing

Escaped Mutant for Mutator "ReturnRemoval": @@ @@ ); if (null === $property) { - return null; + } /** @var mixed $value */
}

/** @var mixed $value */
$value = $property['value'] ?? null;

return is_string($value) && '' !== trim($value) ? trim($value) : null;
}
}
Loading
Loading