Refactor variables collection and builder to prevent scope creep and improve encapsulation

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

Problem

The variables collection and builder classes are currently too open-ended, leading to scope creep where domains that shouldn't be aware of precedence logic need to handle it manually. This architectural issue was highlighted in MR !203379 (merged) where the build_runner_presenter had to use variables&.to_hash instead of directly accessing the variables collection to ensure proper precedence handling.

Thread reference: !203379 (comment 2723906858)

Current Issues

1. Leaky Abstractions: The variables collection exposes internal structure that requires consumers to know about precedence logic
2. Error-Prone Usage: Developers need to remember to call to_hash to apply precedence, which is easy to forget
3. Scope Creep: Presenters and other consumers are forced to handle domain logic that should be encapsulated within the variables system
4. Inconsistent API: The collection can be used in multiple ways, some of which bypass important precedence logic

Proposed Solution

Refactor the variables collection and builder to:

1. Encapsulate precedence logic - Make precedence handling automatic and transparent to consumers
2. Provide a cleaner API - Consumers shouldn't need to know about internal implementation details
3. Reduce coupling - Presenters and other consumers should only need to request variables, not handle precedence
4. Improve maintainability - Centralize variable handling logic to reduce duplication and potential bugs

Related

• Original issue: gitlab-runner#28894 (closed)
• Fix MR: !203379 (merged)