Add flexible API compatibility modes for recursive dependency resolution

[AndreaV-Lsi]

Add flexible API compatibility modes for recursive dependency resolution

Feature Description

Currently, LsiGitCheckout uses a strict intersection algorithm when resolving version conflicts between multiple projects that depend on the same repository. While this ensures maximum compatibility, it can be overly conservative in development environments where teams can quickly adapt to API changes.

This feature introduces flexible API compatibility modes that allow users to choose between strict compatibility (current behavior) and permissive compatibility based on their needs.

Proposed Implementation

1. Add "API Compatibility" field to dependencies.json

• Optional field with values: "Strict" or "Permissive"
• Controls how version conflicts are resolved for each repository
• When not specified, inherits from script parameter default

2. Add -ApiCompatibility script parameter

• Sets the default compatibility mode when not specified in dependencies
• Default value: "Permissive"
• Validates input to accept only "Strict" or "Permissive"

3. Mode Behaviors

Strict Mode

• Uses intersection of compatible tags (conservative, ensures compatibility)
• Selects the most recent version from the intersection set
• Ideal for production environments requiring stability

Permissive Mode

• Uses union of compatible tags (flexible, allows newer versions)
• Selects the most recent version from the union set
• Ideal for development environments with rapid iteration

4. Mode Interaction Rules

When the same repository is encountered multiple times with different compatibility modes:

• Strict + Strict → Use intersection algorithm
• Strict + Permissive → Keep existing Strict repository unchanged
• Permissive + Permissive → Use union algorithm
• Permissive + Strict → Adopt Strict mode and its requirements

Use Cases

Strict Mode is ideal for:

• Production environments
• Systems requiring API stability
• Regulated industries (financial, healthcare)
• Conservative version management
• Critical infrastructure components

Permissive Mode is ideal for:

• Development environments
• Rapid iteration cycles
• Teams that can adapt to API changes
• Projects prioritizing latest features
• Experimental or beta testing

Example Configuration

[
  {
    "Repository URL": "https://github.com/myorg/stable-lib.git",
    "Base Path": "libs/stable",
    "Tag": "v2.0.0",
    "API Compatible Tags": ["v1.8.0", "v1.9.0"],
    "API Compatibility": "Strict",
    "_comment": "Production library requiring strict compatibility"
  },
  {
    "Repository URL": "https://github.com/myorg/dev-lib.git",
    "Base Path": "libs/dev",
    "Tag": "v3.0.0-beta",
    "API Compatible Tags": ["v2.0.0", "v2.1.0", "v2.2.0"],
    "API Compatibility": "Permissive",
    "_comment": "Development library allowing flexible updates"
  },
  {
    "Repository URL": "https://github.com/myorg/shared-utils.git",
    "Base Path": "libs/utils",
    "Tag": "v1.5.0",
    "API Compatible Tags": ["v1.0.0", "v1.1.0", "v1.2.0", "v1.3.0", "v1.4.0"],
    "_comment": "Uses default compatibility mode from script parameter"
  }
]

Command Line Examples

# Development environment with permissive defaults
.\LsiGitCheckout.ps1 -Recursive

# Production environment with strict defaults
.\LsiGitCheckout.ps1 -Recursive -ApiCompatibility Strict

# Mixed environment with custom configuration
.\LsiGitCheckout.ps1 -Recursive -ApiCompatibility Permissive -InputFile production-deps.json

Benefits

1. Flexibility: Adapt to different environment requirements without changing core logic
2. Backward Compatibility: Defaults to Permissive mode, maintaining expected behavior
3. Gradual Migration: Allows transitioning between modes on a per-repository basis
4. Mixed Environments: Supports both stable and experimental components in the same project
5. Clear Semantics: Mode names clearly indicate their behavior and use cases

Technical Implementation Details

Union Algorithm Enhancement

• Preserves temporal ordering when tag lists share common prefixes
• Falls back to unordered union with warning when lists are incompatible
• Maintains chronological order for better version selection

Repository Dictionary Enhancement

• Tracks API Compatibility mode for each repository
• Updates mode based on interaction rules
• Preserves most restrictive mode when conflicts occur

Error Handling

• Validates API Compatibility values
• Provides clear warnings for temporal ordering issues
• Maintains existing error handling for version conflicts

Migration Path

For users upgrading from v4.0.x:

• No changes required for existing configurations
• Default behavior changes to Permissive (more flexible)
• To maintain exact v4.0.x behavior: use -ApiCompatibility Strict
• Existing "API Compatible Tags" continue to work as before

Testing Scenarios

1. Pure Strict Mode: All repositories with Strict compatibility
2. Pure Permissive Mode: All repositories with Permissive compatibility
3. Mixed Mode: Combination of Strict and Permissive repositories
4. Mode Transitions: Repository changing from Permissive to Strict
5. Default Behavior: Repositories without explicit compatibility setting
6. Temporal Ordering: Various tag list configurations to test union algorithm

Documentation Updates

• Update README.md with new parameter and field documentation
• Add examples demonstrating different compatibility modes
• Update migration guide for v4.0.x → v4.1.x
• Include use case recommendations in documentation

Future Enhancements

Consider for future versions:

• Additional compatibility modes (e.g., "Latest", "Stable")
• Per-dependency override capabilities
• Compatibility mode recommendations based on repository characteristics
• Integration with CI/CD pipelines for environment-specific configurations