bug(analyzer): infering and binding template parameters

[norberttech]

🐞 Describe the Bug

I think mago should infer template type parameters from actual function arguments.

When calling a generic function with a concrete type argument (e.g., Type<array<string, string>>), mago does not bind the template parameters and instead reports a type mismatch.

Expected behavior:
Mago should infer that TKey = string and TValue = string from the Type<array<string, string>> argument and validate the types match (which they do).

Actual behavior:
Mago leaves template parameters unbound and reports a type error.

🔄 Steps to Reproduce

1. Checkout branch from 1892 replace php cs fixer and rector with mago linter formatter flow-php/flow#1894
2. Run ./tools/mago/vendor/bin/mago analyze --reporting-format=short --minimum-report-level=error

⚙️ Configuration (mago.toml)

php-version = "8.2.0"

[source]
paths = [
    "src/adapter/etl-adapter-avro/src/Flow",
    "src/adapter/etl-adapter-avro/tests/Flow",
    "src/adapter/etl-adapter-chartjs/src/Flow",
    "src/adapter/etl-adapter-chartjs/tests/Flow",
    "src/adapter/etl-adapter-csv/src/Flow",
    "src/adapter/etl-adapter-csv/tests/Flow",
    "src/adapter/etl-adapter-doctrine/src/Flow",
    "src/adapter/etl-adapter-doctrine/tests/Flow",
    "src/adapter/etl-adapter-elasticsearch/src/Flow",
    "src/adapter/etl-adapter-elasticsearch/tests/Flow",
    "src/adapter/etl-adapter-excel/src/Flow",
    "src/adapter/etl-adapter-excel/tests/Flow",
    "src/adapter/etl-adapter-google-sheet/src/Flow",
    "src/adapter/etl-adapter-google-sheet/tests/Flow",
    "src/adapter/etl-adapter-http/src/Flow",
    "src/adapter/etl-adapter-http/tests/Flow",
    "src/adapter/etl-adapter-json/src/Flow",
    "src/adapter/etl-adapter-json/tests/Flow",
    "src/adapter/etl-adapter-logger/src/Flow",
    "src/adapter/etl-adapter-logger/tests/Flow",
    "src/adapter/etl-adapter-meilisearch/src/Flow",
    "src/adapter/etl-adapter-meilisearch/tests/Flow",
    "src/adapter/etl-adapter-parquet/src/Flow",
    "src/adapter/etl-adapter-parquet/tests/Flow",
    "src/adapter/etl-adapter-text/src/Flow",
    "src/adapter/etl-adapter-text/tests/Flow",
    "src/adapter/etl-adapter-xml/src/Flow",
    "src/adapter/etl-adapter-xml/tests/Flow",
    "src/bridge/filesystem/async-aws/src/Flow",
    "src/bridge/filesystem/async-aws/tests/Flow",
    "src/bridge/filesystem/azure/src/Flow",
    "src/bridge/filesystem/azure/tests/Flow",
    "src/bridge/monolog/http/src/Flow",
    "src/bridge/monolog/http/tests/Flow",
    "src/bridge/openapi/specification/src/Flow",
    "src/bridge/openapi/specification/tests/Flow",
    "src/bridge/symfony/http-foundation/src/Flow",
    "src/bridge/symfony/http-foundation/tests/Flow",
    "src/cli/src/Flow",
    "src/cli/tests/Flow",
    "src/core/etl/src/Flow",
    "src/core/etl/tests/Flow",
    "src/lib/array-dot/src/Flow",
    "src/lib/array-dot/tests/Flow",
    "src/lib/azure-sdk/src/Flow",
    "src/lib/azure-sdk/tests/Flow",
    "src/lib/doctrine-dbal-bulk/src/Flow",
    "src/lib/doctrine-dbal-bulk/tests/Flow",
    "src/lib/dremel/src/Flow",
    "src/lib/dremel/tests/Flow",
    "src/lib/filesystem/src/Flow",
    "src/lib/filesystem/tests/Flow",
    "src/lib/parquet-viewer/src/Flow",
    "src/lib/parquet-viewer/tests/Flow",
    "src/lib/parquet/src/Flow",
    "src/lib/parquet/tests/Flow",
    "src/lib/snappy/src/Flow",
    "src/lib/snappy/tests/Flow",
    "src/lib/types/src/Flow",
    "src/lib/types/tests/Flow",
    "src/tools/documentation/src/Flow",
    "src/tools/documentation/tests/Flow"
]
includes = [
    "vendor",
    "tools/phpunit/vendor"
]
excludes = [
    "src/lib/parquet/src/Flow/Parquet/ThriftModel"
]

📜 Command Output

Error message:

  src/core/etl/tests/Flow/ETL/Tests/Unit/Row/Entry/MapEntryTest.php:143:53: error[invalid-argument]: Invalid argument type for argument #3 of `Flow\ETL\DSL\map_entry`: expected `Flow\Types\Type<array<('TKey.flow\etl\dsl\map_entry() extends array-key), ('TValue.flow\etl\dsl\map_entry() extends
  mixed)>>`, but found `Flow\Types\Type<array<string, string>>`.

📂 PHP Code Sample (If Applicable)

<?php

  declare(strict_types=1);

  /**
   * @template T
   */
  interface Type
  {
      /** @param T $value */
      public function isValid(mixed $value): bool;
  }

  /**
   * @template TKey of array-key
   * @template TValue
   *
   * @param ?array<array-key, mixed> $value
   * @param Type<array<TKey, TValue>> $mapType
   *
   * @return Entry<?array<TKey, TValue>>
   */
  function map_entry(string $name, ?array $value, Type $mapType): Entry
  {
      return new MapEntry($name, $value, $mapType);
  }

  /**
   * @template TKey of array-key
   * @template TValue
   * @return Type<array<TKey, TValue>>
   */
  function type_map(Type $keyType, Type $valueType): Type
  {
      // Implementation
  }
  
  /**
   * @return Type<string>
   */
  function type_string(): Type
  {
      // Implementation
  }


I think mago should infer `TKey=string, TValue=string`
from the `type_map(type_string(), type_string())` argument


(map_entry('strings', ['one' => 'two'], type_map(type_string(), type_string())))->value()

🖥️ Operating System

macOS

📦 How did you install Mago?

Composer (composer require carthage-software/mago)

📝 Additional Context

PHPStan (level 9) handles this pattern without errors.

[azjezz]

type_map function is missing @param to specify type generics. adding those makes the issue clearer.

It seems Psalm also suffers from the same problem: https://psalm.dev/r/46799e68e5

[norberttech]

type_map function is missing @param to specify type generics. adding those makes the issue clearer.

It seems Psalm also suffers from the same problem: https://psalm.dev/r/46799e68e5

I think I didn't reproduce this issue properly.
Here is code litraly taken from Flow codebase that phpstan is fine with:

TypeInterface

/**
 * @template-covariant T
 */
interface Type
{
    /**
     * Checks if the value is of the type of this object.
     * When isValid method is used, it will not narrow the type of the value for static analysis tools.
     *
     * @phpstan-assert-if-true T $value
     */
    public function isValid(mixed $value) : bool;
}

MapType

<?php

declare(strict_types=1);

namespace Flow\Types\Type\Logical;

/**
 * @template TKey of array-key
 * @template TValue
 *
 * @implements Type<array<TKey, TValue>>
 */
final readonly class MapType implements Type
{
    /**
     * @param Type<TKey> $key
     * @param Type<TValue> $value
     */
    public function __construct(private Type $key, private Type $value)
    {
    }
}

[type_map dsl function[(https://github.com/flow-php/flow/blob/1.x/src/lib/types/src/Flow/Types/DSL/functions.php#L207)

/**
 * @template TKey of array-key
 * @template TValue
 *
 * @param Type<TKey> $key_type
 * @param Type<TValue> $value_type
 *
 * @return Type<array<TKey, TValue>>
 */
#[DocumentationDSL(module: Module::TYPES, type: DSLType::TYPE)]
function type_map(Type $key_type, Type $value_type) : Type
{
    return new MapType($key_type, $value_type);
}

StringType

/**
 * @implements Type<string>
 */
final readonly class StringType implements Type
{
}

type_string dsl

/**
 * @return Type<string>
 */
#[DocumentationDSL(module: Module::TYPES, type: DSLType::TYPE)]
function type_string() : Type
{
    return new StringType();
}

MapEntry

/**
 * @template TKey of array-key
 * @template TValue
 *
 * @implements Entry<?array<TKey, TValue>>
 */
final class MapEntry implements Entry
{
    use EntryRef;

    private Metadata $metadata;

    /**
     * @var Type<array<TKey, TValue>>
     */
    private Type $type;

    /**
     * @param ?array<array-key, mixed> $value
     * @param Type<array<TKey, TValue>> $type
     *
     * @throws InvalidArgumentException
     */
    public function __construct(
        private readonly string $name,
        private readonly ?array $value,
        Type $type,
        ?Metadata $metadata = null,
    ) {}
}

test that mago complains about

    public function test_rename() : void
    {
        self::assertEquals(
            (map_entry('new_name', ['one', 'two', 'three'], type_map(type_integer(), type_string()))),
            (map_entry('strings', ['one', 'two', 'three'], type_map(type_integer(), type_string())))->rename('new_name')
        );
    }

Mago reports eror on (map_entry('strings', ['one', 'two', 'three'], type_map(type_integer(), type_string())))->rename('new_name') while phpstan is ok

[norberttech]

Output of

\PHPStan\dumpType(map_entry('strings', ['one', 'two', 'three'], type_map(type_integer(), type_string()))->rename('new_name'));

 ------ ---------------------------------------------------------- 
  Line   type_array.php                                            
 ------ ---------------------------------------------------------- 
  10     Dumped type: Flow\ETL\Row\Entry<array<int, string>|null>  
         at type_array.php:10                                      
 ------ ---------------------------------------------------------- 

[azjezz]

@norberttech can you verify that main branch solves the issue?

[norberttech]

"carthage-software/mago": "dev-main"

Not really, the same errors in the same places:

src/core/etl/tests/Flow/ETL/Tests/Unit/Row/Entry/MapEntryTest.php:114:61: error[invalid-argument]: Invalid argument type for argument #3 of `Flow\ETL\DSL\map_entry`: expected `Flow\Types\Type<array<('TKey.flow\etl\dsl\map_entry() extends array-key), ('TValue.flow\etl\dsl\map_entry() extends mixed)>>`, but found `Flow\Types\Type<array<int, string>>`.
src/core/etl/tests/Flow/ETL/Tests/Unit/Row/Entry/MapEntryTest.php:115:60: error[invalid-argument]: Invalid argument type for argument #3 of `Flow\ETL\DSL\map_entry`: expected `Flow\Types\Type<array<('TKey.flow\etl\dsl\map_entry() extends array-key), ('TValue.flow\etl\dsl\map_entry() extends mixed)>>`, but found `Flow\Types\Type<array<int, string>>`.
src/core/etl/tests/Flow/ETL/Tests/Unit/Row/Entry/MapEntryTest.php:123:60: error[invalid-argument]: Invalid argument type for argument #3 of `Flow\ETL\DSL\map_entry`: expected `Flow\Types\Type<array<('TKey.flow\etl\dsl\map_entry() extends array-key), ('TValue.flow\etl\dsl\map_entry() extends mixed)>>`, but found `Flow\Types\Type<array<int, string>>`.
src/core/etl/tests/Flow/ETL/Tests/Unit/Row/Entry/MapEntryTest.php:131:60: error[invalid-argument]: Invalid argument type for argument #3 of `Flow\ETL\DSL\map_entry`: expected `Flow\Types\Type<array<('TKey.flow\etl\dsl\map_entry() extends array-key), ('TValue.flow\etl\dsl\map_entry() extends mixed)>>`, but found `Flow\Types\Type<array<int, string>>`.
src/core/etl/tests/Flow/ETL/Tests/Unit/Row/Entry/MapEntryTest.php:139:60: error[invalid-argument]: Invalid argument type for argument #3 of `Flow\ETL\DSL\map_entry`: expected `Flow\Types\Type<array<('TKey.flow\etl\dsl\map_entry() extends array-key), ('TValue.flow\etl\dsl\map_entry() extends mixed)>>`, but found `Flow\Types\Type<array<int, string>>`.
src/core/etl/tests/Flow/ETL/Tests/Unit/Row/Entry/MapEntryTest.php:143:53: error[invalid-argument]: Invalid argument type for argument #3 of `Flow\ETL\DSL\map_entry`: expected `Flow\Types\Type<array<('TKey.flow\etl\dsl\map_entry() extends array-key), ('TValue.flow\etl\dsl\map_entry() extends mixed)>>`, but found `Flow\Types\Type<array<string, string>>`.