Warn about replacing real class type with @param object $x

NEWS.md

@@ -28,6 +28,7 @@ Bug fixes:
 + Don't include both `.` and `vendor/x/y/` when initializing Phan configs with settings such as `--init --init-analyze-dir=.` (#3699)
 + Be more consistent about resolving `static` in generators and template types.
 + Infer the iterable value type for `Generator<V>`. It was previously only inferred when there were 2 or more template args in phpdoc.
++ Don't let less specific type signatures such as `@param object $x` override the real type signature of `MyClass $x` (#3749)
 
 Feb 20 2020, Phan 2.5.0
 -----------------------

src/Phan/Language/Type.php

@@ -3350,9 +3350,12 @@ public function isExclusivelyNarrowedFormOrEquivalentTo(
 
         // Test to see if this (or any ancestor types) can cast to the given union type.
         $expanded_types = $this_resolved->asExpandedTypes($code_base);
-        return $expanded_types->canCastToUnionType(
-            $union_type
-        );
+        foreach ($expanded_types->getTypeSet() as $type) {
+            if ($type->isSubtypeOfAnyTypeInSet($union_type->getTypeSet())) {
+                return true;
+            }
+        }
+        return false;
     }
 
     /**

src/Phan/Language/Type/GenericArrayType.php

@@ -877,4 +877,10 @@ public function convertIntegerKeyArrayToList(): ArrayType
         }
         return ListType::fromElementType($this->element_type, $this->is_nullable, $this->key_type);
     }
+
+    public function isSubtypeOf(Type $type): bool
+    {
+        // TODO more specific
+        return $this->canCastToType($type);
+    }
 }

tests/files/expected/0863_vaguer_type.php.expected

@@ -0,0 +1,6 @@
+%s:3 PhanTypeMismatchDeclaredParam Doc-block of $dom in vaguer_comment contains phpdoc param type object which is incompatible with the param type \DOMDocument declared in the signature
+%s:6 PhanUndeclaredMethod Call to undeclared method \DOMDocument::missingMethod
+%s:9 PhanTypeMismatchDeclaredParam Doc-block of $ao in base_class contains phpdoc param type \ArrayAccess which is incompatible with the param type \ArrayObject declared in the signature
+%s:12 PhanParamTooManyInternal Call with 1 arg(s) to \ArrayObject::count() which only takes 0 arg(s)
+%s:15 PhanTypeMismatchDeclaredParam Doc-block of $dom in wrong_comment contains phpdoc param type \stdClass which is incompatible with the param type \DOMDocument declared in the signature
+%s:18 PhanUndeclaredMethod Call to undeclared method \DOMDocument::missingMethod

tests/files/src/0863_vaguer_type.php

@@ -0,0 +1,19 @@
+<?php
+/**
+ * @param object $dom
+ */
+function vaguer_comment(DOMDocument $dom) {
+    $dom->missingMethod('test');
+}
+/**
+ * @param ArrayAccess $ao
+ */
+function base_class(ArrayObject $ao) {
+    return $ao->count('unexpected');
+}
+/**
+ * @param stdClass $dom
+ */
+function wrong_comment(DOMDocument $dom) {
+    $dom->missingMethod('test');
+}