From 3f2082ef2e98b3080a749098a74f09b636419afd Mon Sep 17 00:00:00 2001
From: provokateurin <kate@provokateurin.de>
Date: Fri, 6 Sep 2024 09:39:13 +0200
Subject: [PATCH] build: Add psalm plugin to ensure OCP implementations have no
 doc block

Signed-off-by: provokateurin <kate@provokateurin.de>
---
 build/psalm/OcInheritDoc.php | 64 ++++++++++++++++++++++++++++++++++++
 psalm.xml                    |  1 +
 2 files changed, 65 insertions(+)
 create mode 100644 build/psalm/OcInheritDoc.php

diff --git a/build/psalm/OcInheritDoc.php b/build/psalm/OcInheritDoc.php
new file mode 100644
index 00000000000..38cc78e2e73
--- /dev/null
+++ b/build/psalm/OcInheritDoc.php
@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+use PhpParser\Node\Name;
+use PhpParser\Node\Stmt\Class_;
+use Psalm\CodeLocation;
+use Psalm\Issue\InvalidDocblock;
+use Psalm\IssueBuffer;
+use Psalm\Plugin\EventHandler\Event\AfterClassLikeVisitEvent;
+
+include __DIR__ . '/../../3rdparty/autoload.php';
+
+class OcInheritDoc implements Psalm\Plugin\EventHandler\AfterClassLikeVisitInterface {
+	public static function afterClassLikeVisit(AfterClassLikeVisitEvent $event): void {
+		$childClass = $event->getStmt();
+		$statementsSource = $event->getStatementsSource();
+
+		if (!$childClass instanceof Class_) {
+			return;
+		}
+
+		$childClassName = $childClass->getAttribute('namespacedName')?->toString() ?? '';
+		if (!str_starts_with($childClassName, 'OC\\')) {
+			return;
+		}
+
+		/** @var Name $impl */
+		foreach ($childClass->implements as $impl) {
+			$parentClassName = $impl->getAttribute('resolvedName') ?? '';
+			if ($parentClassName === 'OCP\\Capabilities\\ICapability' || $parentClassName === 'OCP\\Capabilities\\IPublicCapability' || !str_starts_with($parentClassName, 'OCP\\')) {
+				continue;
+			}
+
+			$parentClass = new ReflectionClass($parentClassName);
+			$parentMethods = $parentClass->getMethods();
+
+			foreach ($childClass->getMethods() as $childMethod) {
+				foreach ($parentMethods as $parentMethod) {
+					if (strtolower($childMethod->name->name) !== strtolower($parentMethod->name)) {
+						continue;
+					}
+
+					$doc = $childMethod->getDocComment();
+					if ($doc !== null) {
+						IssueBuffer::maybeAdd(
+							new InvalidDocblock(
+								'Docblock for OCP implementation must be empty to inherit the interface.',
+								new CodeLocation($statementsSource, $childMethod)
+							)
+						);
+					}
+
+					break;
+				}
+			}
+		}
+	}
+}
diff --git a/psalm.xml b/psalm.xml
index 1d62b7327bc..14e3acd97ba 100644
--- a/psalm.xml
+++ b/psalm.xml
@@ -17,6 +17,7 @@
 	<plugins>
 		<plugin filename="build/psalm/AppFrameworkTainter.php" />
 		<plugin filename="build/psalm/AttributeNamedParameters.php" />
+		<plugin filename="build/psalm/OcInheritDoc.php" />
 	</plugins>
 	<projectFiles>
 		<directory name="apps/admin_audit"/>