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

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,89 @@
+# --------------------------------------------------------------------------
+# Static analysis of the generated project.
+#
+# ``compileall`` is mandatory - a template that cannot be byte-compiled is
+# broken beyond argument. ``mypy`` is opt-in because it needs the template's
+# own dependencies installed and is far slower.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import subprocess
+import sys
+from typing import List
+
+from fastapi_fastkit.utils.logging import debug_log
+
+from .context import InspectionContext
+
+COMPILE_TIMEOUT = 120
+MYPY_TIMEOUT = 300
+
+
+def _interpreter(ctx: InspectionContext) -> str:
+    """Prefer the inspection venv interpreter, falling back to the host one."""
+    return ctx.python_executable() or sys.executable
+
+
+def check_compileall(ctx: InspectionContext) -> bool:
+    """Byte-compile every Python file of the generated project."""
+    command: List[str] = [
+        _interpreter(ctx),
+        "-m",
+        "compileall",
+        "-q",
+        "-x",
+        r"(\.venv|venv|node_modules)",
+        ctx.temp_dir,
+    ]
+    try:
+        result = subprocess.run(
+            command,
+            cwd=ctx.temp_dir,
+            capture_output=True,
+            text=True,
+            timeout=COMPILE_TIMEOUT,
+        )
+    except subprocess.TimeoutExpired:
+        ctx.add_error("compileall timed out")
+        return False
+    except OSError as e:
+        ctx.add_error(f"Failed to run compileall: {e}")
+        return False
+
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        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}")

fastapi_fastkit/backend/inspection/smoke.py

@@ -0,0 +1,327 @@
+# --------------------------------------------------------------------------
+# HTTP smoke test for a generated project.
+#
+# Booting the application is the only honest way to prove a template works:
+# a substring search for "FastAPI" in main.py cannot tell a working app from
+# one that raises on import. The generated project is started with uvicorn in
+# a subprocess on a free port; ``/docs`` must answer 200 and ``/health``, when
+# the template exposes one, must answer 200 as well.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import os
+import signal
+import socket
+import subprocess
+import tempfile
+import time
+import tomllib
+import urllib.error
+import urllib.request
+from typing import IO, List, Optional, Tuple
+
+from fastapi_fastkit.utils.logging import debug_log
+
+from .context import InspectionContext
+
+#: Probed in order when no explicit app_module is declared.
+MAIN_MODULE_CANDIDATES = [
+    ("src/app/main.py", "src.app.main"),
+    ("src/main.py", "src.main"),
+    ("app/main.py", "app.main"),
+    ("main.py", "main"),
+]
+DEFAULT_APP_ATTRIBUTE = "app"
+SHUTDOWN_TIMEOUT = 10
+
+#: How many ports to try before giving up. ``find_free_port`` releases the
+#: port before uvicorn binds it, so another process can win the race; on a
+#: busy CI machine that is common enough to be worth retrying.
+PORT_ATTEMPTS = 3
+
+#: Bytes of captured server output attached to a failure report.
+LOG_TAIL_BYTES = 4000
+
+
+def find_free_port() -> int:
+    """Reserve and release a port so uvicorn can bind it."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        port: int = sock.getsockname()[1]
+    return port
+
+
+def _app_module_from_pyproject(ctx: InspectionContext) -> Optional[str]:
+    """Read ``[tool.fastapi-fastkit].app_module`` from the generated project."""
+    pyproject_path = ctx.temp_path("pyproject.toml")
+    if not os.path.exists(pyproject_path):
+        return None
+    try:
+        with open(pyproject_path, "rb") as f:
+            data = tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError) as e:
+        debug_log(f"Could not read generated pyproject.toml: {e}", "warning")
+        return None
+    value = data.get("tool", {}).get("fastapi-fastkit", {}).get("app_module")
+    return str(value) if value else None
+
+
+def _app_module_from_template_config(ctx: InspectionContext) -> Optional[str]:
+    """Read ``app_module`` from template-config.yml, if the template ships one."""
+    if not ctx.template_config:
+        return None
+    value = ctx.template_config.get("app_module")
+    return str(value) if value else None
+
+
+def _app_module_from_layout(ctx: InspectionContext) -> Optional[str]:
+    """Fall back to the conventional main module locations."""
+    for relative_path, dotted in MAIN_MODULE_CANDIDATES:
+        if os.path.exists(ctx.temp_path(*relative_path.split("/"))):
+            return f"{dotted}:{DEFAULT_APP_ATTRIBUTE}"
+    return None
+
+
+def resolve_app_module(ctx: InspectionContext) -> Optional[str]:
+    """Determine the ``module:attribute`` uvicorn target for the project.
+
+    Resolution order: generated ``pyproject.toml`` metadata, then
+    ``template-config.yml``, then the conventional file layout.
+    """
+    for resolver in (
+        _app_module_from_pyproject,
+        _app_module_from_template_config,
+        _app_module_from_layout,
+    ):
+        value = resolver(ctx)
+        if value:
+            if ":" not in value:
+                value = f"{value}:{DEFAULT_APP_ATTRIBUTE}"
+            debug_log(f"Resolved app module: {value}", "info")
+            return value
+    return None
+
+
+def _probe(url: str, timeout: int = 5) -> Optional[int]:
+    """GET ``url`` and return its status code, or ``None`` when unreachable."""
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as response:
+            status: int = response.status
+            return status
+    except urllib.error.HTTPError as e:
+        return int(e.code)
+    except (urllib.error.URLError, OSError, TimeoutError):
+        return None
+
+
+def _wait_for_server(
+    process: "subprocess.Popen[bytes]", base_url: str, timeout: int
+) -> Tuple[bool, str]:
+    """Poll ``/docs`` until the server answers, the process dies or time runs out."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if process.poll() is not None:
+            return False, "server process exited before becoming reachable"
+        status = _probe(f"{base_url}/docs")
+        if status is not None:
+            if status == 200:
+                return True, ""
+            return False, f"/docs returned HTTP {status} (expected 200)"
+        time.sleep(0.5)
+    return False, f"server did not become reachable within {timeout}s"
+
+
+def _signal_group(process: "subprocess.Popen[bytes]", sig: int) -> bool:
+    """Signal the server's whole process group, if it has one of its own.
+
+    uvicorn spawns reloader / worker children, and signalling only the
+    parent leaves them holding the port. The process is started with
+    ``start_new_session=True`` so the group id equals its pid.
+
+    Only a group we created ourselves is ever signalled: the pid must be a
+    real positive integer and must be its own group leader. Anything else --
+    a mocked process object, a pid that has been reaped and rejoined another
+    group, the init group, or the group this interpreter itself belongs to --
+    falls back to signalling the single process, because signalling the wrong
+    group would tear down unrelated processes (a CI runner, for one).
+
+    :return: True when the group was signalled, False to fall back
+    """
+    if not hasattr(os, "killpg"):  # pragma: no cover - non-POSIX
+        return False
+
+    pid = process.pid
+    if type(pid) is not int or pid <= 1:
+        debug_log(f"Refusing to signal process group for pid {pid!r}", "debug")
+        return False
+
+    try:
+        pgid = os.getpgid(pid)
+    except OSError as e:
+        debug_log(f"Could not read smoke test process group: {e}", "debug")
+        return False
+
+    # start_new_session=True makes the child its own group leader, so a pgid
+    # that differs from the pid means the process is sharing someone else's
+    # group -- never ours to signal.
+    if pgid != pid or pgid <= 1 or pgid == os.getpgrp():
+        debug_log(
+            f"Smoke test process {pid} is not its own group leader "
+            f"(pgid {pgid}); signalling the process only",
+            "debug",
+        )
+        return False
+
+    try:
+        os.killpg(pgid, sig)
+        return True
+    except OSError as e:
+        debug_log(f"Could not signal smoke test process group: {e}", "debug")
+        return False
+
+
+def _terminate(process: "subprocess.Popen[bytes]") -> None:
+    """Stop the server process (and its group), escalating to SIGKILL."""
+    if process.poll() is not None:
+        return
+
+    if not _signal_group(process, signal.SIGTERM):
+        process.terminate()
+    try:
+        process.wait(timeout=SHUTDOWN_TIMEOUT)
+        return
+    except subprocess.TimeoutExpired:
+        pass
+
+    if not _signal_group(process, signal.SIGKILL):
+        process.kill()
+    try:
+        process.wait(timeout=SHUTDOWN_TIMEOUT)
+    except subprocess.TimeoutExpired:  # pragma: no cover - defensive
+        debug_log("Smoke test server could not be killed", "warning")
+
+
+#: Phrases uvicorn / asyncio emit when the chosen port was taken between
+#: ``find_free_port`` releasing it and uvicorn binding it.
+_PORT_CONFLICT_MARKERS = (
+    "address already in use",
+    "error while attempting to bind on address",
+    "only one usage of each socket address",
+)
+
+
+def _is_port_conflict(output: str) -> bool:
+    """Return True when captured server output shows a failed port bind."""
+    lowered = output.lower()
+    return any(marker in lowered for marker in _PORT_CONFLICT_MARKERS)
+
+
+def _read_log_tail(log_file: IO[bytes]) -> str:
+    """Return the tail of the captured server output."""
+    try:
+        log_file.flush()
+        size = os.fstat(log_file.fileno()).st_size
+        log_file.seek(max(0, size - LOG_TAIL_BYTES))
+        return log_file.read().decode("utf-8", errors="replace").strip()
+    except OSError as e:  # pragma: no cover - defensive
+        debug_log(f"Could not read smoke test server log: {e}", "warning")
+        return ""
+
+
+def check_smoke_test(ctx: InspectionContext) -> bool:
+    """Boot the generated project and verify its HTTP surface."""
+    if not ctx.options.run_smoke_test:
+        debug_log("Smoke test disabled", "info")
+        return True
+
+    python_executable = ctx.python_executable()
+    if not python_executable or not os.path.exists(python_executable):
+        ctx.add_error(
+            "Smoke test requires an installed environment, but no virtual "
+            "environment was prepared for the generated project"
+        )
+        return False
+
+    app_module = resolve_app_module(ctx)
+    if not app_module:
+        ctx.add_error(
+            "Could not determine the ASGI app module: declare "
+            "[tool.fastapi-fastkit].app_module or ship a conventional main.py"
+        )
+        return False
+
+    env = os.environ.copy()
+    env["PYTHONPATH"] = ctx.temp_dir + os.pathsep + env.get("PYTHONPATH", "")
+
+    last_failure = ""
+    for attempt in range(1, PORT_ATTEMPTS + 1):
+        port = find_free_port()
+        base_url = f"http://127.0.0.1:{port}"
+        command: List[str] = [
+            python_executable,
+            "-m",
+            "uvicorn",
+            app_module,
+            "--host",
+            "127.0.0.1",
+            "--port",
+            str(port),
+        ]
+
+        debug_log(f"Starting smoke test server: {' '.join(command)}", "info")
+
+        # The server's output goes to a temp file rather than a pipe: uvicorn
+        # keeps logging for as long as it runs, and a pipe nobody drains fills
+        # its buffer and blocks the server mid-request.
+        with tempfile.TemporaryFile() as log_file:
+            try:
+                process = subprocess.Popen(
+                    command,
+                    cwd=ctx.temp_dir,
+                    stdout=log_file,
+                    stderr=subprocess.STDOUT,
+                    env=env,
+                    # Own process group, so terminating the server also stops
+                    # any worker it spawned instead of orphaning it.
+                    start_new_session=True,
+                )
+            except OSError as e:
+                ctx.add_error(f"Failed to start the application server: {e}")
+                return False
+
+            try:
+                reachable, reason = _wait_for_server(
+                    process, base_url, ctx.options.smoke_timeout
+                )
+                if not reachable:
+                    output = _read_log_tail(log_file)
+                    last_failure = f"Smoke test failed: {reason}\n{output}".rstrip()
+                    if _is_port_conflict(output) and attempt < PORT_ATTEMPTS:
+                        debug_log(
+                            f"Port {port} was taken before uvicorn bound it; "
+                            f"retrying on another port ({attempt}/{PORT_ATTEMPTS})",
+                            "warning",
+                        )
+                        continue
+                    ctx.add_error(last_failure)
+                    return False
+
+                health_status = _probe(f"{base_url}/health")
+                if health_status is None:
+                    ctx.add_warning("Smoke test: /health did not respond")
+                elif health_status == 404:
+                    debug_log("Template exposes no /health endpoint, skipping", "info")
+                elif health_status != 200:
+                    ctx.add_error(
+                        f"Smoke test failed: /health returned HTTP {health_status} "
+                        "(expected 200)\n" + _read_log_tail(log_file)
+                    )
+                    return False
+            finally:
+                _terminate(process)
+
+        debug_log("Smoke test passed", "info")
+        return True
+
+    ctx.add_error(last_failure or "Smoke test failed: no free port could be bound")
+    return False