mdtool.py

#!/usr/bin/env python3
"""
mdtool -- Markdown multi-tool. TOC, table formatting, link checking, stats. Zero deps.

Usage:
    py mdtool.py toc README.md                   # Generate table of contents
    py mdtool.py toc README.md --insert           # Insert TOC into file (at <!-- toc --> marker)
    py mdtool.py fmt README.md                    # Format/align markdown tables
    py mdtool.py links README.md                  # List all links
    py mdtool.py links README.md --check          # Check links for broken anchors
    py mdtool.py stats README.md                  # Document statistics
    py mdtool.py headings README.md               # Show heading structure
    py mdtool.py toc *.md                         # Process multiple files
"""

import argparse
import os
import re
import sys
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

# Colors
RESET = "\033[0m"
BOLD = "\033[1m"
DIM = "\033[2m"
GREEN = "\033[32m"
YELLOW = "\033[33m"
CYAN = "\033[36m"
RED = "\033[31m"


def color_supported() -> bool:
    if os.environ.get("NO_COLOR"):
        return False
    if sys.platform == "win32":
        return bool(os.environ.get("TERM") or os.environ.get("WT_SESSION"))
    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()


USE_COLOR = color_supported()


def c(code: str, text: str) -> str:
    return f"{code}{text}{RESET}" if USE_COLOR else text


# --- Heading parsing ---

def parse_headings(content: str) -> list[dict]:
    """Parse markdown headings from content."""
    headings = []
    in_code_block = False
    for lineno, line in enumerate(content.splitlines(), 1):
        stripped = line.strip()
        if stripped.startswith("```"):
            in_code_block = not in_code_block
            continue
        if in_code_block:
            continue
        m = re.match(r"^(#{1,6})\s+(.+?)(?:\s*#*\s*)?$", line)
        if m:
            level = len(m.group(1))
            text = m.group(2).strip()
            # Remove inline formatting for anchor
            anchor = heading_to_anchor(text)
            headings.append({
                "level": level,
                "text": text,
                "anchor": anchor,
                "line": lineno,
            })
    return headings


def heading_to_anchor(text: str) -> str:
    """Convert heading text to GitHub-compatible anchor."""
    # Remove inline code, bold, italic, links
    anchor = re.sub(r"`[^`]+`", "", text)
    anchor = re.sub(r"\*+([^*]+)\*+", r"\1", anchor)
    anchor = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", anchor)
    anchor = re.sub(r"<[^>]+>", "", anchor)
    # GitHub anchor rules
    anchor = anchor.lower().strip()
    anchor = re.sub(r"[^\w\s-]", "", anchor)
    anchor = re.sub(r"\s+", "-", anchor)
    return anchor


# --- TOC generation ---

def generate_toc(headings: list[dict], max_level: int = 3, min_level: int = 1) -> str:
    """Generate markdown table of contents."""
    lines = []
    for h in headings:
        if h["level"] < min_level or h["level"] > max_level:
            continue
        indent = "  " * (h["level"] - min_level)
        lines.append(f"{indent}- [{h['text']}](#{h['anchor']})")
    return "\n".join(lines)


def insert_toc(content: str, toc: str) -> str:
    """Insert TOC between <!-- toc --> markers, or add at top."""
    marker_pattern = r"(<!-- toc -->)(.*?)(<!-- /toc -->)"
    replacement = f"<!-- toc -->\n{toc}\n<!-- /toc -->"

    if re.search(marker_pattern, content, re.DOTALL):
        return re.sub(marker_pattern, replacement, content, flags=re.DOTALL)
    else:
        # Insert after first heading
        m = re.search(r"^#.+$", content, re.MULTILINE)
        if m:
            pos = m.end()
            return content[:pos] + f"\n\n<!-- toc -->\n{toc}\n<!-- /toc -->\n" + content[pos:]
        return f"<!-- toc -->\n{toc}\n<!-- /toc -->\n\n{content}"


# --- Table formatting ---

def format_tables(content: str) -> str:
    """Find and align all markdown tables in content."""
    lines = content.splitlines()
    result = []
    i = 0
    while i < len(lines):
        # Detect table start (line with |)
        if "|" in lines[i] and i + 1 < len(lines) and re.match(r"^\s*\|[\s:|-]+\|\s*$", lines[i + 1]):
            table_lines = []
            while i < len(lines) and "|" in lines[i]:
                table_lines.append(lines[i])
                i += 1
            formatted = _format_single_table(table_lines)
            result.extend(formatted)
        else:
            result.append(lines[i])
            i += 1
    return "\n".join(result)


def _format_single_table(table_lines: list[str]) -> list[str]:
    """Format a single markdown table with aligned columns."""
    rows = []
    separator_idx = None
    for idx, line in enumerate(table_lines):
        cells = [c.strip() for c in line.strip().strip("|").split("|")]
        rows.append(cells)
        if idx > 0 and separator_idx is None and all(re.match(r"^[\s:|-]+$", c) for c in cells):
            separator_idx = idx

    if not rows or separator_idx is None:
        return table_lines

    # Calculate column widths
    num_cols = max(len(r) for r in rows)
    widths = [3] * num_cols
    for r in rows:
        for j, cell in enumerate(r):
            if j < num_cols and not re.match(r"^[\s:|-]+$", cell):
                widths[j] = max(widths[j], len(cell))

    # Detect alignment from separator
    alignments = []
    if separator_idx < len(rows):
        for j, cell in enumerate(rows[separator_idx]):
            cell = cell.strip()
            if cell.startswith(":") and cell.endswith(":"):
                alignments.append("center")
            elif cell.endswith(":"):
                alignments.append("right")
            else:
                alignments.append("left")
    while len(alignments) < num_cols:
        alignments.append("left")

    # Format output
    result = []
    for idx, row in enumerate(rows):
        cells = []
        for j in range(num_cols):
            val = row[j] if j < len(row) else ""
            if idx == separator_idx:
                if alignments[j] == "center":
                    cells.append(":" + "-" * (widths[j]) + ":")
                elif alignments[j] == "right":
                    cells.append("-" * (widths[j] + 1) + ":")
                else:
                    cells.append("-" * (widths[j] + 2))
            else:
                cells.append(f" {val.ljust(widths[j])} ")
        result.append("|" + "|".join(cells) + "|")

    return result


# --- Link extraction ---

def extract_links(content: str) -> list[dict]:
    """Extract all links from markdown content."""
    links = []
    in_code_block = False
    for lineno, line in enumerate(content.splitlines(), 1):
        if line.strip().startswith("```"):
            in_code_block = not in_code_block
            continue
        if in_code_block:
            continue
        # [text](url) links
        for m in re.finditer(r"\[([^\]]*)\]\(([^)]+)\)", line):
            text, url = m.group(1), m.group(2)
            link_type = "internal" if url.startswith("#") else "external" if url.startswith("http") else "relative"
            links.append({"text": text, "url": url, "type": link_type, "line": lineno})
        # Bare URLs
        for m in re.finditer(r"(?<!\()(https?://[^\s)>\]]+)", line):
            url = m.group(0)
            if not any(l["url"] == url for l in links if l["line"] == lineno):
                links.append({"text": url, "url": url, "type": "bare", "line": lineno})
    return links


def check_internal_links(content: str, links: list[dict], headings: list[dict]) -> list[dict]:
    """Check internal anchor links against actual headings."""
    available_anchors = {h["anchor"] for h in headings}
    broken = []
    for link in links:
        if link["type"] == "internal":
            anchor = link["url"].lstrip("#")
            if anchor not in available_anchors:
                broken.append(link)
    return broken


# --- Statistics ---

def compute_stats(content: str, filepath: str) -> dict:
    """Compute document statistics."""
    lines = content.splitlines()
    headings = parse_headings(content)
    links = extract_links(content)

    # Word count (exclude code blocks)
    words = 0
    in_code = False
    for line in lines:
        if line.strip().startswith("```"):
            in_code = not in_code
            continue
        if not in_code:
            words += len(line.split())

    # Code block count
    code_blocks = content.count("```") // 2

    # Table count
    tables = 0
    for i, line in enumerate(lines):
        if i > 0 and "|" in line and re.match(r"^\s*\|[\s:|-]+\|\s*$", line):
            tables += 1

    return {
        "file": filepath,
        "lines": len(lines),
        "words": words,
        "chars": len(content),
        "headings": len(headings),
        "h1": sum(1 for h in headings if h["level"] == 1),
        "h2": sum(1 for h in headings if h["level"] == 2),
        "h3": sum(1 for h in headings if h["level"] == 3),
        "links_total": len(links),
        "links_external": sum(1 for l in links if l["type"] == "external"),
        "links_internal": sum(1 for l in links if l["type"] == "internal"),
        "code_blocks": code_blocks,
        "tables": tables,
    }


# --- Commands ---

def cmd_toc(args):
    for filepath in args.files:
        content = Path(filepath).read_text(encoding="utf-8", errors="replace")
        headings = parse_headings(content)
        if not headings:
            print(c(DIM, f"  {filepath}: no headings found"))
            continue
        toc = generate_toc(headings, max_level=args.depth)
        if args.insert:
            new_content = insert_toc(content, toc)
            Path(filepath).write_text(new_content, encoding="utf-8")
            print(c(GREEN, f"  {filepath}: TOC inserted ({len(headings)} headings)"))
        else:
            if len(args.files) > 1:
                print(c(CYAN, f"\n  --- {filepath} ---"))
            print(toc)
            if len(args.files) > 1:
                print()


def cmd_fmt(args):
    for filepath in args.files:
        content = Path(filepath).read_text(encoding="utf-8", errors="replace")
        formatted = format_tables(content)
        if formatted != content:
            if args.write:
                Path(filepath).write_text(formatted, encoding="utf-8")
                print(c(GREEN, f"  {filepath}: tables formatted"))
            else:
                print(formatted)
        else:
            print(c(DIM, f"  {filepath}: no tables to format"))


def cmd_links(args):
    for filepath in args.files:
        content = Path(filepath).read_text(encoding="utf-8", errors="replace")
        links = extract_links(content)
        headings = parse_headings(content)

        if not links:
            print(c(DIM, f"  {filepath}: no links found"))
            continue

        if len(args.files) > 1:
            print(c(CYAN, f"\n  --- {filepath} ---"))

        if args.check:
            # Check internal links
            broken = check_internal_links(content, links, headings)
            if broken:
                print(f"\n  {c(RED, f'{len(broken)} broken internal link(s):')}")
                for l in broken:
                    print(f"    Line {l['line']:>4}: [{l['text']}]({l['url']})")
            else:
                internal = [l for l in links if l["type"] == "internal"]
                print(c(GREEN, f"  All {len(internal)} internal link(s) valid"))
            print()
        else:
            print(f"\n  Links in {filepath} ({len(links)} total):\n")
            for l in links:
                icon = {"internal": "#", "external": "@", "relative": "~", "bare": "@"}.get(l["type"], "?")
                ln = f"L{l['line']:>3}"
                print(f"    {c(DIM, ln)}  {icon}  {l['text'][:40]:<40}  {c(DIM, l['url'][:60])}")
            print()


def cmd_stats(args):
    for filepath in args.files:
        content = Path(filepath).read_text(encoding="utf-8", errors="replace")
        s = compute_stats(content, filepath)
        print(f"\n  {c(BOLD, filepath)}")
        print(f"    Lines:     {s['lines']}")
        print(f"    Words:     {s['words']}")
        print(f"    Chars:     {s['chars']}")
        print(f"    Headings:  {s['headings']} (H1:{s['h1']} H2:{s['h2']} H3:{s['h3']})")
        print(f"    Links:     {s['links_total']} ({s['links_external']} external, {s['links_internal']} internal)")
        print(f"    Code:      {s['code_blocks']} block(s)")
        print(f"    Tables:    {s['tables']}")
    print()


def cmd_headings(args):
    for filepath in args.files:
        content = Path(filepath).read_text(encoding="utf-8", errors="replace")
        headings = parse_headings(content)
        if not headings:
            print(c(DIM, f"  {filepath}: no headings"))
            continue
        if len(args.files) > 1:
            print(c(CYAN, f"\n  --- {filepath} ---"))
        print()
        for h in headings:
            indent = "  " * (h["level"] - 1)
            marker = "#" * h["level"]
            ln = f"L{h['line']:>3}"
            print(f"  {c(DIM, ln)}  {indent}{c(CYAN, marker)} {h['text']}")
        print()


def main():
    parser = argparse.ArgumentParser(
        description="mdtool -- markdown multi-tool",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    sub = parser.add_subparsers(dest="command")

    # toc
    p = sub.add_parser("toc", help="Generate table of contents")
    p.add_argument("files", nargs="+", help="Markdown file(s)")
    p.add_argument("--insert", action="store_true", help="Insert TOC into file (at <!-- toc --> marker)")
    p.add_argument("--depth", type=int, default=3, help="Max heading depth (default: 3)")

    # fmt
    p = sub.add_parser("fmt", help="Format/align markdown tables")
    p.add_argument("files", nargs="+", help="Markdown file(s)")
    p.add_argument("-w", "--write", action="store_true", help="Write changes to file (default: stdout)")

    # links
    p = sub.add_parser("links", help="List or check links")
    p.add_argument("files", nargs="+", help="Markdown file(s)")
    p.add_argument("--check", action="store_true", help="Check internal links for broken anchors")

    # stats
    p = sub.add_parser("stats", help="Document statistics")
    p.add_argument("files", nargs="+", help="Markdown file(s)")

    # headings
    p = sub.add_parser("headings", help="Show heading structure")
    p.add_argument("files", nargs="+", help="Markdown file(s)")

    args = parser.parse_args()
    commands = {
        "toc": cmd_toc, "fmt": cmd_fmt, "links": cmd_links,
        "stats": cmd_stats, "headings": cmd_headings,
    }
    if args.command in commands:
        commands[args.command](args)
    else:
        parser.print_help()


if __name__ == "__main__":
    main()