@fragments-sdk/cli 0.2.2

package/src/viewer/intelligence/healthReport.ts

@@ -0,0 +1,505 @@
+/**
+ * Health Report Generator
+ * Aggregates usage, drift, and documentation data into a comprehensive health report
+ */
+
+import type { SegmentDefinition } 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 {
+  /** Segments to analyze */
+  segments: Array<{ path: string; segment: SegmentDefinition }>;
+  /** 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(
+  segments: Array<{ path: string; segment: SegmentDefinition }>,
+  usageScan?: FullScanResult
+): UsageStats {
+  const allComponentNames = segments.map((s) => s.segment.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 segments
+ */
+function calculateDocumentationStats(
+  segments: Array<{ path: string; segment: SegmentDefinition }>
+): DocumentationStats {
+  const documented: string[] = [];
+  const undocumented: string[] = [];
+  const missingDescriptions: string[] = [];
+  const missingUsage: string[] = [];
+
+  for (const { segment } of segments) {
+    const name = segment.meta.name;
+
+    // Check for description
+    const hasDescription = segment.meta.description && segment.meta.description.trim().length > 10;
+
+    // Check for usage guidelines
+    const hasUsage = segment.usage && (segment.usage.when.length > 0 || segment.usage.whenNot.length > 0);
+
+    // Check for variants
+    const hasVariants = segment.variants && segment.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 = segments.length > 0
+    ? Math.round((documented.length / segments.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 { segments, usageScan, driftReports, tokenData } = options;
+
+  const usage = calculateUsageStats(segments, usageScan);
+  const styleDrift = calculateDriftStats(driftReports);
+  const documentation = calculateDocumentationStats(segments);
+  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');
+}