@bfra.me/workspace-analyzer 0.1.0

package/src/cache/cache-schema.ts

@@ -0,0 +1,247 @@
+/**
+ * Cache schema types for workspace analyzer incremental analysis.
+ *
+ * These types define the structure for storing and retrieving analysis results
+ * to enable efficient incremental analysis on large codebases.
+ */
+
+import type {Issue} from '../types/index'
+
+/**
+ * Schema version for cache format migration.
+ * Increment when making breaking changes to cache structure.
+ */
+export const CACHE_SCHEMA_VERSION = 1
+
+/**
+ * Metadata about a cached file's state at analysis time.
+ */
+export interface CachedFileState {
+  /** Absolute file path */
+  readonly path: string
+  /** Content hash (SHA-256) at time of analysis */
+  readonly contentHash: string
+  /** File modification timestamp (ISO 8601) */
+  readonly modifiedAt: string
+  /** File size in bytes */
+  readonly size: number
+}
+
+/**
+ * Metadata about a cached analysis run.
+ */
+export interface CacheMetadata {
+  /** Cache schema version for migration support */
+  readonly version: number
+  /** Workspace root path that was analyzed */
+  readonly workspacePath: string
+  /** Timestamp when the cache was created (ISO 8601) */
+  readonly createdAt: string
+  /** Timestamp when the cache was last updated (ISO 8601) */
+  readonly updatedAt: string
+  /** Hash of the analyzer configuration */
+  readonly configHash: string
+  /** Workspace analyzer package version */
+  readonly analyzerVersion: string
+}
+
+/**
+ * A cached analysis result for a single file.
+ */
+export interface CachedFileAnalysis {
+  /** File state at time of analysis */
+  readonly fileState: CachedFileState
+  /** Issues found in this file */
+  readonly issues: readonly Issue[]
+  /** Analyzer IDs that processed this file */
+  readonly analyzersRun: readonly string[]
+  /** Analysis timestamp (ISO 8601) */
+  readonly analyzedAt: string
+}
+
+/**
+ * A cached package-level analysis result.
+ */
+export interface CachedPackageAnalysis {
+  /** Package name */
+  readonly packageName: string
+  /** Package path relative to workspace root */
+  readonly packagePath: string
+  /** Hash of package.json content */
+  readonly packageJsonHash: string
+  /** Issues found at the package level */
+  readonly issues: readonly Issue[]
+  /** Analyzer IDs that processed this package */
+  readonly analyzersRun: readonly string[]
+  /** Analysis timestamp (ISO 8601) */
+  readonly analyzedAt: string
+}
+
+/**
+ * Complete analysis cache for a workspace.
+ */
+export interface AnalysisCache {
+  /** Cache metadata */
+  readonly metadata: CacheMetadata
+  /** Per-file analysis results indexed by file path */
+  readonly files: Readonly<Record<string, CachedFileAnalysis>>
+  /** Per-package analysis results indexed by package name */
+  readonly packages: Readonly<Record<string, CachedPackageAnalysis>>
+  /** Workspace-level issues not tied to specific files */
+  readonly workspaceIssues: readonly Issue[]
+  /** Configuration files state for invalidation detection */
+  readonly configFiles: readonly CachedFileState[]
+}
+
+/**
+ * Result of cache validation check.
+ */
+export interface CacheValidationResult {
+  /** Whether the cache is valid and can be used */
+  readonly isValid: boolean
+  /** Files that have changed since last analysis */
+  readonly changedFiles: readonly string[]
+  /** Files that are new since last analysis */
+  readonly newFiles: readonly string[]
+  /** Files that were deleted since last analysis */
+  readonly deletedFiles: readonly string[]
+  /** Packages that need re-analysis */
+  readonly invalidatedPackages: readonly string[]
+  /** Configuration files that changed (triggers full invalidation) */
+  readonly changedConfigFiles: readonly string[]
+  /** Reason for invalidation if not valid */
+  readonly invalidationReason?: string
+}
+
+/**
+ * Options for cache operations.
+ */
+export interface CacheOptions {
+  /** Directory path for cache storage (default: .workspace-analyzer-cache) */
+  readonly cacheDir?: string
+  /** Maximum cache age in milliseconds (default: 7 days) */
+  readonly maxAge?: number
+  /** Whether to compress cache files (default: true) */
+  readonly compress?: boolean
+  /** Hash algorithm for file content (default: sha256) */
+  readonly hashAlgorithm?: 'sha256' | 'md5'
+}
+
+/**
+ * Statistics about cache usage.
+ */
+export interface CacheStatistics {
+  /** Number of cached files */
+  readonly cachedFiles: number
+  /** Number of cached packages */
+  readonly cachedPackages: number
+  /** Total cache size in bytes */
+  readonly totalSizeBytes: number
+  /** Cache age in milliseconds */
+  readonly ageMs: number
+  /** Number of cache hits during last analysis */
+  readonly hitCount: number
+  /** Number of cache misses during last analysis */
+  readonly missCount: number
+  /** Cache hit rate (0-1) */
+  readonly hitRate: number
+}
+
+/**
+ * Configuration file patterns for cache invalidation.
+ * Changes to these files trigger re-analysis of affected areas.
+ */
+export const CONFIG_FILE_PATTERNS: readonly string[] = [
+  'package.json',
+  'tsconfig.json',
+  'tsconfig.*.json',
+  'eslint.config.ts',
+  'eslint.config.js',
+  'eslint.config.mjs',
+  '.eslintrc.*',
+  'tsup.config.ts',
+  'tsup.config.js',
+  'vitest.config.ts',
+  'vitest.config.js',
+  'workspace-analyzer.config.ts',
+  'workspace-analyzer.config.js',
+]
+
+/**
+ * Default cache options.
+ */
+export const DEFAULT_CACHE_OPTIONS: Required<CacheOptions> = {
+  cacheDir: '.workspace-analyzer-cache',
+  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
+  compress: true,
+  hashAlgorithm: 'sha256',
+} as const
+
+/**
+ * Creates an empty analysis cache with default metadata.
+ */
+export function createEmptyCache(
+  workspacePath: string,
+  configHash: string,
+  analyzerVersion: string,
+): AnalysisCache {
+  const now = new Date().toISOString()
+  return {
+    metadata: {
+      version: CACHE_SCHEMA_VERSION,
+      workspacePath,
+      createdAt: now,
+      updatedAt: now,
+      configHash,
+      analyzerVersion,
+    },
+    files: {},
+    packages: {},
+    workspaceIssues: [],
+    configFiles: [],
+  }
+}
+
+/**
+ * Creates a cache entry for a file analysis result.
+ */
+export function createFileAnalysisEntry(
+  path: string,
+  contentHash: string,
+  modifiedAt: Date,
+  size: number,
+  issues: readonly Issue[],
+  analyzersRun: readonly string[],
+): CachedFileAnalysis {
+  return {
+    fileState: {
+      path,
+      contentHash,
+      modifiedAt: modifiedAt.toISOString(),
+      size,
+    },
+    issues,
+    analyzersRun,
+    analyzedAt: new Date().toISOString(),
+  }
+}
+
+/**
+ * Creates a cache entry for a package analysis result.
+ */
+export function createPackageAnalysisEntry(
+  packageName: string,
+  packagePath: string,
+  packageJsonHash: string,
+  issues: readonly Issue[],
+  analyzersRun: readonly string[],
+): CachedPackageAnalysis {
+  return {
+    packageName,
+    packagePath,
+    packageJsonHash,
+    issues,
+    analyzersRun,
+    analyzedAt: new Date().toISOString(),
+  }
+}

package/src/cache/change-detector.ts

@@ -0,0 +1,169 @@
+/**
+ * Change detector for incremental analysis.
+ *
+ * Re-exports from @bfra.me/es/watcher with workspace-analyzer-specific utilities.
+ */
+
+import type {ChangeDetector, ChangeDetectorOptions} from '@bfra.me/es/watcher'
+import type {CachedFileState, CacheValidationResult} from './cache-schema'
+import {createChangeDetector} from '@bfra.me/es/watcher'
+
+import {createWorkspaceHasher} from './file-hasher'
+
+// Re-export the core change detector
+export {createChangeDetector}
+export type {ChangeDetector, ChangeDetectorOptions}
+
+/**
+ * Options for creating an analysis change detector.
+ */
+export interface AnalysisChangeDetectorOptions extends ChangeDetectorOptions {
+  /** Configuration file patterns to monitor for invalidation */
+  readonly configFilePatterns?: readonly string[]
+}
+
+/**
+ * Extended change detector for workspace analysis.
+ */
+export interface AnalysisChangeDetector extends ChangeDetector {
+  /** Validate cache against current file states */
+  readonly validateCache: (
+    cachedFiles: readonly CachedFileState[],
+    currentFiles: readonly string[],
+  ) => Promise<CacheValidationResult>
+  /** Get all recorded file paths */
+  readonly getRecordedPaths: () => readonly string[]
+  /** Check if configuration files have changed */
+  readonly hasConfigChanged: (configFiles: readonly CachedFileState[]) => Promise<boolean>
+}
+
+/**
+ * Creates an extended change detector for workspace analysis.
+ *
+ * @param options - Change detector configuration options
+ * @returns An AnalysisChangeDetector instance
+ *
+ * @example
+ * ```ts
+ * const detector = createAnalysisChangeDetector()
+ *
+ * // Record initial file state
+ * await detector.record('src/index.ts')
+ *
+ * // Later, validate cache
+ * const validation = await detector.validateCache(
+ *   cachedFileStates,
+ *   currentFilePaths
+ * )
+ *
+ * if (!validation.isValid) {
+ *   console.log('Cache invalid:', validation.invalidationReason)
+ * }
+ * ```
+ */
+export function createAnalysisChangeDetector(
+  options: AnalysisChangeDetectorOptions = {},
+): AnalysisChangeDetector {
+  const baseDetector = createChangeDetector(options)
+  const hasher = createWorkspaceHasher({algorithm: options.algorithm})
+  const recordedPaths = new Set<string>()
+
+  return {
+    async hasChanged(path: string): Promise<boolean> {
+      return baseDetector.hasChanged(path)
+    },
+
+    async record(path: string): Promise<void> {
+      recordedPaths.add(path)
+      return baseDetector.record(path)
+    },
+
+    clear(path: string): void {
+      recordedPaths.delete(path)
+      baseDetector.clear(path)
+    },
+
+    clearAll(): void {
+      recordedPaths.clear()
+      baseDetector.clearAll()
+    },
+
+    getRecordedPaths(): readonly string[] {
+      return Array.from(recordedPaths)
+    },
+
+    async validateCache(
+      cachedFiles: readonly CachedFileState[],
+      currentFiles: readonly string[],
+    ): Promise<CacheValidationResult> {
+      const cachedPaths = new Set(cachedFiles.map(f => f.path))
+      const currentPaths = new Set(currentFiles)
+
+      const changedFiles: string[] = []
+      const newFiles: string[] = []
+      const deletedFiles: string[] = []
+
+      // Check for new files
+      for (const path of currentPaths) {
+        if (!cachedPaths.has(path)) {
+          newFiles.push(path)
+        }
+      }
+
+      // Check for deleted and changed files
+      for (const cached of cachedFiles) {
+        if (!currentPaths.has(cached.path)) {
+          deletedFiles.push(cached.path)
+          continue
+        }
+
+        // Check if file content has changed
+        try {
+          const currentHash = await hasher.hash(cached.path)
+          if (currentHash !== cached.contentHash) {
+            changedFiles.push(cached.path)
+          }
+        } catch {
+          // File might have been deleted or inaccessible
+          deletedFiles.push(cached.path)
+        }
+      }
+
+      const hasChanges = changedFiles.length > 0 || newFiles.length > 0 || deletedFiles.length > 0
+
+      let invalidationReason: string | undefined
+      if (hasChanges) {
+        const reasons: string[] = []
+        if (changedFiles.length > 0) reasons.push(`${changedFiles.length} files changed`)
+        if (newFiles.length > 0) reasons.push(`${newFiles.length} new files`)
+        if (deletedFiles.length > 0) reasons.push(`${deletedFiles.length} files deleted`)
+        invalidationReason = reasons.join(', ')
+      }
+
+      return {
+        isValid: !hasChanges,
+        changedFiles,
+        newFiles,
+        deletedFiles,
+        invalidatedPackages: [], // Computed by cache manager based on file paths
+        changedConfigFiles: [],
+        invalidationReason,
+      }
+    },
+
+    async hasConfigChanged(configFiles: readonly CachedFileState[]): Promise<boolean> {
+      for (const config of configFiles) {
+        try {
+          const currentHash = await hasher.hash(config.path)
+          if (currentHash !== config.contentHash) {
+            return true
+          }
+        } catch {
+          // Config file was deleted or inaccessible = changed
+          return true
+        }
+      }
+      return false
+    },
+  }
+}

package/src/cache/file-hasher.ts

@@ -0,0 +1,65 @@
+/**
+ * File hasher for cache invalidation and change detection.
+ *
+ * Re-exports from @bfra.me/es/watcher with workspace-analyzer-specific utilities.
+ */
+
+import type {FileHasher} from '@bfra.me/es/watcher'
+import {createFileHasher} from '@bfra.me/es/watcher'
+
+// Re-export the core hasher factory
+export {createFileHasher}
+export type {FileHasher}
+
+/**
+ * Options for creating a workspace file hasher.
+ */
+export interface WorkspaceHasherOptions {
+  /** Hash algorithm to use (default: sha256) */
+  readonly algorithm?: 'sha256' | 'md5'
+  /** Whether to normalize line endings before hashing (default: true) */
+  readonly normalizeLineEndings?: boolean
+}
+
+/**
+ * Extended file hasher with workspace-specific utilities.
+ */
+export interface WorkspaceFileHasher extends FileHasher {
+  /** Hash a JSON object consistently (keys sorted) */
+  readonly hashJson: (obj: unknown) => string
+  /** Hash multiple files and return combined hash */
+  readonly hashFiles: (paths: readonly string[]) => Promise<string>
+}
+
+/**
+ * Creates an extended file hasher with workspace-specific utilities.
+ *
+ * @param options - Hasher configuration options
+ * @returns A WorkspaceFileHasher instance
+ *
+ * @example
+ * ```ts
+ * const hasher = createWorkspaceHasher()
+ * const configHash = hasher.hashJson(analyzerConfig)
+ * const filesHash = await hasher.hashFiles(['package.json', 'tsconfig.json'])
+ * ```
+ */
+export function createWorkspaceHasher(options: WorkspaceHasherOptions = {}): WorkspaceFileHasher {
+  const {algorithm = 'sha256'} = options
+  const baseHasher = createFileHasher(algorithm)
+
+  return {
+    ...baseHasher,
+
+    hashJson(obj: unknown): string {
+      const normalized = JSON.stringify(obj, Object.keys(obj as object).sort(), 0)
+      return baseHasher.hashContent(normalized)
+    },
+
+    async hashFiles(paths: readonly string[]): Promise<string> {
+      const hashes = await Promise.all(paths.map(async path => baseHasher.hash(path)))
+      const combined = hashes.join(':')
+      return baseHasher.hashContent(combined)
+    },
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Cache module exports for workspace analyzer.
+ *
+ * Provides caching infrastructure for incremental analysis including
+ * file hashing, change detection, and cache management.
+ */
+
+// Cache manager
+export {collectConfigFileStates, createCacheManager, initializeCache} from './cache-manager'
+
+export type {CacheError, CacheErrorCode, CacheManager, CacheManagerOptions} from './cache-manager'
+
+// Cache schema types and utilities
+export {
+  CACHE_SCHEMA_VERSION,
+  CONFIG_FILE_PATTERNS,
+  createEmptyCache,
+  createFileAnalysisEntry,
+  createPackageAnalysisEntry,
+  DEFAULT_CACHE_OPTIONS,
+} from './cache-schema'
+
+export type {
+  AnalysisCache,
+  CachedFileAnalysis,
+  CachedFileState,
+  CachedPackageAnalysis,
+  CacheMetadata,
+  CacheOptions,
+  CacheStatistics,
+  CacheValidationResult,
+} from './cache-schema'
+
+// Change detector utilities
+export {createAnalysisChangeDetector, createChangeDetector} from './change-detector'
+
+export type {
+  AnalysisChangeDetector,
+  AnalysisChangeDetectorOptions,
+  ChangeDetector,
+  ChangeDetectorOptions,
+} from './change-detector'
+
+// File hasher utilities
+export {createFileHasher, createWorkspaceHasher} from './file-hasher'
+
+export type {FileHasher, WorkspaceFileHasher, WorkspaceHasherOptions} from './file-hasher'