@fragments-sdk/cli 0.10.0 → 0.11.1

package/src/viewer/intelligence/healthReport.ts

@@ -1,505 +0,0 @@
-/**
- * Health Report Generator
- * Aggregates usage, drift, and documentation data into a comprehensive health report
- */
-
-import type { FragmentDefinition } from '../../core/index.js';
-import type { FullScanResult, UsageScanResult } from './usageScanner.js';
-import type { DriftReport, DriftSummary, FullDriftResult } from './styleDrift.js';
-import { aggregateDriftReports, getWorstOffenders } from './styleDrift.js';
-
-export interface UsageStats {
-  totalComponents: number;
-  usedComponents: number;
-  unusedComponents: string[];
-  mostUsed: Array<{ component: string; count: number }>;
-  adoptionRate: number;
-}
-
-export interface StyleDriftStats {
-  componentsWithDrift: number;
-  totalDrifts: number;
-  averageCompliance: number;
-  byProperty: Record<string, number>;
-  bySeverity: {
-    high: number;
-    medium: number;
-    low: number;
-  };
-  worstOffenders: Array<{
-    component: string;
-    variant: string;
-    driftCount: number;
-    complianceScore: number;
-  }>;
-}
-
-export interface DocumentationStats {
-  documented: number;
-  undocumented: string[];
-  documentationRate: number;
-  missingDescriptions: string[];
-  missingUsage: string[];
-}
-
-export interface TokenStats {
-  complianceScore: number;
-  hardcodedValues: number;
-  tokenizedValues: number;
-  tokenizationRate: number;
-}
-
-export interface HealthReport {
-  generatedAt: string;
-  overallScore: number;
-  grades: {
-    usage: 'A' | 'B' | 'C' | 'D' | 'F';
-    drift: 'A' | 'B' | 'C' | 'D' | 'F';
-    documentation: 'A' | 'B' | 'C' | 'D' | 'F';
-    tokens: 'A' | 'B' | 'C' | 'D' | 'F';
-  };
-  usage: UsageStats;
-  styleDrift: StyleDriftStats;
-  documentation: DocumentationStats;
-  tokens: TokenStats;
-  recommendations: string[];
-}
-
-export interface HealthReportOptions {
-  /** Fragments to analyze */
-  fragments: Array<{ path: string; fragment: FragmentDefinition }>;
-  /** Usage scan results (optional) */
-  usageScan?: FullScanResult;
-  /** Drift reports (optional) */
-  driftReports?: DriftReport[];
-  /** Token compliance data (optional) */
-  tokenData?: {
-    complianceScore: number;
-    hardcodedCount: number;
-    tokenizedCount: number;
-  };
-}
-
-/**
- * Convert a percentage to a letter grade
- */
-function toGrade(score: number): 'A' | 'B' | 'C' | 'D' | 'F' {
-  if (score >= 90) return 'A';
-  if (score >= 80) return 'B';
-  if (score >= 70) return 'C';
-  if (score >= 60) return 'D';
-  return 'F';
-}
-
-/**
- * Calculate usage statistics from scan results
- */
-function calculateUsageStats(
-  fragments: Array<{ path: string; fragment: FragmentDefinition }>,
-  usageScan?: FullScanResult
-): UsageStats {
-  const allComponentNames = fragments.map((s) => s.fragment.meta.name);
-
-  if (!usageScan) {
-    return {
-      totalComponents: allComponentNames.length,
-      usedComponents: 0,
-      unusedComponents: allComponentNames,
-      mostUsed: [],
-      adoptionRate: 0,
-    };
-  }
-
-  const usageMap = new Map(usageScan.results.map((r) => [r.component, r.totalUsages]));
-
-  const usedComponents = allComponentNames.filter((name) => usageMap.has(name) && usageMap.get(name)! > 0);
-  const unusedComponents = allComponentNames.filter((name) => !usageMap.has(name) || usageMap.get(name) === 0);
-
-  const mostUsed = usageScan.results
-    .filter((r) => allComponentNames.includes(r.component))
-    .slice(0, 10)
-    .map((r) => ({ component: r.component, count: r.totalUsages }));
-
-  const adoptionRate = allComponentNames.length > 0
-    ? Math.round((usedComponents.length / allComponentNames.length) * 100)
-    : 0;
-
-  return {
-    totalComponents: allComponentNames.length,
-    usedComponents: usedComponents.length,
-    unusedComponents,
-    mostUsed,
-    adoptionRate,
-  };
-}
-
-/**
- * Calculate style drift statistics from drift reports
- */
-function calculateDriftStats(driftReports?: DriftReport[]): StyleDriftStats {
-  if (!driftReports || driftReports.length === 0) {
-    return {
-      componentsWithDrift: 0,
-      totalDrifts: 0,
-      averageCompliance: 100,
-      byProperty: {},
-      bySeverity: { high: 0, medium: 0, low: 0 },
-      worstOffenders: [],
-    };
-  }
-
-  const summary = aggregateDriftReports(driftReports);
-  const worstOffenders = getWorstOffenders(driftReports, 5);
-
-  return {
-    componentsWithDrift: summary.componentsWithDrift,
-    totalDrifts: summary.totalDrifts,
-    averageCompliance: summary.averageCompliance,
-    byProperty: summary.byProperty,
-    bySeverity: summary.bySeverity,
-    worstOffenders: worstOffenders.map((r) => ({
-      component: r.component,
-      variant: r.variant,
-      driftCount: r.drifts.length,
-      complianceScore: r.complianceScore,
-    })),
-  };
-}
-
-/**
- * Calculate documentation statistics from fragments
- */
-function calculateDocumentationStats(
-  fragments: Array<{ path: string; fragment: FragmentDefinition }>
-): DocumentationStats {
-  const documented: string[] = [];
-  const undocumented: string[] = [];
-  const missingDescriptions: string[] = [];
-  const missingUsage: string[] = [];
-
-  for (const { fragment } of fragments) {
-    const name = fragment.meta.name;
-
-    // Check for description
-    const hasDescription = fragment.meta.description && fragment.meta.description.trim().length > 10;
-
-    // Check for usage guidelines
-    const hasUsage = fragment.usage && (fragment.usage.when.length > 0 || fragment.usage.whenNot.length > 0);
-
-    // Check for variants
-    const hasVariants = fragment.variants && fragment.variants.length > 0;
-
-    if (hasDescription && hasVariants) {
-      documented.push(name);
-    } else {
-      undocumented.push(name);
-    }
-
-    if (!hasDescription) {
-      missingDescriptions.push(name);
-    }
-
-    if (!hasUsage) {
-      missingUsage.push(name);
-    }
-  }
-
-  const documentationRate = fragments.length > 0
-    ? Math.round((documented.length / fragments.length) * 100)
-    : 0;
-
-  return {
-    documented: documented.length,
-    undocumented,
-    documentationRate,
-    missingDescriptions,
-    missingUsage,
-  };
-}
-
-/**
- * Calculate token statistics
- */
-function calculateTokenStats(tokenData?: {
-  complianceScore: number;
-  hardcodedCount: number;
-  tokenizedCount: number;
-}): TokenStats {
-  if (!tokenData) {
-    return {
-      complianceScore: 100,
-      hardcodedValues: 0,
-      tokenizedValues: 0,
-      tokenizationRate: 100,
-    };
-  }
-
-  const total = tokenData.hardcodedCount + tokenData.tokenizedCount;
-  const tokenizationRate = total > 0
-    ? Math.round((tokenData.tokenizedCount / total) * 100)
-    : 100;
-
-  return {
-    complianceScore: tokenData.complianceScore,
-    hardcodedValues: tokenData.hardcodedCount,
-    tokenizedValues: tokenData.tokenizedCount,
-    tokenizationRate,
-  };
-}
-
-/**
- * Generate recommendations based on health data
- */
-function generateRecommendations(
-  usage: UsageStats,
-  drift: StyleDriftStats,
-  documentation: DocumentationStats,
-  tokens: TokenStats
-): string[] {
-  const recommendations: string[] = [];
-
-  // Usage recommendations
-  if (usage.unusedComponents.length > 0) {
-    if (usage.unusedComponents.length <= 3) {
-      recommendations.push(
-        `Consider removing or deprecating unused components: ${usage.unusedComponents.join(', ')}`
-      );
-    } else {
-      recommendations.push(
-        `${usage.unusedComponents.length} components are not being used. Run \`fragments scan\` for details.`
-      );
-    }
-  }
-
-  if (usage.adoptionRate < 50) {
-    recommendations.push(
-      'Low component adoption rate. Consider documenting migration paths from legacy components.'
-    );
-  }
-
-  // Drift recommendations
-  if (drift.bySeverity.high > 0) {
-    recommendations.push(
-      `${drift.bySeverity.high} high-severity style drift${drift.bySeverity.high > 1 ? 's' : ''} detected. These affect brand colors and typography.`
-    );
-  }
-
-  if (drift.averageCompliance < 80) {
-    recommendations.push(
-      `Style compliance is at ${drift.averageCompliance}%. Review the Styles panel for fix suggestions.`
-    );
-  }
-
-  // Documentation recommendations
-  if (documentation.missingDescriptions.length > 0) {
-    if (documentation.missingDescriptions.length <= 3) {
-      recommendations.push(
-        `Add descriptions to: ${documentation.missingDescriptions.join(', ')}`
-      );
-    } else {
-      recommendations.push(
-        `${documentation.missingDescriptions.length} components are missing descriptions.`
-      );
-    }
-  }
-
-  if (documentation.missingUsage.length > 0) {
-    recommendations.push(
-      `${documentation.missingUsage.length} components are missing usage guidelines (when/whenNot).`
-    );
-  }
-
-  // Token recommendations
-  if (tokens.hardcodedValues > 0) {
-    recommendations.push(
-      `${tokens.hardcodedValues} hardcoded value${tokens.hardcodedValues > 1 ? 's' : ''} should use design tokens.`
-    );
-  }
-
-  if (tokens.tokenizationRate < 80) {
-    recommendations.push(
-      'Token usage is low. Consider running token audits to identify migration opportunities.'
-    );
-  }
-
-  return recommendations;
-}
-
-/**
- * Calculate overall health score
- */
-function calculateOverallScore(
-  usage: UsageStats,
-  drift: StyleDriftStats,
-  documentation: DocumentationStats,
-  tokens: TokenStats
-): number {
-  // Weighted average of different metrics
-  const weights = {
-    adoption: 0.2,
-    compliance: 0.3,
-    documentation: 0.25,
-    tokens: 0.25,
-  };
-
-  const scores = {
-    adoption: usage.adoptionRate,
-    compliance: drift.averageCompliance,
-    documentation: documentation.documentationRate,
-    tokens: tokens.tokenizationRate,
-  };
-
-  const weightedSum =
-    scores.adoption * weights.adoption +
-    scores.compliance * weights.compliance +
-    scores.documentation * weights.documentation +
-    scores.tokens * weights.tokens;
-
-  return Math.round(weightedSum);
-}
-
-/**
- * Generate a comprehensive health report
- */
-export function generateHealthReport(options: HealthReportOptions): HealthReport {
-  const { fragments, usageScan, driftReports, tokenData } = options;
-
-  const usage = calculateUsageStats(fragments, usageScan);
-  const styleDrift = calculateDriftStats(driftReports);
-  const documentation = calculateDocumentationStats(fragments);
-  const tokens = calculateTokenStats(tokenData);
-
-  const overallScore = calculateOverallScore(usage, styleDrift, documentation, tokens);
-  const recommendations = generateRecommendations(usage, styleDrift, documentation, tokens);
-
-  return {
-    generatedAt: new Date().toISOString(),
-    overallScore,
-    grades: {
-      usage: toGrade(usage.adoptionRate),
-      drift: toGrade(styleDrift.averageCompliance),
-      documentation: toGrade(documentation.documentationRate),
-      tokens: toGrade(tokens.tokenizationRate),
-    },
-    usage,
-    styleDrift,
-    documentation,
-    tokens,
-    recommendations,
-  };
-}
-
-/**
- * Format health report as markdown
- */
-export function formatHealthReportAsMarkdown(report: HealthReport): string {
-  const lines: string[] = [
-    '# Design System Health Report',
-    '',
-    `Generated: ${new Date(report.generatedAt).toLocaleString()}`,
-    '',
-    `## Overall Score: ${report.overallScore}%`,
-    '',
-    '| Category | Grade | Score |',
-    '|----------|-------|-------|',
-    `| Usage | ${report.grades.usage} | ${report.usage.adoptionRate}% |`,
-    `| Style Compliance | ${report.grades.drift} | ${report.styleDrift.averageCompliance}% |`,
-    `| Documentation | ${report.grades.documentation} | ${report.documentation.documentationRate}% |`,
-    `| Token Usage | ${report.grades.tokens} | ${report.tokens.tokenizationRate}% |`,
-    '',
-  ];
-
-  // Usage section
-  lines.push('## Usage Statistics');
-  lines.push('');
-  lines.push(`- **Total Components**: ${report.usage.totalComponents}`);
-  lines.push(`- **Used Components**: ${report.usage.usedComponents}`);
-  lines.push(`- **Adoption Rate**: ${report.usage.adoptionRate}%`);
-
-  if (report.usage.mostUsed.length > 0) {
-    lines.push('');
-    lines.push('### Most Used Components');
-    lines.push('');
-    for (const item of report.usage.mostUsed.slice(0, 5)) {
-      lines.push(`- ${item.component}: ${item.count} usages`);
-    }
-  }
-
-  if (report.usage.unusedComponents.length > 0) {
-    lines.push('');
-    lines.push('### Unused Components');
-    lines.push('');
-    for (const name of report.usage.unusedComponents) {
-      lines.push(`- ${name}`);
-    }
-  }
-
-  // Style Drift section
-  lines.push('');
-  lines.push('## Style Drift Analysis');
-  lines.push('');
-  lines.push(`- **Components with Drift**: ${report.styleDrift.componentsWithDrift}`);
-  lines.push(`- **Total Drifts**: ${report.styleDrift.totalDrifts}`);
-  lines.push(`- **Average Compliance**: ${report.styleDrift.averageCompliance}%`);
-
-  if (Object.keys(report.styleDrift.bySeverity).some((k) => report.styleDrift.bySeverity[k as keyof typeof report.styleDrift.bySeverity] > 0)) {
-    lines.push('');
-    lines.push('### Drift by Severity');
-    lines.push('');
-    lines.push(`- High: ${report.styleDrift.bySeverity.high}`);
-    lines.push(`- Medium: ${report.styleDrift.bySeverity.medium}`);
-    lines.push(`- Low: ${report.styleDrift.bySeverity.low}`);
-  }
-
-  if (report.styleDrift.worstOffenders.length > 0) {
-    lines.push('');
-    lines.push('### Components Needing Attention');
-    lines.push('');
-    for (const item of report.styleDrift.worstOffenders) {
-      lines.push(`- **${item.component}** (${item.variant}): ${item.driftCount} drifts, ${item.complianceScore}% compliant`);
-    }
-  }
-
-  // Documentation section
-  lines.push('');
-  lines.push('## Documentation Coverage');
-  lines.push('');
-  lines.push(`- **Documented**: ${report.documentation.documented} components`);
-  lines.push(`- **Documentation Rate**: ${report.documentation.documentationRate}%`);
-
-  if (report.documentation.undocumented.length > 0) {
-    lines.push('');
-    lines.push('### Needs Documentation');
-    lines.push('');
-    for (const name of report.documentation.undocumented.slice(0, 10)) {
-      lines.push(`- ${name}`);
-    }
-    if (report.documentation.undocumented.length > 10) {
-      lines.push(`- ... and ${report.documentation.undocumented.length - 10} more`);
-    }
-  }
-
-  // Token section
-  lines.push('');
-  lines.push('## Design Token Usage');
-  lines.push('');
-  lines.push(`- **Token Compliance**: ${report.tokens.complianceScore}%`);
-  lines.push(`- **Tokenized Values**: ${report.tokens.tokenizedValues}`);
-  lines.push(`- **Hardcoded Values**: ${report.tokens.hardcodedValues}`);
-
-  // Recommendations
-  if (report.recommendations.length > 0) {
-    lines.push('');
-    lines.push('## Recommendations');
-    lines.push('');
-    for (const rec of report.recommendations) {
-      lines.push(`- ${rec}`);
-    }
-  }
-
-  lines.push('');
-  lines.push('---');
-  lines.push('*Generated by Fragments CLI*');
-
-  return lines.join('\n');
-}