Skip to content

feat(discovery): onboard documentation sites from the doc-target property - #6

Merged
tyrsson merged 2 commits into
1.0.xfrom
tyrsson-discovery-of-projects
Nov 13, 2026
Merged

tyrsson merged 2 commits into
1.0.xfrom
tyrsson-discovery-of-projects

Conversation

@tyrsson

@tyrsson tyrsson commented Nov 13, 2026

Copy link
Copy Markdown
Member

What this does

Implements the discovery half of the aggregate site: an organisation is listed, each repository's doc-target custom property is read, and the repositories that carry one become the projects the build renders. Onboarding a new documentation site is now one property write and nothing else.

One commit, 702ea13d, on top of 1.0.x at 75a57e5e.

Why this shape

doc-target is the same custom property the CI workflow already targets, so there is one source of truth for "this repository publishes documentation" rather than a manifest that would drift. A repository without the property is not rendered; it simply never becomes a project.

The HTTP boundary is deliberately split in two. GitHubApi owns the request, the token and the status codes and decides nothing about meaning ("What an answer means is decided by the caller; this type only refuses it"). GitHubProjectSource owns the meaning, including the one asymmetry that matters: a 404 on the properties endpoint reads as "no property", not as a failure.

ProjectSourceInterface sits beside Source\SourceFactoryInterface and takes the same shape, create(SiteConfig). Both exist for the same reason: the organisation, the token variable and the cache directory are not known until site.json has been read. The dependency runs discovery to source, not the other way round: SourceInterface consumes Discovery\Project, never the reverse.

Verification

Run locally in the worktree at 702ea13d, tree clean and in sync with origin. core.autocrlf is false, so format --check is meaningful.

Gate Result
mago lint --ignore-baseline No issues found
mago format --check All files already formatted
mago analyze No issues found
mago guard No issues found
PHPUnit unit OK, 391 tests, 788 assertions
PHPUnit integration OK, 17 tests, 41 assertions

408 tests, 829 assertions, zero failures. No baseline entry was added and no [[issues]] suppression was introduced for any new file. tasks.md checkboxes are left unticked and .specify is untouched.

Local Infection on this commit: MSI 97% and covered code MSI 97% against the 95 floor, 843 mutations. Two escaped mutants sit in the new code and both are structural no-ops: DocTarget line 45 (a removed return null falls through to $property['value'] ?? null, which returns the same null) and GitHubApi line 85 (array_values over a JSON array, which always decodes to a list, kept because it enforces the list<array<string, mixed>> type that array_merge(...$pages) relies on). Neither warrants a test that exists only to kill a mutant.

Decisions the plan did not settle

  1. The API base URL is a constructor default, https://api.github.com, rather than a site.json key. site-config.schema.json has no such key and adding one is a schema change, so it is left for a plan revision if a GitHub Enterprise target is ever wanted.
  2. A discovery failure is caught in BuildCommand and mapped to exit 2 with a diagnostic on stderr and no report written. SiteBuild keeps @throws DiscoveryFailed, so the failure cannot be swallowed by a caller that does not handle it.
  3. SiteBuildFactory takes a ProjectSourceFactoryInterface, not a ProjectSourceInterface, because a factory only ever receives a SiteConfig at build time.
  4. Colliding site paths are left to the corpus duplicate-slug finding rather than being detected twice.
  5. GitHubApi and DocTarget are split to stay inside mago's class complexity, kan-defect and method-count thresholds. No threshold was raised.

Spec

specs/001-aggregate-renderer/tasks.md phase 5, US3, T064 to T070. Checkpoint: a new project appears in the next build after one property change and nothing else.

Closes nothing; this is one phase of 001-aggregate-renderer.

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com

@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 97.80220% with 4 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/Discovery/GitHubApi.php 92.30% 3 Missing ⚠️
src/Discovery/DocTarget.php 88.88% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

tyrsson and others added 2 commits November 13, 2026 00:29
Adds SitePath, DiscoveryFailed, Token, DocTarget, GitHubApi,
GitHubProjectSource and the per-build factory seam, and binds
ProjectSourceFactoryInterface in ConfigProvider so site:build can
read the doc-target repository property and find onboarded projects.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Rename the discovery failure so it ends in Exception and move it into the
root level Exception namespace, matching the fleet guard rule that any
exception class be named *Exception and live in an Exception namespace
segment.

Behaviour is unchanged: the private constructor, the readonly reasonCode
property and the three named constructors are identical, and every
reference in source, tests and the plan source tree follows the rename.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@tyrsson
tyrsson force-pushed the tyrsson-discovery-of-projects branch from cade1df to 1e34cf6 Compare November 13, 2026 06:31
@tyrsson
tyrsson merged commit 8dbdf85 into 1.0.x Nov 13, 2026
23 checks passed
@tyrsson
tyrsson deleted the tyrsson-discovery-of-projects branch November 13, 2026 06:35
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