Add type specifier for Drupal\Component\Assertion\Inspector

[mglaman]

Backport of #826

[mglaman]

@Niklan I'm backporting this to 1.x, but there are two failures. I think it might just be a difference in PHPStan 1.0 and 2.0 but wanted your feedback before adjusting the tests

// Inspector::assertAllArrays()
$input = mixed_function();
\assert(Inspector::assertAllArrays($input));
assertType('iterable<array<mixed, mixed>>', $input);

Failed asserting that two strings are identical.
Expected :'iterable<array<mixed, mixed>>'
Actual   :'iterable<array>'

// Inspector::assertAllHaveKey()
$input = mixed_function();
assert(Inspector::assertAllHaveKey($input, 'foo', 'baz'));
assertType("array<mixed, array<hasOffset('baz')&hasOffset('foo'), mixed>>", $input);

Expected :'array<mixed, array<hasOffset('baz')&hasOffset('foo'), mixed>>'
Actual   :'array<array<hasOffset('baz')&hasOffset('foo'), mixed>>'

[Niklan]

@mglaman I did some testing locally. The API from PHPStan is the same, and it dumps the type internally properly:

^ PHPStan\Type\ArrayType^ {#19170
  -itemType: PHPStan\Type\MixedType^ {#19338
    -isExplicitMixed: true
    -subtractedType: null
  }
  -keyType: PHPStan\Type\MixedType^ {#19229
    -isExplicitMixed: true
    -subtractedType: null
  }
}

PHPStan v1 appears to treat mixed types as insufficiently specific in certain scenarios. Specifically, when mixed is the sole subtype (e.g., in array<mixed, mixed>) or when it's not part of an enumeration as in assertAllHaveKey(), PHPStan v1 simply omits it from the resolved type.

I think it it safe to change those assertions for v1 to:

// Inspector::assertAllArrays()
$input = mixed_function();
\assert(Inspector::assertAllArrays($input));
assertType('iterable<array>', $input);

and

// Inspector::assertAllHaveKey()
$input = mixed_function();
assert(Inspector::assertAllHaveKey($input, 'foo', 'baz'));
assertType("array<array<hasOffset('baz')&hasOffset('foo'), mixed>>", $input);

The tests are passing this way, but I think it will create some noise when projects update to Drupal 11.2+ and PHPStan v2 becomes available, because it will detect mixed. But I don't think we can do anything here, because it looks like a limitation for PHPStan v1, such as its inability to handle arguments with a reference, which leads to weird reports, but it is fine in v2.

[mglaman]

Thank you @Niklan for confirming!