feat: support directory outline (#35)

* feat: support directory outline

* Address code review feedback for directory outline feature (#36)

* Initial plan

* fix: address code review feedback for directory outline

- Remove filesystem access from schema validator
- Add path validation and scope check in capability handler
- Add error handling for failed LSP symbol requests in directory mode
- Add validation for mutually exclusive OutlineResponse fields
- Add semaphore to limit concurrent directory file processing
- Exclude common directories (node_modules, .git, __pycache__, etc.)
- Use string-based sorting for cross-platform path consistency
- Improve OutlineFileItem docstring
- Add test for scope+directory validation
- Add test verifying non-code files are excluded
- Add is_directory assertions to directory tests

Co-authored-by: observerw <20661574+observerw@users.noreply.github.com>

* refactor: improve error handling and move constant to module level

- Move EXCLUDED_DIRS to module-level constant (_EXCLUDED_DIRS) for better performance
- Add logging for failed file processing in directory mode
- Import loguru logger for debug logging

Co-authored-by: observerw <20661574+observerw@users.noreply.github.com>

* refactor: improve exception handling and imports

- Use specific exceptions (OSError, PermissionError) instead of broad Exception catch
- Use logger format strings instead of f-strings for better performance
- Move tempfile import to top level in tests

Co-authored-by: observerw <20661574+observerw@users.noreply.github.com>

* perf: improve glob pattern and directory exclusion check

- Fix glob pattern to use `*.{suffix}` instead of `*{suffix}` for proper extension matching
- Use frozenset.isdisjoint() instead of any() for better performance on deeply nested paths

Co-authored-by: observerw <20661574+observerw@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: observerw <20661574+observerw@users.noreply.github.com>

* feat: add with_sem

* feat: add subdir tips

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: observerw <20661574+observerw@users.noreply.github.com>

Author: observerw

src/lsap/capability/outline.py

@@ -5,7 +5,6 @@
 from typing import override
 
 import anyio
-import asyncer
 from attrs import define, field
 from lsp_client.capability.request import WithRequestDocumentSymbol, WithRequestHover
 from lsprotocol.types import DocumentSymbol
@@ -22,6 +21,7 @@
 from lsap.schema.types import SymbolPath
 from lsap.utils.capability import ensure_capability
 from lsap.utils.markdown import clean_hover_content
+from lsap.utils.sem import with_sem
 from lsap.utils.symbol import iter_symbols
 
 from .abc import Capability
@@ -30,6 +30,7 @@
 @define
 class OutlineCapability(Capability[OutlineRequest, OutlineResponse]):
     hover_sem: anyio.Semaphore = field(default=anyio.Semaphore(32), init=False)
+    directory_sem: anyio.Semaphore = field(default=anyio.Semaphore(10), init=False)
 
     @override
     async def __call__(self, req: OutlineRequest) -> OutlineResponse | None:
@@ -38,44 +39,51 @@ async def __call__(self, req: OutlineRequest) -> OutlineResponse | None:
         return await self._handle_file(req)
 
     async def _handle_directory(self, req: OutlineRequest) -> OutlineResponse | None:
-        directory = req.path
+        assert req.path.is_dir()
 
-        lang_config = self.client.get_language_config()
         code_files: list[Path] = []
 
-        if req.recursive:
-            for suffix in lang_config.suffixes:
-                code_files.extend(directory.rglob(f"*{suffix}"))
-        else:
-            for suffix in lang_config.suffixes:
-                code_files.extend(directory.glob(f"*{suffix}"))
-
-        code_files = sorted(set(code_files))
+        lang_config = self.client.get_language_config()
+        glob = req.path.rglob if req.recursive else req.path.glob
+        for suffix in lang_config.suffixes:
+            code_files.extend(glob(f"*{suffix}"))
 
         file_groups: list[OutlineFileGroup] = []
         total_symbols = 0
 
-        async with asyncer.create_task_group() as tg:
+        async with anyio.create_task_group() as tg:
             for file_path in code_files:
-                _ = tg.soonify(self._process_file_for_directory)(file_path, file_groups)
+                tg.start_soon(
+                    with_sem(
+                        self.directory_sem,
+                        self._process_file_for_directory,
+                        file_path,
+                        file_groups,
+                    )
+                )
 
         for group in file_groups:
             total_symbols += len(group.symbols)
 
-        file_groups.sort(key=lambda g: g.file_path)
+        has_subdirs = False
+        if not req.recursive:
+            for p in req.path.iterdir():
+                if p.is_dir() and not p.name.startswith("."):
+                    has_subdirs = True
+                    break
 
         return OutlineResponse(
-            path=directory,
+            path=req.path,
             is_directory=True,
+            request=req,
             files=file_groups,
             total_files=len(file_groups),
             total_symbols=total_symbols,
+            has_subdirs=has_subdirs,
         )
 
     async def _process_file_for_directory(
-        self,
-        file_path: Path,
-        file_groups: list[OutlineFileGroup],
+        self, file_path: Path, file_groups: list[OutlineFileGroup]
     ) -> None:
         symbols = await ensure_capability(
             self.client, WithRequestDocumentSymbol
@@ -112,7 +120,9 @@ async def _handle_file(self, req: OutlineRequest) -> OutlineResponse | None:
                 if path == target_path
             ]
             if not matched:
-                return OutlineResponse(path=file_path, is_directory=False, items=[])
+                return OutlineResponse(
+                    path=file_path, is_directory=False, request=req, items=[]
+                )
 
             symbols_iter: list[tuple[SymbolPath, DocumentSymbol]] = []
             for path, symbol in matched:
@@ -129,7 +139,9 @@ async def _handle_file(self, req: OutlineRequest) -> OutlineResponse | None:
 
         items = await self.resolve_symbols(file_path, symbols_iter)
 
-        return OutlineResponse(path=file_path, is_directory=False, items=items)
+        return OutlineResponse(
+            path=file_path, is_directory=False, request=req, items=items
+        )
 
     def _iter_top_symbols(
         self,
@@ -181,11 +193,18 @@ async def resolve_symbols(
         symbols_with_path: Iterable[tuple[SymbolPath, DocumentSymbol]],
     ) -> list[SymbolDetailInfo]:
         items: list[SymbolDetailInfo] = []
-        async with asyncer.create_task_group() as tg:
+        async with anyio.create_task_group() as tg:
             for path, symbol in symbols_with_path:
                 item = self._make_item(file_path, path, symbol)
                 items.append(item)
-                tg.soonify(self._fill_hover)(item, symbol.selection_range.start)
+                tg.start_soon(
+                    with_sem(
+                        self.hover_sem,
+                        self._fill_hover,
+                        item,
+                        symbol.selection_range.start,
+                    )
+                )
 
         return items
 
@@ -205,8 +224,7 @@ def _make_item(
         )
 
     async def _fill_hover(self, item: SymbolDetailInfo, pos: LSPPosition) -> None:
-        async with self.hover_sem:
-            if hover := await ensure_capability(
-                self.client, WithRequestHover
-            ).request_hover(item.file_path, pos):
-                item.hover = clean_hover_content(hover.value)
+        if hover := await ensure_capability(
+            self.client, WithRequestHover
+        ).request_hover(item.file_path, pos):
+            item.hover = clean_hover_content(hover.value)

src/lsap/schema/outline.py

@@ -73,7 +73,14 @@
 
 
 class OutlineFileItem(SymbolDetailInfo):
-    """Symbol information for directory outline mode."""
+    """
+    Thin semantic wrapper around :class:`SymbolDetailInfo` used for directory outline mode.
+
+    This class intentionally does not add any new fields or behaviour today; it exists as a
+    distinct type to make directory outline responses self-documenting and to preserve a
+    stable extension point for adding directory-specific metadata in the future without
+    breaking the public API.
+    """
 
 
 class OutlineRequest(Request):
@@ -103,9 +110,8 @@ class OutlineRequest(Request):
     """If true: for directories, scan subdirectories; for files, include all nested symbols."""
 
     @model_validator(mode="after")
-    def validate_scope(self) -> Self:
-        """Ensure scope is only used with files, not directories."""
-        if self.scope is not None and self.path.is_dir():
+    def validate_request_fields(self) -> Self:
+        if self.scope and self.path.is_dir():
             raise ValueError("scope cannot be used with directory paths")
         return self
 
@@ -139,6 +145,13 @@ def validate_scope(self) -> Self:
 {%- endif %}
 
 {% endfor -%}
+
+{% if has_subdirs and request.recursive == false -%}
+---
+
+> [!TIP]
+> Subdirectories found. Set `recursive=true` to scan them.
+{%- endif %}
 """
 
 
@@ -150,10 +163,12 @@ class OutlineFileGroup(Response):
 class OutlineResponse(Response):
     path: Path
     is_directory: bool
+    request: OutlineRequest
     items: list[SymbolDetailInfo] | None = None
     files: list[OutlineFileGroup] | None = None
     total_files: int | None = None
     total_symbols: int | None = None
+    has_subdirs: bool = False
 
     model_config = ConfigDict(
         json_schema_extra={
@@ -162,6 +177,21 @@ class OutlineResponse(Response):
         }
     )
 
+    @model_validator(mode="after")
+    def validate_response_fields(self) -> Self:
+        """Ensure correct fields are populated based on is_directory flag."""
+        if self.is_directory:
+            if self.files is None:
+                raise ValueError("files must be provided when is_directory=True")
+            if self.items is not None:
+                raise ValueError("items must be None when is_directory=True")
+        else:
+            if self.items is None:
+                raise ValueError("items must be provided when is_directory=False")
+            if self.files is not None:
+                raise ValueError("files must be None when is_directory=False")
+        return self
+
     @override
     def format(self, template_name: str = "markdown") -> str:
         if template_name == "markdown" and self.is_directory:

src/lsap/utils/sem.py

@@ -0,0 +1,16 @@
+from collections.abc import Awaitable, Callable
+
+import anyio
+
+
+def with_sem[**P, R](
+    sem: anyio.Semaphore,
+    func: Callable[P, Awaitable[R]],
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> Callable[[], Awaitable[R]]:
+    async def wrapper() -> R:
+        async with sem:
+            return await func(*args, **kwargs)
+
+    return wrapper

tests/test_outline.py

@@ -1,3 +1,4 @@
+import tempfile
 from contextlib import asynccontextmanager
 from pathlib import Path
 
@@ -402,8 +403,6 @@ async def request_document_symbol_list(self, file_path) -> list[DocumentSymbol]:
 
 @pytest.mark.asyncio
 async def test_outline_directory():
-    import tempfile
-
     class MockDirectoryClient(MockOutlineClient):
         def __init__(self, tmpdir):
             super().__init__()
@@ -457,6 +456,7 @@ async def request_document_symbol_list(self, file_path) -> list[DocumentSymbol]:
         resp = await capability(req)
         assert resp is not None
         assert resp.path == tmppath
+        assert resp.is_directory is True
         assert resp.total_files == 2
         assert resp.total_symbols == 2
 
@@ -475,8 +475,6 @@ async def request_document_symbol_list(self, file_path) -> list[DocumentSymbol]:
 
 @pytest.mark.asyncio
 async def test_outline_directory_recursive():
-    import tempfile
-
     class MockDirectoryClient(MockOutlineClient):
         def __init__(self, tmpdir):
             super().__init__()
@@ -546,6 +544,7 @@ async def request_document_symbol_list(self, file_path) -> list[DocumentSymbol]:
         resp = await capability(req)
         assert resp is not None
         assert resp.path == tmppath
+        assert resp.is_directory is True
         assert resp.total_files == 2
         assert resp.total_symbols == 2
         file_names = {group.file_path.name for group in resp.files}
@@ -556,7 +555,81 @@ async def request_document_symbol_list(self, file_path) -> list[DocumentSymbol]:
         resp = await capability(req)
         assert resp is not None
         assert resp.path == tmppath
+        assert resp.is_directory is True
         assert resp.total_files == 3
         assert resp.total_symbols == 3
         file_names = {group.file_path.name for group in resp.files}
         assert file_names == {"file1.py", "file2.py", "nested.py"}
+
+
+@pytest.mark.asyncio
+async def test_outline_directory_scope_validation():
+    """Test that scope parameter raises ValueError with directory paths."""
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmppath = Path(tmpdir)
+        (tmppath / "file1.py").write_text("class ClassA:\n    pass\n")
+
+        client = MockOutlineClient()
+        capability = OutlineCapability(client=client)  # type: ignore
+
+        # Should raise ValueError when scope is provided with directory path
+        with pytest.raises(
+            ValueError, match="scope cannot be used with directory paths"
+        ):
+            req = OutlineRequest(
+                path=tmppath,
+                scope={"symbol_path": ["SomeClass"]},
+            )
+            await capability(req)
+
+
+@pytest.mark.asyncio
+async def test_outline_directory_excludes_non_code_files():
+    """Test that non-code files like README.md are excluded from directory outline."""
+
+    class MockDirectoryClient(MockOutlineClient):
+        def __init__(self, tmpdir):
+            super().__init__()
+            self.tmpdir = tmpdir
+            self.file_symbols = {
+                "file1.py": [
+                    DocumentSymbol(
+                        name="ClassA",
+                        kind=SymbolKind.Class,
+                        range=LSPRange(
+                            start=LSPPosition(line=0, character=0),
+                            end=LSPPosition(line=1, character=0),
+                        ),
+                        selection_range=LSPRange(
+                            start=LSPPosition(line=0, character=6),
+                            end=LSPPosition(line=0, character=12),
+                        ),
+                    )
+                ],
+            }
+
+        async def request_document_symbol_list(self, file_path) -> list[DocumentSymbol]:
+            filename = file_path.name
+            return self.file_symbols.get(filename, [])
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmppath = Path(tmpdir)
+        (tmppath / "file1.py").write_text("class ClassA:\n    pass\n")
+        (tmppath / "README.md").write_text("# Not a code file")
+        (tmppath / "data.json").write_text('{"key": "value"}')
+
+        client = MockDirectoryClient(tmppath)
+        capability = OutlineCapability(client=client)  # type: ignore
+
+        req = OutlineRequest(path=tmppath)
+        resp = await capability(req)
+
+        assert resp is not None
+        assert resp.is_directory is True
+        assert resp.total_files == 1
+        # Explicitly verify that only the Python file is included
+        file_names = {group.file_path.name for group in resp.files}
+        assert file_names == {"file1.py"}
+        assert "README.md" not in file_names
+        assert "data.json" not in file_names