🔧 Support multiple --mappings-file flags with deep merge capability

[httpdss]

🧩 Feature Implementation

This PR implements support for multiple --mappings-file flags as requested in issue #66.

✅ What Changed

Core Functionality

• Modified argument parser to accept multiple --mappings-file flags using action='append'
• Added deep merge capability with _deep_merge_dicts() method for intelligent merging
• Implemented order-preserving merge where later files override earlier ones for conflicting keys
• Deep merging for nested dictionaries to preserve hierarchical structure

Usage Examples

Basic multiple mappings:

struct generate \
  --mappings-file ./common-mappings.yaml \
  --mappings-file ./env-specific-mappings.yaml \
  file://my-struct.yaml .

Environment-based automation:

struct generate \
  --mappings-file ./mappings/common.yaml \
  --mappings-file ./mappings/${ENVIRONMENT}.yaml \
  file://infrastructure.yaml \
  ./output

Merging Behavior

Input files:

common.yaml:

mappings:
  teams:
    devops: devops-team
  environments:
    dev:
      database_url: postgres://dev-db:5432

production.yaml:

mappings:
  teams:
    frontend: frontend-team
  environments:
    dev:
      debug: true
    prod:
      database_url: postgres://prod-db:5432

Merged result:

mappings:
  teams:
    devops: devops-team      # from common.yaml
    frontend: frontend-team  # from production.yaml
  environments:
    dev:
      database_url: postgres://dev-db:5432  # from common.yaml
      debug: true                           # from production.yaml
    prod:
      database_url: postgres://prod-db:5432 # from production.yaml

🛠️ Technical Implementation

Deep Merge Algorithm

• Recursively merges nested dictionaries
• Preserves all keys from both dictionaries
• Later values override earlier ones for conflicts
• Maintains data type integrity

Error Handling

• Validates each mappings file exists before processing
• Stops execution if any mappings file is missing or invalid
• Provides clear error messages for debugging

Backward Compatibility

• Single --mappings-file usage remains unchanged
• No breaking changes to existing functionality
• Graceful handling when no mappings files are provided

📚 Documentation Updates

• Enhanced mappings.md with detailed multiple files documentation
• Updated usage.md to reflect new capability
• Added practical examples showing environment-specific patterns
• Explained merging behavior with clear examples

🧪 Testing

Added comprehensive tests covering:

• Deep merge functionality with nested dictionaries
• Multiple mappings file loading and merging
• Order preservation and override behavior
• Integration with existing generate command flow

🚀 Benefits

For CI/CD Automation

# Clean separation of common vs environment-specific config
struct generate \
  --mappings-file ./mappings/common.yaml \
  --mappings-file ./mappings/${ENVIRONMENT}.yaml \
  file://infrastructure.yaml \
  ./output

For DRY Principles

• Reusable common configurations across environments
• Environment-specific overrides without duplication
• Modular mapping organization for better maintainability

For Complex Projects

• Team-specific configurations with shared defaults
• Multi-environment deployments with inheritance
• Progressive configuration builds from base to specific

🔗 Resolves

Closes #66

---

This implementation provides the exact functionality requested in the issue while maintaining backward compatibility and adding comprehensive documentation and testing.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 86.04651% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.47%. Comparing base (5b7cfc8) to head (44369a3).

Files with missing lines	Patch %	Lines
struct_module/commands/generate.py	70.00%	5 Missing and 1 partial ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #67      +/-   ##
==========================================
+ Coverage   65.33%   66.47%   +1.14%     
==========================================
  Files          22       22              
  Lines        1203     1238      +35     
  Branches      171      174       +3     
==========================================
+ Hits          786      823      +37     
+ Misses        378      376       -2     
  Partials       39       39              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.