Add tests for mixin referrals across mixin files

Document how add_mixins replaces a whole mixin when a later mixin file
redefines an existing name, and what that means for the 'mixin' referral
key: the referral is dropped, changed or added together with the rest of
the mixin, an unrelated addition leaves it untouched, and a later file
can supply a mixin that an earlier one already references.

Assisted-by: Claude Opus (Antigravity) for test case generation and
  architecture-level testing

Author: PiousCrossten

test/test_add_mixins_referral.py

@@ -0,0 +1,135 @@
+# Copyright 2026 Innocent Pious
+# Licensed under the Apache License, Version 2.0
+
+"""Tests for how ``add_mixins`` merges the 'mixin' referral key.
+
+When a second mixin file (e.g. from another mixin repository/location)
+defines a mixin whose name already exists, ``add_mixins`` replaces the whole
+mixin dict rather than merging individual keys. These tests document how that
+whole-mixin overwrite affects the 'mixin' referral key introduced for mixins
+referencing other mixins.
+"""
+
+from collections import defaultdict
+
+from colcon_mixin.mixin import add_mixins
+from colcon_mixin.mixin.order import compute_application_order
+
+
+def _write_mixin(tmp_path, name, content):
+    path = tmp_path / name
+    path.write_text(content)
+    return path
+
+
+def _add(tmp_path, name, content):
+    """Add a mixin file to a fresh collection and return it."""
+    mixins_by_verb = defaultdict(dict)
+    add_mixins(_write_mixin(tmp_path, name, content), mixins_by_verb)
+    return mixins_by_verb
+
+
+def test_referral_dropped_when_overwritten_without_mixin_key(tmp_path):
+    # repo 1 defines 'child' referencing 'base'
+    mixins_by_verb = _add(tmp_path, 'repo1.mixin', """\
+build:
+  base:
+    cmake-args: ['FOO=BASE']
+  child:
+    mixin: ['base']
+    cmake-args: ['FOO=CHILD1']
+""")
+    # repo 2 redefines 'child' WITHOUT the referral
+    add_mixins(_write_mixin(tmp_path, 'repo2.mixin', """\
+build:
+  child:
+    cmake-args: ['FOO=CHILD2']
+"""), mixins_by_verb)
+
+    child = mixins_by_verb[('build',)]['child']
+    # the whole mixin was replaced, so the referral is gone
+    assert 'mixin' not in child
+    assert child['cmake-args'] == ['FOO=CHILD2']
+    # and the application order no longer pulls in 'base'
+    assert compute_application_order(
+        mixins_by_verb[('build',)], 'child') == ['child']
+
+
+def test_referral_changed_when_overwritten_with_different_targets(tmp_path):
+    # repo 1: child -> [base_a]
+    mixins_by_verb = _add(tmp_path, 'repo1.mixin', """\
+build:
+  base_a: {cmake-args: ['FOO=A']}
+  base_b: {cmake-args: ['FOO=B']}
+  child:
+    mixin: ['base_a']
+""")
+    # repo 2 redefines child -> [base_b]
+    add_mixins(_write_mixin(tmp_path, 'repo2.mixin', """\
+build:
+  child:
+    mixin: ['base_b']
+"""), mixins_by_verb)
+
+    assert mixins_by_verb[('build',)]['child']['mixin'] == ['base_b']
+    assert compute_application_order(
+        mixins_by_verb[('build',)], 'child') == ['base_b', 'child']
+
+
+def test_referral_added_when_overwriting_plain_mixin(tmp_path):
+    # repo 1: child has no referral
+    mixins_by_verb = _add(tmp_path, 'repo1.mixin', """\
+build:
+  base: {cmake-args: ['FOO=BASE']}
+  child: {cmake-args: ['FOO=CHILD1']}
+""")
+    # repo 2 redefines child to reference base
+    add_mixins(_write_mixin(tmp_path, 'repo2.mixin', """\
+build:
+  child:
+    mixin: ['base']
+    cmake-args: ['FOO=CHILD2']
+"""), mixins_by_verb)
+
+    assert mixins_by_verb[('build',)]['child']['mixin'] == ['base']
+    assert compute_application_order(
+        mixins_by_verb[('build',)], 'child') == ['base', 'child']
+
+
+def test_referral_survives_when_second_repo_adds_unrelated_mixin(tmp_path):
+    # repo 1 defines child -> [base]
+    mixins_by_verb = _add(tmp_path, 'repo1.mixin', """\
+build:
+  base: {cmake-args: ['FOO=BASE']}
+  child:
+    mixin: ['base']
+    cmake-args: ['FOO=CHILD1']
+""")
+    # repo 2 only adds a new, unrelated mixin
+    add_mixins(_write_mixin(tmp_path, 'repo2.mixin', """\
+build:
+  extra: {cmake-args: ['FOO=EXTRA']}
+"""), mixins_by_verb)
+
+    # the existing referral is untouched
+    assert mixins_by_verb[('build',)]['child']['mixin'] == ['base']
+    assert compute_application_order(
+        mixins_by_verb[('build',)], 'child') == ['base', 'child']
+
+
+def test_second_repo_can_supply_the_referenced_mixin(tmp_path):
+    # repo 1 references a 'base' that does not exist yet
+    mixins_by_verb = _add(tmp_path, 'repo1.mixin', """\
+build:
+  child:
+    mixin: ['base']
+    cmake-args: ['FOO=CHILD1']
+""")
+    # repo 2 provides the referenced mixin
+    add_mixins(_write_mixin(tmp_path, 'repo2.mixin', """\
+build:
+  base: {cmake-args: ['FOO=BASE']}
+"""), mixins_by_verb)
+
+    assert compute_application_order(
+        mixins_by_verb[('build',)], 'child') == ['base', 'child']