File System Interface

/**
 * Check if a file exists in the file system
 * @param file - File path to check
 * @returns true if file exists, false otherwise
 */
exists(file: string): boolean;

/**
 * Get all files tracked by the file system
 * @returns Array of all file paths
 */
getAllFiles(): Array<string>;

const { fileSystem } = await fileMap.build();

// Check if specific file exists
if (fileSystem.exists('src/components/Button.js')) {
  console.log('Button component found');
}

// Get all tracked files
const allFiles = fileSystem.getAllFiles();
console.log(`Total files: ${allFiles.length}`);

// Filter by extension
const jsFiles = allFiles.filter(file => file.endsWith('.js'));
const tsFiles = allFiles.filter(file => file.endsWith('.ts'));

/**
 * Get dependencies for a specific file
 * @param file - File path to analyze
 * @returns Array of dependency paths or null if not computed
 */
getDependencies(file: string): Array<string> | null;

/**
 * Get the module name for a file (if it's a Haste module)
 * @param file - File path to check
 * @returns Module name or null if not a named module
 */
getModuleName(file: string): string | null;

/**
 * Get SHA1 hash for a file (if computed)
 * @param file - File path to check
 * @returns SHA1 hash string or null if not computed
 */
getSha1(file: string): string | null;

/**
 * Get serializable snapshot of file system data
 * @returns Serializable file system data for caching
 */
getSerializableSnapshot(): unknown;

/**
 * Get difference between current state and provided files
 * @param files - File data to compare against
 * @returns Object with changed and removed files
 */
getDifference(files: FileData): {
  changedFiles: FileData;
  removedFiles: Set<string>;
};

// Analyze file dependencies
const deps = fileSystem.getDependencies('src/App.js');
if (deps) {
  console.log('Dependencies:', deps);
  // Example output: ['./components/Header', 'react', 'lodash']
}

// Check if file is a named module
const moduleName = fileSystem.getModuleName('src/components/Button.js');
if (moduleName) {
  console.log(`Module name: ${moduleName}`);
  // Example output: "Button"
}

// Get file hash for cache validation
const hash = fileSystem.getSha1('package.json');
if (hash) {
  console.log(`File hash: ${hash}`);
}

/**
 * Match files with filtering options
 * @param opts - Matching options
 * @returns Iterable of matching file paths
 */
matchFiles(opts: MatchFilesOptions): Iterable<string>;

interface MatchFilesOptions {
  /** Filter relative paths against a pattern */
  filter?: RegExp | null;
  /** Apply filter against absolute paths vs rootDir-relative (default: false) */
  filterCompareAbsolute?: boolean;
  /** Apply filter against posix-delimited paths, even on Windows (default: false) */
  filterComparePosix?: boolean;
  /** Follow symlinks when enumerating paths (default: false) */
  follow?: boolean;
  /** Search for files recursively (default: true) */
  recursive?: boolean;
  /** Match files under a given root, or null for all files */
  rootDir?: string | null;
}

// Find all JavaScript files
const jsFiles = Array.from(fileSystem.matchFiles({
  filter: /\.js$/,
  recursive: true
}));

// Find files in specific directory
const componentFiles = Array.from(fileSystem.matchFiles({
  rootDir: 'src/components',
  filter: /\.(js|ts)x?$/
}));

// Find test files
const testFiles = Array.from(fileSystem.matchFiles({
  filter: /\.(test|spec)\.(js|ts)$/,
  recursive: true
}));

console.log(`Found ${testFiles.length} test files`);

/**
 * Look up path information, following symlinks
 * @param mixedPath - Path to look up
 * @returns Lookup result with existence and metadata
 */
lookup(mixedPath: string): LookupResult;

/**
 * Perform hierarchical lookup for finding closest matches
 * @param mixedStartPath - Starting path for search
 * @param subpath - Subpath to search for
 * @param opts - Lookup options
 * @returns Match result or null if not found
 */
hierarchicalLookup(
  mixedStartPath: string,
  subpath: string,
  opts: {
    breakOnSegment?: string;
    invalidatedBy?: Set<string>;
    subpathType: 'f' | 'd';
  }
): {
  absolutePath: string;
  containerRelativePath: string;
} | null;

// Look up file information
const lookupResult = fileSystem.lookup('src/components/Button.js');
if (lookupResult.exists) {
  console.log('Real path:', lookupResult.realPath);
  console.log('Type:', lookupResult.type); // 'f' for file, 'd' for directory
  console.log('Symlinks traversed:', lookupResult.links);
} else {
  console.log('Missing path:', lookupResult.missing);
}

// Find closest package.json
const packageResult = fileSystem.hierarchicalLookup(
  'src/components/Button.js',
  'package.json',
  { subpathType: 'f', breakOnSegment: 'node_modules' }
);

if (packageResult) {
  console.log('Closest package.json:', packageResult.absolutePath);
  console.log('Relative container:', packageResult.containerRelativePath);
}

// Find node_modules directory
const nodeModulesResult = fileSystem.hierarchicalLookup(
  'src/components/Button.js',
  'node_modules',
  { subpathType: 'd' }
);

/**
 * Get link statistics for a file (without following symlinks)
 * @param file - File path to check
 * @returns File statistics or null if not found
 */
linkStats(file: string): FileStats | null;

interface FileStats {
  fileType: 'f' | 'l'; // File or Link
  modifiedTime: number | null;
  size: number | null;
}

// Get file statistics
const stats = fileSystem.linkStats('src/index.js');
if (stats) {
  console.log('File type:', stats.fileType);
  console.log('Modified:', new Date(stats.modifiedTime));
  console.log('Size:', stats.size, 'bytes');
}

// Check if file is a symlink
if (stats && stats.fileType === 'l') {
  console.log('File is a symbolic link');
}

/**
 * Get or compute SHA1 hash for a file
 * @param file - File path to process
 * @returns Promise resolving to hash result or null
 */
getOrComputeSha1(file: string): Promise<{
  sha1: string;
  content?: Buffer;
} | null>;

// Compute SHA1 with content
const result = await fileSystem.getOrComputeSha1('src/config.json');
if (result) {
  console.log('SHA1:', result.sha1);
  if (result.content) {
    const config = JSON.parse(result.content.toString());
    console.log('Config loaded:', config);
  }
}

// Batch process files
const files = ['package.json', 'tsconfig.json', 'babel.config.js'];
const hashes = await Promise.all(
  files.map(async file => {
    const result = await fileSystem.getOrComputeSha1(file);
    return { file, hash: result?.sha1 };
  })
);

console.log('File hashes:', hashes);

type LookupResult = 
  | {
      exists: false;
      /** Real, normal, absolute paths of any symlinks traversed */
      links: ReadonlySet<string>;
      /** Real, normal, absolute path of first missing segment */
      missing: string;
    }
  | {
      exists: true;
      /** Real, normal, absolute paths of any symlinks traversed */
      links: ReadonlySet<string>;
      /** Real, normal, absolute path of the file or directory */
      realPath: string;
      /** Type: directory or regular file */
      type: 'd' | 'f';
    };

interface FileStats {
  fileType: 'f' | 'l';
  modifiedTime: number | null;
  size: number | null;
}

type FileData = Map<string, FileMetadata>;

interface FileDifference {
  changedFiles: FileData;
  removedFiles: Set<string>;
}