llm-tool-cli 0.2.0__py3-none-any.whl

llm_tool_cli/paths/errors.py

@@ -0,0 +1,42 @@
+"""Public project-path failures."""
+
+from llm_tool_cli.core import errors as core_errors
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    """Base for expected project-path failures."""
+
+
+class InvalidProjectPath(EnvironmentError):
+    """An input cannot identify a path below the project root."""
+
+    code: str = "invalid_project_path"
+    message: str = "invalid project path `{error.path}`"
+    path: str
+
+
+class PathResolutionFailed(EnvironmentError):
+    """A filesystem path could not be resolved."""
+
+    code: str = "path_resolution_failed"
+    message: str = "could not resolve project path `{error.path}`: {error.reason}"
+    path: str
+    reason: str
+
+
+class InvalidGlobPattern(EnvironmentError):
+    """A glob contains invalid capture syntax."""
+
+    code: str = "invalid_glob_pattern"
+    message: str = "invalid glob pattern `{error.pattern}`: {error.reason}"
+    pattern: str
+    reason: str
+
+
+class FilesUnreadable(EnvironmentError):
+    """Project files could not be enumerated."""
+
+    code: str = "files_unreadable"
+    message: str = "could not discover files under `{error.path}`: {error.reason}"
+    path: str
+    reason: str

llm_tool_cli/paths/filesystem.py

@@ -0,0 +1,164 @@
+"""Filesystem resolution and containment of project paths."""
+
+import stat
+from pathlib import Path
+from typing import NewType
+
+from llm_tool_cli.core.result import Err, Ok, Result, unwrap_to_error
+from llm_tool_cli.paths.errors import InvalidProjectPath, PathResolutionFailed
+from llm_tool_cli.paths.normalization import ProjectPathId, normalize_project_path_id, project_path_parts
+
+PathInput = NewType("PathInput", Path)
+ProjectConfigPath = NewType("ProjectConfigPath", Path)
+ProjectRootPath = NewType("ProjectRootPath", Path)
+RelativeProjectPath = NewType("RelativeProjectPath", Path)
+ResolvedProjectPath = NewType("ResolvedProjectPath", Path)
+
+
+@unwrap_to_error
+def _project_path_input(value: str, root: ProjectRootPath, *, allow_absolute: bool = True) -> Result[PathInput]:
+    """Select a filesystem candidate without interpreting its target."""
+    if value.startswith("@"):
+        normalized = normalize_project_path_id(value).unwrap()
+        return Ok(PathInput(root.joinpath(*project_path_parts(normalized))))
+
+    try:
+        path = Path(value).expanduser()
+    except (OSError, RuntimeError) as error:
+        return Err([PathResolutionFailed(path=value, reason=str(error)).with_cause(error)])
+
+    if path.is_absolute() and not allow_absolute:
+        return Err([InvalidProjectPath(path=value)])
+
+    return Ok(PathInput(path if path.is_absolute() else root / path))
+
+
+@unwrap_to_error
+def resolve_project_path(value: str, root: Path, *, allow_absolute: bool = True) -> Result[ResolvedProjectPath]:
+    """Resolve an identifier or filesystem input strictly below a project root.
+
+    Resolve the root first. Normalize identifiers before checking for symlinks;
+    expand home markers only in filesystem inputs. Relative filesystem inputs
+    use the resolved root. When absolute inputs are disabled, reject paths
+    that are absolute after home expansion. Do not require an existing target.
+    """
+    project_root = resolve_project_root(root).unwrap()
+    candidate = _project_path_input(value, project_root, allow_absolute=allow_absolute).unwrap()
+    return resolve_inside_project(candidate, project_root)
+
+
+@unwrap_to_error
+def normalize_path(value: str, root: Path, *, cwd: Path | None = None) -> Result[ProjectPathId]:
+    """Normalize an identifier or filesystem input to a project identifier.
+
+    Resolve the root first and reject empty inputs. Normalize inputs starting
+    with ``@`` lexically; otherwise expand home markers. Enforce containment
+    and reject symlinks below the root in both cases. Relative inputs use the
+    supplied directory base, or the resolved root.
+    Neither form requires an existing target.
+    """
+    project_root = resolve_project_root(root).unwrap()
+
+    if not value:
+        return Err([InvalidProjectPath(path=value)])
+
+    if value.startswith("@"):
+        resolved = resolve_root_anchored_path(value, project_root).unwrap()
+        return Ok(project_path_id_from_resolved(resolved, project_root))
+
+    try:
+        path = Path(value).expanduser()
+    except (OSError, RuntimeError) as error:
+        return Err([PathResolutionFailed(path=value, reason=str(error)).with_cause(error)])
+
+    candidate = path if path.is_absolute() else (cwd if cwd is not None else project_root) / path
+    resolved = resolve_inside_project(candidate, project_root).unwrap()
+    return Ok(project_path_id_from_resolved(resolved, project_root))
+
+
+@unwrap_to_error
+def project_path_id_from_filesystem(path: Path, root: Path) -> Result[ProjectPathId]:
+    """Resolve a filesystem path and convert it to a project identifier.
+
+    Resolve the supplied root first, then enforce containment strictly below it.
+    Relative roots and paths use the process working directory. Do not expand
+    home markers, interpret identifiers, or require an existing target.
+    Preserve root and target resolution failures and containment diagnostics.
+    """
+    project_root = resolve_project_root(root).unwrap()
+    resolved = resolve_inside_project(path, project_root).unwrap()
+    return Ok(project_path_id_from_resolved(resolved, project_root))
+
+
+def project_path_id_from_resolved(path: ResolvedProjectPath, root: ProjectRootPath) -> ProjectPathId:
+    """Convert a resolved path strictly below its resolved root to an identifier.
+
+    The path must already have passed containment resolution for this root.
+    Preserve segment text without filesystem access or repeated validation.
+    """
+    return ProjectPathId("@/" + path.relative_to(root).as_posix())
+
+
+def resolve_project_root(root: Path) -> Result[ProjectRootPath]:
+    """Resolve a filesystem root without requiring an existing directory.
+
+    Relative roots use the process working directory. Resolve symlinks and
+    parent segments without expanding home markers. Return filesystem
+    resolution failures with their original cause.
+    """
+    try:
+        return Ok(ProjectRootPath(root.resolve()))
+    except (OSError, RuntimeError) as error:
+        return Err([PathResolutionFailed(path=str(root), reason=str(error)).with_cause(error)])
+
+
+def _validate_no_symlinks(path: Path, root: ProjectRootPath) -> Result[None]:  # noqa: CCR001
+    """Reject links below the resolved root before resolving the target."""
+    candidate = path.absolute()
+    current = Path(candidate.anchor)
+    for part in candidate.parts[1:]:
+        current = current.parent if part == ".." else current / part
+        if current == root or not current.is_relative_to(root):
+            # Root aliases and symlinks above the chosen root remain supported.
+            current = current.resolve()
+            continue
+        try:
+            mode = current.lstat().st_mode
+        except (FileNotFoundError, NotADirectoryError):
+            continue
+        if stat.S_ISLNK(mode):
+            return Err([InvalidProjectPath(path=str(path))])
+    return Ok(None)
+
+
+@unwrap_to_error
+def resolve_inside_project(path: Path, root: ProjectRootPath) -> Result[ResolvedProjectPath]:
+    """Resolve a filesystem path and require it to be strictly below the root.
+
+    The root must already be resolved. Relative paths use the process working
+    directory; callers choose any other base before calling. Do not expand
+    home markers or require an existing target.
+    """
+    try:
+        _validate_no_symlinks(path, root).unwrap()
+        resolved = path.resolve()
+    except (OSError, RuntimeError) as error:
+        return Err([PathResolutionFailed(path=str(path), reason=str(error)).with_cause(error)])
+
+    if resolved == root or not resolved.is_relative_to(root):
+        return Err([InvalidProjectPath(path=str(path))])
+
+    return Ok(ResolvedProjectPath(resolved))
+
+
+@unwrap_to_error
+def resolve_root_anchored_path(value: str, root: ProjectRootPath) -> Result[ResolvedProjectPath]:
+    """Normalize an ``@/`` identifier and resolve it strictly below the root.
+
+    The root must already be resolved. Normalize identifier segments before
+    resolving symlinks and checking containment, without requiring an existing
+    target. Preserve lexical and filesystem resolution diagnostics.
+    """
+    normalized = normalize_project_path_id(value).unwrap()
+    path = root.joinpath(*project_path_parts(normalized))
+    return resolve_inside_project(path, root)

llm_tool_cli/paths/globs.py

@@ -0,0 +1,124 @@
+"""Shared project glob preparation, matching, and named captures."""
+
+import fnmatch
+import glob
+import os.path
+import re
+from pathlib import Path
+from typing import NewType
+
+from llm_tool_cli.core.result import Err, Ok, Result, unwrap_to_error
+from llm_tool_cli.paths.errors import InvalidGlobPattern, InvalidProjectPath, PathResolutionFailed
+from llm_tool_cli.paths.filesystem import (
+    ProjectRootPath,
+    _project_path_input,
+    _validate_no_symlinks,
+    resolve_project_root,
+)
+from llm_tool_cli.paths.normalization import ProjectPathId, project_path_parts
+
+FileGlobPattern = NewType("FileGlobPattern", str)
+"""A supplied filesystem glob without validity or containment guarantees."""
+
+
+@unwrap_to_error
+def _pattern_parts(pattern: FileGlobPattern, root: ProjectRootPath) -> Result[tuple[str, ...]]:
+    """Resolve the literal prefix without treating glob syntax as filenames."""
+    candidate = _project_path_input(pattern, root).unwrap()
+    parts = candidate.parts
+    start = len(root.parts) if candidate.is_relative_to(root) else 0
+    first_magic = next((index for index in range(start, len(parts)) if glob.has_magic(parts[index])), len(parts))
+    prefix = Path(*parts[:first_magic])
+    try:
+        _validate_no_symlinks(prefix, root).unwrap()
+        resolved = prefix.resolve().joinpath(*parts[first_magic:])
+    except (OSError, RuntimeError) as error:
+        return Err([PathResolutionFailed(path=str(candidate), reason=str(error)).with_cause(error)])
+    normalized = Path(os.path.normpath(resolved))
+    if normalized == root or not normalized.is_relative_to(root):
+        return Err([InvalidProjectPath(path=str(candidate))])
+    return Ok(normalized.relative_to(root).parts)
+
+
+def _compile_glob(pattern: FileGlobPattern) -> Result[tuple[re.Pattern[str], bool]]:  # noqa: CCR001, TAE002
+    """Compile path syntax and report whether it can cross directory boundaries."""
+    regex: list[str] = []
+    recursive = False
+    index = 0
+    while index < len(pattern):
+        character = pattern[index]
+        if character == "[":
+            end = index + 1
+            if end < len(pattern) and pattern[end] == "!":
+                end += 1
+            if end < len(pattern) and pattern[end] == "]":
+                end += 1
+            end = pattern.find("]", end)
+            if end != -1 and "/" not in pattern[index : end + 1]:
+                # Delegate character-class rules (including escaping and invalid
+                # ranges) to fnmatch, removing its whole-string wrapper.
+                translated = fnmatch.translate(pattern[index : end + 1])
+                regex.append("(?!/)" + translated[4:-3])
+                index = end + 1
+                continue
+
+        if character == "{" and pattern[index + 1 : index + 2] == "*":
+            end = pattern.find("}", index)
+            if end == -1:
+                return Err([InvalidGlobPattern(pattern=pattern, reason="unclosed capture")])
+            token = pattern[index + 1 : end]
+            wildcard = "**" if token.startswith("**") else "*"
+            name = token[len(wildcard) :]
+            if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name) is None:
+                return Err([InvalidGlobPattern(pattern=pattern, reason=f"invalid capture name `{name}`")])
+            index = end + 1
+            if wildcard == "**":
+                recursive = True
+                if pattern[index : index + 1] == "/":
+                    regex.append(f"(?:(?P<{name}>.*)/)?")
+                    index += 1
+                else:
+                    regex.append(f"(?P<{name}>.*)")
+            else:
+                regex.append(f"(?P<{name}>[^/]*)")
+            continue
+
+        if pattern[index : index + 2] == "**":
+            recursive = True
+            index += 2
+            if pattern[index : index + 1] == "/":
+                regex.append("(?:.*/)?")
+                index += 1
+            else:
+                regex.append(".*")
+            continue
+
+        regex.append("[^/]*" if character == "*" else "[^/]" if character == "?" else re.escape(character))
+        index += 1
+
+    try:
+        return Ok((re.compile("".join(regex), re.DOTALL), recursive))
+    except re.error as error:
+        return Err([InvalidGlobPattern(pattern=pattern, reason=str(error)).with_cause(error)])
+
+
+@unwrap_to_error
+def glob_capture_names(pattern: FileGlobPattern) -> Result[set[str]]:
+    """Validate glob syntax and collect capture names without filesystem access."""
+    compiled, _ = _compile_glob(pattern).unwrap()
+    return Ok(set(compiled.groupindex))
+
+
+@unwrap_to_error
+def match_glob(path: ProjectPathId, pattern: FileGlobPattern, root: Path) -> Result[dict[str, str] | None]:
+    """Match an already normalized identifier, including a missing reference.
+
+    Only the pattern's literal prefix is resolved against the filesystem.
+    Return captured strings (empty for omitted recursive directories), an empty
+    dictionary for a match without captures, or None for a non-match.
+    """
+    project_root = resolve_project_root(root).unwrap()
+    parts = _pattern_parts(pattern, project_root).unwrap()
+    compiled, _ = _compile_glob(FileGlobPattern("/".join(parts))).unwrap()
+    match = compiled.fullmatch("/".join(project_path_parts(path)))
+    return Ok({name: value or "" for name, value in match.groupdict().items()} if match else None)

llm_tool_cli/paths/normalization.py

@@ -0,0 +1,58 @@
+"""Lexical operations on project-path identifiers."""
+
+from typing import NewType
+
+from llm_tool_cli.core.result import Err, Ok, Result
+from llm_tool_cli.paths.errors import InvalidProjectPath
+
+ProjectPathId = NewType("ProjectPathId", str)
+
+_PROJECT_ROOT_PREFIX = "@/"
+
+
+def normalize_project_path_id(value: str) -> Result[ProjectPathId]:
+    """Normalize a root-anchored identifier without accessing the filesystem.
+
+    Remove ``.`` and resolve ``..`` lexically. Reject missing ``@/``, empty
+    segments, traversal above the root, and a final root-only identifier with
+    ``Err([InvalidProjectPath(...)])``. Preserve all other segment text.
+    """
+    if not value.startswith(_PROJECT_ROOT_PREFIX):
+        return Err([InvalidProjectPath(path=value)])
+
+    parts: list[str] = []
+    for part in value.removeprefix(_PROJECT_ROOT_PREFIX).split("/"):
+        match part:
+            case "":
+                return Err([InvalidProjectPath(path=value)])
+            case ".":
+                continue
+            case "..":
+                if not parts:
+                    return Err([InvalidProjectPath(path=value)])
+                parts.pop()
+            case _:
+                parts.append(part)
+
+    if not parts:
+        return Err([InvalidProjectPath(path=value)])
+
+    return Ok(ProjectPathId(_PROJECT_ROOT_PREFIX + "/".join(parts)))
+
+
+def is_project_path_id(value: object) -> bool:
+    """Check whether an input is already a canonical project-path identifier.
+
+    Return false for non-strings and values requiring lexical normalization.
+    Do not access the filesystem or apply application-specific rules.
+    """
+    return isinstance(value, str) and normalize_project_path_id(value).ok() == value
+
+
+def project_path_parts(value: ProjectPathId) -> tuple[str, ...]:
+    """Return the components of an already canonical project-path identifier.
+
+    The caller must establish canonical form before calling. Preserve segment
+    text without filesystem access or repeated normalization and validation.
+    """
+    return tuple(value.removeprefix(_PROJECT_ROOT_PREFIX).split("/"))

llm_tool_cli/paths/tests/test_enumeration.py

@@ -0,0 +1,229 @@
+import glob
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+from pytest_mock import MockerFixture
+
+from llm_tool_cli.paths import FileGlobPattern, ProjectPathId, enumerate_files, match_glob
+from llm_tool_cli.paths.enumeration import _glob_files, _walk_files
+from llm_tool_cli.paths.errors import FilesUnreadable, InvalidGlobPattern, InvalidProjectPath, PathResolutionFailed
+
+
+class TestWalkFiles:
+    def test_only_regular_files_without_following_links(self, tmp_path: Path) -> None:
+        (tmp_path / "nested").mkdir()
+        (tmp_path / "nested/file").touch()
+        (tmp_path / "cycle").symlink_to(tmp_path)
+        (tmp_path / "link").symlink_to(tmp_path / "nested/file")
+        (tmp_path / "broken").symlink_to(tmp_path / "missing")
+
+        assert list(_walk_files(tmp_path)) == [tmp_path / "nested/file"]
+        assert list(_walk_files(tmp_path / "missing")) == []
+        assert list(_walk_files(tmp_path / "nested/file/child")) == []
+
+
+class TestGlobFiles:
+    def test_recursive_patterns_dedicated_components(self, tmp_path: Path) -> None:
+        (tmp_path / "nested").mkdir()
+        (tmp_path / "nested/a.py").touch()
+        (tmp_path / "b.py").touch()
+        (tmp_path / "broken.py").symlink_to(tmp_path / "absent")
+
+        assert sorted(_glob_files(tmp_path, ("**", "*.py"))) == [tmp_path / "b.py", tmp_path / "nested/a.py"]
+
+    def test_missing_or_non_directory_prefix_has_no_matches(self, tmp_path: Path) -> None:
+        (tmp_path / "file").touch()
+
+        assert list(_glob_files(tmp_path / "missing", ("*",))) == []
+        assert list(_glob_files(tmp_path / "file/child", ("*",))) == []
+        assert list(_glob_files(tmp_path / "file", ("*",))) == []
+
+
+class TestEnumerateFiles:
+    @pytest.mark.parametrize(
+        "pattern",
+        [
+            "**/*",
+            "**",
+            "**/**",
+            "src/[ab].py",
+            "src/[!b]*.py",
+            "src/a**.py",
+            "src/{*module}.py",
+            "src/{**module}.py",
+            "{**directory}/{*file}",
+            "src/star[*].py",
+            "src/**/a?.py",
+            "src/[[]literal].py",
+            "src/a.py/**",
+            "src/[**].py",
+            "src/[a/nested].py",
+            "src/Case.py",
+            "src/[!x]*.py",
+        ],
+    )
+    def test_enumeration_and_matching_share_the_same_grammar(self, tmp_path: Path, pattern: str) -> None:
+        names = [
+            "src/a.py",
+            "src/b.py",
+            "src/a/nested.py",
+            "src/.hidden/a1.py",
+            "src/.hidden.py",
+            "src/star*.py",
+            "src/[literal].py",
+            "src/line\nbreak.py",
+            "src/*.py",
+            "src/case.py",
+            "docs/a.py",
+            "root.txt",
+        ]
+        for name in names:
+            path = tmp_path / name
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.touch()
+        pattern_value = FileGlobPattern(pattern)
+        expected = [
+            "@/" + name
+            for name in sorted(names, key=lambda name: Path(name).parts)
+            if match_glob(ProjectPathId("@/" + name), pattern_value, tmp_path).unwrap() is not None
+        ]
+
+        assert enumerate_files(tmp_path, pattern_value).unwrap() == expected
+
+    def test_recursive_captures_and_embedded_wildcards_select_nested_files(self, tmp_path: Path) -> None:
+        (tmp_path / "a").mkdir()
+        (tmp_path / "a/nested.py").touch()
+        (tmp_path / "a.py").touch()
+
+        for pattern in ["a**.py", "{**module}.py"]:
+            assert enumerate_files(tmp_path, FileGlobPattern(pattern)).unwrap() == ["@/a/nested.py", "@/a.py"]
+
+    @pytest.mark.parametrize("pattern", ["{*bad-name}", "{*name}/{*name}", "{*unclosed"])
+    def test_invalid_captures_fail_even_in_an_empty_directory(self, tmp_path: Path, pattern: str) -> None:
+        assert enumerate_files(tmp_path, FileGlobPattern(pattern)).is_err(InvalidGlobPattern)
+
+    def test_nonmatching_directories_are_not_traversed(self, tmp_path: Path, mocker: MockerFixture) -> None:
+        (tmp_path / "src").mkdir()
+        (tmp_path / "src/file.py").touch()
+        (tmp_path / "unrelated").mkdir()
+        iterdir = Path.iterdir
+
+        def read_directory(path: Path) -> Iterator[Path]:
+            if path == tmp_path / "unrelated":
+                raise PermissionError("must not traverse unrelated directory")
+            return iterdir(path)
+
+        mocker.patch.object(Path, "iterdir", autospec=True, side_effect=read_directory)
+
+        assert enumerate_files(tmp_path, FileGlobPattern("s?c/**/*.py")).unwrap() == ["@/src/file.py"]
+
+    def test_wildcards_do_not_resolve_literal_symlink_names(self, tmp_path: Path) -> None:
+        (tmp_path / "ordinary").touch()
+        (tmp_path / "*").symlink_to(tmp_path)
+        (tmp_path / "**").symlink_to(tmp_path)
+
+        assert enumerate_files(tmp_path).unwrap() == ["@/ordinary"]
+
+    @pytest.mark.parametrize("pattern", ["**/*", "@/**/*", "**", "**/**"])
+    def test_unique_files_in_component_order_including_hidden_entries(self, tmp_path: Path, pattern: str) -> None:
+        names = ["a/child", "a.txt", ".hidden/file", ".hidden-file", "z"]
+        for name in names:
+            path = tmp_path / name
+            path.parent.mkdir(exist_ok=True)
+            path.touch()
+        (tmp_path / "empty").mkdir()
+
+        assert enumerate_files(tmp_path, FileGlobPattern(pattern)).unwrap() == [
+            "@/.hidden/file",
+            "@/.hidden-file",
+            "@/a/child",
+            "@/a.txt",
+            "@/z",
+        ]
+
+    @pytest.mark.parametrize("pattern", ["**/*.py", "@/**/*.py", "**/a?.[pt][xy]", "**/[!b]*.py"])
+    def test_glob_syntax_and_zero_directory_recursion(self, tmp_path: Path, pattern: str) -> None:
+        (tmp_path / "nested").mkdir()
+        for name in ["a1.py", "nested/a2.py", "b.txt"]:
+            (tmp_path / name).touch()
+
+        assert enumerate_files(tmp_path, FileGlobPattern(pattern)).unwrap() == ["@/a1.py", "@/nested/a2.py"]
+
+    @pytest.mark.parametrize("pattern", ["**/*", "**", "*.py", "*/**/*"])
+    def test_skips_all_discovered_links(self, tmp_path: Path, pattern: str) -> None:
+        project = tmp_path / "project"
+        project.mkdir()
+        target = tmp_path / "outside"
+        target.mkdir()
+        (target / "outside.py").touch()
+        (project / "ordinary.py").touch()
+        for name, destination in [
+            ("file.py", project / "ordinary.py"),
+            ("external.py", target / "outside.py"),
+            ("directory", target),
+            ("cycle", project),
+            ("broken.py", project / "missing"),
+        ]:
+            (project / name).symlink_to(destination)
+
+        expected = [] if pattern == "*/**/*" else ["@/ordinary.py"]
+        assert enumerate_files(project, FileGlobPattern(pattern)).unwrap() == expected
+
+    @pytest.mark.parametrize("suffix", ["", "/**/*", "/../ordinary"])
+    def test_rejects_explicit_symlink_prefix(self, tmp_path: Path, suffix: str) -> None:
+        (tmp_path / "link").symlink_to(tmp_path)
+        result = enumerate_files(tmp_path, FileGlobPattern("link" + suffix))
+
+        assert result.is_err(InvalidProjectPath)
+
+    def test_missing_directory_or_file_root_produces_no_files(self, tmp_path: Path) -> None:
+        (tmp_path / "file").touch()
+
+        assert enumerate_files(tmp_path, FileGlobPattern("missing/**/*")).unwrap() == []
+        assert enumerate_files(tmp_path / "missing").unwrap() == []
+        assert enumerate_files(tmp_path / "file").unwrap() == []
+
+    def test_literal_pattern_and_escaped_metacharacters(self, tmp_path: Path) -> None:
+        directory = tmp_path / "[work]*?"
+        directory.mkdir()
+        (directory / "file.py").touch()
+
+        assert enumerate_files(tmp_path, FileGlobPattern(glob.escape(directory.name) + "/file.py")).unwrap() == [
+            "@/[work]*?/file.py"
+        ]
+
+    def test_absolute_and_home_patterns(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("HOME", str(tmp_path))
+        (tmp_path / "file.py").touch()
+
+        assert enumerate_files(tmp_path, FileGlobPattern(str(tmp_path / "*.py"))).unwrap() == ["@/file.py"]
+        assert enumerate_files(tmp_path, FileGlobPattern("~/*.py")).unwrap() == ["@/file.py"]
+
+    @pytest.mark.parametrize("pattern", ["../*", "@/../*", "@/", "@/a//b", "."])
+    def test_invalid_patterns_preserve_diagnostics(self, tmp_path: Path, pattern: str) -> None:
+        assert enumerate_files(tmp_path, FileGlobPattern(pattern)).is_err(InvalidProjectPath)
+
+    def test_root_resolution_failure_precedes_pattern_processing(self, tmp_path: Path) -> None:
+        root = tmp_path / "loop"
+        root.symlink_to(root)
+
+        assert enumerate_files(root, FileGlobPattern("@/../*")).is_err(PathResolutionFailed)
+
+    def test_directory_read_failure_is_not_an_empty_result(self, tmp_path: Path, mocker: MockerFixture) -> None:
+        cause = PermissionError("cannot list directory")
+        mocker.patch.object(Path, "iterdir", side_effect=cause)
+
+        failure = enumerate_files(tmp_path).unwrap_err()[0]
+
+        assert isinstance(failure, FilesUnreadable)
+        assert failure.code == "files_unreadable"
+        assert failure.path == str(tmp_path)
+        assert failure.cause == cause
+        assert "cause" not in failure.as_record()
+
+    def test_unexpected_failure_remains_an_exception(self, tmp_path: Path, mocker: MockerFixture) -> None:
+        mocker.patch.object(Path, "iterdir", side_effect=ValueError("unexpected failure"))
+
+        with pytest.raises(ValueError, match="unexpected failure"):
+            enumerate_files(tmp_path)