From df1aa9d61c7976e1192753e9d8ffb0877e30172d Mon Sep 17 00:00:00 2001
From: Jochen Hoenle <173445474+hoe-jo@users.noreply.github.com>
Date: Tue, 22 Sep 2026 11:30:34 +0200
Subject: [PATCH] [plantuml resolver] warn on ambiguous fqns

---
 .../invalid_ambiguous_root_vs_relative.puml   | 29 +++++++++++++++++++
 .../output.yaml                               | 18 ++++++++++++
 .../src/component_resolver.rs                 | 11 +++++++
 .../tests/component_resolver_test.rs          |  5 ++++
 4 files changed, 63 insertions(+)
 create mode 100644 plantuml/parser/integration_test/component_diagram/invalid_ambiguous_root_vs_relative/invalid_ambiguous_root_vs_relative.puml
 create mode 100644 plantuml/parser/integration_test/component_diagram/invalid_ambiguous_root_vs_relative/output.yaml

diff --git a/plantuml/parser/integration_test/component_diagram/invalid_ambiguous_root_vs_relative/invalid_ambiguous_root_vs_relative.puml b/plantuml/parser/integration_test/component_diagram/invalid_ambiguous_root_vs_relative/invalid_ambiguous_root_vs_relative.puml
new file mode 100644
index 00000000..dd918cd0
--- /dev/null
+++ b/plantuml/parser/integration_test/component_diagram/invalid_ambiguous_root_vs_relative/invalid_ambiguous_root_vs_relative.puml
@@ -0,0 +1,29 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+@startuml
+
+component "a" as a <<component>> {
+    component "B" as B <<unit>>
+}
+
+component "x" as x <<component>>
+
+package "pkg" as pkg #LightBlue {
+    component "a" as a <<component>> {
+        component "B" as B <<unit>>
+    }
+
+    x --> a.B : ambiguous
+}
+
+@enduml
diff --git a/plantuml/parser/integration_test/component_diagram/invalid_ambiguous_root_vs_relative/output.yaml b/plantuml/parser/integration_test/component_diagram/invalid_ambiguous_root_vs_relative/output.yaml
new file mode 100644
index 00000000..18d5ad5c
--- /dev/null
+++ b/plantuml/parser/integration_test/component_diagram/invalid_ambiguous_root_vs_relative/output.yaml
@@ -0,0 +1,18 @@
+# *******************************************************************************
+# Copyright (c) 2026 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+invalid_ambiguous_root_vs_relative.puml:
+  error:
+    type: "AmbiguousReference"
+    fields:
+      reference: "a.B"
+      candidates: "a.B, pkg.a.B"
diff --git a/plantuml/parser/puml_resolver/src/component_diagram/src/component_resolver.rs b/plantuml/parser/puml_resolver/src/component_diagram/src/component_resolver.rs
index 58ec644d..24a4233e 100644
--- a/plantuml/parser/puml_resolver/src/component_diagram/src/component_resolver.rs
+++ b/plantuml/parser/puml_resolver/src/component_diagram/src/component_resolver.rs
@@ -334,6 +334,17 @@ impl ComponentResolver {
 
         // 2. relative qualified name
         if let Some(res) = self.resolve_relative(&parts)? {
+            // A distinct top-level element can also match the literal text;
+            // silently preferring the scope-relative hit would shadow it.
+            let absolute_fqn = parts.join(".");
+            if absolute_fqn != res && self.elements.contains_key(&absolute_fqn) {
+                let mut candidates = vec![res, absolute_fqn];
+                candidates.sort();
+                return Err(ComponentResolverError::AmbiguousReference {
+                    reference: raw.to_string(),
+                    candidates,
+                });
+            }
             return Ok(res);
         }
 
diff --git a/plantuml/parser/puml_resolver/src/component_diagram/tests/component_resolver_test.rs b/plantuml/parser/puml_resolver/src/component_diagram/tests/component_resolver_test.rs
index 99f044a6..87550604 100644
--- a/plantuml/parser/puml_resolver/src/component_diagram/tests/component_resolver_test.rs
+++ b/plantuml/parser/puml_resolver/src/component_diagram/tests/component_resolver_test.rs
@@ -119,6 +119,11 @@ fn test_invalid_ambiguous_reference_element_alias() {
     run_component_resolver_case("invalid_ambiguous_reference_element_alias");
 }
 
+#[test]
+fn test_invalid_ambiguous_root_vs_relative() {
+    run_component_resolver_case("invalid_ambiguous_root_vs_relative");
+}
+
 #[test]
 fn test_invalid_duplicate_component() {
     run_component_resolver_case("invalid_duplicate_component");