@runtimestudio/tailwind-sort-php 0.2.1 → 0.4.0

package/package.json

@@ -1,57 +1,57 @@
 {
-  "name": "@runtimestudio/tailwind-sort-php",
-  "version": "0.2.1",
-  "description": "Tailwind CSS Class Sorter for PHP",
-  "keywords": [
-    "class-sorting",
-    "formatter",
-    "php",
-    "prettier",
-    "tailwindcss",
-    "wordpress"
-  ],
-  "homepage": "https://github.com/runtime-studio-au/tailwind-sort-php#readme",
-  "bugs": "https://github.com/runtime-studio-au/tailwind-sort-php/issues",
-  "license": "MIT",
-  "author": "Greg Sevastos <greg@runtimestudio.com.au> (https://runtimestudio.com.au)",
-  "files": [
-    "dist",
-    "src"
-  ],
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "type": "module",
-  "bin": {
-    "tailwind-sort-php": "dist/cli.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/runtime-studio-au/tailwind-sort-php.git"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "prepublishOnly": "npm test && npm run build",
-    "sort": "bun run src/cli.ts",
-    "sort:check": "bun run src/cli.ts --check",
-    "test": "node --test \"test/*.test.ts\""
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "prettier": "^3.8",
-    "prettier-plugin-tailwindcss": "^0.8",
-    "tailwindcss": "^4",
-    "typescript": ">=5.7"
-  },
-  "peerDependencies": {
-    "prettier": ">=3",
-    "prettier-plugin-tailwindcss": ">=0.8"
-  },
-  "engines": {
-    "node": ">=22.18"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
+    "name": "@runtimestudio/tailwind-sort-php",
+    "version": "0.4.0",
+    "description": "Tailwind CSS Class Sorter for PHP",
+    "keywords": [
+        "class-sorting",
+        "formatter",
+        "php",
+        "prettier",
+        "tailwindcss",
+        "wordpress"
+    ],
+    "homepage": "https://github.com/runtime-studio-au/tailwind-sort-php#readme",
+    "bugs": "https://github.com/runtime-studio-au/tailwind-sort-php/issues",
+    "license": "MIT",
+    "author": "Greg Sevastos <greg@runtimestudio.com.au> (https://runtimestudio.com.au)",
+    "files": [
+        "dist",
+        "src"
+    ],
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module",
+    "bin": {
+        "tailwind-sort-php": "dist/cli.js"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/runtime-studio-au/tailwind-sort-php.git"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "prepublishOnly": "npm test && npm run build",
+        "sort": "bun run src/cli.ts",
+        "sort:check": "bun run src/cli.ts --check",
+        "test": "node --test \"test/*.test.ts\""
+    },
+    "devDependencies": {
+        "@types/bun": "latest",
+        "prettier": "^3.9",
+        "prettier-plugin-tailwindcss": "^0.8",
+        "tailwindcss": "^4.3",
+        "typescript": ">=5.7"
+    },
+    "peerDependencies": {
+        "prettier": ">=3",
+        "prettier-plugin-tailwindcss": ">=0.8"
+    },
+    "engines": {
+        "node": ">=22.18"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
 }

package/src/cli.ts

@@ -1,19 +1,10 @@
 #!/usr/bin/env node
 /**
- * tailwind-sort-php CLI
+ * tailwind-sort-php CLI — see `USAGE` for the flag reference.
  *
- * 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` when no globs are given.
- * Skips `node_modules`, `vendor`, `dist` and `.git`. The `init` subcommand installs the pre-commit hook; see `init.ts`.
+ * Option values fall back to the resolved Prettier config — the same source of truth `prettier-plugin-tailwindcss`
+ * uses; see `fromPrettierConfig()`.
+ * The `init` subcommand installs the pre-commit hook; see `init.ts`.
  */
 
 import { readFile, writeFile } from 'node:fs/promises';
@@ -21,14 +12,32 @@ import { transform, type TransformOptions } from './transform.ts';
 import { createTailwindSortFn } from './sorter.ts';
 import { runInit } from './init.ts';
 
+const USAGE = `Usage:
+  tailwind-sort-php [options] [glob ...]
+  tailwind-sort-php init [--fix] [--force] [--dry-run]
+
+Options:
+  --stylesheet <path>  Tailwind v4 CSS entry (default: tailwindStylesheet from your Prettier config)
+  --attr <name>        Extra attribute to sort (repeatable; merged with tailwindAttributes)
+  --php-source <glob>  Also sort class strings in PHP declarations in matching files
+                       (repeatable; merged with tailwindPhpSources)
+  --check              Don't write; exit 1 if any file needs sorting
+  --no-short-tags      Don't treat bare <? as a PHP open tag
+  -h, --help           Show this help
+  --version            Print the version
+
+Defaults to all .php files under the cwd when no globs are given;
+node_modules, vendor, dist and .git are always skipped.`;
+
 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 +47,39 @@ 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 === '--stylesheet') cli.stylesheet = requireValue(argv, ++i, a);
+        else if (a === '--attr') cli.attrs.push(requireValue(argv, ++i, a));
+        else if (a === '--php-source') cli.phpSources.push(requireValue(argv, ++i, a));
+        else if (a === '--check') cli.check = true;
+        else if (a === '--no-short-tags') cli.shortTags = false;
+        else if (a.startsWith('--')) {
+            console.error(`Unknown option: ${a}\n\n${USAGE}`);
+            process.exit(2);
+        } else cli.globs.push(a);
+    }
+    if (cli.globs.length === 0) cli.globs.push('**/*.php');
+    return cli;
+}
+
+/**
+ * Return a flag's value argument or exit with a usage error when it is missing or is itself a flag.
+ */
+function requireValue(argv: string[], i: number, flag: string): string {
+    const v = argv[i];
+    if (v === undefined || v.startsWith('--')) {
+        console.error(`Missing value for ${flag}`);
+        process.exit(2);
+    }
+    return v;
 }
 
 /**
@@ -65,17 +88,19 @@ function parseArgs(argv: string[]): Cli {
  * @param globs Glob patterns relative to `cwd`.
  */
 async function* scanFiles(globs: string[]): AsyncGenerator<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;
+    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');
+        // Prunes ignored directories during traversal; newer Node versions pass a Dirent instead of a path string.
+        const exclude = (entry: string | { name: string }) => ignored(typeof entry === 'string' ? entry : entry.name);
+        for (const pattern of globs) {
+            for await (const f of glob(pattern, { exclude })) yield f as string;
+        }
     }
-  }
 }
 
 /**
@@ -84,92 +109,117 @@ async function* scanFiles(globs: string[]): AsyncGenerator<string> {
  * @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: string) => IGNORE.some((d) => file.includes(`${d}/`) || file.startsWith(d));
+const ignored = (file: string) => file.split(/[\\/]/).some((seg) => IGNORE.includes(seg));
 
 /**
- * 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);
+
+    // Help/version take precedence everywhere, including after `init`.
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(USAGE);
+        return;
+    }
+    if (argv.includes('--version')) {
+        const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+        console.log(pkg.version);
+        return;
+    }
+
+    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);
     }
-  }
-
-  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}`);
+    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);
+    }
+
+    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);
 });