From 66e68aea143eda00130c3b793960940b788eb4cd Mon Sep 17 00:00:00 2001
From: Chirag Aggarwal <chiragaggarwal5k@gmail.com>
Date: Sun, 5 Apr 2026 19:37:29 +0530
Subject: [PATCH] fix: fail specs when docs are missing

---
 app/cli.php                                   |  6 +++++-
 src/Appwrite/SDK/Specification/Format.php     | 19 +++++++++++++++++++
 .../SDK/Specification/Format/OpenAPI3.php     |  4 ++--
 .../SDK/Specification/Format/Swagger2.php     |  4 ++--
 4 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/app/cli.php b/app/cli.php
index b8721320be..b636707f1c 100644
--- a/app/cli.php
+++ b/app/cli.php
@@ -329,17 +329,20 @@ $setResource('bus', function (Registry $register) use ($cli) {
 
 $setResource('telemetry', fn () => new NoTelemetry(), []);
 
+$exitCode = 0;
+
 $cli
     ->error()
     ->inject('error')
     ->inject('logError')
-    ->action(function (Throwable $error, callable $logError) use ($taskName) {
+    ->action(function (Throwable $error, callable $logError) use ($taskName, &$exitCode) {
         call_user_func_array($logError, [
             $error,
             'Task',
             $taskName,
         ]);
 
+        $exitCode = 1;
         Timer::clearAll();
     });
 
@@ -348,3 +351,4 @@ $cli->shutdown()->action(fn () => Timer::clearAll());
 Runtime::enableCoroutine(SWOOLE_HOOK_ALL);
 require_once __DIR__ . '/init/span.php';
 run($cli->run(...));
+Console::exit($exitCode);
diff --git a/src/Appwrite/SDK/Specification/Format.php b/src/Appwrite/SDK/Specification/Format.php
index 7a867c5b91..dd4d378345 100644
--- a/src/Appwrite/SDK/Specification/Format.php
+++ b/src/Appwrite/SDK/Specification/Format.php
@@ -210,6 +210,25 @@ abstract class Format
         return $this->services;
     }
 
+    protected function getDescriptionContents(?string $description): string
+    {
+        if ($description === null || $description === '') {
+            return '';
+        }
+
+        if (!\str_ends_with($description, '.md')) {
+            return $description;
+        }
+
+        $contents = @\file_get_contents($description);
+
+        if ($contents === false) {
+            throw new \RuntimeException('Documentation file not found or unreadable: ' . $description);
+        }
+
+        return $contents;
+    }
+
     protected function getRequestEnumName(string $service, string $method, string $param): ?string
     {
         /* `$service` is `$namespace` */
diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php
index 753a0dc52f..41ed386e30 100644
--- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php
+++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php
@@ -128,7 +128,7 @@ class OpenAPI3 extends Format
             if ($desc === null) {
                 $desc = '';
             }
-            $descContents = \str_ends_with($desc, '.md') ? \file_get_contents($desc) : $desc;
+            $descContents = $this->getDescriptionContents($desc);
 
             $temp = [
                 'summary' => $route->getDesc(),
@@ -193,7 +193,7 @@ class OpenAPI3 extends Format
                         'parameters' => [],
                         'required' => [],
                         'responses' => [],
-                        'description' => ($desc) ? \file_get_contents($desc) : '',
+                        'description' => $this->getDescriptionContents($desc),
                         'demo' => \strtolower($namespace) . '/' . Template::fromCamelCaseToDash($methodObj->getMethodName()) . '.md',
                         'public' => $methodObj->isPublic(),
                     ];
diff --git a/src/Appwrite/SDK/Specification/Format/Swagger2.php b/src/Appwrite/SDK/Specification/Format/Swagger2.php
index 3e9ac891fa..dc65bea215 100644
--- a/src/Appwrite/SDK/Specification/Format/Swagger2.php
+++ b/src/Appwrite/SDK/Specification/Format/Swagger2.php
@@ -129,7 +129,7 @@ class Swagger2 extends Format
             if ($desc === null) {
                 $desc = '';
             }
-            $descContents = \str_ends_with($desc, '.md') ? \file_get_contents($desc) : $desc;
+            $descContents = $this->getDescriptionContents($desc);
 
             $temp = [
                 'summary' => $route->getDesc(),
@@ -201,7 +201,7 @@ class Swagger2 extends Format
                         'parameters' => [],
                         'required' => [],
                         'responses' => [],
-                        'description' => ($desc) ? \file_get_contents($desc) : '',
+                        'description' => $this->getDescriptionContents($desc),
                         'demo' => \strtolower($namespace) . '/' . Template::fromCamelCaseToDash($methodObj->getMethodName()) . '.md',
                         'public' => $methodObj->isPublic(),
                     ];