@runtimestudio/tailwind-sort-php 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Runtime Studio
+Copyright (c) 2026 The Trustee for G&J Sevastos Family Trust t/a Runtime Studio
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,10 @@
-# @runtimestudio/tailwind-sort-php
+# Tailwind CSS Class Sorter for PHP
 
-Tailwind CSS class sorting for **mixed PHP/HTML templates** — the WordPress template-partial case that
-`@prettier/plugin-php` + `prettier-plugin-tailwindcss` can't handle.
+[![npm version](https://img.shields.io/npm/v/@runtimestudio/tailwind-sort-php)](https://www.npmjs.com/package/@runtimestudio/tailwind-sort-php)
+[![License: MIT](https://img.shields.io/npm/l/@runtimestudio/tailwind-sort-php)](LICENSE)
+
+`@runtimestudio/tailwind-sort-php` sorts Tailwind CSS classes in **plain PHP files, WordPress themes and plugins, and
+mixed PHP/HTML templates** — the case `prettier-plugin-tailwindcss` can't parse and `@prettier/plugin-php` mangles.
 
 `prettier-plugin-tailwindcss` sorts classes beautifully, but it can't parse files that interleave PHP with HTML, and
 `@prettier/plugin-php` reformats the entire PHP file as a side effect. This tool sorts **only** the class attribute
@@ -63,12 +66,15 @@ bunx tailwind-sort-php --check
 
 # explicit stylesheet (overrides the Prettier config)
 bunx tailwind-sort-php --stylesheet ./resources/css/main.css
+
+# one-time: install the pre-commit hook (see "Pre-commit gate" below)
+bunx tailwind-sort-php init
 ```
 
 ### Options
 
 | Flag                  | Description                                                                                       |
-| --------------------- | ------------------------------------------------------------------------------------------------- |
+|-----------------------|---------------------------------------------------------------------------------------------------|
 | `--stylesheet <path>` | Tailwind v4 CSS entry. Defaults to `tailwindStylesheet` from your Prettier config.                |
 | `--attr <name>`       | Extra attribute to sort (repeatable). Merged with `tailwindAttributes` from your Prettier config. |
 | `--check`             | Don't write; exit 1 if any file needs sorting.                                                    |
@@ -76,6 +82,68 @@ bunx tailwind-sort-php --stylesheet ./resources/css/main.css
 
 Default globs are all `.php` files under the cwd; `node_modules`, `vendor`, `dist`, and `.git` are always skipped.
 
+## Editor integration
+
+No IDE plugin is needed — two small setups cover the common workflows.
+
+### Sort on save (PhpStorm / IntelliJ)
+
+Add a File Watcher (Settings → Tools → File Watchers → `+` → Custom):
+
+- **File type:** PHP
+- **Program:** `$ProjectFileDir$/node_modules/.bin/tailwind-sort-php`
+- **Arguments:** `$FilePathRelativeToProjectRoot$`
+- **Working directory:** `$ProjectFileDir$`
+
+Untick "Auto-save edited files to trigger the watcher" so it runs on explicit save (~130 ms per file). The definition
+lives in `.idea/watcherTasks.xml`, which you can commit to share it with your team.
+
+### Sort on save (VS Code)
+
+Install the [Run on Save](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave) extension, then add
+to `.vscode/settings.json`:
+
+```json
+{
+  "emeraldwalk.runonsave": {
+    "commands": [
+      {
+        "match": "\\.php$",
+        "cmd": "${workspaceFolder}/node_modules/.bin/tailwind-sort-php ${relativeFile}"
+      }
+    ]
+  }
+}
+```
+
+### Pre-commit gate
+
+Keep unsorted classes from landing regardless of the editor. One command installs a dependency-free Git hook at
+`.githooks/pre-commit` and points `core.hooksPath` at it:
+
+```sh
+# check-and-fail (default): names the unsorted files and blocks the commit
+npx tailwind-sort-php init
+
+# auto-fix: sorts the staged files in place, then blocks the commit for review and re-staging
+npx tailwind-sort-php init --fix
+```
+
+`init` is no-clobber by default: it refuses to overwrite a differing hook, repoint a `core.hooksPath` that's set
+elsewhere (husky etc.), or disable hooks already living in `.git/hooks` — pass `--force` to override, `--dry-run` to
+preview. Run it once per clone; commit the `.githooks/` directory to share the hook with your team.
+
+Both variants check working-tree file contents, so with partial staging (`git add -p`) the hook can mis-report — and
+under `--fix`, re-staging a fixed file can pull in unrelated unstaged hunks.
+
+Wiring the gate into your own hook manager (husky, lefthook) instead? The staged-PHP check is this one-liner:
+
+```sh
+git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 ./node_modules/.bin/tailwind-sort-php --check
+```
+
+In CI there's no staged diff — just sweep the whole project with `npx tailwind-sort-php --check`.
+
 ## How it handles mixed templates
 
 PHP islands inside a class attribute are treated as opaque atoms that never move. Static text between islands is sorted
@@ -131,11 +199,14 @@ const out = transform(source, sortFn);
 
 ```sh
 bun test                       # or: node --test "test/*.test.ts"
+bun run build                  # compile src → dist (tsc); the published artifact
 ```
 
-41 tests, zero dependencies — the sorter is injected (`SortFn`), so tests run with a mock alphabetical sorter and the
-official sorter is only loaded by the CLI.
+54 tests: 41 core tests that are dependency-free (the sorter is injected, so they run against a mock `SortFn`), 5
+integration tests that exercise the real `prettier-plugin-tailwindcss` sorter and skip automatically when the Tailwind
+toolchain isn't installed, and 8 `init` tests that run against throwaway git repositories and skip when `git` is
+unavailable.
 
 ## License
 
-MIT © Runtime Studio
+[MIT](LICENSE) © Runtime Studio

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * tailwind-sort-php CLI
+ *
+ * Usage:
+ *   tailwind-sort-php [options] [glob ...]
+ *   tailwind-sort-php init [--fix] [--force] [--dry-run]
+ *
+ * Options:
+ *   --stylesheet <path> Tailwind v4 CSS entry
+ *   --attr <name> Extra attribute to sort (repeatable)
+ *   --check Don't write; exit 1 if any file needs sorting
+ *   --no-short-tags Don't treat bare `<?` as a PHP open tag
+ *
+ * Defaults to all `.php` files under `cwd` (`"**" + "/*.php"`) when no globs are given.
+ * Skips `node_modules`, `vendor`, `dist` and `.git`. The `init` subcommand installs the pre-commit hook; see `init.ts`.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * tailwind-sort-php CLI
+ *
+ * Usage:
+ *   tailwind-sort-php [options] [glob ...]
+ *   tailwind-sort-php init [--fix] [--force] [--dry-run]
+ *
+ * Options:
+ *   --stylesheet <path> Tailwind v4 CSS entry
+ *   --attr <name> Extra attribute to sort (repeatable)
+ *   --check Don't write; exit 1 if any file needs sorting
+ *   --no-short-tags Don't treat bare `<?` as a PHP open tag
+ *
+ * Defaults to all `.php` files under `cwd` (`"**" + "/*.php"`) when no globs are given.
+ * Skips `node_modules`, `vendor`, `dist` and `.git`. The `init` subcommand installs the pre-commit hook; see `init.ts`.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { transform } from "./transform.js";
+import { createTailwindSortFn } from "./sorter.js";
+import { runInit } from "./init.js";
+const IGNORE = ['node_modules', 'vendor', 'dist', '.git'];
+/**
+ * Parse command-line arguments.
+ *
+ * @param argv Arguments after the runtime and script path.
+ * @returns Parsed CLI options with defaults applied.
+ */
+function parseArgs(argv) {
+    const cli = {
+        globs: [],
+        attrs: ['class', 'className'],
+        check: false,
+        shortTags: true,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--check')
+            cli.check = true;
+        else if (a === '--no-short-tags')
+            cli.shortTags = false;
+        else if (a === '--stylesheet')
+            cli.stylesheet = argv[++i];
+        else if (a === '--attr')
+            cli.attrs.push(argv[++i]);
+        else if (a.startsWith('--')) {
+            console.error(`Unknown option: ${a}`);
+            process.exit(2);
+        }
+        else
+            cli.globs.push(a);
+    }
+    if (cli.globs.length === 0)
+        cli.globs.push('**/*.php');
+    return cli;
+}
+/**
+ * Yield file paths matching the given globs, using `Bun.Glob` under Bun and `node:fs` glob (Node >= 22) otherwise.
+ *
+ * @param globs Glob patterns relative to `cwd`.
+ */
+async function* scanFiles(globs) {
+    // Use `Bun.Glob` when available, fall back to `node:fs` glob (Node 22+).
+    if (typeof globalThis.Bun !== 'undefined') {
+        const { Glob } = await import('bun');
+        for (const pattern of globs) {
+            for await (const f of new Glob(pattern).scan('.'))
+                yield f;
+        }
+    }
+    else {
+        const { glob } = await import('node:fs/promises');
+        for (const pattern of globs) {
+            for await (const f of glob(pattern))
+                yield f;
+        }
+    }
+}
+/**
+ * Whether a path falls inside an always-ignored directory.
+ *
+ * @param file Path to test, relative to `cwd`.
+ * @returns True when the path is inside an ignored directory and should be skipped.
+ */
+const ignored = (file) => IGNORE.some((d) => file.includes(`${d}/`) || file.startsWith(d));
+/**
+ * Best-effort read of the project's resolved Prettier config, so this tool shares one source of truth with
+ * `prettier-plugin-tailwindcss`. Picks up `tailwindStylesheet` (resolved relative to the config file) and
+ * `tailwindAttributes` (merged into the attribute list).
+ *
+ * @returns The resolved stylesheet path and attributes, or an empty object if none are available.
+ */
+async function fromPrettierConfig() {
+    try {
+        const prettier = await import('prettier');
+        const { dirname, resolve } = await import('node:path');
+        const configFile = await prettier.resolveConfigFile();
+        if (!configFile)
+            return {};
+        const cfg = (await prettier.resolveConfig(configFile));
+        if (!cfg)
+            return {};
+        const out = {};
+        if (typeof cfg.tailwindStylesheet === 'string') {
+            out.stylesheet = resolve(dirname(configFile), cfg.tailwindStylesheet);
+        }
+        if (Array.isArray(cfg.tailwindAttributes)) {
+            out.attributes = cfg.tailwindAttributes.filter((a) => typeof a === 'string' && !a.startsWith('/'));
+        }
+        return out;
+    }
+    catch {
+        return {}; // prettier not installed or config unreadable — flags only
+    }
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv[0] === 'init')
+        return runInit(argv.slice(1));
+    const cli = parseArgs(argv);
+    const pc = await fromPrettierConfig();
+    const stylesheet = cli.stylesheet ?? pc.stylesheet;
+    if (!stylesheet) {
+        console.error('No Tailwind stylesheet found. Pass --stylesheet <path> or set ' +
+            '`tailwindStylesheet` in your Prettier config.');
+        process.exit(2);
+    }
+    if (pc.attributes) {
+        for (const a of pc.attributes) {
+            if (!cli.attrs.includes(a))
+                cli.attrs.push(a);
+        }
+    }
+    const sortFn = await createTailwindSortFn({ stylesheet });
+    const opts = {
+        attributes: cli.attrs,
+        shortOpenTags: cli.shortTags,
+    };
+    let scanned = 0;
+    let changed = 0;
+    for (const pattern of cli.globs) {
+        for await (const file of scanFiles([pattern])) {
+            if (ignored(file))
+                continue;
+            scanned++;
+            const src = await readFile(file, 'utf8');
+            const out = transform(src, sortFn, opts);
+            if (out !== src) {
+                changed++;
+                if (cli.check) {
+                    console.log(`needs sorting: ${file}`);
+                }
+                else {
+                    await writeFile(file, out);
+                    console.log(`sorted: ${file}`);
+                }
+            }
+        }
+    }
+    console.log(`${scanned} file(s) scanned, ${changed} ${cli.check ? 'need(s) sorting' : 'updated'}`);
+    if (cli.check && changed > 0)
+        process.exit(1);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/html.d.ts

@@ -0,0 +1,59 @@
+/**
+ * HTML attribute scanner — the second pass of the two-pass lexer.
+ *
+ * Operates on a "masked" copy of the source in which every PHP island byte has been replaced with `\x00`
+ * (offsets preserved). This means:
+ *   - quotes/angle brackets inside PHP can never confuse the HTML scan
+ *   - islands inside a tag read as attribute separators
+ *   - islands inside a quoted attribute value read as opaque atoms
+ *
+ * Skips HTML comments, doctype/CDATA, and the raw-text content of `script`/`style`/`textarea`/`title` elements —
+ * their `script`/`style` content may contain strings like `class="..."` that must not be touched.
+ *
+ * @see islands.ts - first pass; produces the islands consumed here.
+ */
+import type { Island } from './islands.ts';
+/**
+ * Location of a sortable class attribute value within the source.
+ */
+export interface ClassAttr {
+    /**
+     * Attribute name as written (e.g. `class`, `className`).
+     */
+    name: string;
+    /**
+     * Offset of the first character inside the quotes.
+     */
+    valueStart: number;
+    /**
+     * Offset just past the last character inside the quotes (exclusive).
+     */
+    valueEnd: number;
+}
+/**
+ * Options controlling which attributes are collected.
+ */
+export interface HtmlScanOptions {
+    /**
+     * Lowercase attribute names to collect; default `['class', 'classname']`.
+     */
+    attributes?: string[];
+}
+/**
+ * Produce a copy of the source with every island byte replaced by `\x00`.
+ *
+ * Length and offsets are preserved, so positions found in the masked string map 1:1 back to the original source.
+ *
+ * @param src     Original template source.
+ * @param islands Island ranges from `findIslands()`.
+ * @returns Masked source of identical length.
+ */
+export declare function maskIslands(src: string, islands: Island[]): string;
+/**
+ * Locate every sortable class attribute in an island-masked source.
+ *
+ * @param masked Source pre-processed by `maskIslands()`.
+ * @param opts   Attribute collection options.
+ * @returns Attribute value locations in document order. Offsets index into the original source.
+ */
+export declare function findClassAttributes(masked: string, opts?: HtmlScanOptions): ClassAttr[];

package/dist/html.js

@@ -0,0 +1,145 @@
+/**
+ * HTML attribute scanner — the second pass of the two-pass lexer.
+ *
+ * Operates on a "masked" copy of the source in which every PHP island byte has been replaced with `\x00`
+ * (offsets preserved). This means:
+ *   - quotes/angle brackets inside PHP can never confuse the HTML scan
+ *   - islands inside a tag read as attribute separators
+ *   - islands inside a quoted attribute value read as opaque atoms
+ *
+ * Skips HTML comments, doctype/CDATA, and the raw-text content of `script`/`style`/`textarea`/`title` elements —
+ * their `script`/`style` content may contain strings like `class="..."` that must not be touched.
+ *
+ * @see islands.ts - first pass; produces the islands consumed here.
+ */
+const RAW_TEXT_TAGS = new Set(['script', 'style', 'textarea', 'title']);
+const NUL = '\x00';
+/**
+ * Produce a copy of the source with every island byte replaced by `\x00`.
+ *
+ * Length and offsets are preserved, so positions found in the masked string map 1:1 back to the original source.
+ *
+ * @param src     Original template source.
+ * @param islands Island ranges from `findIslands()`.
+ * @returns Masked source of identical length.
+ */
+export function maskIslands(src, islands) {
+    if (islands.length === 0)
+        return src;
+    let out = '';
+    let pos = 0;
+    for (const isl of islands) {
+        out += src.slice(pos, isl.start);
+        out += NUL.repeat(isl.end - isl.start);
+        pos = isl.end;
+    }
+    out += src.slice(pos);
+    return out;
+}
+/**
+ * Locate every sortable class attribute in an island-masked source.
+ *
+ * @param masked Source pre-processed by `maskIslands()`.
+ * @param opts   Attribute collection options.
+ * @returns Attribute value locations in document order. Offsets index into the original source.
+ */
+export function findClassAttributes(masked, opts = {}) {
+    const wanted = new Set((opts.attributes ?? ['class', 'classname']).map((a) => a.toLowerCase()));
+    const out = [];
+    const len = masked.length;
+    let i = 0;
+    while (i < len) {
+        const lt = masked.indexOf('<', i);
+        if (lt === -1)
+            break;
+        // HTML comment.
+        if (masked.startsWith('<!--', lt)) {
+            const close = masked.indexOf('-->', lt + 4);
+            i = close === -1 ? len : close + 3;
+            continue;
+        }
+        // Doctype / CDATA / other declarations.
+        if (masked[lt + 1] === '!') {
+            const close = masked.indexOf('>', lt + 2);
+            i = close === -1 ? len : close + 1;
+            continue;
+        }
+        // Closing tag.
+        if (masked[lt + 1] === '/') {
+            const close = masked.indexOf('>', lt + 2);
+            i = close === -1 ? len : close + 1;
+            continue;
+        }
+        // Opening tag?
+        if (lt + 1 < len && /[A-Za-z]/.test(masked[lt + 1])) {
+            let j = lt + 1;
+            while (j < len && /[A-Za-z0-9:-]/.test(masked[j]))
+                j++;
+            const tagName = masked.slice(lt + 1, j).toLowerCase();
+            j = scanTagAttributes(masked, j, wanted, out);
+            // Skip raw-text element content up to its closing tag.
+            if (RAW_TEXT_TAGS.has(tagName)) {
+                const closer = `</${tagName}`;
+                const idx = masked.toLowerCase().indexOf(closer, j);
+                j = idx === -1 ? len : idx;
+            }
+            i = j;
+            continue;
+        }
+        i = lt + 1;
+    }
+    return out;
+}
+const isTagWs = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f' || c === NUL;
+/**
+ * Parse attributes from just past the tag name to just past `>`.
+ * Returns the offset after `>` (or EOF). Pushes matches into `out`.
+ */
+function scanTagAttributes(masked, i, wanted, out) {
+    const len = masked.length;
+    while (i < len) {
+        while (i < len && isTagWs(masked[i]))
+            i++;
+        if (i >= len)
+            return len;
+        const c = masked[i];
+        if (c === '>')
+            return i + 1;
+        if (c === '/') {
+            i++;
+            continue;
+        }
+        // Attribute name.
+        const nameStart = i;
+        while (i < len && !isTagWs(masked[i]) && masked[i] !== '=' && masked[i] !== '>' && masked[i] !== '/')
+            i++;
+        const name = masked.slice(nameStart, i);
+        if (name.length === 0) {
+            i++;
+            continue;
+        }
+        while (i < len && isTagWs(masked[i]))
+            i++;
+        if (masked[i] !== '=')
+            continue; // boolean attribute
+        i++;
+        while (i < len && isTagWs(masked[i]))
+            i++;
+        const q = masked[i];
+        if (q === '"' || q === "'") {
+            const valueStart = i + 1;
+            const close = masked.indexOf(q, valueStart);
+            const valueEnd = close === -1 ? len : close;
+            if (wanted.has(name.toLowerCase())) {
+                out.push({ name, valueStart, valueEnd });
+            }
+            i = valueEnd + 1;
+        }
+        else {
+            // Unquoted value — read it but never rewrite (too risky to widen).
+            while (i < len && !isTagWs(masked[i]) && masked[i] !== '>')
+                i++;
+        }
+    }
+    return len;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public API for `@runtimestudio/tailwind-sort-php`.
+ *
+ * Tailwind CSS class sorting for mixed PHP/HTML templates. The core is dependency-free;
+ * the official sorting engine is wired in via `createTailwindSortFn()` or any custom `SortFn`.
+ *
+ * @packageDocumentation
+ * @see cli.ts - command-line interface built on this API.
+ */
+export { transform, type SortFn, type TransformOptions } from './transform.ts';
+export { findIslands, type Island, type IslandOptions } from './islands.ts';
+export { maskIslands, findClassAttributes, type ClassAttr, type HtmlScanOptions } from './html.ts';
+export { createTailwindSortFn, type SorterOptions } from './sorter.ts';

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * Public API for `@runtimestudio/tailwind-sort-php`.
+ *
+ * Tailwind CSS class sorting for mixed PHP/HTML templates. The core is dependency-free;
+ * the official sorting engine is wired in via `createTailwindSortFn()` or any custom `SortFn`.
+ *
+ * @packageDocumentation
+ * @see cli.ts - command-line interface built on this API.
+ */
+export { transform } from "./transform.js";
+export { findIslands } from "./islands.js";
+export { maskIslands, findClassAttributes } from "./html.js";
+export { createTailwindSortFn } from "./sorter.js";

package/dist/init.d.ts

@@ -0,0 +1,12 @@
+/**
+ * tailwind-sort-php init
+ *
+ * Installs the pre-commit hook: writes `.githooks/pre-commit` and points `core.hooksPath` at it.
+ * No-clobber unless `--force`; `--fix` installs the auto-fixing variant; `--dry-run` previews.
+ */
+/**
+ * Run the `init` subcommand: install the pre-commit hook and point `core.hooksPath` at it.
+ *
+ * @param argv Arguments after the `init` subcommand name.
+ */
+export declare function runInit(argv: string[]): Promise<void>;