From 93a54b0f704895281b060111152a55e3875dea70 Mon Sep 17 00:00:00 2001 From: DerManoMann Date: Wed, 30 Sep 2026 17:17:56 +1300 Subject: [PATCH] fix(Assembler): say what to do about an ambiguous merge The message named the problem and stopped there. An author who stacks a header beside two responses is told their attribute matches multiple siblings, which is accurate and leaves them nowhere: the resolutions are to nest it in the one it belongs to, or to give it a `component` and reference it from each, and neither is obvious from the wording. Found migrating a real codebase, where this is the single reason a converted project loses most of its paths, and where it fires ten times in twenty-two files. It is not a migration-specific problem though -- the same message reaches anyone writing spec attributes by hand -- so the hint belongs in the diagnostic rather than in a migration guide. `AttributeFactoryTest` matches the message by pattern, so it still holds. --- src/Utils/AttributeFactory.php | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/Utils/AttributeFactory.php b/src/Utils/AttributeFactory.php index d5796194d..4436924cd 100644 --- a/src/Utils/AttributeFactory.php +++ b/src/Utils/AttributeFactory.php @@ -396,7 +396,10 @@ protected function mergeIntoSibling(array $attributes, int $index, array &$merge if ($candidate instanceof $targetClass) { if ($matchingTarget instanceof AttributeInterface) { throw OpenApiException::fromSource( - sprintf('Ambiguous merge: %s matches multiple siblings on the same target', $attribute::class), + sprintf( + 'Ambiguous merge: %s matches multiple siblings on the same target. Nest it explicitly in the one it belongs to, or give it a `component` and reference it from each.', + $attribute::class + ), $attribute->getSourceLocation(), ); }