Quality Gates

Comprehensive quality assurance system for the TypeScript Project Template.

Overview

Quality gates ensure code consistency, reliability, and maintainability through automated checks:

• Linting with ESLint 9
• Formatting with Prettier
• Testing with Jest
• Type checking with TypeScript
• Build verification

Quick Quality Check

Single Command

# Run all quality gates
npm run check

This executes:

1. ESLint (linting)
2. Prettier (format check)
3. Jest (testing)
4. TypeScript (build verification)

Auto-Fix Command

# Fix auto-fixable issues
npm run fix

This runs:

1. ESLint with --fix flag
2. Prettier formatting

Individual Quality Gates

1. Linting (ESLint)

Run Linting

# Check for linting issues
npm run lint

# Fix auto-fixable issues
npm run lint:fix

ESLint Configuration

• ESLint 9 with flat configuration
• TypeScript integration with type checking
• Prettier integration for formatting
• Import organization rules
• Jest-specific rules for test files

Common Linting Rules

// ✅ Good
export async function main(): Promise<void> {
  console.log('Hello World');
}

// ❌ Bad - missing return type
export async function main() {
  console.log('Hello World');
}

2. Formatting (Prettier)

Run Formatting

# Check formatting
npm run format:check

# Apply formatting
npm run format

Prettier Configuration

• Single quotes for strings
• No trailing commas for clean syntax
• 2-space indentation for readability
• 100-character line width for modern displays
• Semicolons enabled for explicit statements

Formatting Examples

// ✅ Good - Prettier formatted
const config: UtilConfig = {
  debug: true,
  maxRetries: 3,
  timeout: 5000
};

// ❌ Bad - inconsistent formatting
const config:UtilConfig={debug:true,maxRetries:3,timeout:5000,};

3. Testing (Jest)

Run Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# CI mode
npm run test:ci

Coverage Requirements

Minimum 80% coverage across all metrics:

• Branches: 80%
• Functions: 80%
• Lines: 80%
• Statements: 80%

Test Quality Standards

// ✅ Good - comprehensive test
describe('formatTimestamp', () => {
  it('should format timestamp correctly', () => {
    const timestamp = new Date('2024-01-15T14:30:00.000Z').getTime();
    const result = formatTimestamp(timestamp);
    expect(result).toBe('2024-01-15 14:30:00');
  });

  it('should handle debug configuration', () => {
    // Test with configuration
  });

  it('should work without configuration', () => {
    // Test default behavior
  });
});

4. Type Checking (TypeScript)

Run Type Checking

# Type check without emitting
npx tsc --noEmit

# Build (includes type checking)
npm run build

TypeScript Standards

• Strict mode enabled
• No implicit any types
• Explicit return types for functions
• Proper error handling with types

Type Safety Examples

// ✅ Good - explicit types
export function safeJsonParse(jsonString: string): AsyncResult<unknown> {
  try {
    const data: unknown = JSON.parse(jsonString);
    return { success: true, data };
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error'
    };
  }
}

// ❌ Bad - implicit any
export function safeJsonParse(jsonString) {
  // TypeScript can't infer types
}

Quality Gate Integration

Pre-Commit Workflow

# Recommended pre-commit sequence
npm run fix      # Auto-fix issues
npm run check    # Verify all gates pass
npm run build    # Final verification
git commit       # Commit if all pass

CI/CD Integration

# GitHub Actions quality gates
- name: Run quality checks
  run: npm run check

- name: Build verification
  run: npm run build

- name: Upload coverage
  uses: codecov/codecov-action@v3

Quality Metrics

Code Quality Indicators

• Zero ESLint errors in production code
• 100% Prettier compliance across codebase
• 80%+ test coverage on all metrics
• Zero TypeScript errors in strict mode
• Successful build with all optimizations

Performance Metrics

• Fast linting with ESLint 9 flat config
• Quick formatting with Prettier
• Efficient testing with Jest parallel execution
• Fast builds with TypeScript incremental compilation

Quality Configuration

ESLint Configuration (eslint.config.js)

export default [
  {
    files: ['**/*.{js,mjs,cjs,ts}'],
    languageOptions: {
      parser: typescriptParser,
      parserOptions: {
        project: './tsconfig.json'
      }
    },
    plugins: {
      '@typescript-eslint': typescript,
      prettier: prettierPlugin
    },
    rules: {
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/explicit-function-return-type': 'warn',
      'prettier/prettier': 'error'
    }
  }
];

Jest Configuration (jest.config.js)

export default {
  preset: 'ts-jest/presets/default-esm',
  testEnvironment: 'node',
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80
    }
  }
};

Troubleshooting Quality Issues

ESLint Issues

# Debug ESLint configuration
npx eslint --print-config src/index.ts

# Check specific file
npx eslint src/index.ts --fix

Prettier Issues

# Check what needs formatting
npx prettier --check "src/**/*.ts"

# Format specific files
npx prettier --write "src/**/*.ts"

Jest Issues

# Clear Jest cache
npm test -- --clearCache

# Debug test configuration
npm test -- --showConfig

TypeScript Issues

# Verbose type checking
npx tsc --noEmit --listFiles

# Check configuration
npx tsc --showConfig

Quality Best Practices

Code Organization

• Consistent file structure following conventions
• Clear module boundaries with proper exports
• Logical grouping of related functionality
• Minimal dependencies between modules

Documentation Standards

• TSDoc comments for all exported functions
• Type documentation with examples
• README updates for new features
• API documentation generation

Testing Standards

• Test-driven development when appropriate
• Comprehensive coverage of edge cases
• Mock external dependencies properly
• Async testing patterns for modern code

Maintenance

• Regular dependency updates with security audits
• Configuration reviews for new tool versions
• Performance monitoring of quality gates
• Team training on quality standards

Continuous Improvement

Metrics Tracking

• Quality gate execution time trends
• Test coverage improvements over time
• Code complexity metrics
• Technical debt identification

Tool Updates

• ESLint rule updates for new best practices
• TypeScript version upgrades for new features
• Jest configuration optimizations
• Prettier rule adjustments for team preferences

Next Steps

• Configuration - Advanced setup options
• Deployment - CI/CD integration
• API Reference - Code examples and patterns