@bernierllc/package-validator

Pure package validation utilities for monorepo quality assurance.

Overview

The @bernierllc/package-validator package provides comprehensive validation utilities for ensuring package quality and consistency across monorepos. It validates package structure, package.json fields, license headers, and more.

Features

• Structure Validation: Ensures packages have required directories and files
• Package.json Validation: Validates all package.json fields according to standards
• License Checking: Verifies license headers in source files
• Monorepo Support: Validates entire monorepos or individual packages
• Comprehensive Error Reporting: Detailed error messages with file paths
• TypeScript Support: Full TypeScript support with strict typing
• No Dependencies: Pure implementation with no external dependencies

Installation

npm install @bernierllc/package-validator

Usage

Basic Package Validation

import { validatePackage } from '@bernierllc/package-validator';

const result = validatePackage('packages/my-package');

if (result.isValid) {
  console.log('Package is valid!');
} else {
  console.log('Validation errors:', result.errors);
}

Validate Multiple Packages

import { validatePackages } from '@bernierllc/package-validator';

const packagePaths = [
  'packages/core/package1',
  'packages/core/package2',
  'packages/service/package3'
];

const summary = validatePackages(packagePaths);
console.log(`Valid packages: ${summary.validPackages}/${summary.totalPackages}`);

Validate Entire Monorepo

import { validateAllPackages } from '@bernierllc/package-validator';

const summary = validateAllPackages();
console.log(`Found ${summary.totalPackages} packages`);
console.log(`Valid: ${summary.validPackages}, Invalid: ${summary.invalidPackages}`);

Get All Packages in Monorepo

import { getAllPackages } from '@bernierllc/package-validator';

const packages = getAllPackages('packages');
console.log('Found packages:', packages);

Configuration

Custom Validation Rules

import { validatePackage, getDefaultConfig } from '@bernierllc/package-validator';

const customConfig = {
  ...getDefaultConfig(),
  structure: [
    { type: 'directory', name: 'src' },
    { type: 'directory', name: 'tests' },
    { 
      type: 'file', 
      name: 'package.json',
      validation: {
        fields: {
          name: { required: true, pattern: '^@myorg/[a-z0-9-]+$' },
          version: { required: true, pattern: '^\\d+\\.\\d+\\.\\d+$' },
          description: { required: true, minLength: 10 }
        }
      }
    }
  ]
};

const result = validatePackage('packages/my-package', { config: customConfig });

License Checking

import { validatePackage } from '@bernierllc/package-validator';

const result = validatePackage('packages/my-package', {
  licenseTemplate: 'Copyright (c) 2025 My Company'
});

API Reference

Functions

validatePackage(packagePath: string, options?: ValidatorOptions): PackageValidationResult

Validates a single package.

Parameters:

• packagePath: Path to the package directory
• options: Optional validation configuration

Returns:

• PackageValidationResult with validation status and errors

validatePackages(packagePaths: string[], options?: ValidatorOptions): ValidationSummary

Validates multiple packages.

Parameters:

• packagePaths: Array of package paths
• options: Optional validation configuration

Returns:

• ValidationSummary with overall statistics

validateAllPackages(options?: ValidatorOptions): ValidationSummary

Validates all packages in the monorepo.

Parameters:

• options: Optional validation configuration

Returns:

• ValidationSummary with overall statistics

getAllPackages(packagesDir?: string): string[]

Gets all package paths in the monorepo.

Parameters:

• packagesDir: Packages directory path (default: 'packages')

Returns:

• Array of package paths

Types

ValidatorOptions

interface ValidatorOptions {
  config?: ValidatorConfig;
  licenseTemplate?: string;
  packagesDir?: string;
  strict?: boolean;
}

PackageValidationResult

interface PackageValidationResult {
  packagePath: string;
  isValid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
}

ValidationSummary

interface ValidationSummary {
  totalPackages: number;
  validPackages: number;
  invalidPackages: number;
  totalErrors: number;
  totalWarnings: number;
  results: PackageValidationResult[];
}

Validation Rules

Structure Validation

The validator checks for required directories and files:

• src/ - Source code directory
• docs/ - Documentation directory
• examples/ - Examples directory
• tests/ - Test files directory
• README.md - Package documentation
• LICENSE - License file
• package.json - Package manifest

Package.json Validation

Validates package.json fields according to standards:

• name: Must be scoped package name (e.g., @bernierllc/package-name)
• version: Must follow semver format
• description: Required with minimum length
• main: Required and file must exist
• author: Required
• license: Must be valid license type
• repository: Must be valid URL or git SSH
• scripts: No dangerous scripts allowed
• dependencies: No blacklisted packages

License Validation

Checks for proper license headers in source files:

• JavaScript/TypeScript files
• Shell scripts
• Python files
• HTML/CSS files
• Excludes JSON, markdown, and binary files

Error Handling

The validator provides detailed error messages with:

• Error type (error/warning)
• File path where error occurred
• Field name (for package.json errors)
• Descriptive error message
• Suggested fixes

Examples

See the examples/ directory for complete usage examples.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

UNLICENSED - See LICENSE file for details.

Changelog

0.1.0

• Initial release
• Basic package validation
• Structure validation
• Package.json field validation
• License checking
• Monorepo support