tailwind-styled-v4 5.0.0 → 5.0.2

package/dist/engine.d.ts

@@ -0,0 +1,398 @@
+import { ScanWorkspaceResult, ScanWorkspaceOptions } from './scanner.js';
+export { ScanFileResult } from './scanner.js';
+
+interface EngineMetricsSnapshot {
+    eventsReceived: number;
+    eventsProcessed: number;
+    batchesProcessed: number;
+    incrementalUpdates: number;
+    fullRescans: number;
+    skippedLargeFiles: number;
+    queueMaxSize: number;
+    lastBuildMs: number;
+    avgBuildMs: number;
+}
+declare class EngineMetricsCollector {
+    private eventsReceived;
+    private eventsProcessed;
+    private batchesProcessed;
+    private incrementalUpdates;
+    private fullRescans;
+    private skippedLargeFiles;
+    private queueMaxSize;
+    private lastBuildMs;
+    private totalBuildMs;
+    markEventReceived(queueSize: number): void;
+    markBatchProcessed(batchSize: number): void;
+    markIncremental(): void;
+    markFullRescan(): void;
+    markSkippedLargeFile(): void;
+    markBuildDuration(ms: number): void;
+    snapshot(): EngineMetricsSnapshot;
+}
+
+interface EnginePluginContext {
+    root: string;
+    timestamp: number;
+}
+interface EngineWatchContext {
+    root: string;
+    timestamp: number;
+}
+interface EnginePlugin {
+    name: string;
+    beforeScan?(context: EnginePluginContext): void | Promise<void>;
+    afterScan?(scan: ScanWorkspaceResult, context: EnginePluginContext): ScanWorkspaceResult | void | Promise<ScanWorkspaceResult | void>;
+    transformClasses?(classes: string[], context: EnginePluginContext): string[] | void | Promise<string[] | void>;
+    beforeBuild?(scan: ScanWorkspaceResult, context: EnginePluginContext): void | Promise<void>;
+    afterBuild?(result: BuildResult, context: EnginePluginContext): BuildResult | void | Promise<BuildResult | void>;
+    onError?(error: Error, context: EnginePluginContext): void | Promise<void>;
+    beforeWatch?(context: EngineWatchContext): void | Promise<void>;
+    afterWatch?(context: EngineWatchContext): void | Promise<void>;
+}
+declare function runBeforeScan(plugins: EnginePlugin[], context: EnginePluginContext): Promise<void>;
+declare function runAfterScan(plugins: EnginePlugin[], scan: ScanWorkspaceResult, context: EnginePluginContext): Promise<ScanWorkspaceResult>;
+declare function runTransformClasses(plugins: EnginePlugin[], classes: string[], context: EnginePluginContext): Promise<string[]>;
+declare function runBeforeBuild(plugins: EnginePlugin[], scan: ScanWorkspaceResult, context: EnginePluginContext): Promise<void>;
+declare function runAfterBuild(plugins: EnginePlugin[], result: BuildResult, context: EnginePluginContext): Promise<BuildResult>;
+declare function runOnError(plugins: EnginePlugin[], error: Error, context: EnginePluginContext): Promise<void>;
+declare function runBeforeWatch(plugins: EnginePlugin[], context: EngineWatchContext): Promise<void>;
+declare function runAfterWatch(plugins: EnginePlugin[], context: EngineWatchContext): Promise<void>;
+
+declare class RuleId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class SelectorId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class VariantChainId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class PropertyId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class ValueId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class LayerId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class ConditionId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class CascadeResolutionId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare enum Origin {
+    UserAgent = 0,
+    UserNormal = 1,
+    AuthorNormal = 2,
+    AuthorImportant = 3,
+    UserImportant = 4
+}
+declare enum Importance {
+    Normal = 0,
+    Important = 1
+}
+declare enum ConditionResult {
+    Active = 0,
+    Inactive = 1,
+    Unknown = 2
+}
+declare enum CascadeStage {
+    Origin = 0,
+    Layer = 1,
+    Importance = 2,
+    Specificity = 3,
+    Order = 4
+}
+type ResolutionCause = {
+    type: "LowerOrigin";
+    winnerOrigin: Origin;
+    loserOrigin: Origin;
+} | {
+    type: "LowerLayer";
+    winnerLayer: string;
+    loserLayer: string;
+} | {
+    type: "LowerImportance";
+} | {
+    type: "LowerSpecificity";
+    delta: number;
+} | {
+    type: "EarlierOrder";
+    delta: number;
+} | {
+    type: "InactiveCondition";
+    condition: string;
+};
+interface ResolutionReason {
+    causes: readonly ResolutionCause[];
+    finalDecision: string;
+}
+interface SelectorIR {
+    id: SelectorId;
+    normalized: string;
+    specificity: number;
+    parts: readonly string[];
+}
+interface VariantChainIR {
+    id: VariantChainId;
+    chain: readonly VariantChainId[];
+    conditionGraphId: number | null;
+}
+interface ConditionIR {
+    id: ConditionId;
+    conditionType: string;
+    expression: string;
+}
+interface RuleIR {
+    id: RuleId;
+    selector: SelectorId;
+    variantChain: VariantChainId;
+    property: PropertyId;
+    value: ValueId;
+    origin: Origin;
+    importance: Importance;
+    layer: LayerId | null;
+    layerOrder: number;
+    specificity: number;
+    condition: ConditionId | null;
+    conditionResult: ConditionResult;
+    insertionOrder: number;
+    fingerprint: string;
+    source: SourceLocation;
+}
+interface PropertyBucketIR {
+    property: PropertyId;
+    rules: readonly RuleId[];
+}
+interface CascadeResolutionIR {
+    id: CascadeResolutionId;
+    property: PropertyId;
+    winner: RuleId;
+    losers: readonly RuleId[];
+    reason: ResolutionReason;
+    stage: CascadeStage;
+}
+interface StyleGraphIR {
+    ruleConflicts: Map<RuleId, readonly RuleId[]>;
+}
+interface FinalComputedStyleIR {
+    className: string;
+    resolvedProperties: Map<PropertyId, CascadeResolutionId>;
+}
+interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+declare function createFingerprint(parts: string[]): string;
+declare function compareCascadeOrder(a: RuleIR, b: RuleIR): number;
+declare function createResolutionReason(causes: ResolutionCause[], finalDecision: string): ResolutionReason;
+
+interface ClassBundleInfo {
+    className: string;
+    usageCount: number;
+    usedInFiles: SourceLocation[];
+    bundleSize: number;
+    componentsAffected: number;
+    variantChain: string[];
+    isDeadCode: boolean;
+    dependencies: string[];
+}
+interface BundleAnalysisResult {
+    className: string;
+    totalUsage: number;
+    files: SourceLocation[];
+    bundleSizeBytes: number;
+    variantChains: string[];
+    isDeadCode: boolean;
+    dependencies: string[];
+}
+declare class BundleAnalyzer {
+    private classUsages;
+    private classCounts;
+    analyzeClass(className: string, scanResult: ScanWorkspaceResult, css: string): BundleAnalysisResult;
+    analyzeAll(scanResult: ScanWorkspaceResult, css: string): Map<string, BundleAnalysisResult>;
+    calculateBundleContribution(className: string, css: string): number;
+    detectDeadCode(scanResult: ScanWorkspaceResult, css: string): string[];
+    private countClassUsage;
+    private getFilesUsingClass;
+    private extractVariantChains;
+    private extractDependencies;
+    private checkIsDeadCode;
+    private extractClassesFromCss;
+}
+
+interface ImpactReport {
+    className: string;
+    totalComponents: number;
+    directUsage: number;
+    indirectUsage: number;
+    bundleSizeBytes: number;
+    estimatedSavings: number;
+    riskLevel: "low" | "medium" | "high";
+    suggestions: string[];
+}
+interface ComponentImpact {
+    file: string;
+    line: number;
+    column: number;
+    usageType: "direct" | "variant" | "component";
+    variant?: string;
+}
+declare class ImpactTracker {
+    private bundleAnalyzer;
+    private criticalPatterns;
+    constructor();
+    calculateImpact(className: string, bundleAnalysis: BundleAnalysisResult, scanResult: any): ImpactReport;
+    findAffectedComponents(className: string, scanResult: any): ComponentImpact[];
+    calculateRisk(className: string, impact: ImpactReport): "low" | "medium" | "high";
+    generateSuggestions(className: string, impact: ImpactReport): string[];
+    private isCriticalClass;
+    private calculateSavings;
+    private createEmptyReport;
+}
+
+interface ClassUsage {
+    className: string;
+    source: SourceLocation;
+    specificity: number;
+    isOverride: boolean;
+    variants: string[];
+}
+interface ReverseLookupResult {
+    property: string;
+    value: string;
+    usedInClasses: ClassUsage[];
+}
+declare class ReverseLookup {
+    private parsedCache;
+    private parseCSS;
+    private findClosingBrace;
+    private calculateSpecificity;
+    fromCSS(cssProperty: string, cssValue: string, css: string): ReverseLookupResult[];
+    fromBundle(className: string, css: string): RuleIR[];
+    findDependents(className: string, css: string): string[];
+    findByProperty(property: string, css: string): ReverseLookupResult[];
+}
+
+/**
+ * Apply an incremental file-change event to an existing scan result.
+ *
+ * Tries Rust processFileChange first for per-file diffing;
+ * falls back to the JS implementation when native is unavailable.
+ */
+declare function applyIncrementalChange(previous: ScanWorkspaceResult, filePath: string, type: "change" | "unlink", scanner?: ScanWorkspaceOptions): ScanWorkspaceResult;
+
+interface WatcherOptions {
+    ignoreDirectories?: string[];
+    /**
+     * Delay before emitting change event to reduce noisy bursts.
+     */
+    debounceMs?: number;
+    onError?: (error: Error, directory: string) => void;
+}
+interface WatcherEvent {
+    type: "change" | "unlink";
+    filePath: string;
+}
+interface WorkspaceWatcher {
+    close(): void;
+}
+declare function watchWorkspace$1(rootDir: string, onEvent: (event: WatcherEvent) => void, options?: WatcherOptions): WorkspaceWatcher;
+
+/**
+ * tailwind-styled-v4 - Rust notify watch backend.
+ *
+ * Uses native notify when available and falls back to Node fs.watch.
+ * Keeps the same public API as watch.ts.
+ */
+interface NativeWatchOptions {
+    pollIntervalMs?: number;
+    extensions?: string[];
+    onError?: (error: Error) => void;
+}
+type WatchEventKind = "add" | "change" | "unlink" | "rename";
+interface WatchEvent {
+    kind: WatchEventKind;
+    path: string;
+}
+type WatchCallback = (events: WatchEvent[]) => void;
+interface WatchHandle {
+    stop(): void;
+    engine: string;
+}
+/**
+ * Start recursive watch.
+ * Callback is polled at `pollIntervalMs` (default 500ms) when events exist.
+ */
+declare function watchWorkspace(rootDir: string, callback: WatchCallback, options?: NativeWatchOptions): WatchHandle;
+
+interface EngineOptions {
+    root?: string;
+    scanner?: ScanWorkspaceOptions;
+    compileCss?: boolean;
+    tailwindConfigPath?: string;
+    plugins?: EnginePlugin[];
+    /** Enable analyzer integration - provides semantic report (unused classes, conflicts). Default: false */
+    analyze?: boolean;
+}
+interface EngineWatchOptions {
+    debounceMs?: number;
+    maxEventsPerFlush?: number;
+    largeFileThreshold?: number;
+}
+interface BuildResult {
+    scan: ScanWorkspaceResult;
+    mergedClassList: string;
+    css: string;
+    /** Analyzer semantic report - present when analyze: true in options */
+    analysis?: {
+        unusedClasses: unknown[];
+        classConflicts: Array<{
+            className: string;
+            files: string[];
+        }>;
+        classUsage: Record<string, number>;
+    };
+}
+type EngineBuildWatchEventType = "initial" | "change" | "unlink" | "full-rescan";
+type EngineWatchEvent = {
+    type: EngineBuildWatchEventType;
+    filePath?: string;
+    result: BuildResult;
+    metrics?: EngineMetricsSnapshot;
+} | {
+    type: "error";
+    filePath?: string;
+    error: string;
+    metrics?: EngineMetricsSnapshot;
+};
+interface TailwindStyledEngine {
+    scan(): Promise<ScanWorkspaceResult>;
+    build(): Promise<BuildResult>;
+    watch(onEvent: (event: EngineWatchEvent) => void, options?: EngineWatchOptions): Promise<{
+        close(): void;
+    }>;
+}
+declare function createEngine(options?: EngineOptions): Promise<TailwindStyledEngine>;
+
+export { type BuildResult, type BundleAnalysisResult, BundleAnalyzer, type CascadeResolutionIR, CascadeResolutionId, CascadeStage, type ClassBundleInfo, type ClassUsage, type ComponentImpact, type ConditionIR, ConditionId, ConditionResult, EngineMetricsCollector, type EngineMetricsSnapshot, type EngineOptions, type EnginePlugin, type EnginePluginContext, type EngineWatchContext, type EngineWatchEvent, type EngineWatchOptions, type FinalComputedStyleIR, type ImpactReport, ImpactTracker, Importance, LayerId, Origin, type PropertyBucketIR, PropertyId, type ResolutionCause, type ResolutionReason, ReverseLookup, type ReverseLookupResult, type RuleIR, RuleId, ScanWorkspaceOptions, ScanWorkspaceResult, type SelectorIR, SelectorId, type SourceLocation, type StyleGraphIR, type TailwindStyledEngine, ValueId, type VariantChainIR, VariantChainId, type WatchCallback, type WatchEvent, type WatchEventKind, type WatchHandle, type WorkspaceWatcher, applyIncrementalChange, compareCascadeOrder, createEngine, createFingerprint, createResolutionReason, runAfterBuild, runAfterScan, runAfterWatch, runBeforeBuild, runBeforeScan, runBeforeWatch, runOnError, runTransformClasses, watchWorkspace$1 as watchWorkspaceLegacy, watchWorkspace as watchWorkspaceNative };