Add mixin composition support (colcon-mixin#39)

Allow mixins to reference other mixins via a 'mixin' key containing a
list of mixin names. Referenced mixins are resolved recursively with
cycle detection, and their arguments are merged left-to-right before
the composing mixin's own arguments are applied on top.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: ArizmendiWan <2311602492@qq.com>

Author: ArizmendiWan

colcon_mixin/mixin/__init__.py

@@ -125,3 +125,60 @@ def add_mixins(mixin_path, mixins_by_verb):
                     'with the same name' %
                     (name, mixin_path.absolute()))
             mixins_by_verb[verb_key][name] = args
+
+
+def resolve_mixin(verb_key, mixin_name, mixins_by_verb, _resolving=None):
+    """
+    Resolve a mixin by flattening its composed references.
+
+    Referenced mixins are resolved left-to-right, then the mixin's own
+    arguments are merged on top. Precedence matches the CLI behavior of
+    _update_args: lists use prepending order, first scalar wins between
+    references, own scalars always override.
+
+    :param tuple verb_key: The verb tuple
+    :param str mixin_name: The name of the mixin to resolve
+    :param dict mixins_by_verb: The full mixin collection
+    :param set _resolving: Internal set for cycle detection
+    :raises RuntimeError: On cycles or missing references
+    :rtype: dict
+    """
+    if _resolving is None:
+        _resolving = set()
+
+    verb_mixins = mixins_by_verb.get(verb_key, {})
+    if mixin_name not in verb_mixins:
+        raise RuntimeError(
+            "Mixin '%s' referenced in composition does not exist for "
+            "verb '%s'" % (mixin_name, '.'.join(verb_key)))
+
+    if mixin_name in _resolving:
+        raise RuntimeError(
+            'Cycle detected in mixin composition: %s' % mixin_name)
+
+    mixin_def = verb_mixins[mixin_name]
+    refs = mixin_def.get('mixin', [])
+    if not isinstance(refs, list):
+        refs = []
+
+    _resolving.add(mixin_name)
+    resolved = {}
+    for ref in refs:
+        ref_args = resolve_mixin(verb_key, ref, mixins_by_verb, _resolving)
+        for k, v in ref_args.items():
+            if k not in resolved:
+                resolved[k] = v
+            elif isinstance(resolved[k], list) and isinstance(v, list):
+                resolved[k] = v + resolved[k]
+    _resolving.discard(mixin_name)
+
+    for k, v in mixin_def.items():
+        if k == 'mixin':
+            continue
+        if k not in resolved:
+            resolved[k] = v
+        elif isinstance(resolved[k], list) and isinstance(v, list):
+            resolved[k] = v + resolved[k]
+        else:
+            resolved[k] = v
+    return resolved

colcon_mixin/mixin/mixin_argument.py

@@ -24,6 +24,7 @@
 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 import resolve_mixin
 
 logger = colcon_logger.getChild(__name__)
 
@@ -187,7 +188,11 @@ def collect_parsers_by_verb(root, parsers, parent_verbs=()):
                     self._parser.error(
                         "Mixin '{mixin}' is not available for '{context}'"
                         .format_map(locals()))
-                mixin_args = mixins[mixin]
+                try:
+                    mixin_args = resolve_mixin(
+                        args.mixin_verb, mixin, mixins_by_verb)
+                except RuntimeError as e:
+                    self._parser.error(str(e))
                 logger.debug(
                     "Using mixin '{mixin}': {mixin_args}".format_map(locals()))
                 self._update_args(args, mixin_args, '.'.join(args.mixin_verb))

test/test_mixin_composition.py

@@ -0,0 +1,98 @@
+# Copyright 2026 Open Robotics
+# Licensed under the Apache License, Version 2.0
+
+from collections import defaultdict
+
+from colcon_mixin.mixin import resolve_mixin
+import pytest
+
+
+def _make_mixins(mixin_dict):
+    """Build a mixins_by_verb dict for verb ('build',)."""
+    mbv = defaultdict(dict)
+    mbv[('build',)] = dict(mixin_dict)
+    return mbv
+
+
+def test_resolve_no_composition():
+    """Mixin without a 'mixin' key returns its args unchanged."""
+    mbv = _make_mixins({
+        'debug': {'args': ['--flag-a']},
+    })
+    result = resolve_mixin(('build',), 'debug', mbv)
+    assert result == {'args': ['--flag-a']}
+
+
+def test_resolve_simple():
+    """Mixin referencing another gets the referenced args plus its own."""
+    mbv = _make_mixins({
+        'base': {'args': ['--flag-a']},
+        'composed': {
+            'mixin': ['base'],
+            'build-base': '/tmp/build',
+        },
+    })
+    result = resolve_mixin(('build',), 'composed', mbv)
+    assert result == {
+        'args': ['--flag-a'],
+        'build-base': '/tmp/build',
+    }
+
+
+def test_resolve_list_concatenation():
+    """List args use prepending order, matching CLI --mixin."""
+    mbv = _make_mixins({
+        'base': {'args': ['--flag-a']},
+        'extra': {
+            'mixin': ['base'],
+            'args': ['--flag-b'],
+        },
+    })
+    result = resolve_mixin(('build',), 'extra', mbv)
+    # own args go first, matching _update_args behavior
+    assert result == {
+        'args': ['--flag-b', '--flag-a'],
+    }
+
+
+def test_resolve_scalar_own_overrides_ref():
+    """Own scalar args override referenced mixin's scalar args."""
+    mbv = _make_mixins({
+        'base': {'build-base': '/tmp/base'},
+        'override': {
+            'mixin': ['base'],
+            'build-base': '/tmp/override',
+        },
+    })
+    result = resolve_mixin(('build',), 'override', mbv)
+    assert result == {'build-base': '/tmp/override'}
+
+
+def test_resolve_scalar_first_ref_wins():
+    """Between references, first scalar wins (matches CLI behavior)."""
+    mbv = _make_mixins({
+        'a': {'build-base': '/from-a'},
+        'b': {'build-base': '/from-b'},
+        'composed': {'mixin': ['a', 'b']},
+    })
+    result = resolve_mixin(('build',), 'composed', mbv)
+    assert result == {'build-base': '/from-a'}
+
+
+def test_resolve_cycle_detection():
+    """Cyclic references raise RuntimeError."""
+    mbv = _make_mixins({
+        'a': {'mixin': ['b'], 'x': 1},
+        'b': {'mixin': ['a'], 'y': 2},
+    })
+    with pytest.raises(RuntimeError, match='Cycle detected'):
+        resolve_mixin(('build',), 'a', mbv)
+
+
+def test_resolve_missing_reference():
+    """Reference to a non-existent mixin raises RuntimeError."""
+    mbv = _make_mixins({
+        'broken': {'mixin': ['nonexistent']},
+    })
+    with pytest.raises(RuntimeError, match='does not exist'):
+        resolve_mixin(('build',), 'broken', mbv)