Skip to content

Commit 3b78366

Browse files
localheinzsebastianbergmann
localheinz
authored and
sebastianbergmann
committed
Enhancement: Document array shapes
1 parent ef1c71e commit 3b78366

14 files changed

+344
-35
lines changed

‎src/CodeCoverage.php‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,11 @@
3535

3636
/**
3737
* Provides collection functionality for PHP code coverage information.
38+
*
39+
* @psalm-type TestType = array{
40+
* size: string,
41+
* status: string,
42+
* }
3843
*/
3944
final class CodeCoverage
4045
{
@@ -51,7 +56,7 @@ final class CodeCoverage
5156
private bool $useAnnotationsForIgnoringCode = true;
5257

5358
/**
54-
* @psalm-var array<string, array{size: string, status: string}>
59+
* @psalm-var array<string, TestType>
5560
*/
5661
private array $tests = [];
5762

@@ -120,15 +125,15 @@ public function setData(ProcessedCodeCoverageData $data): void
120125
}
121126

122127
/**
123-
* @psalm-return array<string, array{size: string, status: string}>
128+
* @psalm-return array<string, TestType>
124129
*/
125130
public function getTests(): array
126131
{
127132
return $this->tests;
128133
}
129134

130135
/**
131-
* @psalm-param array<string, array{size: string, status: string}> $tests
136+
* @psalm-param array<string, TestType> $tests
132137
*/
133138
public function setTests(array $tests): void
134139
{

‎src/Data/ProcessedCodeCoverageData.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,19 +20,42 @@
2020

2121
/**
2222
* @internal This class is not covered by the backward compatibility promise for phpunit/php-code-coverage
23+
*
24+
* @psalm-import-type XdebugFunctionCoverageType from \SebastianBergmann\CodeCoverage\Driver\XdebugDriver
25+
*
26+
* @psalm-type TestIdType = string
2327
*/
2428
final class ProcessedCodeCoverageData
2529
{
2630
/**
2731
* Line coverage data.
2832
* An array of filenames, each having an array of linenumbers, each executable line having an array of testcase ids.
33+
*
34+
* @psalm-var array<string, array<int, null|list<TestIdType>>>
2935
*/
3036
private array $lineCoverage = [];
3137

3238
/**
3339
* Function coverage data.
3440
* Maintains base format of raw data (@see https://xdebug.org/docs/code_coverage), but each 'hit' entry is an array
3541
* of testcase ids.
42+
*
43+
* @psalm-var array<string, array<string, array{
44+
* branches: array<int, array{
45+
* op_start: int,
46+
* op_end: int,
47+
* line_start: int,
48+
* line_end: int,
49+
* hit: list<TestIdType>,
50+
* out: array<int, int>,
51+
* out_hit: array<int, int>,
52+
* }>,
53+
* paths: array<int, array{
54+
* path: array<int, int>,
55+
* hit: list<TestIdType>,
56+
* }>,
57+
* hit: list<TestIdType>
58+
* }>>
3659
*/
3760
private array $functionCoverage = [];
3861

@@ -213,6 +236,8 @@ private function priorityForLine(array $data, int $line): int
213236

214237
/**
215238
* For a function we have never seen before, copy all data over and simply init the 'hit' array.
239+
*
240+
* @psalm-param XdebugFunctionCoverageType $functionData
216241
*/
217242
private function initPreviouslyUnseenFunction(string $file, string $functionName, array $functionData): void
218243
{
@@ -231,6 +256,8 @@ private function initPreviouslyUnseenFunction(string $file, string $functionName
231256
* For a function we have seen before, only copy over and init the 'hit' array for any unseen branches and paths.
232257
* Techniques such as mocking and where the contents of a file are different vary during tests (e.g. compiling
233258
* containers) mean that the functions inside a file cannot be relied upon to be static.
259+
*
260+
* @psalm-param XdebugFunctionCoverageType $functionData
234261
*/
235262
private function initPreviouslySeenFunction(string $file, string $functionName, array $functionData): void
236263
{

‎src/Data/RawCodeCoverageData.php‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@
2626

2727
/**
2828
* @internal This class is not covered by the backward compatibility promise for phpunit/php-code-coverage
29+
*
30+
* @psalm-import-type XdebugFunctionsCoverageType from \SebastianBergmann\CodeCoverage\Driver\XdebugDriver
31+
* @psalm-import-type XdebugCodeCoverageWithoutPathCoverageType from \SebastianBergmann\CodeCoverage\Driver\XdebugDriver
32+
* @psalm-import-type XdebugCodeCoverageWithPathCoverageType from \SebastianBergmann\CodeCoverage\Driver\XdebugDriver
2933
*/
3034
final class RawCodeCoverageData
3135
{
@@ -35,20 +39,26 @@ final class RawCodeCoverageData
3539
private static array $emptyLineCache = [];
3640

3741
/**
38-
* @see https://xdebug.org/docs/code_coverage for format
42+
* @psalm-var XdebugCodeCoverageWithoutPathCoverageType
3943
*/
4044
private array $lineCoverage;
4145

4246
/**
43-
* @see https://xdebug.org/docs/code_coverage for format
47+
* @psalm-var array<string, XdebugFunctionsCoverageType>
4448
*/
4549
private array $functionCoverage;
4650

51+
/**
52+
* @psalm-param XdebugCodeCoverageWithoutPathCoverageType $rawCoverage
53+
*/
4754
public static function fromXdebugWithoutPathCoverage(array $rawCoverage): self
4855
{
4956
return new self($rawCoverage, []);
5057
}
5158

59+
/**
60+
* @psalm-param XdebugCodeCoverageWithPathCoverageType $rawCoverage
61+
*/
5262
public static function fromXdebugWithPathCoverage(array $rawCoverage): self
5363
{
5464
$lineCoverage = [];
@@ -73,6 +83,10 @@ public static function fromUncoveredFile(string $filename, FileAnalyser $analyse
7383
return new self([$filename => $lineCoverage], []);
7484
}
7585

86+
/**
87+
* @psalm-param XdebugCodeCoverageWithoutPathCoverageType $lineCoverage
88+
* @psalm-param array<string, XdebugFunctionsCoverageType> $functionCoverage
89+
*/
7690
private function __construct(array $lineCoverage, array $functionCoverage)
7791
{
7892
$this->lineCoverage = $lineCoverage;
@@ -86,11 +100,17 @@ public function clear(): void
86100
$this->lineCoverage = $this->functionCoverage = [];
87101
}
88102

103+
/**
104+
* @psalm-return XdebugCodeCoverageWithoutPathCoverageType
105+
*/
89106
public function lineCoverage(): array
90107
{
91108
return $this->lineCoverage;
92109
}
93110

111+
/**
112+
* @psalm-return array<string, XdebugFunctionsCoverageType>
113+
*/
94114
public function functionCoverage(): array
95115
{
96116
return $this->functionCoverage;

‎src/Driver/XdebugDriver.php‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,34 @@
3131

3232
/**
3333
* @internal This class is not covered by the backward compatibility promise for phpunit/php-code-coverage
34+
*
35+
* @see https://xdebug.org/docs/code_coverage#xdebug_get_code_coverage
36+
*
37+
* @psalm-type XdebugLinesCoverageType = array<int, int>
38+
* @psalm-type XdebugBranchCoverageType = array{
39+
* op_start: int,
40+
* op_end: int,
41+
* line_start: int,
42+
* line_end: int,
43+
* hit: int,
44+
* out: array<int, int>,
45+
* out_hit: array<int, int>,
46+
* }
47+
* @psalm-type XdebugPathCoverageType = array{
48+
* path: array<int, int>,
49+
* hit: int,
50+
* }
51+
* @psalm-type XdebugFunctionCoverageType = array{
52+
* branches: array<int, XdebugBranchCoverageType>,
53+
* paths: array<int, XdebugPathCoverageType>,
54+
* }
55+
* @psalm-type XdebugFunctionsCoverageType = array<string, XdebugFunctionCoverageType>
56+
* @psalm-type XdebugPathAndBranchesCoverageType = array{
57+
* lines: XdebugLinesCoverageType,
58+
* functions: XdebugFunctionsCoverageType,
59+
* }
60+
* @psalm-type XdebugCodeCoverageWithoutPathCoverageType = array<string, XdebugLinesCoverageType>
61+
* @psalm-type XdebugCodeCoverageWithPathCoverageType = array<string, XdebugPathAndBranchesCoverageType>
3462
*/
3563
final class XdebugDriver extends Driver
3664
{
@@ -84,9 +112,11 @@ public function stop(): RawCodeCoverageData
84112
xdebug_stop_code_coverage();
85113

86114
if ($this->collectsBranchAndPathCoverage()) {
115+
/* @var XdebugCodeCoverageWithPathCoverageType $data */
87116
return RawCodeCoverageData::fromXdebugWithPathCoverage($data);
88117
}
89118

119+
/* @var XdebugCodeCoverageWithoutPathCoverageType $data */
90120
return RawCodeCoverageData::fromXdebugWithoutPathCoverage($data);
91121
}
92122

‎src/Node/AbstractNode.php‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@
1919

2020
/**
2121
* @internal This class is not covered by the backward compatibility promise for phpunit/php-code-coverage
22+
*
23+
* @psalm-import-type LinesOfCodeType from \SebastianBergmann\CodeCoverage\StaticAnalysis\FileAnalyser
24+
* @psalm-import-type ProcessedFunctionType from \SebastianBergmann\CodeCoverage\Node\File
25+
* @psalm-import-type ProcessedClassType from \SebastianBergmann\CodeCoverage\Node\File
26+
* @psalm-import-type ProcessedTraitType from \SebastianBergmann\CodeCoverage\Node\File
2227
*/
2328
abstract class AbstractNode implements Countable
2429
{
@@ -163,14 +168,23 @@ public function numberOfTestedFunctionsAndMethods(): int
163168
return $this->numberOfTestedFunctions() + $this->numberOfTestedMethods();
164169
}
165170

171+
/**
172+
* @psalm-return array<string, ProcessedClassType>
173+
*/
166174
abstract public function classes(): array;
167175

176+
/**
177+
* @psalm-return array<string, ProcessedTraitType>
178+
*/
168179
abstract public function traits(): array;
169180

181+
/**
182+
* @psalm-return array<string, ProcessedFunctionType>
183+
*/
170184
abstract public function functions(): array;
171185

172186
/**
173-
* @psalm-return array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}
187+
* @psalm-return LinesOfCodeType
174188
*/
175189
abstract public function linesOfCode(): array;
176190

‎src/Node/Builder.php‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@
2727

2828
/**
2929
* @internal This class is not covered by the backward compatibility promise for phpunit/php-code-coverage
30+
*
31+
* @psalm-import-type TestType from \SebastianBergmann\CodeCoverage\CodeCoverage
3032
*/
3133
final class Builder
3234
{
@@ -56,7 +58,7 @@ public function build(CodeCoverage $coverage): Directory
5658
}
5759

5860
/**
59-
* @psalm-param array<string, array{size: string, status: string}> $tests
61+
* @psalm-param array<string, TestType> $tests
6062
*/
6163
private function addItems(Directory $root, array $items, array $tests): void
6264
{
@@ -129,6 +131,8 @@ private function addItems(Directory $root, array $items, array $tests): void
129131
* )
130132
* )
131133
* </code>
134+
*
135+
* @psalm-return array<string, array<string, array{lineCoverage: array<int, int>, functionCoverage: array<string, array<int, int>>}>>
132136
*/
133137
private function buildDirectoryStructure(ProcessedCodeCoverageData $data): array
134138
{

‎src/Node/Directory.php‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616

1717
/**
1818
* @internal This class is not covered by the backward compatibility promise for phpunit/php-code-coverage
19+
*
20+
* @psalm-import-type LinesOfCodeType from \SebastianBergmann\CodeCoverage\StaticAnalysis\FileAnalyser
1921
*/
2022
final class Directory extends AbstractNode implements IteratorAggregate
2123
{
@@ -38,7 +40,7 @@ final class Directory extends AbstractNode implements IteratorAggregate
3840
private ?array $functions = null;
3941

4042
/**
41-
* @psalm-var null|array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}
43+
* @psalm-var null|LinesOfCodeType
4244
*/
4345
private ?array $linesOfCode = null;
4446
private int $numFiles = -1;
@@ -161,7 +163,7 @@ public function functions(): array
161163
}
162164

163165
/**
164-
* @psalm-return array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}
166+
* @psalm-return LinesOfCodeType
165167
*/
166168
public function linesOfCode(): array
167169
{

0 commit comments

Comments
 (0)