tailwind-typescript-plugin 1.4.1-beta.1 → 1.4.1-beta.10

package/CHANGELOG.md

@@ -1,3 +1,70 @@
+## [1.4.0-beta.10](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.4.0-beta.9...v1.4.0-beta.10) (2025-11-29)
+
+### ⚡ Performance
+
+* optimize test execution with sharding and separated test commands ([0a89bdd](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/0a89bddcd77ec96eba6a2c0ff579b1c8b4d46f2d))
+
+## [1.4.0-beta.9](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.4.0-beta.8...v1.4.0-beta.9) (2025-11-29)
+
+### ♻️ Code Refactoring
+
+* restructure test cases into folder-based organization with JSDoc comments ([13cc790](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/13cc7900545d35b215e12618c8e7b003cfc67d02))
+
+## [1.4.0-beta.8](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.4.0-beta.7...v1.4.0-beta.8) (2025-11-28)
+
+### ✨ Features
+
+* add import verification for utility functions ([9d34a12](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/9d34a129cdb05d5e74cba1510d89b9b6c6afeab6))
+* add namespace import verification for member expressions ([eaacf9a](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/eaacf9a808c7f63e1d2fa5a284c24e1426821aa6))
+
+### ♻️ Code Refactoring
+
+* add imports to test files and update default utility functions ([698fdc2](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/698fdc2afcfbb59dcd1cf6b17c754ef4a0b9a542))
+
+## [1.4.0-beta.7](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.4.0-beta.6...v1.4.0-beta.7) (2025-11-28)
+
+### ✨ Features
+
+* add wildcard pattern support for allowedClasses ([a490b68](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/a490b68800b54bfde6eadef42ab97aaee51550fc))
+
+## [1.4.0-beta.6](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.4.0-beta.5...v1.4.0-beta.6) (2025-11-28)
+
+### ✨ Features
+
+* add spread operator support for class name validation ([a4c4ad1](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/a4c4ad1fc2ef42e7d4d87351af4fe464384c44b3))
+
+### 🔧 Chores
+
+* add utility libraries and cn helper ([2ac664d](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/2ac664dc33ba4a5c52e3059ee5ec5c9257da1c78))
+
+## [1.4.0-beta.5](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.4.0-beta.4...v1.4.0-beta.5) (2025-11-27)
+
+### ♻️ Code Refactoring
+
+* split test cases into folder structure for better organization ([fbe6774](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/fbe67742147857fb7c01e6e925142ba26d9fe7bf))
+
+## [1.4.0-beta.4](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.4.0-beta.3...v1.4.0-beta.4) (2025-11-27)
+
+### ✨ Features
+
+* warn on all duplicate class occurrences ([d01d878](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/d01d87844da17e15d5608ddddb1e3fdc033c8d38))
+
+### 🐛 Bug Fixes
+
+* dispose plugin in benchmark to close file watchers ([9efdc6a](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/9efdc6a8e24de4dd3000c44fc075bb765ddba1bb))
+
+## [1.4.0-beta.3](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.4.0-beta.2...v1.4.0-beta.3) (2025-11-26)
+
+### ✨ Features
+
+* add hot reloading for global.css changes ([c215ae6](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/c215ae68b71741b1909460df0d22606dbfd5c0f1)), closes [#ff0000](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/issues/ff0000)
+
+## [1.4.0-beta.2](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.4.0-beta.1...v1.4.0-beta.2) (2025-11-26)
+
+### ✨ Features
+
+* add conflicting class detection ([a31c01a](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/commit/a31c01aa6e747e2949109273f7eec3f1b7ac4876))
+
 ## [1.4.0-beta.1](https://github.com/IvanRodriCalleja/tailwind-typescript-plugin/compare/v1.3.0...v1.4.0-beta.1) (2025-11-26)
 
 ### ✨ Features

package/README.md

@@ -82,15 +82,27 @@ Add the plugin to the `compilerOptions.plugins` array in your `tsconfig.json`:
 
 - `globalCss` (required): Path to your global CSS file that imports Tailwind CSS. This can be relative to your project root.
 
-- `allowedClasses` (optional): Array of custom class names that should be treated as valid alongside Tailwind classes. Useful for project-specific or third-party utility classes that aren't part of Tailwind.
+- `allowedClasses` (optional): Array of custom class names or wildcard patterns that should be treated as valid alongside Tailwind classes. Useful for project-specific or third-party utility classes that aren't part of Tailwind.
   - **Default**: `[]` (no custom classes allowed)
+  - **Supports wildcard patterns**:
+    | Pattern | Description | Example | Matches |
+    |---------|-------------|---------|---------|
+    | `prefix-*` | Matches classes starting with prefix | `custom-*` | `custom-button`, `custom-card` |
+    | `*-suffix` | Matches classes ending with suffix | `*-icon` | `arrow-icon`, `close-icon` |
+    | `*-contains-*` | Matches classes containing the string | `*-component-*` | `app-component-header` |
+    | `exact` | Exact match (no wildcards) | `my-class` | Only `my-class` |
   - **Example**:
     ```json
     {
-      "allowedClasses": ["custom-button", "app-header", "project-card"]
+      "allowedClasses": [
+        "custom-*",
+        "*-icon",
+        "*-component-*",
+        "exact-class"
+      ]
     }
     ```
-  - Classes in this list will be considered valid and won't trigger validation errors
+  - Classes matching any pattern will be considered valid and won't trigger validation errors
   - Works with all extraction patterns (literals, expressions, functions, arrays, etc.)
   - Combines with Tailwind classes - both are validated independently
 
@@ -128,34 +140,99 @@ Add the plugin to the `compilerOptions.plugins` array in your `tsconfig.json`:
     ```
   - **Performance impact**: Disabling unused extractors skips TypeChecker operations and symbol resolution for that library, providing faster validation
 
-- `utilityFunctions` (optional): Array of additional function names to validate. These will be **merged with the defaults**, so you don't lose the common ones.
-  - **Defaults (always included)**: `['clsx', 'cn', 'classnames', 'classNames', 'cx', 'cva', 'twMerge', 'tv']`
-  - **Add your own**: Provide custom function names that will be added to the defaults
-  - **Example config**:
-    ```json
-    {
-      "utilityFunctions": ["myCustomFn", "buildClasses"]
-    }
-    ```
-    This will validate: `clsx`, `cn`, `classnames`, `classNames`, `cx`, `cva`, `twMerge`, `tv`, **`myCustomFn`**, **`buildClasses`**
+- `utilityFunctions` (optional): Array of utility functions to validate. These will be **merged with the defaults**, so you don't lose the common ones. Supports two formats:
 
-  - **Supported patterns**:
-    ```typescript
-    // Simple calls (validated by default):
-    className={clsx('flex', 'items-center')}
-    className={cn('flex', 'items-center')}
+  **Simple string format** (matches by function name only):
+  ```json
+  {
+    "utilityFunctions": ["myCustomFn", "buildClasses"]
+  }
+  ```
+
+  **Object format with import verification** (matches by name AND verifies import source):
+  ```json
+  {
+    "utilityFunctions": [
+      { "name": "merge", "from": "@/lib/utils" },
+      { "name": "cx", "from": "my-styling-package" }
+    ]
+  }
+  ```
+
+  **Mixed format** (combine both):
+  ```json
+  {
+    "utilityFunctions": [
+      "anyFunctionNamedThis",
+      { "name": "merge", "from": "@/lib/utils" }
+    ]
+  }
+  ```
 
-    // Member expressions (nested property access):
-    className={utils.cn('flex', 'items-center')}
-    className={lib.clsx('flex', 'items-center')}
+  - **Defaults (always included)**: `clsx` (from 'clsx'), `cn` (name-only), `classnames`/`classNames`/`cx` (from 'classnames'), `twMerge` (from 'tailwind-merge'). Note: `cva` and `tv` are variant functions handled by dedicated extractors.
+  - **Import verification**: When using the object format with `from`, the plugin verifies the function is actually imported from that package before validating. This prevents false positives when a function with the same name exists but isn't a className utility.
+  - **Subpath matching**: `{ "name": "fn", "from": "my-pkg" }` also matches `import { fn } from 'my-pkg/utils'`
 
-    // Custom functions (add via config):
-    className={myCustomFn('flex', 'items-center')}
-    className={buildClasses('flex', 'items-center')}
+  **Example configurations**:
+  ```json
+  // Simple: just add function names
+  {
+    "utilityFunctions": ["myCustomFn", "buildClasses"]
+  }
 
-    // Dynamic calls (ignored, won't throw errors):
-    className={functions['cn']('flex', 'items-center')}
-    ```
+  // Precise: verify import sources
+  {
+    "utilityFunctions": [
+      { "name": "cn", "from": "@/lib/utils" },
+      { "name": "merge", "from": "tailwind-merge" }
+    ]
+  }
+
+  // Mixed: some with import verification, some without
+  {
+    "utilityFunctions": [
+      "anyFn",
+      { "name": "preciseFn", "from": "@/utils" }
+    ]
+  }
+  ```
+
+  **Supported import patterns**:
+  ```typescript
+  // Named import
+  import { merge } from '@/lib/utils';
+  className={merge('flex', 'items-center')} // ✅ Validated
+
+  // Default import
+  import merge from '@/lib/utils';
+  className={merge('flex', 'items-center')} // ✅ Validated
+
+  // Aliased import
+  import { something as merge } from '@/lib/utils';
+  className={merge('flex', 'items-center')} // ✅ Validated
+
+  // Wrong import source (not validated when using object format)
+  import { merge } from 'different-package';
+  className={merge('flex', 'invalid-class')} // ⏭️ Skipped (wrong import)
+  ```
+
+  **Supported call patterns**:
+  ```typescript
+  // Simple calls (validated by default):
+  className={clsx('flex', 'items-center')}
+  className={cn('flex', 'items-center')}
+
+  // Member expressions (nested property access):
+  className={utils.cn('flex', 'items-center')}
+  className={lib.clsx('flex', 'items-center')}
+
+  // Custom functions (add via config):
+  className={myCustomFn('flex', 'items-center')}
+  className={buildClasses('flex', 'items-center')}
+
+  // Dynamic calls (ignored, won't throw errors):
+  className={functions['cn']('flex', 'items-center')}
+  ```
 
 ### 2. Ensure your CSS file imports Tailwind
 
@@ -245,6 +322,18 @@ const validClass = 'flex items-center';
 const baseClass = 'flex';
 <div className={[baseClass, 'items-center']}>Array with variable</div>
 
+// ✅ Spread operator in arrays
+const baseClasses = ['flex', 'items-center'];
+<div className={[...baseClasses, 'p-4']}>Spread in array</div>
+
+// ✅ Spread operator in function calls
+<div className={cn(...baseClasses, 'p-4')}>Spread in function</div>
+
+// ✅ Multiple spreads
+const layoutClasses = ['flex', 'items-center'];
+const spacingClasses = ['p-4', 'm-2'];
+<div className={cn(...layoutClasses, ...spacingClasses)}>Multiple spreads</div>
+
 // ✅ Variables in tv() and cva()
 const buttonBase = 'font-semibold text-white';
 const button = tv({ base: buttonBase });
@@ -275,6 +364,14 @@ const badClass = 'invalid-array-class';
 // Error: The class "invalid-array-class" is not a valid Tailwind class.
 //        This value is used as className via variable "badClass" on line 8
 <div className={['flex', badClass]}>Array with invalid variable</div>
+
+// ❌ Invalid class in spread operator
+const invalidClasses = ['flex', 'invalid-spread-class'];
+// Error: The class "invalid-spread-class" is not a valid Tailwind class.
+<div className={[...invalidClasses, 'items-center']}>Spread with invalid</div>
+
+// ❌ Invalid class in spread within function call
+<div className={cn(...invalidClasses, 'p-4')}>Function spread with invalid</div>
 ```
 
 **Custom allowed classes**:
@@ -326,6 +423,18 @@ The plugin detects duplicate classes within the same `className` attribute and s
 <div className={cn(['flex', 'flex', 'items-center'])}>In array</div>
 // Warning: Duplicate class "flex"
 
+// ⚠️ Warning: Duplicates with spread operators
+const baseClasses = ['flex', 'items-center'];
+<div className={cn(...baseClasses, 'flex', 'items-center', 'p-4')}>Spread duplicates</div>
+// Warning: Duplicate class "flex"
+// Warning: Duplicate class "items-center"
+
+// ⚠️ Warning: Duplicates between multiple spreads
+const layoutClasses = ['flex', 'items-center'];
+const containerClasses = ['flex', 'justify-center'];
+<div className={cn(...layoutClasses, ...containerClasses)}>Multiple spread duplicates</div>
+// Warning: Duplicate class "flex"
+
 // ✅ Valid: Same class in DIFFERENT elements (not duplicates)
 <div className="flex items-center">
   <span className="flex justify-center">Different elements</span>
@@ -479,6 +588,22 @@ The plugin intelligently handles ternary expressions - conflicts are NOT flagged
 // Warning: Both classes affect text-align
 ```
 
+**Conflicts with spread operators**:
+
+```tsx
+// ⚠️ Warning: Conflicts with spread operator
+const baseClasses = ['flex', 'p-4'];
+<div className={cn(...baseClasses, 'p-2', 'items-center')}>Spread conflict</div>
+// Warning: Class "p-4" conflicts with "p-2". Both affect the padding property.
+
+// ⚠️ Warning: Conflicts between multiple spreads
+const smallText = ['text-sm', 'font-medium'];
+const largeText = ['text-lg', 'font-bold'];
+<div className={cn(...smallText, ...largeText)}>Multiple spread conflicts</div>
+// Warning: Class "text-sm" conflicts with "text-lg". Both affect the font-size property.
+// Warning: Class "font-medium" conflicts with "font-bold". Both affect the font-weight property.
+```
+
 **Conflicts in tv() and cva()**:
 
 The plugin detects conflicts within `tv()` and `cva()` base properties, but intelligently skips conflicts between base and variants since variants are designed to override base styles:
@@ -834,6 +959,15 @@ const card2 = tv({ base: 'flex justify-center' });
   Validates variables used in computed object property keys
   Example: `const myClass = 'invalid-class'; <div className={{ [myClass]: true }}>Object</div>`
 
+- [X] **Spread Operator** → [`test-spread-operator/`](./example/src/test-spread-operator/)
+  Validates spread operators in arrays and function calls
+  Example: `const base = ['flex', 'invalid']; <div className={[...base, 'p-4']}>Spread</div>`
+  - Spread in arrays: `className={[...baseClasses, 'p-4']}`
+  - Spread in function calls: `className={cn(...baseClasses, 'p-4')}`
+  - Multiple spreads: `className={cn(...layoutClasses, ...spacingClasses)}`
+  - Nested spreads: Variables containing arrays with spreads are resolved
+  - Detects invalid classes, duplicates, and conflicts within spread expressions
+
 - [X] **TV Variable** → [`tv-variable.tsx`](./example/src/tv-variable.tsx)
   Validates variables in tailwind-variants tv() definitions
   Example: `const baseClasses = 'invalid-class'; const button = tv({ base: baseClasses })`
@@ -842,19 +976,19 @@ const card2 = tv({ base: 'flex justify-center' });
   Validates variables in class-variance-authority cva() definitions
   Example: `const baseClasses = 'invalid-class'; const button = cva(baseClasses)`
 
-- [X] **Duplicate Classes** → [`duplicate-classes.tsx`](./example/src/duplicate-classes.tsx)
+- [X] **Duplicate Classes** → [`duplicate-classes/`](./example/src/duplicate-classes/)
   Detects duplicate classes within the same className attribute
-  Example: `className="flex flex items-center"` shows warning on second `flex`
+  Example: `className="flex flex items-center"` shows warning on both `flex` occurrences
 
-- [X] **Duplicate Classes in Ternary** → [`duplicate-classes.tsx`](./example/src/duplicate-classes.tsx)
+- [X] **Duplicate Classes in Ternary** → [`duplicate-classes/`](./example/src/duplicate-classes/)
   Smart detection of duplicates in ternary expressions:
-  - Root + branch duplicate: `clsx('flex', isActive ? 'flex' : 'flex')` → Warning (true duplicate)
+  - Root + branch duplicate: `clsx('flex', isActive ? 'flex' : 'flex')` → Warning on all occurrences
   - Both branches same class: `clsx('mt-4', isActive ? 'flex' : 'flex')` → Warning (consider extracting)
   - Single branch only: `clsx('mt-4', isActive ? 'flex' : '')` → No warning (valid pattern)
 
-- [X] **Duplicate Classes in Variables with Conditionals** → [`duplicate-classes.tsx`](./example/src/duplicate-classes.tsx)
+- [X] **Duplicate Classes in Variables with Conditionals** → [`duplicate-classes/`](./example/src/duplicate-classes/)
   Resolves variables containing ternary expressions and detects duplicates:
-  - `const x = isActive ? 'flex' : 'flex'; clsx('flex', x)` → Warning (root + variable duplicate)
+  - `const x = isActive ? 'flex' : 'flex'; clsx('flex', x)` → Warning on all occurrences
   - `const x = isActive ? 'flex' : 'flex'; clsx('mt-4', x)` → Warning (consider extracting from variable)
   - `const x = isActive ? 'flex' : ''; clsx('mt-4', x)` → No warning (single branch)
 
@@ -879,6 +1013,16 @@ const card2 = tv({ base: 'flex justify-center' });
   - Works with clsx, cn, tv(), cva() and other utility functions
   - tv()/cva() base vs variant: NO conflict (variants are designed to override base)
 
+- [X] **Utility Function Import Verification** → [`utility-function-imports/`](./example/src/utility-function-imports/)
+  Validates custom utility functions with optional import source verification
+  Example: `{ "name": "merge", "from": "@/lib/utils" }` only validates `merge()` if imported from `@/lib/utils`
+  - Supports simple string format (name-only matching) and object format (with import verification)
+  - Named imports: `import { merge } from '@/lib/utils'`
+  - Default imports: `import merge from '@/lib/utils'`
+  - Aliased imports: `import { something as merge } from '@/lib/utils'`
+  - Subpath matching: `{ "from": "my-pkg" }` matches `import from 'my-pkg/utils'`
+  - Functions from wrong import sources are skipped (prevents false positives)
+
 ## How It Works
 
 The plugin hooks into the TypeScript Language Service and:
@@ -902,6 +1046,34 @@ The plugin is designed for minimal performance impact:
 
 **Typical overhead**: <1ms per file for most files, ~2-3ms for files with many tv()/cva() calls
 
+## Hot Reloading
+
+The plugin automatically watches your global CSS file for changes. When you modify your Tailwind configuration or add custom classes in your CSS file, the plugin will:
+
+1. **Detect changes** - Watches the `globalCss` file specified in your `tsconfig.json`
+2. **Reload the design system** - Automatically re-parses your Tailwind configuration
+3. **Clear caches** - Invalidates all diagnostic caches
+4. **Refresh diagnostics** - Requests TypeScript to revalidate all open files
+
+This means you can add new custom classes or modify your Tailwind theme, and the plugin will immediately recognize them without restarting your editor or TypeScript server.
+
+```css
+/* global.css */
+@import "tailwindcss";
+
+/* Add a custom utility - plugin will recognize it after save */
+@utility custom-gradient {
+  background: linear-gradient(to right, #ff7e5f, #feb47b);
+}
+```
+
+```tsx
+// This will be valid immediately after saving global.css
+<div className="custom-gradient">Hot reloaded!</div>
+```
+
+**Note**: The file watcher uses debouncing (300ms) to avoid excessive reloads when making rapid changes.
+
 ## Development
 
 This is a monorepo using Yarn workspaces:
@@ -944,7 +1116,7 @@ Commit to main → Auto-publishes 1.0.33-beta.3
 
 Users can install beta versions:
 ```bash
-npm install typescript-custom-plugin@beta
+npm install tailwind-typescript-plugin@beta
 ```
 
 ### Stable Releases (Manual)

package/lib/core/interfaces.d.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript/lib/tsserverlibrary';
-import { ClassNameInfo, ExtractionContext } from './types';
+import { ClassNameInfo, ExtractionContext, UtilityFunction } from './types';
 /**
  * Base interface for class name extractors
  * Follows the Strategy pattern for extensibility
@@ -34,7 +34,7 @@ export interface IVariantsConfig {
  */
 export interface IPluginConfig {
     globalCss?: string;
-    utilityFunctions?: string[];
+    utilityFunctions?: UtilityFunction[];
     variants?: IVariantsConfig;
     allowedClasses?: string[];
     enableLogging?: boolean;

package/lib/core/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/core/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAE9D;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,aAAa,EAAE,CAAC;CACpE;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,aAAa,IAAI,OAAO,CAAC;IACzB,iBAAiB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,gBAAgB,CAAC,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,UAAU,CAAC;CACrF"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/core/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE5E;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAE9D;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,aAAa,EAAE,CAAC;CACpE;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,aAAa,IAAI,OAAO,CAAC;IACzB,iBAAiB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,gBAAgB,CAAC,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,UAAU,CAAC;CACrF"}

package/lib/core/types.d.ts

@@ -1,4 +1,22 @@
 import * as ts from 'typescript/lib/tsserverlibrary';
+/**
+ * Represents a utility function configuration with optional import source
+ * When 'from' is specified, the import will be verified before matching
+ *
+ * Examples:
+ * - { name: 'clsx', from: 'clsx' } - matches `import { clsx } from 'clsx'` or `import clsx from 'clsx'`
+ * - { name: 'cn', from: '@/lib/utils' } - matches `import { cn } from '@/lib/utils'`
+ */
+export interface UtilityFunctionConfig {
+    name: string;
+    from: string;
+}
+/**
+ * A utility function can be either:
+ * - A simple string (matches by function name only, backwards compatible)
+ * - A UtilityFunctionConfig object (matches by name AND verifies import source)
+ */
+export type UtilityFunction = string | UtilityFunctionConfig;
 /**
  * Represents information about a class name found in source code
  */
@@ -45,7 +63,7 @@ export interface ClassNameInfo {
 export interface ExtractionContext {
     readonly typescript: typeof ts;
     readonly sourceFile: ts.SourceFile;
-    readonly utilityFunctions: string[];
+    readonly utilityFunctions: UtilityFunction[];
     readonly typeChecker?: ts.TypeChecker;
 }
 /**

package/lib/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,aAAa,CAAC,EAAE;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;KAClB,CAAC;IACF;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,aAAa,EAAE,CAAC;CAC5B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,qBAAqB,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,aAAa,CAAC,EAAE;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;KAClB,CAAC;IACF;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,aAAa,EAAE,CAAC;CAC5B"}

package/lib/extractors/BaseExtractor.d.ts

@@ -1,11 +1,21 @@
 import * as ts from 'typescript/lib/tsserverlibrary';
 import { IClassNameExtractor } from '../core/interfaces';
-import { ClassNameInfo, ExtractionContext } from '../core/types';
+import { ClassNameInfo, ExtractionContext, UtilityFunction } from '../core/types';
 /**
  * Abstract base class for all extractors
  * Provides common functionality and enforces the contract
  */
 export declare abstract class BaseExtractor implements IClassNameExtractor {
+    /**
+     * Cache for import mappings per file
+     * Maps filename -> (local identifier name -> module specifier)
+     */
+    private importCache;
+    /**
+     * Cache for namespace import mappings per file
+     * Maps filename -> (namespace identifier -> module specifier)
+     */
+    private namespaceImportCache;
     abstract canHandle(node: ts.Node, context: ExtractionContext): boolean;
     abstract extract(node: ts.Node, context: ExtractionContext): ClassNameInfo[];
     /**
@@ -15,7 +25,44 @@ export declare abstract class BaseExtractor implements IClassNameExtractor {
     protected extractFromStringLiteral(literal: ts.StringLiteral | ts.NoSubstitutionTemplateLiteral, context: ExtractionContext): ClassNameInfo[];
     /**
      * Helper method to check if a function call should be validated
+     * Supports both simple string matching and precise import verification
+     */
+    protected shouldValidateFunctionCall(callExpression: ts.CallExpression, utilityFunctions: UtilityFunction[], context?: ExtractionContext): boolean;
+    /**
+     * Check if a function name is imported from a specific module
+     * Supports:
+     * - Named imports: import { clsx } from 'clsx'
+     * - Aliased imports: import { clsx as cx } from 'clsx'
+     * - Default imports: import clsx from 'clsx'
+     */
+    protected isImportedFrom(functionName: string, expectedModule: string, context: ExtractionContext): boolean;
+    /**
+     * Check if an object name is a namespace import from a specific module
+     * For: import * as utils from 'clsx' -> utils.clsx('flex')
+     */
+    protected isNamespaceImportedFrom(objectName: string, expectedModule: string, context: ExtractionContext): boolean;
+    /**
+     * Get the import map for the current file
+     * Caches the result for performance
+     */
+    private getImportMap;
+    /**
+     * Get the namespace import map for the current file
+     * Caches the result for performance
+     */
+    private getNamespaceImportMap;
+    /**
+     * Build both import maps (regular and namespace) for the current file
+     */
+    private buildImportMaps;
+    /**
+     * Clear the import cache (useful for testing or when files change)
+     */
+    clearImportCache(): void;
+    /**
+     * Check if a function name matches any utility function (by name only)
+     * Used for quick exclusion checks without import verification
      */
-    protected shouldValidateFunctionCall(callExpression: ts.CallExpression, utilityFunctions: string[]): boolean;
+    protected isUtilityFunctionName(functionName: string, utilityFunctions: UtilityFunction[]): boolean;
 }
 //# sourceMappingURL=BaseExtractor.d.ts.map

package/lib/extractors/BaseExtractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseExtractor.d.ts","sourceRoot":"","sources":["../../src/extractors/BaseExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEjE;;;GAGG;AACH,8BAAsB,aAAc,YAAW,mBAAmB;IACjE,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO;IACtE,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,aAAa,EAAE;IAE5E;;;OAGG;IACH,SAAS,CAAC,wBAAwB,CACjC,OAAO,EAAE,EAAE,CAAC,aAAa,GAAG,EAAE,CAAC,6BAA6B,EAC5D,OAAO,EAAE,iBAAiB,GACxB,aAAa,EAAE;IA0BlB;;OAEG;IACH,SAAS,CAAC,0BAA0B,CACnC,cAAc,EAAE,EAAE,CAAC,cAAc,EACjC,gBAAgB,EAAE,MAAM,EAAE,GACxB,OAAO;CAgBV"}
+{"version":3,"file":"BaseExtractor.d.ts","sourceRoot":"","sources":["../../src/extractors/BaseExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAclF;;;GAGG;AACH,8BAAsB,aAAc,YAAW,mBAAmB;IACjE;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAgC;IAEnD;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAAyC;IAErE,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO;IACtE,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,aAAa,EAAE;IAE5E;;;OAGG;IACH,SAAS,CAAC,wBAAwB,CACjC,OAAO,EAAE,EAAE,CAAC,aAAa,GAAG,EAAE,CAAC,6BAA6B,EAC5D,OAAO,EAAE,iBAAiB,GACxB,aAAa,EAAE;IA0BlB;;;OAGG;IACH,SAAS,CAAC,0BAA0B,CACnC,cAAc,EAAE,EAAE,CAAC,cAAc,EACjC,gBAAgB,EAAE,eAAe,EAAE,EACnC,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO;IAyDV;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,CACvB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,iBAAiB,GACxB,OAAO;IAYV;;;OAGG;IACH,SAAS,CAAC,uBAAuB,CAChC,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,iBAAiB,GACxB,OAAO;IAYV;;;OAGG;IACH,OAAO,CAAC,YAAY;IAcpB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;OAEG;IACH,OAAO,CAAC,eAAe;IAsDvB;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAKxB;;;OAGG;IACH,SAAS,CAAC,qBAAqB,CAC9B,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,eAAe,EAAE,GACjC,OAAO;CASV"}