@runtimestudio/tailwind-sort-php 0.2.1 → 0.4.0

package/dist/islands.js

@@ -9,8 +9,7 @@
  *
  * @see html.ts - second pass; consumes islands via `maskIslands()`.
  */
-const isIdentStart = (c) => /[A-Za-z_\u0080-\uffff]/.test(c);
-const isIdent = (c) => /[A-Za-z0-9_\u0080-\uffff]/.test(c);
+import { isIdent, scanHeredoc, scanLineComment, scanQuoted } from "./php-lexer.js";
 /**
  * Find every PHP island in a mixed PHP/HTML template source.
  *
@@ -69,23 +68,23 @@ function scanPhpBody(src, i) {
             return i + 2;
         // Single-quoted string.
         if (c === "'") {
-            i = scanQuoted(src, i + 1, "'");
+            i = Math.min(scanQuoted(src, i + 1, "'", len) + 1, len);
             continue;
         }
         // Double-quoted string.
         // Limitation: nested double quotes in complex `{$a["k"]}` interpolation can desync the lexer; see README.
         if (c === '"') {
-            i = scanQuoted(src, i + 1, '"');
+            i = Math.min(scanQuoted(src, i + 1, '"', len) + 1, len);
             continue;
         }
         // Backtick (shell exec) string — same escaping rules.
         if (c === '`') {
-            i = scanQuoted(src, i + 1, '`');
+            i = Math.min(scanQuoted(src, i + 1, '`', len) + 1, len);
             continue;
         }
         // Comments.
         if (c === '/' && src[i + 1] === '/') {
-            i = scanLineComment(src, i + 2);
+            i = scanLineComment(src, i + 2, len);
             if (src.startsWith('?>', i))
                 return i + 2;
             continue;
@@ -96,7 +95,7 @@ function scanPhpBody(src, i) {
                 i += 2;
                 continue;
             }
-            i = scanLineComment(src, i + 1);
+            i = scanLineComment(src, i + 1, len);
             if (src.startsWith('?>', i))
                 return i + 2;
             continue;
@@ -108,7 +107,7 @@ function scanPhpBody(src, i) {
         }
         // Heredoc / nowdoc.
         if (c === '<' && src[i + 1] === '<' && src[i + 2] === '<') {
-            const here = scanHeredoc(src, i + 3);
+            const here = scanHeredoc(src, i + 3, len);
             if (here !== -1) {
                 i = here;
                 continue;
@@ -118,89 +117,3 @@ function scanPhpBody(src, i) {
     }
     return len; // file ends while still in PHP mode
 }
-/**
- * Scan a quoted string body; `i` is just past the open quote.
- * Returns offset just past the closing quote (or EOF).
- */
-function scanQuoted(src, i, quote) {
-    const len = src.length;
-    while (i < len) {
-        const c = src[i];
-        if (c === '\\') {
-            i += 2;
-            continue;
-        }
-        if (c === quote)
-            return i + 1;
-        i++;
-    }
-    return len;
-}
-/**
- * Scan a `//` or `#` line comment body, which ends at a newline or at `?>`.
- * Returns the offset past a consumed newline, or the offset of an unconsumed `?>`
- * (left for the caller, since `?>` closes both the comment and the island).
- */
-function scanLineComment(src, i) {
-    const len = src.length;
-    while (i < len) {
-        if (src[i] === '\n')
-            return i + 1;
-        if (src[i] === '?' && src[i + 1] === '>')
-            return i;
-        i++;
-    }
-    return len;
-}
-/**
- * Scan a heredoc/nowdoc; `i` is just past `<<<`.
- * Returns the offset past the closing identifier line, or -1 if `<<<` isn't followed by a valid heredoc identifier.
- */
-function scanHeredoc(src, i) {
-    const len = src.length;
-    // Optional whitespace (PHP allows spaces/tabs after `<<<`).
-    while (i < len && (src[i] === ' ' || src[i] === '\t'))
-        i++;
-    // Optional quote around the identifier.
-    let quote = '';
-    if (src[i] === "'" || src[i] === '"') {
-        quote = src[i];
-        i++;
-    }
-    if (i >= len || !isIdentStart(src[i]))
-        return -1;
-    const idStart = i;
-    while (i < len && isIdent(src[i]))
-        i++;
-    const id = src.slice(idStart, i);
-    if (quote) {
-        if (src[i] !== quote)
-            return -1;
-        i++;
-    }
-    // After the identifier, the line must end immediately — PHP disallows trailing whitespace,
-    // but we tolerate `\r` so `\r\n` endings still work.
-    while (i < len && src[i] === '\r')
-        i++;
-    if (src[i] !== '\n')
-        return -1;
-    i++;
-    // Find a line that starts with optional indentation,
-    // then the identifier followed by a non-identifier character
-    // (PHP 7.3 flexible syntax).
-    while (i < len) {
-        let j = i;
-        while (j < len && (src[j] === ' ' || src[j] === '\t'))
-            j++;
-        if (src.startsWith(id, j)) {
-            const k = j + id.length;
-            if (k >= len || !isIdent(src[k]))
-                return k;
-        }
-        const nl = src.indexOf('\n', i);
-        if (nl === -1)
-            return len;
-        i = nl + 1;
-    }
-    return len;
-}

package/dist/php-lexer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared low-level PHP lexing helpers.
+ *
+ * Used by both passes that read PHP code — island detection (`islands.ts`) and string harvesting (`php-strings.ts`)
+ * — so the two can never drift apart on string/comment/heredoc boundary rules.
+ *
+ * All scanners operate on the `[i, end)` window of the source and return offsets within it.
+ */
+export declare const isIdentStart: (c: string) => boolean;
+export declare const isIdent: (c: string) => boolean;
+/**
+ * Scan a quoted string body; `i` is just past the open quote.
+ *
+ * @returns The offset of the closing quote, or `end` when unterminated.
+ */
+export declare function scanQuoted(src: string, i: number, quote: string, end: number): number;
+/**
+ * Scan a `//` or `#` line comment body, which ends at a newline or at `?>`.
+ *
+ * @returns The offset past a consumed newline, or the offset of an unconsumed `?>`
+ *          (left for the caller, since `?>` closes both the comment and the island).
+ */
+export declare function scanLineComment(src: string, i: number, end: number): number;
+/**
+ * Scan a heredoc/nowdoc; `i` is just past `<<<`.
+ *
+ * @returns The offset past the closing identifier, or -1 if `<<<` isn't followed by a valid heredoc identifier.
+ */
+export declare function scanHeredoc(src: string, i: number, end: number): number;

package/dist/php-lexer.js

@@ -0,0 +1,96 @@
+/**
+ * Shared low-level PHP lexing helpers.
+ *
+ * Used by both passes that read PHP code — island detection (`islands.ts`) and string harvesting (`php-strings.ts`)
+ * — so the two can never drift apart on string/comment/heredoc boundary rules.
+ *
+ * All scanners operate on the `[i, end)` window of the source and return offsets within it.
+ */
+export const isIdentStart = (c) => /[A-Za-z_\u0080-\uffff]/.test(c);
+export const isIdent = (c) => /[A-Za-z0-9_\u0080-\uffff]/.test(c);
+/**
+ * Scan a quoted string body; `i` is just past the open quote.
+ *
+ * @returns The offset of the closing quote, or `end` when unterminated.
+ */
+export function scanQuoted(src, i, quote, end) {
+    while (i < end) {
+        const c = src[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (c === quote)
+            return i;
+        i++;
+    }
+    return end;
+}
+/**
+ * Scan a `//` or `#` line comment body, which ends at a newline or at `?>`.
+ *
+ * @returns The offset past a consumed newline, or the offset of an unconsumed `?>`
+ *          (left for the caller, since `?>` closes both the comment and the island).
+ */
+export function scanLineComment(src, i, end) {
+    while (i < end) {
+        if (src[i] === '\n')
+            return i + 1;
+        if (src[i] === '?' && src[i + 1] === '>')
+            return i;
+        i++;
+    }
+    return end;
+}
+/**
+ * Scan a heredoc/nowdoc; `i` is just past `<<<`.
+ *
+ * @returns The offset past the closing identifier, or -1 if `<<<` isn't followed by a valid heredoc identifier.
+ */
+export function scanHeredoc(src, i, end) {
+    // Optional whitespace (PHP allows spaces/tabs after `<<<`).
+    while (i < end && (src[i] === ' ' || src[i] === '\t'))
+        i++;
+    // Optional quote around the identifier.
+    let quote = '';
+    if (src[i] === "'" || src[i] === '"') {
+        quote = src[i];
+        i++;
+    }
+    if (i >= end || !isIdentStart(src[i]))
+        return -1;
+    const idStart = i;
+    while (i < end && isIdent(src[i]))
+        i++;
+    const id = src.slice(idStart, i);
+    if (quote) {
+        if (src[i] !== quote)
+            return -1;
+        i++;
+    }
+    // After the identifier, the line must end immediately — PHP disallows trailing whitespace,
+    // but we tolerate `\r` so `\r\n` endings still work.
+    while (i < end && src[i] === '\r')
+        i++;
+    if (src[i] !== '\n')
+        return -1;
+    i++;
+    // Find a line that starts with optional indentation,
+    // then the identifier followed by a non-identifier character
+    // (PHP 7.3 flexible syntax).
+    while (i < end) {
+        let j = i;
+        while (j < end && (src[j] === ' ' || src[j] === '\t'))
+            j++;
+        if (src.startsWith(id, j)) {
+            const k = j + id.length;
+            if (k >= end || !isIdent(src[k]))
+                return k;
+        }
+        const nl = src.indexOf('\n', i);
+        if (nl === -1 || nl >= end)
+            return end;
+        i = nl + 1;
+    }
+    return end;
+}

package/dist/php-strings.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PHP string-literal harvester — the optional third pass.
+ *
+ * Given the source and the PHP islands already found by `findIslands()`, this locates the byte ranges of every
+ * string literal *value* inside PHP code that is eligible for class sorting, applying these structural rules:
+ *
+ *   - Only the *value* of a `key => value` pair is eligible; array keys are never sorted.
+ *   - Bare list-style elements (`['a', 'b']`) and scalar assignments (`const X = '...'`) are values.
+ *   - Strings that are part of a concatenation expression (`'btn-' . $v`) are skipped — a literal joined to dynamic
+ *     code may be a partial class fragment, and reordering it would corrupt the rendered string.
+ *   - Double-quoted strings containing interpolation (`"p-4 {$x}"`) are skipped, mirroring the HTML side's
+ *     conservatism around dynamic content.
+ *   - Strings whose body contains a backslash escape are skipped, so escape sequences can never be mangled.
+ *   - Heredoc/nowdoc and backtick (shell-exec) strings are never harvested.
+ *
+ * This pass is opt-in per file (the caller decides which files are class-string holders); it does NOT judge whether
+ * a given string "looks like" Tailwind classes — within a matched file, every eligible value is sorted.
+ *
+ * @see islands.ts   - first pass; produces the islands consumed here.
+ * @see transform.ts - splices the sorted strings back via the shared byte-replacement path.
+ */
+import type { Island } from './islands.ts';
+/**
+ * Inner byte range of a sortable string literal — the span *between* the quotes, in original-source offsets.
+ */
+export interface PhpStringRange {
+    /**
+     * Offset of the first character inside the quotes.
+     */
+    start: number;
+    /**
+     * Offset just past the last character inside the quotes (exclusive).
+     */
+    end: number;
+}
+/**
+ * Find every sortable string-literal value within the given PHP islands.
+ *
+ * @param src     Original template source.
+ * @param islands Island ranges from `findIslands()`.
+ * @returns Inner ranges of eligible string values, in document order.
+ *
+ * @example
+ * const islands = findIslands(`<?php $x = 'z a'; ?>`);
+ * findSortablePhpStrings(`<?php $x = 'z a'; ?>`, islands); // [{ start: 11, end: 14 }]
+ */
+export declare function findSortablePhpStrings(src: string, islands: Island[]): PhpStringRange[];

package/dist/php-strings.js

@@ -0,0 +1,156 @@
+/**
+ * PHP string-literal harvester — the optional third pass.
+ *
+ * Given the source and the PHP islands already found by `findIslands()`, this locates the byte ranges of every
+ * string literal *value* inside PHP code that is eligible for class sorting, applying these structural rules:
+ *
+ *   - Only the *value* of a `key => value` pair is eligible; array keys are never sorted.
+ *   - Bare list-style elements (`['a', 'b']`) and scalar assignments (`const X = '...'`) are values.
+ *   - Strings that are part of a concatenation expression (`'btn-' . $v`) are skipped — a literal joined to dynamic
+ *     code may be a partial class fragment, and reordering it would corrupt the rendered string.
+ *   - Double-quoted strings containing interpolation (`"p-4 {$x}"`) are skipped, mirroring the HTML side's
+ *     conservatism around dynamic content.
+ *   - Strings whose body contains a backslash escape are skipped, so escape sequences can never be mangled.
+ *   - Heredoc/nowdoc and backtick (shell-exec) strings are never harvested.
+ *
+ * This pass is opt-in per file (the caller decides which files are class-string holders); it does NOT judge whether
+ * a given string "looks like" Tailwind classes — within a matched file, every eligible value is sorted.
+ *
+ * @see islands.ts   - first pass; produces the islands consumed here.
+ * @see transform.ts - splices the sorted strings back via the shared byte-replacement path.
+ */
+import { isIdent, isIdentStart, scanHeredoc, scanLineComment, scanQuoted } from "./php-lexer.js";
+/**
+ * Find every sortable string-literal value within the given PHP islands.
+ *
+ * @param src     Original template source.
+ * @param islands Island ranges from `findIslands()`.
+ * @returns Inner ranges of eligible string values, in document order.
+ *
+ * @example
+ * const islands = findIslands(`<?php $x = 'z a'; ?>`);
+ * findSortablePhpStrings(`<?php $x = 'z a'; ?>`, islands); // [{ start: 11, end: 14 }]
+ */
+export function findSortablePhpStrings(src, islands) {
+    const ranges = [];
+    for (const isl of islands) {
+        const tokens = tokenizeIsland(src, isl.start, isl.end);
+        for (let k = 0; k < tokens.length; k++) {
+            const token = tokens[k];
+            if (token.kind !== 'string' || token.skip)
+                continue;
+            const next = tokens[k + 1];
+            const prev = tokens[k - 1];
+            // Array key (`'left' => ...`) — never sorted.
+            if (next && next.kind === 'arrow')
+                continue;
+            // Part of a concatenation expression (`'btn-' . $v` / `$v . 'suffix'`).
+            if ((next && next.kind === 'dot') || (prev && prev.kind === 'dot'))
+                continue;
+            ranges.push({ start: token.start, end: token.end });
+        }
+    }
+    return ranges;
+}
+/**
+ * Tokenize one PHP island into the minimal token stream needed for value classification: string literals
+ * (with their inner range and a skip flag), the `=>` arrow, the `.` concatenation operator, and a coalesced `other`
+ * marker for everything else. Whitespace and comments are dropped so adjacency is judged across them.
+ */
+function tokenizeIsland(src, start, end) {
+    const tokens = [];
+    const pushOther = () => {
+        if (tokens.length === 0 || tokens[tokens.length - 1].kind !== 'other')
+            tokens.push({ kind: 'other' });
+    };
+    let i = start;
+    while (i < end) {
+        const c = src[i];
+        // Whitespace.
+        if (c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f' || c === '\v') {
+            i++;
+            continue;
+        }
+        // Line comments (`//`, `#`) — but `#[` opens a PHP 8 attribute, which is code.
+        if (c === '/' && src[i + 1] === '/') {
+            i = scanLineComment(src, i + 2, end);
+            continue;
+        }
+        if (c === '#' && src[i + 1] !== '[') {
+            i = scanLineComment(src, i + 1, end);
+            continue;
+        }
+        // Block comment.
+        if (c === '/' && src[i + 1] === '*') {
+            const close = src.indexOf('*/', i + 2);
+            i = close === -1 || close + 2 > end ? end : close + 2;
+            continue;
+        }
+        // Heredoc / nowdoc — never harvested; skip the whole construct.
+        if (c === '<' && src[i + 1] === '<' && src[i + 2] === '<') {
+            const here = scanHeredoc(src, i + 3, end);
+            if (here !== -1) {
+                i = here;
+                pushOther();
+                continue;
+            }
+        }
+        // Quoted strings.
+        if (c === "'") {
+            const close = scanQuoted(src, i + 1, "'", end);
+            const inner = src.slice(i + 1, close);
+            tokens.push({ kind: 'string', start: i + 1, end: close, skip: inner.includes('\\') });
+            i = close + 1;
+            continue;
+        }
+        if (c === '"') {
+            const close = scanQuoted(src, i + 1, '"', end);
+            const inner = src.slice(i + 1, close);
+            // Skip interpolation (any unescaped `$`) and escapes.
+            tokens.push({ kind: 'string', start: i + 1, end: close, skip: hasInterpolationOrEscape(inner) });
+            i = close + 1;
+            continue;
+        }
+        if (c === '`') {
+            // Shell-exec string — never a class list.
+            i = scanQuoted(src, i + 1, '`', end) + 1;
+            pushOther();
+            continue;
+        }
+        // Operators that matter for classification.
+        if (c === '=' && src[i + 1] === '>') {
+            tokens.push({ kind: 'arrow' });
+            i += 2;
+            continue;
+        }
+        if (c === '.') {
+            tokens.push({ kind: 'dot' });
+            i++;
+            continue;
+        }
+        // Everything else (identifiers, punctuation, the `<?php`/`?>` tags themselves).
+        pushOther();
+        if (isIdentStart(c)) {
+            i++;
+            while (i < end && isIdent(src[i]))
+                i++;
+        }
+        else {
+            i++;
+        }
+    }
+    return tokens;
+}
+/**
+ * True if a double-quoted body contains interpolation (an unescaped `$`) or any escape sequence.
+ */
+function hasInterpolationOrEscape(body) {
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c === '\\')
+            return true;
+        if (c === '$')
+            return true;
+    }
+    return false;
+}

package/dist/sorter.d.ts

@@ -11,7 +11,7 @@ import type { SortFn } from './transform.ts';
  */
 export interface SorterOptions {
     /**
-     * Tailwind v4 CSS entry point (`@import "tailwindcss"`, `@theme`, etc.).
+     * Tailwind v4 CSS entry point.
      */
     stylesheet: string;
     /**
@@ -20,8 +20,8 @@ export interface SorterOptions {
     base?: string;
 }
 /**
- * Create a `SortFn` backed by the official `prettier-plugin-tailwindcss` sorting engine, configured with
- * the project's Tailwind v4 stylesheet so custom `@theme` tokens and `@utility` classes sort correctly.
+ * Create a `SortFn` backed by the official `prettier-plugin-tailwindcss` sorting engine,
+ * configured with the project's Tailwind v4 stylesheet so custom tokens and classes sort correctly.
  *
  * Requires `prettier-plugin-tailwindcss` >= 0.8 (the `/sorter` entrypoint).
  *

package/dist/sorter.js

@@ -6,8 +6,8 @@
  * @see transform.ts - consumes the `SortFn` produced here.
  */
 /**
- * Create a `SortFn` backed by the official `prettier-plugin-tailwindcss` sorting engine, configured with
- * the project's Tailwind v4 stylesheet so custom `@theme` tokens and `@utility` classes sort correctly.
+ * Create a `SortFn` backed by the official `prettier-plugin-tailwindcss` sorting engine,
+ * configured with the project's Tailwind v4 stylesheet so custom tokens and classes sort correctly.
  *
  * Requires `prettier-plugin-tailwindcss` >= 0.8 (the `/sorter` entrypoint).
  *
@@ -15,8 +15,7 @@
  * @returns A synchronous `SortFn` for use with `transform()`.
  */
 export async function createTailwindSortFn(opts) {
-    // Dynamic import so the core package works without the dependency
-    // installed (e.g., when only running tests with a mock sorter).
+    // Dynamic import so the core package works without the dependency installed.
     const { createSorter } = await import('prettier-plugin-tailwindcss/sorter');
     const sorter = await createSorter({
         base: opts.base ?? process.cwd(),

package/dist/transform.d.ts

@@ -24,9 +24,13 @@ import { type HtmlScanOptions } from './html.ts';
  */
 export type SortFn = (classes: string[]) => string[];
 /**
- * Combined options for both lexer passes.
+ * Combined options for all lexer passes.
  */
 export interface TransformOptions extends IslandOptions, HtmlScanOptions {
+    /**
+     * Sort classes in PHP string-literal values too. Off by default; see `php-strings.ts` for eligibility.
+     */
+    sortPhpStrings?: boolean;
 }
 /**
  * Rewrite all class attribute values in the template source with sorted classes.

package/dist/transform.js

@@ -18,6 +18,7 @@
  */
 import { findIslands } from "./islands.js";
 import { maskIslands, findClassAttributes } from "./html.js";
+import { findSortablePhpStrings } from "./php-strings.js";
 /**
  * Rewrite all class attribute values in the template source with sorted classes.
  * Everything outside class attribute values is byte-identical in the result; the function is idempotent.
@@ -35,28 +36,64 @@ export function transform(src, sortFn, opts = {}) {
     const islands = findIslands(src, opts);
     const masked = maskIslands(src, islands);
     const attrs = findClassAttributes(masked, opts);
-    // Apply replacements back-to-front so offsets stay valid.
-    let out = src;
-    for (let a = attrs.length - 1; a >= 0; a--) {
-        const { valueStart, valueEnd } = attrs[a];
+    // Computed before the attribute pass: an edit inside a class-attribute island must be folded into that
+    // attribute's rewrite, or the enclosing rewrite would overwrite it and a second pass would be needed.
+    const phpEdits = [];
+    if (opts.sortPhpStrings) {
+        for (const { start, end } of findSortablePhpStrings(src, islands)) {
+            const original = src.slice(start, end);
+            const tokens = original.split(/\s+/).filter(Boolean);
+            if (tokens.length < 2)
+                continue; // nothing to reorder; leave byte-identical
+            const text = sortFn(tokens).join(' ');
+            if (text !== original)
+                phpEdits.push({ start, end, text });
+        }
+    }
+    // Collect every edit as a {start, end, text} range, then apply them back-to-front so offsets stay valid.
+    const edits = [];
+    const absorbed = new Set();
+    for (const { valueStart, valueEnd } of attrs) {
         const original = src.slice(valueStart, valueEnd);
         const inner = islands.filter((isl) => isl.start >= valueStart && isl.end <= valueEnd);
-        const rewritten = rewriteValue(original, valueStart, inner, sortFn);
-        if (rewritten !== original) {
-            out = out.slice(0, valueStart) + rewritten + out.slice(valueEnd);
-        }
+        const innerEdits = phpEdits.filter((e) => e.start >= valueStart && e.end <= valueEnd);
+        const rewritten = rewriteValue(original, valueStart, inner, sortFn, innerEdits);
+        if (rewritten !== original)
+            edits.push({ start: valueStart, end: valueEnd, text: rewritten });
+        for (const e of innerEdits)
+            absorbed.add(e);
     }
+    for (const e of phpEdits)
+        if (!absorbed.has(e))
+            edits.push(e);
+    edits.sort((a, b) => b.start - a.start);
+    let out = src;
+    for (const e of edits)
+        out = out.slice(0, e.start) + e.text + out.slice(e.end);
     return out;
 }
-function rewriteValue(value, base, islands, sortFn) {
-    // Build alternating static/island parts.
+/**
+ * Apply the edits that fall entirely within `[offset, offset + text.length)` to `text`.
+ * Edits arrive in document order and never overlap, so a back-to-front pass keeps offsets valid.
+ */
+function spliceEdits(text, offset, edits) {
+    for (let k = edits.length - 1; k >= 0; k--) {
+        const e = edits[k];
+        if (e.start < offset || e.end > offset + text.length)
+            continue;
+        text = text.slice(0, e.start - offset) + e.text + text.slice(e.end - offset);
+    }
+    return text;
+}
+function rewriteValue(value, base, islands, sortFn, phpEdits) {
+    // Build alternating static/island parts; island text carries any PHP-string edits it contains.
     const parts = [];
     let pos = 0;
     for (const isl of islands) {
         const s = isl.start - base;
         const e = isl.end - base;
         parts.push({ type: 'static', text: value.slice(pos, s) });
-        parts.push({ type: 'island', text: value.slice(s, e) });
+        parts.push({ type: 'island', text: spliceEdits(value.slice(s, e), isl.start, phpEdits) });
         pos = e;
     }
     parts.push({ type: 'static', text: value.slice(pos) });