Summary

Several functions in the codebase have grown large and complex, making them harder to maintain, test, and extend. Rather than a big-bang refactor, this issue tracks an incremental approach: add markers to guide developers to extract methods as they touch the code.

Problem

ObjectTransformer.map_object (~190 lines)

The main transformation function has an 8-branch if/elif chain for slot derivation strategies:

• slot_derivation.value
• slot_derivation.unit_conversion
• slot_derivation.expr
• slot_derivation.populated_from
• slot_derivation.sources
• slot_derivation.object_derivations
• default fallback

Each new feature (pivot #103, offset #96, cross-class lookup #97) adds another branch.

eval_utils.eval_ (~100 lines)

Type-dispatch function with 15+ branches for AST node types. Will grow if expression language expands (#98).

Approach

1. Add a developer note at the top of each function explaining the extract-on-touch pattern
2. Add # EXTRACT: markers at each branch with suggested method signature
3. Point developers to the new test framework (tests/test_transformer/test_object_transformer_new.py)
4. As features are added or bugs fixed, extract the touched section

Benefits

• No merge conflicts with active PRs (And read and write TSV for data mapping #100, Allow populated_from to lookup from external class #101)
• Refactoring cost spread across feature work
• Each extraction is small and reviewable
• Test coverage grows incrementally

Checklist

• Add markers to ObjectTransformer.map_object
• Add markers to eval_utils.eval_
• Document the pattern in contributing guide (optional)

Related Issues

• implement pivot operation, for unmelting generic measurement/EAV data to wide tables #103 - Pivot operation (would add to map_object)
• Standardize how to map scalar binning Enums to a corresponding scalar slot #99 - Scalar binning enums (would add to map_object)
• Implement offset calculation #96 - Offset calculation (would add to map_object)
• identify expression language and implementation(s) in LinkML. Applicable to linkml-map? #98 - Expression language (would add to eval_)
• Error mapping between slots in implicit study model and target model when both are enums #85 - Enum mapping bug (fix would benefit from cleaner code)