"""Read file contents from disk."""

from pathlib import Path


def run(path: str, *, encoding: str = "utf-8", max_bytes: int = 1_000_000) -> dict:
    """Read a file and return its content.

    Args:
        path: Absolute or relative file path.
        encoding: Text encoding. Default: utf-8.
        max_bytes: Maximum bytes to read (safety limit). Default: 1 MB.

    Returns:
        dict with keys: content, path, size_bytes, encoding
    """
    file_path = Path(path).expanduser().resolve()
    if not file_path.exists():
        raise FileNotFoundError(f"File not found: {file_path}")
    if not file_path.is_file():
        raise ValueError(f"Not a regular file: {file_path}")

    size = file_path.stat().st_size
    if size > max_bytes:
        raise ValueError(
            f"File too large ({size:,} bytes). "
            f"Max is {max_bytes:,} bytes. Pass max_bytes= to increase the limit."
        )

    content = file_path.read_text(encoding=encoding)
    return {
        "content": content,
        "path": str(file_path),
        "size_bytes": size,
        "encoding": encoding,
    }
