|
| 1 | +<?php |
| 2 | + |
| 3 | +declare(strict_types=1); |
| 4 | + |
| 5 | +namespace LTS\PHPQA\PHPStan\Rules; |
| 6 | + |
| 7 | +use LTS\PHPQA\PackageType\ProjectComposerTypeReader; |
| 8 | +use PhpParser\Node; |
| 9 | +use PHPStan\Analyser\Scope; |
| 10 | +use PHPStan\Node\InClassNode; |
| 11 | +use PHPStan\Reflection\ClassReflection; |
| 12 | +use PHPStan\Reflection\ReflectionProvider; |
| 13 | +use PHPStan\Rules\Rule; |
| 14 | +use PHPStan\Rules\RuleErrorBuilder; |
| 15 | +use PHPStan\Type\Type; |
| 16 | + |
| 17 | +/** |
| 18 | + * API-surface integrity (the complement to {@see RequireApiOrInternalTagRule}). |
| 19 | + * |
| 20 | + * Classifying every class-like `@api` / `@internal` is necessary but not |
| 21 | + * sufficient: the classification can still be INCOHERENT. If an `@api` class |
| 22 | + * exposes an `@internal` one through its public signature — a public method's |
| 23 | + * parameter or return type, or a public property — then a consumer using the |
| 24 | + * supported `@api` type is forced to touch the `@internal` one, and PHPStan flags |
| 25 | + * the consumer with `class.internal` / `method.internal`. The public contract has |
| 26 | + * leaked an internal type; the `@api` promise is hollow. |
| 27 | + * |
| 28 | + * This rule catches that leak at the library's own gate. For a `type: library` |
| 29 | + * project, every `@api` class-like's public surface (public-method parameter and |
| 30 | + * return types, public-property types) is scanned; referencing an `@internal` |
| 31 | + * class-like IN THE SAME PACKAGE (same root namespace segment — the boundary |
| 32 | + * PHPStan keys `@internal` on) is an error. The fix is one of: promote the |
| 33 | + * referenced type to `@api` (commit to it as public contract), or keep it off the |
| 34 | + * public surface (e.g. map it to an `@api` DTO at the boundary). |
| 35 | + * |
| 36 | + * Third-party `@internal` types (a different root namespace) are NOT flagged here |
| 37 | + * — leaking another package's internals is that package's concern, and flagging it |
| 38 | + * would punish unavoidable vendor surface. The rule no-ops for any non-library |
| 39 | + * package type. |
| 40 | + * |
| 41 | + * @implements Rule<InClassNode> |
| 42 | + */ |
| 43 | +final readonly class ApiMustNotExposeInternalRule implements Rule |
| 44 | +{ |
| 45 | + public const string IDENTIFIER = RuleIdentifierInterface::PREFIX . '.apiMustNotExposeInternal'; |
| 46 | + |
| 47 | + public function __construct( |
| 48 | + private ProjectComposerTypeReader $typeReader, |
| 49 | + private ReflectionProvider $reflectionProvider, |
| 50 | + ) { |
| 51 | + } |
| 52 | + |
| 53 | + public function getNodeType(): string |
| 54 | + { |
| 55 | + return InClassNode::class; |
| 56 | + } |
| 57 | + |
| 58 | + /** |
| 59 | + * @return list<\PHPStan\Rules\IdentifierRuleError> |
| 60 | + */ |
| 61 | + public function processNode(Node $node, Scope $scope): array |
| 62 | + { |
| 63 | + if ('library' !== $this->typeReader->effectiveType()) { |
| 64 | + return []; |
| 65 | + } |
| 66 | + |
| 67 | + $classReflection = $node->getClassReflection(); |
| 68 | + if ($classReflection->isAnonymous()) { |
| 69 | + return []; |
| 70 | + } |
| 71 | + |
| 72 | + // Only the public (@api) surface can leak; an @internal class referencing |
| 73 | + // an @internal one is fine. |
| 74 | + if (!$this->hasTag($this->docText($node->getOriginalNode()->getDocComment()), 'api')) { |
| 75 | + return []; |
| 76 | + } |
| 77 | + |
| 78 | + $className = $classReflection->getName(); |
| 79 | + $ownRoot = $this->rootSegment($className); |
| 80 | + |
| 81 | + $errors = []; |
| 82 | + $reported = []; |
| 83 | + foreach ($this->publicSurface($classReflection, $scope) as [$where, $type]) { |
| 84 | + foreach ($type->getReferencedClasses() as $referenced) { |
| 85 | + if ($referenced === $className) { |
| 86 | + continue; |
| 87 | + } |
| 88 | + |
| 89 | + if (isset($reported[$referenced])) { |
| 90 | + continue; |
| 91 | + } |
| 92 | + |
| 93 | + if ($this->rootSegment($referenced) !== $ownRoot) { |
| 94 | + continue; // only OUR OWN internals are the leak we own |
| 95 | + } |
| 96 | + |
| 97 | + if (!$this->reflectionProvider->hasClass($referenced)) { |
| 98 | + continue; |
| 99 | + } |
| 100 | + |
| 101 | + if (!$this->isInternal($this->reflectionProvider->getClass($referenced))) { |
| 102 | + continue; |
| 103 | + } |
| 104 | + |
| 105 | + $reported[$referenced] = true; |
| 106 | + $errors[] = RuleErrorBuilder::message(\sprintf( |
| 107 | + 'Class %s is @api but exposes @internal type %s through its public surface (%s). ' |
| 108 | + . 'A consumer using this @api class would be forced to touch an @internal one ' |
| 109 | + . '(PHPStan flags that as class.internal/method.internal). Either promote %s to @api ' |
| 110 | + . '(commit to it as a public contract) or keep it off the public surface ' |
| 111 | + . '(e.g. map it to an @api type at the boundary).', |
| 112 | + $className, |
| 113 | + $referenced, |
| 114 | + $where, |
| 115 | + $referenced, |
| 116 | + ))->identifier(self::IDENTIFIER)->build(); |
| 117 | + } |
| 118 | + } |
| 119 | + |
| 120 | + return $errors; |
| 121 | + } |
| 122 | + |
| 123 | + /** |
| 124 | + * Yield [where-label, type] for every type on the class's own public surface: |
| 125 | + * public-method parameter + return types (constructor included) and |
| 126 | + * public-property types. Inherited members are skipped (a parent classifies |
| 127 | + * its own surface). |
| 128 | + * |
| 129 | + * @return iterable<array{string, Type}> |
| 130 | + */ |
| 131 | + private function publicSurface(ClassReflection $classReflection, Scope $scope): iterable |
| 132 | + { |
| 133 | + $native = $classReflection->getNativeReflection(); |
| 134 | + $className = $classReflection->getName(); |
| 135 | + |
| 136 | + foreach ($native->getMethods() as $nativeMethod) { |
| 137 | + if (!$nativeMethod->isPublic()) { |
| 138 | + continue; |
| 139 | + } |
| 140 | + |
| 141 | + if ($nativeMethod->getDeclaringClass()->getName() !== $className) { |
| 142 | + continue; |
| 143 | + } |
| 144 | + |
| 145 | + $method = $classReflection->getMethod($nativeMethod->getName(), $scope); |
| 146 | + foreach ($method->getVariants() as $variant) { |
| 147 | + foreach ($variant->getParameters() as $parameter) { |
| 148 | + yield [ |
| 149 | + \sprintf('parameter $%s of method %s()', $parameter->getName(), $nativeMethod->getName()), |
| 150 | + $parameter->getType(), |
| 151 | + ]; |
| 152 | + } |
| 153 | + |
| 154 | + yield [\sprintf('return type of method %s()', $nativeMethod->getName()), $variant->getReturnType()]; |
| 155 | + } |
| 156 | + } |
| 157 | + |
| 158 | + foreach ($native->getProperties() as $nativeProperty) { |
| 159 | + if (!$nativeProperty->isPublic()) { |
| 160 | + continue; |
| 161 | + } |
| 162 | + |
| 163 | + if ($nativeProperty->getDeclaringClass()->getName() !== $className) { |
| 164 | + continue; |
| 165 | + } |
| 166 | + |
| 167 | + if (!$classReflection->hasProperty($nativeProperty->getName())) { |
| 168 | + continue; |
| 169 | + } |
| 170 | + |
| 171 | + $property = $classReflection->getProperty($nativeProperty->getName(), $scope); |
| 172 | + yield [\sprintf('property $%s', $nativeProperty->getName()), $property->getReadableType()]; |
| 173 | + } |
| 174 | + } |
| 175 | + |
| 176 | + private function isInternal(ClassReflection $classReflection): bool |
| 177 | + { |
| 178 | + return $this->hasTag($this->docText($classReflection->getNativeReflection()->getDocComment()), 'internal'); |
| 179 | + } |
| 180 | + |
| 181 | + private function rootSegment(string $fqcn): string |
| 182 | + { |
| 183 | + return explode('\\', ltrim($fqcn, '\\'))[0]; |
| 184 | + } |
| 185 | + |
| 186 | + private function docText(\PhpParser\Comment\Doc|string|false|null $docComment): string |
| 187 | + { |
| 188 | + if ($docComment instanceof \PhpParser\Comment\Doc) { |
| 189 | + return $docComment->getText(); |
| 190 | + } |
| 191 | + |
| 192 | + return \is_string($docComment) ? $docComment : ''; |
| 193 | + } |
| 194 | + |
| 195 | + /** |
| 196 | + * Matches a standalone `@api` / `@internal` PHPDoc tag, not a longer tag that |
| 197 | + * merely starts with it (e.g. `@apiNote`, `@internalRef`). |
| 198 | + */ |
| 199 | + private function hasTag(string $docText, string $tag): bool |
| 200 | + { |
| 201 | + return 1 === \Safe\preg_match('/@' . $tag . '(?![\w-])/', $docText); |
| 202 | + } |
| 203 | +} |
0 commit comments