vcti-path 1.0.3__tar.gz

vcti_path-1.0.3/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_path-1.0.3/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: vcti-path
+Version: 1.0.3
+Summary: Safe path handling for VCollab applications
+Author: Visual Collaboration Technologies Inc.
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Dynamic: license-file
+
+# Path Utilities
+
+## Purpose
+
+Safe path handling for VCollab applications -- filename validation, file
+identity (POSIX-style relative paths as stable IDs), and path resolution
+with access validation.
+
+This package has **zero external dependencies**.
+
+---
+
+## Installation
+
+```bash
+pip install vcti-path
+```
+
+### In `requirements.txt`
+
+```
+vcti-path>=1.0.3
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-path>=1.0.3",
+]
+```
+
+---
+
+## Quick Start
+
+### Validate filenames
+
+```python
+from vcti.path import FileNameValidator
+
+FileNameValidator.is_valid("report.pdf")     # True
+FileNameValidator.is_valid("bad|name")       # False
+FileNameValidator.is_valid("..")             # False
+
+FileNameValidator.validate("data.json")      # OK
+FileNameValidator.validate("bad/name")       # Raises ValueError
+```
+
+### File IDs -- stable POSIX-style identifiers
+
+A file ID is a POSIX-format relative path that uniquely identifies a
+file or directory within a base directory. No leading `/`, `./`, or `../`.
+
+```python
+from pathlib import Path
+from vcti.path import FileId
+
+# Validate
+FileId.is_valid("scripts/setup.sh")     # True
+FileId.is_valid("/absolute/path")       # False
+FileId.is_valid("../escape")            # False
+
+# Resolve to filesystem path
+base = Path("/project")
+FileId.resolve_path("src/main.py", base)
+# -> Path("/project/src/main.py")
+
+# Extract file ID from a path
+src = Path("/project/src/main.py")
+FileId.get_file_id(src, base)
+# -> "src/main.py"
+```
+
+### Path resolution and access validation
+
+```python
+from vcti.path import abs_path, validate_file_access, resolve_path
+
+# Absolute path resolution
+abs_path("relative/file.txt")
+# -> Path("<cwd>/relative/file.txt")
+
+# Validate that a file exists and is readable
+validate_file_access("config.yaml")
+# Raises FileNotFoundError, IsADirectoryError, or PermissionError
+
+# Resolve relative to a base directory
+resolve_path("data/input.csv", "/project")
+# -> Path("/project/data/input.csv")
+```
+
+---
+
+## Public API
+
+| Symbol | Type | Purpose |
+|--------|------|---------|
+| `FileNameValidator.is_valid(name)` | classmethod | Check if a filename is valid |
+| `FileNameValidator.validate(name)` | classmethod | Validate filename, raise `ValueError` if invalid |
+| `FileId.is_valid(file_id)` | staticmethod | Check if a POSIX file ID is valid |
+| `FileId.validate(file_id)` | staticmethod | Validate file ID, raise `ValueError` if invalid |
+| `FileId.resolve_path(file_id, base_dir)` | staticmethod | Resolve file ID to absolute path |
+| `FileId.get_file_id(file_path, base_dir)` | staticmethod | Extract file ID from absolute path |
+| `abs_path(fp)` | function | Convert to absolute resolved `Path` |
+| `validate_file_access(fp)` | function | Validate file exists and is readable |
+| `validate_folder_access(fp)` | function | Validate directory exists |
+| `resolve_path(path, base_dir)` | function | Resolve path relative to base directory |
+
+---
+
+## Documentation
+
+- [Design](docs/design.md) -- Concepts, architecture decisions, and rationale
+- [Source Guide](docs/source-guide.md) -- File descriptions and execution flow traces
+- [API Reference](docs/api.md) -- Autodoc for all modules

vcti_path-1.0.3/README.md

@@ -0,0 +1,116 @@
+# Path Utilities
+
+## Purpose
+
+Safe path handling for VCollab applications -- filename validation, file
+identity (POSIX-style relative paths as stable IDs), and path resolution
+with access validation.
+
+This package has **zero external dependencies**.
+
+---
+
+## Installation
+
+```bash
+pip install vcti-path
+```
+
+### In `requirements.txt`
+
+```
+vcti-path>=1.0.3
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-path>=1.0.3",
+]
+```
+
+---
+
+## Quick Start
+
+### Validate filenames
+
+```python
+from vcti.path import FileNameValidator
+
+FileNameValidator.is_valid("report.pdf")     # True
+FileNameValidator.is_valid("bad|name")       # False
+FileNameValidator.is_valid("..")             # False
+
+FileNameValidator.validate("data.json")      # OK
+FileNameValidator.validate("bad/name")       # Raises ValueError
+```
+
+### File IDs -- stable POSIX-style identifiers
+
+A file ID is a POSIX-format relative path that uniquely identifies a
+file or directory within a base directory. No leading `/`, `./`, or `../`.
+
+```python
+from pathlib import Path
+from vcti.path import FileId
+
+# Validate
+FileId.is_valid("scripts/setup.sh")     # True
+FileId.is_valid("/absolute/path")       # False
+FileId.is_valid("../escape")            # False
+
+# Resolve to filesystem path
+base = Path("/project")
+FileId.resolve_path("src/main.py", base)
+# -> Path("/project/src/main.py")
+
+# Extract file ID from a path
+src = Path("/project/src/main.py")
+FileId.get_file_id(src, base)
+# -> "src/main.py"
+```
+
+### Path resolution and access validation
+
+```python
+from vcti.path import abs_path, validate_file_access, resolve_path
+
+# Absolute path resolution
+abs_path("relative/file.txt")
+# -> Path("<cwd>/relative/file.txt")
+
+# Validate that a file exists and is readable
+validate_file_access("config.yaml")
+# Raises FileNotFoundError, IsADirectoryError, or PermissionError
+
+# Resolve relative to a base directory
+resolve_path("data/input.csv", "/project")
+# -> Path("/project/data/input.csv")
+```
+
+---
+
+## Public API
+
+| Symbol | Type | Purpose |
+|--------|------|---------|
+| `FileNameValidator.is_valid(name)` | classmethod | Check if a filename is valid |
+| `FileNameValidator.validate(name)` | classmethod | Validate filename, raise `ValueError` if invalid |
+| `FileId.is_valid(file_id)` | staticmethod | Check if a POSIX file ID is valid |
+| `FileId.validate(file_id)` | staticmethod | Validate file ID, raise `ValueError` if invalid |
+| `FileId.resolve_path(file_id, base_dir)` | staticmethod | Resolve file ID to absolute path |
+| `FileId.get_file_id(file_path, base_dir)` | staticmethod | Extract file ID from absolute path |
+| `abs_path(fp)` | function | Convert to absolute resolved `Path` |
+| `validate_file_access(fp)` | function | Validate file exists and is readable |
+| `validate_folder_access(fp)` | function | Validate directory exists |
+| `resolve_path(path, base_dir)` | function | Resolve path relative to base directory |
+
+---
+
+## Documentation
+
+- [Design](docs/design.md) -- Concepts, architecture decisions, and rationale
+- [Source Guide](docs/source-guide.md) -- File descriptions and execution flow traces
+- [API Reference](docs/api.md) -- Autodoc for all modules

vcti_path-1.0.3/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-path"
+version = "1.0.3"
+description = "Safe path handling for VCollab applications"
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12,<3.15"
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.path", "vcti.path.*"]
+
+[tool.setuptools]
+zip-safe = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.path --cov-report=term-missing --cov-fail-under=95"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_path-1.0.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_path-1.0.3/src/vcti/path/__init__.py

@@ -0,0 +1,25 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Safe path handling for VCollab applications.
+
+Provides filename validation, file identity (POSIX-style relative paths
+as stable IDs), and path resolution with access validation.
+"""
+
+from importlib.metadata import version
+
+from .file_id_utils import FileId
+from .filename_validator import FileNameValidator
+from .path_utils import abs_path, resolve_path, validate_file_access, validate_folder_access
+
+__version__ = version("vcti-path")
+
+__all__ = [
+    "__version__",
+    "FileNameValidator",
+    "FileId",
+    "abs_path",
+    "validate_file_access",
+    "validate_folder_access",
+    "resolve_path",
+]

vcti_path-1.0.3/src/vcti/path/file_id_utils.py

@@ -0,0 +1,160 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Utilities for validating and resolving file identifiers relative to a base directory."""
+
+from pathlib import Path
+
+from .filename_validator import FileNameValidator
+
+
+class FileId:
+    """
+    Utilities to work with file identifiers--POSIX-style relative paths
+    representing files or directories inside a base directory.
+
+    Rules for a valid file ID:
+    - Must not start with "/", "./", "../"
+    - Must use "/" as the path separator (POSIX format)
+    - Each part must be a valid file/folder name (see FileNameValidator)
+
+    Example:
+        file_id = "scripts/setup.sh"  -> base_dir / "scripts/setup.sh"
+
+    This utility supports:
+    - Validating file IDs
+    - Resolving file IDs to full paths
+    - Extracting file IDs from full paths
+    """
+
+    @staticmethod
+    def is_valid(file_id: str) -> bool:
+        """
+        Check if a file ID is valid.
+
+        Args:
+            file_id (str): A relative POSIX-style file ID.
+
+        Returns:
+            bool: True if valid, False otherwise.
+        """
+        if not isinstance(file_id, str):
+            raise TypeError(f"file_id must be a str, got {type(file_id).__name__}")
+
+        if not file_id or file_id.strip() == "":
+            return False
+
+        if file_id.startswith(("/", "./", "../")):
+            return False
+
+        if file_id.endswith("/") and len(file_id) > 1:
+            file_id = file_id.rstrip("/")
+
+        parts = file_id.split("/")
+        return all(FileNameValidator.is_valid(part) for part in parts)
+
+    @staticmethod
+    def validate(file_id: str) -> None:
+        """
+        Validate a file ID and raise ValueError if invalid.
+
+        Args:
+            file_id (str): File ID to validate.
+
+        Raises:
+            TypeError: If file_id is not a str.
+            ValueError: If the file ID is invalid.
+        """
+        if not FileId.is_valid(file_id):
+            raise ValueError(f"Invalid file ID: '{file_id}'")
+
+    @staticmethod
+    def resolve_path(
+        file_id: str | None,
+        base_dir: Path,
+        *,
+        must_exist: bool = False,
+        must_be_dir: bool = False,
+        must_be_file: bool = False,
+    ) -> Path:
+        """
+        Resolve a file ID to an absolute path inside the base directory.
+
+        Args:
+            file_id: Relative file ID in POSIX format. If None or empty string,
+                returns base_dir.
+            base_dir: The root directory to resolve from.
+            must_exist: Raise FileNotFoundError if path doesn't exist.
+            must_be_dir: Raise NotADirectoryError if path isn't a directory.
+            must_be_file: Raise IsADirectoryError if path isn't a file.
+
+        Returns:
+            Path: Absolute resolved path.
+
+        Raises:
+            ValueError: If file ID is invalid.
+            RuntimeError: If resolved path is a symbolic link.
+            FileNotFoundError, NotADirectoryError, IsADirectoryError: Based on flags.
+
+        Note:
+            Symbolic links are rejected to prevent escaping the base directory.
+            For general-purpose path validation that follows symlinks, use
+            ``validate_file_access`` or ``validate_folder_access`` instead.
+        """
+        # Validate file ID before joining to base_dir
+        if file_id:
+            FileId.validate(file_id)
+
+        target = base_dir.joinpath(Path(file_id)) if file_id else base_dir
+
+        if must_exist and not target.exists():
+            raise FileNotFoundError(f"Path does not exist: {target}")
+
+        if target.exists():
+            if target.is_symlink():
+                raise RuntimeError(f"Symbolic links are not supported: {target}")
+            if must_be_dir and not target.is_dir():
+                raise NotADirectoryError(f"Expected a directory: {target}")
+            if must_be_file and not target.is_file():
+                raise IsADirectoryError(f"Expected a file: {target}")
+
+        return target
+
+    @staticmethod
+    def get_file_id(file_path: Path, base_dir: Path) -> str:
+        """
+        Get the POSIX-style file ID for a file path inside the base directory.
+
+        Args:
+            file_path: The absolute or relative path to convert.
+            base_dir: The root directory to compute relative to.
+
+        Returns:
+            str: File ID in POSIX format.
+
+        Raises:
+            TypeError: If file_path or base_dir is not a Path.
+            ValueError: If file_path is outside the base_dir.
+        """
+        if not isinstance(file_path, Path):
+            raise TypeError(f"file_path must be a Path, got {type(file_path).__name__}")
+        if not isinstance(base_dir, Path):
+            raise TypeError(f"base_dir must be a Path, got {type(base_dir).__name__}")
+
+        try:
+            rel_path = file_path.relative_to(base_dir)
+        except ValueError:
+            raise ValueError(f"Path '{file_path}' is not under base directory '{base_dir}'")
+
+        if rel_path == Path("."):
+            return ""
+
+        parts = rel_path.parts
+        for part in parts:
+            FileNameValidator.validate(part)
+
+        file_id = rel_path.as_posix()
+
+        if file_path.exists() and file_path.is_dir() and rel_path != Path("."):
+            return file_id + "/"
+
+        return file_id

vcti_path-1.0.3/src/vcti/path/filename_validator.py

@@ -0,0 +1,69 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Utility class for validating file and folder names."""
+
+import re
+
+
+class FileNameValidator:
+    """
+    Validates basic file or folder names based on common restrictions.
+
+    Rules:
+    - Must not be "." or ".."
+    - Must not be empty or whitespace only
+    - Must not contain illegal characters: / \\ : * ? " < > |
+
+    This class is useful for validating user-supplied names for files or
+    directories before creating them on the filesystem.
+
+    Example:
+        >>> FileNameValidator.is_valid("file.txt")        # Returns True
+        >>> FileNameValidator.is_valid("invalid|file")    # Returns False
+        >>> FileNameValidator.validate("data.json")       # OK
+        >>> FileNameValidator.validate("bad/name")        # Raises ValueError
+    """
+
+    INVALID_CHARS = r'<>:"/\\|?*'
+    INVALID_PATTERN = re.compile(rf"[{re.escape(INVALID_CHARS)}]")
+    RESERVED_NAMES = {".", ".."}
+
+    @classmethod
+    def is_valid(cls, name: str) -> bool:
+        """
+        Returns whether the given file or folder name is valid.
+
+        Args:
+            name (str): Name to check.
+
+        Returns:
+            bool: True if valid, False otherwise.
+        """
+        if not isinstance(name, str):
+            raise TypeError(f"name must be a str, got {type(name).__name__}")
+
+        if not name or name.strip() == "":
+            return False
+
+        if name in cls.RESERVED_NAMES:
+            return False
+
+        if cls.INVALID_PATTERN.search(name):
+            return False
+
+        return True
+
+    @classmethod
+    def validate(cls, name: str) -> None:
+        """
+        Validates the given file or folder name.
+
+        Args:
+            name (str): The filename to validate.
+
+        Raises:
+            TypeError: If name is not a str.
+            ValueError: If the name is reserved, empty, or contains illegal characters.
+        """
+        if not cls.is_valid(name):
+            raise ValueError(f"Invalid file or directory name: {name!r}")

vcti_path-1.0.3/src/vcti/path/path_utils.py

@@ -0,0 +1,111 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Utility functions for handling file and folder paths."""
+
+import errno
+import os
+from pathlib import Path
+
+
+def abs_path(fp: Path | str) -> Path:
+    """
+    Converts a given file path to an absolute, resolved `Path` object.
+
+    Args:
+        fp: The input file path.
+
+    Returns:
+        Path: The absolute resolved file path.
+    """
+    return Path(fp).resolve()
+
+
+def validate_file_access(fp: Path | str) -> None:
+    """
+    Validates that the specified file path exists and is a readable file.
+
+    Args:
+        fp: The file path to validate.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        IsADirectoryError: If the path points to a directory instead of a file.
+        PermissionError: If the file exists but is not readable.
+    """
+    path = Path(fp)
+
+    if not path.exists():
+        raise FileNotFoundError(errno.ENOENT, os.strerror(errno.ENOENT), str(path))
+
+    if path.is_dir():
+        raise IsADirectoryError(errno.EISDIR, os.strerror(errno.EISDIR), str(path))
+
+    if not path.is_file():
+        raise FileNotFoundError(errno.ENOENT, os.strerror(errno.ENOENT), str(path))
+
+    if not os.access(path, os.R_OK):
+        raise PermissionError(errno.EACCES, os.strerror(errno.EACCES), str(path))
+
+
+def validate_folder_access(fp: Path | str) -> None:
+    """
+    Validates that the specified folder path exists and is a directory.
+
+    Args:
+        fp: The folder path to validate.
+
+    Raises:
+        FileNotFoundError: If the directory does not exist.
+        NotADirectoryError: If the path is not a directory.
+    """
+    path = Path(fp)
+
+    if not path.exists():
+        raise FileNotFoundError(errno.ENOENT, os.strerror(errno.ENOENT), str(path))
+
+    if not path.is_dir():
+        raise NotADirectoryError(errno.ENOTDIR, os.strerror(errno.ENOTDIR), str(path))
+
+
+def resolve_path(path: Path | str, base_dir: Path | str) -> Path:
+    """
+    Resolves a path relative to a base directory, handling both absolute and relative paths.
+
+    Args:
+        path: The path to resolve (absolute or relative)
+        base_dir: The base directory for relative path resolution
+
+    Returns:
+        Path: The fully resolved absolute path
+
+    Raises:
+        FileNotFoundError: If the base_dir does not exist
+        NotADirectoryError: If base_dir is not a directory
+
+    Note:
+        This function does not prevent directory traversal via ``..``.
+        For untrusted input that must stay within a base directory, use
+        ``FileId.resolve_path`` which validates the path format first.
+    """
+    if not isinstance(path, (str, Path)):
+        raise TypeError(f"path must be a str or Path, got {type(path).__name__}")
+    if not isinstance(base_dir, (str, Path)):
+        raise TypeError(f"base_dir must be a str or Path, got {type(base_dir).__name__}")
+
+    path = Path(path) if isinstance(path, str) else path
+    base_dir = Path(base_dir) if isinstance(base_dir, str) else base_dir
+
+    # Resolve the path
+    if not path.is_absolute():
+        validate_folder_access(base_dir)
+        path = base_dir / path
+
+    return path.resolve()
+
+
+__all__ = [
+    "abs_path",
+    "validate_file_access",
+    "validate_folder_access",
+    "resolve_path",
+]

vcti_path-1.0.3/src/vcti_path.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: vcti-path
+Version: 1.0.3
+Summary: Safe path handling for VCollab applications
+Author: Visual Collaboration Technologies Inc.
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Dynamic: license-file
+
+# Path Utilities
+
+## Purpose
+
+Safe path handling for VCollab applications -- filename validation, file
+identity (POSIX-style relative paths as stable IDs), and path resolution
+with access validation.
+
+This package has **zero external dependencies**.
+
+---
+
+## Installation
+
+```bash
+pip install vcti-path
+```
+
+### In `requirements.txt`
+
+```
+vcti-path>=1.0.3
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-path>=1.0.3",
+]
+```
+
+---
+
+## Quick Start
+
+### Validate filenames
+
+```python
+from vcti.path import FileNameValidator
+
+FileNameValidator.is_valid("report.pdf")     # True
+FileNameValidator.is_valid("bad|name")       # False
+FileNameValidator.is_valid("..")             # False
+
+FileNameValidator.validate("data.json")      # OK
+FileNameValidator.validate("bad/name")       # Raises ValueError
+```
+
+### File IDs -- stable POSIX-style identifiers
+
+A file ID is a POSIX-format relative path that uniquely identifies a
+file or directory within a base directory. No leading `/`, `./`, or `../`.
+
+```python
+from pathlib import Path
+from vcti.path import FileId
+
+# Validate
+FileId.is_valid("scripts/setup.sh")     # True
+FileId.is_valid("/absolute/path")       # False
+FileId.is_valid("../escape")            # False
+
+# Resolve to filesystem path
+base = Path("/project")
+FileId.resolve_path("src/main.py", base)
+# -> Path("/project/src/main.py")
+
+# Extract file ID from a path
+src = Path("/project/src/main.py")
+FileId.get_file_id(src, base)
+# -> "src/main.py"
+```
+
+### Path resolution and access validation
+
+```python
+from vcti.path import abs_path, validate_file_access, resolve_path
+
+# Absolute path resolution
+abs_path("relative/file.txt")
+# -> Path("<cwd>/relative/file.txt")
+
+# Validate that a file exists and is readable
+validate_file_access("config.yaml")
+# Raises FileNotFoundError, IsADirectoryError, or PermissionError
+
+# Resolve relative to a base directory
+resolve_path("data/input.csv", "/project")
+# -> Path("/project/data/input.csv")
+```
+
+---
+
+## Public API
+
+| Symbol | Type | Purpose |
+|--------|------|---------|
+| `FileNameValidator.is_valid(name)` | classmethod | Check if a filename is valid |
+| `FileNameValidator.validate(name)` | classmethod | Validate filename, raise `ValueError` if invalid |
+| `FileId.is_valid(file_id)` | staticmethod | Check if a POSIX file ID is valid |
+| `FileId.validate(file_id)` | staticmethod | Validate file ID, raise `ValueError` if invalid |
+| `FileId.resolve_path(file_id, base_dir)` | staticmethod | Resolve file ID to absolute path |
+| `FileId.get_file_id(file_path, base_dir)` | staticmethod | Extract file ID from absolute path |
+| `abs_path(fp)` | function | Convert to absolute resolved `Path` |
+| `validate_file_access(fp)` | function | Validate file exists and is readable |
+| `validate_folder_access(fp)` | function | Validate directory exists |
+| `resolve_path(path, base_dir)` | function | Resolve path relative to base directory |
+
+---
+
+## Documentation
+
+- [Design](docs/design.md) -- Concepts, architecture decisions, and rationale
+- [Source Guide](docs/source-guide.md) -- File descriptions and execution flow traces
+- [API Reference](docs/api.md) -- Autodoc for all modules

vcti_path-1.0.3/src/vcti_path.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/vcti/path/__init__.py
+src/vcti/path/file_id_utils.py
+src/vcti/path/filename_validator.py
+src/vcti/path/path_utils.py
+src/vcti/path/py.typed
+src/vcti_path.egg-info/PKG-INFO
+src/vcti_path.egg-info/SOURCES.txt
+src/vcti_path.egg-info/dependency_links.txt
+src/vcti_path.egg-info/requires.txt
+src/vcti_path.egg-info/top_level.txt
+src/vcti_path.egg-info/zip-safe
+tests/test_file_id_utils.py
+tests/test_filename_validator.py
+tests/test_path_utils.py

vcti_path-1.0.3/src/vcti_path.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vcti_path-1.0.3/src/vcti_path.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[lint]
+ruff
+
+[test]
+pytest
+pytest-cov

vcti_path-1.0.3/src/vcti_path.egg-info/top_level.txt

@@ -0,0 +1 @@
+vcti

vcti_path-1.0.3/src/vcti_path.egg-info/zip-safe

@@ -0,0 +1 @@
+

vcti_path-1.0.3/tests/test_file_id_utils.py

@@ -0,0 +1,158 @@
+import os
+
+import pytest
+
+from vcti.path.file_id_utils import FileId
+
+
+class TestFileIdIsValid:
+    """Tests for FileId.is_valid."""
+
+    def test_simple_filename(self):
+        assert FileId.is_valid("file.txt") is True
+
+    def test_nested_path(self):
+        assert FileId.is_valid("scripts/setup.sh") is True
+
+    def test_deeply_nested(self):
+        assert FileId.is_valid("a/b/c/d.txt") is True
+
+    def test_empty_string_invalid(self):
+        assert FileId.is_valid("") is False
+
+    def test_whitespace_only_invalid(self):
+        assert FileId.is_valid("   ") is False
+
+    def test_absolute_path_invalid(self):
+        assert FileId.is_valid("/absolute/path") is False
+
+    def test_dot_slash_prefix_invalid(self):
+        assert FileId.is_valid("./relative") is False
+
+    def test_dotdot_slash_prefix_invalid(self):
+        assert FileId.is_valid("../parent") is False
+
+    def test_trailing_slash_valid(self):
+        assert FileId.is_valid("folder/") is True
+
+    def test_name_with_illegal_chars_invalid(self):
+        assert FileId.is_valid("bad|name") is False
+
+    def test_name_with_colon_invalid(self):
+        assert FileId.is_valid("bad:name") is False
+
+    def test_backslash_path_invalid(self):
+        assert FileId.is_valid("folder\\file.txt") is False
+
+    @pytest.mark.parametrize("invalid_input", [None, 123, b"bytes", ["list"]])
+    def test_non_string_raises_type_error(self, invalid_input):
+        with pytest.raises(TypeError, match="file_id must be a str"):
+            FileId.is_valid(invalid_input)
+
+
+class TestFileIdValidate:
+    """Tests for FileId.validate."""
+
+    def test_valid_raises_nothing(self):
+        FileId.validate("scripts/run.sh")  # Should not raise
+
+    def test_invalid_raises_value_error(self):
+        with pytest.raises(ValueError, match="Invalid file ID"):
+            FileId.validate("/absolute")
+
+    def test_empty_raises_value_error(self):
+        with pytest.raises(ValueError):
+            FileId.validate("")
+
+
+class TestFileIdResolvePath:
+    """Tests for FileId.resolve_path."""
+
+    def test_none_returns_base_dir(self, tmp_path):
+        result = FileId.resolve_path(None, tmp_path)
+        assert result == tmp_path
+
+    def test_empty_string_returns_base_dir(self, tmp_path):
+        result = FileId.resolve_path("", tmp_path)
+        assert result == tmp_path
+
+    def test_resolves_relative_id(self, tmp_path):
+        result = FileId.resolve_path("subdir/file.txt", tmp_path)
+        assert result == tmp_path / "subdir" / "file.txt"
+
+    def test_must_exist_raises_if_missing(self, tmp_path):
+        with pytest.raises(FileNotFoundError):
+            FileId.resolve_path("nonexistent.txt", tmp_path, must_exist=True)
+
+    def test_must_exist_passes_if_file_exists(self, tmp_path):
+        f = tmp_path / "real.txt"
+        f.write_text("data")
+        result = FileId.resolve_path("real.txt", tmp_path, must_exist=True)
+        assert result == f
+
+    def test_must_be_file_raises_for_dir(self, tmp_path):
+        d = tmp_path / "mydir"
+        d.mkdir()
+        with pytest.raises(IsADirectoryError):
+            FileId.resolve_path("mydir", tmp_path, must_be_file=True)
+
+    def test_must_be_dir_raises_for_file(self, tmp_path):
+        f = tmp_path / "file.txt"
+        f.write_text("data")
+        with pytest.raises(NotADirectoryError):
+            FileId.resolve_path("file.txt", tmp_path, must_be_dir=True)
+
+    def test_invalid_file_id_raises_value_error(self, tmp_path):
+        with pytest.raises(ValueError):
+            FileId.resolve_path("/absolute", tmp_path)
+
+    # Note: Windows junctions/reparse points are not tested
+    @pytest.mark.skipif(os.name != "posix", reason="POSIX symlinks only")
+    def test_symlink_raises_runtime_error(self, tmp_path):
+        target = tmp_path / "real.txt"
+        target.write_text("data")
+        link = tmp_path / "link.txt"
+        link.symlink_to(target)
+        with pytest.raises(RuntimeError, match="Symbolic links are not supported"):
+            FileId.resolve_path("link.txt", tmp_path)
+
+
+class TestFileIdGetFileId:
+    """Tests for FileId.get_file_id."""
+
+    def test_file_returns_posix_id(self, tmp_path):
+        f = tmp_path / "data.txt"
+        f.write_text("x")
+        result = FileId.get_file_id(f, tmp_path)
+        assert result == "data.txt"
+
+    def test_nested_file_returns_posix_id(self, tmp_path):
+        sub = tmp_path / "sub"
+        sub.mkdir()
+        f = sub / "file.txt"
+        f.write_text("x")
+        result = FileId.get_file_id(f, tmp_path)
+        assert result == "sub/file.txt"
+
+    def test_directory_returns_trailing_slash(self, tmp_path):
+        d = tmp_path / "mydir"
+        d.mkdir()
+        result = FileId.get_file_id(d, tmp_path)
+        assert result == "mydir/"
+
+    def test_base_dir_itself_returns_empty(self, tmp_path):
+        result = FileId.get_file_id(tmp_path, tmp_path)
+        assert result == ""
+
+    def test_outside_base_dir_raises(self, tmp_path):
+        outside = tmp_path.parent / "other.txt"
+        with pytest.raises(ValueError, match="not under base directory"):
+            FileId.get_file_id(outside, tmp_path)
+
+    def test_non_path_file_path_raises_type_error(self, tmp_path):
+        with pytest.raises(TypeError, match="file_path must be a Path"):
+            FileId.get_file_id("string/path", tmp_path)
+
+    def test_non_path_base_dir_raises_type_error(self, tmp_path):
+        with pytest.raises(TypeError, match="base_dir must be a Path"):
+            FileId.get_file_id(tmp_path, "/string/base")

vcti_path-1.0.3/tests/test_filename_validator.py

@@ -0,0 +1,101 @@
+import re
+
+import pytest
+
+import vcti.path
+from vcti.path.filename_validator import FileNameValidator
+
+
+class TestVersion:
+    """Tests for package version metadata."""
+
+    def test_version_exists(self):
+        assert hasattr(vcti.path, "__version__")
+
+    def test_version_is_valid_semver(self):
+        assert re.match(r"^\d+\.\d+\.\d+", vcti.path.__version__)
+
+
+class TestPublicAPI:
+    """Tests that all public symbols are re-exported from vcti.path."""
+
+    @pytest.mark.parametrize(
+        "symbol",
+        [
+            "FileNameValidator",
+            "FileId",
+            "abs_path",
+            "validate_file_access",
+            "validate_folder_access",
+            "resolve_path",
+        ],
+    )
+    def test_public_symbol_exported(self, symbol):
+        assert hasattr(vcti.path, symbol)
+        assert symbol in vcti.path.__all__
+
+
+class TestFileNameValidatorIsValid:
+    """Tests for FileNameValidator.is_valid."""
+
+    def test_valid_simple_name(self):
+        assert FileNameValidator.is_valid("file.txt") is True
+
+    def test_valid_name_no_extension(self):
+        assert FileNameValidator.is_valid("myfile") is True
+
+    def test_valid_name_with_spaces(self):
+        assert FileNameValidator.is_valid("my file.txt") is True
+
+    def test_valid_name_with_underscores_dashes(self):
+        assert FileNameValidator.is_valid("my-file_name.txt") is True
+
+    def test_empty_string_invalid(self):
+        assert FileNameValidator.is_valid("") is False
+
+    def test_whitespace_only_invalid(self):
+        assert FileNameValidator.is_valid("   ") is False
+
+    def test_dot_reserved_invalid(self):
+        assert FileNameValidator.is_valid(".") is False
+
+    def test_dotdot_reserved_invalid(self):
+        assert FileNameValidator.is_valid("..") is False
+
+    @pytest.mark.parametrize("char", ["/", "\\", ":", "*", "?", '"', "<", ">", "|"])
+    def test_illegal_characters_invalid(self, char):
+        assert FileNameValidator.is_valid(f"file{char}name") is False
+
+    def test_valid_hidden_file_unix(self):
+        assert FileNameValidator.is_valid(".hidden") is True
+
+    def test_valid_numeric_name(self):
+        assert FileNameValidator.is_valid("12345") is True
+
+    @pytest.mark.parametrize("invalid_input", [None, 123, b"bytes", ["list"]])
+    def test_non_string_raises_type_error(self, invalid_input):
+        with pytest.raises(TypeError, match="name must be a str"):
+            FileNameValidator.is_valid(invalid_input)
+
+
+class TestFileNameValidatorValidate:
+    """Tests for FileNameValidator.validate."""
+
+    def test_valid_name_no_exception(self):
+        FileNameValidator.validate("data.json")  # Should not raise
+
+    def test_empty_raises_value_error(self):
+        with pytest.raises(ValueError, match="Invalid file or directory name"):
+            FileNameValidator.validate("")
+
+    def test_dot_raises_value_error(self):
+        with pytest.raises(ValueError):
+            FileNameValidator.validate(".")
+
+    def test_illegal_char_raises_value_error(self):
+        with pytest.raises(ValueError):
+            FileNameValidator.validate("bad/name")
+
+    def test_dotdot_raises_value_error(self):
+        with pytest.raises(ValueError):
+            FileNameValidator.validate("..")

vcti_path-1.0.3/tests/test_path_utils.py

@@ -0,0 +1,193 @@
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from vcti.path.path_utils import (
+    abs_path,
+    resolve_path,
+    validate_file_access,
+    validate_folder_access,
+)
+
+
+class TestPathUtils:
+    """Test cases for path utility functions."""
+
+    @pytest.fixture(autouse=True)
+    def setup_teardown(self, tmp_path):
+        """Create temporary files and directories for testing."""
+        self.test_dir = tmp_path / "test_directory"
+        self.test_dir.mkdir()
+
+        self.test_file = tmp_path / "test_file.txt"
+        self.test_file.write_text("Sample content")
+
+        self.non_existent_path = tmp_path / "non_existent.txt"
+        self.subdir = self.test_dir / "subdir"
+        self.subdir.mkdir()
+
+        # Store original permissions to restore later
+        self.original_mode = self.test_file.stat().st_mode
+        yield  # This is where the testing happens
+
+        # Restore original permissions (in case they were modified)
+        self.test_file.chmod(self.original_mode)
+
+    def test_abs_path_with_str(self):
+        """Test absolute path resolution with string input."""
+        relative_path = str(self.test_file)
+        result = abs_path(relative_path)
+        assert result == Path(relative_path).resolve()
+        assert isinstance(result, Path)
+
+    def test_abs_path_with_path(self):
+        """Test absolute path resolution with Path object input."""
+        result = abs_path(self.test_file)
+        assert result == self.test_file.resolve()
+        assert isinstance(result, Path)
+
+    def test_validate_file_access_valid(self):
+        """Test validate_file_access with valid file."""
+        validate_file_access(self.test_file)  # Should not raise
+
+    def test_validate_file_access_non_existent(self):
+        """Test validate_file_access with non-existent file."""
+        with pytest.raises(FileNotFoundError):
+            validate_file_access(self.non_existent_path)
+
+    def test_validate_file_access_is_directory(self):
+        """Test validate_file_access with directory."""
+        with pytest.raises(IsADirectoryError):
+            validate_file_access(self.test_dir)
+
+    # Note: Windows ACL-based permission testing is beyond scope
+    @pytest.mark.skipif(os.name != "posix", reason="POSIX permissions only")
+    def test_validate_file_access_no_permission(self):
+        """Test validate_file_access with unreadable file (POSIX only)."""
+        self.test_file.chmod(0o000)  # Remove all permissions
+        with pytest.raises(PermissionError):
+            validate_file_access(self.test_file)
+
+    def test_validate_folder_access_valid(self):
+        """Test validate_folder_access with valid directory."""
+        validate_folder_access(self.test_dir)  # Should not raise
+
+    def test_validate_folder_access_non_existent(self):
+        """Test validate_folder_access with non-existent directory."""
+        with pytest.raises(FileNotFoundError):
+            validate_folder_access(self.non_existent_path)
+
+    def test_validate_folder_access_not_directory(self):
+        """Test validate_folder_access with file."""
+        with pytest.raises(NotADirectoryError):
+            validate_folder_access(self.test_file)
+
+    @pytest.mark.parametrize(
+        "path_input",
+        [
+            b"bytes_path",  # bytes input
+            123,  # integer input
+        ],
+    )
+    def test_abs_path_with_wrong_types(self, path_input):
+        """Test abs_path with unusual input types."""
+        with pytest.raises(TypeError):
+            abs_path(path_input)
+
+    @patch("pathlib.Path.exists", return_value=True)
+    @patch("pathlib.Path.is_file", return_value=True)
+    @patch("vcti.path.path_utils.os.access")
+    def test_validate_file_access_mocked(self, mock_access, mock_is_file, mock_exists):
+        """Test validate_file_access with mocked permissions."""
+        mock_access.return_value = True  # Readable
+        validate_file_access("any_path")  # Should pass with mocked permissions
+
+        mock_access.return_value = False  # Not readable
+        with pytest.raises(PermissionError):
+            validate_file_access("any_path")
+
+    # Note: Windows junctions/reparse points are not tested
+    @pytest.mark.skipif(os.name != "posix", reason="POSIX symlinks only")
+    def test_symlink_valid_target(self):
+        """Test validate_file_access follows symlink to valid target."""
+        symlink_path = self.test_dir / "symlink.txt"
+        symlink_path.symlink_to(self.test_file)
+        validate_file_access(symlink_path)
+
+    @pytest.mark.skipif(os.name != "posix", reason="POSIX symlinks only")
+    def test_symlink_broken_raises_file_not_found(self):
+        """Test validate_file_access raises for broken symlink."""
+        broken_symlink = self.test_dir / "broken_symlink"
+        broken_symlink.symlink_to("nonexistent_target")
+        with pytest.raises(FileNotFoundError):
+            validate_file_access(broken_symlink)
+
+    def test_resolve_path_absolute(self, tmp_path):
+        """Test resolve_path with absolute path input."""
+        abs_test_file = self.test_file.resolve()
+        result = resolve_path(abs_test_file, tmp_path)
+        assert result == abs_test_file
+
+    def test_resolve_path_relative(self, tmp_path):
+        """Test resolve_path with relative path input."""
+        rel_path = "test_directory/subdir"
+        result = resolve_path(rel_path, tmp_path)
+        expected = (tmp_path / rel_path).resolve()
+        assert result == expected
+
+    def test_resolve_path_with_str_input(self, tmp_path):
+        """Test resolve_path with string inputs."""
+        result = resolve_path("test_file.txt", str(tmp_path))
+        expected = (tmp_path / "test_file.txt").resolve()
+        assert result == expected
+
+    def test_resolve_path_invalid_base(self):
+        """Test resolve_path with non-existent base path."""
+        with pytest.raises(FileNotFoundError):
+            resolve_path("any_path", "/non/existent/base")
+
+    def test_resolve_path_base_not_dir(self, tmp_path):
+        """Test resolve_path when base path is not a directory."""
+        with pytest.raises(NotADirectoryError):
+            resolve_path("any_path", self.test_file)
+
+    def test_resolve_path_dot_dot(self, tmp_path):
+        """Test resolve_path with parent directory references."""
+        result = resolve_path("../test_file.txt", self.subdir)
+        expected = (self.test_dir / "test_file.txt").resolve()
+        assert result == expected
+
+    def test_resolve_path_empty_path(self, tmp_path):
+        """Test resolve_path with empty path string."""
+        result = resolve_path("", tmp_path)
+        assert result == tmp_path.resolve()
+
+    def test_resolve_path_dot(self, tmp_path):
+        """Test resolve_path with '.' path."""
+        result = resolve_path(".", tmp_path)
+        assert result == tmp_path.resolve()
+
+    def test_resolve_path_relative_to_cwd(self, tmp_path, monkeypatch):
+        """Test that relative paths without base_path use cwd."""
+        monkeypatch.chdir(tmp_path)
+        rel_path = "test_file.txt"
+        result = resolve_path(rel_path, ".")
+        expected = (tmp_path / rel_path).resolve()
+        assert result == expected
+
+    @pytest.mark.parametrize(
+        "invalid_input",
+        [
+            None,
+            123,
+            b"bytes_path",
+        ],
+    )
+    def test_resolve_path_invalid_types(self, invalid_input, tmp_path):
+        """Test resolve_path with invalid input types."""
+        with pytest.raises(TypeError):
+            resolve_path(invalid_input, tmp_path)
+        with pytest.raises(TypeError):
+            resolve_path("valid_path", invalid_input)