chaincss 2.2.0 → 2.3.0

package/dist/compiler/source-optimizer.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Source-Aware Optimization Engine
+ *
+ * Unifies all analysis modules into an enterprise-grade optimization report.
+ * Tracks where every style originates and detects:
+ *   - Duplicate styles across files
+ *   - Dead/unreachable rules
+ *   - Specificity wars
+ *   - Conflicting animations
+ *   - Redundant media queries
+ *   - Unused variants and recipes
+ */
+import type { IRRule, IRPass } from './style-ir.js';
+export interface DuplicateGroup {
+    /** The shared signature */
+    signature: string;
+    /** All occurrences with source locations */
+    occurrences: Array<{
+        selector: string;
+        file?: string;
+        line?: number;
+        component?: string;
+    }>;
+    /** How many times it appears */
+    count: number;
+    /** Suggested extraction */
+    suggestion: string;
+    /** Estimated savings in bytes */
+    savingsBytes: number;
+}
+export interface DeadRule {
+    ruleId: string;
+    selector: string;
+    file?: string;
+    line?: number;
+    reason: string;
+    bytesWasted: number;
+}
+export interface SpecificityConflict {
+    higher: {
+        selector: string;
+        specificity: number;
+        file?: string;
+        line?: number;
+    };
+    lower: {
+        selector: string;
+        specificity: number;
+        file?: string;
+        line?: number;
+    };
+    property?: string;
+    severity: 'warning' | 'info';
+}
+export interface AnimationConflict {
+    name: string;
+    locations: Array<{
+        file?: string;
+        line?: number;
+        selector: string;
+    }>;
+    count: number;
+}
+export interface MediaQueryRedundancy {
+    query: string;
+    count: number;
+    files: string[];
+    suggestion: string;
+    savingsBytes: number;
+}
+export interface OptimizationReport {
+    duplicates: DuplicateGroup[];
+    deadRules: DeadRule[];
+    specificityConflicts: SpecificityConflict[];
+    animationConflicts: AnimationConflict[];
+    mediaQueryRedundancies: MediaQueryRedundancy[];
+    summary: {
+        totalIssues: number;
+        duplicatesCount: number;
+        deadCount: number;
+        specificityCount: number;
+        animationCount: number;
+        mediaQueryCount: number;
+        totalSavingsBytes: number;
+        totalSavingsKB: string;
+    };
+    formattedReport: string;
+}
+declare function findDuplicates(rules: IRRule[]): DuplicateGroup[];
+declare function findDeadRules(rules: IRRule[]): DeadRule[];
+declare function findSpecificityConflicts(rules: IRRule[]): SpecificityConflict[];
+declare function findAnimationConflicts(rules: IRRule[]): AnimationConflict[];
+declare function findMediaQueryRedundancies(rules: IRRule[]): MediaQueryRedundancy[];
+declare function formatReport(report: OptimizationReport): string;
+declare function generateOptimizationReport(rules: IRRule[]): OptimizationReport;
+export declare const sourceOptimizerPass: IRPass;
+export declare function optimizeSource(rules: IRRule[]): OptimizationReport;
+export declare const sourceOptimizer: {
+    optimize: typeof optimizeSource;
+    findDuplicates: typeof findDuplicates;
+    findDeadRules: typeof findDeadRules;
+    findSpecificityConflicts: typeof findSpecificityConflicts;
+    findAnimationConflicts: typeof findAnimationConflicts;
+    findMediaQueryRedundancies: typeof findMediaQueryRedundancies;
+    report: typeof generateOptimizationReport;
+    format: typeof formatReport;
+    pass: IRPass;
+};
+export default sourceOptimizer;

package/dist/compiler/style-ir.d.ts

@@ -0,0 +1,183 @@
+/**
+ * ChainCSS Intermediate Representation (IR)
+ *
+ * The single source of truth that all compiler passes read from and write to.
+ * Replaces direct object mutation with a typed, traceable AST.
+ *
+ * Architecture:
+ *   StyleDefinition → parseIR() → StyleIR → [passes] → generateCSS()
+ */
+import type { StyleDefinition } from '../core/types.js';
+/** Unique identifier for every IR node */
+export type IRNodeId = string;
+/** Source location for debugging and source maps */
+export interface SourceLocation {
+    file?: string;
+    line?: number;
+    column?: number;
+    component?: string;
+}
+/** A single CSS declaration (property: value) */
+export interface IRDeclaration {
+    id: IRNodeId;
+    property: string;
+    value: string | number;
+    important?: boolean;
+    source?: SourceLocation;
+    /** Transform history — who modified this and why */
+    history: IRTransformRecord[];
+    /** Metadata from passes */
+    meta: Record<string, any>;
+}
+/** A CSS rule (selector + declarations + nested rules) */
+export interface IRRule {
+    id: IRNodeId;
+    selector: string;
+    declarations: IRDeclaration[];
+    pseudoClasses: IRPseudoClass[];
+    atRules: IRAtRule[];
+    nestedRules: IRRule[];
+    /** Conditional if() expressions */
+    conditions: IRCondition[];
+    /** Dead code flag — set by optimizer passes */
+    isDead: boolean;
+    /** Specificity — set by graph pass */
+    specificity: number;
+    /** Content hash for deduplication */
+    hash: string;
+    source: SourceLocation;
+    history: IRTransformRecord[];
+    meta: Record<string, any>;
+}
+/** Pseudo-class block (hover, focus, etc.) */
+export interface IRPseudoClass {
+    id: IRNodeId;
+    name: string;
+    declarations: IRDeclaration[];
+    source: SourceLocation;
+    history: IRTransformRecord[];
+}
+/** At-rule block (media, keyframes, supports, etc.) */
+export interface IRAtRule {
+    id: IRNodeId;
+    type: 'media' | 'keyframes' | 'font-face' | 'supports' | 'container' | 'layer';
+    query?: string;
+    name?: string;
+    declarations: IRDeclaration[];
+    nestedRules: IRRule[];
+    source: SourceLocation;
+    history: IRTransformRecord[];
+}
+/** CSS if() conditional */
+export interface IRCondition {
+    id: IRNodeId;
+    property: string;
+    variable: string;
+    conditions: Record<string, string | number>;
+    defaultValue: string | number;
+    source: SourceLocation;
+}
+/** Transform record — who touched this node and why */
+export interface IRTransformRecord {
+    pass: string;
+    action: string;
+    timestamp: number;
+    previous?: any;
+    reason?: string;
+}
+/** The full IR tree */
+export interface StyleIR {
+    id: string;
+    rules: IRRule[];
+    diagnostics: IRDiagnostic[];
+    meta: {
+        version: string;
+        createdAt: number;
+        sourceFiles: string[];
+        passCount: number;
+        passes: string[];
+    };
+}
+/** Diagnostic attached to an IR node */
+export interface IRDiagnostic {
+    id: IRNodeId;
+    nodeId: IRNodeId;
+    severity: 'error' | 'warning' | 'info' | 'hint';
+    message: string;
+    suggestion?: string;
+    pass: string;
+}
+export declare function resetIdCounter(): void;
+export declare function createDeclaration(property: string, value: string | number, source?: SourceLocation, meta?: Record<string, any>): IRDeclaration;
+export declare function createRule(selector: string, source?: SourceLocation): IRRule;
+export declare function createIR(sourceFiles?: string[]): StyleIR;
+/**
+ * Parse a StyleDefinition (or Record<string, any>) into the IR.
+ * This is the bridge — existing code produces StyleDefinition,
+ * this converts it to typed IR for all downstream passes.
+ */
+export declare function parseIR(styles: Record<string, StyleDefinition> | Record<string, any>, sourceFile?: string): StyleIR;
+/**
+ * Generate a CSS string from the IR.
+ * This replaces the ad-hoc CSS generation scattered across modules.
+ */
+export declare function generateCSS(ir: StyleIR, options?: {
+    minify?: boolean;
+}): string;
+/** Count all nodes in the IR */
+export declare function countNodes(ir: StyleIR): {
+    rules: number;
+    declarations: number;
+    pseudoClasses: number;
+    atRules: number;
+    conditions: number;
+};
+/** Find a rule by selector */
+export declare function findRule(ir: StyleIR, selector: string): IRRule | undefined;
+/** Clone an IR (deep copy) */
+export declare function cloneIR(ir: StyleIR): StyleIR;
+/** Debug: print IR summary */
+export declare function debugIR(ir: StyleIR): string;
+export type IRPass = (ir: StyleIR) => StyleIR;
+/**
+ * Apply a transform pass to the IR.
+ * Records the pass in metadata for debugging.
+ */
+export declare function applyPass(ir: StyleIR, pass: IRPass, passName: string): StyleIR;
+/**
+ * Apply multiple passes in sequence.
+ */
+export declare function applyPasses(ir: StyleIR, passes: Array<{
+    name: string;
+    pass: IRPass;
+}>): StyleIR;
+/**
+ * Full pipeline: StyleDefinition → IR → passes → CSS.
+ * Drop-in replacement for existing compile() calls.
+ */
+export declare function compileViaIR(styles: Record<string, StyleDefinition>, passes?: Array<{
+    name: string;
+    pass: IRPass;
+}>, options?: {
+    minify?: boolean;
+    sourceFile?: string;
+}): {
+    css: string;
+    ir: StyleIR;
+};
+export declare const styleIR: {
+    createIR: typeof createIR;
+    parseIR: typeof parseIR;
+    generateCSS: typeof generateCSS;
+    createRule: typeof createRule;
+    createDeclaration: typeof createDeclaration;
+    countNodes: typeof countNodes;
+    findRule: typeof findRule;
+    cloneIR: typeof cloneIR;
+    debugIR: typeof debugIR;
+    applyPass: typeof applyPass;
+    applyPasses: typeof applyPasses;
+    compileViaIR: typeof compileViaIR;
+    resetIdCounter: typeof resetIdCounter;
+};
+export default styleIR;

package/dist/index.d.ts

@@ -44,6 +44,25 @@ export { orchestrator, contrastRatio, checkContrast, auditContrast, createContex
 export type { ContrastResult, ContrastReport, ContextualToken, TokenContext } from './compiler/design-orchestrator.js';
 export { scrollTimeline, compileScrollAnimation, compileScrollAnimations, createScrollAnimation, getScrollPresets, SCROLL_PRESETS, } from './compiler/scroll-timeline.js';
 export type { ScrollTimelineConfig, ScrollAnimation, ScrollTimelineResult, KeyframeStep } from './compiler/scroll-timeline.js';
+export { styleIR, createIR, parseIR, generateCSS, createRule, createDeclaration, applyPass, applyPasses, compileViaIR, countNodes, debugIR, resetIdCounter, } from './compiler/style-ir.js';
+export type { StyleIR, IRRule, IRDeclaration, IRPseudoClass, IRAtRule, IRCondition, IRTransformRecord, IRDiagnostic, IRNodeId, SourceLocation, IRPass, } from './compiler/style-ir.js';
+export { PassManager, runDefaultPipeline, DEFAULT_PIPELINE, intentRecoveryPass, unitResolutionPass, validationPass, specificitySortPass, deadEliminationPass, atomicExtractionPass, mediaQueryPackingPass, cssIfTranspilePass, cssCompressionPass, diagnosticsExportPass, } from './compiler/pass-manager.js';
+export type { PassName, PassPriority, PassDefinition, PassResult, PipelineResult } from './compiler/pass-manager.js';
+export { constraintSolver, resolveConstraint, resolveStickyUntil, resolveContainerQuery, parseConstraint, constraintSolverPass, } from './compiler/constraint-solver.js';
+export type { Constraint, ConstraintOperator, ConstraintTarget, ResolvedConstraint } from './compiler/constraint-solver.js';
+export { layoutIntelligence, recognizeLayout, suggestMacro, getLayoutPatterns, layoutIntelligencePass, } from './compiler/layout-intelligence.js';
+export type { LayoutPattern, PatternMatch, PatternReport } from './compiler/layout-intelligence.js';
+export { responsiveInference, analyzeResponsive, generateResponsiveReport, autoFixIssue, autoFixAll, responsiveInferencePass, } from './compiler/responsive-inference.js';
+export type { ResponsiveIssue, ResponsiveReport } from './compiler/responsive-inference.js';
+export { patternLearner, learnPatterns, getExtractionCandidates, patternLearningPass, } from './compiler/pattern-learner.js';
+export type { StyleFingerprint, PatternCluster, LearningReport } from './compiler/pattern-learner.js';
+export { sourceOptimizer, optimizeSource, sourceOptimizerPass, } from './compiler/source-optimizer.js';
+export type { OptimizationReport, DuplicateGroup, DeadRule, SpecificityConflict, AnimationConflict, MediaQueryRedundancy } from './compiler/source-optimizer.js';
+export { semanticTokens, resolveSemantic, getSemanticIntents, getSemanticDescription, semanticTokensPass, } from './compiler/semantic-tokens.js';
+export type { SurfaceIntent, TextIntent, ElevationIntent, StateIntent, SpacingIntent, SemanticMapping, ThemeContext } from './compiler/semantic-tokens.js';
+export { accessibilityEngine, auditAccessibility, checkRule, accessibilityPass, } from './compiler/accessibility-engine.js';
+export type { AccessibilityIssue, AccessibilityReport } from './compiler/accessibility-engine.js';
+export { intentAPI, resolveIntent, getAvailableIntents, getIntentsByCategory, getIntentDescription, intentAPIPass, } from './compiler/intent-api.js';
 import { chain } from './compiler/Chain.js';
 export default chain;
 export type { Properties as CSSProperties } from 'csstype';