scaffold-ca-python 0.1.1__py3-none-any.whl

scaffold_ca_python/core/structure_validator.py

@@ -0,0 +1,142 @@
+"""StructureValidator: AST-based Clean Architecture import checker (T059)."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from scaffold_ca_python.core.name_utils import ScaffoldError
+from scaffold_ca_python.models.layer import FORBIDDEN_IMPORTS, Layer
+from scaffold_ca_python.models.violation import ValidationReport, Violation
+
+# ---------------------------------------------------------------------------
+# Path → Layer mapping (filesystem directory names use underscores)
+# ---------------------------------------------------------------------------
+
+_PATH_SEGMENTS_TO_LAYER: list[tuple[tuple[str, ...], Layer]] = [
+    (("domain", "model"), Layer.DOMAIN_MODEL),
+    (("domain", "usecase"), Layer.DOMAIN_USECASE),
+    (("infrastructure", "entry_points"), Layer.ENTRY_POINTS),
+    (("infrastructure", "driven_adapters"), Layer.DRIVEN_ADAPTERS),
+    (("infrastructure", "helpers"), Layer.HELPERS),
+    (("application",), Layer.APPLICATION),
+]
+
+
+def _layer_from_path_parts(parts: tuple[str, ...]) -> Layer | None:
+    """Return the Layer for *parts* (relative to the package root), or None."""
+    for segments, layer in _PATH_SEGMENTS_TO_LAYER:
+        n = len(segments)
+        if len(parts) >= n and parts[:n] == segments:
+            return layer
+    return None
+
+
+def _layer_from_module(module: str, python_package: str) -> Layer | None:
+    """Return the Layer that *module* belongs to, or None if not project-internal."""
+    parts = tuple(module.split("."))
+    if not parts or parts[0] != python_package:
+        return None
+    return _layer_from_path_parts(parts[1:])
+
+
+def _make_hint(source: Layer, target: Layer) -> str:
+    if source in (Layer.DOMAIN_MODEL, Layer.DOMAIN_USECASE):
+        return f"Define a port interface in {source} and inject the adapter. Do not import directly from {target}."
+    return f"{source} must not import from {target}. Pass dependencies via constructor injection instead."
+
+
+# ---------------------------------------------------------------------------
+# Validator
+# ---------------------------------------------------------------------------
+
+
+class StructureValidator:
+    """Walks ``src/`` and reports Clean Architecture import violations."""
+
+    def validate(self, project_root: Path) -> ValidationReport:
+        """Scan all ``.py`` files under ``src/`` and return a ``ValidationReport``.
+
+        Args:
+            project_root: Root of the scaffolded project (contains ``pyproject.toml``).
+
+        Returns:
+            A :class:`~scaffold_ca_python.models.violation.ValidationReport`.
+
+        Raises:
+            ScaffoldError: If ``src/`` does not exist under *project_root*.
+        """
+        src = project_root / "src"
+        if not src.exists():
+            raise ScaffoldError("Could not locate src/ under project root.")
+
+        py_files = sorted(src.rglob("*.py"))
+        violations: list[Violation] = []
+        files_scanned = 0
+
+        for py_file in py_files:
+            # Determine source layer from the file path: skip files outside known layers.
+            try:
+                rel = py_file.relative_to(src)
+            except ValueError:
+                continue
+
+            parts = rel.parts
+            # parts[0] = python_package, parts[1:] = layer path
+            if len(parts) < 2:
+                continue
+
+            python_package = parts[0]
+            source_layer = _layer_from_path_parts(parts[1:])
+            if source_layer is None:
+                continue  # file outside any registered layer directory
+
+            files_scanned += 1
+            forbidden = FORBIDDEN_IMPORTS.get(source_layer, [])
+
+            try:
+                content = py_file.read_text(encoding="utf-8")
+                tree = ast.parse(content, filename=str(py_file))
+            except SyntaxError:
+                # Non-fatal — warn and continue scanning other files.
+                import warnings
+
+                warnings.warn(f"could not parse '{py_file}' — skipping", stacklevel=2)
+                continue
+
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ImportFrom) and node.module:
+                    target = _layer_from_module(node.module, python_package)
+                    if target is not None and target in forbidden:
+                        names = ", ".join(a.name for a in node.names)
+                        violations.append(
+                            Violation(
+                                source_file=py_file,
+                                line_number=node.lineno,
+                                import_statement=f"from {node.module} import {names}",
+                                source_layer=source_layer,
+                                target_layer=target,
+                                resolution_hint=_make_hint(source_layer, target),
+                            )
+                        )
+
+                elif isinstance(node, ast.Import):
+                    for alias in node.names:
+                        target = _layer_from_module(alias.name, python_package)
+                        if target is not None and target in forbidden:
+                            violations.append(
+                                Violation(
+                                    source_file=py_file,
+                                    line_number=node.lineno,
+                                    import_statement=f"import {alias.name}",
+                                    source_layer=source_layer,
+                                    target_layer=target,
+                                    resolution_hint=_make_hint(source_layer, target),
+                                )
+                            )
+
+        return ValidationReport(
+            project_root=project_root,
+            files_scanned=files_scanned,
+            violations=violations,
+        )

scaffold_ca_python/core/template_renderer.py

@@ -0,0 +1,100 @@
+"""template_renderer: Jinja2 rendering via importlib.resources (T024)."""
+
+from __future__ import annotations
+
+import importlib.resources
+from typing import Any
+
+from jinja2 import BaseLoader, Environment, TemplateNotFound
+from pydantic import BaseModel
+
+from scaffold_ca_python.core.name_utils import ScaffoldError
+
+
+class _ResourceLoader(BaseLoader):
+    """Jinja2 loader backed by ``importlib.resources.files()``."""
+
+    _PACKAGE = "scaffold_ca_python.templates"
+
+    def get_source(
+        self,
+        environment: Environment,
+        template: str,
+    ) -> tuple[str, str | None, Any]:
+        try:
+            ref = importlib.resources.files(self._PACKAGE).joinpath(template)
+            source = ref.read_text(encoding="utf-8")
+            return source, str(ref), None
+        except (FileNotFoundError, TypeError) as exc:
+            raise TemplateNotFound(template) from exc
+
+
+class TemplateRenderer:
+    """Load and render Jinja2 templates from the ``scaffold_ca_python.templates`` package.
+
+    Usage::
+
+        renderer = TemplateRenderer()
+
+        # Render a packaged template
+        output = renderer.render("domain_model.py.j2", module_ctx)
+
+        # Render an inline template string (useful for testing / simple cases)
+        output = renderer.render_string("class {{ class_name }}:", ctx_dict)
+    """
+
+    def __init__(self) -> None:
+        self._env = Environment(
+            loader=_ResourceLoader(),
+            autoescape=False,
+            keep_trailing_newline=True,
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def render(self, template_name: str, context: BaseModel | dict[str, Any]) -> str:
+        """Render *template_name* with the fields from *context*.
+
+        *context* may be a Pydantic ``BaseModel`` (``model_dump()`` is called
+        automatically) or a plain ``dict``.
+
+        Raises
+        ------
+        ScaffoldError
+            When the template is not found in the package.
+        """
+        ctx_dict = self._to_dict(context)
+        try:
+            tmpl = self._env.get_template(template_name)
+        except TemplateNotFound as exc:
+            raise ScaffoldError(
+                f"Template {template_name!r} not found in scaffold_ca_python.templates. "
+                "Hint: ensure the template file exists in the package."
+            ) from exc
+        return tmpl.render(**ctx_dict)
+
+    def render_string(self, source: str, context: BaseModel | dict[str, Any]) -> str:
+        """Render an inline *source* string with *context*.
+
+        Primarily useful for tests and one-off generation.
+        """
+        ctx_dict = self._to_dict(context)
+        tmpl = self._env.from_string(source)
+        return tmpl.render(**ctx_dict)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _to_dict(context: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        """Convert a Pydantic model or plain dict to a render context dict."""
+        if isinstance(context, dict):
+            return context
+        # Pydantic v2 BaseModel
+        if hasattr(context, "model_dump"):
+            return context.model_dump()
+        # Fallback: try __dict__
+        return dict(vars(context))

scaffold_ca_python/factory/__init__.py

@@ -0,0 +1,16 @@
+"""Factory contracts for scaffold module generation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from scaffold_ca_python.core.module_builder import ModuleBuilder
+
+
+@runtime_checkable
+class ModuleFactory(Protocol):
+    """Contract for type-specific module generators."""
+
+    def build(self, builder: ModuleBuilder) -> None:
+        """Populate *builder* with file/dependency operations for this module type."""

scaffold_ca_python/factory/driven_adapters/da_generic.py

@@ -0,0 +1,65 @@
+"""DrivenAdapterGeneric factory implementation (T029)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from scaffold_ca_python.core.name_utils import to_snake_case
+from scaffold_ca_python.core.project_detector import resolve_tests_root
+from scaffold_ca_python.factory import ModuleFactory
+
+if TYPE_CHECKING:
+    from scaffold_ca_python.core.module_builder import ModuleBuilder
+
+
+class DrivenAdapterGeneric(ModuleFactory):
+    """Factory for Generic driven-adapter type."""
+
+    def build(self, builder: ModuleBuilder) -> None:
+        """Build Generic driven-adapter files.
+
+        Queues files:
+        - src/infrastructure/driven_adapters/<snake_name>/__init__.py
+        - src/infrastructure/driven_adapters/<snake_name>/<snake_name>_adapter.py
+        - tests/infrastructure/driven_adapters/<snake_name>/test_<snake_name>_adapter.py
+
+        No dependencies injected for generic type.
+        """
+        project_root = builder.project_root
+        pkg = builder.project_ctx.python_package
+
+        # Get adapter name from module context
+        adapter_name = builder.module_ctx.name if builder.module_ctx else "CustomAdapter"
+        snake_name = to_snake_case(adapter_name)
+
+        # Setup directory paths
+        src_dir = project_root / "src" / pkg / "infrastructure" / "driven_adapters" / snake_name
+        test_dir = resolve_tests_root(project_root) / "infrastructure" / "driven_adapters" / snake_name
+
+        # Template base path for driven_adapter/generic
+        base = "driven_adapter/generic"
+
+        # Build context dict from module context
+        ctx_dict = {}
+        if builder.module_ctx:
+            ctx_dict.update(builder.module_ctx.model_dump())
+
+        # Add source files
+        builder.add_file(
+            src_dir / "__init__.py",
+            builder.render(f"{base}/__init__.py.jinja2", ctx_dict),
+            template_name=f"{base}/__init__.py.jinja2",
+        )
+        builder.add_file(
+            src_dir / f"{snake_name}_adapter.py",
+            builder.render(f"{base}/adapter.py.jinja2", ctx_dict),
+            template_name=f"{base}/adapter.py.jinja2",
+        )
+
+        # Add test files
+        builder.add_file(
+            test_dir / f"test_{snake_name}_adapter.py",
+            builder.render(f"{base}/test_adapter.py.jinja2", ctx_dict),
+            template_name=f"{base}/test_adapter.py.jinja2",
+            is_test=True,
+        )

scaffold_ca_python/factory/driven_adapters/da_rest_consumer.py

@@ -0,0 +1,64 @@
+"""DrivenAdapterRestConsumer factory implementation (T025)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from scaffold_ca_python.core.project_detector import resolve_tests_root
+from scaffold_ca_python.factory import ModuleFactory
+
+if TYPE_CHECKING:
+    from scaffold_ca_python.core.module_builder import ModuleBuilder
+
+
+class DrivenAdapterRestConsumer(ModuleFactory):
+    """Factory for REST Consumer driven-adapter type."""
+
+    def build(self, builder: ModuleBuilder) -> None:
+        """Build REST Consumer driven-adapter files and dependencies.
+
+        Queues files:
+        - src/infrastructure/driven_adapters/rest_consumer/__init__.py
+        - src/infrastructure/driven_adapters/rest_consumer/rest_consumer.py
+        - tests/infrastructure/driven_adapters/rest_consumer/test_rest_consumer.py
+
+        Injects:
+        - httpx>=0.27
+        """
+        project_root = builder.project_root
+        pkg = builder.project_ctx.python_package
+
+        # Setup directory paths
+        src_dir = project_root / "src" / pkg / "infrastructure" / "driven_adapters" / "rest_consumer"
+        test_dir = resolve_tests_root(project_root) / "infrastructure" / "driven_adapters" / "rest_consumer"
+
+        # Template base path for driven_adapter/rest_consumer
+        base = "driven_adapter/rest_consumer"
+
+        # Build context dict from module context
+        ctx_dict = {}
+        if builder.module_ctx:
+            ctx_dict.update(builder.module_ctx.model_dump())
+
+        # Add source files
+        builder.add_file(
+            src_dir / "__init__.py",
+            builder.render(f"{base}/__init__.py.jinja2", ctx_dict),
+            template_name=f"{base}/__init__.py.jinja2",
+        )
+        builder.add_file(
+            src_dir / "rest_consumer.py",
+            builder.render(f"{base}/rest_consumer.py.jinja2", ctx_dict),
+            template_name=f"{base}/rest_consumer.py.jinja2",
+        )
+
+        # Add test files
+        builder.add_file(
+            test_dir / "test_rest_consumer.py",
+            builder.render(f"{base}/test_rest_consumer.py.jinja2", ctx_dict),
+            template_name=f"{base}/test_rest_consumer.py.jinja2",
+            is_test=True,
+        )
+
+        # Add dependency
+        builder.add_dependency("httpx>=0.27")

scaffold_ca_python/factory/driven_adapters/da_secrets.py

@@ -0,0 +1,64 @@
+"""DrivenAdapterSecrets factory implementation (T027)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from scaffold_ca_python.core.project_detector import resolve_tests_root
+from scaffold_ca_python.factory import ModuleFactory
+
+if TYPE_CHECKING:
+    from scaffold_ca_python.core.module_builder import ModuleBuilder
+
+
+class DrivenAdapterSecrets(ModuleFactory):
+    """Factory for Secrets driven-adapter type."""
+
+    def build(self, builder: ModuleBuilder) -> None:
+        """Build Secrets driven-adapter files and dependencies.
+
+        Queues files:
+        - src/infrastructure/driven_adapters/secrets/__init__.py
+        - src/infrastructure/driven_adapters/secrets/secrets_adapter.py
+        - tests/infrastructure/driven_adapters/secrets/test_secrets_adapter.py
+
+        Injects:
+        - boto3>=1.34
+        """
+        project_root = builder.project_root
+        pkg = builder.project_ctx.python_package
+
+        # Setup directory paths
+        src_dir = project_root / "src" / pkg / "infrastructure" / "driven_adapters" / "secrets"
+        test_dir = resolve_tests_root(project_root) / "infrastructure" / "driven_adapters" / "secrets"
+
+        # Template base path for driven_adapter/secrets
+        base = "driven_adapter/secrets"
+
+        # Build context dict from module context
+        ctx_dict = {}
+        if builder.module_ctx:
+            ctx_dict.update(builder.module_ctx.model_dump())
+
+        # Add source files
+        builder.add_file(
+            src_dir / "__init__.py",
+            builder.render(f"{base}/__init__.py.jinja2", ctx_dict),
+            template_name=f"{base}/__init__.py.jinja2",
+        )
+        builder.add_file(
+            src_dir / "secrets_adapter.py",
+            builder.render(f"{base}/secrets_adapter.py.jinja2", ctx_dict),
+            template_name=f"{base}/secrets_adapter.py.jinja2",
+        )
+
+        # Add test files
+        builder.add_file(
+            test_dir / "test_secrets_adapter.py",
+            builder.render(f"{base}/test_secrets_adapter.py.jinja2", ctx_dict),
+            template_name=f"{base}/test_secrets_adapter.py.jinja2",
+            is_test=True,
+        )
+
+        # Add dependency
+        builder.add_dependency("boto3>=1.34")

scaffold_ca_python/factory/entry_points/ep_agent.py

@@ -0,0 +1,91 @@
+"""EntryPointAgent factory implementation (T017)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from scaffold_ca_python.core.project_detector import resolve_tests_root
+from scaffold_ca_python.factory import ModuleFactory
+
+if TYPE_CHECKING:
+    from scaffold_ca_python.core.module_builder import ModuleBuilder
+
+
+class EntryPointAgent(ModuleFactory):
+    """Factory for Agent entry-point type."""
+
+    def build(self, builder: ModuleBuilder) -> None:
+        """Build Agent entry-point files and dependencies.
+
+        Queues files:
+        - src/infrastructure/entry_points/agent/__init__.py
+        - src/infrastructure/entry_points/agent/agent.py
+        - src/infrastructure/entry_points/agent/card.py
+        - tests/infrastructure/entry_points/agent/test_agent.py
+
+        Overwrites:
+        - src/main.py (if exists)
+
+        Injects:
+        - a2a-sdk>=0.1
+        """
+        project_root = builder.project_root
+        pkg = builder.project_ctx.python_package
+
+        # Setup directory paths
+        src_dir = project_root / "src" / pkg / "infrastructure" / "entry_points" / "agent"
+        test_dir = resolve_tests_root(project_root) / "infrastructure" / "entry_points" / "agent"
+        main_py = project_root / "src" / pkg / "main.py"
+
+        # Template base path for entry_point/agent
+        base = "entry_point/agent"
+
+        # Build context dict from module context and params
+        ctx_dict = {}
+        if builder.module_ctx:
+            ctx_dict.update(builder.module_ctx.model_dump())
+
+        # Add enable_kafka and enable_mcp_client if present in params
+        if builder.get_param("enable_kafka"):
+            ctx_dict["enable_kafka"] = True
+        if builder.get_param("enable_mcp_client"):
+            ctx_dict["enable_mcp_client"] = True
+
+        # Add source files
+        def tpl(f: str) -> str:
+            return f"{base}/{f}"
+
+        builder.add_file(
+            src_dir / "__init__.py",
+            builder.render(f"{base}/__init__.py.jinja2", ctx_dict),
+            template_name=tpl("__init__.py.jinja2"),
+        )
+        builder.add_file(
+            src_dir / "agent.py",
+            builder.render(f"{base}/agent.py.jinja2", ctx_dict),
+            template_name=tpl("agent.py.jinja2"),
+        )
+        builder.add_file(
+            src_dir / "card.py",
+            builder.render(f"{base}/card.py.jinja2", ctx_dict),
+            template_name=tpl("card.py.jinja2"),
+        )
+
+        # Add test files
+        builder.add_file(
+            test_dir / "test_agent.py",
+            builder.render(f"{base}/test_agent.py.jinja2", ctx_dict),
+            template_name=tpl("test_agent.py.jinja2"),
+            is_test=True,
+        )
+
+        # Overwrite main.py
+        builder.add_file(
+            main_py,
+            builder.render(f"{base}/entrypoint_main.py.jinja2", ctx_dict),
+            template_name=tpl("entrypoint_main.py.jinja2"),
+            overwrite=True,
+        )
+
+        # Add dependency
+        builder.add_dependency("a2a-sdk>=0.1")

scaffold_ca_python/factory/entry_points/ep_generic.py

@@ -0,0 +1,75 @@
+"""EntryPointGeneric factory implementation (T021)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from scaffold_ca_python.core.project_detector import resolve_tests_root
+from scaffold_ca_python.factory import ModuleFactory
+
+if TYPE_CHECKING:
+    from scaffold_ca_python.core.module_builder import ModuleBuilder
+
+
+class EntryPointGeneric(ModuleFactory):
+    """Factory for Generic entry-point type."""
+
+    def build(self, builder: ModuleBuilder) -> None:
+        """Build Generic entry-point files.
+
+        Queues files:
+        - src/infrastructure/entry_points/generic/__init__.py
+        - src/infrastructure/entry_points/generic/entry_point.py
+        - tests/infrastructure/entry_points/generic/test_entry_point.py
+
+        Overwrites:
+        - src/main.py (if exists)
+
+        No dependencies injected for generic type.
+        """
+        project_root = builder.project_root
+        pkg = builder.project_ctx.python_package
+
+        # Setup directory paths
+        src_dir = project_root / "src" / pkg / "infrastructure" / "entry_points" / "generic"
+        test_dir = resolve_tests_root(project_root) / "infrastructure" / "entry_points" / "generic"
+        main_py = project_root / "src" / pkg / "main.py"
+
+        # Template base path for entry_point/generic
+        base = "entry_point/generic"
+
+        # Build context dict from module context
+        ctx_dict = {}
+        if builder.module_ctx:
+            ctx_dict.update(builder.module_ctx.model_dump())
+
+        # Add source files
+        def tpl(f: str) -> str:
+            return f"{base}/{f}"
+
+        builder.add_file(
+            src_dir / "__init__.py",
+            builder.render(f"{base}/__init__.py.jinja2", ctx_dict),
+            template_name=tpl("__init__.py.jinja2"),
+        )
+        builder.add_file(
+            src_dir / "entry_point.py",
+            builder.render(f"{base}/handler.py.jinja2", ctx_dict),
+            template_name=tpl("handler.py.jinja2"),
+        )
+
+        # Add test files
+        builder.add_file(
+            test_dir / "test_entry_point.py",
+            builder.render(f"{base}/test_handler.py.jinja2", ctx_dict),
+            template_name=tpl("test_handler.py.jinja2"),
+            is_test=True,
+        )
+
+        # Overwrite main.py
+        builder.add_file(
+            main_py,
+            builder.render(f"{base}/entrypoint_main.py.jinja2", ctx_dict),
+            template_name=tpl("entrypoint_main.py.jinja2"),
+            overwrite=True,
+        )