feat(analyzer): add a method return type provider for UnitEnum::cases() method

closes #735

Signed-off-by: azjezz <[email protected]>

Author: azjezz

crates/analyzer/src/plugin/libraries/mod.rs

@@ -18,6 +18,7 @@ pub fn register_library_providers(registry: &mut PluginRegistry) {
     registry.register_function_provider(stdlib::array::ArrayMergeProvider);
     registry.register_function_provider(stdlib::array::CompactProvider);
     registry.register_method_provider(stdlib::closure::ClosureGetCurrentProvider);
+    registry.register_method_provider(stdlib::r#enum::EnumCasesProvider);
 
     registry.register_function_provider(psl::type_::ShapeProvider);
     registry.register_function_provider(psl::type_::OptionalProvider);

crates/analyzer/src/plugin/libraries/stdlib/enum/cases.rs

@@ -0,0 +1,65 @@
+//! UnitEnum::cases() return type provider.
+
+use mago_codex::ttype::atomic::TAtomic;
+use mago_codex::ttype::atomic::array::TArray;
+use mago_codex::ttype::atomic::array::list::TList;
+use mago_codex::ttype::atomic::object::TObject;
+use mago_codex::ttype::atomic::object::r#enum::TEnum;
+use mago_codex::ttype::union::TUnion;
+
+use crate::plugin::context::InvocationInfo;
+use crate::plugin::context::ProviderContext;
+use crate::plugin::provider::Provider;
+use crate::plugin::provider::ProviderMeta;
+use crate::plugin::provider::method::MethodReturnTypeProvider;
+use crate::plugin::provider::method::MethodTarget;
+
+static META: ProviderMeta =
+    ProviderMeta::new("php::enum::cases", "UnitEnum::cases", "Returns non-empty-list for enums with at least one case");
+
+// Use wildcard for class since all enums implement UnitEnum
+static TARGETS: [MethodTarget; 1] = [MethodTarget::any_class("cases")];
+
+/// Provider for the `UnitEnum::cases()` method.
+///
+/// Returns `non-empty-list<EnumType>` for enums with at least one case,
+/// or `list<EnumType>` for enums with no cases (edge case).
+#[derive(Default)]
+pub struct EnumCasesProvider;
+
+impl Provider for EnumCasesProvider {
+    fn meta() -> &'static ProviderMeta {
+        &META
+    }
+}
+
+impl MethodReturnTypeProvider for EnumCasesProvider {
+    fn targets() -> &'static [MethodTarget] {
+        &TARGETS
+    }
+
+    fn get_return_type(
+        &self,
+        _context: &ProviderContext<'_, '_, '_>,
+        _class_name: &str,
+        _method_name: &str,
+        invocation_info: &InvocationInfo<'_, '_, '_>,
+    ) -> Option<TUnion> {
+        let class_metadata = invocation_info.invocation.target.get_method_context()?.class_like_metadata;
+
+        if !class_metadata.kind.is_enum() {
+            return None;
+        }
+
+        let enum_type = TUnion::from_atomic(TAtomic::Object(TObject::Enum(TEnum {
+            name: class_metadata.original_name,
+            case: None,
+        })));
+
+        if !class_metadata.enum_cases.is_empty() {
+            Some(TUnion::from_atomic(TAtomic::Array(TArray::List(TList::new_non_empty(Box::new(enum_type))))))
+        } else {
+            Some(TUnion::from_atomic(TAtomic::Array(TArray::List(TList::new(Box::new(enum_type))))))
+        }
+    }
+}

crates/analyzer/src/plugin/libraries/stdlib/enum/mod.rs

@@ -0,0 +1,5 @@
+//! PHP Enum method providers.
+
+mod cases;
+
+pub use cases::EnumCasesProvider;

crates/analyzer/src/plugin/libraries/stdlib/mod.rs

@@ -2,6 +2,7 @@
 
 pub mod array;
 pub mod closure;
+pub mod r#enum;
 pub mod json;
 pub mod random;
 pub mod spl;

crates/analyzer/tests/cases/issue_735.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @param non-empty-list $choices
+ */
+function countNonEmptyList(array $choices): int
+{
+    return count($choices);
+}
+
+enum MyCases: string
+{
+    case FIRST = 'first';
+    case SECOND = 'second';
+    case THIRD = 'third';
+}
+
+countNonEmptyList(MyCases::cases());

crates/analyzer/tests/mod.rs

@@ -443,6 +443,7 @@ test_case!(issue_728_symfony_reference);
 test_case!(issue_729);
 test_case!(issue_731);
 test_case!(issue_733);
+test_case!(issue_735);
 test_case!(issue_736);
 test_case!(issue_737);
 test_case!(issue_739);