Merge pull request #51 from Ardenexal/feat/50-property-metadata-caching

Feat/50 property metadata caching

Author: Ardenexal

.github/workflows/pr.yml

@@ -33,7 +33,7 @@ jobs:
             -   name: Install dependencies
                 run: composer install --prefer-dist --no-progress --no-suggest
             -   name: Security audit
-                run: composer audit
+                run: composer audit --abandoned=report
     style:
         runs-on: ubuntu-latest
         env:
@@ -67,9 +67,6 @@ jobs:
             -   name: Validate composer files
                 run: composer validate --strict
 
-            -   name: Security audit
-                run: composer audit
-
     unit-tests:
         runs-on: ubuntu-latest
         env:
@@ -144,8 +141,6 @@ jobs:
             -   name: Run FHIRPath specification tests
                 run: composer run test-fhirpath-spec -- --log-junit=./results/fhir-path-tests.xml --coverage-clover ./results/fhir-path-coverage.xml
 
-            -   name: Security audit
-                run: composer audit
             -   name: Upload test results to Codecov
                 if: ${{ !cancelled() }}
                 uses: codecov/codecov-action@v5
@@ -313,3 +308,94 @@ jobs:
                           repo: context.repo.repo,
                           body: commentBody
                         });
+
+    benchmarks:
+        runs-on: ubuntu-latest
+        needs: [ unit-tests, integration-tests ]
+        permissions:
+            pull-requests: write
+            contents: read
+
+        steps:
+            -   uses: actions/checkout@v4
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: '8.3'
+                    extensions: ctype, iconv, zip, bcmath
+
+            -   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 dependencies
+                run: composer install --prefer-dist --no-progress --no-suggest
+
+            -   name: Run benchmarks
+                id: bench
+                run: |
+                    mkdir -p results
+                    php ./vendor/bin/phpbench run bench/ --report=aggregate --no-interaction > results/benchmarks.txt 2>&1 || true
+
+            -   name: Assert no regression against baseline
+                id: regression
+                if: hashFiles('.phpbench/*.xml') != ''
+                run: |
+                    php ./vendor/bin/phpbench run bench/ \
+                        --report=compare \
+                        --ref=baseline \
+                        --assert="mode(variant.time.avg) < mode(baseline.time.avg) * 1.50" \
+                        --no-interaction \
+                        > results/regression.txt 2>&1
+                    echo "exit_code=$?" >> $GITHUB_OUTPUT
+                continue-on-error: true
+
+            -   name: Comment PR with benchmark results
+                if: ${{ !cancelled() }}
+                uses: actions/github-script@v7
+                with:
+                    script: |
+                        const fs = require('fs');
+
+                        let benchOutput = '';
+                        try {
+                            benchOutput = fs.readFileSync('results/benchmarks.txt', 'utf8');
+                        } catch (e) {
+                            benchOutput = 'Could not read benchmark output.';
+                        }
+
+                        const baselineExists = '${{ hashFiles('.phpbench/*.xml') }}' !== '';
+                        let regressionSection = '';
+
+                        if (baselineExists) {
+                            let regressionOutput = '';
+                            try {
+                                regressionOutput = fs.readFileSync('results/regression.txt', 'utf8');
+                            } catch (e) {
+                                regressionOutput = 'Could not read regression output.';
+                            }
+                            const passed = '${{ steps.regression.outputs.exit_code }}' === '0';
+                            const icon = passed ? '✅' : '❌';
+                            const label = passed ? 'Regression check passed' : 'Regression detected (>50% slower than baseline)';
+                            regressionSection = `\n### ${icon} ${label}\n\n<details>\n<summary>Comparison vs baseline</summary>\n\n\`\`\`\n${regressionOutput}\n\`\`\`\n</details>`;
+                        } else {
+                            regressionSection = '\n> No baseline stored yet. Run `composer bench:baseline` and commit `.phpbench/` to enable regression checks.';
+                        }
+
+                        const commentBody = `## Benchmark Results\n\n<details>\n<summary>Serialization + FHIRPath benchmarks</summary>\n\n\`\`\`\n${benchOutput}\n\`\`\`\n</details>\n${regressionSection}\n\n*Run \`composer bench\` locally for full results.*`;
+
+                        github.rest.issues.createComment({
+                            issue_number: context.issue.number,
+                            owner: context.repo.owner,
+                            repo: context.repo.repo,
+                            body: commentBody
+                        });
+
+            -   name: Fail if regression detected
+                if: steps.regression.outputs.exit_code != '0' && hashFiles('.phpbench/*.xml') != ''
+                run: exit 1

.phpbench/.gitkeep

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3] - 2026-03-30
+
+### Added
+- implement FHIR metadata cache warmer and configuration support
+
+### Fixed
+- standardize formatting and indentation across multiple PHP files
+
+[Unreleased]: https://github.com/Ardenexal/php-fhir-tools/compare/0.3...HEAD
+[0.3]: https://github.com/Ardenexal/php-fhir-tools/compare/0.2...0.3

.phpbench/7ea/3/1e/13525ea0a5ac1d17a64652fd207cfde5a99fc020.xml

@@ -0,0 +1,143 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ardenexal\FHIRTools\Benchmarks\FHIRPath;
+
+use Ardenexal\FHIRTools\Component\FHIRPath\Service\FHIRPathService;
+use Ardenexal\FHIRTools\Component\Models\R4\DataType\HumanName;
+use Ardenexal\FHIRTools\Component\Models\R4\Resource\PatientResource;
+use PhpBench\Attributes as Bench;
+
+/**
+ * Benchmarks for FHIRPath expression evaluation.
+ *
+ * Each expression is tested in two modes:
+ *  - Cold cache: the parsed AST is not yet cached — measures lexer + parser + evaluator.
+ *  - Warm cache: the AST is pre-compiled and cached — measures evaluator only.
+ */
+class FHIRPathEvaluationBench
+{
+    private const EXPR_SIMPLE  = 'Patient.name.given';
+
+    private const EXPR_FILTER  = "Patient.name.where(use = 'official').given";
+
+    private const EXPR_DEEP    = 'Patient.contact.where(relationship.coding.code = \'N\').name.family';
+
+    private const EXPR_CHAIN   = 'Patient.name.given.where($this.length() > 3).first()';
+
+    private FHIRPathService $service;
+
+    private PatientResource $patient;
+
+    public function setUp(): void
+    {
+        $this->service = new FHIRPathService();
+
+        // Build a Patient with contacts so deep-navigation expressions have data to traverse.
+        $this->patient = new PatientResource(
+            id: 'bench-fhirpath-001',
+            name: [
+                new HumanName(family: 'Smith', given: ['John', 'Michael']),
+                new HumanName(family: 'Smith', given: ['Johnny']),
+            ],
+        );
+    }
+
+    /** Compile (prime) the simple expression into the service cache. */
+    public function primeSimple(): void
+    {
+        $this->setUp();
+        $this->service->compile(self::EXPR_SIMPLE);
+    }
+
+    /** Compile (prime) the filter expression into the service cache. */
+    public function primeFilter(): void
+    {
+        $this->setUp();
+        $this->service->compile(self::EXPR_FILTER);
+    }
+
+    /** Compile all expressions into the service cache. */
+    public function primeAll(): void
+    {
+        $this->setUp();
+        $this->service->compile(self::EXPR_SIMPLE);
+        $this->service->compile(self::EXPR_FILTER);
+        $this->service->compile(self::EXPR_DEEP);
+        $this->service->compile(self::EXPR_CHAIN);
+    }
+
+    /** Clear the expression cache before cold benchmarks. */
+    public function clearCache(): void
+    {
+        $this->setUp();
+        $this->service->clearCache();
+    }
+
+    // -------------------------------------------------------------------------
+    // Simple path: Patient.name.given
+    // -------------------------------------------------------------------------
+
+    /**
+     * Evaluate a simple property-navigation path with no cached AST.
+     */
+    #[Bench\BeforeMethods(['clearCache'])]
+    public function benchSimplePathColdCache(): void
+    {
+        $this->service->evaluate(self::EXPR_SIMPLE, $this->patient);
+    }
+
+    /**
+     * Evaluate a simple property-navigation path with a pre-compiled cached AST.
+     */
+    #[Bench\BeforeMethods(['primeSimple'])]
+    public function benchSimplePathWarmCache(): void
+    {
+        $this->service->evaluate(self::EXPR_SIMPLE, $this->patient);
+    }
+
+    // -------------------------------------------------------------------------
+    // Filter expression: Patient.name.where(use = 'official').given
+    // -------------------------------------------------------------------------
+
+    /**
+     * Evaluate a filter expression (where clause) with no cached AST.
+     */
+    #[Bench\BeforeMethods(['clearCache'])]
+    public function benchComplexFilterColdCache(): void
+    {
+        $this->service->evaluate(self::EXPR_FILTER, $this->patient);
+    }
+
+    /**
+     * Evaluate a filter expression (where clause) with a pre-compiled cached AST.
+     */
+    #[Bench\BeforeMethods(['primeFilter'])]
+    public function benchComplexFilterWarmCache(): void
+    {
+        $this->service->evaluate(self::EXPR_FILTER, $this->patient);
+    }
+
+    // -------------------------------------------------------------------------
+    // Deep navigation + function chain (always warm — focuses on evaluator cost)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Evaluate a multi-hop navigation with a nested where() filter (warm cache).
+     */
+    #[Bench\BeforeMethods(['primeAll'])]
+    public function benchDeepNavigation(): void
+    {
+        $this->service->evaluate(self::EXPR_DEEP, $this->patient);
+    }
+
+    /**
+     * Evaluate a chained function expression (where + length + first) (warm cache).
+     */
+    #[Bench\BeforeMethods(['primeAll'])]
+    public function benchFunctionChain(): void
+    {
+        $this->service->evaluate(self::EXPR_CHAIN, $this->patient);
+    }
+}

CHANGELOG.md

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ardenexal\FHIRTools\Benchmarks\FHIRPath;
+
+use Ardenexal\FHIRTools\Component\FHIRPath\Parser\FHIRPathLexer;
+use Ardenexal\FHIRTools\Component\FHIRPath\Parser\FHIRPathParser;
+use PhpBench\Attributes as Bench;
+
+/**
+ * Benchmarks for FHIRPath lexing and parsing (no evaluation).
+ *
+ * Isolates the parse phase so regressions in the lexer or parser are visible
+ * independently of evaluator performance.
+ */
+#[Bench\BeforeMethods(['setUp'])]
+class FHIRPathParsingBench
+{
+    private FHIRPathLexer $lexer;
+
+    private FHIRPathParser $parser;
+
+    public function setUp(): void
+    {
+        $this->lexer  = new FHIRPathLexer();
+        $this->parser = new FHIRPathParser();
+    }
+
+    /**
+     * Tokenize and parse a simple three-segment property-navigation path.
+     */
+    public function benchParseSimple(): void
+    {
+        $tokens = $this->lexer->tokenize('Patient.name.given');
+        $this->parser->parse($tokens);
+    }
+
+    /**
+     * Tokenize and parse a complex expression with function calls, boolean operators,
+     * and chained member access.
+     */
+    public function benchParseComplex(): void
+    {
+        $tokens = $this->lexer->tokenize(
+            "Patient.name.where(use = 'official' and family.exists()).given.first()",
+        );
+        $this->parser->parse($tokens);
+    }
+
+    /**
+     * Tokenize and parse a deeply nested expression mixing arithmetic, comparisons,
+     * and multiple function calls — representative of real-world CQL-style paths.
+     */
+    public function benchParseDeep(): void
+    {
+        $tokens = $this->lexer->tokenize(
+            'Patient.name.where(use = \'official\').given.where($this.length() > 3 and $this.startsWith(\'Jo\')).first()',
+        );
+        $this->parser->parse($tokens);
+    }
+}