@runtimestudio/tailwind-sort-php 0.2.0 → 0.3.0

package/src/cli.ts

@@ -9,10 +9,11 @@
  * Options:
  *   --stylesheet <path> Tailwind v4 CSS entry
  *   --attr <name> Extra attribute to sort (repeatable)
+ *   --php-source <glob> Also sort class strings in PHP declarations in matching files (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.
+ * Defaults to all `.php` files under `cwd` when no globs are given.
  * Skips `node_modules`, `vendor`, `dist` and `.git`. The `init` subcommand installs the pre-commit hook; see `init.ts`.
  */
 
@@ -24,11 +25,12 @@ import { runInit } from './init.ts';
 const IGNORE = ['node_modules', 'vendor', 'dist', '.git'];
 
 interface Cli {
-  globs: string[];
-  stylesheet?: string;
-  attrs: string[];
-  check: boolean;
-  shortTags: boolean;
+    globs: string[];
+    stylesheet?: string;
+    attrs: string[];
+    phpSources: string[];
+    check: boolean;
+    shortTags: boolean;
 }
 
 /**
@@ -38,25 +40,27 @@ interface Cli {
  * @returns Parsed CLI options with defaults applied.
  */
 function parseArgs(argv: string[]): Cli {
-  const cli: 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;
+    const cli: Cli = {
+        globs: [],
+        attrs: ['class', 'className'],
+        phpSources: [],
+        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 === '--php-source') cli.phpSources.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;
 }
 
 /**
@@ -65,18 +69,17 @@ function parseArgs(argv: string[]): Cli {
  * @param globs Glob patterns relative to `cwd`.
  */
 async function* scanFiles(globs: string[]): AsyncGenerator<string> {
-  // Use `Bun.Glob` when available, fall back to `node:fs` glob (Node 22+).
-  if (typeof (globalThis as any).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 as string;
+    if (typeof (globalThis as any).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 as string;
+        }
     }
-  }
 }
 
 /**
@@ -88,89 +91,102 @@ async function* scanFiles(globs: string[]): AsyncGenerator<string> {
 const ignored = (file: string) => 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).
+ * Best-effort read of the resolved Prettier config — the shared source of truth with `prettier-plugin-tailwindcss`.
+ * Picks up `tailwindStylesheet`, `tailwindAttributes`, and `tailwindPhpSources`.
  *
- * @returns The resolved stylesheet path and attributes, or an empty object if none are available.
+ * @returns The found settings, or an empty object if none are available.
  */
 async function fromPrettierConfig(): Promise<{
-  stylesheet?: string;
-  attributes?: string[];
+    stylesheet?: string;
+    attributes?: string[];
+    phpSources?: string[];
 }> {
-  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)) as Record<string, unknown> | null;
-    if (!cfg) return {};
-    const out: { stylesheet?: string; attributes?: string[] } = {};
-    if (typeof cfg.tailwindStylesheet === 'string') {
-      out.stylesheet = resolve(dirname(configFile), cfg.tailwindStylesheet);
-    }
-    if (Array.isArray(cfg.tailwindAttributes)) {
-      out.attributes = cfg.tailwindAttributes.filter((a): a is string => typeof a === 'string' && !a.startsWith('/'));
+    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)) as Record<string, unknown> | null;
+        if (!cfg) return {};
+        const out: { stylesheet?: string; attributes?: string[]; phpSources?: string[] } = {};
+        if (typeof cfg.tailwindStylesheet === 'string') {
+            out.stylesheet = resolve(dirname(configFile), cfg.tailwindStylesheet);
+        }
+        if (Array.isArray(cfg.tailwindAttributes)) {
+            out.attributes = cfg.tailwindAttributes.filter(
+                (a): a is string => typeof a === 'string' && !a.startsWith('/'),
+            );
+        }
+        if (Array.isArray(cfg.tailwindPhpSources)) {
+            out.phpSources = cfg.tailwindPhpSources.filter((p): p is string => typeof p === 'string');
+        }
+        return out;
+    } catch {
+        return {}; // prettier not installed or config unreadable — flags only
     }
-    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 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: TransformOptions = {
+        attributes: cli.attrs,
+        shortOpenTags: cli.shortTags,
+    };
+
+    // Pre-scan the opt-in `tailwindPhpSources` globs; a file gets `sortPhpStrings` only if it matches one.
+    const phpSources = [...cli.phpSources, ...(pc.phpSources ?? [])];
+    const phpSourceFiles = new Set<string>();
+    for await (const file of scanFiles(phpSources)) {
+        if (!ignored(file)) phpSourceFiles.add(file);
     }
-  }
-
-  const sortFn = await createTailwindSortFn({ stylesheet });
-  const opts: TransformOptions = {
-    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}`);
+
+    let scanned = 0;
+    let changed = 0;
+    const seen = new Set<string>();
+
+    // Include php-source files so a designated holder is sorted even outside the main globs; `seen` dedupes.
+    for await (const file of scanFiles([...cli.globs, ...phpSources])) {
+        if (ignored(file) || seen.has(file)) continue;
+        seen.add(file);
+        scanned++;
+        const src = await readFile(file, 'utf8');
+        const out = transform(src, sortFn, { ...opts, sortPhpStrings: phpSourceFiles.has(file) });
+        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);
+    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);
+    console.error(err);
+    process.exit(1);
 });

package/src/html.ts

@@ -8,7 +8,7 @@
  *   - 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.
+ * their content may contain strings like `class="..."` that must not be touched.
  *
  * @see islands.ts - first pass; produces the islands consumed here.
  */
@@ -19,28 +19,28 @@ 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;
+    /**
+     * 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[];
+    /**
+     * Lowercase attribute names to collect; default `['class', 'classname']`.
+     */
+    attributes?: string[];
 }
 
 const RAW_TEXT_TAGS = new Set(['script', 'style', 'textarea', 'title']);
@@ -56,16 +56,16 @@ const NUL = '\x00';
  * @returns Masked source of identical length.
  */
 export function maskIslands(src: string, islands: Island[]): string {
-  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;
+    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;
 }
 
 /**
@@ -76,58 +76,58 @@ export function maskIslands(src: string, islands: Island[]): string {
  * @returns Attribute value locations in document order. Offsets index into the original source.
  */
 export function findClassAttributes(masked: string, opts: HtmlScanOptions = {}): ClassAttr[] {
-  const wanted = new Set((opts.attributes ?? ['class', 'classname']).map((a) => a.toLowerCase()));
-  const out: ClassAttr[] = [];
-  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;
+    const wanted = new Set((opts.attributes ?? ['class', 'classname']).map((a) => a.toLowerCase()));
+    const out: ClassAttr[] = [];
+    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;
     }
 
-    i = lt + 1;
-  }
-
-  return out;
+    return out;
 }
 
 const isTagWs = (c: string) => c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f' || c === NUL;
@@ -137,48 +137,48 @@ const isTagWs = (c: string) => c === ' ' || c === '\t' || c === '\n' || c === '\
  * Returns the offset after `>` (or EOF). Pushes matches into `out`.
  */
 function scanTagAttributes(masked: string, i: number, wanted: Set<string>, out: ClassAttr[]): number {
-  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++;
+    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;
+    return len;
 }

package/src/index.ts

@@ -11,4 +11,5 @@
 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 { findSortablePhpStrings, type PhpStringRange } from './php-strings.ts';
 export { createTailwindSortFn, type SorterOptions } from './sorter.ts';