feat: add relation API draft

Author: observerw

docs/schemas/draft/relation.md

@@ -0,0 +1,65 @@
+# Relation API
+
+The Relation API allows finding all call chains (paths) that connect two specific symbols. This is useful for understanding how one part of the system interacts with another, validating architectural dependencies, or impact analysis.
+
+It leverages the [Call Hierarchy API](call_hierarchy.md) to trace paths.
+
+## RelationRequest
+
+| Field       | Type                  | Default  | Description                                |
+| :---------- | :-------------------- | :------- | :----------------------------------------- |
+| `source`    | [`Locate`](locate.md) | Required | The starting symbol for the path search.   |
+| `target`    | [`Locate`](locate.md) | Required | The ending symbol for the path search.     |
+| `max_depth` | `number`              | `10`     | Maximum depth to search for connections.   |
+
+## RelationResponse
+
+| Field       | Type                    | Description                                                                 |
+| :---------- | :---------------------- | :-------------------------------------------------------------------------- |
+| `source`    | `CallHierarchyItem`     | The resolved source symbol.                                                 |
+| `target`    | `CallHierarchyItem`     | The resolved target symbol.                                                 |
+| `chains`    | `CallHierarchyItem[][]` | List of paths connecting source to target. Each path is a sequence of items.|
+| `max_depth` | `number`                | The maximum depth used for the search.                                      |
+
+## Example Usage
+
+### Scenario 1: How does `handle_request` reach `db.query`?
+
+#### Request
+
+```json
+{
+  "source": {
+    "file_path": "src/controllers.py",
+    "scope": {
+      "symbol_path": ["handle_request"]
+    }
+  },
+  "target": {
+    "file_path": "src/db.py",
+    "scope": {
+      "symbol_path": ["query"]
+    }
+  },
+  "max_depth": 5
+}
+```
+
+#### Markdown Rendered for LLM
+
+```markdown
+# Relation: `handle_request` → `query`
+
+Found 2 call chain(s):
+
+### Chain 1
+1. **handle_request** (`Function`) - `src/controllers.py`
+2. **UserService.get_user** (`Method`) - `src/services/user.py`
+3. **db.query** (`Function`) - `src/db.py`
+
+### Chain 2
+1. **handle_request** (`Function`) - `src/controllers.py`
+2. **AuthService.validate_token** (`Method`) - `src/services/auth.py`
+3. **SessionManager.get_session** (`Method`) - `src/services/session.py`
+4. **db.query** (`Function`) - `src/db.py`
+```

src/lsap_schema/__init__.py

@@ -46,6 +46,12 @@
     RenameResponse,
 )
 
+# Relation
+from .draft.relation import (
+    RelationRequest,
+    RelationResponse,
+)
+
 # Type hierarchy
 from .draft.type_hierarchy import (
     TypeEdge,
@@ -162,6 +168,9 @@
     "RenameFileChange",
     "RenameRequest",
     "RenameResponse",
+    # Relation
+    "RelationRequest",
+    "RelationResponse",
     # Symbol
     "SymbolRequest",
     "SymbolResponse",

src/lsap_schema/draft/relation.py

@@ -0,0 +1,54 @@
+from typing import Final
+
+from pydantic import ConfigDict
+
+from lsap_schema.abc import Request, Response
+from lsap_schema.draft.call_hierarchy import CallHierarchyItem
+from lsap_schema.locate import Locate
+
+
+class RelationRequest(Request):
+    """
+    Finds call chains connecting two symbols.
+
+    Uses call hierarchy to trace paths from source to target.
+    """
+
+    source: Locate
+    target: Locate
+
+    max_depth: int = 10
+    """Maximum depth to search for connections"""
+
+
+markdown_template: Final = """
+# Relation: `{{ source.name }}` → `{{ target.name }}`
+
+{% if chains.size > 0 %}
+Found {{ chains | size }} call chain(s):
+
+{% for chain in chains %}
+### Chain {{ forloop.index }}
+{% for item in chain %}
+{{ forloop.index }}. **{{ item.name }}** (`{{ item.kind }}`) - `{{ item.file_path }}`
+{% endfor %}
+{% endfor %}
+{% else %}
+No connection found between `{{ source.name }}` and `{{ target.name }}` (depth: {{ max_depth }}).
+{% endif %}
+"""
+
+
+class RelationResponse(Response):
+    source: CallHierarchyItem
+    target: CallHierarchyItem
+    chains: list[list[CallHierarchyItem]]
+    """List of paths, where each path is a sequence of items from source to target."""
+
+    max_depth: int
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "markdown": markdown_template,
+        }
+    )