client: add document outline

hide/client/hide_client.py

@@ -234,6 +234,22 @@ def search_symbols(
             raise HideClientError(response.text)
         return [model.Symbol.model_validate(symbol) for symbol in response.json()]
 
+    def document_outline(
+        self, project_id: str, file: model.File | model.FileInfo | model.FilePath
+    ) -> model.DocumentOutline:
+        match file:
+            case model.FilePath():
+                path = file
+            case model.File():
+                path = file.path
+            case model.FileInfo():
+                path = file.path
+
+        response = requests.get(f"{self.base_url}/projects/{project_id}/outline/{path}")
+        if not response.ok:
+            raise HideClientError(response.text)
+        return model.DocumentOutline.model_validate(response.json())
+
 
 class HideClientError(Exception):
     def __init__(self, message: str) -> None:

hide/model.py

@@ -292,3 +292,20 @@ class SearchMode(IntEnum):
 class ListFilesFormat(str, Enum):
     JSON = "json"
     TREE = "tree"
+
+
+class DocumentSymbol(BaseModel):
+    name: str = Field(..., description="The name of the symbol.")
+    detail: str = Field(..., description="The details of the symbol.")
+    kind: str = Field(..., description="The kind of the symbol.")
+    range: Range = Field(..., description="The range of the symbol.")
+    children: list["DocumentSymbol"] = Field(
+        default_factory=list, description="The children of the symbol."
+    )
+
+
+class DocumentOutline(BaseModel):
+    path: FilePath = Field(..., description="The path of the file.")
+    document_symbols: list[DocumentSymbol] = Field(
+        ..., description="The document symbols."
+    )

tests/test_hide_client.py

@@ -517,3 +517,46 @@ def test_search_files_failure(client):
         mock_get.return_value = Mock(ok=False, text="Error")
         with pytest.raises(HideClientError, match="Error"):
             client.search_files(PROJECT_ID, query="test")
+
+
+def test_document_outline_success(client):
+    response_data = {
+        "path": "file.txt",
+        "document_symbols": [
+            {
+                "name": "Symbol 1",
+                "detail": "Details 1",
+                "kind": "Kind 1",
+                "range": {
+                    "start": {"line": 1, "character": 1},
+                    "end": {"line": 1, "character": 2},
+                },
+                "children": [
+                    {
+                        "name": "Child 1",
+                        "detail": "Child details 1",
+                        "kind": "Child kind 1",
+                        "range": {
+                            "start": {"line": 2, "character": 1},
+                            "end": {"line": 2, "character": 2},
+                        },
+                        "children": [],
+                    }
+                ],
+            }
+        ],
+    }
+    with patch("requests.get") as mock_get:
+        mock_get.return_value = Mock(ok=True, json=lambda: response_data)
+        outline = client.document_outline(PROJECT_ID, PATH)
+        assert outline == model.DocumentOutline.model_validate(response_data)
+        mock_get.assert_called_once_with(
+            f"http://localhost/projects/{PROJECT_ID}/outline/{PATH}"
+        )
+
+
+def test_document_outline_failure(client):
+    with patch("requests.get") as mock_get:
+        mock_get.return_value = Mock(ok=False, text="Error")
+        with pytest.raises(HideClientError, match="Error"):
+            client.document_outline(PROJECT_ID, PATH)