Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Report dependency cycles from the host analyzer (#11261)

Trevor Manz3d8d5bc49e8e
diff --git a/marimo/_server/host/analysis.py b/marimo/_server/host/analysis.py
index 85494cf2bf..bb97df6e79 100644
--- a/marimo/_server/host/analysis.py
+++ b/marimo/_server/host/analysis.py
@@ -1,8 +1,5 @@
# Copyright 2026 Marimo. All rights reserved.
-"""Cell definitions, references, syntax errors, and multiple definitions.
-
-The kernel reports cycles.
-"""
+"""Cell definitions, references, syntax errors, and graph diagnostics."""
from __future__ import annotations
@@ -13,7 +10,10 @@ from typing import TYPE_CHECKING
from marimo._ast.cell import CellImpl
from marimo._ast.compiler import compile_cell
from marimo._core import protocol
-from marimo._lint.validate_graph import check_for_multiple_definitions
+from marimo._lint.validate_graph import (
+ check_for_cycles,
+ check_for_multiple_definitions,
+)
from marimo._lint.visitors import VariableLineVisitor
from marimo._runtime.dataflow import DirectedGraph
from marimo._runtime.dataflow.edges import resolve_cell_references
@@ -21,6 +21,7 @@ from marimo._types.ids import CellId_t
if TYPE_CHECKING:
from marimo._core.document import Document
+ from marimo._messaging.errors import CycleError
SOURCE = "marimo"
@@ -70,6 +71,7 @@ class CellAnalyzer:
self._cache = cache
conflicts = check_for_multiple_definitions(graph)
+ cycles = check_for_cycles(graph)
order = {cell.id: index for index, cell in enumerate(document)}
analyses: dict[protocol.CellId, protocol.CellAnalysis] = {}
for cell in document:
@@ -104,6 +106,13 @@ class CellAnalyzer:
),
)
for error in conflicts.get(CellId_t(cell.id), ())
+ )
+ + tuple(
+ _cycle(error)
+ for error in sorted(
+ cycles.get(CellId_t(cell.id), ()),
+ key=lambda error: error.edges_with_vars,
+ )
),
)
return analyses
@@ -155,6 +164,31 @@ class CellAnalyzer:
)
+def _cycle(error: CycleError) -> protocol.Error:
+ edges = error.edges_with_vars
+ # Preserve dependency order, starting at the same cell for any rotation.
+ start = min(range(len(edges)), key=lambda index: edges[index][2])
+ edges = edges[start:] + edges[:start]
+ return protocol.Error(
+ kind="cycle-dependencies",
+ message=error.describe(),
+ source=SOURCE,
+ severity="error",
+ range=None,
+ name=None,
+ traceback=None,
+ related=tuple(
+ protocol.Related(
+ cell_id=protocol.CellId(child),
+ range=None,
+ message=f"Depends on {parent}"
+ + (f" through {', '.join(names)}" if names else ""),
+ )
+ for parent, names, child in edges
+ ),
+ )
+
+
def _syntax_error(code: str, e: Exception) -> protocol.Error:
where = None
if isinstance(e, SyntaxError) and e.lineno is not None:
diff --git a/tests/_server/host/test_host_analysis.py b/tests/_server/host/test_host_analysis.py
index ae7e5fd0c0..ac4b7adfb8 100644
--- a/tests/_server/host/test_host_analysis.py
+++ b/tests/_server/host/test_host_analysis.py
@@ -1,5 +1,5 @@
# Copyright 2026 Marimo. All rights reserved.
-"""The host's analyzer reports each cell's names, syntax errors, and conflicts."""
+"""The host's analyzer reports names, syntax errors, conflicts, and cycles."""
from __future__ import annotations
@@ -8,6 +8,7 @@ import threading
from unittest.mock import Mock
import pytest
+from inline_snapshot import snapshot
from marimo._ast.cell import CellImpl
from marimo._ast.compiler import compile_cell
@@ -18,7 +19,7 @@ from marimo._server.host.analysis import CellAnalyzer, HostAnalyzer
from marimo._types.ids import CellId_t
-def snapshot(codes: dict[str, str]) -> Document:
+def document_snapshot(codes: dict[str, str]) -> Document:
return Document(
[DocumentCell(cid, code) for cid, code in codes.items()],
{},
@@ -28,7 +29,74 @@ def snapshot(codes: dict[str, str]) -> Document:
def analyze(
codes: dict[str, str],
) -> dict[protocol.CellId, protocol.CellAnalysis]:
- return CellAnalyzer()(snapshot(codes))
+ return CellAnalyzer()(document_snapshot(codes))
+
+
+def render_diagnostics(
+ codes: dict[str, str],
+ analyses: dict[protocol.CellId, protocol.CellAnalysis],
+) -> str:
+ """Show spans on source, with related spans labeled by their origin cell.
+
+ Escape non-ASCII text and tabs so alignment does not depend on terminal
+ character widths. Protocol columns count UTF-16 units, not characters.
+ """
+
+ def display(text: str) -> str:
+ return text.encode("unicode_escape").decode("ascii")
+
+ def column(text: str, offset: int) -> int:
+ encoded = text.encode("utf-16-le")
+ assert 0 <= offset * 2 <= len(encoded)
+ return len(display(encoded[: offset * 2].decode("utf-16-le")))
+
+ annotations: dict[str, list[tuple[protocol.Range | None, str]]] = {
+ cid: [
+ (error.range, f"{error.severity}[{error.kind}]: {error.message}")
+ for error in analyses[cid].errors
+ ]
+ for cid in codes
+ }
+ for cid, analysis in analyses.items():
+ for error in analysis.errors:
+ for related in error.related:
+ annotations[related.cell_id].append(
+ (related.range, f"related[{cid}]: {related.message}")
+ )
+
+ rendered: list[str] = []
+ for cid, source in codes.items():
+ rendered.append(f"-- {cid} --")
+ lines = source.split("\n")
+ width = len(str(len(lines)))
+ for where, _ in annotations[cid]:
+ if where is not None:
+ assert 0 <= where.start.line <= where.end.line < len(lines)
+ for index, text in enumerate(lines):
+ rendered.append(f"{index + 1:>{width}} | {display(text)}")
+ for where, label in annotations[cid]:
+ if (
+ where is None
+ or not where.start.line <= index <= where.end.line
+ ):
+ continue
+ start = (
+ column(text, where.start.character)
+ if index == where.start.line
+ else 0
+ )
+ end = (
+ column(text, where.end.character)
+ if index == where.end.line
+ else len(display(text))
+ )
+ assert start <= end
+ marker = " " * start + "^" * max(end - start, 1)
+ rendered.append(f"{' ' * width} | {marker} {label}")
+ for where, label in annotations[cid]:
+ if where is None:
+ rendered.append(f"{' ' * width} = {label} (no range)")
+ return "\n".join(rendered)
def test_refs_are_names_other_cells_define() -> None:
@@ -48,41 +116,141 @@ def test_refs_are_names_other_cells_define() -> None:
def test_a_name_defined_twice_is_an_error_on_each_definer() -> None:
- analyses = analyze({"a": "x = 1", "b": "y = 2\nx = y", "c": "z = x"})
+ codes = {
+ "a": "s = '😀'; value = 1",
+ "b": "y = 2\nvalue = y",
+ "c": "result = value",
+ }
+ analyses = analyze(codes)
assert analyses["b"].refs == ()
- assert analyses["c"].refs == ("x",)
- assert analyses["c"].errors == ()
-
- (first,) = analyses["a"].errors
- (second,) = analyses["b"].errors
- assert first.kind == second.kind == "multiple-definitions"
- assert first.message == "Multiple cells define x"
- assert first.severity == "error"
- # Each copy is ranged at its own definition and lists every definer.
- assert first.range == span(0, 0, 1)
- assert second.range == span(1, 0, 1)
- assert first.related == second.related
- assert [(r.cell_id, r.range, r.message) for r in first.related] == [
- ("a", span(0, 0, 1), "Defines x"),
- ("b", span(1, 0, 1), "Defines x"),
- ]
+ assert analyses["c"].refs == ("value",)
+ assert render_diagnostics(codes, analyses) == snapshot("""\
+-- a --
+1 | s = '\\U0001f600'; value = 1
+ | ^^^^^ error[multiple-definitions]: Multiple cells define value
+ | ^^^^^ related[a]: Defines value
+ | ^^^^^ related[b]: Defines value
+-- b --
+1 | y = 2
+2 | value = y
+ | ^^^^^ error[multiple-definitions]: Multiple cells define value
+ | ^^^^^ related[a]: Defines value
+ | ^^^^^ related[b]: Defines value
+-- c --
+1 | result = value\
+""")
-def test_definition_ranges_cover_the_bound_name() -> None:
- analyses = analyze(
- {
- "a": "def x():\n pass",
- "b": "import numpy as x",
- "c": "for x in range(3):\n def y():\n x = 1",
- "d": "mo.sql('CREATE TABLE x (id INT)')",
- }
[email protected]("reverse", [False, True])
+ ("codes", "dependencies"),
+ [
+ (
+ {
+ "a": "x = z",
+ "b": "y = x",
+ "c": "z = y",
+ "downstream": "result = y",
+ },
+ [
+ ("a", "Depends on c through z"),
+ ("b", "Depends on a through x"),
+ ("c", "Depends on b through y"),
+ ],
+ ),
+ (
+ {"provider": "x = 1", "a": "del x; y = 1", "b": "z = x + y"},
+ [("a", "Depends on b through x"), ("b", "Depends on a through y")],
+ ),
+ ],
+)
+def test_cycles_report_the_dependency_chain_on_every_participant(
+ codes, dependencies, reverse
+):
+ if reverse:
+ codes = dict(reversed(list(codes.items())))
+ analyses = analyze(codes)
+ expected = protocol.Error(
+ kind="cycle-dependencies",
+ message="This cell is in a cycle",
+ source="marimo",
+ severity="error",
+ range=None,
+ name=None,
+ traceback=None,
+ related=tuple(
+ protocol.Related(cell_id=cid, range=None, message=message)
+ for cid, message in dependencies
+ ),
)
- ranges = {cell_id: analyses[cell_id].errors[0].range for cell_id in "abcd"}
- assert ranges["a"] == span(0, 4, 5)
- assert ranges["b"] == span(0, 16, 17)
- assert ranges["c"] == span(0, 4, 5)
- # A SQL definition has no name in the Python source.
- assert ranges["d"] is None
+ participants = {cid for cid, _ in dependencies}
+ assert {cid: cell.errors for cid, cell in analyses.items()} == {
+ cid: (expected,) if cid in participants else () for cid in codes
+ }
+
+
+def test_cycles_and_multiple_definitions_are_reported_together() -> None:
+ codes = {"a": "x, z = y, 0", "b": "y, z = x, 0"}
+ assert render_diagnostics(codes, analyze(codes)) == snapshot("""\
+-- a --
+1 | x, z = y, 0
+ | ^ error[multiple-definitions]: Multiple cells define z
+ | ^ related[a]: Defines z
+ | ^ related[b]: Defines z
+ = error[cycle-dependencies]: This cell is in a cycle (no range)
+ = related[a]: Depends on b through y (no range)
+ = related[b]: Depends on b through y (no range)
+-- b --
+1 | y, z = x, 0
+ | ^ error[multiple-definitions]: Multiple cells define z
+ | ^ related[a]: Defines z
+ | ^ related[b]: Defines z
+ = error[cycle-dependencies]: This cell is in a cycle (no range)
+ = related[a]: Depends on a through x (no range)
+ = related[b]: Depends on a through x (no range)\
+""")
+
+
+def test_definition_ranges_cover_the_bound_name() -> None:
+ codes = {
+ "a": "def x():\n pass",
+ "b": "import numpy as x",
+ "c": "for x in range(3):\n def y():\n x = 1",
+ "d": "mo.sql('CREATE TABLE x (id INT)')",
+ }
+ assert render_diagnostics(codes, analyze(codes)) == snapshot("""\
+-- a --
+1 | def x():
+ | ^ error[multiple-definitions]: Multiple cells define x
+ | ^ related[a]: Defines x
+ | ^ related[b]: Defines x
+ | ^ related[c]: Defines x
+ | ^ related[d]: Defines x
+2 | pass
+-- b --
+1 | import numpy as x
+ | ^ error[multiple-definitions]: Multiple cells define x
+ | ^ related[a]: Defines x
+ | ^ related[b]: Defines x
+ | ^ related[c]: Defines x
+ | ^ related[d]: Defines x
+-- c --
+1 | for x in range(3):
+ | ^ error[multiple-definitions]: Multiple cells define x
+ | ^ related[a]: Defines x
+ | ^ related[b]: Defines x
+ | ^ related[c]: Defines x
+ | ^ related[d]: Defines x
+2 | def y():
+3 | x = 1
+-- d --
+1 | mo.sql('CREATE TABLE x (id INT)')
+ = error[multiple-definitions]: Multiple cells define x (no range)
+ = related[a]: Defines x (no range)
+ = related[b]: Defines x (no range)
+ = related[c]: Defines x (no range)
+ = related[d]: Defines x (no range)\
+""")
def span(line: int, start: int, end: int) -> protocol.Range:
@@ -154,17 +322,18 @@ def test_an_analyzer_kept_between_edits_matches_a_fresh_one() -> None:
{"a": "x = 1", "b": "y = x", "c": "z = y"},
{"a": "x = 1", "b": "y = x\nw = z", "c": "z = y"},
{"b": "y = x\nw = z", "c": "z = y"},
+ {"b": "y = x\nw = z"},
{"b": "def (:", "c": "z = y"},
]
for codes in steps:
- assert analyzer(snapshot(codes)) == analyze(codes), codes
+ assert analyzer(document_snapshot(codes)) == analyze(codes), codes
def test_analyzer_retries_after_an_unexpected_compiler_failure(
monkeypatch: pytest.MonkeyPatch,
) -> None:
analyzer = CellAnalyzer()
- analyzer(snapshot({"a": "x = 1"}))
+ analyzer(document_snapshot({"a": "x = 1"}))
codes = {"a": "y = 2", "b": "z = y"}
def fail(*_args: object, **_kwargs: object) -> None:
@@ -173,9 +342,9 @@ def test_analyzer_retries_after_an_unexpected_compiler_failure(
with monkeypatch.context() as patch:
patch.setattr("marimo._server.host.analysis.compile_cell", fail)
with pytest.raises(RuntimeError, match="compiler failed"):
- analyzer(snapshot(codes))
+ analyzer(document_snapshot(codes))
- assert analyzer(snapshot(codes)) == analyze(codes)
+ assert analyzer(document_snapshot(codes)) == analyze(codes)
async def test_host_analyzer_reports_each_revision_off_the_loop(
@@ -197,7 +366,7 @@ async def test_host_analyzer_reports_each_revision_off_the_loop(
"marimo._server.host.analysis.compile_cell", blocked_compile
)
analyzer = HostAnalyzer()
- reported = asyncio.create_task(analyzer.analyze(snapshot(codes)))
+ reported = asyncio.create_task(analyzer.analyze(document_snapshot(codes)))
try:
await asyncio.wait_for(started.wait(), timeout=5)
# The loop must resume while compilation is still blocked.
@@ -219,7 +388,7 @@ async def test_host_analyzer_raises_unexpected_failures(
monkeypatch.setattr("marimo._server.host.analysis.compile_cell", fail)
with pytest.raises(RuntimeError, match="boom"):
- await analyzer.analyze(snapshot({"a": "x = 1"}))
+ await analyzer.analyze(document_snapshot({"a": "x = 1"}))
def test_compilation_cache_uses_identity_and_code_hash(