@bernierllc/development-checker

Service package for checking development environment setup, configuration, and best practices in a monorepo environment.

Features

• Comprehensive Environment Checks: Validate workspace configuration, packages, dependencies, licenses, git status, scripts, and development tools
• Real Filesystem Operations: No mocks - uses real filesystem and git operations for accurate checking
• Flexible Check Selection: Run all checks or select specific check types
• Detailed Reporting: Get comprehensive reports with errors, warnings, and suggestions
• Health Assessment: Determine overall development environment health
• Actionable Suggestions: Get specific recommendations for improving the environment
• TypeScript Support: Full TypeScript support with strict typing

Installation

npm install @bernierllc/development-checker

Quick Start

import { DevelopmentChecker } from '@bernierllc/development-checker';

// Initialize checker
const checker = new DevelopmentChecker({
  workspaceRoot: './',
  strictMode: false,
  verboseMode: true
});

// Run all checks
const result = await checker.runChecks();

if (result.isHealthy) {
  console.log('✅ Development environment is healthy!');
  console.log(`Passed: ${result.summary.passed}/${result.summary.total} checks`);
} else {
  console.log('❌ Development environment has issues:');
  console.log(`Errors: ${result.errors.length}`);
  console.log(`Warnings: ${result.warnings.length}`);
  console.log(`Suggestions: ${result.suggestions.length}`);
}

API Reference

DevelopmentChecker

Constructor

new DevelopmentChecker(config?: Partial<DevelopmentCheckerConfig>)

Configuration Options:

• workspaceRoot: Root directory of the workspace (default: process.cwd())
• defaultChecks: Default check types to run (default: ['workspace', 'packages', 'licenses', 'git', 'scripts', 'configuration'])
• strictMode: Enable strict mode where warnings affect health (default: false)
• verboseMode: Enable verbose output (default: false)
• autoFix: Enable automatic fixing of issues (default: false)
• timeoutMs: Timeout for operations in milliseconds (default: 30000)

Methods

runChecks(options: DevelopmentCheckOptions): Promise

Run development environment checks.

const result = await checker.runChecks({
  workspaceRoot: './',
  checkTypes: ['workspace', 'packages', 'git'],
  strict: false,
  verbose: true,
  fix: false
});

getCheckResult(checkType: DevelopmentCheckType, options: DevelopmentCheckOptions): Promise

Get results for a specific check type.

const workspaceCheck = await checker.getCheckResult('workspace');
const gitCheck = await checker.getCheckResult('git');

Check Types

The checker supports the following check types:

workspace

• Validates workspace configuration (npm/yarn/pnpm)
• Checks package discovery
• Verifies workspace structure

packages

• Validates package structure and configuration
• Checks for required files (package.json, README.md, LICENSE, etc.)
• Verifies package naming conventions

dependencies

• Analyzes dependency versions and security
• Checks for outdated dependencies
• Identifies duplicate dependencies
• Validates peer dependencies

licenses

• Checks license header compliance
• Validates license file presence
• Ensures proper licensing across files

git

• Validates git repository setup
• Checks working directory status
• Verifies remote configuration
• Analyzes commit history

scripts

• Validates package.json scripts
• Checks for dangerous scripts
• Ensures common scripts are present
• Analyzes script security

configuration

• Checks development tool configurations
• Validates TypeScript, Jest, ESLint, Prettier setup
• Ensures proper tooling configuration

Types

DevelopmentCheckOptions

interface DevelopmentCheckOptions {
  workspaceRoot?: string;        // Workspace root directory
  checkTypes?: DevelopmentCheckType[];  // Specific checks to run
  strict?: boolean;              // Enable strict mode
  verbose?: boolean;             // Enable verbose output
  fix?: boolean;                 // Enable auto-fix
}

DevelopmentCheckResult

interface DevelopmentCheckResult {
  workspaceRoot: string;         // Workspace root directory
  checks: DevelopmentCheck[];    // Individual check results
  summary: CheckSummary;         // Summary statistics
  isHealthy: boolean;            // Overall health status
  errors: string[];              // All errors
  warnings: string[];            // All warnings
  suggestions: string[];         // All suggestions
}

DevelopmentCheck

interface DevelopmentCheck {
  type: DevelopmentCheckType;    // Check type
  name: string;                  // Check name
  description: string;           // Check description
  status: CheckStatus;           // Check status (passed/failed/warning/skipped)
  details: CheckDetails;         // Detailed results
  errors: string[];              // Check-specific errors
  warnings: string[];            // Check-specific warnings
  suggestions: string[];         // Check-specific suggestions
  duration: number;              // Check duration in milliseconds
}

CheckSummary

interface CheckSummary {
  total: number;                 // Total checks run
  passed: number;                // Passed checks
  failed: number;                // Failed checks
  warnings: number;              // Warning checks
  skipped: number;               // Skipped checks
  duration: number;              // Total duration in milliseconds
}

Examples

Basic Usage

import { DevelopmentChecker } from '@bernierllc/development-checker';

const checker = new DevelopmentChecker();

// Run all default checks
const result = await checker.runChecks();

console.log(`Environment Health: ${result.isHealthy ? '✅ Healthy' : '❌ Issues Found'}`);
console.log(`Summary: ${result.summary.passed}/${result.summary.total} checks passed`);
console.log(`Duration: ${result.summary.duration}ms`);

if (!result.isHealthy) {
  console.log('\nIssues Found:');
  result.errors.forEach(error => console.log(`❌ ${error}`));
  result.warnings.forEach(warning => console.log(`⚠️  ${warning}`));
  result.suggestions.forEach(suggestion => console.log(`💡 ${suggestion}`));
}

Specific Checks

// Run only workspace and git checks
const result = await checker.runChecks({
  checkTypes: ['workspace', 'git']
});

// Run all checks
const allChecks = await checker.runChecks({
  checkTypes: ['all']
});

Individual Check Results

// Get specific check results
const workspaceCheck = await checker.getCheckResult('workspace');
const gitCheck = await checker.getCheckResult('git');
const scriptsCheck = await checker.getCheckResult('scripts');

console.log(`Workspace: ${workspaceCheck.status}`);
console.log(`Git: ${gitCheck.status}`);
console.log(`Scripts: ${scriptsCheck.status}`);

Custom Configuration

const checker = new DevelopmentChecker({
  workspaceRoot: '/path/to/workspace',
  strictMode: true,
  verboseMode: true,
  defaultChecks: ['workspace', 'packages', 'git']
});

const result = await checker.runChecks({
  strict: true
});

Error Handling

try {
  const result = await checker.runChecks();
  
  if (result.isHealthy) {
    console.log('Environment is ready for development');
  } else {
    console.log('Environment needs attention:');
    
    if (result.errors.length > 0) {
      console.log('\nCritical Issues:');
      result.errors.forEach(error => console.log(`❌ ${error}`));
    }
    
    if (result.warnings.length > 0) {
      console.log('\nWarnings:');
      result.warnings.forEach(warning => console.log(`⚠️  ${warning}`));
    }
    
    if (result.suggestions.length > 0) {
      console.log('\nSuggestions:');
      result.suggestions.forEach(suggestion => console.log(`💡 ${suggestion}`));
    }
  }
} catch (error) {
  console.error('Check failed:', error);
}

Detailed Check Analysis

const result = await checker.runChecks();

// Analyze each check
for (const check of result.checks) {
  console.log(`\n${check.name}:`);
  console.log(`  Status: ${check.status}`);
  console.log(`  Duration: ${check.duration}ms`);
  
  if (check.errors.length > 0) {
    console.log(`  Errors: ${check.errors.length}`);
    check.errors.forEach(error => console.log(`    ❌ ${error}`));
  }
  
  if (check.warnings.length > 0) {
    console.log(`  Warnings: ${check.warnings.length}`);
    check.warnings.forEach(warning => console.log(`    ⚠️  ${warning}`));
  }
  
  if (check.suggestions.length > 0) {
    console.log(`  Suggestions: ${check.suggestions.length}`);
    check.suggestions.forEach(suggestion => console.log(`    💡 ${suggestion}`));
  }
}

Check Details

Workspace Check Details

interface WorkspaceCheckDetails {
  isValid: boolean;              // Workspace configuration validity
  type: string;                  // Workspace type (npm/yarn/pnpm)
  packages: string[];            // Discovered packages
  configPath?: string;           // Configuration file path
}

Package Check Details

interface PackageCheckDetails {
  totalPackages: number;         // Total packages found
  validPackages: number;         // Valid packages
  invalidPackages: string[];     // Invalid package names
  missingFiles: string[];        // Missing required files
  packageErrors: PackageError[]; // Detailed package errors
}

Git Check Details

interface GitCheckDetails {
  isRepository: boolean;         // Is a git repository
  hasRemote: boolean;            // Has remote configured
  currentBranch: string;         // Current branch name
  isClean: boolean;              // Working directory is clean
  uncommittedFiles: string[];    // Uncommitted files
  untrackedFiles: string[];      // Untracked files
  lastCommit: string;            // Last commit hash
}

Script Check Details

interface ScriptCheckDetails {
  totalScripts: number;          // Total scripts found
  validScripts: number;          // Valid scripts
  invalidScripts: string[];      // Invalid script names
  missingScripts: string[];      // Missing common scripts
  dangerousScripts: string[];    // Potentially dangerous scripts
}

Configuration Check Details

interface ConfigurationCheckDetails {
  hasTypeScript: boolean;        // TypeScript configuration present
  hasJest: boolean;              // Jest configuration present
  hasESLint: boolean;            // ESLint configuration present
  hasPrettier: boolean;          // Prettier configuration present
  hasHusky: boolean;             // Husky configuration present
  hasLintStaged: boolean;        // Lint-staged configuration present
  missingConfigs: string[];      // Missing configurations
}

Testing

The package includes comprehensive tests that use real filesystem operations:

npm test

Tests cover:

• All check types and their functionality
• Error handling and edge cases
• Configuration options and modes
• Real filesystem and git operations
• Integration with core packages

Best Practices

1. Run checks regularly: Integrate into CI/CD pipelines and pre-commit hooks
2. Use strict mode in production: Enable strict mode for critical environments
3. Address warnings: Don't ignore warnings - they often indicate potential issues
4. Follow suggestions: Implement suggested improvements for better development experience
5. Customize for your needs: Configure check types based on your project requirements
6. Monitor trends: Track check results over time to identify patterns

Integration

CI/CD Pipeline

# GitHub Actions example
- name: Check Development Environment
  run: |
    npm install @bernierllc/development-checker
    node -e "
      const { DevelopmentChecker } = require('@bernierllc/development-checker');
      const checker = new DevelopmentChecker({ strictMode: true });
      checker.runChecks().then(result => {
        if (!result.isHealthy) {
          console.error('Development environment issues found');
          process.exit(1);
        }
      });
    "

Pre-commit Hook

{
  "husky": {
    "hooks": {
      "pre-commit": "node scripts/check-dev-env.js"
    }
  }
}

// scripts/check-dev-env.js
const { DevelopmentChecker } = require('@bernierllc/development-checker');

const checker = new DevelopmentChecker({ strictMode: true });

checker.runChecks().then(result => {
  if (!result.isHealthy) {
    console.error('❌ Development environment issues found');
    console.error('Please fix the issues before committing');
    process.exit(1);
  }
  console.log('✅ Development environment is healthy');
});

Contributing

This package follows the project's development standards:

• No mocks in tests - use real filesystem operations
• Comprehensive TypeScript typing
• Clear documentation and examples
• Proper error handling and validation
• Integration with core packages

License

This package is licensed under the same terms as the parent project.