@sylphx/flow 1.0.1 → 1.0.3

package/src/utils/codebase-helpers.ts

@@ -0,0 +1,211 @@
+/**
+ * Codebase indexing helper functions
+ * Utility functions for file scanning and language detection
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import ignore, { type Ignore } from 'ignore';
+
+/**
+ * Detect programming language from file extension
+ */
+export function detectLanguage(filePath: string): string | undefined {
+  const ext = path.extname(filePath).toLowerCase();
+  const languageMap: Record<string, string> = {
+    '.ts': 'TypeScript',
+    '.tsx': 'TSX',
+    '.js': 'JavaScript',
+    '.jsx': 'JSX',
+    '.py': 'Python',
+    '.java': 'Java',
+    '.go': 'Go',
+    '.rs': 'Rust',
+    '.c': 'C',
+    '.cpp': 'C++',
+    '.cs': 'C#',
+    '.rb': 'Ruby',
+    '.php': 'PHP',
+    '.swift': 'Swift',
+    '.kt': 'Kotlin',
+    '.md': 'Markdown',
+    '.json': 'JSON',
+    '.yaml': 'YAML',
+    '.yml': 'YAML',
+    '.toml': 'TOML',
+    '.sql': 'SQL',
+    '.sh': 'Shell',
+    '.bash': 'Bash',
+  };
+  return languageMap[ext];
+}
+
+/**
+ * Check if file is text-based (not binary)
+ */
+export function isTextFile(filePath: string): boolean {
+  const textExtensions = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.py',
+    '.java',
+    '.go',
+    '.rs',
+    '.c',
+    '.cpp',
+    '.h',
+    '.hpp',
+    '.cs',
+    '.rb',
+    '.php',
+    '.swift',
+    '.kt',
+    '.md',
+    '.txt',
+    '.json',
+    '.yaml',
+    '.yml',
+    '.toml',
+    '.xml',
+    '.sql',
+    '.sh',
+    '.bash',
+    '.zsh',
+    '.fish',
+    '.dockerfile',
+    '.gitignore',
+    '.env',
+    '.env.example',
+    '.env.local',
+    '.env.development',
+    '.env.production',
+  ]);
+
+  const ext = path.extname(filePath).toLowerCase();
+  return textExtensions.has(ext) || !ext; // Files without extension might be text
+}
+
+/**
+ * Load .gitignore file and create ignore filter
+ */
+export function loadGitignore(codebaseRoot: string): Ignore {
+  const ig = ignore();
+
+  // Add default ignore patterns
+  ig.add([
+    'node_modules',
+    '.git',
+    '.svn',
+    '.hg',
+    '.DS_Store',
+    '.idea',
+    '.vscode',
+    '*.suo',
+    '*.ntvs*',
+    '*.njsproj',
+    '*.sln',
+    '*.swp',
+    '.sylphx-flow',
+    '.cache',
+    'dist',
+    'build',
+    'coverage',
+    '.nyc_output',
+  ]);
+
+  const gitignorePath = path.join(codebaseRoot, '.gitignore');
+
+  if (fs.existsSync(gitignorePath)) {
+    try {
+      const content = fs.readFileSync(gitignorePath, 'utf8');
+      ig.add(content);
+    } catch (error) {
+      console.warn(`[WARN] Failed to read .gitignore: ${error}`);
+    }
+  }
+
+  return ig;
+}
+
+/**
+ * Scan directory recursively for files
+ */
+export interface ScanOptions {
+  ignoreFilter?: Ignore;
+  codebaseRoot?: string;
+}
+
+export interface ScanResult {
+  path: string;
+  absolutePath: string;
+  content: string;
+  size: number;
+  mtime: number;
+}
+
+/**
+ * Scan files in directory with .gitignore support
+ */
+export function scanFiles(dir: string, options: ScanOptions = {}): ScanResult[] {
+  const results: ScanResult[] = [];
+  const ignoreFilter = options.ignoreFilter;
+  const codebaseRoot = options.codebaseRoot || dir;
+
+  function scan(currentDir: string) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      const relativePath = path.relative(codebaseRoot, fullPath);
+
+      // Skip ignored files
+      if (ignoreFilter?.ignores(relativePath)) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        scan(fullPath);
+      } else if (entry.isFile()) {
+        try {
+          const stats = fs.statSync(fullPath);
+          const _ext = path.extname(fullPath);
+
+          // Only process text files
+          if (!isTextFile(fullPath)) {
+            continue;
+          }
+
+          const content = fs.readFileSync(fullPath, 'utf8');
+
+          results.push({
+            path: relativePath,
+            absolutePath: fullPath,
+            content,
+            size: stats.size,
+            mtime: stats.mtimeMs,
+          });
+        } catch (error) {
+          console.warn(`[WARN] Failed to read file: ${relativePath}`, error);
+        }
+      }
+    }
+  }
+
+  scan(dir);
+  return results;
+}
+
+/**
+ * Calculate simple hash for file content (for change detection)
+ */
+export function simpleHash(content: string): string {
+  let hash = 0;
+  for (let i = 0; i < content.length; i++) {
+    const char = content.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash &= hash; // Convert to 32-bit integer
+  }
+  return hash.toString(36);
+}

package/src/utils/console-ui.ts

@@ -0,0 +1,79 @@
+/**
+ * Modern console UI utilities
+ * Progressive output with beautiful formatting
+ */
+
+import chalk from 'chalk';
+
+export const ui = {
+  // Headers
+  header: (text: string) => {
+    console.log('');
+    console.log(chalk.cyan.bold(`▸ ${text}`));
+  },
+
+  subheader: (text: string) => {
+    console.log(chalk.gray(`  ${text}`));
+  },
+
+  // Status messages
+  success: (text: string) => {
+    console.log(chalk.green(`✓ ${text}`));
+  },
+
+  error: (text: string) => {
+    console.log(chalk.red(`✗ ${text}`));
+  },
+
+  warning: (text: string) => {
+    console.log(chalk.yellow(`⚠ ${text}`));
+  },
+
+  info: (text: string) => {
+    console.log(chalk.cyan(`ℹ ${text}`));
+  },
+
+  // Progress
+  step: (text: string) => {
+    console.log(chalk.gray(`  • ${text}`));
+  },
+
+  loading: (text: string) => {
+    console.log(chalk.cyan(`⏳ ${text}`));
+  },
+
+  // Fields
+  field: (label: string, value: string, secret = false) => {
+    const displayValue = secret ? '•'.repeat(Math.min(8, value.length)) : value;
+    console.log(`  ${chalk.gray(label)}: ${chalk.white(displayValue)}`);
+  },
+
+  // Dividers
+  divider: () => {
+    console.log(chalk.gray('  ─'.repeat(40)));
+  },
+
+  spacer: () => {
+    console.log('');
+  },
+
+  // Lists
+  list: (items: string[]) => {
+    items.forEach((item) => {
+      console.log(chalk.gray(`  • ${item}`));
+    });
+  },
+
+  // Input prompt (for simple inputs)
+  prompt: (label: string, required = false) => {
+    const indicator = required ? chalk.red('*') : '';
+    return `${chalk.cyan('❯')} ${label}${indicator}: `;
+  },
+
+  // Section
+  section: (title: string, content: () => void) => {
+    console.log('');
+    console.log(chalk.cyan.bold(`▸ ${title}`));
+    content();
+  },
+};

package/src/utils/database-errors.ts

@@ -0,0 +1,140 @@
+/**
+ * Database Error Handling - Simplified System
+ * Replaces complex error hierarchy with simplified database-specific errors
+ */
+
+import {
+  AppError,
+  createDatabaseError,
+  createValidationError,
+  ErrorCategory,
+  ErrorHandler,
+  ErrorSeverity,
+  DatabaseError as SimplifiedDatabaseError,
+  ValidationError as SimplifiedValidationError,
+} from './simplified-errors.js';
+
+/**
+ * Simplified Database Error with additional database context
+ */
+export class DatabaseError extends SimplifiedDatabaseError {
+  constructor(
+    message: string,
+    operation?: string,
+    cause?: Error,
+    context?: Record<string, unknown>
+  ) {
+    super(message, operation, context?.query as string);
+    this.cause = cause;
+    if (context) {
+      this.context = { ...this.context, ...context };
+    }
+  }
+}
+
+/**
+ * Database-specific validation error
+ */
+export class ValidationError extends SimplifiedValidationError {
+  constructor(message: string, field: string, value?: unknown, cause?: Error) {
+    super(message, field, value);
+    this.cause = cause;
+  }
+}
+
+/**
+ * Database connection error
+ */
+export class ConnectionError extends AppError {
+  constructor(message: string, connectionDetails?: Record<string, unknown>, cause?: Error) {
+    super(
+      message,
+      'CONNECTION_ERROR',
+      ErrorCategory.NETWORK,
+      ErrorSeverity.HIGH,
+      connectionDetails,
+      cause
+    );
+    this.name = 'ConnectionError';
+  }
+}
+
+/**
+ * Database migration error
+ */
+export class MigrationError extends AppError {
+  public readonly migrationName?: string;
+
+  constructor(message: string, migrationName?: string, cause?: Error) {
+    super(
+      message,
+      'MIGRATION_ERROR',
+      ErrorCategory.DATABASE,
+      ErrorSeverity.HIGH,
+      { migrationName },
+      cause
+    );
+    this.migrationName = migrationName;
+    this.name = 'MigrationError';
+  }
+}
+
+/**
+ * Execute database operation with comprehensive error handling
+ */
+export async function executeOperation<T>(
+  operation: string,
+  fn: () => Promise<T>,
+  context?: Record<string, unknown>
+): Promise<T> {
+  const result = await ErrorHandler.execute(fn, { operation, ...context });
+
+  if (result.success) {
+    return result.data;
+  }
+
+  // Convert to appropriate database error type
+  if (result.error instanceof AppError) {
+    throw result.error;
+  }
+
+  // Unknown error - wrap in DatabaseError
+  throw createDatabaseError(result.error.message, operation, context?.query as string);
+}
+
+/**
+ * Type guard functions for database errors
+ */
+export function isDatabaseError(error: unknown): error is DatabaseError {
+  return error instanceof DatabaseError;
+}
+
+export function isValidationError(error: unknown): error is ValidationError {
+  return error instanceof ValidationError;
+}
+
+export function isConnectionError(error: unknown): error is ConnectionError {
+  return error instanceof ConnectionError;
+}
+
+export function isMigrationError(error: unknown): error is MigrationError {
+  return error instanceof MigrationError;
+}
+
+/**
+ * Convenience functions for creating database errors
+ */
+export const createMigrationError = (
+  message: string,
+  migrationName?: string,
+  cause?: Error
+): MigrationError => new MigrationError(message, migrationName, cause);
+
+export const createConnectionError = (
+  message: string,
+  connectionDetails?: Record<string, unknown>,
+  cause?: Error
+): ConnectionError => new ConnectionError(message, connectionDetails, cause);
+
+// Re-export for backward compatibility
+export { createDatabaseError, createValidationError, ErrorHandler, AppError };

package/src/utils/debug-logger.ts

@@ -0,0 +1,49 @@
+/**
+ * Debug Logger
+ * Uses industry-standard 'debug' package
+ *
+ * Usage:
+ *   DEBUG=* bun ./packages/flow/src/index.ts              // All debug logs
+ *   DEBUG=sylphx:* bun ...                                 // All sylphx namespaces
+ *   DEBUG=sylphx:search:* bun ...                          // Search namespace
+ *   (no DEBUG) bun ...                                     // No debug logs
+ *
+ * Examples:
+ *   import { createLogger } from '../utils/debug-logger.js';
+ *
+ *   const log = createLogger('search:indexing');
+ *   log('Indexing started:', filePath);
+ *
+ * Features from 'debug' package:
+ *   - Color-coded namespaces
+ *   - Timestamp support (DEBUG_COLORS=no for no color)
+ *   - Wildcard matching (DEBUG=sylphx:*)
+ *   - Conditional logging (no performance impact when disabled)
+ *   - Industry standard (used by Express, Socket.io, etc.)
+ */
+
+import debug from 'debug';
+
+/**
+ * Create a logger for a specific namespace
+ * Namespace will be prefixed with 'sylphx:'
+ *
+ * @example
+ * const log = createLogger('search:indexing');
+ * log('Indexing started:', filePath);
+ *
+ * // Enable with:
+ * // DEBUG=sylphx:search:indexing bun ./packages/flow/src/index.ts
+ */
+export function createLogger(namespace: string) {
+  return debug(`sylphx:${namespace}`);
+}
+
+/**
+ * For backwards compatibility
+ * @deprecated Use createLogger instead
+ */
+export function debugLog(namespace: string, ...args: any[]) {
+  const log = debug(`sylphx:${namespace}`);
+  log(...args);
+}

package/src/utils/error-handler.ts

@@ -0,0 +1,53 @@
+/**
+ * Legacy error handling utilities
+ * @deprecated Use core/functional/error-handler.ts instead
+ *
+ * MIGRATION PATH:
+ * 1. Replace CLIError with cliError from error-types.ts
+ * 2. Replace handleError with exitWithError from error-handler.ts
+ * 3. Replace createAsyncHandler with createAsyncHandler from error-handler.ts
+ *
+ * Kept for backward compatibility during migration
+ */
+
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public code?: string
+  ) {
+    super(message);
+    this.name = 'CLIError';
+  }
+}
+
+/**
+ * @deprecated Use exitWithError from core/functional/error-handler.ts
+ */
+export function handleError(error: unknown, context?: string): never {
+  const message = error instanceof Error ? error.message : String(error);
+  const contextMsg = context ? ` (${context})` : '';
+
+  console.error(`✗ Error${contextMsg}: ${message}`);
+
+  if (error instanceof CLIError && error.code) {
+    console.error(`   Code: ${error.code}`);
+  }
+
+  process.exit(1);
+}
+
+/**
+ * @deprecated Use createAsyncHandler from core/functional/error-handler.ts
+ */
+export function createAsyncHandler<T extends Record<string, any>>(
+  handler: (options: T) => Promise<void>,
+  context?: string
+) {
+  return async (options: T): Promise<void> => {
+    try {
+      await handler(options);
+    } catch (error) {
+      handleError(error, context);
+    }
+  };
+}