Enhancement: Document array shapes

sebastianbergmann · Mar 19, 2023 · f465f57 · f465f57
1 parent e9e9b31
commit f465f57
Show file tree

Hide file tree

Showing 6 changed files with 86 additions and 21 deletions.
diff --git a/.psalm/baseline.xml b/.psalm/baseline.xml
@@ -66,13 +66,6 @@
       <code><![CDATA[$this->files[]    = &$this->children[count($this->children) - 1]]]></code>
     </UnsupportedReferenceUsage>
   </file>
-  <file src="src/Node/File.php">
-    <InvalidPropertyAssignmentValue>
-      <code><![CDATA[$this->codeUnitsByLine]]></code>
-      <code><![CDATA[$this->codeUnitsByLine]]></code>
-      <code><![CDATA[$this->codeUnitsByLine]]></code>
-    </InvalidPropertyAssignmentValue>
-  </file>
   <file src="src/Node/Iterator.php">
     <ArgumentTypeCoercion>
       <code><![CDATA[$this->nodes[$this->position]]]></code>

diff --git a/src/Node/File.php b/src/Node/File.php
@@ -46,6 +46,9 @@ final class File extends AbstractNode
 
     /**
      * @psalm-param array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int} $linesOfCode
+     * @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
+     * @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
+     * @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}> $functions
      */
     public function __construct(string $name, AbstractNode $parent, array $lineCoverageData, array $functionCoverageData, array $testData, array $classes, array $traits, array $functions, array $linesOfCode)
     {
@@ -253,6 +256,11 @@ public function numberOfTestedFunctions(): int
         return $this->numTestedFunctions;
     }
 
+    /**
+     * @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
+     * @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
+     * @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}> $functions
+     */
     private function calculateStatistics(array $classes, array $traits, array $functions): void
     {
         foreach (range(1, $this->linesOfCode['linesOfCode']) as $lineNumber) {
@@ -355,6 +363,9 @@ private function calculateStatistics(array $classes, array $traits, array $funct
         }
     }
 
+    /**
+     * @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
+     */
     private function processClasses(array $classes): void
     {
         $link = $this->id() . '.html#';
@@ -401,6 +412,9 @@ private function processClasses(array $classes): void
         }
     }
 
+    /**
+     * @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
+     */
     private function processTraits(array $traits): void
     {
         $link = $this->id() . '.html#';
@@ -447,6 +461,9 @@ private function processTraits(array $traits): void
         }
     }
 
+    /**
+     * @psalm-param array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}> $functions
+     */
     private function processFunctions(array $functions): void
     {
         $link = $this->id() . '.html#';
@@ -513,6 +530,27 @@ static function (array $path)
         }
     }
 
+    /**
+     * @psalm-param array{methodName: string, signature: string, visibility: string, startLine: int, endLine: int, ccn: int} $method
+     *
+     * @psalm-return array{
+     *     methodName: string,
+     *     visibility: string,
+     *     signature: string,
+     *     startLine: int,
+     *     endLine: int,
+     *     executableLines: int,
+     *     executedLines: int,
+     *     executableBranches: int,
+     *     executedBranches: int,
+     *     executablePaths: int,
+     *     executedPaths: int,
+     *     ccn: int,
+     *     coverage: int,
+     *     crap: int,
+     *     link: string
+     * }
+     */
     private function newMethod(string $className, string $methodName, array $method, string $link): array
     {
         $methodData = [

diff --git a/src/StaticAnalysis/CodeUnitFindingVisitor.php b/src/StaticAnalysis/CodeUnitFindingVisitor.php
@@ -36,17 +36,17 @@
 final class CodeUnitFindingVisitor extends NodeVisitorAbstract
 {
     /**
-     * @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}>}>
+     * @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}>}>
      */
     private array $classes = [];
 
     /**
-     * @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}>}>
+     * @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}>}>
      */
     private array $traits = [];
 
     /**
-     * @psalm-var array<string,array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
+     * @psalm-var array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
      */
     private array $functions = [];
 
@@ -84,23 +84,23 @@ public function enterNode(Node $node): void
     }
 
     /**
-     * @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}>}>
+     * @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}>}>
      */
     public function classes(): array
     {
         return $this->classes;
     }
 
     /**
-     * @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}>}>
+     * @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}>}>
      */
     public function traits(): array
     {
         return $this->traits;
     }
 
     /**
-     * @psalm-return array<string,array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
+     * @psalm-return array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
      */
     public function functions(): array
     {

diff --git a/src/StaticAnalysis/ExecutableLinesFindingVisitor.php b/src/StaticAnalysis/ExecutableLinesFindingVisitor.php
@@ -352,6 +352,9 @@ public function afterTraverse(array $nodes): void
         );
     }
 
+    /**
+     * @psalm-return array<int, int>
+     */
     public function executableLinesGroupedByBranch(): array
     {
         return $this->executableLinesGroupedByBranch;

diff --git a/src/StaticAnalysis/FileAnalyser.php b/src/StaticAnalysis/FileAnalyser.php
@@ -14,18 +14,33 @@
  */
 interface FileAnalyser
 {
+    /**
+     * @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}>}>
+     */
     public function classesIn(string $filename): array;
 
+    /**
+     * @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}>}>
+     */
     public function traitsIn(string $filename): array;
 
+    /**
+     * @psalm-return array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>
+     */
     public function functionsIn(string $filename): array;
 
     /**
      * @psalm-return array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}
      */
     public function linesOfCodeFor(string $filename): array;
 
+    /**
+     * @psalm-return array<int, int>
+     */
     public function executableLinesIn(string $filename): array;
 
+    /**
+     * @psalm-return array<int, int>
+     */
     public function ignoredLinesFor(string $filename): array;
 }
diff --git a/src/StaticAnalysis/ParsingFileAnalyser.php b/src/StaticAnalysis/ParsingFileAnalyser.php
@@ -35,15 +35,34 @@
  */
 final class ParsingFileAnalyser implements FileAnalyser
 {
-    private array $classes   = [];
-    private array $traits    = [];
+    /**
+     * @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}>}>>
+     */
+    private array $classes = [];
+
+    /**
+     * @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}>}>>
+     */
+    private array $traits = [];
+
+    /**
+     * @psalm-var array<string, array<string, array{name: string, namespacedName: string, namespace: string, signature: string, startLine: int, endLine: int, ccn: int}>>
+     */
     private array $functions = [];
 
     /**
-     * @var array<string,array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}>
+     * @var array<string, array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}>
+     */
+    private array $linesOfCode = [];
+
+    /**
+     * @var array<string, array<int, int>>
+     */
+    private array $ignoredLines = [];
+
+    /**
+     * @var array<string, array<int, int>>
      */
-    private array $linesOfCode     = [];
-    private array $ignoredLines    = [];
     private array $executableLines = [];
     private readonly bool $useAnnotationsForIgnoringCode;
     private readonly bool $ignoreDeprecatedCode;
@@ -75,9 +94,6 @@ public function functionsIn(string $filename): array
         return $this->functions[$filename];
     }
 
-    /**
-     * @psalm-return array{linesOfCode: int, commentLinesOfCode: int, nonCommentLinesOfCode: int}
-     */
     public function linesOfCodeFor(string $filename): array
     {
         $this->analyse($filename);