Support mixins referencing other mixins via a reserved 'mixin' key

A mixin definition may now reference other mixins through a 'mixin' key
whose value is a list of mixin names, so a high-level mixin can be
composed from smaller building-block mixins.

The application order is computed by a new standalone module
(colcon_mixin/mixin/order.py) using a depth-first, post-order traversal
with re-application: referenced mixins are recorded before the mixin
that references them, and a mixin reachable through multiple paths is
applied once per path to preserve last-applied-wins semantics. Cycle
detection uses the active recursion path only, so legitimate
re-application is never mistaken for a cycle.

In parse_args the requested mixins are expanded into the full
application order and applied in reverse, so the prepend-based overlay
produces the computed order while explicit command line arguments keep
precedence. The referencing mixin is applied conceptually last and can
override values inherited from its references. The reserved 'mixin' key
is skipped during overlay since it is metadata, not an argument.

Circular references, unknown references and malformed 'mixin' keys are
reported as clean CLI errors. Mixins without a 'mixin' key behave
exactly as before.

Add unit tests for the ordering algorithm and parser integration tests
covering nested references, scalar overrides, the canonical reference
graph, command line precedence and error reporting.

Author: PiousCrossten

colcon_mixin/mixin/mixin_argument.py

@@ -24,6 +24,10 @@
 from colcon_core.plugin_system import satisfies_version
 from colcon_mixin.mixin import add_mixins
 from colcon_mixin.mixin import get_mixins
+from colcon_mixin.mixin.order import CircularMixinError
+from colcon_mixin.mixin.order import compute_application_order
+from colcon_mixin.mixin.order import InvalidMixinError
+from colcon_mixin.mixin.order import MissingMixinError
 
 logger = colcon_logger.getChild(__name__)
 
@@ -181,23 +185,36 @@ def collect_parsers_by_verb(root, parsers, parent_verbs=()):
         # update args based on selected mixins
         if 'mixin_verb' in args:
             mixins = mixins_by_verb.get(args.mixin_verb, {})
+            context = '.'.join(args.mixin_verb)
             # validate the requested mixins in the order given on the command
             # line so an error reports the first unavailable mixin
             for mixin in args.mixin or ():
                 if mixin not in mixins:
-                    context = '.'.join(args.mixin_verb)
                     self._parser.error(
                         "Mixin '{mixin}' is not available for '{context}'"
                         .format_map(locals()))
+            # expand each requested mixin into the full list of mixins to
+            # apply: a mixin may reference other mixins through a 'mixin' key,
+            # which are applied first so the requesting mixin can override
+            # them (depth-first post-order, see colcon_mixin.mixin.order)
+            application_order = []
+            for mixin in args.mixin or ():
+                try:
+                    application_order += compute_application_order(
+                        mixins, mixin)
+                except (
+                    CircularMixinError, InvalidMixinError, MissingMixinError,
+                ) as e:
+                    self._parser.error(str(e))
             # apply the mixins in reverse order: since _update_args() handles
             # each mixin by prepending its list values, iterating in reverse
-            # makes the resulting list follow the order the mixins were given
-            # on the command line while keeping any explicit command line
-            for mixin in reversed(args.mixin or ()):
+            # makes the resulting list follow the computed application order
+            # while keeping any explicit command line arguments last
+            for mixin in reversed(application_order):
                 mixin_args = mixins[mixin]
                 logger.debug(
                     "Using mixin '{mixin}': {mixin_args}".format_map(locals()))
-                self._update_args(args, mixin_args, '.'.join(args.mixin_verb))
+                self._update_args(args, mixin_args, context)
 
         # undo default value wrapping injected in the add_argument() method
         for k, v in args.__dict__.items():
@@ -261,6 +278,10 @@ def _update_mixin_argument(self, argument, mixins):
     def _update_args(self, args, mixin_args, context):
         destinations = self.get_destinations()
         for mixin_key, mixin_value in mixin_args.items():
+            if mixin_key == 'mixin':
+                # reserved metadata key listing referenced mixins; it is not
+                # an argument to overlay (see colcon_mixin.mixin.order)
+                continue
             if mixin_key not in destinations:
                 logger.warning(
                     "Mixin key '{mixin_key}' is not a valid argument for "

colcon_mixin/mixin/order.py

@@ -0,0 +1,113 @@
+# Copyright 2026 C Innocent Pious
+# Licensed under the Apache License, Version 2.0
+
+"""Compute the application order of mixins which reference other mixins.
+
+A mixin definition may reference other mixins through a ``"mixin"`` key whose
+value is a list of other mixin names. Given a requested mixin and the mapping
+of all available mixins, :func:`compute_application_order` produces the ordered
+list of mixin names to apply using a depth-first, post-order traversal with
+re-application.
+
+The traversal model:
+
+* Depth-first -- follow each reference chain to its end before backing up.
+* Post-order -- record a mixin AFTER its referenced mixins, so dependencies
+  come first and the referencing mixin comes last and can override them.
+* Re-application -- nodes are NOT skipped when reached through multiple
+  paths; a shared mixin is applied once per path. This preserves correct
+  last-applied-wins override behavior.
+
+Cycle detection uses the active recursion path only (not a global visited
+set), so legitimate re-application is never mistaken for a cycle.
+
+This module only yields the order in which mixins should be applied; merging
+their arguments is a separate concern handled by the caller.
+"""
+
+
+class CircularMixinError(Exception):
+    """Raised when the mixin reference graph contains a cycle.
+
+    The message names the full cycle path, e.g. 'A -> B -> A'.
+    """
+
+
+class MissingMixinError(Exception):
+    """Raised when a referenced mixin name does not exist in the mixins."""
+
+
+class InvalidMixinError(Exception):
+    """Raised when a 'mixin' key is malformed (not a list of strings)."""
+
+
+def _read_references(mixins, name):
+    """Read and validate the references of a single mixin.
+
+    :param dict mixins: mapping of mixin name -> mixin definition.
+    :param str name: the mixin whose references should be read.
+    :returns: the list of referenced mixin names (empty if no 'mixin' key).
+    :rtype: list
+    :raises InvalidMixinError: if the 'mixin' key is not a list of strings.
+    """
+    refs = mixins[name].get('mixin', [])
+    if not isinstance(refs, list) or not all(
+        isinstance(ref, str) for ref in refs
+    ):
+        raise InvalidMixinError(
+            "Mixin '{name}' has an invalid 'mixin' key: expected a list of "
+            'strings'.format_map(locals()))
+    return refs
+
+
+def compute_application_order(mixins, requested):
+    """Compute the order in which mixins should be applied.
+
+    Performs a depth-first, post-order traversal of the mixin reference
+    graph, re-applying nodes on each encounter (no skipping of
+    already-visited nodes). Dependencies are ordered before the mixins that
+    reference them, so the requesting mixin appears last and can override its
+    dependencies.
+
+    :param dict mixins: mapping of mixin name -> mixin definition. A
+        definition is a dict that MAY contain a "mixin" key whose value is a
+        list of other mixin names it references. Definitions without a
+        "mixin" key have no references.
+    :param str requested: the name of the mixin the user requested.
+    :returns: list of mixin names in application order (may contain
+        duplicates).
+    :rtype: list
+    :raises CircularMixinError: if a circular reference is detected.
+    :raises MissingMixinError: if a referenced mixin does not exist.
+    :raises InvalidMixinError: if a "mixin" key is malformed.
+    """
+    order = []
+    # names currently on the active recursion path, used for cycle detection
+    stack_path = []
+
+    def visit(name, referrer):
+        if name not in mixins:
+            if referrer is None:
+                raise MissingMixinError(
+                    "Requested mixin '{name}' does not exist"
+                    .format_map(locals()))
+            raise MissingMixinError(
+                "Mixin '{referrer}' references unknown mixin '{name}'"
+                .format_map(locals()))
+
+        if name in stack_path:
+            path = ' -> '.join(stack_path + [name])
+            raise CircularMixinError(
+                'Circular mixin reference: {path}'.format_map(locals()))
+
+        refs = _read_references(mixins, name)
+
+        stack_path.append(name)
+        for ref in refs:  # left-to-right, user-listed order
+            visit(ref, name)  # depth-first
+        stack_path.pop()
+
+        order.append(name)  # POST-ORDER: record after references
+
+    visit(requested, None)
+    return order

test/test_mixin_argument.py

@@ -20,6 +20,28 @@
 }
 
 
+# a mixin referencing another mixin through the 'mixin' key
+NESTED_MIXINS = {
+    'base': {'cmake-args': ['FOO=BASE']},
+    'child': {'mixin': ['base'], 'cmake-args': ['FOO=CHILD']},
+}
+
+
+SCALAR_NESTED_MIXINS = {
+    'base': {'build-base': 'BASE'},
+    'child': {'mixin': ['base'], 'build-base': 'CHILD'},
+}
+
+
+# the canonical graph from the reference doc: A->[B,D], B->[C], C->[D]
+CANONICAL_MIXINS = {
+    'A': {'mixin': ['B', 'D'], 'cmake-args': ['A']},
+    'B': {'mixin': ['C'], 'cmake-args': ['B']},
+    'C': {'mixin': ['D'], 'cmake-args': ['C']},
+    'D': {'cmake-args': ['D']},
+}
+
+
 def _parse(argv, mixins=MIXINS):
     base = argparse.ArgumentParser(prog='colcon')
     decorator = MixinArgumentDecorator(base)
@@ -88,3 +110,45 @@ def test_unavailable_mixin_reports_first(capsys):
     with pytest.raises(SystemExit):
         _parse(['build', '--mixin', 'bad', 'a'])
     assert "Mixin 'bad' is not available" in capsys.readouterr().err
+
+
+def test_referenced_mixin_applied_before_referencing():
+    # 'child' references 'base'; the referenced mixin is applied first so its
+    # list values come before the referencing mixin's values
+    args = _parse(['build', '--mixin', 'child'], NESTED_MIXINS)
+    assert args.cmake_args == ['FOO=BASE', 'FOO=CHILD']
+
+
+def test_referencing_mixin_overrides_referenced_scalar():
+    # a scalar from the referencing mixin must win over its reference
+    args = _parse(['build', '--mixin', 'child'], SCALAR_NESTED_MIXINS)
+    assert args.build_base == 'CHILD'
+
+
+def test_canonical_reference_graph_order():
+    # the overlaid list follows the canonical [D, C, B, D, A] order
+    args = _parse(['build', '--mixin', 'A'], CANONICAL_MIXINS)
+    assert args.cmake_args == ['D', 'C', 'B', 'D', 'A']
+
+
+def test_nested_mixin_command_line_arguments_take_precedence():
+    args = _parse(
+        ['build', '--mixin', 'child', '--cmake-args=FOO=CLI'], NESTED_MIXINS)
+    assert args.cmake_args == ['FOO=BASE', 'FOO=CHILD', 'FOO=CLI']
+
+
+def test_circular_mixin_reference_reports_error(capsys):
+    mixins = {
+        'a': {'mixin': ['b']},
+        'b': {'mixin': ['a']},
+    }
+    with pytest.raises(SystemExit):
+        _parse(['build', '--mixin', 'a'], mixins)
+    assert 'Circular mixin reference' in capsys.readouterr().err
+
+
+def test_unknown_referenced_mixin_reports_error(capsys):
+    mixins = {'a': {'mixin': ['missing']}}
+    with pytest.raises(SystemExit):
+        _parse(['build', '--mixin', 'a'], mixins)
+    assert "unknown mixin 'missing'" in capsys.readouterr().err

test/test_order.py

@@ -0,0 +1,141 @@
+# Copyright 2026 C Innocent Pious
+# Licensed under the Apache License, Version 2.0
+
+"""Tests for the mixin application-order function."""
+
+from colcon_mixin.mixin.order import CircularMixinError
+from colcon_mixin.mixin.order import compute_application_order
+from colcon_mixin.mixin.order import InvalidMixinError
+from colcon_mixin.mixin.order import MissingMixinError
+import pytest
+
+
+def test_no_mixin_key():
+    mixins = {'A': {'cmake-args': ['-DA=1']}}
+    assert compute_application_order(mixins, 'A') == ['A']
+
+
+def test_empty_mixin_list():
+    mixins = {'A': {'mixin': [], 'cmake-args': ['-DA=1']}}
+    assert compute_application_order(mixins, 'A') == ['A']
+
+
+def test_single_reference():
+    mixins = {
+        'A': {'mixin': ['B']},
+        'B': {},
+    }
+    assert compute_application_order(mixins, 'A') == ['B', 'A']
+
+
+def test_two_references_order_preserved():
+    mixins = {
+        'A': {'mixin': ['B', 'C']},
+        'B': {},
+        'C': {},
+    }
+    assert compute_application_order(mixins, 'A') == ['B', 'C', 'A']
+
+
+def test_nested_chain():
+    mixins = {
+        'A': {'mixin': ['B']},
+        'B': {'mixin': ['C']},
+        'C': {'mixin': ['D']},
+        'D': {},
+    }
+    assert compute_application_order(mixins, 'A') == ['D', 'C', 'B', 'A']
+
+
+def test_canonical_example():
+    mixins = {
+        'A': {'mixin': ['B', 'D'], 'cmake-args': ['-DA=1']},
+        'B': {'mixin': ['C'], 'cmake-args': ['-DB=1']},
+        'C': {'mixin': ['D'], 'cmake-args': ['-DC=1']},
+        'D': {'cmake-args': ['-DD=1']},
+    }
+    assert compute_application_order(mixins, 'A') == \
+        ['D', 'C', 'B', 'D', 'A']
+
+
+def test_diamond_re_application():
+    # A references B and C; both reference D. D is shared but reached via two
+    # distinct, already-completed branches -> it appears once per path.
+    mixins = {
+        'A': {'mixin': ['B', 'C']},
+        'B': {'mixin': ['D']},
+        'C': {'mixin': ['D']},
+        'D': {},
+    }
+    order = compute_application_order(mixins, 'A')
+    assert order == ['D', 'B', 'D', 'C', 'A']
+    assert order.count('D') == 2
+
+
+def test_self_reference_cycle():
+    mixins = {'A': {'mixin': ['A']}}
+    with pytest.raises(CircularMixinError) as exc_info:
+        compute_application_order(mixins, 'A')
+    assert 'A -> A' in str(exc_info.value)
+
+
+def test_two_node_cycle():
+    mixins = {
+        'A': {'mixin': ['B']},
+        'B': {'mixin': ['A']},
+    }
+    with pytest.raises(CircularMixinError) as exc_info:
+        compute_application_order(mixins, 'A')
+    assert 'A -> B -> A' in str(exc_info.value)
+
+
+def test_three_node_cycle():
+    mixins = {
+        'A': {'mixin': ['B']},
+        'B': {'mixin': ['C']},
+        'C': {'mixin': ['A']},
+    }
+    with pytest.raises(CircularMixinError) as exc_info:
+        compute_application_order(mixins, 'A')
+    assert 'A -> B -> C -> A' in str(exc_info.value)
+
+
+def test_missing_referenced_mixin():
+    mixins = {'A': {'mixin': ['B']}}
+    with pytest.raises(MissingMixinError) as exc_info:
+        compute_application_order(mixins, 'A')
+    assert "'A'" in str(exc_info.value)
+    assert "'B'" in str(exc_info.value)
+
+
+def test_malformed_mixin_string_not_list():
+    mixins = {'A': {'mixin': 'B'}}
+    with pytest.raises(InvalidMixinError):
+        compute_application_order(mixins, 'A')
+
+
+def test_malformed_mixin_list_with_non_string():
+    mixins = {
+        'A': {'mixin': ['B', 1]},
+        'B': {},
+    }
+    with pytest.raises(InvalidMixinError):
+        compute_application_order(mixins, 'A')
+
+
+def test_requested_mixin_not_in_dict():
+    mixins = {'A': {}}
+    with pytest.raises(MissingMixinError):
+        compute_application_order(mixins, 'Z')
+
+
+def test_mixin_key_never_in_output():
+    mixins = {
+        'A': {'mixin': ['B', 'D']},
+        'B': {'mixin': ['C']},
+        'C': {'mixin': ['D']},
+        'D': {},
+    }
+    order = compute_application_order(mixins, 'A')
+    assert 'mixin' not in order
+    assert set(order) <= set(mixins.keys())