(Changed) Performance optimisations, bug fixes, and Docker-based development setup

.codacy.yaml

@@ -0,0 +1,36 @@
+---
+# Codacy configuration to align with PER 2.0 coding standard
+engines:
+  # Try to use PHP_CodeSniffer with our custom config
+  phpcodesniffer:
+    enabled: true
+    config: phpcs.xml
+  # Also try php-cs-fixer if supported
+  php-cs-fixer:
+    enabled: true
+    config: .php-cs-fixer.php
+  # Disable other style checkers
+  phpmd:
+    enabled: false
+  # Keep duplication detection
+  duplication:
+    enabled: true
+    config:
+      languages:
+        - php
+
+# Exclude non-source files from analysis
+exclude_paths:
+  - 'vendor/**'
+  - '.github/**'
+  - 'docker/**'
+  - 'node_modules/**'
+  - 'tests/Benchmark/**'
+  - '*.md'
+  - '*.sh'
+  - '*.yml'
+  - '*.yaml'
+  - 'Dockerfile'
+  - '.php-cs-fixer.cache'
+  - 'composer.lock'
+  - 'package-lock.json'

.codacyignore

@@ -0,0 +1,35 @@
+# Codacy ignore file
+# Exclude test benchmarks as they have different style requirements
+tests/Benchmark/
+
+# Exclude vendor and dependencies
+vendor/
+node_modules/
+
+# Exclude build and CI files
+.github/
+docker/
+Dockerfile
+docker-compose.yml
+
+# Exclude documentation
+*.md
+README.md
+CONTRIBUTING.md
+CLAUDE.md
+IMPROVEMENTS.md
+
+# Exclude configuration files
+*.yml
+*.yaml
+.gitignore
+.dockerignore
+composer.lock
+package-lock.json
+
+# Exclude shell scripts
+*.sh
+
+# Exclude cache files
+.php-cs-fixer.cache
+.psalm-cache

.dockerignore

@@ -0,0 +1,17 @@
+.git
+.github
+.idea
+vendor
+.phpunit.cache
+.phpunit.result.cache
+.php-cs-fixer.cache
+reports
+.qodo
+*.log
+.DS_Store
+docker-compose.yml
+Dockerfile
+.dockerignore
+.gitignore
+README.md
+CLAUDE.md

.githooks/commit-msg

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+
+# Conventional Commits validation hook using commitlint
+# This hook validates that commit messages follow the Conventional Commits specification
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Check if it's a merge commit
+merge_regex='^Merge '
+commit_message=$(cat "$1")
+
+if echo "$commit_message" | grep -qE "$merge_regex"; then
+    exit 0
+fi
+
+# Determine which commitlint runner to use
+if command -v npx &> /dev/null && [ -d "node_modules" ]; then
+    # Use local npx
+    echo -e "${GREEN}Running commitlint (local)...${NC}"
+
+    if ! npx --no -- commitlint --edit "$1"; then
+        echo ""
+        echo -e "${RED}ERROR: Commit message does not pass commitlint validation!${NC}"
+        echo ""
+        echo "Please ensure your commit message follows the Conventional Commits format."
+        echo "See commitlint.config.js for the specific rules."
+        exit 1
+    fi
+elif [ -f "./commitlint-docker.sh" ] && command -v docker &> /dev/null && docker info &> /dev/null; then
+    # Use Docker wrapper
+    echo -e "${GREEN}Running commitlint (Docker)...${NC}"
+
+    if ! ./commitlint-docker.sh "$1"; then
+        echo ""
+        echo -e "${RED}ERROR: Commit message does not pass commitlint validation!${NC}"
+        echo ""
+        echo "Please ensure your commit message follows the Conventional Commits format."
+        echo "See commitlint.config.js for the specific rules."
+        exit 1
+    fi
+else
+    # Fallback to basic regex validation
+    echo -e "${YELLOW}WARNING: commitlint not available. Using basic validation.${NC}"
+
+    commit_regex='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test|security)(\([a-z0-9\-]+\))?(!)?: .{1,100}$'
+    first_line=$(echo "$commit_message" | head -n1)
+
+    if ! echo "$first_line" | grep -qE "$commit_regex"; then
+        echo -e "${RED}ERROR: Commit message does not follow Conventional Commits format!${NC}"
+        echo ""
+        echo "Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, security"
+        echo "Format: <type>(<scope>): <subject>"
+        echo ""
+        echo "Your message: $first_line"
+        exit 1
+    fi
+fi
+
+# Additional checks for signed-off-by (required by this project)
+if ! grep -q "Signed-off-by: " "$1"; then
+    echo -e "${YELLOW}Adding 'Signed-off-by' line...${NC}"
+
+    # Get git user info
+    name=$(git config user.name)
+    email=$(git config user.email)
+
+    if [ -n "$name" ] && [ -n "$email" ]; then
+        echo "" >> "$1"
+        echo "Signed-off-by: $name <$email>" >> "$1"
+    else
+        echo -e "${RED}ERROR: Cannot add Signed-off-by - git user.name or user.email not configured${NC}"
+        exit 1
+    fi
+fi
+
+exit 0

.gitignore

@@ -6,3 +6,26 @@ tests/temp
 .phpunit.result.cache
 .php-cs-fixer.cache
 reports
+
+.qodo
+
+# Qodana
+qodana.yaml
+qodana.sarif.json
+.qodana/
+
+# Temporary files
+commit_messages.txt
+*.tmp
+
+# Docker
+.docker/
+docker-compose.override.yml
+
+# Pre-commit
+.pre-commit/
+
+# Node modules
+node_modules/
+package-lock.json
+.php-cs-fixer.cache

.gitmessage

@@ -0,0 +1,22 @@
+# Conventional Commit Format:
+# <type>(<scope>): <subject>
+#
+# <body>
+#
+# <footer>
+#
+# Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+# Scope: Optional, e.g., parser, compiler, etc.
+# Subject: Brief description (imperative mood, no period)
+# Body: Detailed explanation (optional)
+# Footer: Breaking changes, issue references (optional)
+#
+# Examples:
+# feat(api): add user authentication endpoint
+# fix(parser): resolve memory leak in tokenizer
+# docs: update installation instructions
+#
+# Breaking change example:
+# feat(api)!: change authentication to use JWT
+#
+# BREAKING CHANGE: API now requires JWT tokens instead of API keys

.phan/config.php

@@ -57,6 +57,9 @@
     // Automatically inferred from composer.json requirement for "php" of "^8.3"
     'target_php_version' => '8.3',
 
+    // Minimum PHP version to check compatibility against
+    'minimum_target_php_version' => '8.3',
+
     // If enabled, missing properties will be created when
     // they are first seen. If false, we'll report an
     // error message if there is an attempt to write
@@ -306,7 +309,7 @@
 
     // The number of processes to fork off during the analysis
     // phase.
-    'processes' => 4,
+    'processes' => 1,
 
     // List of case-insensitive file extensions supported by Phan.
     // (e.g. `['php', 'html', 'htm']`)
@@ -356,6 +359,7 @@
     // your application should be included in this list.
     'directory_list' => [
         'src',
+        'tests',
         'vendor',
     ],
 

.php-cs-fixer.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+$finder = PhpCsFixer\Finder::create()
+    ->in(__DIR__)
+    ->exclude('vendor')
+    ->exclude('.github')
+    ->exclude('docker')
+    ->name('*.php')
+    ->notName('*.blade.php')
+    ->ignoreDotFiles(true)
+    ->ignoreVCS(true);
+
+return (new PhpCsFixer\Config())
+    ->setFinder($finder)
+    ->setRules([
+        '@PER-CS2.0' => true,  // PER 2.0 coding standard
+        // Additional project-specific rules to align with our standards
+        'concat_space' => ['spacing' => 'one'],
+        'array_indentation' => true,
+        'binary_operator_spaces' => [
+            'operators' => [
+                '=>' => 'align_single_space_minimal',
+            ],
+        ],
+        'phpdoc_line_span' => [
+            'const' => 'single',
+            'property' => 'single',
+            'method' => 'multi',
+        ],
+        'no_superfluous_phpdoc_tags' => [
+            'allow_mixed' => true,
+            'allow_unused_params' => false,
+        ],
+    ])
+    ->setRiskyAllowed(true)
+    ->setUsingCache(true);

.pr_agent.toml

@@ -55,4 +55,4 @@ push_commands = [
     """,
     "/review auto_approve --pr_reviewer.num_code_suggestions=0 --pr_reviewer.inline_code_comments=true"
 ]
-handle_push_trigger = true
+handle_push_trigger = true

.pre-commit-config.yaml

@@ -0,0 +1,98 @@
+# See https://pre-commit.com for more information
+repos:
+  # Local hooks that run in Docker containers
+  - repo: local
+    hooks:
+      - id: composer-validate
+        name: Validate composer.json
+        entry: docker-compose run --rm test-code-style composer validate --strict
+        language: system
+        files: composer\.(json|lock)$
+        pass_filenames: false
+
+      - id: php-lint
+        name: PHP Syntax Check
+        entry: docker-compose run --rm test-lint
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: php-code-style
+        name: PHP Code Style (Laravel Pint)
+        entry: docker-compose run --rm test-code-style
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: phpstan
+        name: PHPStan Static Analysis
+        entry: docker-compose run --rm test-phpstan
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: psalm
+        name: Psalm Static Analysis
+        entry: docker-compose run --rm test-psalm
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: phpunit
+        name: PHPUnit Tests
+        entry: docker-compose run --rm test-phpunit
+        language: system
+        files: \.(php|xml)$
+        pass_filenames: false
+
+      - id: security-check
+        name: Security Vulnerabilities Check
+        entry: docker-compose run --rm test-security
+        language: system
+        files: composer\.lock$
+        pass_filenames: false
+
+      - id: phpmd
+        name: PHP Mess Detector
+        entry: docker-compose run --rm test-phpmd
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: phan
+        name: Phan Static Analysis
+        entry: docker-compose run --rm test-phan
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: rector
+        name: Rector Code Quality
+        entry: docker-compose run --rm test-rector
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: infection
+        name: Infection Mutation Testing
+        entry: docker-compose run --rm test-infection
+        language: system
+        files: \.php$
+        pass_filenames: false
+        stages: [pre-push]
+
+  # Standard pre-commit hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^vendor/
+      - id: end-of-file-fixer
+        exclude: ^vendor/
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: check-json
+      - id: check-xml
+      - id: mixed-line-ending
+        args: ['--fix=lf']