Skip extends-annotation generation when parent class isn't generic

The extends-emission path in ModelAnnotator::addBehaviorExtends()
unconditionally writes a generic extends-annotation pointing at the
parent (with the behavior-array and entity-type templates) for every
table whose parent has a behavior list or entity to project,
regardless of whether the parent class actually declares any template
of its own. When the parent isn't generic — e.g.
Ratings\Model\Table\RatingsTable from dereuromark/cakephp-ratings —
this produces an annotation that PHPStan correctly rejects with the
generics.notGeneric error, breaking the consumer's build until the
line is removed by hand.

Gate the emission on a new parentSupportsGenerics() helper:

- Cake\ORM\Table (long-standing TBehaviors template, plus TEntity
  template from 5.3.4) is treated as generic unconditionally.
- Any other parent is reflected and considered generic iff its own
  docblock declares a template tag of its own — inheriting from a
  generic ancestor without re-declaring the template doesn't make
  the subclass generic itself (PHPStan would still report
  generics.notGeneric on any consumer's extends annotation pointing
  at the subclass).
- A bare extends annotation without generic params is genuinely
  redundant with PHP's own extends clause, so non-generic parents
  get no extends-annotation line at all rather than a parameter-less
  placeholder.

The previous "protected-parent" fixture (AbstractTable — not generic)
loses its extends-annotation line in the test expectation, and the
snapshot annotation count drops accordingly. Two new focused tests
assert the two branches: non-generic custom parent emits nothing, and
Cake\ORM\Table parent still emits the extends-annotation.

Note: orphan extends-annotation lines in already-annotated files are
NOT removed automatically — the orphan-pruning pass only touches tag
types the current run also generates. Consumers need a one-time manual
cleanup, or upstreaming a template tag to their custom base class so
the annotator re-emits and replaces the line.

Author: dereuromark

src/Annotator/ModelAnnotator.php

@@ -593,13 +593,51 @@ protected function addBehaviorExtends(array $result, array $behaviors, string $p
 		if (!$parentClass) {
 			$parentClass = '\\Cake\\ORM\\Table';
 		}
+		if (!$this->parentSupportsGenerics($parentClass)) {
+			// A bare `@extends` adds no information beyond PHP's own `extends` clause,
+			// and emitting `@extends NonGenericParent<...>` would trigger PHPStan's
+			// `generics.notGeneric` error on every consumer.
+			return $result;
+		}
 		// Prepend so @extends sits at the top of the class doc-block, matching the
 		// classOrder defined by php-collective/code-sniffer DocBlockTagOrderSniff.
 		array_unshift($result, AnnotationFactory::createOrFail(ExtendsAnnotation::TAG, '\\' . $parentClass . '<array{' . $list . '}' . $entityTemplate . '>'));
 
 		return $result;
 	}
 
+	/**
+	 * Whether the given parent class declares template parameters and can therefore
+	 * be parameterized via `@extends`.
+	 *
+	 * A class is generic iff its own docblock contains an `@template` tag — inheriting
+	 * from a generic parent without declaring `@template` on the subclass does NOT
+	 * make the subclass generic (PHPStan would report `generics.notGeneric` for any
+	 * `@extends Subclass<...>` annotation in consumers).
+	 *
+	 * @param string $parentClass
+	 * @return bool
+	 */
+	protected function parentSupportsGenerics(string $parentClass): bool {
+		if ($parentClass === '' || ltrim($parentClass, '\\') === Table::class) {
+			// `\Cake\ORM\Table` declares `@template TBehaviors` (long-standing) and
+			// `@template TEntity` (from 5.3.4). Either makes the parent generic.
+			return true;
+		}
+
+		$fqcn = ltrim($parentClass, '\\');
+		if (!class_exists($fqcn)) {
+			return false;
+		}
+
+		$doc = (new ReflectionClass($fqcn))->getDocComment();
+		if ($doc === false) {
+			return false;
+		}
+
+		return preg_match('/^\s*\*\s*@template\s/m', $doc) === 1;
+	}
+
 	/**
 	 * Whether `\Cake\ORM\Table` declares a second `TEntity` template parameter.
 	 *

tests/TestCase/Annotator/ModelAnnotatorTest.php

@@ -339,7 +339,7 @@ public function testAnnotateProtectedParent() {
 		$annotator->annotate($path);
 
 		$output = $this->out->output();
-		$this->assertTextContains('  -> 18 annotations added', $output);
+		$this->assertTextContains('  -> 17 annotations added', $output);
 	}
 
 	/**
@@ -494,6 +494,56 @@ public function testAnnotateWithEntityTemplateKeepsOverridesForCustomParent() {
 		$this->assertStringContainsString('patchEntity(', $capture);
 	}
 
+	/**
+	 * Regression: when the parent base table declares no `@template` of its own
+	 * (i.e. is not a generic class), emitting `@extends Parent<...>` would trigger
+	 * PHPStan's `generics.notGeneric` error in every consumer. The annotation must
+	 * be skipped entirely for non-generic parents — the PHP `extends` clause is
+	 * sufficient and a bare `@extends` adds no information.
+	 *
+	 * @return void
+	 */
+	public function testAnnotateSkipsExtendsForNonGenericParent() {
+		$annotator = $this->_getEntityTemplateAnnotatorMock([]);
+
+		$capture = '';
+		$annotator->method('storeFile')
+			->with($this->anything(), $this->callback(function ($value) use (&$capture) {
+				$capture = $value;
+
+				return true;
+			}));
+
+		$annotator->annotate(APP . 'Model/Table/BarBarsAbstractTable.php');
+
+		$this->assertStringNotContainsString('@extends \TestApp\Model\Table\AbstractTable', $capture);
+		$this->assertStringNotContainsString('@extends', $capture);
+	}
+
+	/**
+	 * Regression: when the parent IS `\Cake\ORM\Table` (the canonical generic parent),
+	 * `@extends Cake\ORM\Table<...>` must still be emitted so consumers benefit from
+	 * the parent's template propagation. Guards against an over-eager skip in
+	 * `parentSupportsGenerics()`.
+	 *
+	 * @return void
+	 */
+	public function testAnnotateEmitsExtendsForGenericCakeTableParent() {
+		$annotator = $this->_getEntityTemplateAnnotatorMock([]);
+
+		$capture = '';
+		$annotator->method('storeFile')
+			->with($this->anything(), $this->callback(function ($value) use (&$capture) {
+				$capture = $value;
+
+				return true;
+			}));
+
+		$annotator->annotate(APP . 'Model/Table/BarBarsTable.php');
+
+		$this->assertStringContainsString('@extends \Cake\ORM\Table<', $capture);
+	}
+
 	/**
 	 * Regression: in `concreteEntitiesInParam` mode the `save()` and `saveOrFail()`
 	 * overrides narrow `$entity` to the concrete entity class, which the parent's

tests/test_files/Model/Table/BarBarsAbstractTable.php

@@ -2,8 +2,6 @@
 namespace TestApp\Model\Table;
 
 /**
- * @extends \TestApp\Model\Table\AbstractTable<array{MyMy: \MyNamespace\MyPlugin\Model\Behavior\MyBehavior, Timestamp: \Cake\ORM\Behavior\TimestampBehavior}>
- *
  * @property \Cake\ORM\Association\BelongsTo<\TestApp\Model\Table\FoosTable> $Foos
  * @property \Cake\ORM\Association\BelongsToMany<\Awesome\Model\Table\HousesTable> $Houses
  *