Test names and descriptions unified

commit_hash:09720eaa924b03c138d3922db5bc6cb7386a59c0

test_data/parsing_test_data/templates/basic_template_definition.json

@@ -1,5 +1,5 @@
 {
-  "description": "Simple template",
+  "description": "A template definition with only literal fields and no reference definitions. Verifies basic merge of template literals into the usage.",
   "templates": {
     "title": {
       "type": "text",

test_data/parsing_test_data/templates/definition_literal_wins_over_reference.json

@@ -0,0 +1,36 @@
+{
+  "description": "A template definition declares both a literal value and a reference definition for the same field. Verifies the literal wins — the reference substitution is skipped when the field is already populated — even when the usage supplies a reference value.",
+  "templates": {
+    "conflicted": {
+      "type": "text",
+      "text": "LITERAL",
+      "$text": "content"
+    }
+  },
+  "card": {
+    "log_id": "test",
+    "states": [
+      {
+        "state_id": 0,
+        "div": {
+          "type": "conflicted",
+          "content": "from link"
+        }
+      }
+    ]
+  },
+  "expected": {
+    "card": {
+      "log_id": "test",
+      "states": [
+        {
+          "state_id": 0,
+          "div": {
+            "type": "text",
+            "text": "LITERAL"
+          }
+        }
+      ]
+    }
+  }
+}

test_data/parsing_test_data/templates/definition_with_nested_object_literal.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template with nested object",
+  "description": "A template definition contains a nested object as a literal. Verifies the object is merged into the usage without references.",
   "templates": {
     "card_text": {
       "type": "text",

test_data/parsing_test_data/templates/derived_template_preserves_parent_references.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template with parent template with link",
+  "description": "A derived template inherits a parent template whose body contains reference definitions inside nested structures. Verifies that inherited references from the parent and the derived template's own references all resolve against the usage's reference values.",
   "templates": {
     "base_text": {
       "type": "text",

test_data/parsing_test_data/templates/derived_template_rebinds_reference.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template link is overridden in derived template",
+  "description": "A derived template (via 'type: <parent>') rebinds the parent's reference definition to a different source name. Verifies the derived template's reference wins over the parent's.",
   "templates": {
     "base_text": {
       "type": "text",

test_data/parsing_test_data/templates/derived_template_without_references.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template chain",
+  "description": "A derived template (via 'type: <parent>') inherits only literal fields from its parent, with no references involved. Verifies the parent's literals are merged into the derived template's resolution.",
   "templates": {
     "base_text": {
       "type": "text",

test_data/parsing_test_data/templates/isolation_items_inside_reference_slot.json

@@ -1,5 +1,5 @@
 {
-  "description": "A 'nested' template declares '$items: items' as a parameter and is placed inside the card's own data under the 'root' template's '$items' slot.",
+  "description": "A template usage with its own explicit 'items: []' sits inside the card's data under the parent template's '$items' reference slot. Verifies parameter cascade stops at the reference-slot boundary: the inner usage's own items are preserved (and later dropped by the container validator, yielding '{type: container}').",
   "templates": {
     "nested": {
       "type": "container",
@@ -64,4 +64,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/isolation_nested_usages_same_reference_field_and_source.json

@@ -1,5 +1,5 @@
 {
-  "description": "Two nested templates ('root' and 'nested') both declare '$items: items' — same link field AND same parameter name. Verifies that each template's 'items' parameter is scoped to that template: the outer root's 'items' value must not leak into the inner nested instance and overwrite its own 'items'.",
+  "description": "Two template definitions ('root' and 'nested') both declare the same reference '$items: items' — identical reference field and identical source name. A usage of one is nested inside the other via the card's own data. Verifies scope isolation: each template's reference is scoped to its own usage, and the outer usage's items do not overwrite the inner usage's items.",
   "templates": {
     "nested": {
       "type": "container",
@@ -56,4 +56,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/isolation_nested_usages_same_reference_source.json

@@ -1,5 +1,5 @@
 {
-  "description": "Link with same reference name (itemsRef) defined in two templates",
+  "description": "Two template definitions both declare '$items: itemsRef' — identical source name, distinct from the field name. A usage of one is nested inside the other via the card's own data. Verifies each reference resolves from its own usage's 'itemsRef', preserving scope despite the source-name collision.",
   "templates": {
     "nested": {
       "type": "container",
@@ -56,4 +56,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/isolation_scalar_reference_inside_reference_slot.json

@@ -0,0 +1,60 @@
+{
+  "description": "Scalar counterpart of isolation_items_inside_reference_slot: a nested template usage with its own reference value ('textRef: \"INNER\"') sits inside the card's data under the parent template's '$items' reference slot, wrapped in a plain container whose own 'textRef: \"OUTER\"' must not leak in. Verifies parameter cascade does not cross the reference-slot boundary for a non-items, non-empty value.",
+  "templates": {
+    "root": {
+      "type": "container",
+      "$items": "items"
+    },
+    "nested": {
+      "type": "text",
+      "$text": "textRef"
+    }
+  },
+  "card": {
+    "log_id": "test",
+    "states": [
+      {
+        "state_id": 0,
+        "div": {
+          "type": "root",
+          "items": [
+            {
+              "type": "container",
+              "textRef": "OUTER",
+              "items": [
+                {
+                  "type": "nested",
+                  "textRef": "INNER"
+                }
+              ]
+            }
+          ]
+        }
+      }
+    ]
+  },
+  "expected": {
+    "card": {
+      "log_id": "test",
+      "states": [
+        {
+          "state_id": 0,
+          "div": {
+            "type": "container",
+            "items": [
+              {
+                "type": "container",
+                "items": [
+                  {
+                    "type": "text",
+                    "text": "INNER"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    }
+  }
+}

test_data/parsing_test_data/templates/isolation_siblings_same_reference_field_distinct_sources.json

@@ -1,5 +1,5 @@
 {
-  "description": "Two templates ('nested_container' and 'row') each declare a '$items' link, but bind it to different parameter names ('content' and 'items'). Verifies that link resolution routes each template's 'items' field from its own declared parameter without cross-template interference.",
+  "description": "Two template definitions each declare a reference for the same field ('$items') but bind to different source names. Verifies each template's reference resolves from its own source name without cross-template interference.",
   "templates": {
     "root_container": {
       "type": "container"
@@ -79,4 +79,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/non_template_nested_type_not_expanded.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template name collides with 'type' value in nested property (e.g. accessibility). The resolver must not try to expand templates inside nested objects where 'type' has a different semantic meaning.",
+  "description": "A template name ('button') collides with the value of a 'type' field inside a non-Div nested property (accessibility.type). Verifies the resolver does not treat that non-Div dict as a template usage.",
   "templates": {
     "button": {
       "type": "text",

test_data/parsing_test_data/templates/outer_instance_overrides_body_default.json

@@ -1,5 +1,5 @@
 {
-  "description": "A '$text: textRef' link declared in the 'nested' template resolves against a 'textRef' value set at two levels: a default inside the intermediate 'root' template body and an override on the card itself. Verifies that the card-level value cascades down and wins over the intermediate template body's default.",
+  "description": "A reference declared on the leaf template resolves against a reference value declared at two levels: a default on the usage site inside an intermediate template's body, and a card-level override on the outer instance. Verifies the card-level value cascades down through template-body content and overrides the intermediate body's default.",
   "card": {
     "log_id": "test",
     "states": [

test_data/parsing_test_data/templates/reference_cascade_through_intermediate_definition.json

@@ -1,5 +1,5 @@
 {
-  "description": "Link (titleTextRef) exist in the middle of template resolution chain (nested_container)",
+  "description": "A reference definition sits on a template usage placed inside an intermediate template's body (between the outer usage and the leaf definition). Verifies that the card instance's reference value cascades through two levels of template-body content down to the leaf template's field.",
   "templates": {
     "root_container": {
       "type": "container",
@@ -58,4 +58,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/reference_cascade_through_nested_usage.json

@@ -1,5 +1,5 @@
 {
-  "description": "Parameter values are forwarded through a 2-level template chain (container → image) via $-link indirection",
+  "description": "A template usage inside another template's body declares a reference definition whose source name matches a field on the card instance. Verifies that the reference value on the outer instance cascades through two levels of template usage to drive the inner template's field.",
   "templates": {
     "inner_template": {
       "type": "image",

test_data/parsing_test_data/templates/reference_chain_two_hop_nested_in_body.json

@@ -1,5 +1,5 @@
 {
-  "description": "Transitive template dependencies in nested items",
+  "description": "A two-hop reference chain via nested usage: a template usage inside another template's body declares its own reference definition that points to a card field, while the used template has its own reference definition for a different field (with a literal default). Verifies the two-hop chain does not propagate and the affected item is dropped with an error.",
   "templates": {
     "base_text": {
       "type": "text",

test_data/parsing_test_data/templates/reference_chain_two_hop_via_usage.json

@@ -1,5 +1,5 @@
 {
-  "description": "Parameters passed via $-links from instance to nested template items",
+  "description": "A template usage inside another template's body declares its own reference definition that points to a field on the outer instance, and the used template has its own reference definition for the same slot. Verifies that a two-hop reference chain (instance field → usage reference → definition reference) does not propagate: only the single-hop sibling resolves, the chained item is dropped with an error.",
   "templates": {
     "header": {
       "type": "text",

test_data/parsing_test_data/templates/reference_definition_on_leaf_template.json

@@ -1,5 +1,5 @@
 {
-  "description": "Link (titleTextRef) exist in template definition (title_text), and not in template instance (nested_container)",
+  "description": "The reference definition lives inside the leaf template's definition itself — not on any usage site. Verifies the card instance's reference value still cascades through two levels of template-body content down to the leaf template's own reference.",
   "templates": {
     "root_container": {
       "type": "container",
@@ -58,4 +58,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/reference_definition_on_usage_inside_body.json

@@ -1,5 +1,5 @@
 {
-  "description": "Single-level link resolution in nested template instance",
+  "description": "A reference definition sits on a template usage placed inside another template's body. Verifies single-hop reference cascade: the card instance's reference value flows through the body to the nested usage's reference definition.",
   "templates": {
     "base_text": {
       "type": "text",

test_data/parsing_test_data/templates/reference_in_plain_nested_dict.json

@@ -1,5 +1,5 @@
 {
-  "description": "Link (image_start) not for direct property of text, but for nested properties (images)",
+  "description": "A reference definition lives inside a plain (non-template) nested dict embedded in a template's body — an element of an 'images' array. Verifies the reference still resolves against the outer instance despite the intermediate plain-dict layers.",
   "card": {
     "log_id": "test",
     "states": [
@@ -57,4 +57,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/reference_source_reused_across_sibling_fields.json

@@ -1,5 +1,5 @@
 {
-  "description": "Same link used in two places",
+  "description": "A template definition reuses the same reference source name across two sibling fields inside a nested object (paddings.$top and paddings.$bottom). Verifies both fields resolve to the same value from the usage's reference value.",
   "templates": {
     "spaced_text": {
       "type": "text",

test_data/parsing_test_data/templates/reference_source_reused_at_multiple_depths.json

@@ -1,5 +1,5 @@
 {
-  "description": "Same ref name (content) used by top-level $-link ($text) and nested non-template $-link ($log_id in actions)",
+  "description": "A single template definition reuses the same reference source name ('content') at two depths: a top-level $text and a nested $log_id inside actions[]. Verifies both sites receive the same value from the usage's reference value.",
   "templates": {
     "action_text": {
       "type": "text",
@@ -44,4 +44,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/reference_source_shared_with_nested_usage.json

@@ -1,5 +1,5 @@
 {
-  "description": "Same ref name (dir) consumed by parent $-link ($orientation) and needed by child template instance ($text)",
+  "description": "One reference source on the usage ('dir') is consumed both by the parent template's own reference definition ($orientation) and by a nested template usage's reference definition ($text). Verifies the reference value flows to both consumers.",
   "templates": {
     "labeled_container": {
       "type": "container",
@@ -47,4 +47,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/reference_to_array_field.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template with array link",
+  "description": "A reference definition targets an array-valued field ($items: children). Verifies the whole array value is pulled from the usage's reference value.",
   "templates": {
     "row": {
       "type": "container",

test_data/parsing_test_data/templates/reference_to_object_field.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template with linked nested object",
+  "description": "A reference definition targets an object-valued field ($paddings: padding_ref). Verifies the entire object value is pulled from the usage's reference value.",
   "templates": {
     "card_text": {
       "type": "text",

test_data/parsing_test_data/templates/reference_unresolved_for_optional_field.json

@@ -1,5 +1,5 @@
 {
-  "description": "Unresolved link for optional field does not break resolution",
+  "description": "A reference definition points to a source name the usage does not provide, for an optional field. Verifies an unresolved reference on an optional field is silently ignored.",
   "templates": {
     "styled_text": {
       "type": "text",

test_data/parsing_test_data/templates/references_at_multiple_depths.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template with link",
+  "description": "A template definition declares reference definitions at multiple depths: top-level ($text), inside a nested object ($top in paddings), and inside an array element ($url in actions[]). Verifies all references resolve against the usage's reference values.",
   "templates": {
     "title": {
       "type": "text",

test_data/parsing_test_data/templates/template_hierarchy_rebinds_reference.json

@@ -0,0 +1,45 @@
+{
+  "description": "A three-level template hierarchy (grand_parent → parent → child) where each derived template rebinds the parent's reference definition to a different source name. The usage supplies all three source fields; only the deepest rebinding must drive the resolved value.",
+  "templates": {
+    "grand_parent": {
+      "type": "text",
+      "$text": "ref_a"
+    },
+    "parent": {
+      "type": "grand_parent",
+      "$text": "ref_b"
+    },
+    "child": {
+      "type": "parent",
+      "$text": "ref_c"
+    }
+  },
+  "card": {
+    "log_id": "test",
+    "states": [
+      {
+        "state_id": 0,
+        "div": {
+          "type": "child",
+          "ref_a": "A",
+          "ref_b": "B",
+          "ref_c": "C"
+        }
+      }
+    ]
+  },
+  "expected": {
+    "card": {
+      "log_id": "test",
+      "states": [
+        {
+          "state_id": 0,
+          "div": {
+            "type": "text",
+            "text": "C"
+          }
+        }
+      ]
+    }
+  }
+}

test_data/parsing_test_data/templates/template_usage_inside_definition_body.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template 'list' (container) uses template 'item' (text) in its items. Verifies that templates referenced inside other templates' items are resolved correctly.",
+  "description": "A template definition ('list') uses another template ('item') inside its items array. Verifies template usages that appear inside another template's body are resolved.",
   "templates": {
     "item": {
       "type": "text",
@@ -51,4 +51,4 @@
       ]
     }
   }
-}
+}

test_data/parsing_test_data/templates/usage_direct_value_overrides_reference.json

@@ -1,5 +1,5 @@
 {
-  "description": "Direct value overrides link",
+  "description": "A template usage supplies both a direct value for a field and a reference value for that field's reference definition. Verifies that the usage's direct value wins — the reference substitution is skipped when the field is already populated.",
   "templates": {
     "linked_text": {
       "type": "text",

test_data/parsing_test_data/templates/usage_overrides_definition_literal.json

@@ -1,5 +1,5 @@
 {
-  "description": "Template with override",
+  "description": "A template usage supplies a direct value for a field that the template definition already sets as a literal. Verifies the usage's value wins over the literal.",
   "templates": {
     "styled_text": {
       "type": "text",

test_data/parsing_test_data/templates/validator_replaces_invalid_field_value.json

@@ -1,5 +1,5 @@
 {
-  "description": "Invalid value replaced with default value (div-text.font_size)",
+  "description": "Not a template test — verifies that an invalid field value (div-text.font_size = -1) is replaced by the field's default and reported as an error.",
   "card": {
     "log_id": "test",
     "states": [