@fragments-sdk/cli 0.2.2

package/src/service/enhance/types.ts

@@ -0,0 +1,346 @@
+/**
+ * Enhancement Types
+ *
+ * Data models for codebase analysis and AI-powered documentation generation.
+ */
+
+/**
+ * A single usage of a component in a file
+ */
+export interface ComponentUsage {
+  /** Name of the component being used */
+  componentName: string;
+
+  /** File path where this usage occurs */
+  filePath: string;
+
+  /** Line number (1-indexed) */
+  line: number;
+
+  /** Column number (0-indexed) */
+  column: number;
+
+  /** Props passed to this usage */
+  props: UsageProps;
+
+  /** 3 lines of surrounding code for context */
+  context: string;
+
+  /** Parent JSX element name (if nested) */
+  parentElement?: string;
+
+  /** Whether this usage has spread props {...props} */
+  hasSpreadProps: boolean;
+
+  /** Whether this is conditionally rendered */
+  isConditional: boolean;
+}
+
+/**
+ * Props extracted from a component usage
+ */
+export interface UsageProps {
+  /** Static prop values: { variant: "primary", disabled: true } */
+  static: Record<string, string | boolean | number>;
+
+  /** Dynamic prop names (values computed at runtime) */
+  dynamic: string[];
+
+  /** Spread prop variable names */
+  spreads: string[];
+}
+
+/**
+ * Import information for a component
+ */
+export interface ComponentImport {
+  /** Name of the imported component */
+  componentName: string;
+
+  /** Local alias if renamed: import { Button as Btn } */
+  localName: string;
+
+  /** Source module path */
+  source: string;
+
+  /** Whether this is a default import */
+  isDefault: boolean;
+
+  /** File where this import was found */
+  filePath: string;
+
+  /** Line number of the import */
+  line: number;
+}
+
+/**
+ * Aggregated usage pattern for a variant/prop combination
+ */
+export interface UsagePattern {
+  /** The prop combination that defines this pattern */
+  props: Record<string, string | boolean | number>;
+
+  /** Number of times this pattern appears */
+  count: number;
+
+  /** Files where this pattern is used */
+  files: string[];
+
+  /** Sample contexts (up to 3) */
+  sampleContexts: string[];
+}
+
+/**
+ * File context classification
+ */
+export type FileContext =
+  | "form"
+  | "modal"
+  | "page"
+  | "layout"
+  | "card"
+  | "list"
+  | "table"
+  | "navigation"
+  | "header"
+  | "footer"
+  | "sidebar"
+  | "dialog"
+  | "unknown";
+
+/**
+ * Analysis results for a single component
+ */
+export interface ComponentAnalysis {
+  /** Component name */
+  name: string;
+
+  /** Source file where component is defined */
+  sourceFile: string;
+
+  /** Total number of usages across codebase */
+  totalUsages: number;
+
+  /** Number of unique files using this component */
+  uniqueFiles: number;
+
+  /** Usage patterns sorted by frequency */
+  patterns: UsagePattern[];
+
+  /** File contexts where component is used */
+  contexts: {
+    type: FileContext;
+    count: number;
+    files: string[];
+  }[];
+
+  /** All individual usages (for detailed analysis) */
+  usages: ComponentUsage[];
+
+  /** Imports that reference this component */
+  imports: ComponentImport[];
+}
+
+/**
+ * Full codebase analysis results
+ */
+export interface UsageAnalysis {
+  /** Timestamp of analysis */
+  timestamp: string;
+
+  /** Root directory analyzed */
+  rootDir: string;
+
+  /** Total files scanned */
+  totalFiles: number;
+
+  /** Total components discovered */
+  totalComponents: number;
+
+  /** Analysis per component */
+  components: Record<string, ComponentAnalysis>;
+
+  /** Files that had parse errors (logged but skipped) */
+  errorFiles: string[];
+}
+
+/**
+ * Cache entry for a single file
+ */
+export interface FileCacheEntry {
+  /** Content hash (MD5) */
+  hash: string;
+
+  /** When this entry was created */
+  timestamp: string;
+
+  /** Imports found in this file */
+  imports: ComponentImport[];
+
+  /** Usages found in this file */
+  usages: ComponentUsage[];
+}
+
+/**
+ * Full analysis cache
+ */
+export interface AnalysisCache {
+  /** Cache version (for invalidation on schema changes) */
+  version: number;
+
+  /** When cache was created */
+  createdAt: string;
+
+  /** When cache was last updated */
+  updatedAt: string;
+
+  /** Root directory this cache is for */
+  rootDir: string;
+
+  /** Per-file cache entries */
+  files: Record<string, FileCacheEntry>;
+}
+
+/**
+ * Current cache version - increment when types change
+ */
+export const CACHE_VERSION = 1;
+
+/**
+ * Progress callback for long-running operations
+ */
+export interface ScanProgress {
+  /** Current item being processed */
+  current: number;
+
+  /** Total items to process */
+  total: number;
+
+  /** Current file path */
+  currentFile: string;
+
+  /** Phase of scanning */
+  phase: "discovering" | "scanning" | "aggregating";
+}
+
+/**
+ * Scan options
+ */
+export interface ScanOptions {
+  /** Root directory to scan */
+  rootDir: string;
+
+  /** Glob patterns for files to include */
+  include?: string[];
+
+  /** Glob patterns for files to exclude */
+  exclude?: string[];
+
+  /** Component names to specifically track (if not provided, discovers all) */
+  componentNames?: string[];
+
+  /** Whether to use cache */
+  useCache?: boolean;
+
+  /** Progress callback */
+  onProgress?: (progress: ScanProgress) => void;
+}
+
+/**
+ * File change detection result
+ */
+export interface FileChanges {
+  /** New files not in cache */
+  added: string[];
+
+  /** Modified files (hash mismatch) */
+  modified: string[];
+
+  /** Deleted files (in cache but not on disk) */
+  deleted: string[];
+
+  /** Unchanged files */
+  unchanged: string[];
+}
+
+/**
+ * Documentation extracted from various sources
+ */
+export interface ExtractedDocs {
+  /** File path of the component source */
+  filePath: string;
+
+  /** Component name */
+  componentName: string;
+
+  /** Component description */
+  description: string;
+
+  /** Props extracted from TypeScript interface or JSDoc */
+  props: Array<{
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+  }>;
+
+  /** Code examples extracted from JSDoc or Storybook */
+  examples: string[];
+
+  /** JSDoc tags (deprecated, since, version, etc.) */
+  tags: Record<string, string>;
+
+  /** Existing when/whenNot from segment file */
+  existingWhen?: string[];
+  existingWhenNot?: string[];
+  existingGuidelines?: string[];
+
+  /** Source of documentation */
+  sources?: ("jsdoc" | "storybook" | "markdown" | "segment")[];
+}
+
+/**
+ * AI-generated enhancement for a component
+ */
+export interface ComponentEnhancement {
+  /** Component name */
+  componentName: string;
+
+  /** Suggested improvements grouped by category */
+  suggestions: {
+    when: string[];
+    whenNot: string[];
+    examples: string[];
+    guidelines?: string[];
+    accessibility?: string[];
+  };
+
+  /** Confidence score 0-100 based on data quality */
+  confidence: number;
+
+  /** Reasoning for the suggestions */
+  reasoning: string[];
+
+  /** Number of usages this was based on */
+  basedOnUsages?: number;
+
+  /** Tokens used for this generation */
+  tokensUsed?: number;
+}
+
+/**
+ * Result of enhancement batch operation
+ */
+export interface EnhancementResult {
+  /** Successfully enhanced components */
+  success: Map<string, ComponentEnhancement>;
+
+  /** Components that failed with error messages */
+  failed: Map<string, string>;
+
+  /** Total API tokens used */
+  totalTokens: number;
+
+  /** Estimated cost in USD */
+  estimatedCost: number;
+}