Show the application order for mixins referencing other mixins

Print an additional 'application order' line for every mixin which
references other mixins through a 'mixin' key, so the resolved
composition is visible without following the references by hand. The
order is computed with colcon_mixin.mixin.order and therefore matches
the order which is applied at build time.

Circular, unknown and malformed references are reported inline as
'unavailable (<reason>)' rather than raised, so the remaining mixins are
still being shown. Mixins which don't reference other mixins are shown
exactly as before.

Add tests covering the added line and its indentation in both the list
and the single mixin output, its absence for mixins without references
and for an empty reference list, re-application through several paths
and the three error cases.

Author: PiousCrossten

colcon_mixin/subverb/show.py

@@ -3,9 +3,35 @@
 
 from colcon_core.plugin_system import satisfies_version
 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
 from colcon_mixin.subverb import MixinSubverbExtensionPoint
 
 
+def _get_application_order(mixins, mixin_name):
+    """
+    Get the order in which a mixin and the mixins it references are applied.
+
+    :param dict mixins: The mixins of a single verb
+    :param str mixin_name: The name of the mixin to resolve
+    :returns: The application order joined by arrows, or None if the mixin
+      doesn't reference any other mixins
+    :rtype: str
+    """
+    if not mixins[mixin_name].get('mixin'):
+        return None
+    try:
+        order = compute_application_order(mixins, mixin_name)
+    except (CircularMixinError, InvalidMixinError, MissingMixinError) as e:
+        # an unresolvable reference is reported here rather than raised, so
+        # that the remaining mixins are still being shown
+        reason = str(e)
+        return 'unavailable ({reason})'.format_map(locals())
+    return ' -> '.join(order)
+
+
 def _get_mixin_name_completer(verb_key, mixins_by_verb):
     def mixin_name_completer(prefix, **kwargs):
         """Callable returning a list of mixin names."""
@@ -71,8 +97,15 @@ def main(self, *, context):  # noqa: D102
                 else:
                     print('- {mixin_name}'.format_map(locals()))
                 mixin_value = mixins[mixin_name]
+                indent = '  ' if context.args.mixin_name is None else ''
                 for arg_key, arg_value in mixin_value.items():
-                    indent = '  ' if context.args.mixin_name is None else ''
                     print(
                         '{indent}{arg_key}: {arg_value}'
                         .format_map(locals()))
+                # only shown for mixins referencing other mixins, to make the
+                # resolved order of the composition visible
+                application_order = _get_application_order(mixins, mixin_name)
+                if application_order is not None:
+                    print(
+                        '{indent}application order: {application_order}'
+                        .format_map(locals()))

test/test_show.py

@@ -0,0 +1,135 @@
+# Copyright 2026 Innocent Pious
+# Licensed under the Apache License, Version 2.0
+
+"""Tests for the output of the mixin show subverb."""
+
+import argparse
+from unittest.mock import patch
+
+from colcon_mixin.subverb.show import ShowMixinSubverb
+
+
+REFERENCING_MIXINS = {
+    ('build', ): {
+        'base': {'cmake-args': ['-DA=1']},
+        'debug': {'mixin': ['base'], 'cmake-args': ['-DB=1']},
+        'strict': {'mixin': ['debug'], 'cmake-args': ['-DC=1']},
+    },
+}
+
+
+PLAIN_MIXINS = {
+    ('build', ): {
+        'debug': {'cmake-args': ['-DB=1']},
+        'release': {'cmake-args': ['-DD=1']},
+    },
+}
+
+
+def _show(capsys, mixins_by_verb, verb=None, mixin_name=None):
+    with patch(
+        'colcon_mixin.subverb.show.get_mixins', return_value=mixins_by_verb
+    ):
+        extension = ShowMixinSubverb()
+        extension.add_arguments(parser=argparse.ArgumentParser())
+    context = argparse.Namespace(
+        args=argparse.Namespace(verb=verb, mixin_name=mixin_name))
+    rc = extension.main(context=context)
+    return capsys.readouterr().out.splitlines(), rc
+
+
+def test_application_order_for_referencing_mixins(capsys):
+    lines, rc = _show(capsys, REFERENCING_MIXINS)
+    assert rc is None
+    assert lines == [
+        'build:',
+        '- base',
+        "  cmake-args: ['-DA=1']",
+        '- debug',
+        "  mixin: ['base']",
+        "  cmake-args: ['-DB=1']",
+        '  application order: base -> debug',
+        '- strict',
+        "  mixin: ['debug']",
+        "  cmake-args: ['-DC=1']",
+        '  application order: base -> debug -> strict',
+    ]
+
+
+def test_no_application_order_without_references(capsys):
+    # mixins which don't reference others are shown as before
+    lines, _ = _show(capsys, PLAIN_MIXINS)
+    assert lines == [
+        'build:',
+        '- debug',
+        "  cmake-args: ['-DB=1']",
+        '- release',
+        "  cmake-args: ['-DD=1']",
+    ]
+
+
+def test_no_application_order_for_empty_reference_list(capsys):
+    mixins = {('build', ): {'a': {'mixin': [], 'cmake-args': ['-DA=1']}}}
+    lines, _ = _show(capsys, mixins)
+    assert not any('application order' in line for line in lines)
+
+
+def test_application_order_for_single_mixin_is_not_indented(capsys):
+    lines, _ = _show(
+        capsys, REFERENCING_MIXINS, verb='build', mixin_name='strict')
+    assert lines == [
+        "mixin: ['debug']",
+        "cmake-args: ['-DC=1']",
+        'application order: base -> debug -> strict',
+    ]
+
+
+def test_application_order_repeats_mixins_reached_twice(capsys):
+    mixins = {
+        ('build', ): {
+            'a': {'mixin': ['b', 'c']},
+            'b': {'mixin': ['d']},
+            'c': {'mixin': ['d']},
+            'd': {},
+        },
+    }
+    lines, _ = _show(capsys, mixins, verb='build', mixin_name='a')
+    assert 'application order: d -> b -> d -> c -> a' in lines
+
+
+def test_missing_reference_is_reported_inline(capsys):
+    mixins = {
+        ('build', ): {
+            'broken': {'mixin': ['nope']},
+            'fine': {'cmake-args': ['-DA=1']},
+        },
+    }
+    lines, rc = _show(capsys, mixins)
+    assert rc is None
+    order_line = [x for x in lines if 'application order' in x][0]
+    assert 'unavailable' in order_line
+    assert "unknown mixin 'nope'" in order_line
+    # the remaining mixins are still being shown
+    assert '- fine' in lines
+
+
+def test_circular_reference_is_reported_inline(capsys):
+    mixins = {
+        ('build', ): {
+            'a': {'mixin': ['b']},
+            'b': {'mixin': ['a']},
+        },
+    }
+    lines, rc = _show(capsys, mixins)
+    assert rc is None
+    assert '  application order: unavailable (Circular mixin reference: ' \
+        'a -> b -> a)' in lines
+
+
+def test_invalid_reference_key_is_reported_inline(capsys):
+    mixins = {('build', ): {'a': {'mixin': 'b'}, 'b': {}}}
+    lines, rc = _show(capsys, mixins)
+    assert rc is None
+    order_line = [x for x in lines if 'application order' in x][0]
+    assert 'unavailable' in order_line
+    assert 'expected a list of strings' in order_line