Getting Started Architecture Overview - hiraishikentaro/rails-factorybot-jump GitHub Wiki

Getting Started: Architecture Overview

High-Level System Design

Rails FactoryBot Jump follows a provider-based architecture pattern typical of VSCode extensions, with specialized components for factory detection and navigation.

graph TB
    A[VSCode Ruby File] --> B[Extension Activation]
    B --> C[FactoryLinkProvider Registration]
    C --> D[File System Watcher]
    C --> E[Factory Cache Initialization]

    F[User Hovers Over Factory Call] --> G[Document Link Provider]
    G --> H[Factory Detection Regex]
    H --> I[Cache Lookup]
    I --> J[Generate Clickable Link]

    K[Factory File Changes] --> D
    D --> L[Cache Refresh]
    L --> E

    M[User Clicks Link] --> N[VSCode Command]
    N --> O[Jump to Definition]

Core Components

1. Extension Entry Point

File: src/extension.ts

The main extension orchestrates the entire system:

  • Activation: Triggers on Ruby language files
  • Provider Registration: Registers the document link provider for Ruby files
  • Command Registration: Sets up the jump-to-line command
  • File Watching: Monitors factory file changes for cache updates
  • Lifecycle Management: Handles activation and deactivation

Source: src/extension.ts#L4-L41

2. Factory Link Provider

File: src/providers/factoryLinkProvider.ts

The core intelligence of the extension:

  • Factory Detection: Uses regex patterns to identify factory calls in test files
  • Cache Management: Maintains in-memory caches for factories and traits
  • Link Generation: Creates clickable VSCode document links
  • Configuration Handling: Reads and responds to user configuration changes

Data Flow Architecture

1. Initialization Flow

sequenceDiagram
    participant VSCode
    participant Extension
    participant Provider
    participant FileSystem

    VSCode->>Extension: Activate on Ruby file
    Extension->>Provider: Create FactoryLinkProvider
    Extension->>VSCode: Register document link provider
    Provider->>FileSystem: Read factory paths configuration
    Provider->>FileSystem: Scan for factory files
    Provider->>Provider: Build factory and trait caches

2. Link Detection Flow

sequenceDiagram
    participant User
    participant VSCode
    participant Provider
    participant Cache

    User->>VSCode: Hover over factory call
    VSCode->>Provider: Request document links
    Provider->>Provider: Run regex detection
    Provider->>Cache: Lookup factory/trait
    Cache->>Provider: Return file URI and line
    Provider->>VSCode: Generate document link
    VSCode->>User: Show clickable link

3. Navigation Flow

sequenceDiagram
    participant User
    participant VSCode
    participant Extension
    participant FileSystem

    User->>VSCode: Click factory link
    VSCode->>Extension: Execute gotoLine command
    Extension->>FileSystem: Open target file
    Extension->>VSCode: Navigate to specific line
    VSCode->>User: Show factory definition

Caching Strategy

Factory Cache Structure

// Simplified cache structure
factoryCache: Map<string, { uri: vscode.Uri; lineNumber: number }>;
traitCache: Map<
  string,
  { uri: vscode.Uri; lineNumber: number; factory: string }
>;

Cache Operations

  1. Build: Scan all factory files and extract definitions
  2. Lookup: Fast O(1) retrieval by factory/trait name
  3. Refresh: Triggered by file system changes
  4. Priority: First definition found takes precedence

Source: src/providers/factoryLinkProvider.ts

Pattern Recognition

Factory Detection Regex

The extension uses sophisticated regex patterns to detect various FactoryBot call formats:

(?:create|create_list|build|build_list|build_stubbed|build_stubbed_list)\s*(?:\(\s*)?((:[a-zA-Z0-9_]+)(?:\s*,\s*(:[a-zA-Z0-9_]+))*)\s*(?:,\s*[^)]*)?(?:\)|\n|$)

Supports:

  • Multiple factory methods (create, build, create_list, etc.)
  • Parentheses and non-parentheses syntax
  • Factory names and traits
  • Complex parameter handling

Factory Definition Detection

factory\s+:([a-zA-Z0-9_]+)\b
trait\s+:([a-zA-Z0-9_]+)\s+do

Extracts:

  • Factory names from factory :name definitions
  • Trait names from trait :name do blocks
  • Precise line numbers for navigation

Configuration Architecture

Settings Schema

{
  "rails-factorybot-jump.factoryPaths": {
    "type": "array",
    "default": ["spec/factories/**/*.rb"],
    "description": "Paths to search for factory files"
  }
}

Configuration Flow

  1. Load: Read from VSCode workspace settings
  2. Validate: Ensure paths are valid glob patterns
  3. Apply: Update file watching and cache building
  4. Refresh: Rebuild caches on configuration changes

Source: package.json#L52-L66

Performance Considerations

Optimization Strategies

  1. Lazy Loading: Factory files are scanned only when needed
  2. Efficient Caching: In-memory maps for O(1) lookups
  3. Incremental Updates: File watcher triggers targeted cache updates
  4. Regex Optimization: Compiled patterns for fast text processing

Memory Management

  • Cache Size: Limited by project size (typically < 1MB)
  • Cleanup: Automatic cleanup on extension deactivation
  • Updates: Incremental rather than full rebuilds

Error Handling

Graceful Degradation

  1. Missing Files: Silent fallback if factory files don't exist
  2. Invalid Patterns: Skip malformed factory definitions
  3. Permission Issues: Continue operation with available files
  4. Regex Failures: Log errors without crashing extension

Integration Points

VSCode APIs

  • Document Link Provider: Core navigation interface
  • File System Watcher: Real-time file change detection
  • Commands: Custom navigation commands
  • Configuration: Settings integration
  • Workspace: Multi-folder workspace support

External Dependencies

  • Node.js: Runtime environment
  • TypeScript: Development language
  • VSCode Extension API: Platform integration
  • File System: Factory file discovery and reading

Next Steps