📘 Technical Design 014 — Test Resource Organization & Cleanup¶

🧭 1. Summary¶

This technical design implements Phase 6 of the DI roadmap by reorganizing test resources from arbitrary naming patterns to feature-based organization. The design consolidates scattered m5_*_pkg resources, creates clear naming conventions, and ensures test suite independence.

At a glance:

• Reorganize test resources by feature instead of milestone-based naming
• Consolidate reflection test resources under tests/resources/reflection/
• Create independent test suites with no shared resource dependencies
• Establish clear naming conventions for test packages and modules
• Move code samples from tests to dedicated resource packages

📚 2. Context and Problem Statement¶

The current test organization has evolved organically with unclear naming and scattered resources:

Current Issues¶

1. Arbitrary Naming - Test resources use m5_*_pkg patterns based on development milestones
2. Scattered Resources - Reflection test packages distributed across different directories
3. Unclear Organization - No consistent structure for test resources by feature area
4. Shared Dependencies - Test suites may inadvertently share resources, causing coupling
5. Poor Discoverability - Difficult to find relevant test resources for specific features

Current State Analysis¶

tests/resources/
├── m5_determinism_pkg/          # Unclear purpose from name
├── m5_forward_refs_pkg/         # Milestone-based naming
├── m5_strict_vs_tolerant_pkg/   # Development-specific naming
├── reflection/                  # Good feature-based naming
│   ├── forward_refs__circular/
│   └── simple_types/
└── (other scattered resources)

2.1 Goals¶

1. Feature-Based Organization - Organize resources by system feature (reflection, DI, annotations)
2. Clear Naming Conventions - Descriptive names that explain resource purpose
3. Test Independence - Each test suite has isolated resources without shared dependencies
4. Improved Discoverability - Easy to find resources for specific testing scenarios
5. Maintainability - Resources are easy to maintain and extend

2.2 Non-Goals (Out of Scope)¶

• Rewriting existing test logic (only reorganizing resources)
• Changing test execution behavior or performance
• Modifying test framework or infrastructure
• Adding new test capabilities beyond organization

2.3 Assumptions and Constraints¶

• Test resources are primarily Python packages for reflection testing
• Existing test logic should continue to work with minimal changes
• Resource reorganization should be backward-compatible during transition
• New organization should support future DI testing needs

🧩 3. Design Overview¶

The reorganization transforms milestone-based naming into feature-based organization with clear hierarchies and independent resource sets.

graph TB
    subgraph "🗑️ Current Structure"
        A[m5_determinism_pkg]
        B[m5_forward_refs_pkg]
        C[m5_strict_vs_tolerant_pkg]
        D[scattered resources]
    end

    subgraph "✨ New Structure"
        E[reflection/]
        F[di/]
        G[annotations/]
        H[integration/]
    end

    subgraph "🔍 Reflection Resources"
        I[forward_refs/]
        J[type_hints/]
        K[scanning/]
        L[annotations/]
    end

    subgraph "🚀 DI Resources"
        M[injection/]
        N[lifecycle/]
        O[scanning/]
        P[configuration/]
    end

    A --> I
    B --> I
    C --> J
    D --> K

    E --> I
    E --> J
    E --> K
    E --> L

    F --> M
    F --> N
    F --> O
    F --> P

    classDef oldNode fill: none, stroke: #f44336, stroke-width: 2px, color: #ffffff
    classDef newNode fill: none, stroke: #4caf50, stroke-width: 2px, color: #ffffff
    classDef featureNode fill: none, stroke: #2196f3, stroke-width: 2px, color: #ffffff

    class A,B,C,D oldNode
    class E,F,G,H newNode
    class I,J,K,L,M,N,O,P featureNode

3.1 Target Structure Overview¶

📐 4. Implementation Details¶

4.1 New Resource Structure¶

tests/resources/
├── reflection/
│   ├── forward_refs/
│   │   ├── simple_forward_refs/          # Basic forward reference scenarios
│   │   ├── circular_dependencies/        # Circular reference handling
│   │   ├── cross_module_refs/           # Inter-module forward references
│   │   └── complex_generic_refs/        # Generic type forward references
│   ├── type_hints/
│   │   ├── basic_types/                 # Simple type hint scenarios
│   │   ├── generic_types/               # Generic and complex types
│   │   ├── union_types/                 # Union and optional types
│   │   └── property_types/              # Property type resolution
│   ├── scanning/
│   │   ├── simple_modules/              # Basic module scanning
│   │   ├── package_hierarchies/         # Complex package structures
│   │   ├── namespace_packages/          # Namespace package scenarios
│   │   └── mixed_content/               # Modules with mixed content types
│   └── annotations/
│       ├── basic_annotations/           # Simple annotation scenarios
│       ├── decorator_annotations/       # Decorator-based annotations
│       ├── metadata_annotations/        # Annotations with metadata
│       └── inheritance_annotations/     # Annotation inheritance scenarios
├── di/
│   ├── injection/
│   │   ├── constructor_injection/       # Constructor injection scenarios
│   │   ├── property_injection/          # Property injection scenarios
│   │   ├── method_injection/            # Method injection scenarios
│   │   └── circular_injection/          # Circular dependency injection
│   ├── lifecycle/
│   │   ├── singleton_services/          # Singleton lifecycle scenarios
│   │   ├── transient_services/          # Transient lifecycle scenarios
│   │   ├── factory_services/            # Factory-based services
│   │   └── complex_lifecycles/          # Mixed lifecycle scenarios
│   ├── scanning/
│   │   ├── annotated_services/          # Service scanning scenarios
│   │   ├── package_scanning/            # Package-based scanning
│   │   ├── filtered_scanning/           # Filtered scanning scenarios
│   │   └── recursive_scanning/          # Recursive package scanning
│   └── configuration/
│       ├── config_binding/              # Configuration binding scenarios
│       ├── config_files/                # Sample configuration files
│       ├── config_providers/            # Custom configuration providers
│       └── environment_configs/         # Environment-specific configurations
├── annotations/
│   ├── discovery/
│   │   ├── class_annotations/           # Class-level annotation discovery
│   │   ├── method_annotations/          # Method-level annotation discovery
│   │   └── property_annotations/        # Property annotation discovery
│   ├── metadata/
│   │   ├── simple_metadata/             # Basic annotation metadata
│   │   ├── complex_metadata/            # Complex metadata scenarios
│   │   └── nested_metadata/             # Nested annotation metadata
│   └── processing/
│       ├── annotation_processors/       # Sample annotation processors
│       ├── processor_chains/            # Annotation processor chains
│       └── processor_errors/            # Error handling scenarios
└── integration/
    ├── di_reflection/
    │   ├── dependency_analysis/         # DI using reflection for analysis
    │   ├── type_discovery/              # Type discovery integration
    │   └── injection_reflection/        # Injection using reflection
    └── annotation_processing/
        ├── di_annotations/              # DI annotation processing
        ├── reflection_annotations/      # Reflection annotation processing
        └── cross_system_annotations/    # Cross-system annotation scenarios

4.2 Migration Mapping¶

class ResourceMigrationPlan:
    """Maps current resources to new organization."""

    MIGRATION_MAP = {
        # Reflection resource migrations
        "m5_determinism_pkg": "reflection/forward_refs/deterministic_resolution",
        "m5_forward_refs_pkg": "reflection/forward_refs/cross_module_refs",
        "m5_strict_vs_tolerant_pkg": "reflection/type_hints/resolution_modes",

        # Existing good resources (keep structure)
        "reflection/forward_refs__circular": "reflection/forward_refs/circular_dependencies",
        "reflection/simple_types": "reflection/type_hints/basic_types",

        # Future DI resources (prepare structure)
        # These will be created as DI implementation progresses
    }

    DEPRECATED_RESOURCES = [
        "m5_determinism_pkg",
        "m5_forward_refs_pkg",
        "m5_strict_vs_tolerant_pkg",
        # Add other milestone-based resources as identified
    ]

    def get_new_path(self, old_path: str) -> str:
        """Get new path for a resource being migrated."""
        return self.MIGRATION_MAP.get(old_path, old_path)

    def is_deprecated(self, path: str) -> bool:
        """Check if a resource path is deprecated."""
        return path in self.DEPRECATED_RESOURCES

4.3 Resource Naming Conventions¶

class ResourceNamingConvention:
    """Defines naming conventions for test resources."""

    @staticmethod
    def validate_package_name(name: str) -> bool:
        """Validate test resource package name."""
        # Must be descriptive, not milestone-based
        if name.startswith(('m5_', 'milestone_', 'phase_')):
            return False

        # Must use snake_case
        if not name.islower() or ' ' in name:
            return False

        # Must be descriptive (at least 2 words)
        if '_' not in name:
            return False

        return True

    @staticmethod
    def suggest_name(purpose: str, feature_area: str) -> str:
        """Suggest appropriate name for test resource."""
        # Convert purpose to snake_case and combine with feature area
        clean_purpose = purpose.lower().replace(' ', '_').replace('-', '_')
        return f"{feature_area}_{clean_purpose}"

    NAMING_GUIDELINES = {
        "reflection": [
            "forward_refs_*",
            "type_hints_*",
            "scanning_*",
            "annotation_*"
        ],
        "di": [
            "injection_*",
            "lifecycle_*",
            "scanning_*",
            "configuration_*"
        ],
        "annotations": [
            "discovery_*",
            "metadata_*",
            "processing_*"
        ]
    }

4.4 Test Independence Validation¶

class TestResourceValidator:
    """Validates test resource independence and organization."""

    def validate_independence(self, test_suite_path: str) -> ValidationResult:
        """Validate that test suite has independent resources."""
        issues = []

        # Check for shared resource imports
        shared_imports = self._find_shared_imports(test_suite_path)
        if shared_imports:
            issues.append(f"Shared resource imports detected: {shared_imports}")

        # Check for cross-suite dependencies
        cross_dependencies = self._find_cross_dependencies(test_suite_path)
        if cross_dependencies:
            issues.append(f"Cross-suite dependencies: {cross_dependencies}")

        # Check naming conventions
        naming_issues = self._validate_naming_conventions(test_suite_path)
        issues.extend(naming_issues)

        return ValidationResult(
            is_valid=len(issues) == 0,
            issues=issues
        )

    def _find_shared_imports(self, path: str) -> list[str]:
        """Find imports that reference shared resources."""
        shared_imports = []

        for test_file in self._get_test_files(path):
            imports = self._extract_imports(test_file)
            for imp in imports:
                if self._is_shared_resource(imp):
                    shared_imports.append(f"{test_file}: {imp}")

        return shared_imports

    def _is_shared_resource(self, import_path: str) -> bool:
        """Check if import references a shared resource."""
        # Resources should be feature-specific, not shared across features
        resource_indicators = [
            "tests.resources.reflection",
            "tests.resources.di",
            "tests.resources.annotations"
        ]

        for indicator in resource_indicators:
            if indicator in import_path:
                # Check if it's being imported from a different feature area
                # This would indicate cross-feature resource sharing
                return self._is_cross_feature_import(import_path)

        return False

    def _validate_naming_conventions(self, path: str) -> list[str]:
        """Validate resource naming follows conventions."""
        issues = []

        for resource_dir in self._get_resource_directories(path):
            if not ResourceNamingConvention.validate_package_name(resource_dir):
                issues.append(f"Invalid resource name: {resource_dir}")

        return issues

⚙️ 5. Semantics¶

5.1 Migration Strategy¶

1. Create New Structure - Establish new directory hierarchy
2. Copy Resources - Copy existing resources to new locations
3. Update Imports - Update test files to use new resource paths
4. Deprecate Old Resources - Mark old resources as deprecated
5. Remove Old Resources - Clean up deprecated resources after migration

5.2 Naming Rules¶

• Feature-Based: Resources organized by system feature (reflection, di, annotations)
• Descriptive Names: Resource names describe their purpose, not implementation details
• Snake Case: All resource package names use snake_case convention
• No Milestones: Avoid milestone-based or development-phase naming

5.3 Independence Requirements¶

• No Shared Resources: Each test suite has dedicated resources
• Feature Isolation: Resources for one feature don't depend on another feature's resources
• Clear Boundaries: Integration tests have separate resources from unit tests

🧪 6. Examples¶

6.1 Resource Migration Example¶

# Before: Milestone-based naming
from tests.resources.m5_forward_refs_pkg.main import ForwardRefUser
from tests.resources.m5_determinism_pkg.a import A

# After: Feature-based naming
from tests.resources.reflection.forward_refs.cross_module_refs.main import ForwardRefUser
from tests.resources.reflection.forward_refs.deterministic_resolution.module_a import ClassA

6.2 New DI Resource Structure¶

# DI injection test resources
from tests.resources.di.injection.constructor_injection.services import (
    ServiceWithDependencies,
    SimpleService,
    CircularServiceA,
    CircularServiceB
)

# DI lifecycle test resources
from tests.resources.di.lifecycle.singleton_services.user_service import UserService
from tests.resources.di.lifecycle.transient_services.request_handler import RequestHandler

6.3 Integration Test Resources¶

# Integration test using dedicated resources
from tests.resources.integration.di_reflection.dependency_analysis import (
    AnalyzableService,
    ComplexDependencyService
)

# No cross-contamination with unit test resources

6.4 Resource Validation¶

# Validate resource organization
validator = TestResourceValidator()

# Check reflection test suite
result = validator.validate_independence("tests/unit/reflection/")
assert result.is_valid, f"Reflection tests have dependency issues: {result.issues}"

# Check DI test suite
result = validator.validate_independence("tests/unit/di/")
assert result.is_valid, f"DI tests have dependency issues: {result.issues}"

🧪 7. Test Matrix¶

tests/unit/test_resource_organization/
├── test_resource_migration.py     # migration mapping, path resolution, import updates
├── test_naming_conventions.py     # naming validation, convention enforcement
└── test_independence_validation.py # dependency detection, cross-suite validation

tests/integration/test_resource_cleanup/
├── test_migration_end_to_end.py   # complete migration workflow validation
├── test_backward_compatibility.py # old vs new resource path compatibility
└── test_validation_tooling.py     # resource validator integration scenarios

tests/regression/test_resource_organization/
├── test_import_paths.py          # import path resolution after migration
├── test_resource_discovery.py     # resource discovery in new structure
└── test_cross_feature_isolation.py # feature boundary enforcement

7.1 Unit Coverage¶

• Migration Mapping: ResourceMigrationPlan correctly maps old paths to new feature-based paths
• Naming Validation: ResourceNamingConvention validates package names against established rules
• Independence Detection: TestResourceValidator identifies shared imports and cross-suite dependencies
• Path Resolution: Migration utilities correctly resolve new resource paths from old milestone-based names
• Convention Enforcement: Naming guidelines are consistently applied across all resource types

7.2 Integration Coverage¶

• End-to-End Migration: Complete migration workflow from old structure to new organization
• Backward Compatibility: Old import paths continue to work during transition period
• Validation Integration: Resource validation tooling integrates with test execution pipeline
• Cross-Feature Isolation: Resources remain isolated between reflection, DI, and annotation features
• Import Resolution: Updated import statements correctly resolve to new resource locations

7.3 Regression Coverage¶

• Import Path Stability: Import paths remain stable after migration completion
• Resource Discovery: Test discovery tools work correctly with new resource organization
• Feature Boundary Enforcement: Cross-feature resource sharing is prevented by validation
• Migration Rollback: Migration process can be safely rolled back if needed
• Performance Impact: Resource loading performance is maintained or improved

Testing notes:

• Unit tests use mock resources and synthetic test scenarios for isolation
• Integration tests use real migration workflows with sample resource packages
• Regression tests ensure long-term stability of resource organization
• No tests for deprecated milestone-based naming patterns

✅ 8. Acceptance Criteria¶

• All milestone-based resource names (m5_*_pkg) are replaced with feature-based names
• Test resources are organized by feature area (reflection, di, annotations, integration)
• Each test suite has independent resources with no shared dependencies
• Resource naming follows established conventions (snake_case, descriptive)
• Existing test functionality continues to work after resource migration
• New resource structure supports future DI testing needs
• Resource validation tools ensure ongoing compliance with organization rules
• Documentation clearly explains resource organization and naming conventions
• Migration is backward-compatible during transition period
• All resource dependencies are explicit and well-documented

❓ 9. Open Questions¶

8.1 Migration Strategy Questions¶

1. Migration Timeline: How should we sequence the resource migration:
2. Should we migrate all resources at once or incrementally by feature?
3. Should we maintain backward compatibility during migration?

4. Should we provide automated migration scripts for test updates?

5. Backward Compatibility: During migration period:

6. Should old resource paths continue to work temporarily?
7. Should we provide import aliases for smooth transition?

8. Should we emit deprecation warnings for old resource usage?

9. Breaking Changes: How should we handle breaking changes:

10. Should resource migration be considered a breaking change?
11. Should we coordinate migration with other development activities?
12. Should we version the test resource organization?

8.2 Resource Organization Questions¶

1. Granularity: How fine-grained should resource organization be:
2. Should each test scenario have its own resource package?
3. Should related scenarios share resource packages?

4. Should we optimize for discoverability or simplicity?

5. Shared Resources: How should we handle truly shared resources:

6. Should common utilities be in a separate shared area?
7. Should shared resources be duplicated across feature areas?

8. Should we have explicit shared resource packages?

9. Integration Resources: How should integration test resources be organized:

10. Should integration resources duplicate unit test resources?
11. Should integration tests reference unit test resources?
12. Should integration resources be completely independent?

8.3 Naming and Convention Questions¶

1. Naming Flexibility: How strict should naming conventions be:
2. Should we enforce naming through tooling/linting?
3. Should conventions be guidelines or strict rules?

4. Should we allow exceptions for special cases?

5. Convention Evolution: How should conventions evolve over time:

6. Should conventions be versioned and documented?
7. Should we provide migration tools for convention changes?
8. Should convention changes require formal approval?

8.4 Validation and Maintenance Questions¶

1. Resource Validation: How should we ensure ongoing compliance:
2. Should resource validation be part of CI/CD pipeline?
3. Should we provide pre-commit hooks for resource validation?

4. Should validation be automated or manual?

5. Maintenance Burden: How should we manage ongoing maintenance:

   • Should resource organization be automatically enforced?
   • Should we provide tooling for resource management?
   • Should resource maintenance be assigned to specific team members?

8.5 Future Extensibility Questions¶

1. New Feature Support: How should resource organization support new features:

   • Should resource structure be designed for unknown future features?
   • Should we provide templates for new feature resource organization?
   • Should resource organization guidelines include extensibility principles?

2. Tooling Integration: How should resources integrate with development tools:

   • Should resource organization support IDE navigation?
   • Should resources be discoverable through development tooling?
   • Should we provide custom tooling for resource management?

3. Performance Considerations: Should resource organization consider performance:

   • Should resource loading performance influence organization?
   • Should we consider resource caching for test performance?
   • Should resource organization optimize for test execution speed?

🚀 10. Rollout and Migration¶

9.1 Implementation Phases¶

Phase 6a: Analysis and planning - Audit current test resources and identify migration candidates - Create detailed migration mapping from old to new structure - Design resource validation tooling

Phase 6b: New structure creation - Create new directory structure for feature-based organization - Implement resource naming conventions and validation - Create migration scripts and tooling

Phase 6c: Resource migration - Migrate reflection resources from milestone-based naming - Update test imports to use new resource paths - Add deprecation warnings for old resource paths

Phase 6d: Cleanup and validation - Remove deprecated resource paths - Validate test suite independence - Document new resource organization

9.2 Migration Plan¶

Week 1: Analysis and Design
- Inventory current resources
- Design new structure
- Create migration scripts

Week 2-3: Reflection Resource Migration
- Migrate m5_*_pkg resources
- Update reflection test imports
- Validate reflection test independence

Week 4: Validation and Cleanup
- Implement resource validation
- Remove deprecated resources
- Update documentation

⚠️ 11. Risks and Mitigations¶

10.1 Test Breakage Risk¶

Risk: Resource migration breaks existing tests Mitigation: Comprehensive testing, backward compatibility period, automated migration

10.2 Developer Confusion Risk¶

Risk: New organization confuses developers familiar with old structure Mitigation: Clear documentation, migration guides, training sessions

10.3 Incomplete Migration Risk¶

Risk: Partial migration leaves inconsistent resource organization Mitigation: Complete migration in single phase, validation tooling, clear timeline

📈 12. Progress¶

Legend: [x] = complete, [ ] = pending

• Audit current test resources and create migration inventory
• Design new feature-based resource organization structure
• Create resource naming conventions and validation rules
• Implement migration scripts and tooling
• Migrate reflection resources from milestone-based naming
• Update test imports to use new resource paths
• Create resource validation tooling and CI integration
• Document new resource organization and naming conventions
• Validate test suite independence after migration
• Remove deprecated resource paths and cleanup old structure

📝 13. Changelog¶

• 2025-10-02: Initial draft technical design created

📖 14. Glossary¶

• Resource: Test data packages and modules used by test suites
• Feature-Based Organization: Organizing resources by system feature rather than development timeline
• Test Independence: Test suites having isolated resources without shared dependencies
• Milestone-Based Naming: Resource naming based on development phases (e.g., m5_*_pkg)
• Resource Migration: Process of moving resources from old to new organizational structure