📘 Technical Design 013 — Bootstrap Plan Building via Package Scanning¶

# Must explicitly import and list all services
from myapp.services import UserService, EmailService
from myapp.repositories import UserRepository

# Manual registration via TD-012 AnnotationProcessor
processor = AnnotationProcessor(...)
processor.process([UserService, EmailService, UserRepository])

from typing import Protocol
from collections.abc import Sequence

from loryth.common.di.bootstrap import RegistrationStep


class RegistrationRule(Protocol):
    """Protocol for rules that translate annotated classes into registration steps.

    Each rule inspects a class and optionally returns registration steps if the
    class matches the rule's criteria (e.g., has specific annotations). Multiple
    rules can apply to the same class (union semantics).

    Rules should be stateless and idempotent - calling apply() multiple times
    with the same class should produce equivalent results.
    """

    def apply(self, cls: type) -> Sequence[RegistrationStep]:
        """Analyze a class and return registration steps if applicable.

        :param cls: The class to analyze
        :return: Sequence of RegistrationStep objects, or empty sequence if rule
                 doesn't apply to this class
        :raises Exception: Rules may raise exceptions on invalid configuration;
                          builder wraps these in BootstrapError
        """
        ...

from dataclasses import dataclass

from loryth.common.annotations import find_annotation
from loryth.common.di.annotations import ServiceAnnotation
from loryth.common.di.bootstrap import (
    RegistrationStep,
    SingletonRegistrationStep,
    TransientRegistrationStep,
)
from loryth.common.di.container import ServiceLifecycle


@dataclass(frozen=True)
class ServiceAnnotationRule:
    """Rule that handles @service annotations."""

    def apply(self, cls: type) -> Sequence[RegistrationStep]:
        """Return registration step if class has @service annotation.

        Respects the lifecycle specified in the annotation (singleton/transient).

        :param cls: The class to analyze
        :return: Sequence containing singleton or transient registration step,
                 or empty sequence if class lacks @service annotation
        """
        annotation = find_annotation(cls, ServiceAnnotation)
        if annotation is None:
            return []

        if annotation.lifecycle == ServiceLifecycle.SINGLETON:
            return [SingletonRegistrationStep(cls, cls)]
        elif annotation.lifecycle == ServiceLifecycle.TRANSIENT:
            return [TransientRegistrationStep(cls, cls)]

        # Default to singleton if lifecycle not specified
        return [SingletonRegistrationStep(cls, cls)]

from loryth.common.di.annotations import ComponentAnnotation


@dataclass(frozen=True)
class ComponentAnnotationRule:
    """Rule that handles @component annotations."""

    def apply(self, cls: type) -> Sequence[RegistrationStep]:
        """Return singleton registration step if class has @component annotation.

        @component always produces singleton registrations.

        :param cls: The class to analyze
        :return: Sequence containing singleton registration step,
                 or empty sequence if class lacks @component annotation
        """
        annotation = find_annotation(cls, ComponentAnnotation)
        if annotation is None:
            return []

        return [SingletonRegistrationStep(cls, cls)]

import inspect
import typing
from typing import Any, Callable

from loryth.common.di.annotations import ConfigurationAnnotation, BeanAnnotation
from loryth.common.di.bootstrap import FactoryRegistrationStep


@dataclass(frozen=True)
class ConfigurationAnnotationRule:
    """Rule that handles @configuration classes and @bean methods.

    Produces:
    1. Singleton registration for the @configuration class itself
    2. Factory registrations for each @bean method on the class
    """

    def apply(self, cls: type) -> Sequence[RegistrationStep]:
        """Return registration steps for @configuration class and its @bean methods.

        The configuration class is registered as a singleton, and each @bean method
        produces a factory registration that resolves the configuration instance
        and invokes the method.

        :param cls: The class to analyze
        :return: Sequence containing singleton step for configuration class plus
                 factory steps for each @bean method, or empty sequence if class
                 lacks @configuration annotation
        """
        annotation = find_annotation(cls, ConfigurationAnnotation)
        if annotation is None:
            return []

        steps: list[RegistrationStep] = []

        # Register configuration class as singleton
        steps.append(SingletonRegistrationStep(cls, cls))

        # Scan for @bean methods
        for name, member in inspect.getmembers(cls, predicate=inspect.ismethod):
            bean_annotation = find_annotation(member, BeanAnnotation)
            if bean_annotation is None:
                continue

            # Extract return type from method signature
            return_type = self._extract_return_type(member)
            if return_type is None:
                continue

            # Create factory that resolves config and calls method
            factory = self._create_bean_factory(cls, member)
            steps.append(FactoryRegistrationStep(return_type, factory))

        return steps

    def _extract_return_type(self, method: Callable[..., Any]) -> type | None:
        """Extract return type annotation from method signature.

        :param method: Method to analyze
        :return: Return type annotation, or None if not present
        """
        hints = typing.get_type_hints(method)
        return hints.get('return')

    def _create_bean_factory(
        self,
        config_cls: type,
        method: Callable[..., Any]
    ) -> Callable[[Any], Any]:
        """Create factory function that resolves config and invokes bean method.

        The factory accepts a container, resolves the configuration instance,
        and calls the bean method on that instance.

        :param config_cls: Configuration class type
        :param method: Bean method to invoke
        :return: Factory function accepting container and returning bean instance
        """
        def factory(container: Any) -> Any:
            config_instance = container.resolve(config_cls)
            return method(config_instance)

        return factory

from dataclasses import dataclass
from collections.abc import Sequence

from loryth.common.annotations import Annotation


@dataclass(frozen=True)
class ScanningConfiguration:
    """Immutable configuration for package scanning behavior.

    :param packages: Sequence of package names to scan (e.g., ["myapp.services"])
    :param include_annotations: If non-empty, only classes with these annotations are included
    :param exclude_patterns: Glob patterns for excluding classes/modules (e.g., ["*_test.py"])
    :param recursive: Whether to recursively scan subpackages (default: True)
    """

    packages: Sequence[str]
    include_annotations: Sequence[type[Annotation]] = ()
    exclude_patterns: Sequence[str] = ()
    recursive: bool = True

import fnmatch
from collections.abc import Sequence

from loryth.common.annotations import AnnotationContext
from loryth.common.annotations import AnnotationContext as AnnCtx
from loryth.common.di.bootstrap import BootstrapPlan, RegistrationStep
from loryth.common.di.exceptions import BootstrapError
from loryth.common.reflection import ReflectionContext
from loryth.common.reflection import reflection
from loryth.common.reflection.member_info import MemberInfo, TypeInfo


class BootstrapPlanBuilder:
    """Fluent API for building bootstrap plans via package scanning and manual registration.

    The builder accumulates discovered classes and registration steps through chained
    method calls, then produces a BootstrapPlan on demand. The builder is reusable -
    build() can be called multiple times to generate plans with the current state.

    Example:
        builder = BootstrapPlanBuilder.create()
        builder.scan_packages(services_config)
        builder.add_class(ManualService)
        plan = builder.build()

        # Builder is reusable
        builder.scan_packages(plugins_config)
        plan2 = builder.build()  # Includes previous scans + plugins
    """

    def __init__(
        self,
        reflection_context: ReflectionContext,
        annotation_context: AnnotationContext,
        rules: Sequence[RegistrationRule],
    ):
        """Initialize builder with required dependencies.

        :param reflection_context: Reflection context for package scanning
        :param annotation_context: Annotation context for annotation lookups
        :param rules: Sequence of registration rules to apply to discovered classes
        """
        self._reflection = reflection_context
        self._annotations = annotation_context
        self._rules = list(rules)
        self._discovered_classes: list[type] = []
        self._accumulated_steps: list[RegistrationStep] = []

    @staticmethod
    def create(
        reflection_context: ReflectionContext | None = None,
        annotation_context: AnnotationContext | None = None,
        rules: Sequence[RegistrationRule] | None = None,
    ) -> "BootstrapPlanBuilder":
        """Static factory with sensible defaults for all dependencies.

        :param reflection_context: Optional reflection context (defaults to singleton)
        :param annotation_context: Optional annotation context (defaults to singleton)
        :param rules: Optional rules (defaults to built-in rules)
        :return: Configured BootstrapPlanBuilder instance
        """
        default_rules = [
            ServiceAnnotationRule(),
            ComponentAnnotationRule(),
            ConfigurationAnnotationRule(),
        ]

        return BootstrapPlanBuilder(
            reflection_context=reflection_context or reflection,
            annotation_context=annotation_context or AnnCtx,
            rules=rules if rules is not None else default_rules,
        )

    def scan_packages(
        self,
        config: ScanningConfiguration
    ) -> "BootstrapPlanBuilder":
        """Scan configured packages and accumulate registration steps.

        This method is chainable - it returns self for fluent API usage.
        Discovered classes and generated steps are accumulated in the builder.

        :param config: Scanning configuration specifying packages and filters
        :return: Self for method chaining
        :raises BootstrapError: If package resolution or scanning fails
        """
        try:
            for package_name in config.packages:
                discovered = self._scan_package(package_name, config)
                self._discovered_classes.extend(discovered)

                # Apply all rules to discovered classes
                for cls in discovered:
                    self._apply_rules(cls)

        except Exception as e:
            raise BootstrapError(
                f"Failed to scan packages {list(config.packages)}: {e}"
            ) from e

        return self

    def add_class(self, cls: type) -> "BootstrapPlanBuilder":
        """Manually add a class and apply rules.

        This method is chainable - it returns self for fluent API usage.
        Useful for registering specific classes without scanning their package.

        :param cls: The class to register
        :return: Self for method chaining
        :raises BootstrapError: If rule application fails
        """
        self._discovered_classes.append(cls)
        self._apply_rules(cls)
        return self

    def build(self) -> BootstrapPlan:
        """Build bootstrap plan from accumulated steps.

        This method does NOT clear builder state - the builder remains reusable.
        Calling build() multiple times returns plans with the same accumulated steps.

        Step deduplication is delegated to the container (TD-020 idempotency).

        :return: BootstrapPlan containing all accumulated registration steps
        """
        return BootstrapPlan(registrations=tuple(self._accumulated_steps))

    def _scan_package(
        self,
        package_name: str,
        config: ScanningConfiguration
    ) -> list[type]:
        """Scan a single package using reflection scanner with filters.

        :param package_name: Package to scan
        :param config: Scanning configuration with filter criteria
        :return: List of discovered classes matching filter criteria
        """
        def predicate(member: MemberInfo) -> bool:
            return self._accept_member(member, config)

        discovered: list[type] = []

        # Use reflection scanner with predicate
        members = self._reflection.scan.package(
            package_name,
            recursive=config.recursive,
            public_only=True,  # Only public classes
        )

        # Apply predicate to filter members
        for member in members:
            if predicate(member) and isinstance(member, TypeInfo):
                discovered.append(member.python_type)

        return discovered

    def _accept_member(
        self,
        member: MemberInfo,
        config: ScanningConfiguration
    ) -> bool:
        """Filter predicate for reflection scanner.

        :param member: Member to evaluate
        :param config: Configuration with filter criteria
        :return: True if member should be included in scan results
        """
        if not isinstance(member, TypeInfo):
            return False

        python_type = member.python_type

        # Include annotation filter
        if config.include_annotations:
            if not any(
                self._annotations.has_annotation(python_type, annotation_type)
                for annotation_type in config.include_annotations
            ):
                return False

        # Exclude pattern filter
        qualname = member.qualname
        module_name = member.module.qualname

        for pattern in config.exclude_patterns:
            if fnmatch.fnmatch(qualname, pattern) or fnmatch.fnmatch(module_name, pattern):
                return False

        return True

    def _apply_rules(self, cls: type) -> None:
        """Apply all rules to a class and accumulate registration steps.

        Uses union semantics - all matching rules apply. If a rule raises an
        exception, it's wrapped in BootstrapError for fail-fast behavior.

        :param cls: Class to analyze
        :raises BootstrapError: If any rule fails
        """
        for rule in self._rules:
            try:
                steps = rule.apply(cls)
                self._accumulated_steps.extend(steps)
            except Exception as e:
                raise BootstrapError(
                    f"Rule {rule.__class__.__name__} failed on {cls.__name__}: {e}"
                ) from e

from loryth.common.di.bootstrap import (
    BootstrapPlanBuilder,
    BootstrapRuntime,
    ScanningConfiguration,
)
from loryth.common.di.container import Container
from loryth.common.di.annotations import ServiceAnnotation, ComponentAnnotation

# Create builder with defaults
builder = BootstrapPlanBuilder.create()

# Configure scanning
config = ScanningConfiguration(
    packages=["myapp.services", "myapp.repositories"],
    include_annotations=[ServiceAnnotation, ComponentAnnotation],
    exclude_patterns=[],
    recursive=True,
)

# Scan and build plan
plan = builder.scan_packages(config).build()

# Bootstrap container
runtime = BootstrapRuntime()
container = Container()
runtime.bootstrap(container, plan)

# Resolve services
user_service = container.resolve(UserService)

from loryth.common.di.bootstrap import BootstrapPlanBuilder, ScanningConfiguration
from loryth.common.di.annotations import ServiceAnnotation

# Create builder
builder = BootstrapPlanBuilder.create()

# Scan with custom filters
config = ScanningConfiguration(
    packages=["myapp"],
    include_annotations=[ServiceAnnotation],  # Only @service
    exclude_patterns=[
        "*_legacy.py",      # Skip legacy modules
        "*.test.*",         # Skip test packages
        "*_mock.py",        # Skip mock implementations
    ],
    recursive=True,
)

plan = builder.scan_packages(config).build()

runtime = BootstrapRuntime()
container = DiContainer()
runtime.bootstrap(container, plan)

from loryth.common.di.bootstrap import BootstrapPlanBuilder, ScanningConfiguration
from loryth.common.di.annotations import ServiceAnnotation, ComponentAnnotation

# Create builder
builder = BootstrapPlanBuilder.create()

# Scan services
services_config = ScanningConfiguration(
    packages=["myapp.services"],
    include_annotations=[ServiceAnnotation],
    exclude_patterns=[],
)
builder.scan_packages(services_config)

# Scan repositories
repositories_config = ScanningConfiguration(
    packages=["myapp.repositories"],
    include_annotations=[ComponentAnnotation],
    exclude_patterns=[],
)
builder.scan_packages(repositories_config)

# Add manual class
builder.add_class(LegacyService)

# Build combined plan
plan = builder.build()

# Bootstrap
runtime = BootstrapRuntime()
container = DiContainer()
runtime.bootstrap(container, plan)

# Reuse builder for additional scans
plugins_config = ScanningConfiguration(
    packages=["myapp.plugins"],
    include_annotations=[ServiceAnnotation],
    exclude_patterns=[],
)
builder.scan_packages(plugins_config)
plan2 = builder.build()  # Includes all previous scans + plugins

tests/unit/di/bootstrap/
├── test_registration_rules.py       # Rule protocol implementation and behavior
├── test_bootstrap_plan_builder.py   # Builder operations, fluent API, state management
└── test_scanning_configuration.py   # Configuration validation and defaults

tests/integration/di/bootstrap/
├── test_scanning_workflows.py       # Package scanning with reflection integration
├── test_rule_application_workflows.py # Union semantics, rule combination scenarios
└── test_builder_runtime_integration.py # End-to-end plan building and bootstrap execution

from loryth.common.di.annotations import AnnotationProcessor
from loryth.common.di.container import Container

# Old processor pattern
container = Container()
processor = AnnotationProcessor(
    builder=AnnotationBuilder(),
    registry=AnnotationRegistry(),
    bridge=InjectorBridge(container),
)
processor.process([UserService, EmailService])  # Mutates container
container.bootstrap()  # Old bootstrap pattern

from loryth.common.di.bootstrap import (
    BootstrapPlanBuilder,
    BootstrapRuntime,
    ScanningConfiguration,
)
from loryth.common.di.container import Container
from loryth.common.di.annotations import ServiceAnnotation

# New rule-based pattern
builder = BootstrapPlanBuilder.create()
builder.add_class(UserService)
builder.add_class(EmailService)
plan = builder.build()

runtime = BootstrapRuntime()
container = Container()
runtime.bootstrap(container, plan)  # New bootstrap pattern (TD-020)

# Replace manual class lists with scanning
config = ScanningConfiguration(
    packages=["myapp.services"],
    include_annotations=[ServiceAnnotation],
    exclude_patterns=[],
)

builder = BootstrapPlanBuilder.create()
plan = builder.scan_packages(config).build()

runtime = BootstrapRuntime()
container = DiContainer()
runtime.bootstrap(container, plan)