Apply referenced mixins in parse_args

Expand each requested mixin into its full application order using
colcon_mixin.mixin.order and apply the result in reverse, so the
prepend-based overlay produces the computed order while explicit command
line arguments keep precedence. A referencing mixin is applied
conceptually last and can override values inherited from its references.
Skip the reserved 'mixin' key during overlay since it is metadata, not
an argument. Report circular, unknown and malformed references as clean
CLI errors. Mixins without a 'mixin' key behave exactly as before.

Add parser integration tests covering nested references, scalar
overrides, command line precedence and error reporting.

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

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 "

test/test_mixin_argument.py

@@ -20,6 +20,26 @@
 }
 
 
+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'},
+}
+
+
+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 +108,42 @@ 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():
+    args = _parse(['build', '--mixin', 'child'], NESTED_MIXINS)
+    assert args.cmake_args == ['FOO=BASE', 'FOO=CHILD']
+
+
+def test_referencing_mixin_overrides_referenced_scalar():
+    args = _parse(['build', '--mixin', 'child'], SCALAR_NESTED_MIXINS)
+    assert args.build_base == 'CHILD'
+
+
+def test_canonical_reference_graph_order():
+    # D appears twice, once per path
+    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