check + fix: Protections around user packges being used as site packages (#6638)

## 📝 Summary

fixes #6553

We overload import spec to hook in for various format types. If there's
a user file that matches an expected format type, we erroneously
attempted to register the formatter for that import. This PR fixes this
issue by introducing `marimo/_utils/site_packages.py` for utils to
detect collisions, and a `marimo check` rule for users to more easily
troubleshoot this issue in the future

<img width="1204" height="261" alt="image"
src="https://github.com/user-attachments/assets/0b4de0ae-7948-4f5b-97c7-47ccd5a1423b"
/>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

docs/guides/lint_rules/index.md

@@ -33,6 +33,14 @@ These errors prevent notebook execution.
 | [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 | ❌ |
 
+### ⚠️ Runtime Rules
+
+These issues may cause runtime problems.
+
+| Code | Name | Description | Fixable |
+|------|------|-------------|----------|
+| [MR001](rules/self_import.md) | self-import | Importing a module with the same name as the file | ❌ |
+
 ### ✨ Formatting Rules
 
 These are style and formatting issues.

docs/guides/lint_rules/rules/self_import.md

@@ -0,0 +1,50 @@
+# MR001: self-import
+
+⚠️ **Runtime** ❌ Not Fixable
+
+MR001: Importing a module with the same name as the file.
+
+## What it does
+
+Analyzes import statements in each cell to detect cases where the imported
+module name matches the current file's name (without the .py extension).
+
+## Why is this bad?
+
+Importing a module with the same name as the file causes several issues:
+- Python may attempt to import the current file instead of the intended module
+- This can lead to circular import errors or unexpected behavior
+- It makes the code confusing and hard to debug
+- It can prevent the notebook from running correctly
+
+This is a runtime issue because it can cause import confusion and unexpected behavior.
+
+## Examples
+
+**Problematic (in a file named `requests.py`):**
+```python
+import requests  # Error: conflicts with file name
+```
+
+**Problematic (in a file named `math.py`):**
+```python
+from math import sqrt  # Error: conflicts with file name
+```
+
+**Solution:**
+```python
+# Rename the file to something else, like my_requests.py
+import requests  # Now this works correctly
+```
+
+**Alternative Solution:**
+```python
+# Use a different approach that doesn't conflict
+import urllib.request  # Use alternative library
+```
+
+## References
+
+- [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/)
+- [Python Import System](https://docs.python.org/3/reference/import.html)
+

marimo/_lint/rules/__init__.py

@@ -2,13 +2,15 @@
 from marimo._lint.rules.base import LintRule
 from marimo._lint.rules.breaking import BREAKING_RULE_CODES
 from marimo._lint.rules.formatting import FORMATTING_RULE_CODES
+from marimo._lint.rules.runtime import RUNTIME_RULE_CODES
 
 RULE_CODES: dict[str, type[LintRule]] = (
-    BREAKING_RULE_CODES | FORMATTING_RULE_CODES
+    BREAKING_RULE_CODES | RUNTIME_RULE_CODES | FORMATTING_RULE_CODES
 )
 
 __all__ = [
     "RULE_CODES",
     "BREAKING_RULE_CODES",
+    "RUNTIME_RULE_CODES",
     "FORMATTING_RULE_CODES",
 ]

marimo/_lint/rules/runtime/__init__.py

@@ -0,0 +1,12 @@
+# Copyright 2025 Marimo. All rights reserved.
+from marimo._lint.rules.base import LintRule
+from marimo._lint.rules.runtime.self_import import SelfImportRule
+
+RUNTIME_RULE_CODES: dict[str, type[LintRule]] = {
+    "MR001": SelfImportRule,
+}
+
+__all__ = [
+    "SelfImportRule",
+    "RUNTIME_RULE_CODES",
+]

marimo/_lint/rules/runtime/self_import.py

@@ -0,0 +1,144 @@
+# Copyright 2025 Marimo. All rights reserved.
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from marimo._lint.diagnostic import Diagnostic, Severity
+from marimo._lint.rules.breaking.graph import GraphRule
+from marimo._utils.site_packages import (
+    has_local_conflict,
+)
+
+if TYPE_CHECKING:
+    from marimo._lint.context import RuleContext
+    from marimo._runtime.dataflow import DirectedGraph
+
+
+class SelfImportRule(GraphRule):
+    """MR001: Importing a module with the same name as the file.
+
+    This rule detects attempts to import a module that has the same name as the
+    current file. This can cause import conflicts, circular import issues, and
+    unexpected behavior where the file might try to import itself instead of
+    the intended external module.
+
+    ## What it does
+
+    Analyzes import statements in each cell to detect cases where the imported
+    module name matches the current file's name (without the .py extension).
+
+    ## Why is this bad?
+
+    Importing a module with the same name as the file causes several issues:
+    - Python may attempt to import the current file instead of the intended module
+    - This can lead to circular import errors or unexpected behavior
+    - It makes the code confusing and hard to debug
+    - It can prevent the notebook from running correctly
+
+    This is a runtime issue because it can cause import confusion and unexpected behavior.
+
+    ## Examples
+
+    **Problematic (in a file named `requests.py`):**
+    ```python
+    import requests  # Error: conflicts with file name
+    ```
+
+    **Problematic (in a file named `math.py`):**
+    ```python
+    from math import sqrt  # Error: conflicts with file name
+    ```
+
+    **Solution:**
+    ```python
+    # Rename the file to something else, like my_requests.py
+    import requests  # Now this works correctly
+    ```
+
+    **Alternative Solution:**
+    ```python
+    # Use a different approach that doesn't conflict
+    import urllib.request  # Use alternative library
+    ```
+
+    ## References
+
+    - [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/)
+    - [Python Import System](https://docs.python.org/3/reference/import.html)
+    """
+
+    code = "MR001"
+    name = "self-import"
+    description = "Importing a module with the same name as the file"
+    severity = Severity.RUNTIME
+    fixable = False
+
+    async def _validate_graph(
+        self, graph: DirectedGraph, ctx: RuleContext
+    ) -> None:
+        """Check for imports that conflict with the file name."""
+        # Get the file name without extension
+        if not ctx.notebook.filename:
+            return
+
+        file_name = os.path.basename(ctx.notebook.filename)
+        if file_name.endswith(".py"):
+            module_name = file_name[:-3]
+        else:
+            # For .md or other extensions, we can't determine conflicts
+            return
+
+        # Get directory containing the notebook file for local package checking
+        notebook_dir = os.path.dirname(ctx.notebook.filename)
+
+        await self._check_cells_for_conflicts(
+            graph, ctx, module_name, file_name, notebook_dir
+        )
+
+    async def _check_cells_for_conflicts(
+        self,
+        graph: DirectedGraph,
+        ctx: RuleContext,
+        module_name: str,
+        file_name: str,
+        notebook_dir: str,
+    ) -> None:
+        """Check all cells for import conflicts using compiled cell data."""
+        for cell_id, cell_impl in graph.cells.items():
+            # Check imports from compiled cell data
+            for variable, var_data_list in cell_impl.variable_data.items():
+                for var_data in var_data_list:
+                    if var_data.import_data is None:
+                        continue
+
+                    import_data = var_data.import_data
+                    top_level_module = import_data.module.split(".")[0]
+                    fix_msg = f"Rename the file to avoid conflicts with the '{top_level_module}' module. "
+                    if top_level_module == module_name:
+                        # Standard self-import conflict
+                        message = f"Importing module '{top_level_module}' conflicts with file name '{file_name}'"
+                    # Check if there's a local file/package with the same name
+                    elif has_local_conflict(top_level_module, notebook_dir):
+                        # Module exists in site-packages - enhanced diagnostic
+                        message = (
+                            f"Importing module '{top_level_module}' conflicts "
+                            "with a module in site-packages, and may cause import ambiguity."
+                        )
+                    else:
+                        continue
+
+                    line, column = self._get_variable_line_info(
+                        cell_id, variable, ctx
+                    )
+                    diagnostic = Diagnostic(
+                        message=message,
+                        line=line,
+                        column=column,
+                        code=self.code,
+                        name=self.name,
+                        severity=self.severity,
+                        fixable=self.fixable,
+                        fix=fix_msg,
+                    )
+                    await ctx.add_diagnostic(diagnostic)

marimo/_lint/visitors.py

@@ -38,3 +38,27 @@ def visit_ClassDef(self, node: ast.ClassDef) -> None:
             self.column_number = node.col_offset + 1
             return
         self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        """Visit ImportFrom nodes to find imported variable definitions."""
+        for alias in node.names:
+            if (
+                alias.asname == self.target_variable
+                or alias.name == self.target_variable
+            ):
+                self.line_number = node.lineno
+                self.column_number = node.col_offset + 1
+                return
+        self.generic_visit(node)
+
+    def visit_Import(self, node: ast.Import) -> None:
+        """Visit Import nodes to find imported variable definitions."""
+        for alias in node.names:
+            if (
+                alias.asname == self.target_variable
+                or alias.name == self.target_variable
+            ):
+                self.line_number = node.lineno
+                self.column_number = node.col_offset + 1
+                return
+        self.generic_visit(node)

marimo/_output/formatters/formatters.py

@@ -38,6 +38,7 @@
 from marimo._output.formatters.structures import StructuresFormatter
 from marimo._output.formatters.sympy_formatters import SympyFormatter
 from marimo._output.formatters.tqdm_formatters import TqdmFormatter
+from marimo._utils.site_packages import is_local_module
 
 LOGGER = _loggers.marimo_logger()
 
@@ -123,6 +124,10 @@ def find_spec(  # type:ignore[no-untyped-def]
         if spec is None:
             return spec
 
+        # Skip patching for local modules (not under site-packages)
+        if is_local_module(spec):
+            return spec
+
         if spec.loader is not None and fullname in third_party_factories:
             # We're now in the process of importing a module with
             # an associated formatter factory. We'll hook into its