Configuration File Replacement Schema Validation Bug

[dwenzel]

Problem Summary

When users place custom configuration files for tools (e.g., rector.php, phpstan.neon) in their project root or config directory, the custom files should replace the default configurations provided by quality-tools. However, this functionality has multiple validation and execution issues due to schema validation conflicts in the configuration discovery process.

Steps to Reproduce

Prerequisites

• Quality-tools package installed in a TYPO3 project
• Access to project root directory

Test Case 1: Basic Configuration File Override

1. Create a custom rector configuration in project root:

   cat > rector.php << 'EOF'
   <?php
   declare(strict_types=1);
   use Rector\Config\RectorConfig;
   return static function (RectorConfig $rectorConfig): void {
       $rectorConfig->paths(['custom-path/']);
   };
   EOF

2. Test configuration validation:

   vendor/bin/qt config:validate

3. Test configuration display:

   vendor/bin/qt config:show

4. Test rector execution:

   vendor/bin/qt lint:rector --dry-run

Test Case 2: Config Directory Override

1. Create configuration in config directory:

   mkdir -p config
   cat > config/rector.php << 'EOF'
   <?php
   declare(strict_types=1);
   use Rector\Config\RectorConfig;
   return static function (RectorConfig $rectorConfig): void {
       $rectorConfig->paths(['config-custom-path/']);
   };
   EOF

2. Repeat validation and execution tests from Test Case 1

Expected Behavior

1. Configuration Validation: Should properly validate merged configurations that include custom tool config file metadata
2. Tool Execution: Tools should use custom configuration files when present, falling back to defaults when not
3. Configuration Display: Should show merged configuration including custom tool config paths without schema errors
4. Priority Handling: Custom configs should override defaults with clear precedence rules

Observed Behavior

1. qt config:validate reports "[OK] Configuration is valid" (false positive)
2. qt lint:rector ignores the custom config file and uses the default config
3. qt config:show fails with schema validation errors:

   [ERROR] Failed to load configuration:
   Configuration file error [merged]: Invalid merged configuration:
   : The property tool_config_file is not defined and the definition does not allow additional properties
   : The property custom_config is not defined and the definition does not allow additional properties
   

Root Cause

The system discovers custom tool configs but adds runtime metadata keys (tool_config_file, custom_config) that aren't defined in the JSON schema at config/schema/quality-tools.json, causing validation failures when the merged configuration is validated.

Solution Branch

Work on this issue is being tracked in the issue-022-configuration-file-replacement-fix branch.

Detailed Analysis

For comprehensive technical analysis, implementation plan, and solution approach, see: Issue 022 Documentation

Impact

Priority: High - Core functionality broken

User Impact:

• Users cannot override default tool configurations
• False positive validation results create confusion
• Configuration introspection commands fail
• Reduced flexibility in tool customization