0
# File System Interface
1

2
Virtual file system abstraction providing querying, lookup, and metadata operations on the crawled file tree. The FileSystem interface is the primary way to interact with discovered files and their relationships.
3

4
## Capabilities
5

6
### File Existence and Enumeration
7

8
Check file existence and enumerate all tracked files.
9

10
```javascript { .api }
11
/**
12
 * Check if a file exists in the file system
13
 * @param file - File path to check
14
 * @returns true if file exists, false otherwise
15
 */
16
exists(file: string): boolean;
17

18
/**
19
 * Get all files tracked by the file system
20
 * @returns Array of all file paths
21
 */
22
getAllFiles(): Array<string>;
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
const { fileSystem } = await fileMap.build();
29

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

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

39
// Filter by extension
40
const jsFiles = allFiles.filter(file => file.endsWith('.js'));
41
const tsFiles = allFiles.filter(file => file.endsWith('.ts'));
42
```
43

44
### Dependency Analysis
45

46
Retrieve file dependencies and module names.
47

48
```javascript { .api }
49
/**
50
 * Get dependencies for a specific file
51
 * @param file - File path to analyze
52
 * @returns Array of dependency paths or null if not computed
53
 */
54
getDependencies(file: string): Array<string> | null;
55

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

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

70
/**
71
 * Get serializable snapshot of file system data
72
 * @returns Serializable file system data for caching
73
 */
74
getSerializableSnapshot(): unknown;
75

76
/**
77
 * Get difference between current state and provided files
78
 * @param files - File data to compare against
79
 * @returns Object with changed and removed files
80
 */
81
getDifference(files: FileData): {
82
  changedFiles: FileData;
83
  removedFiles: Set<string>;
84
};
85
```
86

87
**Usage Examples:**
88

89
```javascript
90
// Analyze file dependencies
91
const deps = fileSystem.getDependencies('src/App.js');
92
if (deps) {
93
  console.log('Dependencies:', deps);
94
  // Example output: ['./components/Header', 'react', 'lodash']
95
}
96

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

104
// Get file hash for cache validation
105
const hash = fileSystem.getSha1('package.json');
106
if (hash) {
107
  console.log(`File hash: ${hash}`);
108
}
109
```
110

111
### File Matching and Filtering
112

113
Match files based on various criteria and patterns.
114

115
```javascript { .api }
116
/**
117
 * Match files with filtering options
118
 * @param opts - Matching options
119
 * @returns Iterable of matching file paths
120
 */
121
matchFiles(opts: MatchFilesOptions): Iterable<string>;
122

123
interface MatchFilesOptions {
124
  /** Filter relative paths against a pattern */
125
  filter?: RegExp | null;
126
  /** Apply filter against absolute paths vs rootDir-relative (default: false) */
127
  filterCompareAbsolute?: boolean;
128
  /** Apply filter against posix-delimited paths, even on Windows (default: false) */
129
  filterComparePosix?: boolean;
130
  /** Follow symlinks when enumerating paths (default: false) */
131
  follow?: boolean;
132
  /** Search for files recursively (default: true) */
133
  recursive?: boolean;
134
  /** Match files under a given root, or null for all files */
135
  rootDir?: string | null;
136
}
137
```
138

139
**Usage Examples:**
140

141
```javascript
142
// Find all JavaScript files
143
const jsFiles = Array.from(fileSystem.matchFiles({
144
  filter: /\.js$/,
145
  recursive: true
146
}));
147

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

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

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

163
### Path Lookup and Resolution
164

165
Look up path information and perform hierarchical searches.
166

167
```javascript { .api }
168
/**
169
 * Look up path information, following symlinks
170
 * @param mixedPath - Path to look up
171
 * @returns Lookup result with existence and metadata
172
 */
173
lookup(mixedPath: string): LookupResult;
174

175
/**
176
 * Perform hierarchical lookup for finding closest matches
177
 * @param mixedStartPath - Starting path for search
178
 * @param subpath - Subpath to search for
179
 * @param opts - Lookup options
180
 * @returns Match result or null if not found
181
 */
182
hierarchicalLookup(
183
  mixedStartPath: string,
184
  subpath: string,
185
  opts: {
186
    breakOnSegment?: string;
187
    invalidatedBy?: Set<string>;
188
    subpathType: 'f' | 'd';
189
  }
190
): {
191
  absolutePath: string;
192
  containerRelativePath: string;
193
} | null;
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
// Look up file information
200
const lookupResult = fileSystem.lookup('src/components/Button.js');
201
if (lookupResult.exists) {
202
  console.log('Real path:', lookupResult.realPath);
203
  console.log('Type:', lookupResult.type); // 'f' for file, 'd' for directory
204
  console.log('Symlinks traversed:', lookupResult.links);
205
} else {
206
  console.log('Missing path:', lookupResult.missing);
207
}
208

209
// Find closest package.json
210
const packageResult = fileSystem.hierarchicalLookup(
211
  'src/components/Button.js',
212
  'package.json',
213
  { subpathType: 'f', breakOnSegment: 'node_modules' }
214
);
215

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

221
// Find node_modules directory
222
const nodeModulesResult = fileSystem.hierarchicalLookup(
223
  'src/components/Button.js',
224
  'node_modules',
225
  { subpathType: 'd' }
226
);
227
```
228

229
### File Statistics and Metadata
230

231
Get detailed file statistics and metadata.
232

233
```javascript { .api }
234
/**
235
 * Get link statistics for a file (without following symlinks)
236
 * @param file - File path to check
237
 * @returns File statistics or null if not found
238
 */
239
linkStats(file: string): FileStats | null;
240

241
interface FileStats {
242
  fileType: 'f' | 'l'; // File or Link
243
  modifiedTime: number | null;
244
  size: number | null;
245
}
246
```
247

248
**Usage Examples:**
249

250
```javascript
251
// Get file statistics
252
const stats = fileSystem.linkStats('src/index.js');
253
if (stats) {
254
  console.log('File type:', stats.fileType);
255
  console.log('Modified:', new Date(stats.modifiedTime));
256
  console.log('Size:', stats.size, 'bytes');
257
}
258

259
// Check if file is a symlink
260
if (stats && stats.fileType === 'l') {
261
  console.log('File is a symbolic link');
262
}
263
```
264

265
### Async Content Operations
266

267
Asynchronously compute SHA1 hashes with optional content retrieval.
268

269
```javascript { .api }
270
/**
271
 * Get or compute SHA1 hash for a file
272
 * @param file - File path to process
273
 * @returns Promise resolving to hash result or null
274
 */
275
getOrComputeSha1(file: string): Promise<{
276
  sha1: string;
277
  content?: Buffer;
278
} | null>;
279
```
280

281
**Usage Examples:**
282

283
```javascript
284
// Compute SHA1 with content
285
const result = await fileSystem.getOrComputeSha1('src/config.json');
286
if (result) {
287
  console.log('SHA1:', result.sha1);
288
  if (result.content) {
289
    const config = JSON.parse(result.content.toString());
290
    console.log('Config loaded:', config);
291
  }
292
}
293

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

303
console.log('File hashes:', hashes);
304
```
305

306
## Types
307

308
```javascript { .api }
309
type LookupResult = 
310
  | {
311
      exists: false;
312
      /** Real, normal, absolute paths of any symlinks traversed */
313
      links: ReadonlySet<string>;
314
      /** Real, normal, absolute path of first missing segment */
315
      missing: string;
316
    }
317
  | {
318
      exists: true;
319
      /** Real, normal, absolute paths of any symlinks traversed */
320
      links: ReadonlySet<string>;
321
      /** Real, normal, absolute path of the file or directory */
322
      realPath: string;
323
      /** Type: directory or regular file */
324
      type: 'd' | 'f';
325
    };
326

327
interface FileStats {
328
  fileType: 'f' | 'l';
329
  modifiedTime: number | null;
330
  size: number | null;
331
}
332

333
type FileData = Map<string, FileMetadata>;
334

335
interface FileDifference {
336
  changedFiles: FileData;
337
  removedFiles: Set<string>;
338
}
339
```