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
14 changes: 12 additions & 2 deletions src/Discovery/DocTarget.php
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,21 @@
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
*/
final class DocTarget
{
public const string PROPERTY = 'doc-target';

private const string DEFAULT_DIRECTORY = 'docs';

private function __construct() {}

/**
Expand All @@ -42,12 +48,16 @@
);

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

Check warning on line 51 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 51 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;

if (true === $value) {
return self::DEFAULT_DIRECTORY;
}

return is_string($value) && '' !== trim($value) ? trim($value) : null;
}
}
5 changes: 3 additions & 2 deletions src/Discovery/GitHubProjectSource.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 3 additions & 3 deletions src/Discovery/Project.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down
23 changes: 22 additions & 1 deletion test/unit/Discovery/DocTargetTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down Expand Up @@ -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
{
Expand All @@ -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
{
Expand Down
Loading