From da04ab63b298b72efeb65de1f08d871f0923fe04 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 8 Jul 2025 17:20:31 +0200
Subject: [PATCH] api/docs: sort resources into tree order

---
 .../clan_lib/log_manager/test_log_manager.py  | 30 +++++++++----------
 pkgs/clan-cli/openapi.py                      | 28 +++++++++++++++++
 2 files changed, 43 insertions(+), 15 deletions(-)

diff --git a/pkgs/clan-cli/clan_lib/log_manager/test_log_manager.py b/pkgs/clan-cli/clan_lib/log_manager/test_log_manager.py
index 422e85083..e68e9385f 100644
--- a/pkgs/clan-cli/clan_lib/log_manager/test_log_manager.py
+++ b/pkgs/clan-cli/clan_lib/log_manager/test_log_manager.py
@@ -723,21 +723,21 @@ class TestLogFileSorting:
             expected_order
         ):
             actual = sorted_files[i]
-            assert (
-                actual.op_key == exp_op
-            ), f"Position {i}: expected op_key {exp_op}, got {actual.op_key}"
-            assert (
-                actual.date_day == exp_date
-            ), f"Position {i}: expected date {exp_date}, got {actual.date_day}"
-            assert (
-                actual.group == exp_group
-            ), f"Position {i}: expected group {exp_group}, got {actual.group}"
-            assert (
-                actual.func_name == exp_func
-            ), f"Position {i}: expected func {exp_func}, got {actual.func_name}"
-            assert (
-                actual.date_second == exp_time
-            ), f"Position {i}: expected time {exp_time}, got {actual.date_second}"
+            assert actual.op_key == exp_op, (
+                f"Position {i}: expected op_key {exp_op}, got {actual.op_key}"
+            )
+            assert actual.date_day == exp_date, (
+                f"Position {i}: expected date {exp_date}, got {actual.date_day}"
+            )
+            assert actual.group == exp_group, (
+                f"Position {i}: expected group {exp_group}, got {actual.group}"
+            )
+            assert actual.func_name == exp_func, (
+                f"Position {i}: expected func {exp_func}, got {actual.func_name}"
+            )
+            assert actual.date_second == exp_time, (
+                f"Position {i}: expected time {exp_time}, got {actual.date_second}"
+            )
 
     def test_get_log_file_returns_newest_when_multiple_exist(
         self, configured_log_manager: LogManager
diff --git a/pkgs/clan-cli/openapi.py b/pkgs/clan-cli/openapi.py
index bd6c280de..ed4cfde04 100644
--- a/pkgs/clan-cli/openapi.py
+++ b/pkgs/clan-cli/openapi.py
@@ -118,6 +118,32 @@ def make_schema_name(func_name: str, part: str) -> str:
     return f"{func_name}_{part}"
 
 
+def get_tag_key(tags: list[str]) -> tuple:
+    """Convert list of tags to a tuple key for sorting."""
+    return tuple(tags)
+
+
+def sort_openapi_paths_by_tag_tree(openapi: dict) -> None:
+    # Extract (tags, path, method, operation) tuples
+    operations = []
+
+    for path, methods in openapi["paths"].items():
+        for method, operation in methods.items():
+            tag_path = operation.get("tags", [])
+            operations.append((tag_path, path, method, operation))
+
+    # Sort by the tag hierarchy
+    operations.sort(key=lambda x: get_tag_key(x[0]))
+
+    # Rebuild sorted openapi["paths"]
+    sorted_paths: dict = {}
+    for _tag_path, path, method, operation in operations:
+        sorted_paths[path] = sorted_paths.get(path, {})
+        sorted_paths[path][method] = operation
+
+    openapi["paths"] = dict(sorted_paths)  # Ensure it's a plain dict
+
+
 def main() -> None:
     input_path = Path(os.environ["INPUT_PATH"])
 
@@ -203,6 +229,8 @@ def main() -> None:
             }
         }
 
+    sort_openapi_paths_by_tag_tree(openapi)
+
     # === Add global definitions from $defs ===
     for def_name, def_schema in defs.items():
         fixed_schema = fix_nullables(deepcopy(def_schema))