From 5fe34a6813a022ddc1f06f462f10f0b42cee194b Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Fri, 14 Aug 2026 11:11:55 +0200
Subject: [PATCH 1/2] fix(lineage): surface the ambiguity warning on the
 diagram surfaces too (#584)

#579 gave `lineage show` and the JSON routes an ambiguity warning, but the
mermaid renderer had no way to carry one: a diagram has no metadata channel,
so all three callers dropped it. A Web UI or --format mermaid user therefore
still got one project's answer looking like the whole picture -- the exact
shape of #568, just on a different surface.

render_mermaid now takes an optional `warnings` list and emits each as a
standalone, deliberately unconnected note node, styled as a warning so it does
not read as part of the dependency graph. All three callers pass what the query
result carries: the CLI's --format mermaid/html, the `lineage server` browser,
and GET /lineage/mermaid. Warnings go through the same label escaping as every
other API-derived string (issue #269 sec-05), covered by a test.

Also removes _find_node, which #579 left behind with no callers. Leaving it
invites a future caller to bypass candidate resolution entirely, which is the
bug #568 reported.
---
 src/keboola_agent_cli/commands/lineage.py     |  5 ++-
 .../server/routers/lineage.py                 |  2 +-
 .../services/deep_lineage_service.py          | 18 +++++++--
 tests/test_deep_lineage_service.py            | 40 +++++++++++++++++++
 4 files changed, 59 insertions(+), 6 deletions(-)

diff --git a/src/keboola_agent_cli/commands/lineage.py b/src/keboola_agent_cli/commands/lineage.py
index 9350f1c8..730571f6 100644
--- a/src/keboola_agent_cli/commands/lineage.py
+++ b/src/keboola_agent_cli/commands/lineage.py
@@ -401,7 +401,9 @@ def _output_mermaid_or_html(
         typer.echo(er_code)
         return
 
-    mermaid_code = DeepLineageService.render_mermaid(edges, graph, direction, node_fqn)
+    mermaid_code = DeepLineageService.render_mermaid(
+        edges, graph, direction, node_fqn, warnings=query_result.get("warnings")
+    )
 
     if output_format == "mermaid":
         typer.echo(mermaid_code)
@@ -1368,6 +1370,7 @@ def _handle_mermaid(self, parsed) -> None:
                 direction,
                 node,
                 show_columns=show_cols,
+                warnings=result.get("warnings"),
             )
         self._serve(mermaid_code, "text/plain")
 
diff --git a/src/keboola_agent_cli/server/routers/lineage.py b/src/keboola_agent_cli/server/routers/lineage.py
index 138ab615..c46f57a2 100644
--- a/src/keboola_agent_cli/server/routers/lineage.py
+++ b/src/keboola_agent_cli/server/routers/lineage.py
@@ -221,6 +221,6 @@ def mermaid(
         code = DeepLineageService.render_er_diagram(edges, graph, node, show_columns=show_cols)
     else:
         code = DeepLineageService.render_mermaid(
-            edges, graph, direction, node, show_columns=show_cols
+            edges, graph, direction, node, show_columns=show_cols, warnings=result.get("warnings")
         )
     return PlainTextResponse(code)
diff --git a/src/keboola_agent_cli/services/deep_lineage_service.py b/src/keboola_agent_cli/services/deep_lineage_service.py
index 85e579b8..f7394e19 100644
--- a/src/keboola_agent_cli/services/deep_lineage_service.py
+++ b/src/keboola_agent_cli/services/deep_lineage_service.py
@@ -1063,10 +1063,6 @@ def _graph_from_dict(data: dict) -> LineageGraph:
             )
         return graph
 
-    def _find_node(self, graph: LineageGraph, identifier: str, project: str = "") -> str | None:
-        candidates = self._find_node_candidates(graph, identifier, project)
-        return candidates[0] if candidates else None
-
     def _find_node_candidates(
         self, graph: LineageGraph, identifier: str, project: str = ""
     ) -> list[str]:
@@ -1120,6 +1116,7 @@ def render_mermaid(
         direction: str,
         node_fqn: str,
         show_columns: bool = False,
+        warnings: list[str] | None = None,
     ) -> str:
         """Render lineage edges as a mermaid flowchart.
 
@@ -1129,6 +1126,12 @@ def render_mermaid(
             direction: "upstream" or "downstream".
             node_fqn: The FQN of the queried node.
             show_columns: If True, include column names in table labels.
+            warnings: Non-fatal notes to render into the diagram itself,
+                typically the ambiguity warning from an unqualified id (#568).
+                A diagram carries no metadata channel the way the JSON shapes
+                do, so a caller that has warnings and drops them leaves the
+                viewer with one project's answer looking like the whole
+                picture -- which is the bug, not a cosmetic omission.
 
         Returns:
             Mermaid flowchart source code.
@@ -1139,6 +1142,13 @@ def render_mermaid(
         graph_dir = "RL" if direction == "upstream" else "LR"
         lines: list[str] = [f"graph {graph_dir}"]
 
+        # Standalone nodes -- deliberately unconnected, so they read as a note
+        # on the diagram rather than as part of the dependency graph.
+        for index, warning in enumerate(warnings or []):
+            warning_id = f"kbagentNote{index}"
+            lines.append(f'  {warning_id}["⚠ {escape(warning)}"]')
+            lines.append(f"  style {warning_id} fill:#fff3cd,stroke:#856404,color:#856404")
+
         # Determine the root node's project for cross-project detection
         root_project = node_fqn.split(":")[0] if ":" in node_fqn else ""
 
diff --git a/tests/test_deep_lineage_service.py b/tests/test_deep_lineage_service.py
index ac529a42..baacc250 100644
--- a/tests/test_deep_lineage_service.py
+++ b/tests/test_deep_lineage_service.py
@@ -683,6 +683,46 @@ def test_name_only_match_suggests_a_retry_that_resolves(self, tmp_path: Path) ->
         assert "error" not in retry
         assert retry["node"] == suggested
 
+    def test_mermaid_carries_the_warning_into_the_diagram(self, tmp_path: Path) -> None:
+        """A diagram has no metadata channel, so the note has to be a node (#584)."""
+        service = self._service(tmp_path)
+        graph = _shared_table_graph()
+        result = service.query_downstream(graph, SHARED_TABLE)
+
+        code = DeepLineageService.render_mermaid(
+            result["edges"],
+            graph,
+            "downstream",
+            result["node"],
+            warnings=result.get("warnings"),
+        )
+
+        assert "kbagentNote0" in code
+        assert "2 projects" in code
+        # Standalone: the note must not become part of the dependency graph.
+        assert "kbagentNote0 --" not in code and "--> kbagentNote0" not in code
+
+    def test_mermaid_without_warnings_gains_no_note(self, tmp_path: Path) -> None:
+        service = self._service(tmp_path)
+        graph = _shared_table_graph()
+        result = service.query_downstream(graph, f"beta:{SHARED_TABLE}")
+
+        code = DeepLineageService.render_mermaid(
+            result["edges"], graph, "downstream", result["node"], warnings=result.get("warnings")
+        )
+
+        assert "kbagentNote" not in code
+
+    def test_mermaid_warning_is_escaped(self) -> None:
+        """Warnings reach the diagram as text; sec-05 escaping must apply to them too."""
+        code = DeepLineageService.render_mermaid(
+            [], LineageGraph(), "downstream", "alpha:in.c-a.t", warnings=['<script>"x"</script>']
+        )
+
+        assert "<script>" not in code
+        assert "&lt;script&gt;" in code
+        assert "&quot;x&quot;" in code
+
     def test_unknown_identifier_still_errors(self, tmp_path: Path) -> None:
         service = self._service(tmp_path)
         result = service.query_downstream(_shared_table_graph(), "in.c-nope.missing")

From 5376ef0e4b80e7f67a97a1584d93221a217ab12d Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Fri, 14 Aug 2026 11:41:37 +0200
Subject: [PATCH 2/2] fix(lineage): carry the warning into the ER view, drop
 angle brackets from it

Two follow-ups from review of the flowchart fix.

render_er_diagram had no warnings channel either, so the ER view dropped the
note on both HTTP surfaces (the CLI's --format er was covered only because the
warning goes to stderr before rendering). erDiagram has no free-standing
annotation, so the notes ride as one relationship-less "note" entity; existing
html.escape(quote=True) neutralises the quotes that would otherwise terminate
the attribute comment.

Rendering the diagrams in a real browser then showed the remedy losing its
most important part: '--upstream/--downstream <project>:id' came out as
'--upstream/--downstream :id'. Escaping is correct and holds -- mermaid
renders the escaped entity back into SVG text as a literal <project>, which
the browser drops as an unknown tag. It looks right in a terminal and passes
every string assertion, and is wrong only where a user reads it. The
placeholder is now PROJECT:, with a test asserting warning text stays free of
angle brackets.
---
 src/keboola_agent_cli/commands/lineage.py     |  5 +-
 .../server/routers/lineage.py                 |  4 +-
 .../services/deep_lineage_service.py          | 28 ++++++++-
 tests/test_deep_lineage_service.py            | 62 ++++++++++++++++++-
 4 files changed, 94 insertions(+), 5 deletions(-)

diff --git a/src/keboola_agent_cli/commands/lineage.py b/src/keboola_agent_cli/commands/lineage.py
index 730571f6..b6b08043 100644
--- a/src/keboola_agent_cli/commands/lineage.py
+++ b/src/keboola_agent_cli/commands/lineage.py
@@ -397,7 +397,9 @@ def _output_mermaid_or_html(
     edges = query_result.get("edges", [])
 
     if output_format == "er":
-        er_code = DeepLineageService.render_er_diagram(edges, graph, node_fqn)
+        er_code = DeepLineageService.render_er_diagram(
+            edges, graph, node_fqn, warnings=query_result.get("warnings")
+        )
         typer.echo(er_code)
         return
 
@@ -1362,6 +1364,7 @@ def _handle_mermaid(self, parsed) -> None:
                 self.graph,
                 node,
                 show_columns=show_cols,
+                warnings=result.get("warnings"),
             )
         else:
             mermaid_code = DeepLineageService.render_mermaid(
diff --git a/src/keboola_agent_cli/server/routers/lineage.py b/src/keboola_agent_cli/server/routers/lineage.py
index c46f57a2..fe08b70d 100644
--- a/src/keboola_agent_cli/server/routers/lineage.py
+++ b/src/keboola_agent_cli/server/routers/lineage.py
@@ -218,7 +218,9 @@ def mermaid(
     edges = result.get("edges", [])
     show_cols = columns == "true"
     if view == "er":
-        code = DeepLineageService.render_er_diagram(edges, graph, node, show_columns=show_cols)
+        code = DeepLineageService.render_er_diagram(
+            edges, graph, node, show_columns=show_cols, warnings=result.get("warnings")
+        )
     else:
         code = DeepLineageService.render_mermaid(
             edges, graph, direction, node, show_columns=show_cols, warnings=result.get("warnings")
diff --git a/src/keboola_agent_cli/services/deep_lineage_service.py b/src/keboola_agent_cli/services/deep_lineage_service.py
index f7394e19..92e38db9 100644
--- a/src/keboola_agent_cli/services/deep_lineage_service.py
+++ b/src/keboola_agent_cli/services/deep_lineage_service.py
@@ -393,8 +393,15 @@ def _ambiguity_warning(identifier: str, candidates: list[str]) -> str:
     ``_find_node_candidates``, which matches a bare table name across buckets:
     those candidates can share a single project, so counting them as projects
     would tell the user a table "exists in 2 projects (alpha, alpha)", and
-    ``<project>:<identifier>`` would not resolve because the real node ids
+    ``PROJECT:<identifier>`` would not resolve because the real node ids
     carry a bucket. That case gets the full ids instead.
+
+    The placeholder is spelled ``PROJECT``, not ``<project>``: this text also
+    reaches the mermaid diagrams, where it is rendered into SVG. Mermaid turns
+    the escaped entity back into a literal ``<project>``, which the browser
+    then swallows as an unknown tag -- the remedy silently loses the very part
+    that makes it actionable. Escaping is correct and holds; the loss happens
+    one layer further on, so keep angle brackets out of warning text (#584).
     """
     shown = candidates[0]
     if all(fqn.partition(":")[2] == identifier for fqn in candidates):
@@ -403,7 +410,7 @@ def _ambiguity_warning(identifier: str, candidates: list[str]) -> str:
             f"'{identifier}' exists in {len(projects)} projects "
             f"({_format_candidates(projects)}); showing '{shown}' only. "
             f"Query a specific one with '--upstream/--downstream "
-            f"<project>:{identifier}' or scope with --project."
+            f"PROJECT:{identifier}' or scope with --project."
         )
     return (
         f"'{identifier}' matches {len(candidates)} nodes "
@@ -1212,14 +1219,31 @@ def render_er_diagram(
         graph: LineageGraph,
         node_fqn: str,
         show_columns: bool = False,
+        warnings: list[str] | None = None,
     ) -> str:
         """Render lineage as a mermaid ER diagram.
 
         Without show_columns: entities with name/row count + relationships.
         With show_columns: full column list with PK markers and AI mappings.
+
+        ``warnings`` carries non-fatal notes -- the ambiguity warning of #568,
+        typically. ``erDiagram`` has no free-standing annotation the way a
+        flowchart does, and the HTTP surfaces return this as plain text with
+        no metadata channel, so the notes ride as one relationship-less entity.
+        Dropping them would leave an ER viewer with one project's answer
+        looking like the whole picture, which is the bug itself (#584).
         """
         lines: list[str] = ["erDiagram"]
 
+        if warnings:
+            lines.append('    "⚠ note" {')
+            for index, warning in enumerate(warnings, start=1):
+                # html.escape(quote=True) also neutralises the double quotes
+                # that would otherwise terminate the attribute comment.
+                attribute = "warning" if len(warnings) == 1 else f"warning_{index}"
+                lines.append(f'        string {attribute} "{html.escape(warning, quote=True)}"')
+            lines.append("    }")
+
         # Collect all table FQNs and their column mappings
         table_fqns: set[str] = set()
         config_fqns: set[str] = set()
diff --git a/tests/test_deep_lineage_service.py b/tests/test_deep_lineage_service.py
index baacc250..e8d96b08 100644
--- a/tests/test_deep_lineage_service.py
+++ b/tests/test_deep_lineage_service.py
@@ -676,7 +676,7 @@ def test_name_only_match_suggests_a_retry_that_resolves(self, tmp_path: Path) ->
 
         warning = service.query_downstream(graph, "orders")["warnings"][0]
 
-        assert "<project>:orders" not in warning
+        assert "PROJECT:orders" not in warning
         suggested = "alpha:in.c-a.orders"
         assert suggested in warning
         retry = service.query_downstream(graph, suggested)
@@ -723,6 +723,66 @@ def test_mermaid_warning_is_escaped(self) -> None:
         assert "&lt;script&gt;" in code
         assert "&quot;x&quot;" in code
 
+    def test_warning_text_carries_no_angle_brackets(self, tmp_path: Path) -> None:
+        """Angle brackets survive escaping but not the browser (#584).
+
+        The warning also reaches the mermaid diagrams. Mermaid renders the
+        escaped entity back to a literal ``<project>`` in SVG text, where the
+        browser drops it as an unknown tag -- so the remedy loses the part
+        that makes it usable, while looking correct in a terminal and in every
+        string assertion. Keep the placeholder bracket-free.
+        """
+        service = self._service(tmp_path)
+
+        cross_project = service.query_downstream(_shared_table_graph(), SHARED_TABLE)
+        same_project = service.query_downstream(self._one_project_two_buckets(), "orders")
+
+        for result in (cross_project, same_project):
+            warning = result["warnings"][0]
+            assert "<" not in warning and ">" not in warning, warning
+
+    def test_er_diagram_carries_the_warning_too(self, tmp_path: Path) -> None:
+        """The ER view is a separate renderer and was dropping it (#584)."""
+        service = self._service(tmp_path)
+        graph = _shared_table_graph()
+        result = service.query_downstream(graph, SHARED_TABLE)
+
+        code = DeepLineageService.render_er_diagram(
+            result["edges"], graph, result["node"], warnings=result.get("warnings")
+        )
+
+        assert '"⚠ note" {' in code
+        assert "2 projects" in code
+
+    def test_er_diagram_without_warnings_gains_no_note(self, tmp_path: Path) -> None:
+        service = self._service(tmp_path)
+        graph = _shared_table_graph()
+        result = service.query_downstream(graph, f"beta:{SHARED_TABLE}")
+
+        code = DeepLineageService.render_er_diagram(
+            result["edges"], graph, result["node"], warnings=result.get("warnings")
+        )
+
+        assert "⚠ note" not in code
+
+    def test_er_diagram_warning_cannot_break_out_of_its_comment(self) -> None:
+        """A raw double quote would terminate the attribute comment (sec-05)."""
+        code = DeepLineageService.render_er_diagram(
+            [], LineageGraph(), "alpha:in.c-a.t", warnings=['say "hi" <script>alert(1)</script>']
+        )
+
+        assert '"hi"' not in code
+        assert "&quot;hi&quot;" in code
+        assert "<script>" not in code
+
+    def test_er_diagram_numbers_multiple_warnings(self) -> None:
+        code = DeepLineageService.render_er_diagram(
+            [], LineageGraph(), "alpha:in.c-a.t", warnings=["first", "second"]
+        )
+
+        assert "string warning_1 " in code
+        assert "string warning_2 " in code
+
     def test_unknown_identifier_still_errors(self, tmp_path: Path) -> None:
         service = self._service(tmp_path)
         result = service.query_downstream(_shared_table_graph(), "in.c-nope.missing")