@styleframe/scanner 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,419 @@
+import { ModifierFactory } from '@styleframe/core';
+import { Root } from '@styleframe/core';
+import { Utility } from '@styleframe/core';
+import { UtilityFactory } from '@styleframe/core';
+
+/**
+ * Pattern to extract the value from an arbitrary value bracket notation.
+ * Matches: [16px], [#1E3A8A], [10px_20px], etc.
+ */
+export declare const ARBITRARY_VALUE_PATTERN: RegExp;
+
+/**
+ * Cache entry for a scanned file
+ */
+export declare interface CacheEntry {
+    /** Content hash for change detection */
+    hash: string;
+    /** Cached scan result */
+    result: FileScanResult;
+    /** Cache timestamp */
+    timestamp: number;
+}
+
+/**
+ * Generate the raw utility class name from options (without CSS escaping).
+ */
+export declare function classNameFromUtilityOptions(options: UtilitySelectorOptions): string;
+
+/**
+ * Create a scanner cache instance.
+ *
+ * The cache stores scan results keyed by file path and validates
+ * entries using content hashing.
+ */
+export declare function createCache(): ScannerCache;
+
+/**
+ * Create a file change handler with debouncing.
+ *
+ * This is a utility for integrating with external file watchers.
+ * The actual file watching should be done at the plugin level
+ * using Vite's HMR or chokidar.
+ *
+ * @param callback Function to call when files change
+ * @param options Watcher options
+ * @returns A debounced change handler
+ */
+export declare function createChangeHandler(callback: (changedFiles: string[]) => void, options?: WatcherOptions): {
+    onChange: (filePath: string) => void;
+    flush: () => void;
+};
+
+/**
+ * Create a scanner that only scans specific content.
+ *
+ * Useful for testing or one-off scans.
+ */
+export declare function createContentScanner(customExtractors?: Extractor[]): (content: string, filePath?: string) => ParsedUtility[];
+
+/**
+ * Create a scanner instance for detecting utility classes in content files.
+ *
+ * @param config Scanner configuration
+ * @returns Scanner instance
+ *
+ * @example
+ * ```ts
+ * const scanner = createScanner({
+ *   content: ['./src/components/*.tsx', './src/pages/*.vue'],
+ * });
+ *
+ * const result = await scanner.scan();
+ * const matches = scanner.match(result.allParsed, root);
+ * ```
+ */
+export declare function createScanner(config: ScannerConfig): Scanner;
+
+/**
+ * Create a filter function that checks if a utility is in the used set.
+ *
+ * @param usedClasses Set of used utility class names
+ * @returns Filter function for utilities
+ */
+export declare function createUtilityFilter(usedClasses: Set<string>): (utility: Utility) => boolean;
+
+/**
+ * Simple debounce utility
+ */
+export declare function debounce<T extends (...args: unknown[]) => void>(fn: T, delay: number): (...args: Parameters<T>) => void;
+
+/**
+ * Default file extensions to scan for utility classes
+ */
+export declare const DEFAULT_EXTENSIONS: string[];
+
+/**
+ * Glob patterns to ignore when scanning
+ */
+export declare const DEFAULT_IGNORE_PATTERNS: string[];
+
+/**
+ * Extract utility classes from file content.
+ *
+ * @param content The file content
+ * @param filePath The file path (used to determine extractor)
+ * @param customExtractors Optional custom extractors to use in addition to defaults
+ * @returns Array of unique utility class names found
+ */
+export declare function extractClasses(content: string, filePath: string, customExtractors?: Extractor[]): string[];
+
+/**
+ * Extract utility classes from Astro content.
+ * Handles both HTML-like and JSX-like patterns.
+ */
+export declare function extractFromAstro(content: string): string[];
+
+/**
+ * Extract utility classes from HTML-like content.
+ * Handles class="..." attributes.
+ */
+export declare function extractFromHTML(content: string): string[];
+
+/**
+ * Extract utility classes from JSX/TSX content.
+ * Handles className="..." and className={...} patterns.
+ */
+export declare function extractFromJSX(content: string): string[];
+
+/**
+ * Extract utility classes from MDX content.
+ * Handles both Markdown and JSX patterns.
+ */
+export declare function extractFromMDX(content: string): string[];
+
+/**
+ * Extract utility classes from string literals in JavaScript/TypeScript code.
+ * Handles single quotes, double quotes, and template literals.
+ *
+ * Note: Template literals with interpolations (e.g., `_margin:${size}`) will only
+ * extract the static portions. Dynamic class names cannot be statically analyzed.
+ * For full coverage, use explicit string arrays or safelist patterns.
+ */
+export declare function extractFromStringLiterals(content: string): string[];
+
+/**
+ * Extract utility classes from Svelte content.
+ * Handles class="...", class:directive={condition}, and class={...} patterns.
+ */
+export declare function extractFromSvelte(content: string): string[];
+
+/**
+ * Extract utility classes from Vue SFC content.
+ * Handles class="...", :class="...", and :class="{...}" patterns.
+ */
+export declare function extractFromVue(content: string): string[];
+
+/**
+ * Custom extractor function type
+ */
+export declare type Extractor = (content: string, filePath: string) => string[];
+
+/**
+ * Extract all utility class names from a content string.
+ *
+ * @param content The content to search
+ * @returns Array of unique utility class names found
+ */
+export declare function extractUtilityClasses(content: string): string[];
+
+/**
+ * Scan result for a single file
+ */
+export declare interface FileScanResult {
+    /** Absolute file path */
+    path: string;
+    /** Set of raw class names found */
+    classes: Set<string>;
+    /** Parsed utility classes */
+    parsed: ParsedUtility[];
+    /** Timestamp of last scan */
+    lastScanned: number;
+}
+
+/**
+ * Filter root children to only include used utilities.
+ *
+ * @param root The Styleframe root instance
+ * @param usedClasses Set of used utility class names
+ * @returns Array of used children (utilities are filtered, other types pass through)
+ */
+export declare function filterUtilities(root: Root, usedClasses: Set<string>): Root["children"];
+
+/**
+ * Generate a utility selector string from components.
+ * This is the inverse of parseUtilityClass.
+ *
+ * @param name Utility name
+ * @param value Utility value
+ * @param modifiers Array of modifier names
+ * @returns The utility class name (without CSS escaping)
+ */
+export declare function generateUtilityClassName(name: string, value: string, modifiers?: string[]): string;
+
+/**
+ * Generate the CSS selector for a utility instance.
+ *
+ * This mirrors the logic from @styleframe/transpiler/defaults.ts
+ */
+export declare function generateUtilitySelector(options: UtilitySelectorOptions): string;
+
+/**
+ * Get matches for arbitrary values.
+ */
+export declare function getArbitraryMatches(matches: UtilityMatch[]): UtilityMatch[];
+
+/**
+ * Get matches that exist in the registered values.
+ */
+export declare function getExistingMatches(matches: UtilityMatch[]): UtilityMatch[];
+
+/**
+ * Get all unique utility class names from matches.
+ */
+export declare function getUsedClassNames(matches: UtilityMatch[]): Set<string>;
+
+/**
+ * Get matches that have a corresponding utility factory.
+ */
+export declare function getValidMatches(matches: UtilityMatch[]): UtilityMatch[];
+
+/**
+ * Create a simple hash from content for change detection.
+ * Uses a hash * 31 algorithm (similar to Java's String.hashCode),
+ * combined with content length to reduce collision probability.
+ */
+export declare function hashContent(content: string): string;
+
+/**
+ * Check if a file path matches any of the given glob patterns.
+ *
+ * This is a simple check that looks for common pattern matches.
+ * For full glob support, use a library like micromatch.
+ */
+export declare function matchesPatterns(filePath: string, patterns: string[]): boolean;
+
+/**
+ * Match parsed utility classes against registered utilities in the root.
+ *
+ * @param parsed Array of parsed utility classes
+ * @param root The Styleframe root instance
+ * @returns Array of match results
+ */
+export declare function matchUtilities(parsed: ParsedUtility[], root: Root): UtilityMatch[];
+
+/**
+ * Parsed utility class structure
+ */
+export declare interface ParsedUtility {
+    /** Original class name as found in content (e.g., "_margin:sm") */
+    raw: string;
+    /** Utility name (e.g., "margin", "background") */
+    name: string;
+    /** Value key (e.g., "sm", "primary", "[16px]") */
+    value: string;
+    /** Applied modifiers in order (e.g., ["hover", "dark"]) */
+    modifiers: string[];
+    /** Whether this uses arbitrary value syntax [value] */
+    isArbitrary: boolean;
+    /** The arbitrary value if isArbitrary is true (e.g., "16px") */
+    arbitraryValue?: string;
+}
+
+/**
+ * Parse a utility class name into its components.
+ *
+ * The utility class format is: _[modifiers:]name[:value]
+ *
+ * Examples:
+ * - "_margin:sm" → { name: "margin", value: "sm", modifiers: [] }
+ * - "_hover:margin:sm" → { name: "margin", value: "sm", modifiers: ["hover"] }
+ * - "_dark:hover:bg:primary" → { name: "bg", value: "primary", modifiers: ["dark", "hover"] }
+ * - "_margin:[16px]" → { name: "margin", value: "[16px]", isArbitrary: true, arbitraryValue: "16px" }
+ * - "_hidden" → { name: "hidden", value: "default", modifiers: [] }
+ *
+ * @param className The utility class name to parse
+ * @returns Parsed utility object or null if invalid
+ */
+export declare function parseUtilityClass(className: string): ParsedUtility | null;
+
+/**
+ * Quick utility to scan content and get parsed utilities.
+ *
+ * @param content Content string to scan
+ * @param filePath Optional file path hint for extractor selection
+ * @returns Array of parsed utilities
+ */
+export declare function quickScan(content: string, filePath?: string): ParsedUtility[];
+
+/**
+ * Scanner instance interface
+ */
+export declare interface Scanner {
+    /** Scan all content files */
+    scan(): Promise<ScanResult>;
+    /** Scan a single file */
+    scanFile(filePath: string): Promise<FileScanResult>;
+    /** Scan content string directly */
+    scanContent(content: string, filePath?: string): ParsedUtility[];
+    /** Match parsed utilities against a root instance */
+    match(parsed: ParsedUtility[], root: Root): UtilityMatch[];
+    /** Start watching content files for changes */
+    watch(callback: (result: ScanResult) => void): () => void;
+    /** Invalidate cache for a file or all files */
+    invalidate(filePath?: string): void;
+}
+
+/**
+ * Scanner cache interface
+ */
+export declare interface ScannerCache {
+    /** Get cached result for a file */
+    get(filePath: string): FileScanResult | null;
+    /** Cache a scan result */
+    set(filePath: string, result: FileScanResult, contentHash: string): void;
+    /** Check if a file has valid cache */
+    isValid(filePath: string, contentHash: string): boolean;
+    /** Get cached result if valid, null otherwise (single lookup) */
+    getIfValid(filePath: string, contentHash: string): FileScanResult | null;
+    /** Invalidate cache for a file */
+    invalidate(filePath: string): void;
+    /** Clear all cache entries */
+    clear(): void;
+}
+
+/**
+ * Configuration for the content scanner
+ */
+export declare interface ScannerConfig {
+    /** Glob patterns for files to scan */
+    content: string[];
+    /** Custom extraction functions */
+    extractors?: Extractor[];
+    /** Base directory for glob resolution (defaults to process.cwd()) */
+    cwd?: string;
+}
+
+/**
+ * Complete scan result across all files
+ */
+export declare interface ScanResult {
+    /** Map of file path to scan result */
+    files: Map<string, FileScanResult>;
+    /** All unique class names found */
+    allClasses: Set<string>;
+    /** All parsed utilities */
+    allParsed: ParsedUtility[];
+}
+
+/**
+ * Regex pattern to match Styleframe utility class names.
+ *
+ * Matches patterns like:
+ * - _margin:sm (base utility)
+ * - _hover:margin:sm (with modifier)
+ * - _dark:hover:background:primary (multiple modifiers)
+ * - _margin:[16px] (arbitrary value)
+ * - _background:[#1E3A8A] (arbitrary color)
+ * - _hidden (default value, no suffix)
+ * - _background:color.primary (dotted reference)
+ *
+ * Pattern breakdown:
+ * - `_` - Required prefix
+ * - `[a-zA-Z][a-zA-Z0-9-]*` - First segment (modifier or name)
+ * - `(?::[a-zA-Z0-9._-]+|\:\[[^\]]+\])*` - Additional segments with `:` separator
+ */
+export declare const UTILITY_CLASS_PATTERN: RegExp;
+
+/**
+ * Filter function for utilities
+ */
+export declare type UtilityFilterFn = (utility: Utility) => boolean;
+
+/**
+ * Match result between a parsed class and a utility factory
+ */
+export declare interface UtilityMatch {
+    /** The parsed utility class */
+    parsed: ParsedUtility;
+    /** The matched utility factory, or null if not found */
+    factory: UtilityFactory | null;
+    /** Matched modifier factories */
+    modifierFactories: ModifierFactory[];
+    /** Whether the utility value exists in the factory */
+    exists: boolean;
+}
+
+/**
+ * Utility selector generation options
+ */
+export declare interface UtilitySelectorOptions {
+    name: string;
+    value: string;
+    modifiers: string[];
+}
+
+/**
+ * Callback type for file change events
+ */
+export declare type WatchCallback = (result: ScanResult) => void;
+
+/**
+ * Options for creating a watcher
+ */
+export declare interface WatcherOptions {
+    /** Debounce time in milliseconds (default: 100) */
+    debounce?: number;
+}
+
+export { }