feat: Add pre-commit check for Radix Dialog <p> nesting violations

New check_frontend_code_quality.py script detects <p> elements nested
inside AlertDialog.Description or Dialog.Description (which render as
<p> by default), causing hydration warnings. Correctly skips blocks
that use asChild. Handles multi-line opening tags.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cadamsdotcom

.pre-commit-config.yaml

@@ -129,6 +129,12 @@ repos:
         language: system
         pass_filenames: false
         always_run: true
+      - id: check-frontend-code-quality
+        name: Check frontend code quality (dialog nesting)
+        entry: uv run python scripts/check_frontend_code_quality.py
+        language: system
+        files: \.tsx$
+        pass_filenames: true
 
   - repo: https://github.com/jendrikseipp/vulture
     rev: v2.13

scripts/check_frontend_code_quality.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""
+Check frontend code quality.
+
+Current checks:
+1. No <p> nesting inside Radix Dialog/AlertDialog Description (renders as <p>)
+   - use asChild with <div> wrapper, or replace <p> with <span className="block">
+"""
+
+import re
+import sys
+from pathlib import Path
+
+Violation = tuple[int, str, str]
+
+DESCRIPTION_OPEN_RE = re.compile(r"<(AlertDialog|Dialog)\.Description\b")
+DESCRIPTION_CLOSE_RE = re.compile(r"</(AlertDialog|Dialog)\.Description>")
+AS_CHILD_RE = re.compile(r"\basChild\b")
+PARAGRAPH_TAG_RE = re.compile(r"<p[\s>/]")
+TAG_END_RE = re.compile(r"(?<!/)>")
+SELF_CLOSING_TAG_RE = re.compile(r"/\s*>")
+
+
+def _check_dialog_description_nesting(source: str) -> list[Violation]:
+    """Find <p> tags nested inside Description without asChild."""
+    lines = source.splitlines()
+    violations: list[Violation] = []
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        open_match = DESCRIPTION_OPEN_RE.search(line)
+        if not open_match:
+            i += 1
+            continue
+
+        # Collect the full opening tag (may span multiple lines)
+        tag_lines = [line]
+        # Check if the tag closes on this line
+        rest_of_line = line[open_match.start() :]
+        while not TAG_END_RE.search(rest_of_line) and not SELF_CLOSING_TAG_RE.search(
+            rest_of_line
+        ):
+            i += 1
+            if i >= len(lines):
+                break
+            tag_lines.append(lines[i])
+            rest_of_line = lines[i]
+
+        full_tag = "\n".join(tag_lines)
+
+        # Self-closing tag - no children possible
+        if SELF_CLOSING_TAG_RE.search(full_tag):
+            i += 1
+            continue
+
+        # Has asChild - children render under a different element
+        if AS_CHILD_RE.search(full_tag):
+            # Skip to closing tag
+            i += 1
+            while i < len(lines):
+                if DESCRIPTION_CLOSE_RE.search(lines[i]):
+                    break
+                i += 1
+            i += 1
+            continue
+
+        # Scan content until closing tag for <p> elements
+        i += 1
+        while i < len(lines):
+            if DESCRIPTION_CLOSE_RE.search(lines[i]):
+                break
+            if PARAGRAPH_TAG_RE.search(lines[i]):
+                violations.append(
+                    (
+                        i + 1,  # 1-indexed line number
+                        "dialog-p-nesting",
+                        '<p> inside Description (renders as <p>) - use asChild with <div>, or <span className="block">',
+                    )
+                )
+            i += 1
+        i += 1
+
+    return violations
+
+
+def check_source(source: str, filename: str) -> list[Violation]:
+    """Check source for all applicable frontend violations."""
+    violations: list[Violation] = []
+    violations.extend(_check_dialog_description_nesting(source))
+    return violations
+
+
+def check_file(file_path: Path) -> list[Violation]:
+    """Check a single file for violations."""
+    try:
+        source = file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    return check_source(source, str(file_path))
+
+
+def main() -> None:
+    """Scan frontend source files and report violations."""
+    if len(sys.argv) > 1:
+        files = [Path(arg) for arg in sys.argv[1:]]
+    else:
+        files = sorted(Path("src").glob("**/*.tsx"))
+
+    total = 0
+    for fp in files:
+        if not fp.is_file():
+            continue
+        violations = check_file(fp)
+        if violations:
+            print(f"\n{fp}:")
+            for lineno, vtype, desc in violations:
+                print(f"  Line {lineno} [{vtype}]: {desc}")
+                total += 1
+
+    if total > 0:
+        print(f"\nFound {total} frontend code quality violations.")
+        sys.exit(1)
+    else:
+        print("No frontend code quality violations found.")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

tests/unit/scripts/test_check_frontend_code_quality.py

@@ -0,0 +1,137 @@
+"""Tests for check_frontend_code_quality.py - frontend code quality checks."""
+
+from scripts.check_frontend_code_quality import check_source
+
+
+class TestDialogDescriptionNesting:
+    """Detect <p> elements nested inside Radix Dialog/AlertDialog Description."""
+
+    def test_flags_p_inside_alert_dialog_description(self) -> None:
+        source = (
+            '<AlertDialog.Description className="mt-3 text-sm">\n'
+            "  <p>Are you sure?</p>\n"
+            "</AlertDialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 1
+        assert nesting_violations[0][0] == 2  # line number of <p>
+
+    def test_flags_p_inside_dialog_description(self) -> None:
+        source = (
+            '<Dialog.Description className="mt-3 text-sm">\n'
+            "  <p>Some content</p>\n"
+            "</Dialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 1
+
+    def test_flags_multiple_p_tags(self) -> None:
+        source = (
+            '<AlertDialog.Description className="mt-3">\n'
+            "  <p>First paragraph</p>\n"
+            "  <p>Second paragraph</p>\n"
+            "</AlertDialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 2
+
+    def test_allows_as_child_with_div_wrapper(self) -> None:
+        source = (
+            "<AlertDialog.Description asChild>\n"
+            '  <div className="mt-3 text-sm">\n'
+            "    <p>This is fine because asChild renders as div</p>\n"
+            "  </div>\n"
+            "</AlertDialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 0
+
+    def test_allows_text_only_content(self) -> None:
+        source = (
+            '<AlertDialog.Description className="mt-3 text-sm">\n'
+            "  This document will be removed from the upload list.\n"
+            "</AlertDialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 0
+
+    def test_allows_span_block_instead_of_p(self) -> None:
+        source = (
+            '<AlertDialog.Description className="mt-3 text-sm">\n'
+            '  <span className="block mb-2">\n'
+            "    Are you sure you want to delete this?\n"
+            "  </span>\n"
+            '  <span className="block">\n'
+            "    This action cannot be undone.\n"
+            "  </span>\n"
+            "</AlertDialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 0
+
+    def test_handles_as_child_on_separate_line(self) -> None:
+        source = (
+            "<AlertDialog.Description\n"
+            "  asChild\n"
+            '  className="mt-3"\n'
+            ">\n"
+            '  <div className="space-y-2">\n'
+            "    <p>Safe because asChild is present</p>\n"
+            "  </div>\n"
+            "</AlertDialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 0
+
+    def test_flags_p_with_multi_line_opening_tag_without_as_child(self) -> None:
+        source = (
+            "<AlertDialog.Description\n"
+            '  className="mt-3 text-sm text-brand-mid-grey"\n'
+            ">\n"
+            "  <p>This is a violation</p>\n"
+            "</AlertDialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 1
+        assert nesting_violations[0][0] == 4
+
+    def test_handles_self_closing_description(self) -> None:
+        source = '<AlertDialog.Description className="sr-only" />\n'
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 0
+
+    def test_handles_multiple_descriptions_in_one_file(self) -> None:
+        source = (
+            "// First dialog - safe (text only)\n"
+            '<AlertDialog.Description className="mt-2">\n'
+            "  Are you sure?\n"
+            "</AlertDialog.Description>\n"
+            "\n"
+            "// Second dialog - violation\n"
+            '<AlertDialog.Description className="mt-2">\n'
+            "  <p>Bad nesting</p>\n"
+            "</AlertDialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 1
+        assert nesting_violations[0][0] == 8
+
+    def test_p_with_attributes_is_also_flagged(self) -> None:
+        source = (
+            '<AlertDialog.Description className="mt-3">\n'
+            '  <p className="text-sm">Content</p>\n'
+            "</AlertDialog.Description>\n"
+        )
+        violations = check_source(source, "src/components/Example.tsx")
+        nesting_violations = [v for v in violations if v[1] == "dialog-p-nesting"]
+        assert len(nesting_violations) == 1