feat: addition info into component list endpoint in luminork

[johnrwatson]

Enhance Components Endpoint with Optional Qualification Status and Upgrade Information

How does this PR change the system?

This PR enhances the existing Luminork API /components endpoint with optional inclusion parameters, allowing clients to request additional component information without breaking backward compatibility. The enhancement provides real-time qualification status and upgrade-ability data on-demand.

Enhanced endpoint: GET /v1/w/{workspace_id}/change-sets/{change_set_id}/components

New optional query parameters:

• includeQualifications=true - Include real-time qualification status with running state tracking
• includeUpgradeStatus=true - Include upgrade-ability information

Key features:

• 100% backward compatible - existing calls work unchanged and return identical responses
• Optional performance cost - additional data only fetched when requested
• Real-time qualification tracking - shows actively executing qualifications via running count based on FuncRun states
• Follows existing patterns - uses same conditional inclusion pattern as existing includeCodegen parameter
• Production contract verified - matches existing production API response format exactly

Screenshots:

Basic response (unchanged, matches production):

{
  "componentDetails": [
    {
      "componentId": "01KCHHG49B8F0JXVJY3PQWS5S1",
      "name": "555s",
      "schemaName": "Workspace Management",
      "codegen": null
    }
  ],
  "nextCursor": null
}

Enhanced response with inclusions:

{
  "componentDetails": [
    {
      "componentId": "01KCHHG49B8F0JXVJY3PQWS5S1",
      "name": "555s",
      "schemaName": "Workspace Management", 
      "codegen": null,
      "qualificationStatus": {
        "total": 2,
        "succeeded": 2,
        "warned": 0,
        "failed": 0,
        "running": 0
      },
      "canBeUpgraded": false
    }
  ],
  "nextCursor": null
}

Out of Scope:

• Individual component qualification details (only summary counts provided)
• Historical qualification data (only current status)
• Modification of core qualification tracking logic (uses existing DAL methods)
• Breaking changes to existing API contracts

How was it tested?

Tests I actually ran and verified:

• Manual test: Production contract verification - Verified our response format matches production API exactly (componentDetails, nextCursor, componentId, schemaName)
• Manual test: Basic endpoint (backward compatibility) - Returns original 4 fields, no new fields when not requested
• Manual test: Enhanced endpoint with qualifications - includeQualifications=true adds qualificationStatus field with real data (total: 2, succeeded: 2, failed: 0, running: 0)
• Manual test: Enhanced endpoint with upgrade status - includeUpgradeStatus=true adds canBeUpgraded field with accurate values
• Manual test: Full inclusions - Both parameters work together, all expected fields present
• Manual test: Pagination with limit - limit=1 returns 1 component with correct cursor
• Manual test: Cursor pagination - Using cursor returns different component (pagination works correctly)
• Manual test: Error handling - Invalid workspace ID returns proper 400 error with correct format
• Manual test: OpenAPI documentation - All new parameters documented and present in spec (includeQualifications, includeUpgradeStatus)

Test results:

• Production contract verified - response format matches api.systeminit.com exactly
• Successfully tested with real workspace data (2 components: "555s" and "1")
• Backward compatibility confirmed - basic calls return identical response structure to production
• New functionality verified - inclusion parameters work as designed
• Real-time qualification tracking confirmed - shows actual qualification states with running count
• Pagination fully functional with enhanced parameters
• Error handling maintains existing behavior

Does it require a docs change?

• Yes, and this PR includes it

Documentation included:

• Complete OpenAPI/Swagger specification with new parameters
• Updated response schema examples showing optional fields
• Parameter descriptions for new inclusion options
• Maintains existing parameter documentation for backward compatibility

Technical approach:

• Backward compatibility: New optional fields use #[serde(skip_serializing_if = "Option::is_none")] to omit when not requested
• Real-time qualification tracking: Checks FuncRun states (Created/Dispatched/Running/PostProcessing) to determine actively executing qualifications
• Performance optimization: Additional database queries only occur when inclusion parameters are provided
• Shared utilities: Centralized qualification tracking logic prevents code duplication
• Consistent patterns: Follows existing conditional inclusion approach used by includeCodegen

Usage Examples

# Existing calls (unchanged) 
GET /components
GET /components?limit=10&includeCodegen=true

# New functionality
GET /components?includeQualifications=true
GET /components?includeUpgradeStatus=true  
GET /components?includeQualifications=true&includeUpgradeStatus=true

# Everything combined
GET /components?includeCodegen=true&includeQualifications=true&includeUpgradeStatus=true

[github-actions]

Dependency Review

✅ No vulnerabilities or OpenSSF Scorecard issues found.

Scanned Files

None