Deployment Build Process - hiraishikentaro/rails-factorybot-jump GitHub Wiki

Deployment: Build Process

Build Process Overview

Rails FactoryBot Jump uses a TypeScript-based build system that compiles source code to JavaScript for VSCode extension distribution. The build process includes compilation, linting, testing, and packaging.

Build System Architecture

1. TypeScript Compilation

Compilation Configuration (tsconfig.json):

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2020",
    "outDir": "out",
    "lib": ["ES2020"],
    "sourceMap": true,
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true
  },
  "exclude": ["node_modules", ".vscode-test"]
}

Key Compilation Settings:

  • Target: ES2020 for modern JavaScript features
  • Module System: CommonJS (required for VSCode extensions)
  • Output Directory: out/ for compiled JavaScript
  • Source Maps: Enabled for debugging support
  • Strict Mode: Enabled for type safety

Source: tsconfig.json

2. Build Scripts

Package.json Build Scripts:

{
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./",
    "pretest": "npm run compile && npm run lint",
    "lint": "eslint src --ext ts",
    "test": "node ./out/test/runTest.js",
    "test:unit": "node ./out/test/runUnitTests.js",
    "test:integration": "node ./out/test/runTest.js",
    "test:all": "npm run test:unit && npm run test:integration",
    "test:watch": "npm run test -- --watch"
  }
}

Script Purposes:

  • vscode:prepublish: Pre-publication hook for VSCode marketplace
  • compile: One-time TypeScript compilation
  • watch: Development mode with file watching
  • pretest: Pre-test preparation (compile + lint)
  • lint: Code quality checking
  • test: Integration test execution (default)
  • test:unit: Unit test execution only
  • test:integration: Integration test execution only
  • test:all: Run both unit and integration tests
  • test:watch: Test execution in watch mode

Source: package.json#L68-L76

Build Workflow

1. Development Build

Standard Development Workflow:

# Install dependencies
npm install

# Compile TypeScript to JavaScript
npm run compile

# Verify build output
ls out/
# Expected: extension.js, providers/, test/

Watch Mode for Development:

# Start watch mode for automatic recompilation
npm run watch

# This will:
# - Monitor TypeScript files for changes
# - Automatically recompile on file save
# - Preserve source maps for debugging
# - Continue running until stopped

2. Production Build

Pre-Publication Build:

# Full production build process
npm run vscode:prepublish

# This executes:
# 1. TypeScript compilation
# 2. Source map generation
# 3. Output optimization

Build Verification:

# Verify compiled output
node out/extension.js  # Should not error

# Check file structure
find out/ -name "*.js" -type f
# Expected files:
# out/extension.js
# out/providers/factoryLinkProvider.js
# out/test/runTest.js
# out/test/suite/extension.test.js
# out/test/suite/index.js

3. Quality Assurance Build

Pre-Test Build Process:

# Run the full QA build
npm run pretest

# This executes in sequence:
# 1. npm run compile  - Compile TypeScript
# 2. npm run lint     - Check code quality
# If either step fails, the process stops

Linting Process:

# Standalone linting
npm run lint

# Expected output for clean code:
# ✓ No ESLint errors or warnings

# Fix auto-fixable issues
npx eslint src --ext ts --fix

Source: package.json#L72-L73

Build Output Structure

1. Compiled JavaScript Structure

out/
├── extension.js              # Main extension entry point
├── extension.js.map          # Source map for debugging
├── providers/
│   ├── factoryLinkProvider.js    # Core provider implementation
│   └── factoryLinkProvider.js.map
├── models/                   # Data models
│   ├── factory.js
│   ├── location.js
│   └── trait.js
├── services/                 # Business services
│   ├── cacheManager.js
│   ├── configurationManager.js
│   ├── errorNotificationService.js
│   ├── factoryParser.js
│   └── fileSearcher.js
├── utils/                    # Utility functions
│   ├── pathUtils.js
│   └── regexPatterns.js
├── constants/
│   └── defaults.js
└── test/
    ├── runTest.js           # Integration test runner
    ├── runUnitTests.js      # Unit test runner
    ├── suite/               # Integration tests
    │   ├── extension.test.js
    │   └── index.js
    └── unit/                # Unit tests
        ├── index.js
        ├── models/
        ├── services/
        ├── utils/
        └── unitTestsRunner.js

2. Source Map Support

Source Map Benefits:

  • Debug TypeScript source in VSCode Extension Development Host
  • Accurate error stack traces pointing to TypeScript lines
  • Breakpoint support in original TypeScript files

Source Map Verification:

# Check source map generation
ls out/*.map out/**/*.map

# Verify source map content
cat out/extension.js.map | jq '.sources'
# Should show original TypeScript file paths

Extension Packaging

1. VSIX Package Generation

Manual Packaging (for development):

# Install vsce (VSCode Extension CLI)
npm install -g vsce

# Create VSIX package
vsce package

# This generates:
# rails-factorybot-jump-{version}.vsix

Package Contents Verification:

# Extract and inspect VSIX contents
unzip -l rails-factorybot-jump-*.vsix

# Key files that should be included:
# - package.json (extension manifest)
# - out/ directory (compiled JavaScript)
# - README.md
# - LICENSE
# - images/icon.png

2. Package Optimization

File Exclusion (.vscodeignore):

.vscode/**
.vscode-test/**
out/test/**
src/**
.gitignore
.yarnrc
vsc-extension-quickstart.md
**/tsconfig.json
**/.eslintrc.json
**/*.map
.nyc_output
coverage
**/.github
node_modules
*.vsix

Size Optimization:

# Check package size
ls -lh *.vsix

# Optimal size: < 1MB for this extension
# If larger, review .vscodeignore exclusions

Continuous Integration Build

1. GitHub Actions Build Matrix

CI Build Configuration (.github/workflows/ci.yml):

Separate CI Workflows:

Unit Test Workflow (.github/workflows/unit_test.yml):

name: Unit Tests

on: [push, pull_request]

jobs:
  unit-test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [22.x]

    runs-on: ${{ matrix.os }}
    timeout-minutes: 10

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Compile TypeScript
        run: npm run compile

      - name: Run linting
        run: npm run lint

      - name: Run unit tests
        run: npm run test:unit

Integration Test Workflow (.github/workflows/integration_test.yml):

name: Integration Tests

on: [push, pull_request]

jobs:
  integration-test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [22.x]

    runs-on: ${{ matrix.os }}
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Compile TypeScript
        run: npm run compile

      - name: Run integration tests (Linux)
        run: xvfb-run -a npm run test:integration
        if: runner.os == 'Linux'

      - name: Run integration tests (non-Linux)
        run: npm run test:integration
        if: runner.os != 'Linux'

2. Build Artifacts

CI Build Outputs:

  • Compiled JavaScript in out/ directory
  • Separate unit and integration test results
  • Linting results
  • Cross-platform compatibility verification
  • Performance metrics for different test types

Build Status Verification:

# Check build status locally before pushing
npm run pretest && npm run test:all

# Run specific test types
npm run test:unit     # Fast unit tests
npm run test:integration  # Full integration tests

# Verify cross-platform compatibility
# Test on Windows, macOS, and Linux if possible

Build Troubleshooting

1. Common Build Issues

TypeScript Compilation Errors:

# Check for syntax errors
npm run compile

# Common issues:
# - Missing type definitions
# - Import path errors
# - TypeScript version mismatches

Linting Failures:

# Fix auto-fixable linting issues
npm run lint -- --fix

# Manual fixes required for:
# - Type annotations
# - Unused variables
# - Code style violations

2. Clean Build Process

Full Clean Build:

# Remove all build artifacts
rm -rf out/
rm -rf node_modules/
rm package-lock.json

# Fresh installation and build
npm install
npm run compile
npm test

Dependency Issues:

# Check for dependency conflicts
npm ls

# Update dependencies if needed
npm update
npm audit
npm audit fix

Performance Optimization

1. Build Speed Optimization

Development Optimizations:

# Use watch mode for faster incremental builds
npm run watch

# Use TypeScript incremental compilation
# (configured in tsconfig.json with "incremental": true)

CI Optimizations:

  • Use npm ci instead of npm install for faster dependency installation
  • Cache node_modules between builds
  • Parallel testing across multiple platforms

2. Output Optimization

JavaScript Optimization:

  • TypeScript compiler optimizations (ES2020 target)
  • Tree shaking for unused code elimination
  • Minification not required for VSCode extensions

Bundle Size Management:

# Analyze bundle contents
npx webpack-bundle-analyzer out/

# Monitor package size
vsce package --out test-package.vsix
ls -lh test-package.vsix

Release Build Process

1. Version Management

Version Update Process:

# Update version in package.json
npm version patch  # or minor/major

# This automatically:
# - Updates package.json version
# - Creates git tag
# - Commits version change

2. Publication Build

Marketplace Publication:

# Full publication process
npm run vscode:prepublish
vsce package
vsce publish

# Or direct publish without local package
vsce publish

Pre-Publication Checklist:

  • All tests passing
  • Linting clean
  • Version updated
  • CHANGELOG updated
  • README up to date
  • Cross-platform testing completed

This comprehensive build process ensures reliable, high-quality extension distribution while maintaining development efficiency and code quality standards.