fix(OpenAPI): Fix array syntax ambiguities

Signed-off-by: provokateurin <kate@provokateurin.de>
nextcloud · Nov 6, 2024 · 034f376 · 034f376
1 parent 42b8563
commit 034f376
Show file tree

Hide file tree

Showing 40 changed files with 250 additions and 320 deletions.
diff --git a/lib/Capabilities.php b/lib/Capabilities.php
@@ -171,8 +171,8 @@ public function __construct(
 
 	/**
 	 * @return array{
-	 *      spreed: TalkCapabilities,
-	 * }|array<empty>
+	 *      spreed?: TalkCapabilities,
+	 * }
 	 */
 	public function getCapabilities(): array {
 		$user = $this->userSession->getUser();
@@ -257,18 +257,18 @@ public function getCapabilities(): array {
 			$capabilities['config']['signaling']['hello-v2-token-key'] = $pubKey;
 		}
 
-		/** @var ?string[] $predefinedBackgrounds */
+		/** @var ?list<string> $predefinedBackgrounds */
 		$predefinedBackgrounds = null;
 		$cachedPredefinedBackgrounds = $this->talkCache->get('predefined_backgrounds');
 		if ($cachedPredefinedBackgrounds !== null) {
 			// Try using cached value
-			/** @var string[]|null $predefinedBackgrounds */
+			/** @var ?list<string> $predefinedBackgrounds */
 			$predefinedBackgrounds = json_decode($cachedPredefinedBackgrounds, true);
 		}
 
 		if (!is_array($predefinedBackgrounds)) {
 			// Cache was empty or invalid, regenerate
-			/** @var string[] $predefinedBackgrounds */
+			/** @var list<string> $predefinedBackgrounds */
 			$predefinedBackgrounds = [];
 			if (file_exists(__DIR__ . '/../img/backgrounds')) {
 				$directoryIterator = new \DirectoryIterator(__DIR__ . '/../img/backgrounds');

diff --git a/lib/Chat/ChatManager.php b/lib/Chat/ChatManager.php
@@ -23,6 +23,7 @@
 use OCA\Talk\Model\Message;
 use OCA\Talk\Model\Poll;
 use OCA\Talk\Participant;
+use OCA\Talk\ResponseDefinitions;
 use OCA\Talk\Room;
 use OCA\Talk\Service\AttachmentService;
 use OCA\Talk\Service\ParticipantService;
@@ -59,6 +60,7 @@
  *
  * When a message is saved the mentioned users are notified as needed, and
  * pending notifications are removed if the messages are deleted.
+ * @psalm-import-type TalkChatMentionSuggestion from ResponseDefinitions
  */
 class ChatManager {
 	public const MAX_CHAT_LENGTH = 32000;
@@ -950,6 +952,10 @@ public function searchForObjectsWithFilters(string $search, array $objectIds, st
 		return $this->commentsManager->searchForObjectsWithFilters($search, 'chat', $objectIds, $verb, $since, $until, $actorType, $actorId, $offset, $limit);
 	}
 
+	/**
+	 * @param list<TalkChatMentionSuggestion> $results
+	 * @return list<TalkChatMentionSuggestion>
+	 */
 	public function addConversationNotify(array $results, string $search, Room $room, Participant $participant): array {
 		if ($room->getType() === Room::TYPE_ONE_TO_ONE) {
 			return $results;

diff --git a/lib/Chat/ReactionManager.php b/lib/Chat/ReactionManager.php
@@ -127,7 +127,7 @@ public function deleteReactionMessage(Room $chat, string $actorType, string $act
 	}
 
 	/**
-	 * @return array<string, TalkReaction[]>
+	 * @return array<string, list<TalkReaction>>
 	 * @throws PreConditionNotMetException
 	 */
 	public function retrieveReactionMessages(Room $chat, Participant $participant, int $messageId, ?string $reaction = null): array {

diff --git a/lib/Controller/BanController.php b/lib/Controller/BanController.php
@@ -77,7 +77,7 @@ public function banActor(string $actorType, string $actorId, string $internalNot
 	 *
 	 * Required capability: `ban-v1`
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkBan[], array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkBan>, array{}>
 	 *
 	 * 200: List all bans
 	 */
@@ -95,7 +95,7 @@ public function listBans(): DataResponse {
 	 * Required capability: `ban-v1`
 	 *
 	 * @param int $banId ID of the ban to be removed
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Unban successfully or not found
 	 */

diff --git a/lib/Controller/BotController.php b/lib/Controller/BotController.php
@@ -120,7 +120,7 @@ protected function getBotFromHeaders(string $token, string $message): Bot {
 	 * @param string $referenceId For the message to be able to later identify it again
 	 * @param int $replyTo Parent id which this message is a reply to
 	 * @param bool $silent If sent silent the chat message will not create any notifications
-	 * @return DataResponse<Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, list<empty>, array{}>
 	 *
 	 * 201: Message sent successfully
 	 * 400: When the replyTo is invalid or message is empty
@@ -183,7 +183,7 @@ public function sendMessage(string $token, string $message, string $referenceId
 	 * @param string $token Conversation token
 	 * @param int $messageId ID of the message
 	 * @param string $reaction Reaction to add
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
 	 * 200: Reaction already exists
 	 * 201: Reacted successfully
@@ -237,7 +237,7 @@ public function react(string $token, int $messageId, string $reaction): DataResp
 	 * @param string $token Conversation token
 	 * @param int $messageId ID of the message
 	 * @param string $reaction Reaction to delete
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_UNAUTHORIZED, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_UNAUTHORIZED, list<empty>, array{}>
 	 *
 	 * 200: Reaction deleted successfully
 	 * 400: Reacting is not possible
@@ -285,7 +285,7 @@ public function deleteReaction(string $token, int $messageId, string $reaction):
 	/**
 	 * List admin bots
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkBotWithDetails[], array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkBotWithDetails>, array{}>
 	 *
 	 * 200: Bot list returned
 	 */
@@ -305,7 +305,7 @@ public function adminListBots(): DataResponse {
 	/**
 	 * List bots
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkBot[], array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkBot>, array{}>
 	 *
 	 * 200: Bot list returned
 	 */

diff --git a/lib/Controller/BreakoutRoomController.php b/lib/Controller/BreakoutRoomController.php
@@ -45,7 +45,7 @@ public function __construct(
 	 * @psalm-param BreakoutRoom::MODE_* $mode
 	 * @param int<1, 20> $amount Number of breakout rooms - Constants {@see BreakoutRoom::MINIMUM_ROOM_AMOUNT} and {@see BreakoutRoom::MAXIMUM_ROOM_AMOUNT}
 	 * @param string $attendeeMap Mapping of the attendees to breakout rooms
-	 * @return DataResponse<Http::STATUS_OK, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Breakout rooms configured successfully
 	 * 400: Configuring breakout rooms errored
@@ -87,7 +87,7 @@ public function removeBreakoutRooms(): DataResponse {
 	 * Broadcast a chat message to all breakout rooms
 	 *
 	 * @param string $message Message to broadcast
-	 * @return DataResponse<Http::STATUS_CREATED, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_CREATED, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, array{error: string}, array{}>
 	 *
 	 * 201: Chat message broadcasted successfully
 	 * 400: Broadcasting chat message is not possible
@@ -111,7 +111,7 @@ public function broadcastChatMessage(string $message): DataResponse {
 	 * Apply an attendee map to the breakout rooms
 	 *
 	 * @param string $attendeeMap JSON encoded mapping of the attendees to breakout rooms `array<int, int>`
-	 * @return DataResponse<Http::STATUS_OK, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Attendee map applied successfully
 	 * 400: Applying attendee map is not possible
@@ -181,7 +181,7 @@ public function resetRequestForAssistance(): DataResponse {
 	/**
 	 * Start the breakout rooms
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Breakout rooms started successfully
 	 * 400: Starting breakout rooms is not possible
@@ -202,7 +202,7 @@ public function startBreakoutRooms(): DataResponse {
 	/**
 	 * Stop the breakout rooms
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Breakout rooms stopped successfully
 	 * 400: Stopping breakout rooms is not possible
@@ -247,7 +247,7 @@ public function switchBreakoutRoom(string $target): DataResponse {
 	}
 
 	/**
-	 * @return TalkRoom[]
+	 * @return list<TalkRoom>
 	 */
 	protected function formatMultipleRooms(array $rooms): array {
 		$return = [];

diff --git a/lib/Controller/CallController.php b/lib/Controller/CallController.php
@@ -67,7 +67,7 @@ public function __construct(
 	/**
 	 * Get the peers for a call
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkCallPeer[], array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkCallPeer>, array{}>
 	 *
 	 * 200: List of peers in the call returned
 	 */
@@ -193,7 +193,7 @@ public function downloadParticipantsForCall(string $format = 'csv'): DataDownloa
 	 *                               (Only needed when the `config => call => recording-consent` capability is set to {@see RecordingService::CONSENT_REQUIRED_YES}
 	 *                               or the capability is {@see RecordingService::CONSENT_REQUIRED_OPTIONAL}
 	 *                               and the conversation `recordingConsent` value is {@see RecordingService::CONSENT_REQUIRED_YES} )
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, array<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error?: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, list<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error?: string}, array{}>
 	 *
 	 * 200: Call joined successfully
 	 * 400: No recording consent was given
@@ -274,7 +274,7 @@ protected function validateRecordingConsent(bool $recordingConsent): void {
 	 * @psalm-param int-mask-of<Participant::FLAG_*>|null $flags
 	 * @param bool $silent Join the call silently
 	 * @param bool $recordingConsent Agreement to be recorded
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error?: string}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, null, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error?: string}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, null, array{}>
 	 *
 	 * 200: Call joined successfully
 	 * 400: Conditions to join not met
@@ -314,7 +314,7 @@ public function joinFederatedCall(string $sessionId, ?int $flags = null, bool $s
 	 * Ring an attendee
 	 *
 	 * @param int $attendeeId ID of the attendee to ring
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, array<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, list<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Attendee rang successfully
 	 * 400: Ringing attendee is not possible
@@ -396,7 +396,7 @@ public function sipDialOut(int $attendeeId): DataResponse {
 	 *
 	 * @param int<0, 15> $flags New flags
 	 * @psalm-param int-mask-of<Participant::FLAG_*> $flags New flags
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
 	 * 200: In-call flags updated successfully
 	 * 400: Updating in-call flags is not possible
@@ -439,7 +439,7 @@ public function updateCallFlags(int $flags): DataResponse {
 	 * @param string $sessionId Federated session id to update the flags with
 	 * @param int<0, 15> $flags New flags
 	 * @psalm-param int-mask-of<Participant::FLAG_*> $flags New flags
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST, array<empty>, array{}>|DataResponse<Http::STATUS_NOT_FOUND, null, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST, list<empty>, array{}>|DataResponse<Http::STATUS_NOT_FOUND, null, array{}>
 	 *
 	 * 200: In-call flags updated successfully
 	 * 400: Updating in-call flags is not possible
@@ -469,7 +469,7 @@ public function updateFederatedCallFlags(string $sessionId, int $flags): DataRes
 	 * Leave a call
 	 *
 	 * @param bool $all whether to also terminate the call for all participants
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
 	 * 200: Call left successfully
 	 * 404: Call session not found
@@ -519,7 +519,7 @@ public function leaveCall(bool $all = false): DataResponse {
 	 * user.
 	 *
 	 * @param string $sessionId Federated session id to leave with
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_NOT_FOUND, null, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>|DataResponse<Http::STATUS_NOT_FOUND, null, array{}>
 	 *
 	 * 200: Call left successfully
 	 * 404: Call session not found