phpstan.neon.dist

# Global ignores for fundamental framework patterns that PHPStan cannot resolve
# (Eloquent magic, generics, new static, etc.). This file is locked — new errors
# should be fixed at the source, or suppressed inline for genuine static analysis
# limitations.

parameters:
  tmpDir: .cache/phpstan
  level: 5
  parallel:
    jobSize: 20
    maximumNumberOfProcesses: 32
    minimumNumberOfJobsPerProcess: 2
  inferPrivatePropertyTypeFromConstructor: true
  treatPhpDocTypesAsCertain: false
  reportUnmatchedIgnoredErrors: false
  paths:
    - src
  scanFiles:
    - phpstan-stubs/constants.php
  excludePaths:
    - %currentWorkingDirectory%/src/helper/*
    - %currentWorkingDirectory%/tests/*
    - %currentWorkingDirectory%/src/testbench/hypervel/*
    - %currentWorkingDirectory%/src/testbench/workbench/*
    - %currentWorkingDirectory%/src/*/node_modules/*
    - %currentWorkingDirectory%/src/*/resources/views/*
    - %currentWorkingDirectory%/src/*/publish/*
    - %currentWorkingDirectory%/src/foundation/src/ComposerScripts.php
    # @TODO: Add pest to root composer.json require-dev and remove this line once Pest 5 is released (required for PHPUnit 13 support).
    - %currentWorkingDirectory%/src/testbench/src/Pest/Autoload.php
  ignoreErrors:
    # Framework traits provided for userland - not used internally but intentionally available
    - '#Trait Hypervel\\[A-Za-z\\\\]+ is used zero times and is not analysed\.#'

    # Fluent class uses magic __get/__set/__call for dynamic properties and methods (ColumnDefinition, IndexDefinition, etc.)
    - '#Access to an undefined property Hypervel\\Support\\Fluent::\$#'
    - '#Access to an undefined property Hypervel\\Database\\Schema\\ColumnDefinition::\$#'
    - '#Access to an undefined property Hypervel\\Database\\Schema\\IndexDefinition::\$#'
    - '#Access to an undefined property Hypervel\\Database\\Schema\\ForeignKeyDefinition::\$#'
    - '#Call to an undefined method Hypervel\\Support\\Fluent::#'
    - '#Call to an undefined method Hypervel\\Database\\Schema\\ColumnDefinition::#'
    - '#Call to an undefined method Hypervel\\Database\\Schema\\IndexDefinition::#'
    - '#Call to an undefined method Hypervel\\Database\\Schema\\ForeignKeyDefinition::#'
    - '#Access to an undefined property Hypervel\\Database\\Schema\\ForeignIdColumnDefinition::\$#'
    - '#Call to an undefined method Hypervel\\Database\\Schema\\ForeignIdColumnDefinition::#'

    # NodeTrait methods - mixed in at app level, not on base Model class
    - message: '#Call to an undefined method Hypervel\\Database\\Eloquent\\Model::new(ScopedQuery|NestedSetQuery)\(\)#'
      path: src/nested-set/*

    # SoftDeletes trait methods - optionally mixed in, can't be statically verified
    - '#Call to an undefined method .*::(getDeletedAtColumn|getQualifiedDeletedAtColumn|withTrashed|withoutTrashed|onlyTrashed|forceDelete|restore|trashed|isForceDeleting)\(\)#'

    # Generic template type limitations - PHPStan can't resolve methods through generic TModel/TRelatedModel
    - '#Call to an undefined method TModel of Hypervel\\Database\\Eloquent\\Model::#'
    - '#Call to an undefined method TRelatedModel of Hypervel\\Database\\Eloquent\\Model::#'
    - '#Call to an undefined method TPivotModel of Hypervel\\Database\\Eloquent\\Relations\\Pivot::#'

    # Deep generic template limitations - PHPStan can't fully resolve complex generic type relationships
    - identifier: generics.lessTypes
      path: src/database/*
    - identifier: generics.notSubtype
      path: src/database/*
    - identifier: method.templateTypeNotInParameter
      path: src/database/*

    # Covariant template types in invariant/contravariant positions - Laravel uses @template-covariant
    # for semantic documentation on collection-like classes even though it violates strict variance rules.
    # The code is functionally correct; this is a PHPStan limitation with PHP's lack of runtime generics.
    - identifier: generics.variance

    # Eloquent Relation subclass method overrides - covariance/contravariance issues with complex generics
    # (e.g., Builder<*> vs Builder<TModel>, parameter type narrowing in overrides)
    - identifier: method.childReturnType
      path: src/database/*
    - identifier: method.childParameterType
      path: src/database/*

    # Eloquent @mixin forwarding loses Eloquent\Builder type - methods forwarded via __call return Query\Builder
    # but actually return $this (Eloquent\Builder) at runtime
    - message: '#Method .* should return Hypervel\\Database\\Eloquent\\Builder<.*> but returns Hypervel\\Database\\Query\\Builder\.$#'
      path: src/database/*

    # Relation @mixin forwarding - Relation methods returning $this forward to Builder methods
    # PHPStan sees Builder return type but the actual return is $this (the Relation)
    - message: '#should return \$this\(Hypervel\\Database\\Eloquent\\Relations\\.+\) but returns Hypervel\\Database\\(Query|Eloquent)\\Builder#'
      path: src/database/*

    # Collection template covariance - specific array shapes are subtypes of array<string, mixed>
    # but Collection<TValue> is invariant, so PHPStan rejects the more specific return type
    - message: '#should return Hypervel\\Support\\Collection<.+, array<.+>> but returns Hypervel\\Support\\Collection<.+, array\{#'

    # BelongsToMany pivot intersection type - PHPDoc uses object{pivot: ...}&TRelatedModel
    # to document that models get a pivot property attached, but PHPStan can't track dynamic attachment
    - message: '#object\{pivot:#'
      path: src/database/*

    # call_user_func with void callbacks - intentional pattern in Eloquent
    - '#Result of function call_user_func \(void\) is used\.#'
    - '#Result of callable passed to call_user_func\(\) \(void\) is used\.#'

    # Laravel's fluent factory pattern (Collection::make, Model::create, etc.) relies on new static() throughout
    - '#Unsafe usage of new static#'