Architecture Technology Stack - hiraishikentaro/rails-factorybot-jump GitHub Wiki

Architecture: Technology Stack

Core Technologies

Primary Language

  • TypeScript 5.3.3 - Primary development language providing type safety and modern JavaScript features
  • Target: ES2020 for modern runtime features
  • Module System: CommonJS (required for VSCode extensions)

Source: package.json#L89, tsconfig.json#L4

Runtime Environment

  • Node.js 18.x - JavaScript runtime environment
  • VSCode Extension Host - Specialized runtime for VSCode extensions
  • Electron - Underlying platform for VSCode

Source: package.json#L79

VSCode Integration

Extension APIs

  • VSCode Extension API 1.85.0+ - Core platform integration
  • Document Link Provider - Interface for creating clickable links
  • File System Watcher - Real-time file change monitoring
  • Commands API - Custom command registration and execution
  • Configuration API - Settings integration

Source: package.json#L9, src/extension.ts

Extension Configuration

  • Activation Events: onLanguage:ruby - Activates when Ruby files are opened
  • Document Link Providers: Registered for file scheme and ruby language
  • Commands: Custom navigation commands
  • Settings Schema: JSON schema for configuration validation

Source: package.json#L35-L66

Development Tools

TypeScript Toolchain

  • TypeScript Compiler - Source code compilation
  • Source Maps - Debugging support
  • Strict Mode - Enhanced type checking and safety
  • ES Module Interop - Module compatibility

Source: tsconfig.json#L9

Code Quality

  • ESLint 8.56.0 - Code quality and style enforcement
  • @typescript-eslint - TypeScript-specific linting rules
  • Parser: TypeScript ESLint parser for accurate code analysis
  • Plugin: TypeScript ESLint plugin for TypeScript-aware rules

Source: package.json#L82-L83

Testing Infrastructure

Testing Framework

  • Mocha 10.8.2 - JavaScript testing framework
  • @vscode/test-electron 2.4.1 - VSCode extension testing environment
  • Sinon 17.0.1 - Mocking and stubbing framework for tests

Source: package.json#L78,L84,L88

Test Environment

  • VSCode Test Runner - Runs tests in actual VSCode environment
  • Electron Test Environment - Realistic testing with full VSCode APIs
  • Headless Testing - Automated testing without GUI (CI/CD)

Source: src/test/runTest.ts

File System & Pattern Matching

Pattern Matching

  • Glob 8.1.0 - File pattern matching for factory discovery
  • Built-in Regex - Factory and trait pattern detection
  • VSCode Workspace APIs - File system access and watching

Source: package.json#L86

Path Handling

  • POSIX Paths - Cross-platform path compatibility
  • Glob Patterns - Flexible file matching (**/*.rb)
  • Workspace Relative - Paths relative to VSCode workspace

Target Languages & Frameworks

Supported Languages

  • Ruby - Primary target language
  • FactoryBot DSL - Specific Ruby testing framework syntax
  • RSpec/Minitest - Compatible with major Ruby testing frameworks

Ruby Integration

  • Factory Detection - Recognizes FactoryBot factory definitions
  • Trait Support - Supports factory traits and variations
  • Method Recognition - Detects various FactoryBot methods (create, build, etc.)

Build System

Compilation

  • TypeScript Compiler - Transpiles TypeScript to JavaScript
  • Output Directory: out/ - Compiled JavaScript files
  • Watch Mode - Automatic recompilation during development
  • Source Maps - Debugging support in development

Build Scripts

npm run compile     # One-time compilation
npm run watch       # Development with file watching
npm run pretest     # Pre-test compilation and linting
npm run vscode:prepublish  # Production build

Source: package.json#L68-L76

Package Management

Dependency Management

  • npm - Package manager for Node.js dependencies
  • package-lock.json - Exact version locking for reproducible builds
  • Semantic Versioning - Version compatibility management

Development Dependencies

  • All dependencies are development-only (no runtime dependencies)
  • Testing frameworks and tools
  • TypeScript compilation tools
  • Code quality tools

Source: package.json#L77-L90

Deployment Technology

Extension Distribution

  • VSCode Marketplace - Primary distribution channel
  • VSIX Package - Extension packaging format
  • Extension Manifest - package.json configuration

Version Management

  • Semantic Versioning - Version numbering scheme
  • Extension Gallery - VSCode extension marketplace integration
  • Publisher Identity - hir4ken publisher on marketplace

Source: package.json#L7

Platform Compatibility

Operating Systems

  • Windows - Full compatibility with Windows-specific path handling
  • macOS - Native macOS support
  • Linux - Linux compatibility with headless testing support

Cross-Platform Considerations

  • Path Normalization - POSIX paths for consistency
  • File System APIs - VSCode abstraction layer for cross-platform compatibility
  • CI/CD Testing - Multi-platform automated testing

Performance Technologies

Optimization Strategies

  • Lazy Loading - Factory files loaded on demand
  • In-Memory Caching - Fast Map-based lookups
  • Incremental Updates - Targeted cache updates on file changes
  • Compiled Regex - Pre-compiled patterns for performance

Memory Management

  • Map Data Structures - Efficient key-value storage for caches
  • Weak References - Where applicable for memory efficiency
  • Cleanup Handlers - Proper resource disposal on deactivation

Security Considerations

File System Security

  • Workspace Boundaries - Restricted to VSCode workspace
  • Read-Only Access - Only reads factory files, no modifications
  • No Network Access - Purely local file system operations
  • VSCode Security Model - Inherits VSCode's security restrictions

Future Technology Considerations

Potential Enhancements

  • Language Server Protocol - For more advanced Ruby language features
  • Tree Sitter - More robust Ruby parsing
  • WebAssembly - Performance-critical operations
  • Multi-Language Support - Extension to other factory frameworks

Scalability

  • Large Codebases - Designed to handle projects with many factory files
  • Memory Efficiency - Scales with project size
  • Performance Monitoring - Built-in performance considerations

Technology Decision Rationale

TypeScript Choice

  • Type Safety - Reduces runtime errors
  • Developer Experience - Better tooling and IDE support
  • VSCode Ecosystem - Natural fit for VSCode extension development
  • Maintainability - Easier to maintain and refactor

Architecture Patterns

  • Provider Pattern - Clean separation of concerns
  • Event-Driven - Reactive updates via file watching
  • Caching Strategy - Balance between memory and performance
  • Lazy Initialization - Better startup performance