added Registry::getMapper(), getAsset() and Mapper::getAsset() return type narrowing

Author: dg

CLAUDE.md

@@ -85,6 +85,22 @@ Extensions for specific Nette packages use dedicated namespaces: `Nette\PHPStan\
 
 `AssertTypeNarrowingExtension` (`StaticMethodTypeSpecifyingExtension` + `TypeSpecifierAwareExtension`) narrows variable types after `Tester\Assert` assertion calls. Each assertion method is mapped to an equivalent PHP expression that PHPStan already understands, then delegated to `TypeSpecifier::specifyTypesInCondition()`. Supported methods: `null`, `notNull`, `true`, `false`, `truthy`, `falsey`, `same`, `notSame`, and `type` (with built-in type strings like `'string'`, `'int'`, etc. and class/interface names). Config: `extension-nette.neon`.
 
+### MapperTypeResolver (Assets)
+
+`MapperTypeResolver` is a shared service used by the three assets extensions below. It resolves mapper IDs to mapper class types from a `mapping` config using keywords (`'file'` → `FilesystemMapper`, `'vite'` → `ViteMapper`, or FQCN for custom classes), resolves asset references to asset class types based on file extension (mirroring `Helpers::createAssetFromUrl()` logic), parses qualified references (`'mapper:reference'`), and checks whether a mapper is a known type (`FilesystemMapper` or `ViteMapper`). Config: `extension-nette.neon` parameter `nette.assets.mapping`.
+
+### GetMapperReturnTypeExtension
+
+`GetMapperReturnTypeExtension` (`DynamicMethodReturnTypeExtension`) narrows return type of `Registry::getMapper()` from `Mapper` to the specific mapper class based on NEON configuration. When no argument is passed, uses `'default'` as mapper ID (matching the method's default parameter). Falls back to declared return type for unknown mapper IDs. Config: `extension-nette.neon`.
+
+### MapperGetAssetExtension
+
+`MapperGetAssetExtension` (`DynamicMethodReturnTypeExtension`) narrows return type of `FilesystemMapper::getAsset()` and `ViteMapper::getAsset()` from `Asset` to the specific asset class based on file extension (e.g. `.jpg` → `ImageAsset`, `.js` → `ScriptAsset`). Single class registered twice in NEON with different `className` argument. For ViteMapper, `.js` narrows to `ScriptAsset` (safe because `EntryAsset extends ScriptAsset`). Config: `extension-nette.neon`.
+
+### RegistryGetAssetExtension
+
+`RegistryGetAssetExtension` (`DynamicMethodReturnTypeExtension`) narrows return types of `Registry::getAsset()` and `Registry::tryGetAsset()` from `Asset`/`?Asset` to specific asset class. Parses the qualified reference to extract mapper ID and asset path, checks if the mapper is a known type (`FilesystemMapper` or `ViteMapper`), then resolves asset type from file extension. For `tryGetAsset()`, adds `|null` via `TypeCombinator::addNull()`. Only narrows for string references; array references fall back to declared type. Config: `extension-nette.neon`.
+
 ### TableRowTypeResolver
 
 `TableRowTypeResolver` is a shared service used by the three database extensions below. It resolves database table names to entity row class types using a configurable convention mask (e.g. `App\Entity\*Row` where `*` is replaced by PascalCase table name) and optional explicit table-to-class overrides. Checks class existence via `ReflectionProvider`. Config: `extension-nette.neon` parameters `nette.database.mapping.convention` and `nette.database.mapping.tables`.

composer.json

@@ -16,6 +16,7 @@
 		"phpstan/phpstan": "^2.1.40"
 	},
 	"require-dev": {
+		"nette/assets": "^1.0",
 		"nette/component-model": "^3.1",
 		"nette/database": "^3.2",
 		"nette/forms": "^3.2",

extension-nette.neon

@@ -7,6 +7,8 @@ parameters:
 		- Nette\Utils\Html
 
 	nette:
+		assets:
+			mapping: []
 		database:
 			mapping:
 				convention: ''
@@ -15,6 +17,9 @@ parameters:
 
 parametersSchema:
 	nette: structure([
+		assets: structure([
+			mapping: arrayOf(string())
+		])
 		database: structure([
 			mapping: structure([
 				convention: string()
@@ -25,6 +30,29 @@ parametersSchema:
 
 
 services:
+	# nette/assets
+	nette.assets.mapperTypeResolver:
+		class: Nette\PHPStan\Assets\MapperTypeResolver
+		arguments:
+			mapping: %nette.assets.mapping%
+
+	-
+		class: Nette\PHPStan\Assets\GetMapperReturnTypeExtension
+		tags: [phpstan.broker.dynamicMethodReturnTypeExtension]
+	-
+		class: Nette\PHPStan\Assets\MapperGetAssetExtension
+		arguments:
+			className: Nette\Assets\FilesystemMapper
+		tags: [phpstan.broker.dynamicMethodReturnTypeExtension]
+	-
+		class: Nette\PHPStan\Assets\MapperGetAssetExtension
+		arguments:
+			className: Nette\Assets\ViteMapper
+		tags: [phpstan.broker.dynamicMethodReturnTypeExtension]
+	-
+		class: Nette\PHPStan\Assets\RegistryGetAssetExtension
+		tags: [phpstan.broker.dynamicMethodReturnTypeExtension]
+
 	# nette/component-model
 	-
 		class: Nette\PHPStan\ComponentModel\GetComponentReturnTypeExtension

readme.md

@@ -55,6 +55,19 @@ parameters:
                     special_table: App\Entity\SpecialRow
 ```
 
+**Asset type narrowing** — narrows return types of `Registry::getMapper()` to the specific mapper class, and `Registry::getAsset()` / `tryGetAsset()` to the specific asset type (e.g. `ImageAsset`, `ScriptAsset`) based on file extension. Also narrows `FilesystemMapper::getAsset()` and `ViteMapper::getAsset()` directly. Configure via:
+
+```neon
+parameters:
+    nette:
+        assets:
+            mapping:
+                default: file                   # FilesystemMapper
+                images: file                    # FilesystemMapper
+                vite: vite                      # ViteMapper
+                custom: App\MyMapper            # custom class (FQCN)
+```
+
 **Html magic methods** — resolves `$html->getXxx()`, `setXxx()`, and `addXxx()` calls on `Nette\Utils\Html` that go through `__call()` but aren't declared via `@method` annotations.
 
 **Removes `|false` and `|null` from PHP functions** — many native functions like `getcwd`, `json_encode`, `preg_split`, `preg_replace`, and [many more](extension-php.neon) include `false` or `null` in their return type even though these error values are unrealistic on modern systems.

src/Assets/GetMapperReturnTypeExtension.php

@@ -0,0 +1,56 @@
+<?php declare(strict_types=1);
+
+namespace Nette\PHPStan\Assets;
+
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Type;
+use function count;
+
+
+/**
+ * Narrows return type of Registry::getMapper() from Mapper
+ * to the specific mapper class based on NEON configuration.
+ */
+class GetMapperReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+	public function __construct(
+		private MapperTypeResolver $resolver,
+	) {
+	}
+
+
+	public function getClass(): string
+	{
+		return 'Nette\Assets\Registry';
+	}
+
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return $methodReflection->getName() === 'getMapper';
+	}
+
+
+	public function getTypeFromMethodCall(
+		MethodReflection $methodReflection,
+		MethodCall $methodCall,
+		Scope $scope,
+	): ?Type
+	{
+		$args = $methodCall->getArgs();
+		if ($args === []) {
+			return $this->resolver->resolveMapper('default');
+		}
+
+		$idType = $scope->getType($args[0]->value);
+		$constantStrings = $idType->getConstantStrings();
+		if (count($constantStrings) !== 1) {
+			return null;
+		}
+
+		return $this->resolver->resolveMapper($constantStrings[0]->getValue());
+	}
+}

src/Assets/MapperGetAssetExtension.php

@@ -0,0 +1,61 @@
+<?php declare(strict_types=1);
+
+namespace Nette\PHPStan\Assets;
+
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Type;
+use function count;
+
+
+/**
+ * Narrows return type of FilesystemMapper::getAsset() and ViteMapper::getAsset()
+ * from Asset to the specific asset class based on file extension.
+ * Registered twice in NEON — once per mapper class.
+ */
+class MapperGetAssetExtension implements DynamicMethodReturnTypeExtension
+{
+	/**
+	 * @param class-string $className
+	 */
+	public function __construct(
+		private MapperTypeResolver $resolver,
+		private string $className,
+	) {
+	}
+
+
+	public function getClass(): string
+	{
+		return $this->className;
+	}
+
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return $methodReflection->getName() === 'getAsset';
+	}
+
+
+	public function getTypeFromMethodCall(
+		MethodReflection $methodReflection,
+		MethodCall $methodCall,
+		Scope $scope,
+	): ?Type
+	{
+		$args = $methodCall->getArgs();
+		if ($args === []) {
+			return null;
+		}
+
+		$refType = $scope->getType($args[0]->value);
+		$constantStrings = $refType->getConstantStrings();
+		if (count($constantStrings) !== 1) {
+			return null;
+		}
+
+		return $this->resolver->resolveAssetType($constantStrings[0]->getValue());
+	}
+}

src/Assets/MapperTypeResolver.php

@@ -0,0 +1,132 @@
+<?php declare(strict_types=1);
+
+namespace Nette\PHPStan\Assets;
+
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Type\ObjectType;
+use function pathinfo, strpos, strtolower, substr;
+
+
+/**
+ * Resolves mapper IDs to mapper class types and asset references to asset class types.
+ * Mapper IDs are resolved from a flat map configured in NEON.
+ * Asset types are resolved from file extensions using hardcoded mapping mirroring Helpers::createAssetFromUrl().
+ */
+class MapperTypeResolver
+{
+	private const ExtensionToAssetClass = [
+		'avif' => 'Nette\Assets\ImageAsset',
+		'gif' => 'Nette\Assets\ImageAsset',
+		'ico' => 'Nette\Assets\ImageAsset',
+		'jpeg' => 'Nette\Assets\ImageAsset',
+		'jpg' => 'Nette\Assets\ImageAsset',
+		'png' => 'Nette\Assets\ImageAsset',
+		'svg' => 'Nette\Assets\ImageAsset',
+		'webp' => 'Nette\Assets\ImageAsset',
+		'js' => 'Nette\Assets\ScriptAsset',
+		'mjs' => 'Nette\Assets\ScriptAsset',
+		'css' => 'Nette\Assets\StyleAsset',
+		'aac' => 'Nette\Assets\AudioAsset',
+		'flac' => 'Nette\Assets\AudioAsset',
+		'm4a' => 'Nette\Assets\AudioAsset',
+		'mp3' => 'Nette\Assets\AudioAsset',
+		'ogg' => 'Nette\Assets\AudioAsset',
+		'wav' => 'Nette\Assets\AudioAsset',
+		'avi' => 'Nette\Assets\VideoAsset',
+		'mkv' => 'Nette\Assets\VideoAsset',
+		'mov' => 'Nette\Assets\VideoAsset',
+		'mp4' => 'Nette\Assets\VideoAsset',
+		'ogv' => 'Nette\Assets\VideoAsset',
+		'webm' => 'Nette\Assets\VideoAsset',
+		'woff' => 'Nette\Assets\FontAsset',
+		'woff2' => 'Nette\Assets\FontAsset',
+		'ttf' => 'Nette\Assets\FontAsset',
+	];
+
+	private const KnownMappers = [
+		'Nette\Assets\FilesystemMapper',
+		'Nette\Assets\ViteMapper',
+	];
+
+
+	/**
+	 * @param array<string, string> $mapping mapper ID → type keyword ('file', 'vite') or FQCN
+	 */
+	public function __construct(
+		private ReflectionProvider $reflectionProvider,
+		private array $mapping = [],
+	) {
+	}
+
+
+	/**
+	 * Resolves a mapper ID to an ObjectType for the mapper class.
+	 */
+	public function resolveMapper(string $mapperId): ?ObjectType
+	{
+		if (!isset($this->mapping[$mapperId])) {
+			return null;
+		}
+
+		$className = $this->inferMapperClass($this->mapping[$mapperId]);
+		return $this->reflectionProvider->hasClass($className)
+			? new ObjectType($className)
+			: null;
+	}
+
+
+	private function inferMapperClass(string $value): string
+	{
+		return match ($value) {
+			'file' => 'Nette\Assets\FilesystemMapper',
+			'vite' => 'Nette\Assets\ViteMapper',
+			default => $value,
+		};
+	}
+
+
+	/**
+	 * Checks whether the mapper for a given ID is a known mapper type
+	 * (FilesystemMapper or ViteMapper) whose asset types can be narrowed.
+	 */
+	public function isKnownMapper(string $mapperId): bool
+	{
+		$mapperType = $this->resolveMapper($mapperId);
+		if ($mapperType === null) {
+			return false;
+		}
+
+		foreach (self::KnownMappers as $knownClass) {
+			if ((new ObjectType($knownClass))->isSuperTypeOf($mapperType)->yes()) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+
+	/**
+	 * Resolves an asset reference to an ObjectType based on its file extension.
+	 */
+	public function resolveAssetType(string $reference): ?ObjectType
+	{
+		$extension = strtolower(pathinfo($reference, PATHINFO_EXTENSION));
+		return isset(self::ExtensionToAssetClass[$extension])
+			? new ObjectType(self::ExtensionToAssetClass[$extension])
+			: null;
+	}
+
+
+	/**
+	 * Splits a qualified reference 'mapper:reference' into [mapperId, assetPath].
+	 * @return array{string, string}
+	 */
+	public function parseReference(string $ref): array
+	{
+		$pos = strpos($ref, ':');
+		return $pos !== false
+			? [substr($ref, 0, $pos), substr($ref, $pos + 1)]
+			: ['default', $ref];
+	}
+}