#!/usr/bin/env python3
"""
Repo-wide formatter for Markdown/MDX docs.

Enforces:
- Indentation: convert tabs to four spaces outside code blocks; list indents normalized to multiples of four.
- Newlines: ensure a single blank line before and after headings, images, and MDX components like Step/Accordion.
- Wrapping: wrap plain text lines to 120 chars (skips code blocks and risky lines).

Usage:
  python scripts/format_docs.py --check   # show files that would change
  python scripts/format_docs.py --write   # rewrite files in-place
"""

from __future__ import annotations

import argparse
import os
import shutil
import subprocess
import re
import sys
from typing import List


INDENT_SPACES = 2


MD_EXTS = {".md", ".mdx", ".markdown"}


def iter_doc_files(root: str) -> List[str]:
    files: List[str] = []
    for base, _dirs, fnames in os.walk(root):
        # Skip common build/output dirs if present
        parts = set(base.split(os.sep))
        if {"node_modules", ".git", ".next", "dist", "build", "archive"} & parts:
            continue
        for fn in fnames:
            _, ext = os.path.splitext(fn)
            if ext.lower() in MD_EXTS:
                files.append(os.path.join(base, fn))
    return files


FENCE_RE = re.compile(r"^\s*(```|~~~)")
HEADING_RE = re.compile(r"^\s{0,3}#{1,6} \S")
HR_RE = re.compile(r"^\s{0,3}(-{3,}|_{3,}|\*{3,})\s*$")
IMAGE_RE = re.compile(r"^\s*!\[[^\]]*\]\([^)]*\)")
LIST_RE = re.compile(r"^(?P<indent>\s*)(?P<marker>(?:[-+*]|\d+[.)]))\s+")
TABLE_RE = re.compile(r"\|.*\|")
BAD_NUM_LIST_RE = re.compile(r"^\s*\d+[.)](\S)")  # missing space after 1. or 1)
ANY_NUM_LIST_RE = re.compile(r"^\s*\d+[.)](?:\s|$)")  # any numbered list marker


BLOCK_COMPONENT_PREFIXES = (
    # Container-level components that should be surrounded by blank lines
    "<Steps",
    "</Steps",
    "<Accordion",
    "</Accordion",
    "<Image",
)


def is_code_fence(line: str) -> bool:
    return bool(FENCE_RE.match(line))


def is_heading(line: str) -> bool:
    return bool(HEADING_RE.match(line))


def is_hr(line: str) -> bool:
    return bool(HR_RE.match(line))


def is_image(line: str) -> bool:
    return bool(IMAGE_RE.match(line.strip()))


def is_block_component(line: str) -> bool:
    s = line.lstrip()
    return any(s.startswith(p) for p in BLOCK_COMPONENT_PREFIXES)


def normalize_indent(line: str) -> str:
    # Replace tabs with four spaces only at leading indentation
    if not line:
        return line
    # Split leading whitespace
    leading = len(line) - len(line.lstrip("\t "))
    prefix = line[:leading]
    suffix = line[leading:]
    prefix = prefix.replace("\t", " " * INDENT_SPACES)
    # For list items, ensure indent is a multiple of four spaces
    m = LIST_RE.match(prefix + suffix)
    if m:
        indent = m.group("indent")
        # Only spaces in indent by now
        spaces = len(indent)
        if spaces % INDENT_SPACES != 0:
            indent = " " * (spaces + (INDENT_SPACES - (spaces % INDENT_SPACES)))
        # Reconstruct with normalized indent and original rest
        marker = m.group("marker")
        rest = (prefix + suffix)[m.end():]
        return f"{indent}{marker} {rest}"
    return prefix + suffix


def merge_excess_blank_lines(lines: List[str]) -> List[str]:
    out: List[str] = []
    blank = False
    for ln in lines:
        if ln.strip() == "":
            if not blank:
                out.append("")
            blank = True
        else:
            out.append(ln)
            blank = False
    return out


def ensure_blank_lines_around_blocks(lines: List[str]) -> List[str]:
    out: List[str] = []
    in_code = False
    container_stack: List[str] = []
    n = len(lines)
    i = 0
    while i < n:
        line = lines[i]
        if is_code_fence(line):
            # Treat code fences like advisory blocks w.r.t. spacing
            if not in_code:
                # Opening fence: ensure a blank line before, but none immediately after
                # Suppress the blank line if previous non-empty line is an immediate child open (Step/AccordionItem/Card)
                suppress_before = False
                if len(out) > 0:
                    # Find previous non-empty output line
                    k = len(out) - 1
                    while k >= 0 and out[k].strip() == "":
                        k -= 1
                    if k >= 0:
                        prev = out[k].lstrip()
                        if prev.startswith("<Step") or prev.startswith("<AccordionItem") or prev.startswith("<Card") or prev.startswith("<Tab"):
                            suppress_before = True
                if len(out) > 0 and out[-1].strip() != "" and not suppress_before:
                    out.append("")
                out.append(line)
                in_code = True
                i += 1
                # Remove any immediate blank lines after the opening fence
                while i < n and lines[i].strip() == "":
                    i += 1
                continue
            else:
                # Closing fence: no blank immediately before, add one after (unless next is a closing tag)
                if len(out) > 0 and out[-1].strip() == "":
                    out.pop()
                out.append(line)
                in_code = False
                # Look ahead to next non-empty original line
                j = i + 1
                while j < n and lines[j].strip() == "":
                    j += 1
                next_is_closing_tag = j < n and lines[j].lstrip().startswith("</")
                if not next_is_closing_tag:
                    out.append("")
                i += 1
                # Skip multiple blanks following in input
                while i < n and lines[i].strip() == "":
                    i += 1
                continue

        def is_open_container(l: str) -> bool:
            s = l.lstrip()
            return (
                s.startswith("<Steps")
                or s.startswith("<Accordion")
                or s.startswith("<AccordionGroup")
                or s.startswith("<Columns")
                or s.startswith("<CardGroup")
                or s.startswith("<CodeGroup")
                or s.startswith("<Frame")
                or s.startswith("<Warning")
                or s.startswith("<Info")
                or s.startswith("<Tip")
                or s.startswith("<Note")
            )

        def is_close_container(l: str) -> bool:
            s = l.lstrip()
            return (
                s.startswith("</Steps")
                or s.startswith("</Accordion")
                or s.startswith("</AccordionGroup")
                or s.startswith("</Columns")
                or s.startswith("</CardGroup")
                or s.startswith("</CodeGroup")
                or s.startswith("</Frame")
                or s.startswith("</Warning")
                or s.startswith("</Info")
                or s.startswith("</Tip")
                or s.startswith("</Note")
            )

        if not in_code:
            # Handle single-line advisory blocks like <Warning> ... </Warning>
            s_line_full = line.lstrip()
            m_single_adv = None
            for _name in ("Warning", "Info", "Tip", "Note"):
                if s_line_full.startswith(f"<{_name}") and f"</{_name}>" in s_line_full:
                    m_single_adv = _name
                    break
            if m_single_adv:
                # Check previous non-empty line for parent exception
                prev_non_empty = None
                for k in range(len(out) - 1, -1, -1):
                    if out[k].strip() != "":
                        prev_non_empty = out[k]
                        break
                prev_is_parent = False
                if prev_non_empty is not None:
                    p = prev_non_empty.lstrip()
                    if p.startswith("<Step") or p.startswith("<Accordion") or p.startswith("<Card"):
                        prev_is_parent = True
                if len(out) > 0 and out[-1].strip() != "" and not prev_is_parent:
                    out.append("")
                # If there is an existing blank line before and we're directly after an opening parent, remove it
                if prev_is_parent and len(out) > 0 and out[-1].strip() == "":
                    out.pop()
                out.append(line)
                # Look ahead to next non-empty line; suppress blank if it's a closing tag
                j = i + 1
                while j < n and lines[j].strip() == "":
                    j += 1
                next_is_closing_tag = False
                if j < n:
                    next_is_closing_tag = lines[j].lstrip().startswith("</")
                if not next_is_closing_tag:
                    out.append("")
                i += 1
                continue
            if False and is_open_container(line):
                # Determine if this is an advisory tag
                s_line = line.lstrip()
                is_advisory = s_line.startswith("<Warning") or s_line.startswith("<Info") or s_line.startswith("<Tip") or s_line.startswith("<Note")
                # Check previous non-empty line
                prev_non_empty = None
                for k in range(len(out) - 1, -1, -1):
                    if out[k].strip() != "":
                        prev_non_empty = out[k]
                        break
                prev_is_parent = False
                if prev_non_empty is not None:
                    p = prev_non_empty.lstrip()
                    if p.startswith("<Step") or p.startswith("<Accordion") or p.startswith("<Card"):
                        prev_is_parent = True
                # Ensure a blank line before unless it's an advisory directly after Step/Accordion/Card
                if len(out) > 0 and out[-1].strip() != "" and not (is_advisory and prev_is_parent):
                    out.append("")
                # If advisory follows an opening parent, remove any pre-existing blank line
                if is_advisory and prev_is_parent and len(out) > 0 and out[-1].strip() == "":
                    out.pop()
                out.append(line)
                # Track which container opened
                name = s_line[1:].split(None, 1)[0].rstrip(">/")
                container_stack.append(name)
                i += 1
                # Remove any immediate blank lines after the opening tag
                while i < n and lines[i].strip() == "":
                    i += 1
                continue
            if is_close_container(line):
                # Remove any immediate blank line before the closing tag
                if len(out) > 0 and out[-1].strip() == "":
                    out.pop()
                out.append(line)
                # Pop matching container if present and detect if it's advisory
                closed_name = None
                if container_stack:
                    closed_name = container_stack.pop()
                # Advisory blocks should normally be followed by a blank line
                s_line = line.lstrip()
                is_advisory_close = (
                    (closed_name in {"Warning", "Info", "Tip", "Note"})
                    or s_line.startswith("</Warning")
                    or s_line.startswith("</Info")
                    or s_line.startswith("</Tip")
                    or s_line.startswith("</Note")
                )
                # Look ahead to next non-empty original line
                j = i + 1
                while j < n and lines[j].strip() == "":
                    j += 1
                next_is_closing_tag = False
                if j < n:
                    next_is_closing_tag = lines[j].lstrip().startswith("</")

                if is_advisory_close:
                    # Add a blank line unless the next non-empty line is also a closing tag
                    if not next_is_closing_tag:
                        out.append("")
                    # Consume successive blank lines in input
                    i += 1
                    while i < n and lines[i].strip() == "":
                        i += 1
                    continue
                else:
                    # For non-advisory containers, ensure a blank line after
                    # unless the next non-empty line is also a closing tag
                    if not next_is_closing_tag:
                        nxt = lines[i + 1] if i + 1 < n else None
                        if nxt is not None and nxt.strip() != "":
                            out.append("")
                    i += 1
                    continue
            # Suppress image blank-line rules inside a <Frame>
            inside_frame = bool(container_stack and container_stack[-1] == "Frame")
            is_markdown_img = is_image(line)
            is_mdx_image = line.lstrip().startswith("<Image") or line.lstrip().startswith("<img")
            if is_heading(line) or ((is_markdown_img or is_mdx_image) and not inside_frame) or (is_block_component(line) and not inside_frame):
                # Ensure blank before and after for other block-ish lines (e.g., images)
                if len(out) > 0 and out[-1].strip() != "":
                    prev_non_empty = None
                    for k in range(len(out) - 1, -1, -1):
                        if out[k].strip() != "":
                            prev_non_empty = out[k].lstrip()
                            break
                    suppress_before = False
                    if prev_non_empty is not None:
                        if prev_non_empty.startswith("<Step") or prev_non_empty.startswith("<AccordionItem") or prev_non_empty.startswith("<Card"):
                            suppress_before = True
                    if not suppress_before:
                        out.append("")
                out.append(line)
                # Decide whether to add a blank after
                add_blank_after = True
                # For images, suppress blank after if the next non-empty line is a closing Step/Accordion/AccordionItem
                if (is_markdown_img or is_mdx_image) and not inside_frame:
                    j2 = i + 1
                    while j2 < n and lines[j2].strip() == "":
                        j2 += 1
                    if j2 < n:
                        next_ne = lines[j2].lstrip()
                        if next_ne.startswith("</Step") or next_ne.startswith("</Accordion") or next_ne.startswith("</AccordionItem"):
                            add_blank_after = False
                if add_blank_after:
                    nxt = lines[i + 1] if i + 1 < n else None
                    if nxt is not None and nxt.strip() != "":
                        out.append("")
                i += 1
                continue

        out.append(line)
        i += 1

    return merge_excess_blank_lines(out)


OPEN_TAG_RE = re.compile(r"^\s*<(?P<name>\w+)(\s|>)")
CLOSE_TAG_RE = re.compile(r"^\s*</(?P<name>\w+)\s*>")


def normalize_steps_indentation(lines: List[str]) -> List[str]:
    """Normalize indentation and spacing for group containers and their items.

    Supports:
    - <Steps> with child <Step>
    - <Accordion> with child <AccordionItem>
    - <Columns> with child <Card>
    - <Tabs> with child <Tab>

    Rules:
    - Blank line before container open and after container close.
    - Inside container: child open/close aligned at container indent + INDENT_SPACES.
    - Content inside child is indented one more level.
    - Remove blank lines immediately after child open and before child close.
    - Ensure exactly one blank line between sibling children; none before container close.
    """
    out: List[str] = []
    in_code = False
    # Stack of (name, indent, managed)
    stack: List[tuple[str, int, bool]] = []

    # Group to child mapping
    children_for = {
        "Steps": {"Step"},
        "Accordion": {"AccordionItem"},
        "AccordionGroup": {"Accordion"},
        "Columns": {"Card"},
        "CardGroup": {"Card"},
        "Tabs": {"Tab"},
    }

    SELF_CLOSING_RE = re.compile(r"^\s*<(?P<name>\w+)(?:[^>]*)/?>\s*$")

    i = 0
    n = len(lines)
    while i < n:
        line = lines[i]

        # Handle code fences
        if is_code_fence(line):
            in_code = not in_code
            out.append(line)
            i += 1
            continue
        if in_code:
            out.append(line)
            i += 1
            continue

        stripped = line.lstrip(" ")
        leading = len(line) - len(stripped)

        # Detect opening/closing tags
        m_open = OPEN_TAG_RE.match(line)
        m_close = CLOSE_TAG_RE.match(line)

        # Opening group containers
        if m_open and m_open.group("name") in children_for:
            # If nested inside a managed child (e.g., <Tab>/<Step>), align the container
            # as a content line inside that child.
            desired_leading = leading
            if stack:
                top_name, top_indent, _top_managed = stack[-1]
                # If the immediate parent is not a group container, treat it as a child-item.
                if top_name not in children_for:
                    desired_leading = top_indent + INDENT_SPACES
            # Ensure a blank line before
            if len(out) > 0 and out[-1].strip() != "":
                prev_non_empty = None
                for k in range(len(out) - 1, -1, -1):
                    if out[k].strip() != "":
                        prev_non_empty = out[k].lstrip()
                        break
                suppress_before = False
                if prev_non_empty is not None:
                    if prev_non_empty.startswith("<Step") or prev_non_empty.startswith("<AccordionItem") or prev_non_empty.startswith("<Card") or prev_non_empty.startswith("<Tab"):
                        suppress_before = True
                if not suppress_before:
                    out.append("")
            # Normalize indent of <Steps> tag itself (retain current leading)
            out.append(" " * desired_leading + stripped)
            stack.append((m_open.group("name"), desired_leading, True))
            # Skip immediate blank lines after opening
            i += 1
            while i < n and lines[i].strip() == "":
                i += 1
            continue

        # Closing group containers
        if m_close and m_close.group("name") in children_for:
            # Align to stored indent if available
            cont_indent = leading
            for name, ind, _managed in reversed(stack):
                if name == m_close.group("name"):
                    cont_indent = ind
                    break
            # Remove preceding blank if any
            if len(out) > 0 and out[-1].strip() == "":
                out.pop()
            out.append(" " * cont_indent + stripped)
            # Pop matching container
            for j in range(len(stack) - 1, -1, -1):
                if stack[j][0] == m_close.group("name"):
                    stack.pop(j)
                    break
            # Ensure exactly one blank line after
            out.append("")
            i += 1
            # Skip multiple blanks following
            while i < n and lines[i].strip() == "":
                i += 1
            continue

        # Opening child items
        if m_open and stack and m_open.group("name") in children_for.get(stack[-1][0], set()):
            parent_indent = stack[-1][1]
            child_indent = parent_indent + INDENT_SPACES
            is_self_closing_child = stripped.endswith("/>")
            out.append(" " * child_indent + stripped)
            if not is_self_closing_child:
                stack.append((m_open.group("name"), child_indent, True))
            # Skip immediate blank lines after child open
            i += 1
            while i < n and lines[i].strip() == "":
                i += 1
            # For self-closing children, add spacing similar to explicit close handling
            if is_self_closing_child:
                jn = i
                while jn < n and lines[jn].strip() == "":
                    jn += 1
                if jn < n:
                    next_lstrip = lines[jn].lstrip()
                    if not next_lstrip.startswith("</"):
                        out.append("")
            continue

        # Closing child items
        if m_close and m_close.group("name") in {"Step", "AccordionItem", "Card", "Tab"}:
            # Align to stored child indent
            child_indent = leading
            for name, ind, _managed in reversed(stack):
                if name == m_close.group("name"):
                    child_indent = ind
                    break
            # Remove preceding blank if any
            if len(out) > 0 and out[-1].strip() == "":
                out.pop()
            out.append(" " * child_indent + stripped)
            # Pop child
            for j in range(len(stack) - 1, -1, -1):
                if stack[j][0] == m_close.group("name"):
                    stack.pop(j)
                    break
            # Ensure spacing after child close:
            # - No blank before container close (next non-empty starts with </)
            # - Add one blank if the next non-empty is any opening tag or text (including imported snippets)
            jn = i + 1
            while jn < n and lines[jn].strip() == "":
                jn += 1
            if jn < n:
                next_lstrip = lines[jn].lstrip()
                if not next_lstrip.startswith("</"):
                    out.append("")
            i += 1
            # Skip any blank lines immediately after; our insertion above already handled spacing
            while i < n and lines[i].strip() == "":
                i += 1
            continue

        # Content lines: if inside a managed child (<Step>/<AccordionItem>/<Card>), indent by one more level
        inside_child = None
        managed_child = False
        for name, ind, managed in reversed(stack):
            if name in {"Step", "Accordion", "AccordionGroup", "AccordionItem", "Card", "Tab"}:
                inside_child = ind
                managed_child = managed
                break
        if inside_child is not None and stripped != "":
            if managed_child:
                if stripped.startswith("#"):
                    # Headings should always align to the left margin even inside managed containers
                    out.append(stripped)
                else:
                    content_indent = inside_child + INDENT_SPACES
                    out.append(" " * content_indent + stripped)
            else:
                out.append(line)
            i += 1
            continue

        # Self-closing component treated as child within group containers
        m_sc = SELF_CLOSING_RE.match(line)
        if m_sc and stack:
            parent_name, parent_indent, _ = stack[-1]
            # Only treat as child if parent is a known group container and this isn't a group close/open mismatch
            if parent_name in children_for and not stripped.startswith("</") and not stripped.startswith("<" + parent_name):
                child_indent = parent_indent + INDENT_SPACES
                out.append(" " * child_indent + stripped)
                # Ensure spacing after this pseudo-child: add one blank unless next is a closing container
                jn = i + 1
                while jn < n and lines[jn].strip() == "":
                    jn += 1
                if jn < n:
                    next_lstrip = lines[jn].lstrip()
                    if not next_lstrip.startswith("</"):
                        out.append("")
                i += 1
                # Skip subsequent blank lines in input to avoid duplicates
                while i < n and lines[i].strip() == "":
                    i += 1
                continue

        # Default: passthrough
        out.append(line)
        i += 1

    return merge_excess_blank_lines(out)


def wrap_line_to_width(line: str, width: int) -> List[str]:
    # Identify simple list prefix
    m = LIST_RE.match(line)
    if m:
        indent = m.group("indent")
        marker = m.group("marker")
        rest = line[m.end():]
        # Avoid wrapping risky content
        if ("`" in rest) or ("|" in rest) or ("<" in rest) or ("http" in rest):
            return [line]
        fill_width = max(20, width)  # safety
        eff_width = fill_width - len(indent) - len(marker) - 1
        lines = wrap_text_with_punct_preference(rest.strip(), eff_width)
        result = [f"{indent}{marker} {lines[0]}"]
        cont_indent = " " * (len(indent) + len(marker) + 1)
        for seg in lines[1:]:
            result.append(f"{cont_indent}{seg}")
        return result

    # Plain text line
    s = line.strip()
    if not s:
        return [line]
    if is_heading(line) or is_hr(line):
        return [line]
    if TABLE_RE.search(line):
        return [line]
    if line.lstrip().startswith(("<", ">")):
        return [line]

    # Preserve original left padding for paragraphs
    pad = len(line) - len(line.lstrip(" "))
    prefix = " " * pad
    wrapped_lines = wrap_text_with_punct_preference(s, width - pad)
    return [prefix + seg for seg in wrapped_lines]


def wrap_text_with_punct_preference(text: str, width: int) -> List[str]:
    """Wrap text preferring breaks after punctuation when possible.

    Does not break long words; if a single token exceeds width, it is placed on its own line.
    """
    if width <= 0:
        return [text]
    words = text.split()
    if not words:
        return [""]
    lines: List[str] = []
    cur_len = 0
    cur_words: List[str] = []
    last_punct_idx: int | None = None

    def is_punct_ending(w: str) -> bool:
        return bool(re.search(r"[\.,;:!\?\)\]\}]$", w))

    for w in words:
        if not cur_words:
            cur_words.append(w)
            cur_len = len(w)
            last_punct_idx = 1 if is_punct_ending(w) else None
            continue
        if cur_len + 1 + len(w) <= width:
            cur_words.append(w)
            cur_len += 1 + len(w)
            if is_punct_ending(w):
                last_punct_idx = len(cur_words)
            continue
        # Would overflow
        if last_punct_idx and last_punct_idx < len(cur_words) + 1:
            # Break at last punctuation within current words
            lines.append(" ".join(cur_words[: last_punct_idx]))
            # Remaining words include those after the break; current w not yet added
            remainder = cur_words[last_punct_idx:]
            cur_words = remainder or []
            cur_len = len(" ".join(cur_words)) if cur_words else 0
            last_punct_idx = None
            # Reprocess current word in next iteration by simulating step back
            if not cur_words:
                # start new line with w
                cur_words = [w]
                cur_len = len(w)
                last_punct_idx = 1 if is_punct_ending(w) else None
            else:
                # Try to add w now if it fits, otherwise force line
                if cur_len + (1 if cur_words else 0) + len(w) <= width:
                    cur_words.append(w)
                    cur_len += 1 + len(w)
                    if is_punct_ending(w):
                        last_punct_idx = len(cur_words)
                else:
                    # Flush current as is
                    lines.append(" ".join(cur_words))
                    cur_words = [w]
                    cur_len = len(w)
                    last_punct_idx = 1 if is_punct_ending(w) else None
            continue
        # No punctuation to break at: break at last whitespace (i.e., before this word)
        if cur_words:
            lines.append(" ".join(cur_words))
        cur_words = [w]
        cur_len = len(w)
        last_punct_idx = 1 if is_punct_ending(w) else None

    if cur_words:
        lines.append(" ".join(cur_words))
    return lines


def wrap_long_lines(lines: List[str], width: int) -> List[str]:
    """Reflow and wrap paragraphs to the target width.

    - Operates outside of fenced code blocks.
    - Preserves headings, tables, MDX/HTML tag lines as-is and treats them as paragraph boundaries.
    - Handles list items with list-aware wrapping, keeping continuation indentation.
    - For plain paragraphs, collapses internal newlines and rewraps to the target width.
    """
    out: List[str] = []
    in_code = False
    in_frontmatter = False
    para: List[str] = []

    def flush_para():
        nonlocal para
        if not para:
            return
        # Determine minimal left padding among non-empty lines
        pads = [len(p) - len(p.lstrip(" ")) for p in para if p.strip()]
        pad = min(pads) if pads else 0
        prefix = " " * pad
        # Build paragraph text by joining with spaces
        text = " ".join(p.strip() for p in para).strip()
        if not text:
            out.append("")
        else:
            wrapped_lines = wrap_text_with_punct_preference(text, max(20, width - pad))
            out.extend(prefix + seg for seg in wrapped_lines)
        para = []

    for ln in lines:
        # YAML frontmatter guard (only at file start)
        if not out and not para and ln.strip() == "---":
            in_frontmatter = True
            out.append(ln)
            continue
        if in_frontmatter:
            out.append(ln)
            if ln.strip() == "---":
                in_frontmatter = False
            continue

        if is_code_fence(ln):
            flush_para()
            in_code = not in_code
            out.append(ln)
            continue
        if in_code:
            out.append(ln)
            continue

        stripped = ln.strip()
        if stripped == "":
            flush_para()
            out.append("")
            continue

        # Boundaries and special lines
        stripped_l = ln.lstrip()
        if is_heading(ln) or is_hr(ln) or TABLE_RE.search(ln) or stripped_l.startswith(("<", ">")) or stripped_l.startswith("import ") or stripped_l.startswith("export "):
            flush_para()
            out.append(ln)
            continue

        # List items are handled individually to preserve markers and continuation indentation
        if LIST_RE.match(ln):
            flush_para()
            out.extend(wrap_line_to_width(ln, width))
            continue

        # Accumulate paragraph text
        para.append(ln)

    flush_para()
    return out


def format_content(text: str, width: int) -> str:
    # Repair accidentally inlined YAML frontmatter keys (if present)
    def fix_frontmatter(blob: str) -> str:
        if not blob.startswith("---\n"):
            return blob
        end = blob.find("\n---", 4)
        if end == -1:
            return blob
        header = blob[4:end]
        # If any line contains more than one key pattern, split them
        # Insert a newline before key-like tokens that follow spaces on the same line
        fixed_header = re.sub(r"(?<!\n)\s+([A-Za-z_][\w-]*:\s*)", r"\n\1", header)
        # Collapse wrapped values for common fields onto one line
        lines = [ln for ln in fixed_header.splitlines() if ln.strip() != ""]
        out_lines: List[str] = []
        current_key = None
        current_val_parts: List[str] = []
        def flush_kv():
            nonlocal current_key, current_val_parts
            if current_key is None:
                return
            value = " ".join(s.strip() for s in current_val_parts).strip()
            value_norm = value.replace('\\"', '"')
            # If the value became double-quoted at both ends (e.g., ""Text""), collapse to single quotes
            if value_norm.startswith('""') and value_norm.endswith('""') and len(value_norm) >= 4:
                value_norm = value_norm[1:-1]
            # Check if value is a boolean (true/false) - don't quote these
            if value_norm.lower() in ('true', 'false'):
                value_quoted = value_norm.lower()
            # Keep existing quotes if already quoted; otherwise quote with double quotes
            elif (len(value_norm) >= 2 and ((value_norm.startswith('"') and value_norm.endswith('"')) or (value_norm.startswith("'") and value_norm.endswith("'")))):
                value_quoted = value_norm
            else:
                value_quoted = '"' + value_norm.replace('"', '\\"') + '"'
            out_lines.append(f"{current_key}: {value_quoted}")
            current_key = None
            current_val_parts = []
        for ln in lines:
            m = re.match(r"^([A-Za-z_][\w-]*):\s*(.*)$", ln)
            if m:
                # New key
                flush_kv()
                current_key = m.group(1)
                rest = m.group(2)
                current_val_parts = [rest] if rest is not None else []
            else:
                # Continuation line for previous key
                if current_key is not None:
                    current_val_parts.append(ln)
                else:
                    out_lines.append(ln)
        flush_kv()
        rebuilt = "\n".join(out_lines)
        return "---\n" + rebuilt.strip("\n") + blob[end:]

    text = fix_frontmatter(text)

    # Split preserving line endings as \n
    raw_lines = text.splitlines()

    # 1) Normalize indentation (outside code blocks)
    lines: List[str] = []
    in_code = False
    for ln in raw_lines:
        if is_code_fence(ln):
            in_code = not in_code
            lines.append(ln)  # Don't normalize fence lines themselves
            continue
        if in_code:
            lines.append(ln)  # Don't normalize lines inside code blocks
        else:
            lines.append(normalize_indent(ln))  # Only normalize outside code blocks

    # 2) Dedent common leading margin across the file (outside code and frontmatter)
    def dedent_common_margin(ls: List[str]) -> List[str]:
        out_ls: List[str] = []
        in_code_f = False
        in_front = False
        # Compute minimal leading spaces among relevant lines
        mins: List[int] = []
        for i, l in enumerate(ls):
            if i == 0 and l.strip() == "---":
                in_front = True
            elif in_front and l.strip() == "---":
                in_front = False
            if is_code_fence(l):
                in_code_f = not in_code_f
                continue
            if in_code_f or in_front:
                continue
            if l.strip() == "":
                continue
            # count spaces only
            lead = len(l) - len(l.lstrip(" "))
            mins.append(lead)
        if not mins:
            return ls
        common = min(mins)
        if common <= 0:
            return ls
        for l in ls:
            # Only trim spaces, not tabs (tabs already normalized earlier)
            if l.startswith(" " * common):
                out_ls.append(l[common:])
            else:
                out_ls.append(l)
        return out_ls

    lines = dedent_common_margin(lines)

    # 3) Normalize <Steps>/<Step> indentation and spacing
    lines = normalize_steps_indentation(lines)

    # 4) Expand single-line advisory tags (<Warning>/<Info>/<Tip>/<Note>) to multi-line with indented content
    def expand_single_line_advisories(ls: List[str]) -> List[str]:
        out_ls: List[str] = []
        in_code_f = False
        pat = re.compile(r"^(?P<indent>\s*)<(?P<name>Warning|Info|Tip|Note)(?P<attrs>[^>]*)>(?P<inner>.*?)</(?P=name)>\s*$")
        for ln in ls:
            if is_code_fence(ln):
                in_code_f = not in_code_f
                out_ls.append(ln)
                continue
            if in_code_f:
                out_ls.append(ln)
                continue
            m = pat.match(ln)
            if m:
                indent = m.group("indent")
                name = m.group("name")
                attrs = m.group("attrs") or ""
                inner = m.group("inner").strip()
                out_ls.append(f"{indent}<{name}{attrs}>")
                out_ls.append(f"{indent}{' ' * INDENT_SPACES}{inner}")
                out_ls.append(f"{indent}</{name}>")
            else:
                out_ls.append(ln)
        return out_ls

    lines = expand_single_line_advisories(lines)

    # 5) Normalize indentation of content inside specific containers
    def normalize_inner_indentation(ls: List[str]) -> List[str]:
        target_names = {"Warning", "Info", "Tip", "Note", "Frame", "CodeGroup"}
        out_ls: List[str] = []
        in_code_f = False
        stack: List[tuple[str, int]] = []  # (name, base_indent)
        for ln in ls:
            if is_code_fence(ln):
                in_code_f = not in_code_f
                s_cf = ln.lstrip(" ")
                # Indent code fence lines when inside CodeGroup
                if stack and stack[-1][0] == "CodeGroup":
                    base = stack[-1][1]
                    desired = base + INDENT_SPACES
                    out_ls.append(" " * desired + s_cf)
                else:
                    out_ls.append(ln)
                continue
            if in_code_f:
                # While inside a fenced code block: never modify content, preserve exactly as-is
                out_ls.append(ln)
                continue

            s = ln.lstrip(" ")
            leading = len(ln) - len(s)

            m_open = OPEN_TAG_RE.match(ln)
            m_close = CLOSE_TAG_RE.match(ln)

            if m_open and m_open.group("name") in target_names:
                out_ls.append(" " * leading + s)
                stack.append((m_open.group("name"), leading))
                continue

            if m_close and stack and m_close.group("name") == stack[-1][0]:
                name, base = stack.pop()
                out_ls.append(" " * base + s)
                continue

            if stack:
                # Inside one of the target containers: enforce indent for content lines
                name, base = stack[-1]
                if s.strip() == "":
                    out_ls.append("")
                else:
                    desired = base + INDENT_SPACES
                    out_ls.append(" " * desired + s)
            else:
                out_ls.append(ln)

        return out_ls

    lines = normalize_inner_indentation(lines)

    # 6) Enforce blank lines around container-level blocks
    lines = ensure_blank_lines_around_blocks(lines)

    # 6.5) Normalize MDX import/export lines and fix merged imports
    def normalize_mdx_imports(ls: List[str]) -> List[str]:
        out_ls: List[str] = []
        in_code_f = False
        imp_pat = re.compile(r"\bimport\s+[^\n\r;]*?\s+from\s+['\"][^'\"]+['\"]")
        for ln in ls:
            if is_code_fence(ln):
                in_code_f = not in_code_f
                out_ls.append(ln)
                continue
            if in_code_f:
                out_ls.append(ln)
                continue
            s = ln.lstrip()
            lead = ln[: len(ln) - len(s)]
            if s.startswith("import "):
                parts = imp_pat.findall(s)
                if parts and len(parts) > 1:
                    for p in parts:
                        out_ls.append(lead + p)
                    continue
            # Repair lines missing 'import' due to previous wrapping, e.g., 'Name from "..."'
            if re.match(r"^[A-Za-z_][\w]*\s+from\s+['\"]", s):
                out_ls.append(lead + "import " + s)
                continue
            out_ls.append(ln)
        return out_ls

    lines = normalize_mdx_imports(lines)

    # 6.7) Remove any blank line immediately after group container opens
    def remove_blank_after_group_opens(ls: List[str]) -> List[str]:
        out_ls: List[str] = []
        in_code_f = False
        opens = ("<Steps", "<AccordionGroup", "<Accordion", "<Columns", "<CardGroup", "<CodeGroup", "<Tabs", "<Tab")
        i2 = 0
        n2 = len(ls)
        while i2 < n2:
            cur = ls[i2]
            if is_code_fence(cur):
                in_code_f = not in_code_f
                out_ls.append(cur)
                i2 += 1
                continue
            if not in_code_f and cur.lstrip().startswith(opens):
                out_ls.append(cur)
                # Skip exactly one following blank line if present
                j2 = i2 + 1
                if j2 < n2 and ls[j2].strip() == "":
                    i2 = j2 + 1
                    continue
                i2 += 1
                continue
            out_ls.append(cur)
            i2 += 1
        return out_ls

    lines = remove_blank_after_group_opens(lines)

    # 6.8) Normalize img tag format: className first, then src, then alt, then other attributes
    def normalize_img_tags(ls: List[str]) -> List[str]:
        out_ls: List[str] = []
        in_code_f = False
        # Pattern to match complete img tag (handles multi-line by joining)
        # Match: <img ... /> or <img ... >
        img_start_pattern = re.compile(r"<img\s+", re.IGNORECASE)
        # Pattern to extract all attribute values: attr="value" or attr='value' or attr={value}
        # For JSX-style attributes with nested braces, we need a more sophisticated approach
        def extract_attributes(content: str) -> dict[str, str]:
            """Extract all attributes from an img tag, handling both quoted and JSX-style attributes."""
            attrs: dict[str, str] = {}
            # Pattern for quoted attributes: attr="value" or attr='value'
            quoted_pattern = re.compile(r'(\w+)\s*=\s*(["\'])([^"\']*)\2', re.IGNORECASE)
            for match in quoted_pattern.finditer(content):
                attr_name = match.group(1).lower()
                quote_char = match.group(2)
                attr_value = match.group(3)
                attrs[attr_name] = f'{quote_char}{attr_value}{quote_char}'
            
            # Pattern for JSX-style attributes: attr={...}
            # We need to handle nested braces, so we'll find the opening { and match the closing }
            jsx_pattern = re.compile(r'(\w+)\s*=\s*(\{)', re.IGNORECASE)
            pos = 0
            while True:
                match = jsx_pattern.search(content, pos)
                if not match:
                    break
                attr_name = match.group(1).lower()
                brace_start = match.start(2)
                # Find matching closing brace
                brace_count = 0
                brace_end = brace_start
                for i in range(brace_start, len(content)):
                    if content[i] == '{':
                        brace_count += 1
                    elif content[i] == '}':
                        brace_count -= 1
                        if brace_count == 0:
                            brace_end = i
                            break
                if brace_count == 0:
                    attr_value = content[brace_start:brace_end + 1]
                    attrs[attr_name] = attr_value
                pos = brace_end + 1
            
            return attrs
        
        i = 0
        n = len(ls)
        while i < n:
            ln = ls[i]
            if is_code_fence(ln):
                in_code_f = not in_code_f
                out_ls.append(ln)
                i += 1
                continue
            if in_code_f:
                out_ls.append(ln)
                i += 1
                continue
            
            stripped = ln.lstrip()
            leading = len(ln) - len(stripped)
            
            # Check if line starts with <img
            if img_start_pattern.match(stripped):
                # Collect the full img tag (may span multiple lines)
                # Only collect lines that are part of the img tag, not blank lines or other tags
                img_parts = [stripped]
                j = i + 1
                tag_closed = False
                
                # Check if tag is already closed on this line (ends with /> or >)
                stripped_rstrip = stripped.rstrip()
                if stripped_rstrip.endswith("/>") or stripped_rstrip.endswith(">"):
                    tag_closed = True
                
                # Collect continuation lines until tag is closed
                # Stop immediately if we hit a blank line, code fence, or other tag
                while j < n and not tag_closed:
                    if is_code_fence(ls[j]):
                        break
                    # Stop if we hit a blank line (img tag shouldn't span blank lines)
                    if ls[j].strip() == "":
                        break
                    next_line = ls[j].lstrip()
                    # Stop if next line starts a new tag or component (but allow if it's another img tag continuation)
                    if next_line.startswith("<"):
                        # If it's not an img tag, stop collecting - this line is NOT part of the img tag
                        if not img_start_pattern.match(next_line):
                            break
                    # This line is part of the img tag, add it
                    img_parts.append(next_line)
                    next_rstrip = next_line.rstrip()
                    if next_rstrip.endswith("/>") or next_rstrip.endswith(">"):
                        tag_closed = True
                        break
                    j += 1
                
                # Join all parts into a single string for processing
                img_content = " ".join(img_parts)
                
                # Extract all attributes using the helper function
                attrs = extract_attributes(img_content)
                
                # Extract values for required attributes
                className_val = None
                class_val = None  # fallback for "class" attribute
                src_val = None
                alt_val = None
                
                for attr_name, attr_value in attrs.items():
                    if attr_name == "classname":
                        # Extract value, handling both quoted and JSX-style
                        if attr_value.startswith("{") and attr_value.endswith("}"):
                            className_val = attr_value[1:-1].strip().strip('"').strip("'")
                        else:
                            className_val = attr_value.strip('"').strip("'")
                    elif attr_name == "class":
                        if attr_value.startswith("{") and attr_value.endswith("}"):
                            class_val = attr_value[1:-1].strip().strip('"').strip("'")
                        else:
                            class_val = attr_value.strip('"').strip("'")
                    elif attr_name == "src":
                        if attr_value.startswith("{") and attr_value.endswith("}"):
                            src_val = attr_value[1:-1].strip().strip('"').strip("'")
                        else:
                            src_val = attr_value.strip('"').strip("'")
                    elif attr_name == "alt":
                        if attr_value.startswith("{") and attr_value.endswith("}"):
                            alt_val = attr_value[1:-1].strip().strip('"').strip("'")
                        else:
                            alt_val = attr_value.strip('"').strip("'")
                
                # Use className if available, otherwise fall back to class
                if not className_val and class_val:
                    className_val = class_val
                    # Update attrs dict to use className instead of class
                    if "classname" not in attrs:
                        attrs["classname"] = attrs.pop("class", f'"{class_val}"')
                
                # Build normalized img tag if we have all required attributes
                if className_val and src_val and alt_val:
                    # Determine closing style
                    is_self_closing = "/>" in img_content
                    closing = "/>" if is_self_closing else ">"
                    
                    # Build attribute list: className first, then src, then alt, then others
                    attr_parts = []
                    # Add className first
                    if "classname" in attrs:
                        attr_parts.append(f'className={attrs["classname"]}')
                    # Add src second
                    if "src" in attrs:
                        attr_parts.append(f'src={attrs["src"]}')
                    # Add alt third
                    if "alt" in attrs:
                        attr_parts.append(f'alt={attrs["alt"]}')
                    # Add all other attributes (preserve original order)
                    for attr_name, attr_value in attrs.items():
                        if attr_name not in {"classname", "class", "src", "alt"}:
                            attr_parts.append(f'{attr_name}={attr_value}')
                    
                    normalized = f'<img {" ".join(attr_parts)} {closing}'.replace(" />", "/>").replace(" >", ">")
                    out_ls.append(" " * leading + normalized)
                    # IMPORTANT: j points to the first line AFTER the img tag
                    # This could be a blank line, closing tag like </Step>, or another element
                    # We set i = j so the next iteration processes that line normally
                    i = j
                else:
                    # If any required attribute is missing, keep original lines
                    # Output all lines from i to j-1 (the img tag lines)
                    for k in range(i, j):
                        out_ls.append(ls[k])
                    # Move to line j (first line after img tag)
                    i = j
            else:
                # Not an img tag line, preserve as-is
                out_ls.append(ln)
                i += 1
        
        return out_ls

    lines = normalize_img_tags(lines)

    # 7) Wrap long lines (outside code blocks)
    lines = wrap_long_lines(lines, width)

    # 8) Remove trailing whitespace on every line
    def strip_trailing_ws(ls: List[str]) -> List[str]:
        return [l.rstrip() for l in ls]

    lines = strip_trailing_ws(lines)

    # Always ensure exactly one trailing newline at EOF
    return ("\n".join(lines)).rstrip("\n") + "\n"


def process_file(path: str, write: bool, width: int) -> bool:
    try:
        with open(path, "r", encoding="utf-8") as f:
            original = f.read()
    except UnicodeDecodeError:
        # Skip non-UTF8 files
        return False

    formatted = format_content(original, width)
    if formatted != original:
        if write:
            with open(path, "w", encoding="utf-8", newline="\n") as f:
                f.write(formatted)
        return True
    return False


def find_numbered_list_spacing_warnings(path: str, text: str) -> List[tuple[int, str]]:
    warnings: List[tuple[int, str]] = []
    in_code = False
    for idx, ln in enumerate(text.splitlines(), start=1):
        if is_code_fence(ln):
            in_code = not in_code
            continue
        if in_code:
            continue
        # Ignore MDX/HTML lines and tables
        if ln.lstrip().startswith(("<", ">")):
            continue
        if TABLE_RE.search(ln):
            continue
        m = BAD_NUM_LIST_RE.match(ln)
        if m:
            # m.group(1) is the first non-space char after the marker
            warnings.append((idx, ln.rstrip()))
    return warnings


def find_numbered_list_occurrences(path: str, text: str) -> List[tuple[int, str]]:
    found: List[tuple[int, str]] = []
    in_code = False
    for idx, ln in enumerate(text.splitlines(), start=1):
        if is_code_fence(ln):
            in_code = not in_code
            continue
        if in_code:
            continue
        # Ignore MDX/HTML lines and tables
        if ln.lstrip().startswith(("<", ">")):
            continue
        if TABLE_RE.search(ln):
            continue
        if ANY_NUM_LIST_RE.match(ln):
            found.append((idx, ln.rstrip()))
    return found


def run_mintlify_broken_links(root: str) -> int:
    """Attempt to run `mintlify broken-links` and print its output.

    Returns the subprocess return code if executed, otherwise 0.
    """
    mintlify = shutil.which("mintlify")
    if not mintlify:
        print("mintlify CLI not found. Skipping 'mintlify broken-links'.")
        print("Install with: npm i -g mintlify")
        return 0
    try:
        print("Running: mintlify broken-links")
        proc = subprocess.run(
            [mintlify, "broken-links"],
            cwd=root,
            capture_output=True,
            text=True,
        )
        # Forward stdout/stderr to user
        if proc.stdout:
            print(proc.stdout.rstrip())
        if proc.stderr:
            print(proc.stderr.rstrip(), file=sys.stderr)
        return proc.returncode
    except Exception as e:
        print(f"Failed to run mintlify broken-links: {e}")
        return 1


LINK_MD_RE = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
IMG_MD_RE = re.compile(r"!\[[^\]]*\]\(([^)]+)\)")
IMG_MDX_RE = re.compile(r"<(?:img|Image)[^>]*\s+src=\"([^\"]+)\"[\s\S]*?/?>")


def fallback_broken_asset_check(root: str, path: str, text: str) -> List[tuple[int, str, str]]:
    """Simple local-asset existence check for links/images when mintlify is unavailable.

    Returns list of (line_number, kind, target) for missing local targets.
    Only checks paths that look local (start with '/' or relative paths without schema).
    """
    results: List[tuple[int, str, str]] = []
    in_code = False
    for idx, ln in enumerate(text.splitlines(), start=1):
        if is_code_fence(ln):
            in_code = not in_code
            continue
        if in_code:
            continue
        # Collect candidates from Markdown links/images
        targets: List[tuple[str, str]] = []  # (kind, target)
        for m in IMG_MD_RE.finditer(ln):
            targets.append(("image", m.group(1)))
        for m in LINK_MD_RE.finditer(ln):
            targets.append(("link", m.group(1)))
        for m in IMG_MDX_RE.finditer(ln):
            targets.append(("image", m.group(1)))

        for kind, target in targets:
            t = target.strip()
            # Skip anchors and mailto and http(s)
            if t.startswith("#") or "://" in t or t.startswith("mailto:"):
                continue
            # Normalize path
            if t.startswith("/"):
                candidate = os.path.join(root, t.lstrip("/"))
            else:
                candidate = os.path.join(os.path.dirname(os.path.join(root, path)), t)
            if not os.path.exists(candidate):
                results.append((idx, kind, t))
    return results


def main() -> int:
    parser = argparse.ArgumentParser(description="Format Markdown/MDX docs")
    parser.add_argument("--check", action="store_true", help="Only report files that would change")
    parser.add_argument("--write", action="store_true", help="Write changes to files")
    parser.add_argument("--width", type=int, default=120, help="Wrap width for text lines")
    parser.add_argument(
        "--paths",
        nargs="*",
        default=[],
        help="Optional list of files/directories to format (defaults to entire repo).",
    )
    # Link checks always run; flag retained for compatibility but ignored
    parser.add_argument("--check-links", action="store_true", help=argparse.SUPPRESS)
    args = parser.parse_args()

    if not args.check and not args.write:
        print("Specify --check or --write", file=sys.stderr)
        return 2

    root = os.getcwd()
    if args.paths:
        files: List[str] = []
        for p in args.paths:
            abspath = os.path.abspath(p)
            if os.path.isdir(abspath):
                files.extend(iter_doc_files(abspath))
            else:
                files.append(abspath)
    else:
        files = iter_doc_files(root)
    changed: List[str] = []
    numbered_list_warnings: List[tuple[str, int, str]] = []
    numbered_list_found: List[tuple[str, int, str]] = []
    frontmatter_icon_warnings: List[str] = []
    for p in files:
        try:
            with open(p, "r", encoding="utf-8") as f:
                original = f.read()
        except UnicodeDecodeError:
            original = ""
        if original:
            # Frontmatter icon check (skip for admins/connectors/* pages)
            if original.startswith("---\n"):
                end = original.find("\n---", 4)
                if end != -1:
                    header = original[4:end]
                    has_icon = any(re.match(r"^icon:\s*", ln.strip()) for ln in header.splitlines())
                    rel = os.path.relpath(p, root).replace("\\", "/")
                    is_exempt = (
                        rel.startswith("admins/connectors/")
                        or rel.startswith("snippets/")
                        or rel.startswith("developers/api_reference/")
                        or rel.startswith("deployment/cloud/aws")
                    )
                    if not has_icon and not is_exempt:
                        frontmatter_icon_warnings.append(p)
            for ln_no, ln_text in find_numbered_list_spacing_warnings(p, original):
                numbered_list_warnings.append((p, ln_no, ln_text))
            for ln_no, ln_text in find_numbered_list_occurrences(p, original):
                numbered_list_found.append((p, ln_no, ln_text))
        if process_file(p, write=args.write, width=args.width):
            changed.append(p)

    # Emit numbered list warnings (informational, non-fatal)
    if numbered_list_found:
        print("Numbered lists detected (consider using <Steps>/<Step> where appropriate):")
        for p, ln_no, ln_text in numbered_list_found:
            print(f"  {p}:{ln_no}: '{ln_text}'")
    # Emit numbered list spacing warnings (missing space after numeric marker)
    if numbered_list_warnings:
        print("Numbered list spacing warnings (missing space after numeric marker):")
        for p, ln_no, ln_text in numbered_list_warnings:
            print(f"  {p}:{ln_no}: '{ln_text}'")

    if frontmatter_icon_warnings:
        print("Frontmatter warnings: missing 'icon' field (all pages should have icons):")
        for p in frontmatter_icon_warnings:
            print(f"  {p}")

    # Always run link check via mintlify if available (no fallback)
    rc = run_mintlify_broken_links(root)
    if rc != 0:
        print(f"mintlify broken-links exited with code {rc}")

    if args.check:
        if changed:
            print(f"{len(changed)} file(s) would be reformatted:")
            for p in changed:
                print(p)
            return 1
        else:
            print("All files are correctly formatted.")
            return 0
    else:
        print(f"Reformatted {len(changed)} file(s).")
        return 0


if __name__ == "__main__":
    raise SystemExit(main())