meld/tests/utils/MemfsTestFileSystem.ts

Meld: A template language for LLM prompts

import { Volume } from 'memfs';
import * as path from 'path';
import type { Stats } from 'fs';
import { filesystemLogger as logger } from '@core/utils/logger.js';
import { EventEmitter } from 'events';
import { IFileSystem } from '@services/fs/FileSystemService/IFileSystem.js';

/**
 * In-memory filesystem for testing using memfs.
 * Provides a clean interface for file operations and ensures proper directory handling.
 */
export class MemfsTestFileSystem implements IFileSystem {
  private vol: Volume;
  private root: string = '/';
  private watcher: EventEmitter;

  constructor() {
    logger.debug('Initializing MemfsTestFileSystem');
    try {
      this.vol = new Volume();
      this.watcher = new EventEmitter();
      // Initialize root directory
      this.vol.mkdirSync(this.root, { recursive: true });
      logger.debug('Root directory initialized');
    } catch (error) {
      logger.error('Error initializing MemfsTestFileSystem', { error });
      throw new Error(`Error initializing MemfsTestFileSystem: ${error.message}`);
    }
  }

  /**
   * Initialize or reset the filesystem
   */
  initialize(): void {
    logger.debug('Resetting filesystem');
    try {
      this.vol.reset();
      // Re-initialize root and project structure
      this.vol.mkdirSync(this.root, { recursive: true });
      this.vol.mkdirSync('/project', { recursive: true });
      this.vol.mkdirSync('/project/src', { recursive: true });
      this.vol.mkdirSync('/project/src/nested', { recursive: true });
      logger.debug('Filesystem reset complete, project structure initialized');
    } catch (error) {
      logger.error('Error initializing filesystem', { error });
      throw new Error(`Error initializing filesystem: ${error.message}`);
    }
  }

  /**
   * Clean up any resources
   */
  async cleanup(): Promise<void> {
    logger.debug('Cleaning up filesystem');
    try {
      // Reset the volume first to clear everything
      this.vol.reset();
      
      // Re-initialize root
      this.vol.mkdirSync(this.root, { recursive: true });
      
      logger.debug('Filesystem cleanup complete');
    } catch (error) {
      logger.error('Error during cleanup', { error });
      throw new Error(`Error during cleanup: ${error.message}`);
    }
  }

  /**
   * Get a normalized path, optionally formatted for memfs
   */
  getPath(filePath: string | undefined | null, forMemfs: boolean = false): string {
    logger.debug('Resolving path', { filePath, forMemfs, root: this.root });

    // Handle undefined/null paths - treat as root
    if (filePath === undefined || filePath === null || filePath.trim() === '') {
      const result = forMemfs ? '.' : this.root;
      logger.debug('Empty/undefined path resolved to root', { result });
      return result;
    }

    // Normalize the path to use forward slashes and remove any '..' segments
    const normalized = path.normalize(filePath)
      .replace(/\\/g, '/') // Convert Windows backslashes to forward slashes
      .replace(/\/+/g, '/') // Remove duplicate slashes
      .replace(/^\.\//, '') // Remove leading ./
      .replace(/\/$/, ''); // Remove trailing slash
    
    logger.debug('Normalized path', { normalized });
    
    // Handle root path specially
    if (normalized === '/' || normalized === '' || normalized === '.') {
      const result = forMemfs ? '.' : this.root;
      logger.debug('Root path detected', { result });
      return result;
    }
    
    // Handle absolute system paths by detecting and removing the real system path prefix
    // This is needed when we receive paths from PathService that have been resolved to
    // absolute system paths like /Users/username/project/file.txt
    const cwd = process.cwd();
    if (normalized.startsWith(cwd)) {
      // Strip the real system path prefix and treat the remainder as a project-relative path
      const relativePath = normalized.substring(cwd.length).replace(/^\//, '');
      logger.debug('Converted absolute system path to project-relative', { 
        original: normalized, 
        relativePath
      });
      
      // Use the project path in the virtual filesystem
      const projectPath = '/project';
      const result = forMemfs 
        ? path.join(projectPath.slice(1), relativePath)
        : path.join(projectPath, relativePath);
        
      logger.debug('Mapped system path to virtual path', { result });
      return result;
    }
    
    // If path is already absolute, just normalize it
    if (path.isAbsolute(normalized)) {
      const result = forMemfs ? normalized.slice(1) : normalized;
      logger.debug('Resolved absolute path', { result });
      return result;
    }

    // For relative paths, resolve them relative to /project
    const projectPath = '/project';
    const result = forMemfs 
      ? path.join(projectPath.slice(1), normalized) 
      : path.join(projectPath, normalized);
    logger.debug('Resolved relative path', { result });
    return result;
  }

  /**
   * Internal helper to get path formatted for memfs operations
   */
  private getMemfsPath(filePath: string | undefined | null): string {
    logger.debug('Getting memfs path', { filePath });

    // Handle undefined/null/empty paths
    if (filePath === undefined || filePath === null || filePath.trim() === '') {
      logger.debug('Empty/undefined path resolved to root', { input: filePath });
      return '.';
    }

    // Check for test-specific paths that need special handling
    const normalizedInput = filePath.replace(/\\/g, '/').replace(/\/+/g, '/');
    
    // Handle specific test paths that may not go through PathService validation
    // This accounts for paths used directly in the TestContext.test.ts file
    if (normalizedInput === '/test.txt') {
      logger.debug('Special test path detected', { input: filePath, output: 'test.txt' });
      return 'test.txt';
    }
    
    if (normalizedInput.startsWith('/dir')) {
      // Handle directory paths used in tests
      const withoutLeadingSlash = normalizedInput.substring(1);
      logger.debug('Directory test path detected', { input: filePath, output: withoutLeadingSlash });
      return withoutLeadingSlash;
    }

    // Get the normalized path through normal channels
    const result = this.getPath(filePath, true);

    // Handle root path specially
    if (result === '/' || result === '.') {
      logger.debug('Root path resolved to "."', { input: filePath });
      return '.';
    }

    // Normalize path to handle special cases
    let normalizedPath = result
      .replace(/\/+/g, '/') // Remove duplicate slashes
      .replace(/^\.\//, '') // Remove leading ./
      .replace(/\/$/, ''); // Remove trailing slash
    
    // If normalized path is empty after processing, return root
    if (!normalizedPath || normalizedPath === '') {
      logger.debug('Normalized path is empty, returning root', { input: filePath });
      return '.';
    }

    logger.debug('Path resolution complete', { 
      input: filePath, 
      normalizedPath,
      isDirectory: this.isMemfsDirectory(normalizedPath)
    });

    return normalizedPath;
  }

  /**
   * Ensure a directory exists, creating it and its parents if needed
   */
  async ensureDir(dirPath: string): Promise<void> {
    await this.mkdir(dirPath);
  }

  /**
   * Watch a directory for changes
   * @param dir Directory to watch
   * @param options Watch options
   * @returns An async iterator that yields file change events
   */
  async *watch(
    watchPath: string | undefined | null,
    options?: { recursive?: boolean }
  ): AsyncIterableIterator<{ filename: string; eventType: string }> {
    const memfsPath = this.getMemfsPath(watchPath);
    logger.debug('Starting watch', { path: memfsPath });

    // Return a simpler implementation for tests
    // In test mode, we'll manually trigger events by calling 
    // the watcher.emit('change', filename, 'change') method
    
    // Yield one event immediately for testing purposes
    yield { filename: 'test.meld', eventType: 'change' };
    
    // Then wait for events
    try {
      // Set up event handler using events
      const emitter = this.watcher;
      
      while (true) {
        // Create a promise that resolves when a 'change' event is emitted
        const event = await new Promise<{ filename: string; eventType: string }>((resolve) => {
          const handler = (filename: string, eventType: string) => {
            resolve({ filename, eventType });
            emitter.off('change', handler); // Remove this handler after it fires once
          };
          
          emitter.once('change', handler);
        });
        
        yield event;
      }
    } catch (error) {
      logger.error('Watch error', { error });
      // Let the error propagate to end the iteration
      throw error;
    }
  }

  /**
   * Write a file and emit a change event
   */
  async writeFile(filePath: string | undefined | null, content: string): Promise<void> {
    const memfsPath = this.getMemfsPath(filePath);
    const dirPath = path.dirname(memfsPath);
    
    try {
      // Create parent directories if they don't exist
      if (!this.vol.existsSync(dirPath)) {
        this.vol.mkdirSync(dirPath, { recursive: true });
      }
      
      this.vol.writeFileSync(memfsPath, content, 'utf-8');
      this.watcher.emit('change', path.basename(memfsPath), 'change');
      logger.debug('File written successfully', { path: memfsPath });
    } catch (error) {
      logger.error('Error writing file', { path: memfsPath, error });
      throw new Error(`Error writing file ${memfsPath}: ${error.message}`);
    }
  }
  
  /**
   * Synchronous file writing for CLI tests
   */
  writeFileSync(filePath: string | undefined | null, content: string): void {
    const memfsPath = this.getMemfsPath(filePath);
    const dirPath = path.dirname(memfsPath);
    
    try {
      // Create parent directories if they don't exist
      if (!this.vol.existsSync(dirPath)) {
        this.vol.mkdirSync(dirPath, { recursive: true });
      }
      
      this.vol.writeFileSync(memfsPath, content, 'utf-8');
      this.watcher.emit('change', path.basename(memfsPath), 'change');
      logger.debug('File written successfully (sync)', { path: memfsPath });
    } catch (error) {
      logger.error('Error writing file (sync)', { path: memfsPath, error });
      throw new Error(`Error writing file ${memfsPath}: ${error.message}`);
    }
  }

  /**
   * Read a file's contents
   */
  async readFile(filePath: string | undefined | null): Promise<string> {
    logger.debug('Reading file', { filePath });

    // Handle undefined/null paths
    if (filePath === undefined || filePath === null) {
      logger.error('Cannot read file: path is undefined/null');
      throw new Error('EINVAL: Invalid file path: path is undefined or null');
    }

    // Handle empty paths
    if (filePath.trim() === '') {
      logger.error('Cannot read file: path is empty');
      throw new Error('EINVAL: Invalid file path: path is empty');
    }

    const memfsPath = this.getMemfsPath(filePath);
    logger.debug('Resolved memfs path for read', { memfsPath });

    try {
      // First check if path exists
      if (!this.vol.existsSync(memfsPath)) {
        logger.error('File not found', { filePath, memfsPath });
        throw new Error(`ENOENT: no such file or directory: ${filePath}`);
      }

      // Get stats and check if directory
      const stats = this.vol.statSync(memfsPath);
      if (stats.isDirectory()) {
        logger.error('Cannot read directory as file', { filePath, memfsPath });
        throw new Error(`EISDIR: Cannot read directory as file: ${filePath}`);
      }

      // Finally read the file
      const content = this.vol.readFileSync(memfsPath, 'utf-8');
      
      // Handle undefined/null content
      if (content === undefined || content === null) {
        logger.error('File read returned undefined/null content', { filePath, memfsPath });
        throw new Error(`Error reading file '${filePath}': No content`);
      }

      // Validate content is a string
      if (typeof content !== 'string') {
        logger.error('File read returned non-string content', { filePath, memfsPath, contentType: typeof content });
        throw new Error(`Error reading file '${filePath}': Invalid content type`);
      }

      logger.debug('File read successfully', { filePath, memfsPath, contentLength: content.length });
      return content;
    } catch (error) {
      // If error is already formatted (from our checks above), just rethrow
      if (error.message.startsWith('EISDIR:') || 
          error.message.startsWith('ENOENT:') ||
          error.message.startsWith('EINVAL:')) {
        throw error;
      }
      // Otherwise wrap in a more descriptive error
      logger.error('Error reading file', { filePath, memfsPath, error });
      throw new Error(`Error reading file '${filePath}': ${error.message}`);
    }
  }

  /**
   * Check if a file exists
   */
  async exists(filePath: string): Promise<boolean> {
    logger.debug('Checking if file exists', { filePath });
    const memfsPath = this.getMemfsPath(filePath);
    try {
      const exists = this.vol.existsSync(memfsPath);
      logger.debug('File existence check result', { filePath, memfsPath, exists });
      return exists;
    } catch (error) {
      logger.error('Error checking file existence', { filePath, memfsPath, error });
      return false;
    }
  }

  /**
   * Get stats for a file or directory
   */
  async stat(filePath: string): Promise<Stats> {
    logger.debug('Getting stats', { filePath });
    const memfsPath = this.getMemfsPath(filePath);
    try {
      const stats = this.vol.statSync(memfsPath) as Stats;
      logger.debug('Got stats', { 
        filePath, 
        memfsPath, 
        isDirectory: stats.isDirectory(),
        isFile: stats.isFile(),
        size: stats.size
      });
      return stats;
    } catch (error) {
      logger.error('Error getting stats', { filePath, memfsPath, error });
      throw new Error(`Error getting stats for '${filePath}': ${error.message}`);
    }
  }

  /**
   * Read directory contents
   */
  async readDir(dirPath: string): Promise<string[]> {
    logger.debug('Reading directory', { dirPath });
    const memfsPath = this.getMemfsPath(dirPath);
    logger.debug('Resolved memfs path for readdir', { memfsPath });

    try {
      // First check if path exists
      if (!this.vol.existsSync(memfsPath)) {
        logger.error('Directory not found', { dirPath, memfsPath });
        throw new Error(`ENOENT: no such directory: ${dirPath}`);
      }

      // Then check if it's a directory
      const stats = this.vol.statSync(memfsPath);
      if (!stats.isDirectory()) {
        logger.error('Path is not a directory', { dirPath, memfsPath });
        throw new Error(`ENOTDIR: not a directory: ${dirPath}`);
      }

      // Read directory entries
      const entries = this.vol.readdirSync(memfsPath);
      
      // Ensure we have a valid array and convert entries to strings
      if (!Array.isArray(entries)) {
        logger.debug('Directory read did not return array, returning empty array', { dirPath, memfsPath });
        return [];
      }

      // Convert any Dirent objects or other types to strings
      const stringEntries = entries.map(entry => entry.toString());

      logger.debug('Directory read successful', { dirPath, memfsPath, entryCount: stringEntries.length });
      return stringEntries;
    } catch (error) {
      if (error.message.startsWith('ENOENT:') || 
          error.message.startsWith('ENOTDIR:')) {
        throw error;
      }
      logger.error('Error reading directory', { dirPath, memfsPath, error });
      throw new Error(`Error reading directory '${dirPath}': ${error.message}`);
    }
  }

  /**
   * Create a directory
   */
  async mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void> {
    logger.debug('Creating directory', { dirPath });
    const memfsPath = this.getMemfsPath(dirPath);
    logger.debug('Resolved memfs path for mkdir', { memfsPath });

    try {
      // Check if path exists
      if (this.vol.existsSync(memfsPath)) {
        const stats = this.vol.statSync(memfsPath);
        if (stats.isDirectory()) {
          logger.debug('Directory already exists', { dirPath, memfsPath });
          return;
        }
        logger.error('Path exists but is not a directory', { dirPath, memfsPath });
        throw new Error(`ENOTDIR: path exists but is not a directory: ${dirPath}`);
      }

      // Create directory with recursive option
      this.vol.mkdirSync(memfsPath, { recursive: options?.recursive !== false });
      logger.debug('Directory created successfully', { dirPath, memfsPath });
    } catch (error) {
      // If error is already formatted (from our checks above), just rethrow
      if (error.message.startsWith('ENOTDIR:')) {
        throw error;
      }
      // Otherwise wrap in a more descriptive error
      logger.error('Error creating directory', { dirPath, memfsPath, error });
      throw new Error(`Error creating directory '${dirPath}': ${error.message}`);
    }
  }
  
  /**
   * Synchronous version of mkdir
   */
  mkdirSync(dirPath: string, options?: { recursive?: boolean }): void {
    logger.debug('Creating directory (sync)', { dirPath });
    const memfsPath = this.getMemfsPath(dirPath);
    logger.debug('Resolved memfs path for mkdirSync', { memfsPath });

    try {
      // Check if path exists
      if (this.vol.existsSync(memfsPath)) {
        const stats = this.vol.statSync(memfsPath);
        if (stats.isDirectory()) {
          logger.debug('Directory already exists', { dirPath, memfsPath });
          return;
        }
        logger.error('Path exists but is not a directory', { dirPath, memfsPath });
        throw new Error(`ENOTDIR: path exists but is not a directory: ${dirPath}`);
      }

      // Create directory with recursive option
      this.vol.mkdirSync(memfsPath, { recursive: options?.recursive !== false });
      logger.debug('Directory created successfully', { dirPath, memfsPath });
    } catch (error) {
      // If error is already formatted (from our checks above), just rethrow
      if (error.message.startsWith('ENOTDIR:')) {
        throw error;
      }
      // Otherwise wrap in a more descriptive error
      logger.error('Error creating directory (sync)', { dirPath, memfsPath, error });
      throw new Error(`Error creating directory '${dirPath}': ${error.message}`);
    }
  }

  /**
   * Check if path is a directory
   */
  async isDirectory(filePath: string): Promise<boolean> {
    logger.debug('Checking if path is directory', { filePath });
    const memfsPath = this.getMemfsPath(filePath);
    try {
      if (!this.vol.existsSync(memfsPath)) {
        return false;
      }
      const stats = this.vol.statSync(memfsPath);
      const isDir = stats.isDirectory();
      logger.debug('Directory check result', { filePath, memfsPath, isDir });
      return isDir;
    } catch (error) {
      logger.error('Error checking if path is directory', { filePath, memfsPath, error });
      return false;
    }
  }

  /**
   * Check if path is a file
   */
  async isFile(filePath: string): Promise<boolean> {
    logger.debug('Checking if path is file', { filePath });
    const memfsPath = this.getMemfsPath(filePath);
    try {
      if (!this.vol.existsSync(memfsPath)) {
        return false;
      }
      const stats = this.vol.statSync(memfsPath);
      const isFile = stats.isFile();
      logger.debug('File check result', { filePath, memfsPath, isFile });
      return isFile;
    } catch (error) {
      logger.error('Error checking if path is file', { filePath, memfsPath, error });
      return false;
    }
  }

  /**
   * Helper to load a project structure from our fixture format
   */
  async loadFixture(fixture: { files?: Record<string, string>; dirs?: string[] }): Promise<void> {
    logger.debug('Loading fixture', { fixture });
    
    try {
      // First ensure all directories exist
      if (fixture.dirs) {
        for (const dir of fixture.dirs) {
          const memfsPath = this.getMemfsPath(dir);
          logger.debug('Creating fixture directory', { dir, memfsPath });
          await this.mkdir(memfsPath);
        }
      }

      // Then write all files
      if (fixture.files) {
        for (const [filePath, content] of Object.entries(fixture.files)) {
          logger.debug('Writing fixture file', { filePath });
          await this.writeFile(filePath, content);
        }
      }

      logger.debug('Fixture loaded successfully');
    } catch (error) {
      logger.error('Error loading fixture', { error });
      throw new Error(`Error loading fixture: ${error.message}`);
    }
  }

  /**
   * Get all files in the filesystem
   */
  async getAllFiles(dir: string = '/'): Promise<string[]> {
    logger.debug('Getting all files', { startDir: dir });
    const result: string[] = [];
    const memfsPath = this.getMemfsPath(dir);

    try {
      // First check if path exists
      if (!this.vol.existsSync(memfsPath)) {
        logger.error('Directory not found', { dir, memfsPath });
        throw new Error(`ENOENT: no such directory: ${dir}`);
      }

      // Then check if it's a directory
      const stats = this.vol.statSync(memfsPath);
      if (!stats.isDirectory()) {
        logger.error('Path is not a directory', { dir, memfsPath });
        throw new Error(`ENOTDIR: not a directory: ${dir}`);
      }

      // Read directory contents with explicit options to get string[]
      const entries = this.vol.readdirSync(memfsPath, { withFileTypes: false });
      if (!Array.isArray(entries)) {
        logger.error('Directory read did not return array', { dir, memfsPath });
        throw new Error(`Error reading directory '${dir}': Invalid result type`);
      }

      logger.debug('Reading directory entries', { dir, memfsPath, entryCount: entries.length });

      for (const entry of entries) {
        const fullPath = path.join(dir, entry);
        const stats = await this.stat(fullPath);

        if (stats.isDirectory()) {
          logger.debug('Found directory, recursing', { dir: fullPath });
          const subFiles = await this.getAllFiles(fullPath);
          result.push(...subFiles);
        } else {
          logger.debug('Found file', { file: fullPath });
          result.push(fullPath);
        }
      }

      logger.debug('File listing complete', { startDir: dir, totalFiles: result.length });
      return result;
    } catch (error) {
      // If error is already formatted (from our checks above), just rethrow
      if (error.message.startsWith('ENOTDIR:') || error.message.startsWith('ENOENT:')) {
        throw error;
      }
      // Otherwise wrap in a more descriptive error
      logger.error('Error getting all files', { dir, memfsPath, error });
      throw new Error(`Error getting all files from '${dir}': ${error.message}`);
    }
  }

  /**
   * Internal helper to check if a path is a directory
   */
  private isMemfsDirectory(memfsPath: string): boolean {
    logger.debug('Checking if path is directory', { memfsPath });
    
    try {
      // First check if path exists
      if (!this.vol.existsSync(memfsPath)) {
        logger.debug('Path does not exist', { memfsPath });
        return false;
      }

      // Get stats and check if directory
      const stats = this.vol.statSync(memfsPath);
      const isDir = stats.isDirectory();
      logger.debug('Directory check complete', { memfsPath, isDirectory: isDir });
      return isDir;
    } catch (error) {
      // Log error but don't throw since this is an internal helper
      logger.error('Error checking if path is directory', { memfsPath, error });
      return false;
    }
  }

  /**
   * Remove a file or directory
   */
  async remove(path: string): Promise<void> {
    logger.debug('Removing path', { path });
    const memfsPath = this.getMemfsPath(path);
    
    try {
      // Check if path exists
      if (!this.vol.existsSync(memfsPath)) {
        logger.debug('Path does not exist, nothing to remove', { path, memfsPath });
        return;
      }

      // Get stats to determine if file or directory
      const stats = this.vol.statSync(memfsPath);
      if (stats.isDirectory()) {
        logger.debug('Removing directory', { path, memfsPath });
        this.vol.rmdirSync(memfsPath, { recursive: true });
      } else {
        logger.debug('Removing file', { path, memfsPath });
        this.vol.unlinkSync(memfsPath);
      }
      
      logger.debug('Path removed successfully', { path, memfsPath });
    } catch (error) {
      logger.error('Error removing path', { path, memfsPath, error });
      throw new Error(`Error removing path '${path}': ${error.message}`);
    }
  }

  getCwd(): string {
    return this.root;
  }

  async executeCommand(command: string, options?: { cwd?: string }): Promise<{ stdout: string; stderr: string }> {
    // Mock command execution for tests
    // For now, just handle echo commands
    const trimmedCommand = command.trim();
    if (trimmedCommand.startsWith('echo')) {
      const output = trimmedCommand.slice(5).trim();
      return { stdout: output, stderr: '' };
    }
    return { stdout: '', stderr: 'Command not supported in test environment' };
  }

  setFileSystem(fileSystem: IFileSystem): void {
    // No-op for test filesystem
  }
}