@fragments-sdk/cli 0.2.2

package/src/service/enhance/cache.ts

@@ -0,0 +1,275 @@
+/**
+ * Analysis Cache Layer
+ *
+ * Caches file analysis results to enable fast incremental updates.
+ */
+
+import { readFile, writeFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join, dirname } from "node:path";
+import { mkdir } from "node:fs/promises";
+import type {
+  AnalysisCache,
+  FileCacheEntry,
+  FileChanges,
+  ComponentImport,
+  ComponentUsage,
+  CACHE_VERSION,
+} from "./types.js";
+
+const CURRENT_CACHE_VERSION = 1;
+const CACHE_FILENAME = "analysis-cache.json";
+
+/**
+ * Get the cache file path for a project
+ */
+export function getCachePath(rootDir: string): string {
+  return join(rootDir, ".fragments", CACHE_FILENAME);
+}
+
+/**
+ * Load cache from disk
+ * Returns null if cache doesn't exist or is invalid
+ */
+export async function loadCache(rootDir: string): Promise<AnalysisCache | null> {
+  const cachePath = getCachePath(rootDir);
+
+  if (!existsSync(cachePath)) {
+    return null;
+  }
+
+  try {
+    const content = await readFile(cachePath, "utf-8");
+    const cache = JSON.parse(content) as AnalysisCache;
+
+    // Validate version
+    if (cache.version !== CURRENT_CACHE_VERSION) {
+      console.warn(
+        `Cache version mismatch: expected ${CURRENT_CACHE_VERSION}, got ${cache.version}. Invalidating cache.`
+      );
+      return null;
+    }
+
+    // Validate root dir matches
+    if (cache.rootDir !== rootDir) {
+      console.warn(`Cache root mismatch. Invalidating cache.`);
+      return null;
+    }
+
+    return cache;
+  } catch (error) {
+    console.warn(`Failed to load cache: ${(error as Error).message}`);
+    return null;
+  }
+}
+
+/**
+ * Save cache to disk
+ */
+export async function saveCache(
+  rootDir: string,
+  cache: AnalysisCache
+): Promise<void> {
+  const cachePath = getCachePath(rootDir);
+  const cacheDir = dirname(cachePath);
+
+  // Ensure .fragments directory exists
+  if (!existsSync(cacheDir)) {
+    await mkdir(cacheDir, { recursive: true });
+  }
+
+  cache.updatedAt = new Date().toISOString();
+  await writeFile(cachePath, JSON.stringify(cache, null, 2));
+}
+
+/**
+ * Create a new empty cache
+ */
+export function createEmptyCache(rootDir: string): AnalysisCache {
+  const now = new Date().toISOString();
+  return {
+    version: CURRENT_CACHE_VERSION,
+    createdAt: now,
+    updatedAt: now,
+    rootDir,
+    files: {},
+  };
+}
+
+/**
+ * Compute content hash for a file
+ */
+export function computeFileHash(content: string): string {
+  return createHash("md5").update(content).digest("hex");
+}
+
+/**
+ * Compute file hash from disk
+ */
+export async function computeFileHashFromDisk(
+  filePath: string
+): Promise<string> {
+  const content = await readFile(filePath, "utf-8");
+  return computeFileHash(content);
+}
+
+/**
+ * Check if a file is cached and unchanged
+ */
+export function isFileCached(
+  cache: AnalysisCache,
+  filePath: string,
+  currentHash: string
+): boolean {
+  const entry = cache.files[filePath];
+  if (!entry) return false;
+  return entry.hash === currentHash;
+}
+
+/**
+ * Get cached data for a file
+ */
+export function getCachedFile(
+  cache: AnalysisCache,
+  filePath: string
+): FileCacheEntry | null {
+  return cache.files[filePath] ?? null;
+}
+
+/**
+ * Update cache with results for a file
+ */
+export function updateCacheFile(
+  cache: AnalysisCache,
+  filePath: string,
+  hash: string,
+  imports: ComponentImport[],
+  usages: ComponentUsage[]
+): void {
+  cache.files[filePath] = {
+    hash,
+    timestamp: new Date().toISOString(),
+    imports,
+    usages,
+  };
+}
+
+/**
+ * Remove a file from cache
+ */
+export function removeCacheFile(cache: AnalysisCache, filePath: string): void {
+  delete cache.files[filePath];
+}
+
+/**
+ * Invalidate cache entries for specific files
+ */
+export function invalidateCache(
+  cache: AnalysisCache,
+  filePaths: string[]
+): void {
+  for (const filePath of filePaths) {
+    delete cache.files[filePath];
+  }
+}
+
+/**
+ * Detect file changes by comparing current files to cache
+ */
+export async function detectFileChanges(
+  cache: AnalysisCache,
+  currentFiles: string[],
+  getFileHash: (filePath: string) => Promise<string>
+): Promise<FileChanges> {
+  const changes: FileChanges = {
+    added: [],
+    modified: [],
+    deleted: [],
+    unchanged: [],
+  };
+
+  const currentFileSet = new Set(currentFiles);
+  const cachedFileSet = new Set(Object.keys(cache.files));
+
+  // Check for added and modified files
+  for (const filePath of currentFiles) {
+    const entry = cache.files[filePath];
+
+    if (!entry) {
+      changes.added.push(filePath);
+    } else {
+      const currentHash = await getFileHash(filePath);
+      if (currentHash !== entry.hash) {
+        changes.modified.push(filePath);
+      } else {
+        changes.unchanged.push(filePath);
+      }
+    }
+  }
+
+  // Check for deleted files
+  for (const cachedFile of cachedFileSet) {
+    if (!currentFileSet.has(cachedFile)) {
+      changes.deleted.push(cachedFile);
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Get all cached imports
+ */
+export function getAllCachedImports(cache: AnalysisCache): ComponentImport[] {
+  const imports: ComponentImport[] = [];
+  for (const entry of Object.values(cache.files)) {
+    imports.push(...entry.imports);
+  }
+  return imports;
+}
+
+/**
+ * Get all cached usages
+ */
+export function getAllCachedUsages(cache: AnalysisCache): ComponentUsage[] {
+  const usages: ComponentUsage[] = [];
+  for (const entry of Object.values(cache.files)) {
+    usages.push(...entry.usages);
+  }
+  return usages;
+}
+
+/**
+ * Get cache statistics
+ */
+export function getCacheStats(cache: AnalysisCache): {
+  totalFiles: number;
+  totalImports: number;
+  totalUsages: number;
+  cacheAge: string;
+} {
+  let totalImports = 0;
+  let totalUsages = 0;
+
+  for (const entry of Object.values(cache.files)) {
+    totalImports += entry.imports.length;
+    totalUsages += entry.usages.length;
+  }
+
+  const ageMs = Date.now() - new Date(cache.updatedAt).getTime();
+  const ageMinutes = Math.round(ageMs / 60000);
+  const cacheAge =
+    ageMinutes < 60
+      ? `${ageMinutes} minutes ago`
+      : ageMinutes < 1440
+        ? `${Math.round(ageMinutes / 60)} hours ago`
+        : `${Math.round(ageMinutes / 1440)} days ago`;
+
+  return {
+    totalFiles: Object.keys(cache.files).length,
+    totalImports,
+    totalUsages,
+    cacheAge,
+  };
+}

package/src/service/enhance/codebase-scanner.ts

@@ -0,0 +1,357 @@
+/**
+ * Full Codebase Scanner
+ *
+ * Scans entire codebase for component usage patterns with caching and progress.
+ */
+
+import fg from "fast-glob";
+import { readFile } from "node:fs/promises";
+import { relative, resolve, dirname, basename } from "node:path";
+import type {
+  ScanOptions,
+  ScanProgress,
+  UsageAnalysis,
+  ComponentImport,
+  ComponentUsage,
+  FileChanges,
+  AnalysisCache,
+} from "./types.js";
+import { scanFile } from "./scanner.js";
+import { aggregateAllUsages } from "./aggregator.js";
+import {
+  loadCache,
+  saveCache,
+  createEmptyCache,
+  computeFileHash,
+  isFileCached,
+  updateCacheFile,
+  removeCacheFile,
+  getCachedFile,
+  detectFileChanges,
+  getCacheStats,
+} from "./cache.js";
+
+/**
+ * Default patterns for files to scan
+ */
+const DEFAULT_INCLUDE = [
+  "**/*.tsx",
+  "**/*.ts",
+  "**/*.jsx",
+  "**/*.js",
+];
+
+/**
+ * Default patterns for files to exclude
+ */
+const DEFAULT_EXCLUDE = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/coverage/**",
+  "**/__tests__/**",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/*.stories.*",
+  "**/*.segment.*",
+  "**/storybook-static/**",
+];
+
+/**
+ * Scan entire codebase for component usages
+ */
+export async function scanCodebase(
+  options: ScanOptions
+): Promise<UsageAnalysis> {
+  const {
+    rootDir,
+    include = DEFAULT_INCLUDE,
+    exclude = DEFAULT_EXCLUDE,
+    componentNames,
+    useCache = true,
+    onProgress,
+  } = options;
+
+  const absoluteRoot = resolve(rootDir);
+
+  // Load or create cache
+  let cache: AnalysisCache | null = null;
+  if (useCache) {
+    cache = await loadCache(absoluteRoot);
+  }
+  if (!cache) {
+    cache = createEmptyCache(absoluteRoot);
+  }
+
+  // Discover all files
+  onProgress?.({
+    current: 0,
+    total: 0,
+    currentFile: "",
+    phase: "discovering",
+  });
+
+  const files = await fg(include, {
+    cwd: absoluteRoot,
+    ignore: exclude,
+    absolute: true,
+    onlyFiles: true,
+  });
+
+  const totalFiles = files.length;
+
+  // Track components to find (if specific ones provided)
+  const trackedComponents = componentNames
+    ? new Set(componentNames)
+    : undefined;
+
+  // Collect all imports and usages
+  const allImports: ComponentImport[] = [];
+  const allUsages: ComponentUsage[] = [];
+  const errorFiles: string[] = [];
+  const componentSources = new Map<string, string>();
+
+  // Process files
+  for (let i = 0; i < files.length; i++) {
+    const filePath = files[i];
+    const relativePath = relative(absoluteRoot, filePath);
+
+    onProgress?.({
+      current: i + 1,
+      total: totalFiles,
+      currentFile: relativePath,
+      phase: "scanning",
+    });
+
+    try {
+      // Read file content for hash
+      const content = await readFile(filePath, "utf-8");
+      const fileHash = computeFileHash(content);
+
+      // Check cache
+      const cachedEntry = getCachedFile(cache, filePath);
+      if (cachedEntry && cachedEntry.hash === fileHash) {
+        // Use cached results
+        allImports.push(...cachedEntry.imports);
+        allUsages.push(...cachedEntry.usages);
+
+        // Track component sources from imports
+        for (const imp of cachedEntry.imports) {
+          if (!componentSources.has(imp.componentName)) {
+            const sourceFile = resolveImportSource(filePath, imp.source);
+            if (sourceFile) {
+              componentSources.set(imp.componentName, sourceFile);
+            }
+          }
+        }
+        continue;
+      }
+
+      // Scan file
+      const { imports, usages } = await scanFile(filePath, trackedComponents);
+
+      // Update cache
+      updateCacheFile(cache, filePath, fileHash, imports, usages);
+
+      allImports.push(...imports);
+      allUsages.push(...usages);
+
+      // Track component sources
+      for (const imp of imports) {
+        if (!componentSources.has(imp.componentName)) {
+          const sourceFile = resolveImportSource(filePath, imp.source);
+          if (sourceFile) {
+            componentSources.set(imp.componentName, sourceFile);
+          }
+        }
+      }
+    } catch (error) {
+      errorFiles.push(relativePath);
+      console.warn(`Error scanning ${relativePath}:`, (error as Error).message);
+    }
+  }
+
+  // Save cache
+  if (useCache) {
+    await saveCache(absoluteRoot, cache);
+  }
+
+  // Aggregate results
+  onProgress?.({
+    current: totalFiles,
+    total: totalFiles,
+    currentFile: "",
+    phase: "aggregating",
+  });
+
+  const analysis = aggregateAllUsages(allUsages, allImports, componentSources);
+  analysis.rootDir = absoluteRoot;
+  analysis.totalFiles = totalFiles;
+  analysis.errorFiles = errorFiles;
+
+  return analysis;
+}
+
+/**
+ * Perform incremental scan for changed files only
+ */
+export async function incrementalScan(
+  rootDir: string,
+  changes: FileChanges,
+  existingCache: AnalysisCache,
+  onProgress?: (progress: ScanProgress) => void
+): Promise<{ analysis: UsageAnalysis; cache: AnalysisCache }> {
+  const absoluteRoot = resolve(rootDir);
+  const cache = { ...existingCache, files: { ...existingCache.files } };
+
+  // Remove deleted files from cache
+  for (const filePath of changes.deleted) {
+    removeCacheFile(cache, filePath);
+  }
+
+  // Files to scan (added + modified)
+  const filesToScan = [...changes.added, ...changes.modified];
+  const totalFiles = filesToScan.length;
+
+  const allImports: ComponentImport[] = [];
+  const allUsages: ComponentUsage[] = [];
+  const errorFiles: string[] = [];
+  const componentSources = new Map<string, string>();
+
+  // First, collect unchanged file data from cache
+  for (const filePath of changes.unchanged) {
+    const cachedEntry = getCachedFile(cache, filePath);
+    if (cachedEntry) {
+      allImports.push(...cachedEntry.imports);
+      allUsages.push(...cachedEntry.usages);
+
+      for (const imp of cachedEntry.imports) {
+        if (!componentSources.has(imp.componentName)) {
+          const sourceFile = resolveImportSource(filePath, imp.source);
+          if (sourceFile) {
+            componentSources.set(imp.componentName, sourceFile);
+          }
+        }
+      }
+    }
+  }
+
+  // Scan changed files
+  for (let i = 0; i < filesToScan.length; i++) {
+    const filePath = filesToScan[i];
+    const relativePath = relative(absoluteRoot, filePath);
+
+    onProgress?.({
+      current: i + 1,
+      total: totalFiles,
+      currentFile: relativePath,
+      phase: "scanning",
+    });
+
+    try {
+      const content = await readFile(filePath, "utf-8");
+      const fileHash = computeFileHash(content);
+
+      const { imports, usages } = await scanFile(filePath);
+
+      updateCacheFile(cache, filePath, fileHash, imports, usages);
+
+      allImports.push(...imports);
+      allUsages.push(...usages);
+
+      for (const imp of imports) {
+        if (!componentSources.has(imp.componentName)) {
+          const sourceFile = resolveImportSource(filePath, imp.source);
+          if (sourceFile) {
+            componentSources.set(imp.componentName, sourceFile);
+          }
+        }
+      }
+    } catch (error) {
+      errorFiles.push(relativePath);
+    }
+  }
+
+  // Save updated cache
+  await saveCache(absoluteRoot, cache);
+
+  // Aggregate
+  const analysis = aggregateAllUsages(allUsages, allImports, componentSources);
+  analysis.rootDir = absoluteRoot;
+  analysis.totalFiles = changes.unchanged.length + filesToScan.length;
+  analysis.errorFiles = errorFiles;
+
+  return { analysis, cache };
+}
+
+/**
+ * Resolve import source to absolute file path
+ */
+function resolveImportSource(
+  importingFile: string,
+  source: string
+): string | null {
+  // Skip node_modules imports
+  if (!source.startsWith(".") && !source.startsWith("/")) {
+    return null;
+  }
+
+  const importDir = dirname(importingFile);
+
+  // Try common extensions
+  const extensions = ["", ".tsx", ".ts", ".jsx", ".js", "/index.tsx", "/index.ts"];
+  for (const ext of extensions) {
+    const fullPath = resolve(importDir, source + ext);
+    // We don't check if file exists here for performance
+    // The source path is mainly for reference
+    if (ext === "" && source.endsWith(".tsx")) {
+      return fullPath;
+    }
+    if (ext) {
+      return resolve(importDir, source) + ext;
+    }
+  }
+
+  return resolve(importDir, source);
+}
+
+/**
+ * Get scan statistics for display
+ */
+export function getScanStats(analysis: UsageAnalysis): {
+  totalFiles: number;
+  totalComponents: number;
+  totalUsages: number;
+  topComponents: { name: string; usages: number }[];
+} {
+  const totalUsages = Object.values(analysis.components).reduce(
+    (sum, c) => sum + c.totalUsages,
+    0
+  );
+
+  const topComponents = Object.values(analysis.components)
+    .map((c) => ({ name: c.name, usages: c.totalUsages }))
+    .sort((a, b) => b.usages - a.usages)
+    .slice(0, 10);
+
+  return {
+    totalFiles: analysis.totalFiles,
+    totalComponents: analysis.totalComponents,
+    totalUsages,
+    topComponents,
+  };
+}
+
+/**
+ * Export for quick check if cache exists and is valid
+ */
+export async function hasCachedAnalysis(rootDir: string): Promise<boolean> {
+  const cache = await loadCache(resolve(rootDir));
+  if (!cache) return false;
+  const stats = getCacheStats(cache);
+  return stats.totalFiles > 0;
+}
+
+// Re-export types and utilities
+export { loadCache, getCacheStats, detectFileChanges } from "./cache.js";