Skip to content

Commit f465f57

Browse files
localheinzlocalheinz
committed
Enhancement: Document array shapes
1 parent e9e9b31 commit f465f57

File tree

6 files changed

+86
-21
lines changed

6 files changed

+86
-21
lines changed

‎.psalm/baseline.xml

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -66,13 +66,6 @@
6666
<code><![CDATA[$this->files[] = &$this->children[count($this->children) - 1]]]></code>
6767
</UnsupportedReferenceUsage>
6868
</file>
69-
<file src="src/Node/File.php">
70-
<InvalidPropertyAssignmentValue>
71-
<code><![CDATA[$this->codeUnitsByLine]]></code>
72-
<code><![CDATA[$this->codeUnitsByLine]]></code>
73-
<code><![CDATA[$this->codeUnitsByLine]]></code>
74-
</InvalidPropertyAssignmentValue>
75-
</file>
7669
<file src="src/Node/Iterator.php">
7770
<ArgumentTypeCoercion>
7871
<code><![CDATA[$this->nodes[$this->position]]]></code>

‎src/Node/File.php

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,9 @@ final class File extends AbstractNode
4646

4747
/**
4848
* @psalm-param array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int} $linesOfCode
49+
* @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}> $classes
50+
* @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}> $traits
51+
* @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}> $functions
4952
*/
5053
public function __construct(string $name, AbstractNode $parent, array $lineCoverageData, array $functionCoverageData, array $testData, array $classes, array $traits, array $functions, array $linesOfCode)
5154
{
@@ -253,6 +256,11 @@ public function numberOfTestedFunctions(): int
253256
return $this->numTestedFunctions;
254257
}
255258

259+
/**
260+
* @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}> $classes
261+
* @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}> $traits
262+
* @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}> $functions
263+
*/
256264
private function calculateStatistics(array $classes, array $traits, array $functions): void
257265
{
258266
foreach (range(1, $this->linesOfCode['linesOfCode']) as $lineNumber) {
@@ -355,6 +363,9 @@ private function calculateStatistics(array $classes, array $traits, array $funct
355363
}
356364
}
357365

366+
/**
367+
* @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}> $classes
368+
*/
358369
private function processClasses(array $classes): void
359370
{
360371
$link = $this->id() . '.html#';
@@ -401,6 +412,9 @@ private function processClasses(array $classes): void
401412
}
402413
}
403414

415+
/**
416+
* @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}> $traits
417+
*/
404418
private function processTraits(array $traits): void
405419
{
406420
$link = $this->id() . '.html#';
@@ -447,6 +461,9 @@ private function processTraits(array $traits): void
447461
}
448462
}
449463

464+
/**
465+
* @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}> $functions
466+
*/
450467
private function processFunctions(array $functions): void
451468
{
452469
$link = $this->id() . '.html#';
@@ -513,6 +530,27 @@ static function (array $path)
513530
}
514531
}
515532

533+
/**
534+
* @psalm-param array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int} $method
535+
*
536+
* @psalm-return array{
537+
* methodName: string,
538+
* visibility: string,
539+
* signature: string,
540+
* startLine: int,
541+
* endLine: int,
542+
* executableLines: int,
543+
* executedLines: int,
544+
* executableBranches: int,
545+
* executedBranches: int,
546+
* executablePaths: int,
547+
* executedPaths: int,
548+
* ccn: int,
549+
* coverage: int,
550+
* crap: int,
551+
* link: string
552+
* }
553+
*/
516554
private function newMethod(string $className, string $methodName, array $method, string $link): array
517555
{
518556
$methodData = [

‎src/StaticAnalysis/CodeUnitFindingVisitor.php

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,17 +36,17 @@
3636
final class CodeUnitFindingVisitor extends NodeVisitorAbstract
3737
{
3838
/**
39-
* @psalm-var array<string,array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string,array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
39+
* @psalm-var array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
4040
*/
4141
private array $classes = [];
4242

4343
/**
44-
* @psalm-var array<string,array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string,array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
44+
* @psalm-var array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
4545
*/
4646
private array $traits = [];
4747

4848
/**
49-
* @psalm-var array<string,array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
49+
* @psalm-var array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
5050
*/
5151
private array $functions = [];
5252

@@ -84,23 +84,23 @@ public function enterNode(Node $node): void
8484
}
8585

8686
/**
87-
* @psalm-return array<string,array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string,array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
87+
* @psalm-return array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
8888
*/
8989
public function classes(): array
9090
{
9191
return $this->classes;
9292
}
9393

9494
/**
95-
* @psalm-return array<string,array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string,array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
95+
* @psalm-return array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
9696
*/
9797
public function traits(): array
9898
{
9999
return $this->traits;
100100
}
101101

102102
/**
103-
* @psalm-return array<string,array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
103+
* @psalm-return array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
104104
*/
105105
public function functions(): array
106106
{

‎src/StaticAnalysis/ExecutableLinesFindingVisitor.php

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -352,6 +352,9 @@ public function afterTraverse(array $nodes): void
352352
);
353353
}
354354

355+
/**
356+
* @psalm-return array<int, int>
357+
*/
355358
public function executableLinesGroupedByBranch(): array
356359
{
357360
return $this->executableLinesGroupedByBranch;

‎src/StaticAnalysis/FileAnalyser.php

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,18 +14,33 @@
1414
*/
1515
interface FileAnalyser
1616
{
17+
/**
18+
* @psalm-return array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
19+
*/
1720
public function classesIn(string $filename): array;
1821

22+
/**
23+
* @psalm-return array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string,array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>
24+
*/
1925
public function traitsIn(string $filename): array;
2026

27+
/**
28+
* @psalm-return array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
29+
*/
2130
public function functionsIn(string $filename): array;
2231

2332
/**
2433
* @psalm-return array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}
2534
*/
2635
public function linesOfCodeFor(string $filename): array;
2736

37+
/**
38+
* @psalm-return array<int, int>
39+
*/
2840
public function executableLinesIn(string $filename): array;
2941

42+
/**
43+
* @psalm-return array<int, int>
44+
*/
3045
public function ignoredLinesFor(string $filename): array;
3146
}

‎src/StaticAnalysis/ParsingFileAnalyser.php

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -35,15 +35,34 @@
3535
*/
3636
final class ParsingFileAnalyser implements FileAnalyser
3737
{
38-
private array $classes = [];
39-
private array $traits = [];
38+
/**
39+
* @psalm-var array<string, array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>>
40+
*/
41+
private array $classes = [];
42+
43+
/**
44+
* @psalm-var array<string, array<string, array{name: string, namespacedName: string, namespace: string, startLine: int, endLine: int, methods: array<string, array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int}>}>>
45+
*/
46+
private array $traits = [];
47+
48+
/**
49+
* @psalm-var array<string, array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>>
50+
*/
4051
private array $functions = [];
4152

4253
/**
43-
* @var array<string,array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}>
54+
* @var array<string, array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}>
55+
*/
56+
private array $linesOfCode = [];
57+
58+
/**
59+
* @var array<string, array<int, int>>
60+
*/
61+
private array $ignoredLines = [];
62+
63+
/**
64+
* @var array<string, array<int, int>>
4465
*/
45-
private array $linesOfCode = [];
46-
private array $ignoredLines = [];
4766
private array $executableLines = [];
4867
private readonly bool $useAnnotationsForIgnoringCode;
4968
private readonly bool $ignoreDeprecatedCode;
@@ -75,9 +94,6 @@ public function functionsIn(string $filename): array
7594
return $this->functions[$filename];
7695
}
7796

78-
/**
79-
* @psalm-return array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}
80-
*/
8197
public function linesOfCodeFor(string $filename): array
8298
{
8399
$this->analyse($filename);

0 commit comments

Comments
 (0)