@fragments-sdk/cli 0.2.2

package/src/service/analytics.ts

@@ -0,0 +1,659 @@
+/**
+ * Analytics engine for design system insights.
+ *
+ * Analyzes compiled segments to provide:
+ * - Component inventory stats
+ * - Documentation coverage
+ * - Usage pattern insights
+ * - Quality scores
+ */
+
+import type { CompiledSegmentsFile, CompiledSegment } from "../core/index.js";
+
+/**
+ * Overall design system analytics
+ */
+export interface DesignSystemAnalytics {
+  /** When the analysis was performed */
+  analyzedAt: Date;
+
+  /** Summary metrics */
+  summary: {
+    totalComponents: number;
+    totalVariants: number;
+    totalProps: number;
+    categories: string[];
+    overallScore: number; // 0-100
+  };
+
+  /** Component inventory */
+  inventory: ComponentInventory;
+
+  /** Documentation coverage */
+  coverage: CoverageAnalytics;
+
+  /** Quality insights */
+  quality: QualityAnalytics;
+
+  /** Distribution charts data */
+  distribution: DistributionAnalytics;
+
+  /** Recommendations for improvement */
+  recommendations: Recommendation[];
+}
+
+/**
+ * Component inventory breakdown
+ */
+export interface ComponentInventory {
+  /** Components by category */
+  byCategory: Record<string, ComponentSummary[]>;
+
+  /** Components by status */
+  byStatus: Record<string, ComponentSummary[]>;
+
+  /** Components sorted by variant count (most to least) */
+  byVariantCount: ComponentSummary[];
+
+  /** Components sorted by prop count */
+  byPropCount: ComponentSummary[];
+}
+
+/**
+ * Summary info for a single component
+ */
+export interface ComponentSummary {
+  name: string;
+  category: string;
+  status: string;
+  variantCount: number;
+  propCount: number;
+  hasUsageWhen: boolean;
+  hasUsageWhenNot: boolean;
+  hasGuidelines: boolean;
+  hasRelations: boolean;
+  documentationScore: number; // 0-100
+}
+
+/**
+ * Documentation coverage analytics
+ */
+export interface CoverageAnalytics {
+  /** Overall coverage percentage */
+  overall: number;
+
+  /** Coverage by field */
+  fields: {
+    description: { covered: number; total: number; percentage: number };
+    usageWhen: { covered: number; total: number; percentage: number };
+    usageWhenNot: { covered: number; total: number; percentage: number };
+    guidelines: { covered: number; total: number; percentage: number };
+    accessibility: { covered: number; total: number; percentage: number };
+    relations: { covered: number; total: number; percentage: number };
+    propDescriptions: { covered: number; total: number; percentage: number };
+    propConstraints: { covered: number; total: number; percentage: number };
+  };
+
+  /** Components with incomplete documentation */
+  incomplete: Array<{
+    component: string;
+    missing: string[];
+  }>;
+}
+
+/**
+ * Quality insights
+ */
+export interface QualityAnalytics {
+  /** Components with no whenNot guidance (anti-patterns) */
+  missingWhenNot: string[];
+
+  /** Components with no relations defined */
+  isolated: string[];
+
+  /** Deprecated components still in use */
+  deprecated: string[];
+
+  /** Components with very few variants (might need more examples) */
+  fewVariants: string[];
+
+  /** Props without descriptions */
+  undocumentedProps: Array<{ component: string; prop: string }>;
+
+  /** Props without constraints (might need validation rules) */
+  unconstrainedProps: Array<{ component: string; prop: string }>;
+}
+
+/**
+ * Distribution data for charts
+ */
+export interface DistributionAnalytics {
+  /** Variants per component distribution */
+  variantsPerComponent: Array<{ name: string; count: number }>;
+
+  /** Props per component distribution */
+  propsPerComponent: Array<{ name: string; count: number }>;
+
+  /** Components per category */
+  componentsPerCategory: Array<{ category: string; count: number }>;
+
+  /** Status distribution */
+  statusDistribution: Array<{ status: string; count: number }>;
+
+  /** Tag frequency */
+  tagFrequency: Array<{ tag: string; count: number }>;
+}
+
+/**
+ * Actionable recommendation
+ */
+export interface Recommendation {
+  priority: "high" | "medium" | "low";
+  category: "documentation" | "coverage" | "quality" | "organization";
+  title: string;
+  description: string;
+  components?: string[];
+  impact: string;
+}
+
+/**
+ * Analyze a compiled segments file and produce analytics
+ */
+export function analyzeDesignSystem(
+  data: CompiledSegmentsFile
+): DesignSystemAnalytics {
+  const segments = Object.values(data.segments);
+  const analyzedAt = new Date();
+
+  // Build component summaries
+  const summaries = segments.map((s) => buildComponentSummary(s));
+
+  // Calculate coverage
+  const coverage = calculateCoverage(segments, summaries);
+
+  // Calculate quality insights
+  const quality = calculateQuality(segments, summaries);
+
+  // Build distribution data
+  const distribution = buildDistribution(segments, summaries);
+
+  // Build inventory
+  const inventory = buildInventory(summaries);
+
+  // Generate recommendations
+  const recommendations = generateRecommendations(coverage, quality, summaries);
+
+  // Calculate overall score
+  const overallScore = calculateOverallScore(coverage, quality, summaries);
+
+  // Collect all categories
+  const categories = [...new Set(segments.map((s) => s.meta.category))].sort();
+
+  return {
+    analyzedAt,
+    summary: {
+      totalComponents: segments.length,
+      totalVariants: segments.reduce((sum, s) => sum + s.variants.length, 0),
+      totalProps: segments.reduce(
+        (sum, s) => sum + Object.keys(s.props ?? {}).length,
+        0
+      ),
+      categories,
+      overallScore,
+    },
+    inventory,
+    coverage,
+    quality,
+    distribution,
+    recommendations,
+  };
+}
+
+/**
+ * Build summary for a single component
+ */
+function buildComponentSummary(segment: CompiledSegment): ComponentSummary {
+  const propCount = Object.keys(segment.props ?? {}).length;
+  const hasUsageWhen = (segment.usage?.when?.length ?? 0) > 0;
+  const hasUsageWhenNot = (segment.usage?.whenNot?.length ?? 0) > 0;
+  const hasGuidelines = (segment.usage?.guidelines?.length ?? 0) > 0;
+  const hasRelations = (segment.relations?.length ?? 0) > 0;
+
+  // Calculate documentation score
+  let docScore = 0;
+  let docTotal = 0;
+
+  // Description (20 points)
+  docTotal += 20;
+  if (segment.meta.description && segment.meta.description.length > 20) {
+    docScore += 20;
+  }
+
+  // Usage when (20 points)
+  docTotal += 20;
+  if (hasUsageWhen) docScore += 20;
+
+  // Usage whenNot (20 points) - key differentiator
+  docTotal += 20;
+  if (hasUsageWhenNot) docScore += 20;
+
+  // Guidelines (15 points)
+  docTotal += 15;
+  if (hasGuidelines) docScore += 15;
+
+  // Relations (10 points)
+  docTotal += 10;
+  if (hasRelations) docScore += 10;
+
+  // Props documented (15 points)
+  docTotal += 15;
+  if (propCount > 0) {
+    const documentedProps = Object.values(segment.props ?? {}).filter(
+      (p) => p.description && p.description.length > 5
+    ).length;
+    docScore += Math.round((documentedProps / propCount) * 15);
+  } else {
+    docScore += 15; // No props = full score for this section
+  }
+
+  return {
+    name: segment.meta.name,
+    category: segment.meta.category,
+    status: segment.meta.status ?? "stable",
+    variantCount: segment.variants.length,
+    propCount,
+    hasUsageWhen,
+    hasUsageWhenNot,
+    hasGuidelines,
+    hasRelations,
+    documentationScore: Math.round((docScore / docTotal) * 100),
+  };
+}
+
+/**
+ * Calculate coverage analytics
+ */
+function calculateCoverage(
+  segments: CompiledSegment[],
+  summaries: ComponentSummary[]
+): CoverageAnalytics {
+  const total = segments.length;
+
+  const fields = {
+    description: {
+      covered: segments.filter(
+        (s) => s.meta.description && s.meta.description.length > 10
+      ).length,
+      total,
+      percentage: 0,
+    },
+    usageWhen: {
+      covered: summaries.filter((s) => s.hasUsageWhen).length,
+      total,
+      percentage: 0,
+    },
+    usageWhenNot: {
+      covered: summaries.filter((s) => s.hasUsageWhenNot).length,
+      total,
+      percentage: 0,
+    },
+    guidelines: {
+      covered: summaries.filter((s) => s.hasGuidelines).length,
+      total,
+      percentage: 0,
+    },
+    accessibility: {
+      covered: segments.filter((s) => (s.usage?.accessibility?.length ?? 0) > 0)
+        .length,
+      total,
+      percentage: 0,
+    },
+    relations: {
+      covered: summaries.filter((s) => s.hasRelations).length,
+      total,
+      percentage: 0,
+    },
+    propDescriptions: {
+      covered: 0,
+      total: 0,
+      percentage: 0,
+    },
+    propConstraints: {
+      covered: 0,
+      total: 0,
+      percentage: 0,
+    },
+  };
+
+  // Calculate prop coverage
+  for (const segment of segments) {
+    const props = Object.values(segment.props ?? {});
+    fields.propDescriptions.total += props.length;
+    fields.propConstraints.total += props.length;
+
+    fields.propDescriptions.covered += props.filter(
+      (p) => p.description && p.description.length > 5
+    ).length;
+    fields.propConstraints.covered += props.filter(
+      (p) => (p.constraints?.length ?? 0) > 0
+    ).length;
+  }
+
+  // Calculate percentages
+  for (const field of Object.values(fields)) {
+    field.percentage =
+      field.total > 0 ? Math.round((field.covered / field.total) * 100) : 100;
+  }
+
+  // Find incomplete components
+  const incomplete: CoverageAnalytics["incomplete"] = [];
+  for (const summary of summaries) {
+    const missing: string[] = [];
+    if (!summary.hasUsageWhen) missing.push("usage.when");
+    if (!summary.hasUsageWhenNot) missing.push("usage.whenNot");
+    if (!summary.hasGuidelines) missing.push("usage.guidelines");
+    if (!summary.hasRelations) missing.push("relations");
+
+    if (missing.length > 0) {
+      incomplete.push({ component: summary.name, missing });
+    }
+  }
+
+  // Overall coverage (weighted average)
+  const overall = Math.round(
+    fields.description.percentage * 0.1 +
+      fields.usageWhen.percentage * 0.2 +
+      fields.usageWhenNot.percentage * 0.25 +
+      fields.guidelines.percentage * 0.15 +
+      fields.relations.percentage * 0.1 +
+      fields.propDescriptions.percentage * 0.15 +
+      fields.propConstraints.percentage * 0.05
+  );
+
+  return { overall, fields, incomplete };
+}
+
+/**
+ * Calculate quality analytics
+ */
+function calculateQuality(
+  segments: CompiledSegment[],
+  summaries: ComponentSummary[]
+): QualityAnalytics {
+  const missingWhenNot = summaries
+    .filter((s) => !s.hasUsageWhenNot)
+    .map((s) => s.name);
+
+  const isolated = summaries
+    .filter((s) => !s.hasRelations)
+    .map((s) => s.name);
+
+  const deprecated = summaries
+    .filter((s) => s.status === "deprecated")
+    .map((s) => s.name);
+
+  const fewVariants = summaries
+    .filter((s) => s.variantCount < 2)
+    .map((s) => s.name);
+
+  const undocumentedProps: QualityAnalytics["undocumentedProps"] = [];
+  const unconstrainedProps: QualityAnalytics["unconstrainedProps"] = [];
+
+  for (const segment of segments) {
+    for (const [propName, prop] of Object.entries(segment.props ?? {})) {
+      if (!prop.description || prop.description.length < 5) {
+        undocumentedProps.push({ component: segment.meta.name, prop: propName });
+      }
+      if (
+        (prop.constraints?.length ?? 0) === 0 &&
+        prop.type !== "boolean" &&
+        prop.type !== "function"
+      ) {
+        unconstrainedProps.push({
+          component: segment.meta.name,
+          prop: propName,
+        });
+      }
+    }
+  }
+
+  return {
+    missingWhenNot,
+    isolated,
+    deprecated,
+    fewVariants,
+    undocumentedProps,
+    unconstrainedProps,
+  };
+}
+
+/**
+ * Build distribution data for charts
+ */
+function buildDistribution(
+  segments: CompiledSegment[],
+  summaries: ComponentSummary[]
+): DistributionAnalytics {
+  // Variants per component
+  const variantsPerComponent = summaries
+    .map((s) => ({ name: s.name, count: s.variantCount }))
+    .sort((a, b) => b.count - a.count);
+
+  // Props per component
+  const propsPerComponent = summaries
+    .map((s) => ({ name: s.name, count: s.propCount }))
+    .sort((a, b) => b.count - a.count);
+
+  // Components per category
+  const categoryMap = new Map<string, number>();
+  for (const s of summaries) {
+    categoryMap.set(s.category, (categoryMap.get(s.category) ?? 0) + 1);
+  }
+  const componentsPerCategory = Array.from(categoryMap.entries())
+    .map(([category, count]) => ({ category, count }))
+    .sort((a, b) => b.count - a.count);
+
+  // Status distribution
+  const statusMap = new Map<string, number>();
+  for (const s of summaries) {
+    statusMap.set(s.status, (statusMap.get(s.status) ?? 0) + 1);
+  }
+  const statusDistribution = Array.from(statusMap.entries())
+    .map(([status, count]) => ({ status, count }))
+    .sort((a, b) => b.count - a.count);
+
+  // Tag frequency
+  const tagMap = new Map<string, number>();
+  for (const segment of segments) {
+    for (const tag of segment.meta.tags ?? []) {
+      tagMap.set(tag, (tagMap.get(tag) ?? 0) + 1);
+    }
+  }
+  const tagFrequency = Array.from(tagMap.entries())
+    .map(([tag, count]) => ({ tag, count }))
+    .sort((a, b) => b.count - a.count);
+
+  return {
+    variantsPerComponent,
+    propsPerComponent,
+    componentsPerCategory,
+    statusDistribution,
+    tagFrequency,
+  };
+}
+
+/**
+ * Build inventory breakdown
+ */
+function buildInventory(summaries: ComponentSummary[]): ComponentInventory {
+  const byCategory: Record<string, ComponentSummary[]> = {};
+  const byStatus: Record<string, ComponentSummary[]> = {};
+
+  for (const summary of summaries) {
+    if (!byCategory[summary.category]) {
+      byCategory[summary.category] = [];
+    }
+    byCategory[summary.category].push(summary);
+
+    if (!byStatus[summary.status]) {
+      byStatus[summary.status] = [];
+    }
+    byStatus[summary.status].push(summary);
+  }
+
+  // Sort within each group by name
+  for (const list of Object.values(byCategory)) {
+    list.sort((a, b) => a.name.localeCompare(b.name));
+  }
+  for (const list of Object.values(byStatus)) {
+    list.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  return {
+    byCategory,
+    byStatus,
+    byVariantCount: [...summaries].sort((a, b) => b.variantCount - a.variantCount),
+    byPropCount: [...summaries].sort((a, b) => b.propCount - a.propCount),
+  };
+}
+
+/**
+ * Generate actionable recommendations
+ */
+function generateRecommendations(
+  coverage: CoverageAnalytics,
+  quality: QualityAnalytics,
+  summaries: ComponentSummary[]
+): Recommendation[] {
+  const recommendations: Recommendation[] = [];
+
+  // High priority: Missing whenNot guidance
+  if (quality.missingWhenNot.length > 0) {
+    recommendations.push({
+      priority: "high",
+      category: "documentation",
+      title: 'Add "When NOT to use" guidance',
+      description: `${quality.missingWhenNot.length} component(s) lack guidance on when NOT to use them. This is critical for AI agents to make correct component choices.`,
+      components: quality.missingWhenNot.slice(0, 5),
+      impact: "Prevents AI from using components incorrectly",
+    });
+  }
+
+  // High priority: Low overall coverage
+  if (coverage.overall < 70) {
+    recommendations.push({
+      priority: "high",
+      category: "coverage",
+      title: "Improve documentation coverage",
+      description: `Overall documentation coverage is ${coverage.overall}%. Aim for at least 80% for effective AI assistance.`,
+      impact: "Better AI understanding and suggestions",
+    });
+  }
+
+  // Medium priority: Isolated components
+  if (quality.isolated.length > summaries.length * 0.3) {
+    recommendations.push({
+      priority: "medium",
+      category: "organization",
+      title: "Add component relationships",
+      description: `${quality.isolated.length} component(s) have no relationships defined. Adding relations helps AI understand component ecosystems.`,
+      components: quality.isolated.slice(0, 5),
+      impact: "Better alternative suggestions",
+    });
+  }
+
+  // Medium priority: Few variants
+  if (quality.fewVariants.length > 0) {
+    recommendations.push({
+      priority: "medium",
+      category: "coverage",
+      title: "Add more variant examples",
+      description: `${quality.fewVariants.length} component(s) have fewer than 2 variants. More examples help demonstrate component flexibility.`,
+      components: quality.fewVariants.slice(0, 5),
+      impact: "Better visual documentation",
+    });
+  }
+
+  // Low priority: Undocumented props
+  if (quality.undocumentedProps.length > 0) {
+    recommendations.push({
+      priority: "low",
+      category: "documentation",
+      title: "Document prop descriptions",
+      description: `${quality.undocumentedProps.length} prop(s) lack descriptions. Clear descriptions help AI generate correct code.`,
+      impact: "Clearer API documentation",
+    });
+  }
+
+  // Low priority: No constraints
+  if (quality.unconstrainedProps.length > 5) {
+    recommendations.push({
+      priority: "low",
+      category: "quality",
+      title: "Add prop constraints",
+      description: `${quality.unconstrainedProps.length} prop(s) could benefit from constraint documentation (validation rules, best practices).`,
+      impact: "Better AI adherence to design rules",
+    });
+  }
+
+  return recommendations;
+}
+
+/**
+ * Calculate overall design system quality score
+ */
+function calculateOverallScore(
+  coverage: CoverageAnalytics,
+  quality: QualityAnalytics,
+  summaries: ComponentSummary[]
+): number {
+  // Base: coverage score (50%)
+  let score = coverage.overall * 0.5;
+
+  // Component documentation scores (30%)
+  const avgDocScore =
+    summaries.reduce((sum, s) => sum + s.documentationScore, 0) /
+    Math.max(summaries.length, 1);
+  score += avgDocScore * 0.3;
+
+  // Quality penalties (20%)
+  let qualityScore = 100;
+
+  // Penalize missing whenNot (most important)
+  const missingWhenNotRatio =
+    quality.missingWhenNot.length / Math.max(summaries.length, 1);
+  qualityScore -= missingWhenNotRatio * 40;
+
+  // Penalize isolated components
+  const isolatedRatio = quality.isolated.length / Math.max(summaries.length, 1);
+  qualityScore -= isolatedRatio * 20;
+
+  // Penalize few variants
+  const fewVariantsRatio =
+    quality.fewVariants.length / Math.max(summaries.length, 1);
+  qualityScore -= fewVariantsRatio * 10;
+
+  score += Math.max(qualityScore, 0) * 0.2;
+
+  return Math.round(Math.max(Math.min(score, 100), 0));
+}
+
+/**
+ * Get a letter grade from a numeric score
+ */
+export function getGrade(score: number): string {
+  if (score >= 90) return "A";
+  if (score >= 80) return "B";
+  if (score >= 70) return "C";
+  if (score >= 60) return "D";
+  return "F";
+}
+
+/**
+ * Get a color for a score (for HTML reports)
+ */
+export function getScoreColor(score: number): string {
+  if (score >= 80) return "#22c55e"; // green
+  if (score >= 60) return "#eab308"; // yellow
+  return "#ef4444"; // red
+}