FastAPI-fastkit 1.3.0__py3-none-any.whl → 1.4.1__py3-none-any.whl

fastapi_fastkit/backend/inspection/freshness.py

@@ -0,0 +1,145 @@
+# --------------------------------------------------------------------------
+# Dependency freshness reporting.
+#
+# Each pinned dependency is compared against the latest release published on
+# PyPI. Findings are warnings only - a template lagging behind upstream is
+# worth surfacing but never a reason to fail an inspection. Network failures
+# are skipped silently, and ``--offline`` disables the lookups entirely.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import json
+import re
+import tomllib
+import urllib.error
+import urllib.request
+from typing import Dict, Optional, Tuple
+
+from fastapi_fastkit.backend.package_managers.poetry_manager import (
+    _parse_pip_requirement,
+)
+from fastapi_fastkit.utils.logging import debug_log
+
+from .context import InspectionContext
+
+PYPI_JSON_URL = "https://pypi.org/pypi/{package}/json"
+PYPI_TIMEOUT = 5
+_VERSION_RE = re.compile(r"(\d+)\.(\d+)")
+#: Only exact/lower-bound pins carry a meaningful "current version".
+_PIN_OPERATORS = ("==", ">=", "~=")
+
+
+def _pinned_version(requirement: str) -> Tuple[str, str]:
+    """Return ``(package name, pinned version)`` for a requirement string.
+
+    Version is empty when the requirement is unpinned or uses an operator
+    that does not identify a concrete current version (e.g. ``<2``).
+    """
+    name, _extras, version_spec, _marker = _parse_pip_requirement(requirement)
+    if not name or not version_spec:
+        return name.lower() if name else "", ""
+    for operator in _PIN_OPERATORS:
+        if version_spec.startswith(operator):
+            return name.lower(), version_spec[len(operator) :].strip()
+    return name.lower(), ""
+
+
+def _parse_version(version: str) -> Optional[Tuple[int, int]]:
+    """Extract a (major, minor) pair from a version string."""
+    match = _VERSION_RE.match(version.strip())
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2))
+
+
+def fetch_latest_version(package: str) -> Optional[str]:
+    """Return the latest version of ``package`` on PyPI, or ``None`` on failure."""
+    url = PYPI_JSON_URL.format(package=package)
+    try:
+        with urllib.request.urlopen(url, timeout=PYPI_TIMEOUT) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except (urllib.error.URLError, OSError, ValueError, TimeoutError) as e:
+        debug_log(f"PyPI lookup failed for {package}: {e}", "debug")
+        return None
+    version = payload.get("info", {}).get("version")
+    return str(version) if version else None
+
+
+def _collect_pins(ctx: InspectionContext) -> Dict[str, str]:
+    """Map package name -> pinned version from the template's metadata files."""
+    pins: Dict[str, str] = {}
+
+    requirements_path = ctx.template_path / "requirements.txt-tpl"
+    if requirements_path.exists():
+        try:
+            with open(requirements_path, encoding="utf-8") as f:
+                lines = f.read().splitlines()
+        except (OSError, UnicodeDecodeError):
+            lines = []
+        for line in lines:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            name, version = _pinned_version(line)
+            if name and version:
+                pins.setdefault(name, version)
+
+    pyproject_path = ctx.template_path / "pyproject.toml-tpl"
+    if pyproject_path.exists():
+        try:
+            with open(pyproject_path, "rb") as f:
+                data = tomllib.load(f)
+        except (OSError, ValueError):
+            data = {}
+        for dep in data.get("project", {}).get("dependencies", []) or []:
+            if not isinstance(dep, str):
+                continue
+            name, version = _pinned_version(dep)
+            if name and version:
+                pins.setdefault(name, version)
+
+    return pins
+
+
+def check_dependency_freshness(ctx: InspectionContext) -> bool:
+    """Warn about dependencies that lag behind their latest PyPI release.
+
+    Always returns ``True``: freshness is advisory.
+    """
+    if ctx.options.offline:
+        debug_log("Offline mode - skipping dependency freshness check", "info")
+        return True
+
+    pins = _collect_pins(ctx)
+    if not pins:
+        debug_log("No pinned dependencies found for freshness check", "info")
+        return True
+
+    checked = 0
+    for package, pinned in sorted(pins.items()):
+        latest = fetch_latest_version(package)
+        if latest is None:
+            continue
+        checked += 1
+        current_parts = _parse_version(pinned)
+        latest_parts = _parse_version(latest)
+        if current_parts is None or latest_parts is None:
+            continue
+        if latest_parts[0] > current_parts[0]:
+            ctx.add_warning(
+                f"{package} is {latest_parts[0] - current_parts[0]} major "
+                f"version(s) behind: pinned {pinned}, latest {latest}"
+            )
+        elif latest_parts[0] == current_parts[0] and latest_parts[1] > current_parts[1]:
+            ctx.add_warning(
+                f"{package} is {latest_parts[1] - current_parts[1]} minor "
+                f"version(s) behind: pinned {pinned}, latest {latest}"
+            )
+
+    if checked == 0:
+        debug_log(
+            "Dependency freshness check skipped - no PyPI responses received", "info"
+        )
+    else:
+        debug_log(f"Dependency freshness check completed ({checked} packages)", "info")
+    return True

fastapi_fastkit/backend/inspection/fsutils.py

@@ -0,0 +1,139 @@
+# --------------------------------------------------------------------------
+# Filesystem helpers shared by the inspection pipeline: shell script line
+# ending normalisation and best-effort removal of temporary directories that
+# Docker or a test run may have left behind with awkward permissions.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import os
+import shutil
+import stat
+import subprocess
+import time
+
+from fastapi_fastkit.utils.logging import debug_log
+
+CLEANUP_MAX_RETRIES = 5
+
+
+def fix_script_line_endings(script_path: str) -> None:
+    """Convert Windows line endings in a script to Unix ones."""
+    try:
+        with open(script_path, "rb") as f:
+            content = f.read()
+
+        content = content.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+
+        with open(script_path, "wb") as f:
+            f.write(content)
+
+        debug_log(f"Fixed line endings in {script_path}", "debug")
+    except OSError as e:
+        debug_log(f"Failed to fix line endings in {script_path}: {e}", "warning")
+
+
+def fix_all_script_line_endings(directory: str) -> None:
+    """Normalise line endings for every shell script below ``directory``."""
+    for root, _dirs, files in os.walk(directory):
+        for file_name in files:
+            if file_name.endswith((".sh", ".bash")):
+                fix_script_line_endings(os.path.join(root, file_name))
+
+    debug_log("Fixed line endings for all shell scripts", "info")
+
+
+def _fix_permissions(path: str) -> None:
+    """Grant full permissions to ``path``, ignoring failures."""
+    try:
+        os.chmod(path, stat.S_IRWXU | stat.S_IRWXG | stat.S_IRWXO)
+    except OSError:
+        pass
+
+
+def fix_directory_permissions(directory_path: str) -> None:
+    """Make a directory tree writable so it can be removed."""
+    _fix_permissions(directory_path)
+    for root, dirs, files in os.walk(directory_path):
+        _fix_permissions(root)
+        for name in dirs + files:
+            _fix_permissions(os.path.join(root, name))
+
+
+def remove_directory_contents(directory_path: str) -> None:
+    """Remove a directory's contents entry by entry, ignoring failures."""
+    for root, dirs, files in os.walk(directory_path, topdown=False):
+        for file_name in files:
+            file_path = os.path.join(root, file_name)
+            _fix_permissions(file_path)
+            try:
+                os.remove(file_path)
+            except OSError:
+                pass
+
+        for dir_name in dirs:
+            dir_path = os.path.join(root, dir_name)
+            _fix_permissions(dir_path)
+            try:
+                os.rmdir(dir_path)
+            except OSError:
+                pass
+
+
+def force_cleanup_directory(directory_path: str) -> None:
+    """Remove ``directory_path`` using progressively more forceful strategies."""
+    for attempt in range(CLEANUP_MAX_RETRIES):
+        try:
+            shutil.rmtree(directory_path)
+            debug_log(
+                f"Successfully cleaned up temp directory: {directory_path}", "info"
+            )
+            return
+        except (OSError, PermissionError) as e:
+            if attempt == CLEANUP_MAX_RETRIES - 1:
+                break
+            debug_log(
+                f"Attempt {attempt + 1} failed to cleanup {directory_path}: {e}",
+                "warning",
+            )
+
+            try:
+                fix_directory_permissions(directory_path)
+                shutil.rmtree(directory_path)
+                debug_log(
+                    "Successfully cleaned up temp directory after permission fix: "
+                    f"{directory_path}",
+                    "info",
+                )
+                return
+            except OSError:
+                pass
+
+            try:
+                remove_directory_contents(directory_path)
+                os.rmdir(directory_path)
+                debug_log(
+                    "Successfully cleaned up temp directory by removing contents: "
+                    f"{directory_path}",
+                    "info",
+                )
+                return
+            except OSError:
+                pass
+
+            time.sleep(2)
+
+    debug_log(
+        f"Failed to cleanup temp directory after {CLEANUP_MAX_RETRIES} attempts: "
+        f"{directory_path}",
+        "warning",
+    )
+    try:
+        if os.name == "nt":  # pragma: no cover - Windows-only branch
+            subprocess.run(
+                ["rmdir", "/s", "/q", directory_path], check=False, shell=True
+            )
+        else:
+            subprocess.run(["rm", "-rf", directory_path], check=False)
+        debug_log(f"Force cleanup completed for: {directory_path}", "info")
+    except OSError:
+        debug_log(f"All cleanup attempts failed for: {directory_path}", "warning")

fastapi_fastkit/backend/inspection/lint.py

@@ -0,0 +1,103 @@
+# --------------------------------------------------------------------------
+# Static analysis of the generated project.
+#
+# The compile check is mandatory - a template that cannot be compiled is
+# broken beyond argument. It is performed in-process with ``compile()`` and
+# deliberately writes nothing to disk: a Docker test run beforehand can leave
+# root-owned ``__pycache__`` directories in the bind-mounted project, and
+# ``compileall`` would then fail with a PermissionError that says nothing
+# about the template. ``mypy`` is opt-in because it needs the template's own
+# dependencies installed and is far slower.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import os
+import subprocess
+import sys
+from typing import List
+
+from fastapi_fastkit.utils.logging import debug_log
+
+from .context import InspectionContext
+
+MYPY_TIMEOUT = 300
+
+#: Directories never worth compiling - third party code and build artefacts.
+EXCLUDED_DIRS = {".venv", "venv", "__pycache__", "node_modules"}
+
+
+def _interpreter(ctx: InspectionContext) -> str:
+    """Prefer the inspection venv interpreter, falling back to the host one."""
+    return ctx.python_executable() or sys.executable
+
+
+def _iter_python_files(root: str) -> List[str]:
+    """Collect every ``.py`` file below ``root``, skipping excluded directories."""
+    python_files: List[str] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [name for name in dirnames if name not in EXCLUDED_DIRS]
+        for file_name in sorted(filenames):
+            if file_name.endswith(".py"):
+                python_files.append(os.path.join(dirpath, file_name))
+    return python_files
+
+
+def check_compileall(ctx: InspectionContext) -> bool:
+    """Compile every Python file of the generated project, in memory.
+
+    Nothing is written to disk - no ``__pycache__`` is created - so the check
+    stays a pure syntax gate that cannot trip over file ownership left behind
+    by a containerised test run.
+    """
+    failures: List[str] = []
+
+    for path in _iter_python_files(ctx.temp_dir):
+        try:
+            with open(path, "rb") as f:
+                source = f.read()
+        except OSError as e:
+            failures.append(f"{path}: could not be read ({e})")
+            continue
+
+        try:
+            compile(source, path, "exec", dont_inherit=True)
+        except (SyntaxError, ValueError) as e:
+            failures.append(f"{path}: {e}")
+
+    if failures:
+        detail = "\n".join(failures)
+        ctx.add_error(f"Generated project failed to compile:\n{detail}")
+        return False
+
+    debug_log("compileall check passed", "info")
+    return True
+
+
+def check_mypy(ctx: InspectionContext) -> bool:
+    """Run mypy inside the generated project (opt-in via ``--mypy``)."""
+    if not ctx.options.run_mypy:
+        debug_log("mypy check disabled", "info")
+        return True
+
+    try:
+        result = subprocess.run(
+            [_interpreter(ctx), "-m", "mypy", "."],
+            cwd=ctx.temp_dir,
+            capture_output=True,
+            text=True,
+            timeout=MYPY_TIMEOUT,
+        )
+    except subprocess.TimeoutExpired:
+        ctx.add_error("mypy timed out")
+        return False
+    except OSError as e:
+        ctx.add_warning(f"Could not run mypy: {e}")
+        return True
+
+    if result.returncode != 0:
+        detail = (result.stdout or result.stderr or "").strip()
+        ctx.add_error(f"mypy reported errors in the generated project:\n{detail}")
+        return False
+
+    debug_log("mypy check passed", "info")
+    return True

fastapi_fastkit/backend/inspection/report.py

@@ -0,0 +1,58 @@
+# --------------------------------------------------------------------------
+# Inspection reporting: turn an InspectionContext into the report dictionary
+# consumed by the CLI, the local scripts and the CI workflows.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+from typing import Any, Dict
+
+from fastapi_fastkit.utils.logging import debug_log
+from fastapi_fastkit.utils.main import print_error, print_success, print_warning
+
+from .context import InspectionContext
+
+
+def build_report(ctx: InspectionContext) -> Dict[str, Any]:
+    """Build the inspection report and log a summary of the findings."""
+    is_valid = len(ctx.errors) == 0
+    template_name = ctx.template_path.name
+
+    if is_valid:
+        debug_log(
+            f"Template inspection completed successfully for {template_name}", "info"
+        )
+    else:
+        debug_log(
+            f"Template inspection failed for {template_name} "
+            f"with {len(ctx.errors)} errors",
+            "error",
+        )
+        for index, error in enumerate(ctx.errors, 1):
+            debug_log(f"Error {index}: {error}", "error")
+
+    if ctx.warnings:
+        debug_log(
+            f"Template {template_name} has {len(ctx.warnings)} warnings: "
+            f"{ctx.warnings}",
+            "warning",
+        )
+
+    return {
+        "template_path": str(ctx.template_path),
+        "errors": list(ctx.errors),
+        "warnings": list(ctx.warnings),
+        "is_valid": is_valid,
+    }
+
+
+def print_report(ctx: InspectionContext, is_valid: bool) -> None:
+    """Print the human-facing inspection outcome."""
+    if is_valid:
+        print_success(f"Template {ctx.template_path} is valid!")
+    else:
+        print_error(f"Template {ctx.template_path} validation failed")
+        for error in ctx.errors:
+            print_error(f"  - {error}")
+
+    for warning in ctx.warnings:
+        print_warning(f"  - {warning}")