feat(rhdh-upgrade-helper): AI-assisted 1.y→2.y chart migration

[rm3l]

Summary

Adds chart values migration support to the rhdh-upgrade-helper skill for RHDH Helm chart major version upgrades (1.y → 2.y).

The 2.y chart flattens the nested upstream.backstage.* / global.* values structure to root-level keys. This implementation combines:

• Deterministic translation engine (103 key mappings + 4 removed keys) applied automatically by a stdlib-only Python script
• AI-assisted resolution of 8 ambiguous areas (ingress, args, extraEnvFrom, auth secret, init containers, networkPolicy, Intelligent Assistant, Orchestrator) via a structured workflow
• Behavioral change warnings (PostgreSQL version, HPA defaults, digest/tag interaction, air-gapped plugin limitations)
• Internal template detection — flags janus-idp.* Helm template references that need updating to rhdh.*, with guidance to inspect _helpers.tpl
• Image digest clearing — dynamically scans all image paths and clears digest when any of registry/repository/tag is explicitly set
• Go template .Values.* reference rewriting — automatically replaces .Values.global.*, .Values.upstream.*, and .Values.route.* references with their 2.y equivalents (e.g., .Values.global.host → .Values.host). Flags decomposed fields and unmapped references for review.
• Chart-managed defaults handling — comments out unconditional chart defaults in extraVolumes, extraVolumeMounts, extraEnv, and extraInitContainers (e.g., dynamic-plugins-root, npmcacache, APP_CONFIG_backend_listen_port) so users can see what was there and uncomment if needed. Flags conditional defaults (BACKEND_SECRET, POSTGRES_*, backstage-app-config, etc.) for review.
• Header recommendation — output files include a TIP advising users to only include customized values for easier maintenance and smoother future upgrades

The migration script never modifies original input files — output is written next to the original with a versioned suffix (e.g., values.yaml → values-2.1.yaml). Multiple input files are supported, preserving the customer's file separation. Review comments are placed inline next to each affected field.

Deliverables

• references/chart-migration-1y-2y.md — authoritative mapping tables, ambiguous area guidance, and full chart-default inventory
• scripts/migrate-chart-values.py — deterministic migration engine with multi-file support, .Values.* ref rewriting, chart-default commenting, and --to versioned output
• workflows/chart-migration.md — 5-step AI-assisted migration workflow with chart version resolution (official repo first, upstream fallback)
• SKILL.md routing, scoring model, and config analysis updates
• Eval suite with 4 cases and 5 judges

Usage

# Single file — output written next to the original
python3 scripts/migrate-chart-values.py values.yaml --to 2.1

# Multiple files — each output next to its original
python3 scripts/migrate-chart-values.py base.yaml prod.yaml --to 2.1

# Explicit output path
python3 scripts/migrate-chart-values.py values.yaml --to 2.1 -o /tmp/migrated.yaml

# stdout
python3 scripts/migrate-chart-values.py values.yaml --to 2.1 -o -

Test plan

• Script runs against simple fixture (exit 0, 24 keys migrated)
• Script runs against complex fixture with all 8 ambiguous areas (exit 1, 41 keys, 8 review areas)
• Script runs against minimal/edge fixture (exit 0, 1 key)
• Multi-file mode produces separate versioned output files next to originals
• --to flag generates correct filenames (e.g., values-2.1.yaml)
• Fallback to -migrated suffix when --to is omitted
• Image digest cleared for any custom image override (registry, repository, or tag)
• janus-idp.* template references detected and flagged inline
• .Values.global.* / .Values.upstream.* template references rewritten to 2.y paths
• Unconditional chart defaults commented out (not removed) with "uncomment if needed" header
• Conditional chart defaults flagged for review (not removed)
• Header TIP recommending only customized values included in output
• MIGRATION-REVIEW comments placed inline next to corresponding fields
• Chart version resolution: official repo checked first, upstream fallback
• Pre-commit hooks pass
• Test against real customer 1.y values files (path-based routing, custom registry, custom tag)
• Validate output with helm template against chart 3.4.5 (appVersion 2.1.0)

Ref: RHIDP-17323

Assisted-by: Claude