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

fastapi_fastkit/backend/inspection/core.py

@@ -0,0 +1,347 @@
+# --------------------------------------------------------------------------
+# The TemplateInspector orchestrator.
+#
+# The inspector generates a real project from the template (copy + convert +
+# metadata injection), runs every check against that generated project, and
+# cleans the temporary directory up afterwards. Individual checks live in
+# sibling modules; this class only sequences them and owns the lifecycle.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import os
+import shutil
+import time
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from fastapi_fastkit.backend.scaffolder import ProjectScaffolder, ScaffoldOptions
+from fastapi_fastkit.core.settings import settings
+from fastapi_fastkit.utils.logging import debug_log
+
+from . import checks, consistency, freshness, lint, smoke, strategies
+from .context import InspectionContext, InspectionOptions
+from .docker import DockerCompose
+from .fsutils import force_cleanup_directory
+from .report import build_report, print_report
+
+#: Metadata used to generate the throwaway project that gets inspected.
+DUMMY_METADATA = {
+    "project_name": "test-template",
+    "author": "Template Inspector",
+    "author_email": "inspector@fastapi-fastkit.dev",
+    "description": "Test project for template inspection",
+}
+
+
+class TemplateInspector:
+    """Validate a FastAPI template by generating and exercising a project.
+
+    Uses the context manager protocol so the temporary project directory is
+    always removed, even when a check raises.
+    """
+
+    def __init__(
+        self,
+        template_path: str,
+        temp_base_dir: Optional[str] = None,
+        options: Optional[InspectionOptions] = None,
+    ):
+        template_name = Path(template_path).name
+        base_dir = temp_base_dir or os.path.dirname(os.path.dirname(__file__))
+        self.ctx = InspectionContext(
+            template_path=Path(template_path),
+            temp_dir=os.path.join(base_dir, f"temp_{template_name}"),
+            options=options or InspectionOptions(),
+        )
+        self._cleanup_needed = False
+
+    # -- state exposed for callers and tests -------------------------------
+    @property
+    def template_path(self) -> Path:
+        """The on-disk template directory being inspected."""
+        return self.ctx.template_path
+
+    @property
+    def temp_dir(self) -> str:
+        """The generated project directory used for the inspection."""
+        return self.ctx.temp_dir
+
+    @property
+    def errors(self) -> List[str]:
+        """Fatal findings accumulated so far."""
+        return self.ctx.errors
+
+    @property
+    def warnings(self) -> List[str]:
+        """Non-fatal findings accumulated so far."""
+        return self.ctx.warnings
+
+    @property
+    def template_config(self) -> Optional[Dict[str, Any]]:
+        """Parsed ``template-config.yml`` contents, when the template ships one."""
+        return self.ctx.template_config
+
+    # -- lifecycle ---------------------------------------------------------
+    def __enter__(self) -> "TemplateInspector":
+        """Create the temporary directory and generate a project from the template."""
+        try:
+            if os.path.exists(self.ctx.temp_dir):
+                debug_log(
+                    f"Cleaning up existing temp directory: {self.ctx.temp_dir}", "info"
+                )
+                try:
+                    shutil.rmtree(self.ctx.temp_dir)
+                except OSError as e:
+                    debug_log(
+                        f"Failed to cleanup existing temp directory: {e}", "warning"
+                    )
+
+            os.makedirs(self.ctx.temp_dir, exist_ok=True)
+            # Mark for cleanup immediately: a failure below must not leak the
+            # directory that was just created.
+            self._cleanup_needed = True
+            self._generate_project()
+
+            self.ctx.template_config = self._load_template_config()
+            debug_log(f"Created temporary directory at {self.ctx.temp_dir}", "debug")
+            return self
+        except Exception as e:
+            debug_log(f"Failed to setup template inspector: {e}", "error")
+            self._cleanup()
+            raise
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Remove the generated project directory."""
+        self._cleanup()
+
+    def _cleanup(self) -> None:
+        """Tear down Docker services and delete the temporary directory."""
+        if not (self._cleanup_needed and os.path.exists(self.ctx.temp_dir)):
+            return
+
+        try:
+            if self._cleanup_docker_services():
+                # Give the daemon a moment to release bind-mounted files.
+                time.sleep(3)
+            force_cleanup_directory(self.ctx.temp_dir)
+        except Exception as e:
+            debug_log(
+                f"Warning: Unexpected error during cleanup of "
+                f"{self.ctx.temp_dir}: {e}",
+                "warning",
+            )
+            try:
+                force_cleanup_directory(self.ctx.temp_dir)
+            except Exception:
+                pass
+        finally:
+            self._cleanup_needed = False
+
+    def _cleanup_docker_services(self) -> bool:
+        """Stop any Docker Compose stack started for this template.
+
+        Returns ``True`` when a teardown was actually attempted - templates
+        without a compose file skip the (slow) docker invocations entirely.
+        """
+        compose_files = [
+            name
+            for name in ("docker-compose.yml", "docker-compose.yaml", "compose.yml")
+            if os.path.exists(self.ctx.temp_path(name))
+        ]
+        if not compose_files:
+            return False
+
+        try:
+            DockerCompose(self.ctx.temp_dir, compose_files[0]).cleanup()
+            return True
+        except Exception as e:
+            debug_log(f"Failed to cleanup Docker services: {e}", "warning")
+            return False
+
+    def _generate_project(self) -> None:
+        """Produce the project to inspect through the real ``startdemo`` path.
+
+        Running the actual ``ProjectScaffolder`` (rather than re-implementing
+        copy + inject here) is the point: whatever generation does for a user
+        - placeholder substitution, the ``[tool.fastapi-fastkit]`` metadata
+        block, the template-only files it filters out - is exactly what the
+        checks then see. Virtualenv creation and dependency installation are
+        switched off, so no package manager is ever invoked.
+
+        A generation failure is propagated: there is nothing meaningful to
+        inspect when the template cannot even be deployed, and ``__enter__``
+        already removes the half-written directory.
+        """
+        template_path = self.ctx.template_path.resolve()
+        project_dir = Path(self.ctx.temp_dir).resolve()
+
+        scaffold_settings = SimpleNamespace(
+            FASTKIT_TEMPLATE_ROOT=str(template_path.parent),
+            USER_WORKSPACE=str(project_dir.parent),
+            PACKAGE_MANAGER_CONFIG=settings.PACKAGE_MANAGER_CONFIG,
+        )
+        options = ScaffoldOptions(
+            project_name=project_dir.name,
+            author=str(DUMMY_METADATA["author"]),
+            author_email=str(DUMMY_METADATA["author_email"]),
+            description=str(DUMMY_METADATA["description"]),
+            package_manager="uv",
+            template=template_path.name,
+            create_project_folder=True,
+            with_venv=False,
+            with_install=False,
+        )
+
+        ProjectScaffolder(scaffold_settings, options).run()
+
+    def _load_template_config(self) -> Optional[Dict[str, Any]]:
+        """Load ``template-config.yml`` from the template, if it ships one.
+
+        The file is read from the template directory rather than the generated
+        project: it is inspector-only metadata and is deliberately not copied
+        into a user's project by the transducer.
+        """
+        config_file = str(self.ctx.template_path / "template-config.yml-tpl")
+        if not os.path.exists(config_file):
+            # Legacy layout: some templates shipped the config without the
+            # ``-tpl`` marker, in which case it still lands in the copy.
+            config_file = self.ctx.temp_path("template-config.yml")
+        if not os.path.exists(config_file):
+            debug_log(
+                "No template-config.yml found, using default testing strategy", "info"
+            )
+            return None
+
+        try:
+            import yaml
+        except ImportError:  # pragma: no cover - PyYAML is an optional extra
+            debug_log(
+                "PyYAML is not installed; ignoring template-config.yml", "warning"
+            )
+            return None
+
+        try:
+            with open(config_file, "r", encoding="utf-8") as f:
+                config = yaml.safe_load(f)
+        except (yaml.YAMLError, OSError, UnicodeDecodeError) as e:
+            debug_log(f"Failed to load template configuration: {e}", "warning")
+            return None
+
+        if not isinstance(config, dict):
+            debug_log("Invalid template configuration format", "warning")
+            return None
+
+        debug_log(
+            f"Loaded template configuration: {config.get('name', 'Unknown')}", "info"
+        )
+        return config
+
+    # -- checks ------------------------------------------------------------
+    def inspect_template(self) -> bool:
+        """Run every inspection step, stopping at the first failure.
+
+        :return: True if template is valid, False otherwise
+        """
+        check_list: List[Tuple[str, Callable[[], bool]]] = [
+            ("File Structure", self._check_file_structure),
+            ("File Extensions", self._check_file_extensions),
+            ("Test Suite Presence", self._check_tests_present),
+            ("Junk Files", self._check_no_junk_files),
+            ("Dependencies", self._check_dependencies),
+            ("Configuration Consistency", self._check_configuration_consistency),
+            ("FastAPI Implementation", self._check_fastapi_implementation),
+            ("Placeholder Substitution", self._check_no_placeholder_residue),
+            ("Template Tests", self._test_template),
+            ("Compile Check", self._check_compileall),
+            ("Type Check", self._check_mypy),
+            ("Smoke Test", self._check_smoke_test),
+            ("Dependency Freshness", self._check_dependency_freshness),
+        ]
+
+        for check_name, check_func in check_list:
+            debug_log(f"Running check: {check_name}", "info")
+            if not check_func():
+                debug_log(f"Check failed: {check_name}", "error")
+                return False
+            debug_log(f"Check passed: {check_name}", "info")
+
+        return True
+
+    def _check_file_structure(self) -> bool:
+        return checks.check_file_structure(self.ctx)
+
+    def _check_file_extensions(self) -> bool:
+        return checks.check_file_extensions(self.ctx)
+
+    def _check_dependencies(self) -> bool:
+        return checks.check_dependencies(self.ctx)
+
+    def _check_fastapi_implementation(self) -> bool:
+        return checks.check_fastapi_implementation(self.ctx)
+
+    def _check_tests_present(self) -> bool:
+        return checks.check_tests_present(self.ctx)
+
+    def _check_no_junk_files(self) -> bool:
+        return checks.check_no_junk_files(self.ctx)
+
+    def _check_no_placeholder_residue(self) -> bool:
+        return checks.check_no_placeholder_residue(self.ctx)
+
+    def _check_configuration_consistency(self) -> bool:
+        return consistency.check_configuration_consistency(self.ctx)
+
+    def _check_compileall(self) -> bool:
+        return lint.check_compileall(self.ctx)
+
+    def _check_mypy(self) -> bool:
+        return lint.check_mypy(self.ctx)
+
+    def _check_smoke_test(self) -> bool:
+        return smoke.check_smoke_test(self.ctx)
+
+    def _check_dependency_freshness(self) -> bool:
+        return freshness.check_dependency_freshness(self.ctx)
+
+    def _test_template(self) -> bool:
+        return strategies.run_template_tests(self.ctx)
+
+    def get_report(self) -> Dict[str, Any]:
+        """
+        Get inspection report with errors and warnings.
+
+        :return: Dictionary containing inspection results
+        """
+        return build_report(self.ctx)
+
+
+def inspect_fastapi_template(
+    template_path: str,
+    temp_base_dir: Optional[str] = None,
+    options: Optional[InspectionOptions] = None,
+) -> Dict[str, Any]:
+    """
+    Convenience function to inspect a FastAPI template.
+
+    :param template_path: Path to the template to inspect
+    :param temp_base_dir: Base directory for temporary files (defaults to backend directory)
+    :param options: Optional switches (offline mode, smoke test, mypy, ...)
+    :return: Inspection report dictionary
+    """
+    template_name = Path(template_path).name
+    debug_log(
+        f"Starting template inspection for {template_name} at {template_path}", "info"
+    )
+
+    with TemplateInspector(template_path, temp_base_dir, options) as inspector:
+        is_valid = inspector.inspect_template()
+        report = inspector.get_report()
+        print_report(inspector.ctx, is_valid)
+
+    debug_log(
+        f"Template inspection completed for {template_name}. Valid: {is_valid}, "
+        f"Errors: {len(report['errors'])}, Warnings: {len(report['warnings'])}",
+        "info",
+    )
+    return report

fastapi_fastkit/backend/inspection/docker.py

@@ -0,0 +1,185 @@
+# --------------------------------------------------------------------------
+# Docker Compose orchestration for templates that declare requires_docker.
+#
+# ``DockerCompose`` owns every ``docker``/``docker-compose`` invocation so the
+# test strategies stay free of process plumbing.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import json
+import subprocess
+import time
+from typing import Any, Dict, List, Optional, Sequence
+
+from fastapi_fastkit.utils.logging import debug_log
+
+COMPOSE_COMMAND = "docker-compose"
+SHORT_TIMEOUT = 10
+STATUS_TIMEOUT = 30
+CLEANUP_TIMEOUT = 60
+TEST_TIMEOUT = 300
+
+
+class DockerCompose:
+    """Thin wrapper around the docker-compose CLI for one project directory."""
+
+    def __init__(self, project_dir: str, compose_file: str = "docker-compose.yml"):
+        self.project_dir = project_dir
+        self.compose_file = compose_file
+
+    def _run(
+        self, args: Sequence[str], timeout: int
+    ) -> Optional[subprocess.CompletedProcess[str]]:
+        """Run a command in the project directory, returning ``None`` on failure."""
+        try:
+            return subprocess.run(
+                list(args),
+                cwd=self.project_dir,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+        except (subprocess.TimeoutExpired, OSError) as e:
+            debug_log(f"Command {' '.join(args)} failed: {e}", "warning")
+            return None
+
+    def _compose(
+        self, args: Sequence[str], timeout: int
+    ) -> Optional[subprocess.CompletedProcess[str]]:
+        """Run a docker-compose subcommand against the configured compose file."""
+        return self._run(
+            [COMPOSE_COMMAND, "-f", self.compose_file, *args], timeout=timeout
+        )
+
+    @staticmethod
+    def is_available() -> bool:
+        """Check that both docker and docker-compose respond."""
+        for command in (["docker", "--version"], [COMPOSE_COMMAND, "--version"]):
+            try:
+                result = subprocess.run(
+                    command, capture_output=True, text=True, timeout=SHORT_TIMEOUT
+                )
+            except (subprocess.TimeoutExpired, OSError):
+                return False
+            if result.returncode != 0:
+                return False
+        return True
+
+    def _services(self, timeout: int) -> List[Dict[str, Any]]:
+        """Return the parsed ``docker-compose ps --format json`` entries."""
+        result = self._compose(["ps", "--format", "json"], timeout=timeout)
+        if result is None or result.returncode != 0:
+            return []
+
+        services: List[Dict[str, Any]] = []
+        for line in result.stdout.strip().split("\n"):
+            if not line.strip():
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(entry, dict):
+                services.append(entry)
+        return services
+
+    def containers_running(self) -> bool:
+        """Check whether every container of the project is already up."""
+        result = self._compose(["ps", "-q"], timeout=STATUS_TIMEOUT)
+        if result is None or result.returncode != 0:
+            return False
+
+        container_ids = [line.strip() for line in result.stdout.strip().split("\n")]
+        container_ids = [cid for cid in container_ids if cid]
+        if not container_ids:
+            return False
+
+        for container_id in container_ids:
+            status = self._run(
+                ["docker", "inspect", "-f", "{{.State.Running}}", container_id],
+                timeout=SHORT_TIMEOUT,
+            )
+            if status is None or status.returncode != 0:
+                return False
+            if status.stdout.strip() != "true":
+                return False
+        return True
+
+    def up(self, timeout: int) -> subprocess.CompletedProcess[str]:
+        """Build and start the compose services in the background."""
+        result = self._compose(["up", "-d", "--build"], timeout=timeout)
+        if result is None:
+            raise subprocess.TimeoutExpired(COMPOSE_COMMAND, timeout)
+        return result
+
+    def wait_until_healthy(self, timeout: int) -> None:
+        """Block until every service reports ``running`` or ``timeout`` elapses."""
+        debug_log("Waiting for services to be healthy...", "info")
+        deadline = time.time() + timeout
+
+        while time.time() < deadline:
+            services = self._services(timeout=SHORT_TIMEOUT)
+            if services and all(
+                service.get("State") == "running" for service in services
+            ):
+                debug_log("All services are running", "info")
+                # Give the application a moment to finish booting.
+                time.sleep(10)
+                return
+
+            debug_log("Services not ready yet, waiting...", "info")
+            time.sleep(5)
+
+        debug_log(
+            f"Services did not become healthy within {timeout} seconds", "warning"
+        )
+
+    def verify_services_running(self) -> Optional[str]:
+        """Return ``None`` when db and app are up, else a descriptive error."""
+        services = self._services(timeout=STATUS_TIMEOUT)
+        if not services:
+            return "Failed to check service status"
+
+        db_running = False
+        app_running = False
+        for service in services:
+            name = str(service.get("Name", ""))
+            state = str(service.get("State", ""))
+            debug_log(f"Service {name}: {state}", "info")
+            if "db" in name and state == "running":
+                db_running = True
+            elif "app" in name and state == "running":
+                app_running = True
+
+        if not db_running:
+            return "Database service is not running"
+        if not app_running:
+            logs = self._compose(
+                ["logs", "--tail", "50", "app"], timeout=STATUS_TIMEOUT
+            )
+            if logs is not None and logs.returncode == 0:
+                return (
+                    "Application service is not running. " f"Logs: {logs.stdout[-500:]}"
+                )
+            return "Application service is not running"
+
+        debug_log("All required services are running", "info")
+        return None
+
+    def exec_tests(
+        self, use_test_script: bool
+    ) -> Optional[subprocess.CompletedProcess[str]]:
+        """Run the template's tests inside the app container."""
+        if use_test_script:
+            command = ["exec", "-T", "app", "bash", "scripts/test.sh"]
+        else:
+            command = ["exec", "-T", "app", "python", "-m", "pytest", "tests/", "-v"]
+        return self._compose(command, timeout=TEST_TIMEOUT)
+
+    def cleanup(self) -> None:
+        """Tear down services and volumes, ignoring any failure."""
+        debug_log("Cleaning up Docker services", "info")
+        self._run(
+            [COMPOSE_COMMAND, "down", "-v", "--remove-orphans"], timeout=CLEANUP_TIMEOUT
+        )
+        self._run(["docker", "system", "prune", "-f"], timeout=STATUS_TIMEOUT)

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