Skip to content

Commit

Permalink
fix(documentator): Document::toSplittable() will remove self links …
Browse files Browse the repository at this point in the history
…(+ added `SelfLinksRemove` mutation).
  • Loading branch information
LastDragon-ru committed Aug 23, 2024
1 parent b76ee17 commit 7842200
Show file tree
Hide file tree
Showing 16 changed files with 222 additions and 18 deletions.
2 changes: 2 additions & 0 deletions packages/documentator/src/Markdown/Document.php
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\FootnotesRemove;
use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\ReferencesInline;
use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\ReferencesPrefix;
use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\SelfLinksRemove;
use LastDragon_ru\LaraASP\Documentator\Utils\Text;
use League\CommonMark\Extension\CommonMark\Node\Block\Heading;
use League\CommonMark\Extension\CommonMark\Node\Block\HtmlBlock;
Expand Down Expand Up @@ -161,6 +162,7 @@ public function toSplittable(): static {
return $this->mutate(new Composite(
new FootnotesRemove(),
new ReferencesInline(),
new SelfLinksRemove(),
));
}

Expand Down
71 changes: 71 additions & 0 deletions packages/documentator/src/Markdown/Mutations/SelfLinksRemove.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
<?php declare(strict_types = 1);

namespace LastDragon_ru\LaraASP\Documentator\Markdown\Mutations;

use LastDragon_ru\LaraASP\Documentator\Markdown\Contracts\Mutation;
use LastDragon_ru\LaraASP\Documentator\Markdown\Data\Data;
use LastDragon_ru\LaraASP\Documentator\Markdown\Data\Offset;
use LastDragon_ru\LaraASP\Documentator\Markdown\Document;
use LastDragon_ru\LaraASP\Documentator\Markdown\Utils;
use League\CommonMark\Extension\CommonMark\Node\Inline\Link;
use League\CommonMark\Node\Block\Document as DocumentNode;
use Override;

use function rawurldecode;

/**
* Removes all links to the self.
*/
readonly class SelfLinksRemove implements Mutation {
public function __construct() {
// empty
}

/**
* @inheritDoc
*/
#[Override]
public function __invoke(Document $document, DocumentNode $node): iterable {
// Just in case
yield from [];

// Update
$links = $this->getLinks($document, $node);

foreach ($links as $link) {
// Location & Offset?
$location = Utils::getLocation($link);
$offset = Data::get($link, Offset::class);

if (!$location || !$offset) {
continue;
}

// Changes
yield [Utils::getLengthLocation($location, 1), null]; // [
yield [Utils::getOffsetLocation($location, $offset - 1), null]; // ](...)
}

// Return
return true;
}

/**
* @return list<Link>
*/
protected function getLinks(Document $document, DocumentNode $node): array {
$links = [];

foreach ($node->iterator() as $child) {
if ($child instanceof Link && $this->isLink($document, rawurldecode($child->getUrl()))) {
$links[] = $child;
}
}

return $links;
}

protected function isLink(Document $document, string $url): bool {
return Utils::isPathRelative($url) && Utils::isPathToSelf($url, $document);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
<?php declare(strict_types = 1);

namespace LastDragon_ru\LaraASP\Documentator\Markdown\Mutations;

use LastDragon_ru\LaraASP\Documentator\Markdown\Document;
use LastDragon_ru\LaraASP\Documentator\Markdown\Editor;
use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase;
use League\CommonMark\Node\Block\Document as DocumentNode;
use Override;
use PHPUnit\Framework\Attributes\CoversClass;

use function array_key_first;
use function array_values;

/**
* @internal
*/
#[CoversClass(SelfLinksRemove::class)]
final class SelfLinksRemoveTest extends TestCase {
public function testInvoke(): void {
$markdown = <<<'MARKDOWN'
# Header
Text text [link](https://example.com) text text [`link`][link] text
text text [self][self] text text [self](#fragment) text text text
text text ![image][image] text text ![image](#fragment).
[self]: #fragment
[link]: ./path/to/file.md
[image]: ./#fragment
# Special
## Inside Quote
> Text text [self][self] text text [self](#fragment) text text text
## Inside Table
| Header | [Header][link] |
|-------------------------|-------------------------------|
| Cell [link][self] cell. | Cell `\|` \\| ![table][image] |
| Cell | Cell cell [table][self]. |
MARKDOWN;
$document = new class($markdown, 'path/to/file.md') extends Document {
#[Override]
public function getNode(): DocumentNode {
return parent::getNode();
}

/**
* @inheritDoc
*/
#[Override]
public function getLines(): array {
return parent::getLines();
}
};
$node = $document->getNode();
$lines = $document->getLines();
$offset = (int) array_key_first($lines);
$mutation = new SelfLinksRemove();
$changes = $mutation($document, $node);
$actual = (string) (new Editor(array_values($lines), $offset))->mutate($changes);

self::assertEquals(
<<<'MARKDOWN'
# Header
Text text [link](https://example.com) text text [`link`][link] text
text text self text text self text text text
text text ![image][image] text text ![image](#fragment).
[self]: #fragment
[link]: ./path/to/file.md
[image]: ./#fragment
# Special
## Inside Quote
> Text text self text text self text text text
## Inside Table
| Header | [Header][link] |
|-------------------------|-------------------------------|
| Cell link cell. | Cell `\|` \\| ![table][image] |
| Cell | Cell cell table. |
MARKDOWN,
$actual,
);
}
}
11 changes: 11 additions & 0 deletions packages/documentator/src/Markdown/Utils.php
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,17 @@ public static function getLocation(Node $node): ?Location {
return $location;
}

public static function getLengthLocation(Location $location, ?int $length): Location {
return new Location(
$location->startLine,
$location->endLine,
$location->offset,
$length,
$location->startLinePadding,
$location->internalPadding,
);
}

public static function getOffsetLocation(Location $location, int $offset): Location {
return new Location(
$location->startLine,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,27 +51,32 @@ public function testInvoke(Closure|string $expected, string $file, Parameters $p
*/
public static function dataProviderProcess(): array {
return [
'default' => [
'default' => [
'ValidExpected.txt',
'Valid.txt',
new Parameters('...'),
],
'with summary' => [
'with summary' => [
'ValidWithSummaryExpected.txt',
'Valid.txt',
new Parameters('...', summary: true),
],
'only summary' => [
'only summary' => [
'ValidOnlySummaryExpected.txt',
'Valid.txt',
new Parameters('...', summary: true, description: false),
],
'no docblock' => [
'only description' => [
'ValidOnlyDescriptionExpected.txt',
'Valid.txt',
new Parameters('...', summary: false, description: true),
],
'no docblock' => [
'NoDocBlockExpected.txt',
'NoDocBlock.txt',
new Parameters('...'),
],
'invalid' => [
'invalid' => [
static function (self $test, Context $context): Exception {
return new TargetIsNotValidPhpFile($context);
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,12 @@
use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction;

/**
* Summary [A][link][^1].
* Summary [A][link][^1] [B](#fragment) [C][fragment].
*
* Description description description description description description
* description description description description description description
* description description description description description description
* [description][link][^1].
* [description][link][^1] [description](#fragment) [description][fragment].
*
* Description with inline tags:
*
Expand All @@ -18,6 +18,7 @@ use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\I
* - {@see Instruction::getName()}
*
* [link]: https://example.com/
* [fragment]: #fragment
*
* [^1]: Footnote
*
Expand Down
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
Summary [A][ffe8b433904a50b3-link][^ffe8b433904a50b3-1].
Summary [A][ffe8b433904a50b3-link][^ffe8b433904a50b3-1] [B](#fragment) [C][ffe8b433904a50b3-fragment].

Description description description description description description
description description description description description description
description description description description description description
[description][ffe8b433904a50b3-link][^ffe8b433904a50b3-1].
[description][ffe8b433904a50b3-link][^ffe8b433904a50b3-1] [description](#fragment) [description][ffe8b433904a50b3-fragment].

Description with inline tags:

Expand All @@ -13,5 +13,6 @@ Description with inline tags:
- `\LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction::getName()`

[ffe8b433904a50b3-link]: https://example.com/
[ffe8b433904a50b3-fragment]: #fragment

[^ffe8b433904a50b3-1]: Footnote
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
Description description description description description description
description description description description description description
description description description description description description
[description](https://example.com/) description description.

Description with inline tags:

- `\B`, `\B`, `\B::b()`
- `\A`, `\A`, `\A::a()`
- `\LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction`
- `\LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction::getName()`
Original file line number Diff line number Diff line change
@@ -1 +1 @@
Summary [A](https://example.com/).
Summary [A](https://example.com/) B C.
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
Summary [A][ffe8b433904a50b3-link][^ffe8b433904a50b3-1].
Summary [A][ffe8b433904a50b3-link][^ffe8b433904a50b3-1] [B](#fragment) [C][ffe8b433904a50b3-fragment].

Description description description description description description
description description description description description description
description description description description description description
[description][ffe8b433904a50b3-link][^ffe8b433904a50b3-1].
[description][ffe8b433904a50b3-link][^ffe8b433904a50b3-1] [description](#fragment) [description][ffe8b433904a50b3-fragment].

Description with inline tags:

Expand All @@ -13,5 +13,6 @@ Description with inline tags:
- `\LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction::getName()`

[ffe8b433904a50b3-link]: https://example.com/
[ffe8b433904a50b3-fragment]: #fragment

[^ffe8b433904a50b3-1]: Footnote
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# Nested A
# Nested [A](#fragment)

Summary [text](../../Document.md).
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
<!-- markdownlint-disable -->

Summary [text](../Document.md) summary [link][link] and summary[^1].
Summary [text](../Document.md) summary [link][link] and summary[^1] and [self](#fragment) and [self][self].

[link]: ../Document.md (title)
[self]: #fragment

[^1]: Footnote
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Document C

Summary [text](../Document.md) summary [link](../Document.md "title") and summary.
Summary [text](../Document.md) summary [link](../Document.md "title") and summary and self and self.

[Read more](<Document C.md>).

Expand Down
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
# The Package with custom readme
# The Package with custom [readme](#fragment)

Text with [link](README.md) and [link][link] and footnote[^note].
Text with [link](README.md) and [link][link] and footnote[^note] and [self](#fragment) and [self][self].

## Section

Text.

[link]: README.md (title)
[self]: #fragment

[^note]: Footnote.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## The Package with custom readme

Text with [link](packages/package%20custom%20readme/README.md) and [link](<packages/package custom readme/README.md> "title") and footnote.
Text with [link](packages/package%20custom%20readme/README.md) and [link](<packages/package custom readme/README.md> "title") and footnote and self and self.

[Read more](<packages/package custom readme/CUSTOM.md>).

Expand Down
5 changes: 5 additions & 0 deletions phpstan-baseline.neon
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,11 @@ parameters:
count: 1
path: packages/documentator/src/Markdown/Mutations/ReferencesPrefix.php

-
message: "#^Generator expects value type array\\{LastDragon_ru\\\\LaraASP\\\\Documentator\\\\Markdown\\\\Location\\\\Location, string\\|null\\}, \\*NEVER\\* given\\.$#"
count: 1
path: packages/documentator/src/Markdown/Mutations/SelfLinksRemove.php

-
message: "#^Parameter \\#1 \\$dependency of class LastDragon_ru\\\\LaraASP\\\\Documentator\\\\Processor\\\\ExecutorTraversable constructor expects LastDragon_ru\\\\LaraASP\\\\Documentator\\\\Processor\\\\Contracts\\\\Dependency\\<Traversable\\<mixed, LastDragon_ru\\\\LaraASP\\\\Documentator\\\\Processor\\\\FileSystem\\\\Directory\\|LastDragon_ru\\\\LaraASP\\\\Documentator\\\\Processor\\\\FileSystem\\\\File\\>\\>, LastDragon_ru\\\\LaraASP\\\\Documentator\\\\Processor\\\\Contracts\\\\Dependency\\<\\*\\> given\\.$#"
count: 1
Expand Down

0 comments on commit 7842200

Please sign in to comment.