@3fn/core 14.0.0 → 15.0.0

package/src/analytics/SemanticTokenUsageTracker.ts

@@ -1,193 +0,0 @@
-/**
- * Semantic Token Usage Tracker
- * 
- * Tracks usage patterns of semantic tokens to provide insights into semantic token
- * adoption and identify opportunities for creating new semantic tokens based on
- * common primitive token usage patterns.
- */
-
-import type { SemanticToken } from '../types/SemanticToken';
-import type { PrimitiveToken } from '../types/PrimitiveToken';
-import { SemanticCategory } from '../types/SemanticToken';
-
-/**
- * Individual semantic token usage record
- */
-export interface SemanticTokenUsage {
-  token: SemanticToken;
-  location: string;  // File path or component identifier
-  timestamp: Date;
-  context?: string;  // Optional usage context
-}
-
-/**
- * Usage statistics for semantic tokens
- */
-export interface SemanticTokenStats {
-  totalUsages: number;
-  uniqueTokensUsed: number;
-  byCategory: Map<SemanticCategory, number>;
-  byToken: Map<string, number>;
-  mostUsedTokens: Array<{ token: string; count: number }>;
-  leastUsedTokens: Array<{ token: string; count: number }>;
-}
-
-/**
- * Tracker for semantic token usage patterns
- */
-export class SemanticTokenUsageTracker {
-  private usages: SemanticTokenUsage[] = [];
-  private availableTokens: Set<string> = new Set();
-
-  /**
-   * Register available semantic tokens for tracking
-   */
-  registerAvailableToken(tokenName: string): void {
-    this.availableTokens.add(tokenName);
-  }
-
-  /**
-   * Record a usage of a semantic token
-   */
-  recordUsage(usage: SemanticTokenUsage): void {
-    this.usages.push(usage);
-    this.availableTokens.add(usage.token.name);
-  }
-
-  /**
-   * Get usage statistics for semantic tokens
-   */
-  getStatistics(): SemanticTokenStats {
-    const totalUsages = this.usages.length;
-    const uniqueTokensUsed = new Set(this.usages.map(u => u.token.name)).size;
-
-    // Group by category
-    const byCategory = new Map<SemanticCategory, number>();
-    for (const usage of this.usages) {
-      byCategory.set(usage.token.category, (byCategory.get(usage.token.category) || 0) + 1);
-    }
-
-    // Group by token
-    const byToken = new Map<string, number>();
-    for (const usage of this.usages) {
-      byToken.set(usage.token.name, (byToken.get(usage.token.name) || 0) + 1);
-    }
-
-    // Get most and least used tokens
-    const tokenCounts = Array.from(byToken.entries())
-      .map(([token, count]) => ({ token, count }))
-      .sort((a, b) => b.count - a.count);
-
-    const mostUsedTokens = tokenCounts.slice(0, 5);
-    const leastUsedTokens = tokenCounts.slice(-5).reverse();
-
-    return {
-      totalUsages,
-      uniqueTokensUsed,
-      byCategory,
-      byToken,
-      mostUsedTokens,
-      leastUsedTokens
-    };
-  }
-
-  /**
-   * Get feedback on semantic token usage patterns
-   */
-  getFeedback(): string[] {
-    const stats = this.getStatistics();
-    const feedback: string[] = [];
-
-    if (stats.totalUsages === 0) {
-      feedback.push('No semantic token usage recorded yet.');
-      return feedback;
-    }
-
-    // Adoption rate feedback
-    const adoptionRate = stats.uniqueTokensUsed / this.availableTokens.size;
-    if (adoptionRate < 0.5) {
-      feedback.push(
-        `Low semantic token adoption (${(adoptionRate * 100).toFixed(1)}% of available tokens used). ` +
-        `Consider promoting semantic token usage over primitive tokens.`
-      );
-    } else if (adoptionRate > 0.8) {
-      feedback.push(
-        `Excellent semantic token adoption (${(adoptionRate * 100).toFixed(1)}% of available tokens used).`
-      );
-    }
-
-    // Category distribution feedback
-    const categoryEntries = Array.from(stats.byCategory.entries());
-    if (categoryEntries.length > 0) {
-      const dominantCategory = categoryEntries.reduce((a, b) => a[1] > b[1] ? a : b);
-      const dominantPercentage = (dominantCategory[1] / stats.totalUsages) * 100;
-      
-      if (dominantPercentage > 60) {
-        feedback.push(
-          `${dominantCategory[0]} tokens dominate usage (${dominantPercentage.toFixed(1)}%). ` +
-          `Consider expanding semantic tokens in other categories.`
-        );
-      }
-    }
-
-    // Unused tokens feedback
-    const unusedTokens = this.availableTokens.size - stats.uniqueTokensUsed;
-    if (unusedTokens > 0) {
-      feedback.push(
-        `${unusedTokens} semantic token(s) are not being used. ` +
-        `Review whether these tokens are needed or if they should be promoted.`
-      );
-    }
-
-    // Most used tokens feedback
-    if (stats.mostUsedTokens.length > 0) {
-      const topToken = stats.mostUsedTokens[0];
-      const topTokenPercentage = (topToken.count / stats.totalUsages) * 100;
-      
-      if (topTokenPercentage > 30) {
-        feedback.push(
-          `Token "${topToken.token}" is heavily used (${topTokenPercentage.toFixed(1)}% of all usages). ` +
-          `This indicates a strong semantic pattern.`
-        );
-      }
-    }
-
-    return feedback;
-  }
-
-  /**
-   * Get usages for a specific semantic token
-   */
-  getUsagesForToken(tokenName: string): SemanticTokenUsage[] {
-    return this.usages.filter(u => u.token.name === tokenName);
-  }
-
-  /**
-   * Get usages by category
-   */
-  getUsagesByCategory(category: SemanticCategory): SemanticTokenUsage[] {
-    return this.usages.filter(u => u.token.category === category);
-  }
-
-  /**
-   * Get unused semantic tokens
-   */
-  getUnusedTokens(): string[] {
-    const usedTokens = new Set(this.usages.map(u => u.token.name));
-    return Array.from(this.availableTokens).filter(token => !usedTokens.has(token));
-  }
-
-  /**
-   * Clear all recorded usages (useful for testing or resetting)
-   */
-  clear(): void {
-    this.usages = [];
-  }
-
-  /**
-   * Clear available tokens registry
-   */
-  clearAvailableTokens(): void {
-    this.availableTokens.clear();
-  }
-}

package/src/analytics/StrategicFlexibilityTracker.ts

@@ -1,226 +0,0 @@
-/**
- * Strategic Flexibility Tracker
- * 
- * Monitors usage patterns of strategic flexibility tokens to ensure they remain
- * exceptional (≤20% of total token usage). Strategic flexibility tokens are
- * mathematically derived exceptions that break systematic progression within
- * their token families (e.g., space075 = 6).
- * 
- * The tracker validates that strategic flexibility tokens are used sparingly
- * and provides insights into appropriateness of individual usages.
- */
-
-import type { PrimitiveToken } from '../types/PrimitiveToken';
-
-/**
- * Usage context for strategic flexibility token usage
- */
-export enum UsageContext {
-  COMPONENT_INTERNAL = 'component-internal',  // Within component boundaries
-  LAYOUT_SPACING = 'layout-spacing',          // Between layout elements
-  TYPOGRAPHY_ADJUSTMENT = 'typography-adjustment', // Typography fine-tuning
-  ACCESSIBILITY_TARGET = 'accessibility-target',   // Accessibility requirements
-  VISUAL_BALANCE = 'visual-balance',          // Visual design balance
-  UNKNOWN = 'unknown'                         // Context not specified
-}
-
-/**
- * Appropriateness assessment for strategic flexibility usage (informational)
- */
-export enum UsageAppropriateness {
-  APPROPRIATE = 'appropriate',      // Correct usage of strategic flexibility
-  QUESTIONABLE = 'questionable',    // Potentially inappropriate usage
-  INAPPROPRIATE = 'inappropriate'   // Clear misuse of strategic flexibility
-}
-
-/**
- * Individual usage record for strategic flexibility token
- */
-export interface StrategicFlexibilityUsage {
-  token: PrimitiveToken;
-  context: UsageContext;
-  appropriateness: UsageAppropriateness;
-  location: string;  // File path or component identifier
-  timestamp: Date;
-  rationale?: string;  // Optional explanation for usage
-}
-
-/**
- * Usage statistics for strategic flexibility tokens
- */
-export interface StrategicFlexibilityStats {
-  totalUsages: number;
-  totalTokenUsages: number;         // Total usages across all tokens
-  usageRate: number;                // SF usages / total usages
-  meetsThreshold: boolean;          // Whether ≤20% threshold is met
-  appropriateUsages: number;        // Informational
-  questionableUsages: number;       // Informational
-  inappropriateUsages: number;      // Informational
-  appropriatenessRate: number;      // Informational
-  byContext: Map<UsageContext, number>;
-  byToken: Map<string, number>;
-}
-
-/**
- * Tracker for strategic flexibility token usage patterns
- */
-export class StrategicFlexibilityTracker {
-  private usages: StrategicFlexibilityUsage[] = [];
-  private readonly USAGE_RATE_THRESHOLD = 0.20;  // 20% threshold (SF should be ≤20% of total)
-
-  /**
-   * Record a usage of a strategic flexibility token
-   */
-  recordUsage(usage: StrategicFlexibilityUsage): void {
-    if (!usage.token.isStrategicFlexibility) {
-      throw new Error(`Token ${usage.token.name} is not a strategic flexibility token`);
-    }
-    this.usages.push(usage);
-  }
-
-  /**
-   * Get usage statistics for strategic flexibility tokens
-   * Requires total token usage count to calculate usage rate
-   */
-  getStatistics(totalTokenUsages: number): StrategicFlexibilityStats {
-    const totalUsages = this.usages.length;
-    const usageRate = totalTokenUsages > 0 ? totalUsages / totalTokenUsages : 0;
-    const meetsThreshold = usageRate <= this.USAGE_RATE_THRESHOLD;
-
-    // Appropriateness tracking (informational)
-    const appropriateUsages = this.usages.filter(
-      u => u.appropriateness === UsageAppropriateness.APPROPRIATE
-    ).length;
-    const questionableUsages = this.usages.filter(
-      u => u.appropriateness === UsageAppropriateness.QUESTIONABLE
-    ).length;
-    const inappropriateUsages = this.usages.filter(
-      u => u.appropriateness === UsageAppropriateness.INAPPROPRIATE
-    ).length;
-
-    const appropriatenessRate = totalUsages > 0 ? appropriateUsages / totalUsages : 1.0;
-
-    // Group by context
-    const byContext = new Map<UsageContext, number>();
-    for (const usage of this.usages) {
-      byContext.set(usage.context, (byContext.get(usage.context) || 0) + 1);
-    }
-
-    // Group by token
-    const byToken = new Map<string, number>();
-    for (const usage of this.usages) {
-      byToken.set(usage.token.name, (byToken.get(usage.token.name) || 0) + 1);
-    }
-
-    return {
-      totalUsages,
-      totalTokenUsages,
-      usageRate,
-      meetsThreshold,
-      appropriateUsages,
-      questionableUsages,
-      inappropriateUsages,
-      appropriatenessRate,
-      byContext,
-      byToken
-    };
-  }
-
-  /**
-   * Get feedback on strategic flexibility usage patterns
-   * Requires total token usage count to provide accurate feedback
-   */
-  getFeedback(totalTokenUsages: number): string[] {
-    const stats = this.getStatistics(totalTokenUsages);
-    const feedback: string[] = [];
-
-    if (stats.totalUsages === 0) {
-      feedback.push('No strategic flexibility token usage recorded yet.');
-      return feedback;
-    }
-
-    // Primary threshold check (PASS/FAIL)
-    if (!stats.meetsThreshold) {
-      feedback.push(
-        `⚠️ FAIL: Strategic flexibility usage exceeds 20% threshold (${(stats.usageRate * 100).toFixed(1)}%). ` +
-        `Strategic flexibility tokens should be exceptional, not common. ` +
-        `Review usage patterns and consider using regular tokens or creating semantic alternatives.`
-      );
-    } else {
-      feedback.push(
-        `✅ PASS: Strategic flexibility usage is within threshold (${(stats.usageRate * 100).toFixed(1)}% ≤ 20%). ` +
-        `Strategic flexibility tokens are being used as exceptions.`
-      );
-    }
-
-    // Informational appropriateness feedback
-    if (stats.inappropriateUsages > 0) {
-      feedback.push(
-        `Found ${stats.inappropriateUsages} inappropriate usage(s) of strategic flexibility tokens. ` +
-        `Review these usages and consider alternatives.`
-      );
-    }
-
-    if (stats.questionableUsages > stats.appropriateUsages) {
-      feedback.push(
-        `Questionable usages (${stats.questionableUsages}) exceed appropriate usages (${stats.appropriateUsages}). ` +
-        `Review usage patterns to ensure strategic flexibility is used correctly.`
-      );
-    }
-
-    // Context-specific feedback
-    const layoutUsages = stats.byContext.get(UsageContext.LAYOUT_SPACING) || 0;
-    if (layoutUsages > stats.totalUsages * 0.3) {
-      feedback.push(
-        `High usage of strategic flexibility in layout spacing (${layoutUsages} usages). ` +
-        `Consider creating semantic layout tokens for common spacing patterns.`
-      );
-    }
-
-    // Positive reinforcement
-    if (stats.meetsThreshold && stats.inappropriateUsages === 0 && stats.appropriatenessRate > 0.8) {
-      feedback.push(
-        `Strategic flexibility usage is excellent (${(stats.appropriatenessRate * 100).toFixed(1)}% appropriate). ` +
-        `Continue using strategic flexibility for exceptional cases only.`
-      );
-    }
-
-    return feedback;
-  }
-
-  /**
-   * Get usages filtered by appropriateness level
-   */
-  getUsagesByAppropriateness(level: UsageAppropriateness): StrategicFlexibilityUsage[] {
-    return this.usages.filter(u => u.appropriateness === level);
-  }
-
-  /**
-   * Get usages for a specific token
-   */
-  getUsagesForToken(tokenName: string): StrategicFlexibilityUsage[] {
-    return this.usages.filter(u => u.token.name === tokenName);
-  }
-
-  /**
-   * Clear all recorded usages (useful for testing or resetting)
-   */
-  clear(): void {
-    this.usages = [];
-  }
-
-  /**
-   * Get the usage rate threshold (20%)
-   */
-  getThreshold(): number {
-    return this.USAGE_RATE_THRESHOLD;
-  }
-
-  /**
-   * Check if usage rate meets threshold (≤20%)
-   */
-  meetsThreshold(totalTokenUsages: number): boolean {
-    const stats = this.getStatistics(totalTokenUsages);
-    return stats.meetsThreshold;
-  }
-}

package/src/analytics/TokenUsageTracker.ts

@@ -1,177 +0,0 @@
-/**
- * Token Usage Tracker
- * 
- * Tracks all token usages across the system to provide baseline metrics
- * for calculating strategic flexibility usage rates and overall token adoption.
- */
-
-import type { PrimitiveToken } from '../types/PrimitiveToken';
-import type { SemanticToken } from '../types/SemanticToken';
-import { TokenCategory } from '../types/PrimitiveToken';
-import { SemanticCategory } from '../types/SemanticToken';
-
-/**
- * Token type for usage tracking
- */
-export enum TokenType {
-    PRIMITIVE = 'primitive',
-    SEMANTIC = 'semantic'
-}
-
-/**
- * Individual token usage record
- */
-export interface TokenUsage {
-    tokenName: string;
-    tokenType: TokenType;
-    isStrategicFlexibility: boolean;
-    category: TokenCategory | SemanticCategory;
-    location: string;  // File path or component identifier
-    timestamp: Date;
-}
-
-/**
- * Overall token usage statistics
- */
-export interface TokenUsageStats {
-    totalUsages: number;
-    primitiveUsages: number;
-    semanticUsages: number;
-    strategicFlexibilityUsages: number;
-    strategicFlexibilityRate: number;  // SF usages / total usages
-    byCategory: Map<TokenCategory | SemanticCategory, number>;
-    byToken: Map<string, number>;
-    mostUsedTokens: Array<{ token: string; count: number }>;
-}
-
-/**
- * Tracker for all token usages across the system
- */
-export class TokenUsageTracker {
-    private usages: TokenUsage[] = [];
-
-    /**
-     * Record a primitive token usage
-     */
-    recordPrimitiveUsage(
-        token: PrimitiveToken,
-        location: string,
-        timestamp: Date = new Date()
-    ): void {
-        this.usages.push({
-            tokenName: token.name,
-            tokenType: TokenType.PRIMITIVE,
-            isStrategicFlexibility: token.isStrategicFlexibility,
-            category: token.category,
-            location,
-            timestamp
-        });
-    }
-
-    /**
-     * Record a semantic token usage
-     */
-    recordSemanticUsage(
-        token: SemanticToken,
-        location: string,
-        timestamp: Date = new Date()
-    ): void {
-        // Get the first primitive token to check strategic flexibility
-        const firstPrimitiveToken = token.primitiveTokens ? Object.values(token.primitiveTokens)[0] : undefined;
-        
-        this.usages.push({
-            tokenName: token.name,
-            tokenType: TokenType.SEMANTIC,
-            isStrategicFlexibility: firstPrimitiveToken?.isStrategicFlexibility || false,
-            category: token.category,
-            location,
-            timestamp
-        });
-    }
-
-    /**
-     * Get overall token usage statistics
-     */
-    getStatistics(): TokenUsageStats {
-        const totalUsages = this.usages.length;
-        const primitiveUsages = this.usages.filter(u => u.tokenType === TokenType.PRIMITIVE).length;
-        const semanticUsages = this.usages.filter(u => u.tokenType === TokenType.SEMANTIC).length;
-        const strategicFlexibilityUsages = this.usages.filter(u => u.isStrategicFlexibility).length;
-
-        const strategicFlexibilityRate = totalUsages > 0
-            ? strategicFlexibilityUsages / totalUsages
-            : 0;
-
-        // Group by category
-        const byCategory = new Map<TokenCategory | SemanticCategory, number>();
-        for (const usage of this.usages) {
-            byCategory.set(usage.category, (byCategory.get(usage.category) || 0) + 1);
-        }
-
-        // Group by token
-        const byToken = new Map<string, number>();
-        for (const usage of this.usages) {
-            byToken.set(usage.tokenName, (byToken.get(usage.tokenName) || 0) + 1);
-        }
-
-        // Get most used tokens
-        const tokenCounts = Array.from(byToken.entries())
-            .map(([token, count]) => ({ token, count }))
-            .sort((a, b) => b.count - a.count);
-
-        const mostUsedTokens = tokenCounts.slice(0, 10);
-
-        return {
-            totalUsages,
-            primitiveUsages,
-            semanticUsages,
-            strategicFlexibilityUsages,
-            strategicFlexibilityRate,
-            byCategory,
-            byToken,
-            mostUsedTokens
-        };
-    }
-
-    /**
-     * Get all usages for a specific token
-     */
-    getUsagesForToken(tokenName: string): TokenUsage[] {
-        return this.usages.filter(u => u.tokenName === tokenName);
-    }
-
-    /**
-     * Get all strategic flexibility usages
-     */
-    getStrategicFlexibilityUsages(): TokenUsage[] {
-        return this.usages.filter(u => u.isStrategicFlexibility);
-    }
-
-    /**
-     * Get usages by token type
-     */
-    getUsagesByType(type: TokenType): TokenUsage[] {
-        return this.usages.filter(u => u.tokenType === type);
-    }
-
-    /**
-     * Get usages by category
-     */
-    getUsagesByCategory(category: TokenCategory | SemanticCategory): TokenUsage[] {
-        return this.usages.filter(u => u.category === category);
-    }
-
-    /**
-     * Clear all recorded usages (useful for testing or resetting)
-     */
-    clear(): void {
-        this.usages = [];
-    }
-
-    /**
-     * Get total usage count
-     */
-    getTotalUsages(): number {
-        return this.usages.length;
-    }
-}