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.

feat: syntax error `check` rule as a base example (#6384)

Dylan Madisettied933512b2ef
diff --git a/development_docs/adding_lint_rules.md b/development_docs/adding_lint_rules.md
new file mode 100644
index 0000000000..375010883a
--- /dev/null
+++ b/development_docs/adding_lint_rules.md
@@ -0,0 +1,393 @@
+# Adding Lint Rules to marimo
+
+This guide explains how to add new lint rules to marimo's linting system.
+
+## Overview
+
+marimo's lint system helps users write better, more reliable notebooks by detecting various issues that could prevent notebooks from running correctly. The system is organized around three severity levels:
+
+- **Breaking (MB)**: Errors that prevent notebook execution
+- **Runtime (MR)**: Issues that may cause runtime problems
+- **Formatting (MF)**: Style and formatting issues
+
+## Rule Code Assignment
+
+Rule codes follow a specific pattern: `M[severity][number]`
+
+### Current Code Ranges
+
+- **MB001-MB099**: Breaking rules
+- **MR001-MR099**: Runtime rules
+- **MF001-MF099**: Formatting rules
+
+### Assigning New Codes
+
+When adding a new rule:
+
+1. **Determine severity**: Choose Breaking, Runtime, or Formatting based on impact
+2. **Find next available code**: Check existing rules in the appropriate category
+3. **Use sequential numbering**: MB005, MB006, etc.
+
+**Example assignments**:
+- MB001: unparsable-cells
+- MB002: multiple-definitions
+- MB003: cycle-dependencies
+- MB004: setup-cell-dependencies
+- MF001: general-formatting
+- MF002: parse-stdout
+- MF003: parse-stderr
+
+## Step-by-Step Implementation
+
+### 1. Create the Rule Class
+
+Create your rule in the appropriate directory:
+- Breaking rules: `marimo/_lint/rules/breaking/`
+- Runtime rules: `marimo/_lint/rules/runtime/`
+- Formatting rules: `marimo/_lint/rules/formatting/`
+
+**Template for a new rule**:
+
+```python
+# Copyright 2025 Marimo. All rights reserved.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from marimo._lint.diagnostic import Diagnostic, Severity
+from marimo._lint.rules.base import LintRule
+
+if TYPE_CHECKING:
+ from marimo._lint.context import RuleContext
+
+
+class YourNewRule(LintRule):
+ """MB005: Brief description of what this rule checks.
+
+ Detailed explanation of what this rule does and why it's important.
+ This should explain the technical details of how the rule works.
+
+ ## What it does
+
+ Clear, concise explanation of what the rule detects.
+
+ ## Why is this bad?
+
+ Explanation of why this issue is problematic:
+ - Impact on notebook execution
+ - Potential for bugs or confusion
+ - Effect on reproducibility
+
+ ## Examples
+
+ **Problematic:**
+ ```python
+ # Example of code that violates this rule
+ bad_code = "example"
+ ```
+
+ **Solution:**
+ ```python
+ # Example of how to fix the violation
+ good_code = "example"
+ ```
+
+ ## References
+
+ - [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/)
+ - [Relevant Guide](https://docs.marimo.io/guides/...)
+ """
+
+ code = "MB005" # Your assigned code
+ name = "your-rule-name" # Kebab-case name
+ description = "Brief description for rule listings"
+ severity = Severity.BREAKING # Or RUNTIME/FORMATTING
+ fixable = False # True if rule can auto-fix issues
+
+ async def check(self, ctx: RuleContext) -> None:
+ """Implement your rule logic here."""
+ # Iterate through notebook cells
+ for cell in ctx.notebook.cells:
+ # Your detection logic here
+ if self._detect_violation(cell):
+ diagnostic = Diagnostic(
+ message="Description of the specific violation",
+ line=cell.lineno,
+ column=cell.col_offset + 1,
+ code=self.code,
+ name=self.name,
+ severity=self.severity,
+ fixable=self.fixable,
+ )
+ await ctx.add_diagnostic(diagnostic)
+
+ def _detect_violation(self, cell) -> bool:
+ """Helper method for detection logic."""
+ # Implement your specific detection logic
+ return False
+```
+
+### 2. Register the Rule
+
+Add your rule to the appropriate `__init__.py` file:
+
+**For Breaking rules** (`marimo/_lint/rules/breaking/__init__.py`):
+
+```python
+from marimo._lint.rules.breaking.your_file import YourNewRule
+
+BREAKING_RULE_CODES: dict[str, type[LintRule]] = {
+ "MB001": UnparsableRule,
+ "MB002": MultipleDefinitionsRule,
+ "MB003": CycleDependenciesRule,
+ "MB004": SetupCellDependenciesRule,
+ "MB005": YourNewRule, # Add your rule here
+}
+
+__all__ = [
+ # ... existing rules ...
+ "YourNewRule", # Add to exports
+ "BREAKING_RULE_CODES",
+]
+```
+
+### 3. Create Test Files
+
+#### a) Create a test notebook file
+
+Create `tests/_lint/test_files/your_rule_name.py`:
+
+```python
+import marimo
+
+__generated_with = "0.15.2"
+app = marimo.App()
+
+
+def _():
+ # Code that should trigger your rule
+ problematic_code = "example"
+ return
+
+
+def _():
+ # Additional test cases
+ return
+
+
+if __name__ == "__main__":
+ app.run()
+```
+
+#### b) Add snapshot test
+
+Add to `tests/_lint/test_runtime_errors_snapshot.py`:
+
+```python
+def test_your_rule_snapshot():
+ """Test snapshot for your new rule."""
+ file = "tests/_lint/test_files/your_rule_name.py"
+ with open(file) as f:
+ code = f.read()
+
+ notebook = parse_notebook(code, filepath=file)
+ errors = lint_notebook(notebook)
+
+ # Format errors for snapshot
+ error_output = []
+ for error in errors:
+ error_output.append(error.format())
+
+ snapshot("your_rule_name_errors.txt", "\n".join(error_output))
+```
+
+#### c) Add unit tests (optional but recommended)
+
+For more rigorous testing, create `tests/_lint/test_your_rule.py`:
+
+```python
+import pytest
+from marimo._ast.parse import parse_notebook
+from marimo._lint.context import LintContext
+from marimo._lint.rules.breaking import YourNewRule
+
+
+class TestYourNewRule:
+ """Test cases for YourNewRule."""
+
+ async def test_detects_violation(self):
+ """Test that the rule detects violations correctly."""
+ code = """import marimo
+app = marimo.App()
+
+def _():
+ # Code that should trigger the rule
+ return
+"""
+ notebook = parse_notebook(code)
+ ctx = LintContext(notebook)
+
+ rule = YourNewRule()
+ await rule.check(ctx)
+
+ diagnostics = await ctx.get_diagnostics()
+ assert len(diagnostics) > 0
+ assert diagnostics[0].code == "MB005"
+ assert diagnostics[0].severity == Severity.BREAKING
+
+ async def test_no_false_positives(self):
+ """Test that the rule doesn't trigger on valid code."""
+ code = """import marimo
+app = marimo.App()
+
+def _():
+ # Valid code that should not trigger the rule
+ return
+"""
+ notebook = parse_notebook(code)
+ ctx = LintContext(notebook)
+
+ rule = YourNewRule()
+ await rule.check(ctx)
+
+ diagnostics = await ctx.get_diagnostics()
+ assert len(diagnostics) == 0
+```
+
+### 4. Generate Documentation
+
+The documentation is automatically generated from your rule's docstring. Run:
+
+```bash
+uv run scripts/generate_lint_docs.py
+```
+
+This will create:
+- `docs/guides/lint_rules/rules/your_rule_name.md`
+- Updated `docs/guides/lint_rules/index.md`
+
+### 5. Run Tests
+
+```bash
+# Run lint tests
+uv run hatch run test:test tests/_lint
+
+# Run your specific test
+uv run hatch run test:test tests/_lint/test_your_rule.py
+
+# Update snapshots if needed
+uv run hatch run test:test tests/_lint/test_runtime_errors_snapshot.py --snapshot-update
+```
+
+## Rule Implementation Guidelines
+
+### Detection Logic
+
+- **Prefer AST analysis** over string matching when possible
+- **Use context information** from `RuleContext` (notebook, graph, etc.)
+- **Be specific** in error messages - help users understand the exact issue
+- **Consider edge cases** - test with various code patterns
+
+### Error Messages
+
+- **Be descriptive**: Explain what the issue is
+- **Be actionable**: Suggest how to fix it
+- **Be consistent**: Follow patterns from existing rules
+
+Good: `"Variable 'x' is defined in multiple cells"`
+Bad: `"Multiple definition error"`
+
+### Performance
+
+- **Avoid expensive operations** in the hot path
+- **Cache results** when checking multiple cells (add to context if needed)
+- **Early return** when possible
+
+### Fixability
+
+TODO: Right now, the only fixable errors are via re-serialization.
+
+## Common Patterns
+
+### Checking All Cells
+
+```python
+async def check(self, ctx: RuleContext) -> None:
+ for cell in ctx.notebook.cells:
+ if self._check_cell(cell):
+ # Create diagnostic
+```
+
+### Using the Dependency Graph
+
+```python
+async def check(self, ctx: RuleContext) -> None:
+ graph = ctx.get_graph()
+ for cell_id, cell_data in graph.cells.items():
+ # Analyze dependencies
+```
+
+## Testing Best Practices
+
+### Snapshot Tests
+
+- **Include in snapshot tests** for regression protection
+- **Use realistic examples** that demonstrate the rule clearly
+- **Test edge cases** in separate unit tests
+
+### Unit Tests
+
+- **Test positive cases** (rule triggers correctly)
+- **Test negative cases** (no false positives)
+- **Test edge cases** (empty cells, syntax errors, etc.)
+- **Test multiple violations** in one notebook
+
+### Test File Structure
+
+```
+tests/_lint/
+├── test_files/ # Test notebooks
+│ └── your_rule_name.py
+├── snapshots/ # Expected outputs
+│ └── your_rule_name_errors.txt
+├── test_your_rule.py # Unit tests
+└── test_runtime_errors_snapshot.py # Snapshot tests
+```
+
+## Documentation Requirements
+
+Your rule's docstring should include:
+
+1. **Rule code and brief description** in the first line
+2. **## What it does** - Technical explanation
+3. **## Why is this bad?** - Impact explanation
+4. **## Examples** - Code samples (problematic and fixed)
+5. **## References** - Links to relevant documentation
+
+The documentation system will automatically:
+- Generate individual rule pages
+- Update the main rules index
+- Create proper navigation links
+- Use human-readable filenames
+
+## Review Checklist
+
+Before submitting your rule:
+
+- [ ] Rule code follows numbering convention
+- [ ] Rule is registered in appropriate `__init__.py`
+- [ ] Comprehensive docstring with all required sections
+- [ ] Unit tests cover positive and negative cases
+- [ ] Snapshot test included
+- [ ] Documentation generates correctly
+- [ ] All lint tests pass
+- [ ] Error messages are clear and actionable
+- [ ] Performance is reasonable for large notebooks
+
+## Example: Simple Rule Implementation
+
+Here's a complete example of a simple rule that checks for syntax errors: https://github.com/marimo-team/marimo/pull/6384
diff --git a/docs/guides/lint_rules/index.md b/docs/guides/lint_rules/index.md
index 01f5b380c2..a5ef3199a8 100644
--- a/docs/guides/lint_rules/index.md
+++ b/docs/guides/lint_rules/index.md
@@ -31,6 +31,7 @@ These errors prevent notebook execution.
| [MB002](rules/multiple_definitions.md) | multiple-definitions | Multiple cells define the same variable | ❌ |
| [MB003](rules/cycle_dependencies.md) | cycle-dependencies | Cells have circular dependencies | ❌ |
| [MB004](rules/setup_cell_dependencies.md) | setup-cell-dependencies | Setup cell cannot have dependencies | ❌ |
+| [MB005](rules/invalid_syntax.md) | invalid-syntax | Cell contains code that throws a SyntaxError on compilation | ❌ |
### ✨ Formatting Rules
diff --git a/docs/guides/lint_rules/rules/invalid_syntax.md b/docs/guides/lint_rules/rules/invalid_syntax.md
new file mode 100644
index 0000000000..acb0309f80
--- /dev/null
+++ b/docs/guides/lint_rules/rules/invalid_syntax.md
@@ -0,0 +1,62 @@
+# MB005: invalid-syntax
+
+🚨 **Breaking** ❌ Not Fixable
+
+MB005: Cell contains code that throws a SyntaxError on compilation.
+
+## What it does
+
+Attempts to compile each cell using marimo's internal compiler and catches any
+SyntaxError exceptions that occur during the compilation process.
+
+## Why is this bad?
+
+Cells with syntax errors cannot be executed, making the notebook non-functional.
+SyntaxErrors prevent marimo from creating the dependency graph and running the
+reactive execution system, breaking the core functionality of the notebook.
+
+## Examples
+
+**Problematic:**
+```python
+# Invalid indentation
+if True:
+print("Hello") # Missing indentation
+```
+
+**Problematic:**
+```python
+# Invalid syntax
+x = 1 + # Missing operand
+```
+
+**Problematic:**
+```python
+# Mismatched brackets
+my_list = [1, 2, 3 # Missing closing bracket
+```
+
+**Solution:**
+```python
+# Fix indentation
+if True:
+ print("Hello") # Proper indentation
+```
+
+**Solution:**
+```python
+# Complete expressions
+x = 1 + 2 # Complete arithmetic expression
+```
+
+**Solution:**
+```python
+# Match brackets
+my_list = [1, 2, 3] # Proper closing bracket
+```
+
+## References
+
+- [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/)
+- [Python SyntaxError Documentation](https://docs.python.org/3/tutorial/errors.html#syntax-errors)
+
diff --git a/marimo/_lint/rules/breaking/__init__.py b/marimo/_lint/rules/breaking/__init__.py
index a28dee103d..4868f1c8dc 100644
--- a/marimo/_lint/rules/breaking/__init__.py
+++ b/marimo/_lint/rules/breaking/__init__.py
@@ -5,6 +5,7 @@ from marimo._lint.rules.breaking.graph import (
MultipleDefinitionsRule,
SetupCellDependenciesRule,
)
+from marimo._lint.rules.breaking.syntax_error import SyntaxErrorRule
from marimo._lint.rules.breaking.unparsable import UnparsableRule
BREAKING_RULE_CODES: dict[str, type[LintRule]] = {
@@ -12,6 +13,7 @@ BREAKING_RULE_CODES: dict[str, type[LintRule]] = {
"MB002": MultipleDefinitionsRule,
"MB003": CycleDependenciesRule,
"MB004": SetupCellDependenciesRule,
+ "MB005": SyntaxErrorRule,
}
__all__ = [
@@ -19,5 +21,6 @@ __all__ = [
"CycleDependenciesRule",
"SetupCellDependenciesRule",
"UnparsableRule",
+ "SyntaxErrorRule",
"BREAKING_RULE_CODES",
]
diff --git a/marimo/_lint/rules/breaking/syntax_error.py b/marimo/_lint/rules/breaking/syntax_error.py
new file mode 100644
index 0000000000..558f26d217
--- /dev/null
+++ b/marimo/_lint/rules/breaking/syntax_error.py
@@ -0,0 +1,116 @@
+# Copyright 2025 Marimo. All rights reserved.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from marimo._ast.compiler import (
+ ir_cell_factory,
+)
+from marimo._lint.diagnostic import Diagnostic, Severity
+from marimo._lint.rules.base import LintRule
+from marimo._schemas.serialization import UnparsableCell
+from marimo._types.ids import CellId_t
+
+if TYPE_CHECKING:
+ from marimo._lint.context import RuleContext
+
+
+class SyntaxErrorRule(LintRule):
+ """MB005: Cell contains code that throws a SyntaxError on compilation.
+
+ This rule detects cells that contain Python code with syntax errors that
+ prevent compilation. Unlike unparsable cells (MB001), these cells can be
+ parsed but fail when Python tries to compile them into executable code.
+
+ ## What it does
+
+ Attempts to compile each cell using marimo's internal compiler and catches any
+ SyntaxError exceptions that occur during the compilation process.
+
+ ## Why is this bad?
+
+ Cells with syntax errors cannot be executed, making the notebook non-functional.
+ SyntaxErrors prevent marimo from creating the dependency graph and running the
+ reactive execution system, breaking the core functionality of the notebook.
+
+ ## Examples
+
+ **Problematic:**
+ ```python
+ # Invalid indentation
+ if True:
+ print("Hello") # Missing indentation
+ ```
+
+ **Problematic:**
+ ```python
+ # Invalid syntax
+ x = 1 + # Missing operand
+ ```
+
+ **Problematic:**
+ ```python
+ # Mismatched brackets
+ my_list = [1, 2, 3 # Missing closing bracket
+ ```
+
+ **Solution:**
+ ```python
+ # Fix indentation
+ if True:
+ print("Hello") # Proper indentation
+ ```
+
+ **Solution:**
+ ```python
+ # Complete expressions
+ x = 1 + 2 # Complete arithmetic expression
+ ```
+
+ **Solution:**
+ ```python
+ # Match brackets
+ my_list = [1, 2, 3] # Proper closing bracket
+ ```
+
+ ## References
+
+ - [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/)
+ - [Python SyntaxError Documentation](https://docs.python.org/3/tutorial/errors.html#syntax-errors)
+ """
+
+ code = "MB005"
+ name = "invalid-syntax"
+ description = "Cell contains code that throws a SyntaxError on compilation"
+ severity = Severity.BREAKING
+ fixable = False
+
+ async def check(self, ctx: RuleContext) -> None:
+ """Check for syntax errors during compilation."""
+ for cell in ctx.notebook.cells:
+ if not isinstance(cell, UnparsableCell):
+ try:
+ ir_cell_factory(
+ cell,
+ cell_id=CellId_t("Hbol"),
+ filename=ctx.notebook.filename,
+ )
+ except SyntaxError as e:
+ message = f"{e.msg}"
+ await ctx.add_diagnostic(
+ Diagnostic(
+ message=message,
+ line=cell.lineno + (e.lineno or 1) - 1,
+ column=(e.offset or 1),
+ fix=_get_known_hints(message),
+ )
+ )
+
+
+def _get_known_hints(message: str) -> str | None:
+ if message == "'return' outside function":
+ return (
+ "marimo cells are not normal Python functions; treat cell bodies"
+ " as top-level code, or use `@app.function` to define a pure function."
+ )
+ return None
diff --git a/mkdocs.yml b/mkdocs.yml
index dca8955fbe..32594216f3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -100,6 +100,7 @@ nav:
- Multiple definitions: guides/lint_rules/rules/multiple_definitions.md
- Cycle dependencies: guides/lint_rules/rules/cycle_dependencies.md
- Setup cell dependencies: guides/lint_rules/rules/setup_cell_dependencies.md
+ - Syntax Error: guides/lint_rules/rules/invalid_syntax.md
- General formatting: guides/lint_rules/rules/general_formatting.md
- Parse stdout: guides/lint_rules/rules/parse_stdout.md
- Parse stderr: guides/lint_rules/rules/parse_stderr.md
diff --git a/tests/_lint/snapshots/syntax_errors.txt b/tests/_lint/snapshots/syntax_errors.txt
new file mode 100644
index 0000000000..f9c943b8fe
--- /dev/null
+++ b/tests/_lint/snapshots/syntax_errors.txt
@@ -0,0 +1,13 @@
+critical[invalid-syntax]: name 'tickers' is assigned to before global declaration
+ --> tests/_lint/test_files/syntax_errors.py:9:1
+ 9 | tickers = ["AAPL", "GOOGL"]
+ 10 | global tickers #
+ | ^
+ 11 |
+critical[invalid-syntax]: 'return' outside function
+ --> tests/_lint/test_files/syntax_errors.py:15:5
+ 15 | if tickers is not None:
+ 16 | return tickers
+ | ^
+ 17 | return
+info: marimo cells are not normal Python functions; treat cell bodies as top-level code, or use `@app.function` to define a pure function.
\ No newline at end of file
diff --git a/tests/_lint/test_files/syntax_errors.py b/tests/_lint/test_files/syntax_errors.py
new file mode 100644
index 0000000000..efcd65326d
--- /dev/null
+++ b/tests/_lint/test_files/syntax_errors.py
@@ -0,0 +1,21 @@
+import marimo
+
+__generated_with = "0.15.5"
+app = marimo.App(width="medium")
+
+
+def global_error():
+ tickers = ["AAPL", "GOOGL"]
+ global tickers #
+
+
+def return_error(tickers):
+ if tickers is not None:
+ return tickers
+ return
+
+
+if __name__ == "__main__":
+ app.run()
diff --git a/tests/_lint/test_runtime_errors_snapshot.py b/tests/_lint/test_runtime_errors_snapshot.py
index e9d4afe9cc..33f3dce9a5 100644
--- a/tests/_lint/test_runtime_errors_snapshot.py
+++ b/tests/_lint/test_runtime_errors_snapshot.py
@@ -91,3 +91,20 @@ def test_formatting_snapshot():
error_output.append(error.format())
snapshot("formatting.txt", "\n".join(error_output))
+
+
+def test_syntax_errors_snapshot():
+ """Test snapshot for syntax errors."""
+ file = "tests/_lint/test_files/syntax_errors.py"
+ with open(file) as f:
+ code = f.read()
+
+ notebook = parse_notebook(code, filepath=file)
+ errors = lint_notebook(notebook)
+
+ # Format errors for snapshot
+ error_output = []
+ for error in errors:
+ error_output.append(error.format())
+
+ snapshot("syntax_errors.txt", "\n".join(error_output))