Python Ultimate

# /// script
# requires-python = ">=3.10"
# dependencies = []
# ///

"""Validate file/directory variable naming conventions.

This script checks if a given variable name follows the python-ultimate
naming conventions for files, directories, and paths.

Usage:
    uv run check_path_naming.py <name>
    uv run check_path_naming.py --check-files <python-file-or-directory>
    uv run check_path_naming.py --check-forbidden <python-file-or-directory>

Examples:
    uv run check_path_naming.py output_file
    # Output: is_file

    uv run check_path_naming.py cache_dir
    # Output: is_dir

    uv run check_path_naming.py --check-files src/
    # Output: List of violations in Python files

    uv run check_path_naming.py --check-forbidden src/
    # Output: List of forbidden pattern matches in Python files
"""

from __future__ import annotations

import argparse
import ast
import enum
import io
import re
import sys
import tokenize
from pathlib import Path


class PathValidity(enum.StrEnum):
    """Validation results for path variable naming."""

    FILE = "is_file"
    DIR = "is_dir"
    PATH = "is_path_exceptional"
    INVALID = "invalid"


FORBIDDEN_REASON: dict[str, str] = {
    "TYPE_CHECKING guard": "Avoid TYPE_CHECKING guards. Refactor imports/types as described in references/type-checking.md.",
    "Optional[T]": "Use pipe syntax (T | None) instead of Optional[T].",
    "os.path usage": "Use pathlib.Path instead of os.path.",
    "noqa suppression": "Fix the underlying lint issue instead of suppressing with # noqa.",
    "sys.path manipulation": "Avoid sys.path manipulation. Use proper package/module layout and imports.",
    "defensive required import": "Check whether this ImportError guard is wrapping a required dependency import.",
}


def check_path_naming(name: str | Path) -> PathValidity:
    """Check if a variable name follows file/directory naming conventions.

    Naming conventions:
    - Variables for files must end with "_file" suffix
    - Variables for directories must end with "_dir" suffix
    - "_path" suffix is only allowed in exceptional cases when
      the type cannot be clearly determined
    - Anti-patterns like "path", "dir_output", "file_output" are invalid
    - Bare generic names (path, file, folder, dir, directory, etc.) are invalid
      when they represent file system paths

    Args:
        name: Variable name to check (string or Path object)

    Returns:
        PathValidity enum indicating the naming validity

    Examples:
        >>> check_path_naming("output_file")
        <PathValidity.FILE: 'is_file'>
        >>> check_path_naming("cache_dir")
        <PathValidity.DIR: 'is_dir'>
        >>> check_path_naming("data_path")
        <PathValidity.PATH: 'is_path_exceptional'>
        >>> check_path_naming("path")
        <PathValidity.INVALID: 'invalid'>
        >>> check_path_naming("folder")
        <PathValidity.INVALID: 'invalid'>
    """
    # Convert Path to string if needed
    var_name = str(name)

    # Strip any Path parent components, get just the name
    var_name = Path(var_name).name if "/" in var_name or "\\" in var_name else var_name

    # Anti-patterns - bare generic names for path-related variables
    # These are always invalid when representing file system paths
    generic_path_names = {
        "path",
        "file",
        "folder",
        "dir",
        "directory",
        "output",
        "input",
        "source",
        "target",
        "dest",
        "destination",
    }
    if var_name in generic_path_names:
        return PathValidity.INVALID

    # "dir" or "file" as prefix instead of suffix
    if var_name.startswith("dir_") or var_name.startswith("file_"):
        return PathValidity.INVALID

    # Check for valid suffixes (in order of specificity)
    if var_name.endswith("_file"):
        return PathValidity.FILE

    if var_name.endswith("_dir"):
        return PathValidity.DIR

    if var_name.endswith("_path"):
        return PathValidity.PATH