@fragments-sdk/cli 0.2.2

package/src/service/index.ts

@@ -0,0 +1,249 @@
+/**
+ * @fragments/service
+ *
+ * Screenshot capture and verification service for Segments.
+ * Provides browser pool management, screenshot capture, and visual diff capabilities.
+ */
+
+// Browser pool
+export {
+  BrowserPool,
+  BrowserPoolError,
+  getSharedPool,
+  shutdownSharedPool,
+  type BrowserPoolConfig,
+} from "./browser-pool.js";
+
+// Capture engine
+export {
+  CaptureEngine,
+  CaptureError,
+  createCaptureEngine,
+  type CaptureOptions,
+} from "./capture.js";
+
+// Storage manager
+export {
+  StorageManager,
+  StorageError,
+  createStorageManager,
+  type StorageConfig,
+} from "./storage.js";
+
+// Diff engine
+export {
+  DiffEngine,
+  DiffError,
+  createDiffEngine,
+  type DiffOptions,
+} from "./diff.js";
+
+// Figma client
+export {
+  FigmaClient,
+  FigmaError,
+  createFigmaClient,
+  type FigmaClientConfig,
+  type FigmaImageResult,
+  type FigmaUrlParts,
+  type FigmaComponent,
+  type FigmaFileComponents,
+  type FigmaVariant,
+  type FigmaComponentSetWithVariants,
+  // Design property types (Phase 3)
+  type FigmaColor,
+  type FigmaFill,
+  type FigmaStroke,
+  type FigmaEffect,
+  type FigmaTypography,
+  type FigmaDesignProperties,
+  type CSSDesignProperties,
+  type StyleDiffResult,
+} from "./figma.js";
+
+// Utilities
+export {
+  ServiceError,
+  Timer,
+  computeHash,
+  createDeferred,
+  sleep,
+  bufferToBase64Url,
+  base64UrlToBuffer,
+  sanitizeFilename,
+  buildScreenshotPath,
+  formatMs,
+  retry,
+} from "./utils.js";
+
+// Analytics engine
+export {
+  analyzeDesignSystem,
+  getGrade,
+  getScoreColor,
+  type DesignSystemAnalytics,
+  type ComponentInventory,
+  type ComponentSummary,
+  type CoverageAnalytics,
+  type QualityAnalytics,
+  type DistributionAnalytics,
+  type Recommendation,
+} from "./analytics.js";
+
+// HTML Report generator
+export { generateHtmlReport } from "./report.js";
+
+// Token parser and registry
+export {
+  parseTokenFile,
+  parseTokenFiles,
+  hexToRgb,
+  rgbToHex,
+  parseRgb,
+  normalizeColor,
+} from "./token-parser.js";
+
+export {
+  TokenRegistryManager,
+  getSharedTokenRegistry,
+  initializeSharedRegistry,
+  clearSharedRegistry,
+  createTokenRegistry,
+} from "./token-registry.js";
+
+// Token fix suggestions
+export {
+  generateTokenFixes,
+  generateAIFixContext,
+  type TokenFixContext,
+} from "./token-fixes.js";
+
+// Patch generator
+export {
+  generateTokenPatches,
+  generateCSSInJSPatches,
+  type Patch,
+  type PatchGenerationResult,
+  type PatchGenerationOptions,
+} from "./patch-generator.js";
+
+// AST utilities for style extraction and patching
+export {
+  extractStyleLocations,
+  applyPatch,
+  applyPatches,
+  findStyleOccurrences,
+  type StyleLocation,
+  type PatchResult,
+} from "./ast-utils.js";
+
+// Metrics storage for compliance trends
+export {
+  MetricsStore,
+  createMetricsStore,
+  type ComplianceSnapshot,
+  type MetricsTrend,
+  type MetricsQueryOptions,
+} from "./metrics-store.js";
+
+// Enhancement module - codebase analysis for AI documentation
+export {
+  // Scanner
+  scanFileForImports,
+  scanFileForUsages,
+  scanFile,
+  scanCodebase,
+  incrementalScan,
+  getScanStats,
+  hasCachedAnalysis,
+  // Aggregator
+  aggregateComponentUsages,
+  aggregateAllUsages,
+  findCommonPropCombinations,
+  summarizePatternsForPrompt,
+  inferRelations,
+  inferAllRelations,
+  type ComponentRelation,
+  // Cache
+  loadCache,
+  saveCache,
+  createEmptyCache,
+  computeFileHash,
+  detectFileChanges,
+  getCacheStats,
+  // Doc Extractor
+  extractComponentDocs,
+  extractDocsFromSource,
+  findComponentSource,
+  extractAllComponentDocs,
+  // Storybook Parser
+  parseStoryFile,
+  parseStorySource,
+  findStoryFiles,
+  parseAllStories,
+  mergeStorybookIntoDoc,
+  type StoryExample,
+  type StorybookMeta,
+  type ArgType,
+  type ParsedStoryFile,
+  // AI Context Generator
+  generateComponentContext,
+  generateAIContextPackage,
+  generatePromptContext,
+  generateEnhancementSuggestions,
+  generateSystemPrompt,
+  generateUserPrompt,
+  isBoilerplate,
+  filterBoilerplate,
+  type ComponentContext,
+  type AIContextPackage,
+  type EnhancedProp,
+  // Props Extractor
+  extractPropsFromFile,
+  extractPropsFromSource,
+  extractPropsForComponent,
+  extractAllComponentProps,
+  convertToSegmentProps,
+  type ExtractedProp,
+  type PropsExtractionResult,
+  type PropsExtractionOptions,
+  // Variant Renderer
+  renderVariants,
+  renderAllComponentVariants,
+  checkStorybookRunning,
+  getStorybookStoryIds,
+  shutdownSharedPool as shutdownVariantPool,
+  type RenderedVariant,
+  type VariantRenderResult,
+  type VariantRenderOptions,
+  // Types
+  type ComponentUsage,
+  type UsageProps,
+  type ComponentImport,
+  type UsagePattern,
+  type FileContext,
+  type ComponentAnalysis,
+  type UsageAnalysis,
+  type AnalysisCache,
+  type ScanProgress,
+  type ScanOptions,
+  type FileChanges,
+  type ExtractedDocs,
+  type ComponentEnhancement,
+  type EnhancementResult,
+} from "./enhance/index.js";
+
+// Re-export types and constants from core for convenience
+export { BRAND, DEFAULTS } from "../core/index.js";
+export type {
+  Screenshot,
+  ScreenshotMetadata,
+  DiffResult,
+  BoundingBox,
+  BaselineInfo,
+  Manifest,
+  VerifyRequest,
+  VerifyResult,
+  Viewport,
+  Theme,
+} from "../core/index.js";

package/src/service/metrics-store.ts

@@ -0,0 +1,333 @@
+/**
+ * Metrics Store
+ *
+ * Persists compliance metrics over time for trend analysis.
+ * Stores snapshots in .segments/metrics/ directory.
+ */
+
+import { readFile, writeFile, mkdir, readdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { BRAND } from "../core/index.js";
+
+/**
+ * A single compliance snapshot for a component
+ */
+export interface ComplianceSnapshot {
+  /** ISO timestamp when snapshot was taken */
+  timestamp: string;
+
+  /** Component name */
+  component: string;
+
+  /** Compliance percentage (0-100) */
+  compliance: number;
+
+  /** Number of violations */
+  violations: number;
+
+  /** Detailed violation info */
+  violationDetails?: Array<{
+    property: string;
+    issue: string;
+    severity: "error" | "warning";
+  }>;
+
+  /** Git commit hash if available */
+  commitHash?: string;
+
+  /** Branch name if available */
+  branch?: string;
+}
+
+/**
+ * Aggregated metrics for trend analysis
+ */
+export interface MetricsTrend {
+  /** Component name or 'system' for aggregate */
+  component: string;
+
+  /** Time period */
+  period: "day" | "week" | "month";
+
+  /** Data points */
+  dataPoints: Array<{
+    date: string;
+    compliance: number;
+    violations: number;
+  }>;
+
+  /** Trend direction */
+  trend: "improving" | "stable" | "declining";
+
+  /** Average compliance over period */
+  averageCompliance: number;
+}
+
+/**
+ * Options for metrics queries
+ */
+export interface MetricsQueryOptions {
+  /** Number of days to look back (default: 30) */
+  days?: number;
+
+  /** Filter by component */
+  component?: string;
+
+  /** Group by period */
+  groupBy?: "day" | "week" | "month";
+}
+
+/**
+ * Metrics Store for persisting compliance data
+ */
+export class MetricsStore {
+  private readonly projectRoot: string;
+  private readonly metricsDir: string;
+
+  constructor(projectRoot: string) {
+    this.projectRoot = projectRoot;
+    this.metricsDir = join(projectRoot, BRAND.dataDir, "metrics");
+  }
+
+  /**
+   * Save a compliance snapshot
+   */
+  async saveSnapshot(snapshot: ComplianceSnapshot): Promise<string> {
+    // Ensure metrics directory exists
+    await mkdir(this.metricsDir, { recursive: true });
+
+    // Create filename with timestamp and component
+    const date = new Date(snapshot.timestamp);
+    const dateStr = date.toISOString().split("T")[0]; // YYYY-MM-DD
+    const filename = `${dateStr}_${snapshot.component}.json`;
+    const filepath = join(this.metricsDir, filename);
+
+    // Append to existing file for the day or create new
+    let snapshots: ComplianceSnapshot[] = [];
+    try {
+      const existing = await readFile(filepath, "utf-8");
+      snapshots = JSON.parse(existing);
+    } catch {
+      // File doesn't exist, start fresh
+    }
+
+    snapshots.push(snapshot);
+
+    await writeFile(filepath, JSON.stringify(snapshots, null, 2));
+
+    return filepath;
+  }
+
+  /**
+   * Get compliance history for a component
+   */
+  async getHistory(
+    component: string,
+    options: MetricsQueryOptions = {}
+  ): Promise<ComplianceSnapshot[]> {
+    const { days = 30 } = options;
+
+    const snapshots: ComplianceSnapshot[] = [];
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - days);
+
+    try {
+      const files = await readdir(this.metricsDir);
+
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+
+        // Check if file is within date range
+        const dateStr = file.split("_")[0];
+        const fileDate = new Date(dateStr);
+        if (fileDate < cutoffDate) continue;
+
+        // Check if file matches component
+        if (component !== "all" && !file.includes(`_${component}.json`)) {
+          continue;
+        }
+
+        try {
+          const content = await readFile(join(this.metricsDir, file), "utf-8");
+          const fileSnapshots: ComplianceSnapshot[] = JSON.parse(content);
+
+          // Filter to matching component
+          const matching = component === "all"
+            ? fileSnapshots
+            : fileSnapshots.filter((s) => s.component === component);
+
+          snapshots.push(...matching);
+        } catch {
+          // Skip malformed files
+        }
+      }
+    } catch {
+      // Metrics directory doesn't exist
+      return [];
+    }
+
+    // Sort by timestamp
+    snapshots.sort(
+      (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+    );
+
+    return snapshots;
+  }
+
+  /**
+   * Get system-wide compliance history
+   */
+  async getSystemHistory(options: MetricsQueryOptions = {}): Promise<ComplianceSnapshot[]> {
+    return this.getHistory("all", options);
+  }
+
+  /**
+   * Calculate compliance trend for a component
+   */
+  async getTrend(
+    component: string,
+    options: MetricsQueryOptions = {}
+  ): Promise<MetricsTrend> {
+    const { days = 30, groupBy = "day" } = options;
+
+    const snapshots = await this.getHistory(component, { days });
+
+    // Group by period
+    const groups = new Map<string, ComplianceSnapshot[]>();
+
+    for (const snapshot of snapshots) {
+      const date = new Date(snapshot.timestamp);
+      let key: string;
+
+      switch (groupBy) {
+        case "week":
+          // Get ISO week
+          const weekStart = new Date(date);
+          weekStart.setDate(date.getDate() - date.getDay());
+          key = weekStart.toISOString().split("T")[0];
+          break;
+        case "month":
+          key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
+          break;
+        case "day":
+        default:
+          key = date.toISOString().split("T")[0];
+          break;
+      }
+
+      const existing = groups.get(key) || [];
+      existing.push(snapshot);
+      groups.set(key, existing);
+    }
+
+    // Calculate aggregates for each period
+    const dataPoints: MetricsTrend["dataPoints"] = [];
+
+    for (const [date, periodSnapshots] of groups) {
+      const avgCompliance =
+        periodSnapshots.reduce((sum, s) => sum + s.compliance, 0) /
+        periodSnapshots.length;
+      const totalViolations = periodSnapshots.reduce(
+        (sum, s) => sum + s.violations,
+        0
+      );
+
+      dataPoints.push({
+        date,
+        compliance: Math.round(avgCompliance * 100) / 100,
+        violations: totalViolations,
+      });
+    }
+
+    // Sort by date
+    dataPoints.sort((a, b) => a.date.localeCompare(b.date));
+
+    // Determine trend
+    let trend: MetricsTrend["trend"] = "stable";
+    if (dataPoints.length >= 2) {
+      const first = dataPoints.slice(0, Math.ceil(dataPoints.length / 2));
+      const second = dataPoints.slice(Math.ceil(dataPoints.length / 2));
+
+      const firstAvg =
+        first.reduce((sum, d) => sum + d.compliance, 0) / first.length;
+      const secondAvg =
+        second.reduce((sum, d) => sum + d.compliance, 0) / second.length;
+
+      const diff = secondAvg - firstAvg;
+      if (diff > 2) trend = "improving";
+      else if (diff < -2) trend = "declining";
+    }
+
+    const averageCompliance =
+      dataPoints.length > 0
+        ? dataPoints.reduce((sum, d) => sum + d.compliance, 0) / dataPoints.length
+        : 0;
+
+    return {
+      component,
+      period: groupBy,
+      dataPoints,
+      trend,
+      averageCompliance: Math.round(averageCompliance * 100) / 100,
+    };
+  }
+
+  /**
+   * Generate an ASCII sparkline for terminal display
+   */
+  generateSparkline(dataPoints: Array<{ compliance: number }>): string {
+    if (dataPoints.length === 0) return "─";
+
+    const chars = " ▁▂▃▄▅▆▇█";
+    const values = dataPoints.map((d) => d.compliance);
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min || 1;
+
+    return values
+      .map((v) => {
+        const normalized = (v - min) / range;
+        const index = Math.round(normalized * (chars.length - 1));
+        return chars[index];
+      })
+      .join("");
+  }
+
+  /**
+   * Delete old metrics beyond retention period
+   */
+  async cleanup(retentionDays: number = 90): Promise<number> {
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - retentionDays);
+
+    let deleted = 0;
+
+    try {
+      const files = await readdir(this.metricsDir);
+      const { unlink } = await import("node:fs/promises");
+
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+
+        const dateStr = file.split("_")[0];
+        const fileDate = new Date(dateStr);
+
+        if (fileDate < cutoffDate) {
+          await unlink(join(this.metricsDir, file));
+          deleted++;
+        }
+      }
+    } catch {
+      // Metrics directory doesn't exist
+    }
+
+    return deleted;
+  }
+}
+
+/**
+ * Create a metrics store instance
+ */
+export function createMetricsStore(projectRoot: string): MetricsStore {
+  return new MetricsStore(projectRoot);
+}