FastAPI-fastkit 1.4.0__tar.gz → 1.5.0__tar.gz

{fastapi_fastkit-1.4.0 → fastapi_fastkit-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: FastAPI-fastkit
-Version: 1.4.0
+Version: 1.5.0
 Summary: Fast, easy-to-use starter kit for new users of Python and FastAPI
 Author-Email: bnbong <bbbong9@gmail.com>
 License: MIT
@@ -20,6 +20,7 @@ Requires-Dist: pre-commit>=4.0.1; extra == "dev"
 Requires-Dist: mypy>=1.12.0; extra == "dev"
 Requires-Dist: isort>=5.13.2; extra == "dev"
 Requires-Dist: pygments>=2.20.0; extra == "dev"
+Requires-Dist: virtualenv>=21.7.13; extra == "dev"
 Requires-Dist: types-pyyaml>=6.0.12.20260408; extra == "dev"
 Description-Content-Type: text/markdown
 
@@ -82,7 +83,9 @@ $ pip install FastAPI-fastkit
 ```console
 fastkit init [OPTIONS]
 ```
-- What it does: Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+> [!TIP]
+> Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
@@ -98,7 +101,9 @@ fastkit init [OPTIONS]
 ```console
 fastkit init --interactive
 ```
-- What it does: Guided step-by-step project setup with intelligent feature selection
+> [!TIP]
+> Guided step-by-step project setup with intelligent feature selection
+
 - Features:
   - **Architecture preset**: `minimal` | `single-module` | `classic-layered` | `domain-starter` (default)
   - **Database selection**: PostgreSQL, MySQL, MongoDB, Redis, SQLite
@@ -114,7 +119,7 @@ fastkit init --interactive
   - **Deployment**: Docker, docker-compose with auto-generated configs
   - **Package manager**: pip, uv, pdm, poetry
   - **Custom packages**: Add your own dependencies
-- Auto-generates (varies by preset — see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
+- Auto-generates (varies by preset - see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
   - `main.py` regenerated from selected features for `minimal` / `single-module`; preserved as-shipped for `classic-layered` / `domain-starter`
   - Database and authentication configuration files at preset-specific paths
   - Docker deployment files (`Dockerfile`, `docker-compose.yml`) with the preset's correct uvicorn entrypoint
@@ -127,7 +132,9 @@ fastkit init --interactive
 ```console
 fastkit startdemo [TEMPLATE] [OPTIONS]
 ```
-- What it does: Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+> [!TIP]
+> Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
@@ -135,12 +142,6 @@ fastkit startdemo [TEMPLATE] [OPTIONS]
   - Refuses to run if the target project directory already exists (`--dry-run` excepted)
 - Tip: List available templates with `fastkit list-templates`
 
-New in v1.4.0: `fastapi-auth-jwt` (JWT auth with refresh rotation),
-`fastapi-sqlmodel` (async SQLModel + Alembic + generic CRUD), and
-`fastapi-llm-agent` (streaming Claude agent with a tool loop).
-`fastapi-dockerized` and `fastapi-async-crud` are deprecated — they still
-work, but are no longer recommended starting points.
-
 ### Add a new route
 ```console
 fastkit addroute <project_name> <route_name>
@@ -160,6 +161,25 @@ fastkit runserver [OPTIONS]
 fastkit list-templates
 ```
 
+Available templates:
+
+| Template | Description | Notes |
+|---|---|---|
+| [`fastapi-default`](src/fastapi_fastkit/fastapi_project_template/fastapi-default/README.md-tpl) | Simple FastAPI project with a classic layered layout | Good first choice |
+| [`fastapi-empty`](src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl) | Minimal FastAPI template | Base for `minimal` preset |
+| [`fastapi-single-module`](src/fastapi_fastkit/fastapi_project_template/fastapi-single-module/README.md-tpl) | Single-file FastAPI app | Base for `single-module` preset |
+| [`fastapi-domain-starter`](src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl) | Domain-oriented, pyproject-first starter for medium-sized APIs | Base for `domain-starter` preset |
+| [`fastapi-auth-jwt`](src/fastapi_fastkit/fastapi_project_template/fastapi-auth-jwt/README.md-tpl) | JWT authentication with refresh-token rotation, argon2 hashing and scopes | New in v1.4.0 |
+| [`fastapi-sqlmodel`](src/fastapi_fastkit/fastapi_project_template/fastapi-sqlmodel/README.md-tpl) | Async SQLModel + Alembic migrations + generic CRUD with pagination | New in v1.4.0 |
+| [`fastapi-llm-agent`](src/fastapi_fastkit/fastapi_project_template/fastapi-llm-agent/README.md-tpl) | Streaming Claude chat agent (SSE) with a tool-call loop | New in v1.4.0 |
+| [`fastapi-mcp`](src/fastapi_fastkit/fastapi_project_template/fastapi-mcp/README.md-tpl) | FastAPI app exposed as an MCP server | |
+| [`fastapi-psql-orm`](src/fastapi_fastkit/fastapi_project_template/fastapi-psql-orm/README.md-tpl) | Item management API with PostgreSQL, SQLModel, Alembic and docker-compose | Requires Docker |
+| [`fastapi-custom-response`](src/fastapi_fastkit/fastapi_project_template/fastapi-custom-response/README.md-tpl) | Item management API with a custom response envelope, error handling and pagination | |
+| [`fastapi-async-crud`](src/fastapi_fastkit/fastapi_project_template/fastapi-async-crud/README.md-tpl) | Async item management API | **Deprecated** — use `fastapi-sqlmodel` |
+| [`fastapi-dockerized`](src/fastapi_fastkit/fastapi_project_template/fastapi-dockerized/README.md-tpl) | Dockerized item management API | **Deprecated** — use `fastapi-default` with the Docker option in `init --interactive` |
+
+Deprecated templates still work but are no longer recommended starting points. See [Which starter should I choose?](https://bnbong.github.io/FastAPI-fastkit/user-guide/choosing-a-starter/) for a decision guide.
+
 ### Delete a project
 ```console
 fastkit deleteproject <project_name>

{fastapi_fastkit-1.4.0 → fastapi_fastkit-1.5.0}/README.md

@@ -57,7 +57,9 @@ $ pip install FastAPI-fastkit
 ```console
 fastkit init [OPTIONS]
 ```
-- What it does: Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+> [!TIP]
+> Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
@@ -73,7 +75,9 @@ fastkit init [OPTIONS]
 ```console
 fastkit init --interactive
 ```
-- What it does: Guided step-by-step project setup with intelligent feature selection
+> [!TIP]
+> Guided step-by-step project setup with intelligent feature selection
+
 - Features:
   - **Architecture preset**: `minimal` | `single-module` | `classic-layered` | `domain-starter` (default)
   - **Database selection**: PostgreSQL, MySQL, MongoDB, Redis, SQLite
@@ -89,7 +93,7 @@ fastkit init --interactive
   - **Deployment**: Docker, docker-compose with auto-generated configs
   - **Package manager**: pip, uv, pdm, poetry
   - **Custom packages**: Add your own dependencies
-- Auto-generates (varies by preset — see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
+- Auto-generates (varies by preset - see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
   - `main.py` regenerated from selected features for `minimal` / `single-module`; preserved as-shipped for `classic-layered` / `domain-starter`
   - Database and authentication configuration files at preset-specific paths
   - Docker deployment files (`Dockerfile`, `docker-compose.yml`) with the preset's correct uvicorn entrypoint
@@ -102,7 +106,9 @@ fastkit init --interactive
 ```console
 fastkit startdemo [TEMPLATE] [OPTIONS]
 ```
-- What it does: Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+> [!TIP]
+> Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
@@ -110,12 +116,6 @@ fastkit startdemo [TEMPLATE] [OPTIONS]
   - Refuses to run if the target project directory already exists (`--dry-run` excepted)
 - Tip: List available templates with `fastkit list-templates`
 
-New in v1.4.0: `fastapi-auth-jwt` (JWT auth with refresh rotation),
-`fastapi-sqlmodel` (async SQLModel + Alembic + generic CRUD), and
-`fastapi-llm-agent` (streaming Claude agent with a tool loop).
-`fastapi-dockerized` and `fastapi-async-crud` are deprecated — they still
-work, but are no longer recommended starting points.
-
 ### Add a new route
 ```console
 fastkit addroute <project_name> <route_name>
@@ -135,6 +135,25 @@ fastkit runserver [OPTIONS]
 fastkit list-templates
 ```
 
+Available templates:
+
+| Template | Description | Notes |
+|---|---|---|
+| [`fastapi-default`](src/fastapi_fastkit/fastapi_project_template/fastapi-default/README.md-tpl) | Simple FastAPI project with a classic layered layout | Good first choice |
+| [`fastapi-empty`](src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl) | Minimal FastAPI template | Base for `minimal` preset |
+| [`fastapi-single-module`](src/fastapi_fastkit/fastapi_project_template/fastapi-single-module/README.md-tpl) | Single-file FastAPI app | Base for `single-module` preset |
+| [`fastapi-domain-starter`](src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl) | Domain-oriented, pyproject-first starter for medium-sized APIs | Base for `domain-starter` preset |
+| [`fastapi-auth-jwt`](src/fastapi_fastkit/fastapi_project_template/fastapi-auth-jwt/README.md-tpl) | JWT authentication with refresh-token rotation, argon2 hashing and scopes | New in v1.4.0 |
+| [`fastapi-sqlmodel`](src/fastapi_fastkit/fastapi_project_template/fastapi-sqlmodel/README.md-tpl) | Async SQLModel + Alembic migrations + generic CRUD with pagination | New in v1.4.0 |
+| [`fastapi-llm-agent`](src/fastapi_fastkit/fastapi_project_template/fastapi-llm-agent/README.md-tpl) | Streaming Claude chat agent (SSE) with a tool-call loop | New in v1.4.0 |
+| [`fastapi-mcp`](src/fastapi_fastkit/fastapi_project_template/fastapi-mcp/README.md-tpl) | FastAPI app exposed as an MCP server | |
+| [`fastapi-psql-orm`](src/fastapi_fastkit/fastapi_project_template/fastapi-psql-orm/README.md-tpl) | Item management API with PostgreSQL, SQLModel, Alembic and docker-compose | Requires Docker |
+| [`fastapi-custom-response`](src/fastapi_fastkit/fastapi_project_template/fastapi-custom-response/README.md-tpl) | Item management API with a custom response envelope, error handling and pagination | |
+| [`fastapi-async-crud`](src/fastapi_fastkit/fastapi_project_template/fastapi-async-crud/README.md-tpl) | Async item management API | **Deprecated** — use `fastapi-sqlmodel` |
+| [`fastapi-dockerized`](src/fastapi_fastkit/fastapi_project_template/fastapi-dockerized/README.md-tpl) | Dockerized item management API | **Deprecated** — use `fastapi-default` with the Docker option in `init --interactive` |
+
+Deprecated templates still work but are no longer recommended starting points. See [Which starter should I choose?](https://bnbong.github.io/FastAPI-fastkit/user-guide/choosing-a-starter/) for a decision guide.
+
 ### Delete a project
 ```console
 fastkit deleteproject <project_name>

{fastapi_fastkit-1.4.0 → fastapi_fastkit-1.5.0}/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
 ]
 requires-python = ">=3.12"
 readme = "README.md"
-version = "1.4.0"
+version = "1.5.0"
 
 [project.license]
 text = "MIT"
@@ -32,6 +32,7 @@ dev = [
     "mypy>=1.12.0",
     "isort>=5.13.2",
     "pygments>=2.20.0",
+    "virtualenv>=21.7.13",
     "types-pyyaml>=6.0.12.20260408",
 ]
 
@@ -128,16 +129,19 @@ directory = "htmlcov"
 [dependency-groups]
 docs = [
     "mkdocs>=1.6.1",
-    "mkdocs-material>=9.6.15",
+    "mkdocs-material>=9.7.7",
     "mdx-include>=1.4.2",
     "mkdocs-static-i18n>=1.3.0",
     "pyyaml>=6.0.3",
     "types-PyYAML>=6.0.12.20250915",
     "pygments>=2.20.0",
     "requests>=2.33.0",
-    "pymdown-extensions>=10.17.2",
+    "idna>=3.15",
+    "urllib3>=2.8.0",
+    "pymdown-extensions>=11.0.1",
 ]
 translation = [
     "openai>=2.8.1",
     "anthropic>=0.74.0",
+    "anyio>=4.14.2",
 ]

fastapi_fastkit-1.5.0/src/fastapi_fastkit/__init__.py

@@ -0,0 +1 @@
+__version__ = 'v1.5.0'

{fastapi_fastkit-1.4.0 → fastapi_fastkit-1.5.0}/src/fastapi_fastkit/backend/inspection/context.py

@@ -43,6 +43,10 @@ class InspectionContext:
     warnings: List[str] = field(default_factory=list)
     #: Populated by a test strategy so later checks can reuse the environment.
     venv_path: Optional[str] = None
+    #: Populated when a test strategy already exercised the app's HTTP surface
+    #: (the Docker strategy probes the running container), so the Smoke Test
+    #: step reuses that verdict instead of booting a second server.
+    smoke_result: Optional[bool] = None
 
     def add_error(self, message: str) -> None:
         """Record a fatal finding."""

{fastapi_fastkit-1.4.0 → fastapi_fastkit-1.5.0}/src/fastapi_fastkit/backend/inspection/core.py

@@ -252,8 +252,12 @@ class TemplateInspector:
             ("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 is a pure static check: it runs before the (much
+            # heavier) Template Tests so a syntax error is reported without
+            # waiting for an environment, and so it never observes files a
+            # containerised test run left behind.
             ("Compile Check", self._check_compileall),
+            ("Template Tests", self._test_template),
             ("Type Check", self._check_mypy),
             ("Smoke Test", self._check_smoke_test),
             ("Dependency Freshness", self._check_dependency_freshness),

{fastapi_fastkit-1.4.0 → fastapi_fastkit-1.5.0}/src/fastapi_fastkit/backend/inspection/docker.py

@@ -7,6 +7,7 @@
 # @author bnbong
 # --------------------------------------------------------------------------
 import json
+import os
 import subprocess
 import time
 from typing import Any, Dict, List, Optional, Sequence
@@ -14,6 +15,12 @@ from typing import Any, Dict, List, Optional, Sequence
 from fastapi_fastkit.utils.logging import debug_log
 
 COMPOSE_COMMAND = "docker-compose"
+#: Fallback for hosts that only ship the ``docker compose`` CLI plugin.
+COMPOSE_PLUGIN_COMMAND = ["docker", "compose"]
+#: Resolved compose invocation, switched by :meth:`DockerCompose.is_available`.
+_compose_prefix: List[str] = [COMPOSE_COMMAND]
+#: Throwaway image used to give bind-mounted files back to the host user.
+RECLAIM_IMAGE = "alpine:3.20"
 SHORT_TIMEOUT = 10
 STATUS_TIMEOUT = 30
 CLEANUP_TIMEOUT = 60
@@ -43,27 +50,49 @@ class DockerCompose:
             debug_log(f"Command {' '.join(args)} failed: {e}", "warning")
             return None
 
+    @staticmethod
+    def compose_command() -> List[str]:
+        """Return the compose invocation resolved by :meth:`is_available`."""
+        return list(_compose_prefix)
+
     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
+            [*self.compose_command(), "-f", self.compose_file, *args], timeout=timeout
         )
 
+    @staticmethod
+    def _probe(command: Sequence[str]) -> bool:
+        """Return whether ``command`` exits successfully."""
+        try:
+            result = subprocess.run(
+                list(command), capture_output=True, text=True, timeout=SHORT_TIMEOUT
+            )
+        except (subprocess.TimeoutExpired, OSError):
+            return False
+        return result.returncode == 0
+
     @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
+        """Check that docker responds and a compose implementation exists.
+
+        ``docker-compose`` stays the preferred command; hosts that only ship
+        the ``docker compose`` CLI plugin fall back to it.
+        """
+        global _compose_prefix
+
+        if not DockerCompose._probe(["docker", "--version"]):
+            return False
+        if DockerCompose._probe([COMPOSE_COMMAND, "--version"]):
+            _compose_prefix = [COMPOSE_COMMAND]
+            return True
+        if DockerCompose._probe([*COMPOSE_PLUGIN_COMMAND, "version"]):
+            debug_log("Falling back to the 'docker compose' CLI plugin", "info")
+            _compose_prefix = list(COMPOSE_PLUGIN_COMMAND)
+            return True
+        return False
 
     def _services(self, timeout: int) -> List[Dict[str, Any]]:
         """Return the parsed ``docker-compose ps --format json`` entries."""
@@ -71,8 +100,34 @@ class DockerCompose:
         if result is None or result.returncode != 0:
             return []
 
+        # Compose sometimes interleaves ``time="..." level=warning`` log lines
+        # with the JSON payload, so only JSON-looking lines are considered.
+        payload = "\n".join(
+            line
+            for line in result.stdout.splitlines()
+            if line.strip().startswith(("[", "{"))
+        ).strip()
+        if not payload:
+            return []
+
+        # Compose < v2.21 prints a single JSON array, newer versions print one
+        # JSON object per line (NDJSON).
+        try:
+            document = json.loads(payload)
+        except json.JSONDecodeError:
+            return DockerCompose._parse_json_lines(payload)
+
+        if isinstance(document, dict):
+            return [document]
+        if isinstance(document, list):
+            return [entry for entry in document if isinstance(entry, dict)]
+        return []
+
+    @staticmethod
+    def _parse_json_lines(payload: str) -> List[Dict[str, Any]]:
+        """Parse NDJSON output, skipping malformed or non-object lines."""
         services: List[Dict[str, Any]] = []
-        for line in result.stdout.strip().split("\n"):
+        for line in payload.split("\n"):
             if not line.strip():
                 continue
             try:
@@ -109,7 +164,7 @@ class DockerCompose:
         """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)
+            raise subprocess.TimeoutExpired(" ".join(self.compose_command()), timeout)
         return result
 
     def wait_until_healthy(self, timeout: int) -> None:
@@ -166,6 +221,50 @@ class DockerCompose:
         debug_log("All required services are running", "info")
         return None
 
+    def published_port(self, service_hint: str = "app") -> Optional[int]:
+        """Return the host port the app container publishes, if any.
+
+        ``docker-compose ps --format json`` reports a ``Publishers`` list per
+        service; an entry with a non-zero ``PublishedPort`` is a port bound on
+        the host, which is what a smoke test can reach. Services whose name
+        contains ``service_hint`` are preferred, so a database that happens to
+        publish a port is never mistaken for the application.
+        """
+        services = self._services(timeout=STATUS_TIMEOUT)
+        if not services:
+            return None
+
+        def _matches(service: Dict[str, Any]) -> bool:
+            name = f"{service.get('Service', '')} {service.get('Name', '')}"
+            return service_hint in name
+
+        for candidate in (
+            [entry for entry in services if _matches(entry)],
+            services,
+        ):
+            for service in candidate:
+                port = self._first_published_port(service)
+                if port is not None:
+                    return port
+        return None
+
+    @staticmethod
+    def _first_published_port(service: Dict[str, Any]) -> Optional[int]:
+        """Extract the first host-bound port from one ``ps`` entry."""
+        publishers = service.get("Publishers")
+        if not isinstance(publishers, list):
+            return None
+        for publisher in publishers:
+            if not isinstance(publisher, dict):
+                continue
+            try:
+                port = int(publisher.get("PublishedPort", 0))
+            except (TypeError, ValueError):
+                continue
+            if port > 0:
+                return port
+        return None
+
     def exec_tests(
         self, use_test_script: bool
     ) -> Optional[subprocess.CompletedProcess[str]]:
@@ -176,10 +275,46 @@ class DockerCompose:
             command = ["exec", "-T", "app", "python", "-m", "pytest", "tests/", "-v"]
         return self._compose(command, timeout=TEST_TIMEOUT)
 
+    def reclaim_bind_mount_ownership(self) -> None:
+        """Give the bind-mounted project directory back to the host user.
+
+        Containers run as root, so a test run inside the stack leaves
+        root-owned artefacts (``__pycache__``, ``.pytest_cache``, ...) in the
+        mounted project. Later host-side steps and the temp directory cleanup
+        cannot touch those and fail with a PermissionError, so the ownership
+        is reset from inside a throwaway container. Best effort: a failure
+        here is never worth failing an inspection over.
+        """
+        if not hasattr(os, "getuid"):  # pragma: no cover - Windows hosts
+            return
+
+        uid, gid = os.getuid(), os.getgid()
+        if uid == 0:
+            return
+
+        debug_log("Reclaiming ownership of bind-mounted project files", "info")
+        self._run(
+            [
+                "docker",
+                "run",
+                "--rm",
+                "-v",
+                f"{self.project_dir}:/mnt",
+                RECLAIM_IMAGE,
+                "chown",
+                "-R",
+                f"{uid}:{gid}",
+                "/mnt",
+            ],
+            timeout=CLEANUP_TIMEOUT,
+        )
+
     def cleanup(self) -> None:
         """Tear down services and volumes, ignoring any failure."""
         debug_log("Cleaning up Docker services", "info")
+        self.reclaim_bind_mount_ownership()
         self._run(
-            [COMPOSE_COMMAND, "down", "-v", "--remove-orphans"], timeout=CLEANUP_TIMEOUT
+            [*self.compose_command(), "down", "-v", "--remove-orphans"],
+            timeout=CLEANUP_TIMEOUT,
         )
         self._run(["docker", "system", "prune", "-f"], timeout=STATUS_TIMEOUT)

fastapi_fastkit-1.5.0/src/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