feat: Add filesystem nodes to complement code graph nodes

[rysweet]

Summary

Implements filesystem nodes feature to provide a complementary view of the codebase from a filesystem perspective. This feature creates nodes representing files and directories in the filesystem and connects them to existing code nodes.

Implementation

New Node Types

• FILESYSTEM: Base type for filesystem nodes
• FILESYSTEM_FILE: Represents a file in the filesystem
• FILESYSTEM_DIRECTORY: Represents a directory

New Relationship Types

• IMPLEMENTS: Connects filesystem files to the code nodes they contain
• DEPENDS_ON: For file dependencies (future use)
• FILESYSTEM_CONTAINS: Parent directory -> child file/directory
• REFERENCED_BY_DESCRIPTION: When LLM descriptions mention file paths

Key Components

1. FilesystemFileNode - Node class for files with metadata (size, extension, last_modified)
2. FilesystemDirectoryNode - Node class for directories with child relationships
3. FilesystemGraphGenerator - Traverses filesystem and creates nodes/relationships
4. Integration - Added to ProjectGraphCreator as optional post-processing step

Features

• Filesystem nodes are created after AST/symbol nodes
• IMPLEMENTS relationships connect files to their code contents
• Supports file metadata (size, permissions, timestamps)
• Integrates with LLM descriptions to detect file references
• Respects existing skip patterns for files/directories

Testing

• Created comprehensive test suite covering node creation and relationships
• Manual testing confirms feature works correctly
• Test output shows proper creation of filesystem nodes and IMPLEMENTS relationships

Configuration

Enable via environment variable:

ENABLE_FILESYSTEM_NODES=true

Or programmatically:

graph_builder = GraphBuilder(
    root_path="/path/to/project",
    enable_filesystem_nodes=True
)

Benefits

1. Enhanced Navigation: Navigate from code to file location and vice versa
2. File Organization Insights: Understand how code is organized in the filesystem
3. Dependency Analysis: Foundation for file-level dependency tracking
4. Cross-Reference Support: Connect LLM descriptions to actual files

Example Output

Filesystem Nodes:
  Files: 2
  Directories: 2

Relationships:
  IMPLEMENTS: 6 (connecting filesystem files to code nodes)
  FILESYSTEM_CONTAINS: 6 (directory structure)

Closes #4

🤖 Generated with Claude Code