Merge pull request #21 from Ardenexal/copilot/implement-fhirpath-type-system

Implement FHIRPath Type System (Phase 7), Service Layer (Phase 8), Optimization (Phase 9), Documentation (Phase 10), Integration (Phase 11), and Final Review (Phase 12)

Author: Ardenexal

.github/workflows/copilot-setup-steps.yml

@@ -8,7 +8,13 @@ on:
   workflow_dispatch:
   push:
     branches:
-      - 'copilot/**'
+        - 'copilot/**'
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
 jobs:
   copilot-setup-steps:
     name: Setup PHP Environment for Copilot Agent
@@ -23,15 +29,15 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      
+
       - name: Setup PHP 8.3
         uses: shivammathur/setup-php@v2
         with:
           php-version: '8.3'
           extensions: ctype, iconv, zip, curl, intl
           ini-values: memory_limit=-1, max_execution_time=0
           coverage: none
-      
+
       - name: Verify PHP installation
         run: |
           echo "=== PHP Version ==="
@@ -42,23 +48,23 @@ jobs:
           echo ""
           echo "=== PHP Configuration ==="
           php -i | grep -E "(memory_limit|max_execution_time)"
-      
+
       - name: Validate Composer
         run: composer --version
-      
+
       - name: Cache Composer packages
         uses: actions/cache@v4
         with:
           path: vendor
           key: ${{ runner.os }}-php-8.3-${{ hashFiles('**/composer.lock') }}
           restore-keys: |
             ${{ runner.os }}-php-8.3-
-      
+
       - name: Install Composer dependencies
         run: |
           composer install --prefer-dist --no-interaction --optimize-autoloader
           echo "✅ Composer dependencies installed successfully"
-      
+
       - name: Verify required tools are installed
         run: |
           echo "=== Checking for required tools ==="
@@ -67,14 +73,14 @@ jobs:
           test -f vendor/bin/phpstan.phar && echo "✅ PHPStan found" || exit 1
           test -f vendor/bin/pint && echo "✅ Pint found" || exit 1
           echo "All required tools are available"
-      
+
       - name: Create required directories
         run: |
           mkdir -p output var/cache var/log coverage
           chmod -R 755 bin/console
           chmod -R 777 var/ coverage/
           echo "✅ Required directories created"
-      
+
       - name: Verify Symfony Console
         run: |
           echo "=== Symfony Console Version ==="
@@ -85,13 +91,13 @@ jobs:
           echo ""
           echo "=== Verifying FHIR Commands ==="
           php bin/console list | grep -q "fhir:generate" && echo "✅ FHIR generation command available" || exit 1
-      
+
       - name: Run unit tests
         run: |
           echo "=== Running Unit Tests ==="
           composer run test-unit -- --no-coverage
           echo "✅ Unit tests passed"
-      
+
       - name: Display project information
         if: always()
         run: |

.kiro/steering/product.md

@@ -0,0 +1,35 @@
+# Product Overview
+
+PHP FHIRTools is a comprehensive toolkit for working with FHIR (Fast Healthcare Interoperability Resources) in PHP applications. It provides modular components for generating PHP model classes from FHIR StructureDefinitions and serializing/deserializing FHIR resources to/from JSON and XML formats.
+
+## Core Functionality
+
+- **FHIR Code Generation**: Automatically generates PHP model classes from FHIR StructureDefinitions for R4, R4B, and R5 versions
+- **FHIR Serialization**: Comprehensive serialization system with JSON/XML support, validation modes, and extension handling
+- **FHIRPath Support**: Implementation of FHIRPath expression language for querying FHIR resources
+- **Symfony Integration**: Full Symfony Bundle integration with dependency injection and console commands
+
+## Multi-Component Architecture
+
+The project is organized as a monorepo with separate, independently usable components:
+
+- **FHIRBundle**: Symfony Bundle for seamless framework integration
+- **CodeGeneration Component**: Standalone FHIR class generator
+- **Serialization Component**: Standalone FHIR JSON/XML serialization
+- **FHIRPath Component**: FHIRPath expression evaluation engine
+- **Models Component**: Generated FHIR model classes for different versions
+
+## Target Users
+
+- Healthcare software developers working with FHIR
+- PHP developers building healthcare interoperability solutions
+- Organizations implementing FHIR-based APIs and systems
+- Developers needing type-safe FHIR resource handling in PHP
+
+## Key Benefits
+
+- Type-safe PHP classes for all FHIR resources
+- Standards-compliant serialization following FHIR specifications
+- Modular design allowing standalone or integrated usage
+- Support for multiple FHIR versions (R4, R4B, R5)
+- Comprehensive validation and error handling

.kiro/steering/structure.md

@@ -0,0 +1,215 @@
+# Project Structure
+
+## Multi-Component Monorepo Architecture
+
+PHP FHIRTools is organized as a monorepo containing multiple independent components that can be used standalone or together through the Symfony Bundle.
+
+## Root Directory Structure
+
+```
+php-fhir-tools/
+├── src/                           # Source code
+│   ├── Bundle/FHIRBundle/         # Symfony Bundle integration
+│   ├── Component/                 # Standalone components
+│   │   ├── CodeGeneration/        # FHIR class generation
+│   │   ├── Serialization/         # FHIR JSON/XML serialization
+│   │   ├── FHIRPath/             # FHIRPath expression engine
+│   │   └── Models/               # Generated FHIR model classes
+│   ├── Exception/                # Root-level exceptions
+│   └── (legacy files)            # Backward compatibility
+├── tests/                        # Test suites
+├── docs/                         # Documentation
+├── config/                       # Symfony configuration
+├── bin/                          # Console entry points
+├── public/                       # Web entry point
+├── var/                          # Runtime files (cache, logs)
+├── vendor/                       # Composer dependencies
+└── composer.json                 # Root package definition
+```
+
+## Component Organization
+
+### FHIRBundle (`src/Bundle/FHIRBundle/`)
+Symfony Bundle for framework integration:
+```
+FHIRBundle/
+├── FHIRBundle.php                # Bundle class
+├── DependencyInjection/          # Service configuration
+│   ├── FHIRExtension.php         # Bundle extension
+│   ├── Configuration.php         # Configuration tree
+│   └── Compiler/                 # Compiler passes
+├── Command/                      # Console commands
+├── Resources/config/             # Service definitions
+├── Compatibility/                # Version compatibility
+├── composer.json                 # Bundle package definition
+└── README.md                     # Bundle documentation
+```
+
+### CodeGeneration Component (`src/Component/CodeGeneration/`)
+Standalone FHIR class generator:
+```
+CodeGeneration/
+├── src/                          # Component source
+│   ├── Generator/                # Code generators
+│   ├── Package/                  # FHIR package handling
+│   ├── Context/                  # Generation context
+│   ├── Configuration/            # Generator configuration
+│   ├── Service/                  # Core services
+│   ├── Command/                  # Console commands
+│   ├── Attributes/               # PHP attributes
+│   └── Exception/                # Component exceptions
+├── tests/                        # Component tests
+├── output/                       # Generated code output
+├── composer.json                 # Component package definition
+└── README.md                     # Component documentation
+```
+
+### Serialization Component (`src/Component/Serialization/`)
+Standalone FHIR serialization:
+```
+Serialization/
+├── src/                          # Component source
+│   ├── Normalizer/               # Symfony normalizers
+│   ├── Validator/                # FHIR validators
+│   ├── Context/                  # Serialization context
+│   ├── Metadata/                 # Type metadata
+│   ├── Exception/                # Component exceptions
+│   ├── FHIRSerializationService.php
+│   ├── FHIRTypeResolver.php
+│   └── FHIRTypeResolverInterface.php
+├── tests/                        # Component tests
+├── composer.json                 # Component package definition
+└── README.md                     # Component documentation
+```
+
+### FHIRPath Component (`src/Component/FHIRPath/`)
+FHIRPath expression evaluation:
+```
+FHIRPath/
+├── src/                          # Component source
+│   ├── Parser/                   # Expression parsing
+│   ├── Evaluator/                # Expression evaluation
+│   ├── Function/                 # FHIRPath functions
+│   ├── Expression/               # Expression types
+│   ├── Type/                     # FHIRPath type system
+│   ├── Service/                  # Core services
+│   ├── Cache/                    # Expression caching
+│   └── Exception/                # Component exceptions
+├── tests/                        # Component tests
+├── composer.json                 # Component package definition
+└── README.md                     # Component documentation
+```
+
+## Test Organization
+
+```
+tests/
+├── Unit/                         # Unit tests
+│   ├── Bundle/FHIRBundle/        # Bundle unit tests
+│   ├── Component/                # Component unit tests
+│   │   ├── CodeGeneration/       # CodeGeneration tests
+│   │   ├── Serialization/        # Serialization tests
+│   │   └── Models/               # Models tests
+│   └── Exception/                # Exception tests
+├── Integration/                  # Integration tests
+│   ├── Package/                  # Package integration
+│   ├── FHIRModelGeneratorIntegrationTest.php
+│   ├── FHIRSerializationIntegrationTest.php
+│   └── CommandIntegrationTest.php
+├── FHIR/                         # FHIR-specific tests
+├── Fixtures/                     # Test data
+│   ├── FHIR/                     # FHIR test resources
+│   ├── OfficialFHIR/             # Official FHIR examples
+│   └── StructureDefinitions/     # Test structure definitions
+├── Utilities/                    # Test utilities
+└── bootstrap.php                 # Test bootstrap
+```
+
+## Configuration Structure
+
+```
+config/
+├── bundles.php                   # Bundle registration
+├── services.yaml                 # Service configuration
+├── packages/                     # Package configurations
+├── routes/                       # Routing configuration
+├── recipes/fhir-bundle/          # Symfony Flex recipe
+└── services/                     # FHIR-specific services
+    ├── fhir_bundle_commands.yaml
+    ├── fhir_code_generation.yaml
+    ├── fhir_path.yaml
+    └── fhir_serialization.yaml
+```
+
+## Documentation Structure
+
+```
+docs/
+├── architecture.md               # Multi-project architecture
+├── migration-guide.md            # Migration instructions
+├── FHIR-Serialization-Guide.md   # Serialization guide
+├── component-guides/             # Component-specific guides
+│   ├── fhir-bundle.md            # Bundle guide
+│   ├── code-generation.md        # CodeGeneration guide
+│   ├── serialization.md          # Serialization guide
+│   └── fhir-path.md              # FHIRPath guide
+└── FHIRPATH_*.md                 # FHIRPath documentation
+```
+
+## Namespace Conventions
+
+### Component Namespaces
+- **Root**: `Ardenexal\FHIRTools\`
+- **Bundle**: `Ardenexal\FHIRTools\Bundle\FHIRBundle\`
+- **CodeGeneration**: `Ardenexal\FHIRTools\Component\CodeGeneration\`
+- **Serialization**: `Ardenexal\FHIRTools\Component\Serialization\`
+- **FHIRPath**: `Ardenexal\FHIRTools\Component\FHIRPath\`
+- **Models**: `Ardenexal\FHIRTools\Component\Models\`
+
+### Generated Code Namespaces
+Generated FHIR classes use configurable namespaces:
+- **Default Pattern**: `{BaseNamespace}\{Version}\{ResourceType}`
+- **Example**: `App\FHIR\R4\Patient`
+
+## File Naming Conventions
+
+### PHP Classes
+- **PascalCase**: `FHIRModelGenerator.php`
+- **Suffix Patterns**: 
+  - Commands: `*Command.php`
+  - Services: `*Service.php`
+  - Exceptions: `*Exception.php`
+  - Interfaces: `*Interface.php`
+
+### Test Files
+- **Pattern**: `{ClassUnderTest}Test.php`
+- **Integration**: `*IntegrationTest.php`
+- **Property Tests**: `*PropertyTest.php`
+
+### Configuration Files
+- **YAML**: `.yaml` extension preferred
+- **Environment**: `.env` files for configuration
+- **Composer**: `composer.json` for package definitions
+
+## Output Organization
+
+Generated FHIR models are organized by version and type:
+```
+output/
+└── Ardenexal/FhirTools/
+    ├── R4/                       # FHIR R4 models
+    ├── R4B/                      # FHIR R4B models
+    └── R5/                       # FHIR R5 models
+```
+
+## Dependency Boundaries
+
+### Component Independence
+- Each component can be used standalone
+- Clear interface definitions between components
+- Minimal cross-component dependencies
+
+### Bundle Integration
+- FHIRBundle depends on all components
+- Components do not depend on the bundle
+- Symfony-specific code isolated in bundle