From 494d28dc0f53808458bad9b292b77191ec1a49d5 Mon Sep 17 00:00:00 2001 From: Joey Smith Date: Fri, 13 Nov 2026 21:38:44 -0600 Subject: [PATCH] fix(discovery): accept boolean doc-target as onboarding The doc-target property is defined at organization level as a boolean, so GitHub answers it with JSON true or false. DocTarget::from() required a string and returned null for true, leaving onboarded repositories undiscovered. Boolean true now onboards with the conventional docs directory, while a non-empty string still selects the directory it names. Boolean false, null, an absent property, and blank or non-string values stay off the site. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/Discovery/DocTarget.php | 14 ++++++++++++-- src/Discovery/GitHubProjectSource.php | 5 +++-- src/Discovery/Project.php | 6 +++--- test/unit/Discovery/DocTargetTest.php | 23 ++++++++++++++++++++++- 4 files changed, 40 insertions(+), 8 deletions(-) diff --git a/src/Discovery/DocTarget.php b/src/Discovery/DocTarget.php index 591da9b..c3df012 100644 --- a/src/Discovery/DocTarget.php +++ b/src/Discovery/DocTarget.php @@ -19,8 +19,12 @@ 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. + * The `doc-target` repository custom property, which is the whole onboarding surface. + * + * The property is defined at organization level as a boolean, so the two accepted forms are a + * boolean `true`, which onboards the repository with the conventional `docs` directory, and a + * non-empty string, which onboards it with the directory it names. Everything else, including + * boolean `false` and a blank string, leaves the repository off the site. * * @internal */ @@ -28,6 +32,8 @@ final class DocTarget { public const string PROPERTY = 'doc-target'; + private const string DEFAULT_DIRECTORY = 'docs'; + private function __construct() {} /** @@ -48,6 +54,10 @@ public static function from(array $properties): ?string /** @var mixed $value */ $value = $property['value'] ?? null; + if (true === $value) { + return self::DEFAULT_DIRECTORY; + } + return is_string($value) && '' !== trim($value) ? trim($value) : null; } } diff --git a/src/Discovery/GitHubProjectSource.php b/src/Discovery/GitHubProjectSource.php index 5d7ea3f..3335fec 100644 --- a/src/Discovery/GitHubProjectSource.php +++ b/src/Discovery/GitHubProjectSource.php @@ -29,8 +29,9 @@ * Discovers the onboarded repositories of one GitHub organization. * * Two endpoints, and no vendor SDK: the organization's repositories, then each repository's custom - * property values. A repository is onboarded when its `doc-target` property carries a directory, so - * the property is the whole onboarding cost and a repository without it is simply not listed. + * property values. A repository is onboarded when its `doc-target` property is boolean `true` or + * names a directory, so the property is the whole onboarding cost and a repository without it is + * simply not listed. * * A failure here is not a project defect: nothing was read, so nothing can be reported per project. * Every failure names a reason code and stops the run before rendering. diff --git a/src/Discovery/Project.php b/src/Discovery/Project.php index 52002a8..550438a 100644 --- a/src/Discovery/Project.php +++ b/src/Discovery/Project.php @@ -22,9 +22,9 @@ /** * One onboarded repository, as discovery reports it. * - * A repository is onboarded when its `doc-target` custom property carries a directory, so a project - * always names the directory its sources live in. A repository without that property produces no - * project at all rather than one with an empty directory. + * A repository is onboarded when its `doc-target` custom property is boolean `true` or names a + * directory, so a project always names the directory its sources live in. A repository without + * that property produces no project at all rather than one with an empty directory. */ final readonly class Project { diff --git a/test/unit/Discovery/DocTargetTest.php b/test/unit/Discovery/DocTargetTest.php index a296bc6..880e3f6 100644 --- a/test/unit/Discovery/DocTargetTest.php +++ b/test/unit/Discovery/DocTargetTest.php @@ -24,6 +24,15 @@ #[CoversMethod(DocTarget::class, 'from')] final class DocTargetTest extends TestCase { + #[Test] + public function onboardsWithTheConventionalDirectoryWhenThePropertyIsTrue(): void + { + static::assertSame( + 'docs', + DocTarget::from([['property_name' => 'doc-target', 'value' => true]]), + ); + } + #[Test] public function readsTheFirstMatchingPropertyOnly(): void { @@ -73,11 +82,17 @@ public function reportsNoTargetWhenThePropertyHoldsAnEmptyValue(): void } #[Test] - public function reportsNoTargetWhenThePropertyHoldsNoString(): void + public function reportsNoTargetWhenThePropertyHoldsANonStringNonBooleanValue(): void { static::assertNull(DocTarget::from([['property_name' => 'doc-target', 'value' => ['docs']]])); } + #[Test] + public function reportsNoTargetWhenThePropertyHoldsNull(): void + { + static::assertNull(DocTarget::from([['property_name' => 'doc-target', 'value' => null]])); + } + #[Test] public function reportsNoTargetWhenThePropertyHoldsOnlyWhitespace(): void { @@ -90,6 +105,12 @@ public function reportsNoTargetWhenThePropertyIsAbsent(): void static::assertNull(DocTarget::from([['property_name' => 'unrelated', 'value' => 'docs']])); } + #[Test] + public function reportsNoTargetWhenThePropertyIsFalse(): void + { + static::assertNull(DocTarget::from([['property_name' => 'doc-target', 'value' => false]])); + } + #[Test] public function trimsTheValueItReads(): void {