Add markers and instructions to extract branches from long functions

Author: amc-corey-cox

.github/CONTRIBUTING.md

@@ -1,5 +1,9 @@
 # Contributing
 
+### Testing
+
+See `tests/README.md` for guidance on the scaffold-based testing pattern used in this project.
+
 ### Code Style
 
 This project uses [`black`](https://github.com/psf/black) to automatically

AGENTS.md

@@ -43,4 +43,13 @@ Best practice:
 * Pydantic or LinkML is favored for data objects
 * For state in engine-style OO classes, dataclasses is favored
 * Declarative principles are favored
-* Always use type hints, always document methods and classes
+* Always use type hints, always document methods and classes
+* **Always add tests when implementing new features or fixing bugs.** Don't wait to be asked.
+* For transformation tests, use the scaffold-based testing pattern described in `tests/README.md`
+
+## Code Patterns
+
+When modifying `ObjectTransformer.map_object`, check for `# EXTRACT:` markers.
+If touching a marked section, extract it to a private method first and add a test
+in `tests/test_transformer/test_object_transformer_new.py` using `@add_to_test_setup`.
+See issue #104 for context.

src/linkml_map/transformer/object_transformer.py

@@ -145,6 +145,13 @@ def index(self, source_obj: Any, target: Optional[str] = None) -> None:
         else:
             self.object_index = ObjectIndex(source_obj, schemaview=self.source_schemaview)
 
+    # Developer Note:
+    # This method has grown large. When modifying it, consider extracting to
+    # private methods and adding tests using the scaffold-based testing pattern.
+    # See EXTRACT markers below for candidates.
+    #
+    # See: tests/README.md for testing guidance
+    # Tracking: https://github.com/linkml/linkml-map/issues/104
     def map_object(
         self,
         source_obj: OBJECT_TYPE,
@@ -161,6 +168,7 @@ def map_object(
         :return: transformed data, either as type target_type or a dictionary
         """
         sv = self.source_schemaview
+        # EXTRACT: _resolve_source_type(sv, source_obj) -> str
         if source_type is None and sv is None:
             # TODO: use smarter method
             source_type = next(iter(self.specification.class_derivations.values())).name
@@ -227,6 +235,7 @@ def map_object(
                 v = self._perform_melt(
                     slot_derivation.pivot_operation, source_obj, slot_derivation
                 )
+            # EXTRACT: _derive_from_expr(slot_derivation, source_obj, source_obj_typed, source_type, sv) -> Any
             elif slot_derivation.expr:
                 if bindings is None:
                     bindings = Bindings(
@@ -248,6 +257,7 @@ def map_object(
                     aeval = Interpreter(usersyms={"src": ctxt_obj, "target": None})
                     aeval(slot_derivation.expr)
                     v = aeval.symtable["target"]
+            # EXTRACT: _derive_from_populated_from(slot_derivation, source_obj, sv, source_type) -> tuple[Any, SlotDefinition]
             elif slot_derivation.populated_from:
                 populated_from = slot_derivation.populated_from
                 fk_resolution = resolve_fk_path(sv, source_type, populated_from)
@@ -309,6 +319,7 @@ def map_object(
                 logger.debug(
                     f"Pop slot {slot_derivation.name} => {v} using {slot_derivation.populated_from} // {source_obj}"
                 )
+            # EXTRACT: _derive_from_object_derivations(slot_derivation, source_obj, source_type, target_type) -> Any
             elif slot_derivation.object_derivations:
                 # We'll collect all derived objects here
                 derived_objs = []
@@ -337,6 +348,7 @@ def map_object(
             else:
                 source_class_slot = sv.induced_slot(slot_derivation.name, source_type)
                 v = source_obj.get(slot_derivation.name, None)
+            # EXTRACT: _post_process_slot_value(v, source_class_slot, slot_derivation, class_deriv) -> Any
             if source_class_slot and v is not None:
                 # slot is mapped and there is a value in the assignment
                 target_range = slot_derivation.range

tests/README.md

@@ -0,0 +1,41 @@
+# Testing
+
+## Scaffold-Based Testing Pattern
+
+This project uses a **scaffold-based testing pattern** for transformation tests. The pattern:
+
+1. A **scaffold** provides base schemas, transform spec, input data, and expected output
+2. **Setup functions** patch the scaffold incrementally using `apply_schema_patch()` / `apply_transform_patch()`
+3. **Unit tests** run each setup function in isolation
+4. **Integration tests** run all setups cumulatively, catching interaction bugs
+
+This pattern is preferred for transformation tests because it:
+- Makes tests concise (just patches, not full schemas)
+- Catches both individual feature bugs and feature interaction bugs
+- Builds up a realistic, complex test scenario over time
+
+### Existing Scaffolds
+
+- **Simple** (`tests/scaffold/`): Basic slot derivations, Person→Agent transforms.
+  Fixtures: `scaffold`, `integration_scaffold`. Decorator: `@add_to_test_setup`
+
+- **Container** (`tests/scaffold_container/`): FK lookups, flattening, cross-class transforms.
+  Fixtures: `container_scaffold`, `integration_container_scaffold`. Decorator: `@add_to_container_test_setup`
+
+### When to Create a New Scaffold
+
+If testing a feature that doesn't fit existing scaffolds (e.g., different schema shape,
+inheritance hierarchies, enum-heavy transforms), create a new scaffold directory following
+the same pattern. See `tests/scaffold/` for the structure.
+
+### Utilities
+
+See `tests/scaffold/utils/apply_patch.py` for patching utilities.
+
+### When to Use Traditional Tests
+
+It's okay to use traditional tests (not scaffold-based) when:
+- Testing utility functions (unit conversion, eval_utils, etc.)
+- Testing error handling or edge cases that don't fit the scaffold pattern
+- Testing components outside the transformer (CLI, schema mapping, inverter)
+- Quick regression tests for specific bugs