Allow space before array shape opening brace and added unit tests

[rhertogh]

Currently when defining an array shape it is possible to include a space before the opening brace on the nested level, but not on the "top" level, e.g.

/**
 * @param array { // <- does not work
 *     key: array { // <- does work
 *         a: int
 *     }
 * } $arr
 * @return int
 */
function foo($arr) {
    /** @psalm-trace $a */
    $a  = $arr['key']['a'];
    return $a;
}

Psalm examples:
Works: https://psalm.dev/r/bf0dc1c5dc
Does not work: https://psalm.dev/r/ac1064b93d

This PR allows the space before array shape opening brace and adds unit tests for \Psalm\Internal\Analyzer\CommentAnalyzer::splitDocLine()

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/bf0dc1c5dc

<?php

/**
 * No space between array and opening brace on line 5, on line 6 it is possible. 
 * @param array{
 *     key: array {
 *         a: int
 *     }
 * } $arr
 * @return int
 */
function foo($arr) {
    /** @psalm-trace $a */
    $a  = $arr['key']['a'];
    return $a;
}

Psalm output (using commit 8fe1f15):

INFO: Trace - 14:5 - $a: int

https://psalm.dev/r/ac1064b93d

<?php

/**
 * Space between array and opening brace on line 5 and 6 doesn't work. 
 * @param array {
 *     key: array {
 *         a: int
 *     }
 * } $arr
 * @return int
 */
function foo($arr) {
    /** @psalm-trace $a */
    $a  = $arr['key']['a'];
    return $a;
}

Psalm output (using commit 8fe1f15):

INFO: MixedArrayAccess - 14:11 - Cannot access array value on mixed variable $arr

INFO: MixedArrayAccess - 14:11 - Cannot access array value on mixed variable $arr['key']

INFO: MixedAssignment - 14:5 - Unable to determine the type that $a is being assigned to

INFO: Trace - 14:5 - $a: mixed

INFO: MixedReturnStatement - 15:12 - Could not infer a return type

INFO: MissingParamType - 12:14 - Parameter $arr has no provided type

INFO: MixedInferredReturnType - 10:12 - Could not verify return type 'int' for foo

[orklah]

I'm not actually sure why Psalm is upset here. it comes from the phpunit plugin. Can you document the provider as returning iterable<array<mixed>>? That should make it happy

[weirdan]

I'm not actually sure why Psalm is upset here

Because if you return [1, 2, 3] from a data provider, it won't work. The bare minimum is iterable of arrays, but, of course, it would be better to see iterable of tuples/maps where every element has a known type. The PHPUnit plugin would then check those types against the function parameters of consuming tests.

[rhertogh]

@orklah Return type specification is added.

[orklah]

oh, sorry, can you replace with iterable<array-key, array<mixed>>? forgot iterable could have different keys types

[rhertogh]

@orklah Updated

[rhertogh]

@orklah 3rd attempt with @return iterable<array-key, array{doc_line: string, expected: string[]}>.
Locally psalm doesn't show warnings when using this format.

[orklah]

Seems good now!

Thanks!