tailwhip 0.9a3__py3-none-any.whl

tailwhip/__init__.py

@@ -0,0 +1,11 @@
+"""Tailwhip - Sort Tailwind CSS classes in HTML and CSS files."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+from tailwhip.cli import main
+
+__all__ = ["main"]
+__version__ = metadata.version("tailwhip")
+__author__ = "Martin Mahner"

tailwhip/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for python -m tailwhip."""
+
+from __future__ import annotations
+
+from tailwhip.cli import main
+
+if __name__ == "__main__":
+    main()

tailwhip/cli.py

@@ -0,0 +1,148 @@
+"""CLI entrypoint."""
+
+from __future__ import annotations
+
+import sys
+import time
+from importlib import metadata
+from pathlib import Path  # noqa: TC003
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from tailwhip.constants import CONSOLE_THEME, GLOBS, SKIP_EXPRESSIONS, VERBOSITY_LOUD
+from tailwhip.datatypes import Config
+from tailwhip.files import apply_changes, find_files
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        version = metadata.version("tailwhip")
+        typer.echo(f"tailwhip {version}")
+        raise typer.Exit
+
+
+app = typer.Typer(
+    help="Sort Tailwind CSS classes in HTML and CSS files",
+    add_completion=False,
+)
+
+
+def main() -> None:
+    """Entrypoint for the CLI."""
+    app()
+
+
+@app.command()
+def run(  # noqa: PLR0913
+    paths: Annotated[
+        list[Path],
+        typer.Argument(
+            help=(
+                f"File or directory paths to process. Plain directories "
+                f"(e.g., 'templates/') use default patterns ({', '.join(GLOBS)}). "
+                f"Glob patterns (e.g., 'templates/**/*.postcss') are matched as-is."
+            )
+        ),
+    ],
+    version: Annotated[  # noqa: ARG001
+        bool,
+        typer.Option(
+            "--version",
+            callback=version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = False,
+    write_mode: Annotated[
+        bool,
+        typer.Option(
+            "--write",
+            help="Apply sorting changes to files. Without this flag, runs in check-only mode to preview changes.",
+        ),
+    ] = False,
+    skip_expressions: Annotated[
+        str,
+        typer.Option(
+            "--skip-expressions",
+            help="Template syntax markers that indicate code blocks to skip sorting. Comma-separated list (e.g., '{{,{%,<%'). Prevents sorting dynamic template expressions.",
+        ),
+    ] = ",".join(SKIP_EXPRESSIONS),
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            "--quiet",
+            "-q",
+            help="Minimal output mode. Only displays errors and warnings.",
+        ),
+    ] = False,
+    verbosity: Annotated[
+        int,
+        typer.Option(
+            "--verbose",
+            "-v",
+            count=True,
+            help="Increase output detail level. Use -v for changes, -vv for file processing, -vvv for debug info.",
+        ),
+    ] = 0,
+    custom_colors: Annotated[
+        str,
+        typer.Option(
+            "--custom-colors",
+            help=(
+                "Comma-separated list of custom color names from your Tailwind config "
+                "(e.g., 'brand,company,accent'). These colors will be recognized and sorted "
+                "alongside standard Tailwind colors. WARNING: Classes using these custom colors "
+                "will sort differently if you run tailwhip again without providing the same "
+                "--custom-colors values. Omitting previously-used custom colors will cause those "
+                "utilities to be treated as non-color classes and sorted into different positions."
+            ),
+        ),
+    ] = "",
+) -> None:
+    """Sort Tailwind CSS classes in HTML and CSS files."""
+    console = Console(quiet=quiet, theme=CONSOLE_THEME)
+    skip_expressions = [
+        expr.strip() for expr in skip_expressions.split(",") if expr.strip()
+    ]
+    custom_colors_list = {
+        color.strip() for color in custom_colors.split(",") if color.strip()
+    }
+
+    config = Config(
+        console=console,
+        paths=paths,
+        write=write_mode,
+        skip_expressions=skip_expressions,
+        verbosity=verbosity + 1,
+        custom_colors=custom_colors_list,
+    )
+
+    console.print("")
+
+    start_time = time.time()
+    targets = find_files(config=config)
+    found_any, skipped, changed = apply_changes(targets=targets, config=config)
+    duration = time.time() - start_time
+
+    if not found_any:
+        config.console.print("[red]Error: No files found[/red]")
+        sys.exit(1)
+
+    if config.verbosity < VERBOSITY_LOUD:
+        console.print(
+            "\nUse [important] -v [/important] (show unchanged files) or [important] -vv [/important] (show diff preview) for more detail."
+        )
+
+    if not config.write:
+        console.print(
+            "\n:warning: Dry Run. No files were actually written. "
+            "Use [important] --write [/important] to write changes."
+        )
+
+    console.print(
+        f"⏱ Completed in [bold]{duration:.3f}s[/bold] for {changed} files. [dim]({skipped} skipped)[/dim]",
+        highlight=False,
+    )

tailwhip/constants.py

@@ -0,0 +1,311 @@
+"""Constants used by tailwhip."""
+
+from __future__ import annotations
+
+import re
+
+from rich.theme import Theme
+
+# File glob(s) to process
+GLOBS = ["**/*.html", "**/*.css"]
+
+# Skip if a template expression appears inside the class attribute
+# List of strings that indicate template expressions to skip
+SKIP_EXPRESSIONS = ["{{", "{%", "<%"]
+
+# Recognize Tailwind variants (order doesn't matter; we sort lexicographically)
+# e.g. "sm:hover:focus:text-blue-500" => variants ["focus", "hover", "sm"]
+VARIANT_SEP = ":"
+
+# A lightweight utility ranking derived from common Tailwind "best practice" ordering.
+# This is not exhaustive, but it's practical. Unknown utilities fall to the end.
+#
+# SORTING MECHANISM: ------------------
+#
+# Each regex pattern in this list defines a GROUP. Groups are matched in order (top
+# to bottom). When a utility class is encountered, it's tested against each pattern
+# until a match is found. The matched group's index becomes the utility's rank (lower
+# index = sorts earlier).
+#
+# WHY MULTIPLE PATTERNS IN ONE GROUP?
+#
+# Some logical categories (e.g., "Layout & display") contain multiple related patterns.
+# These are kept as separate regex entries rather than one mega-pattern because:
+#
+#   1. Readability: Easier to see what utilities belong together
+#   2. Maintainability: Simpler to add/remove/modify individual patterns
+#   3. Order control: You can fine-tune the sort order within a category
+#      (e.g., "flex" before "grid" before "table")
+#
+# WHY SINGLE PATTERNS?
+#
+# Single patterns are used when:
+#
+#   - The utility is standalone or unique (e.g., "container")
+#   - It needs precise positioning in the sort order
+#   - It's a catch-all for a prefix (e.g., "text-" matches text-sm, text-lg, etc.)
+#
+# WITHIN-GROUP SORTING:
+#
+# Classes matching the SAME group index are then sorted:
+#
+#   1. Non-color utilities before color utilities
+#   2. Alphabetically by the full class name
+#
+# Example: "flex", "flex-col", "flex-row" all match r"(flex|inline-flex)" and sort alphabetically.
+#
+GROUPS = [
+    #
+    # 0) Components (Tailwind "components" layer comes before utilities)
+    r"(^| )(container)( |$)",
+    #
+    # 1) Layout & display
+    r"(hidden|visible|invisible)",
+    r"(z)-",
+    r"(block|inline-block|inline|flow-root|contents)",
+    r"(flex|inline-flex)",
+    r"(grid|inline-grid)",
+    r"(table|inline-table)",
+    r"(box-border|box-content|box-decoration-(slice|clone))",
+    r"(isolate|isolation-auto)",
+    r"(static|fixed|absolute|relative|sticky)",
+    r"(inset|top|right|bottom|left|z)-",
+    r"(float|clear)-(left|right|none|start|end)",
+    #
+    # floats/clears
+    r"(columns)-",
+    #
+    # CSS multi-column
+    r"(break)-(inside|before|after)-",
+    #
+    # page/column breaks
+    r"(overflow|overscroll)-",
+    #
+    # scrolling/overflow
+    r"(scroll|scroll-m|scroll-p|scroll-smooth)",
+    #
+    # scroll behavior & margins
+    r"(snap)-",
+    #
+    # 2) Flexbox & Grid
+    r"(order|grow|shrink|basis)-",
+    r"(grid-cols|grid-rows|grid-flow|auto-cols|auto-rows)-",
+    r"(col-(span|start|end)|row-(span|start|end))-",
+    r"(gap|space-[xy])-",
+    #
+    # 3) Alignment & distribution (box alignment)
+    r"(place|content|items|self|justify|align)-",
+    #
+    # 4) Sizing
+    r"(size)-",
+    r"(w)-",
+    r"(min-w)-",
+    r"(max-w)-",
+    r"(h)-",
+    r"(min-h)-",
+    r"(max-h)-",
+    r"(aspect)-",
+    #
+    # 5) Spacing (x,y,t,r,b,l)
+    r"(m)-",
+    r"(mx)-",
+    r"(my)-",
+    r"(mt)-",
+    r"(mr)-",
+    r"(mb)-",
+    r"(ml)-",
+    r"(p)-",
+    r"(px)-",
+    r"(py)-",
+    r"(pt)-",
+    r"(pr)-",
+    r"(pb)-",
+    r"(pl)-",
+    #
+    # 6) Typography
+    r"(font)-",
+    r"(text-(balance|pretty|wrap))",
+    r"(text)-",
+    r"(tracking)-",
+    r"(leading)-",
+    r"(list)-",
+    r"(indent)-",
+    r"(placeholder)-",
+    r"(whitespace|break|hyphens)-",
+    r"(tab-size)-",
+    r"(line-clamp)-",
+    #
+    # official plugin utility
+    r"(antialiased|subpixel-antialiased|truncate)",
+    #
+    # single-token type utils
+    r"(tabular-nums|slashed-zero|lining-nums|oldstyle-nums|proportional-nums|ordinal)",
+    #
+    # content-['…'] utilities
+    r"(content)-",
+    #
+    # 7) Backgrounds
+    # includes bg-clip, -origin, -repeat, -size, -position, -attachment, colors
+    r"(bg)-",
+    #
+    # gradients
+    r"(from)-",
+    r"(to)-",
+    r"(via)-",
+    #
+    #
+    # 8) Borders & outlines & rings & divide
+    r"(rounded)-",
+    r"(border)-",
+    r"(divide)-",
+    r"(ring)-",
+    r"(outline)-",
+    #
+    # 9) Effects
+    r"(shadow)-",
+    r"(opacity)-",
+    r"(mix-blend)-",
+    r"(backdrop|filter|blur|brightness|contrast|grayscale|hue-rotate|invert|saturate|sepia|drop-shadow)-",
+    #
+    # 10) Transforms
+    r"(transform|scale|rotate|translate|skew|origin)-",
+    #
+    # 11) Transitions & animation
+    r"(transition|duration|ease|delay|animate)-",
+    #
+    # 12) Interactivity & misc
+    r"(cursor|select|pointer-events|resize|appearance|accent|caret|touch)-",
+    r"(object)-",
+    #
+    # object-fit/position
+    r"(outline-none)",
+    #
+    # single token
+    r"(stroke|fill)-",
+    #
+    # SVG
+    #
+    # 13) Accessibility helpers (kept near the end so utility groups dominate)
+    r"(sr-only|not-sr-only)",
+    #
+    # 14) Group/peer & attribute base selectors (as raw classes, not variants)
+    r"(peer|group|aria-|data-)(:|$)",
+]
+
+VARIANT_PREFIX_ORDER = [
+    #
+    #  Container queries (most specific, come first)
+    r"@container:",
+    r"@\w+:",
+    #
+    #  Direction & theme
+    r"(rtl|ltr):",
+    r"dark:",
+    #
+    #  Media-like variants
+    r"(portrait|landscape|print):",
+    r"(motion-safe|motion-reduce):",
+    r"(contrast-more|contrast-less):",
+    #
+    #  Container & size queries (if using v4 container queries)
+    r"(supports-\[.*\]|supports-.*:)",
+    #
+    #  supports: variant patterns
+    r"(size-.*:|cq-.*:)",
+    #
+    #  Breakpoints (mobile-first)
+    r"min-\[.*\]:",
+    r"max-\[.*\]:",
+    r"sm:",
+    r"md:",
+    r"lg:",
+    r"xl:",
+    r"2xl:",
+    #
+    #  Structural/state
+    r"(first):",
+    r"(last):",
+    r"(only):",
+    r"(odd):",
+    r"(even):",
+    r"(first-of-type|last-of-type|only-of-type):",
+    r"(visited|target|open|empty):",
+    r"(enabled|disabled|read-only|required|optional):",
+    r"(checked|indeterminate|default):",
+    r"(valid|invalid):",
+    r"(in-range|out-of-range):",
+    r"(placeholder-shown):",
+    r"(autofill):",
+    r"(focus-within):",
+    r"(hover|focus|focus-visible|focus-within|active):",
+    r"(pressed|selected):",
+    r"(current):",
+    r"(aria-.*:|data-.*:)",
+    #
+    #  attribute variants
+    r"(group(-\[.*\])?:.*:|group-.*:)",
+    #
+    #  group/compound (e.g. group-hover:)
+    r"(peer(-\[.*\])?:.*:|peer-.*:)",
+    #
+    #  peer/compound (e.g. peer-checked:)
+    r"(marker:|selection:|file:|placeholder:|backdrop:|first-letter:|first-line:)",
+]
+
+
+# Standard Tailwind color names (extracted from the palette)
+TAILWIND_COLORS = {
+    "transparent",
+    "current",
+    "black",
+    "white",
+    "amber",
+    "blue",
+    "blue-gray",
+    "cool-gray",
+    "cyan",
+    "emerald",
+    "fuchsia",
+    "gray",
+    "green",
+    "indigo",
+    "light-blue",
+    "lime",
+    "orange",
+    "pink",
+    "purple",
+    "red",
+    "rose",
+    "sky",
+    "teal",
+    "true-gray",
+    "violet",
+    "warm-gray",
+    "yellow",
+}
+
+
+GROUP_PATTERNS = [re.compile("^" + g) for g in GROUPS]
+
+CLASS_ATTR_RE = re.compile(
+    r"""(?P<full>\bclass\s*=\s*(?P<quote>["'])(?P<val>.*?)(?P=quote))""",
+    re.IGNORECASE | re.DOTALL,
+)
+
+APPLY_RE = re.compile(
+    r"""@apply\s+(?P<classes>[^;]+);""",
+    re.MULTILINE,
+)
+
+CONSOLE_THEME = Theme(
+    {
+        "important": "white on deep_pink4",
+        "highlight": "yellow1",
+        "filename": "white",
+        "bold": "sky_blue1",
+    }
+)
+
+VERBOSITY_NONE = 0
+VERBOSITY_LOUD = 2
+VERBOSITY_ALL = 3

tailwhip/datatypes.py

@@ -0,0 +1,23 @@
+"""Datatypes for tailwhip."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from rich.console import Console
+
+
+@dataclass
+class Config:
+    """Argument parser config."""
+
+    console: Console
+    paths: list[Path]
+    write: bool
+    skip_expressions: list[str]
+    verbosity: int
+    custom_colors: set[str]

tailwhip/files.py

@@ -0,0 +1,170 @@
+"""File-related utilities."""
+
+from __future__ import annotations
+
+import difflib
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rich.padding import Padding
+from rich.syntax import Syntax
+
+from tailwhip.constants import GLOBS, VERBOSITY_ALL, VERBOSITY_LOUD, VERBOSITY_NONE
+from tailwhip.process import process_text
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Iterable
+
+    from tailwhip.datatypes import Config
+
+
+def find_files(*, config: Config) -> Generator[Path]:  # noqa: C901
+    """Find all HTML/CSS files from a list of paths.
+
+    Processes multiple path inputs (files, directories, or glob patterns), expands each
+    one, and returns a deduplicated generator of all matching HTML/CSS files. If no paths
+    are provided, defaults to scanning the current directory.
+
+    Args:
+        config: Argument configuration object
+
+    Yields:
+        Path objects for all HTML/CSS files found (deduplicated and sorted)
+
+    Examples:
+        >>> config.paths = [Path('templates/'), Path('styles/')]
+        >>> list(find_files(config))
+        [PosixPath('templates/index.html'), PosixPath('styles/main.css')]
+
+        >>> config.paths = [Path('src/**/*.html'), Path('components/**/*.html')]
+        >>> list(find_files(config))
+        [PosixPath('src/pages/home.html'), PosixPath('components/nav.html')]
+
+        >>> config.paths = []
+        >>> list(find_files(config))  # Defaults to current directory
+        [PosixPath('./index.html'), PosixPath('./styles.css')]
+
+        >>> config.paths = [Path('index.html'), Path('about.html'), Path('index.html')]
+        >>> list(find_files(config))
+        [PosixPath('index.html'), PosixPath('about.html')]  # Deduplication
+
+        >>> config.paths = [Path('*.html'), Path('static/*.css')]
+        >>> list(find_files(config))
+        [PosixPath('home.html'), PosixPath('static/app.css')]
+
+    """
+    seen = set()
+
+    for entry in config.paths:
+        p = Path(entry)
+
+        # Case 1: Existing directory - search within it using configured glob patterns
+        # Example: entry="src/" with config.globs=["**/*.html"]
+        # → yields: src/index.html, src/pages/about.html
+        if p.is_dir():
+            for pattern in GLOBS:
+                for match in p.glob(pattern):
+                    resolved = match.resolve()
+                    if resolved not in seen:
+                        seen.add(resolved)
+                        yield resolved
+
+        # Case 2: Existing file - yield it directly without pattern matching
+        # Example: entry="index.html" (file exists)
+        # → yields: /absolute/path/to/index.html
+        elif p.is_file():
+            resolved = p.resolve()
+            if resolved not in seen:
+                seen.add(resolved)
+                yield resolved
+
+        # Case 3: Non-existent path - interpret as recursive glob pattern from cwd
+        # Example: entry="**/*.css" or entry="templates/*.html" (path doesn't exist as literal)
+        # → yields: styles/main.css, components/button.css (all matching files from cwd)
+        else:
+            for match in Path().rglob(str(entry)):
+                if match.is_file():
+                    resolved = match.resolve()
+                    if resolved not in seen:
+                        seen.add(resolved)
+                        yield resolved
+
+
+def get_diff(path: Path, old_text: str, new_text: str) -> Syntax:
+    """Show a nice diff using Rich."""
+    # Create a text diff between old and new text
+    diff = difflib.unified_diff(
+        old_text.splitlines(),
+        new_text.splitlines(),
+        fromfile=str(path),
+        tofile=str(path),
+        n=1,
+    )
+
+    # Remove blank lines
+    code = "\n".join([line.strip() for line in diff])
+    return Syntax(code, "diff", theme="ansi_dark", background_color="default")
+
+
+def apply_changes(*, targets: Iterable[Path], config: Config) -> tuple[bool, int, int]:
+    """Process target files and apply Tailwind class sorting changes.
+
+    Reads each file, processes it to sort Tailwind classes (skipping any with
+    template syntax), and either writes the changes back or reports what would be
+    changed. Provides detailed diff output at higher verbosity levels.
+
+    Args:
+        targets: List of Path objects for files to process
+        config: Argument configuration object
+
+    Returns:
+        A tuple of (skipped_count, changed_count) where:
+        - skipped_count: Number of files with no changes needed
+        - changed_count: Number of files that were modified or would be modified
+
+    Examples:
+        >>> apply_changes(targets=[Path('index.html')], config=config)
+        (0, 1)  # 0 skipped, 1 changed
+
+        >>> apply_changes(targets=[Path('a.html'), Path('b.html')], config=config)
+        (1, 1)  # 1 skipped (no changes), 1 changed
+
+    """
+    skipped = 0
+    changed = 0
+    found_any = False
+
+    for f in targets:
+        found_any = True
+        old_text = f.read_text(encoding="utf-8")
+        new_text = process_text(old_text, config)
+
+        # Skip files that don't need changes
+        if old_text == new_text:
+            if config.verbosity >= VERBOSITY_LOUD:
+                config.console.print(
+                    f"[grey30]Already sorted {f}[/grey30]", highlight=False
+                )
+            skipped += 1
+            continue
+
+        changed += 1
+
+        # Write changes if in write mode, otherwise just report
+        if config.write:
+            f.write_text(new_text, encoding="utf-8")
+
+        # No report if verbosity is low
+        if config.verbosity == VERBOSITY_NONE:
+            continue
+
+        if config.write:
+            config.console.print(f"[dim]Updated[/dim] [filename]{f}[/filename]")
+        else:
+            config.console.print(f"[dim]Would update[/dim] [filename]{f}[/filename]")
+
+        if config.verbosity >= VERBOSITY_ALL:
+            diff = get_diff(f, old_text, new_text)
+            config.console.print(Padding(diff, (1, 0, 1, 4)))
+
+    return found_any, skipped, changed