@bernierllc/validators-license-headers

License header validation primitive for ensuring source files contain proper copyright notices, SPDX identifiers, and compliant licensing information.

Installation

npm install @bernierllc/validators-license-headers

Overview

This validator provides comprehensive license header validation for source code files, checking for:

• Header presence - Ensures files contain license headers
• Copyright year - Validates year is present and current
• Forbidden licenses - Detects incompatible licenses (e.g., GPL in commercial code)
• SPDX identifiers - Validates standard license identifiers
• Copyright holders - Verifies copyright holder information

Usage

Basic Validation

import { validateLicenseHeaders } from '@bernierllc/validators-license-headers';
import type { SharedUtils } from '@bernierllc/validators-core';

const fileMetadata = {
  path: 'src/index.ts',
  content: fileContent,
  extension: '.ts'
};

const utils: SharedUtils = /* validators utils */;

const result = await validateLicenseHeaders(fileMetadata, {}, utils);

if (result.problems.length > 0) {
  console.log('License header issues found:');
  result.problems.forEach(problem => {
    console.log(`- ${problem.message}`);
  });
}

With Custom Options

const result = await validateLicenseHeaders(
  fileMetadata,
  {
    requireHeader: true,
    validateCopyrightYear: true,
    expectedYear: 2025,
    checkForbiddenLicenses: true,
    forbiddenLicenses: ['GPL-2.0', 'GPL-3.0', 'AGPL-3.0'],
    requireSpdxIdentifier: true,
    allowedSpdxIdentifiers: ['MIT', 'Apache-2.0', 'ISC'],
    requireCopyrightHolder: true,
    expectedCopyrightHolders: ['Bernier LLC'],
    maxHeaderLineOffset: 10
  },
  utils
);

Create Configured Validator

import { createLicenseHeaderValidator } from '@bernierllc/validators-license-headers';

const validator = createLicenseHeaderValidator({
  requireHeader: true,
  validateCopyrightYear: true,
  expectedYear: 2025,
  checkForbiddenLicenses: true
});

const result = await validator.validate(fileMetadata, utils);

// Get validator metadata
const meta = validator.getMeta();
console.log(`Validator: ${meta.name}`);
console.log(`Enabled rules: ${meta.enabledRules.join(', ')}`);

Configuration Options

LicenseHeaderOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | requireHeader | boolean | true | Require license header to be present | | validateCopyrightYear | boolean | true | Validate copyright year is present and valid | | expectedYear | number \| number[] | Current year | Expected copyright year(s) | | checkForbiddenLicenses | boolean | true | Check for forbidden licenses | | forbiddenLicenses | string[] | ['GPL-2.0', 'GPL-3.0', 'AGPL-3.0'] | List of forbidden license identifiers | | requireSpdxIdentifier | boolean | false | Require SPDX identifier to be present | | allowedSpdxIdentifiers | string[] | [] | List of allowed SPDX identifiers (empty = all allowed) | | requireCopyrightHolder | boolean | false | Require copyright holder to be specified | | expectedCopyrightHolders | string[] | [] | Expected copyright holder(s) | | maxHeaderLineOffset | number | 10 | Maximum lines from top of file to search for header |

Validation Rules

Header Presence

Validates that source files contain a license header in the first few lines.

Severity: error

Example violation:

// No license header
const x = 1;

Example passing:

/*
Copyright (c) 2025 Bernier LLC
SPDX-License-Identifier: MIT
*/

const x = 1;

Copyright Year

Validates copyright year is present and matches expected year(s).

Severity: warn (for mismatch), error (for missing)

Example violation:

/*
Copyright (c) 2020 Bernier LLC
*/
// Expected: 2025

Example passing:

/*
Copyright (c) 2025 Bernier LLC
*/

/*
Copyright (c) 2020-2025 Bernier LLC
*/

Forbidden Licenses

Detects forbidden licenses like GPL in commercial code.

Severity: error

Example violation:

/*
Copyright (c) 2025 Company
SPDX-License-Identifier: GPL-3.0
*/

Reason: GPL requires derivative works to be open source (copyleft)

SPDX Identifier

Validates SPDX license identifier is present and matches allowed list.

Severity: warn (for missing), error (for not allowed)

Example violation:

/*
Copyright (c) 2025 Bernier LLC
*/
// Missing SPDX-License-Identifier

Example passing:

/*
Copyright (c) 2025 Bernier LLC
SPDX-License-Identifier: MIT
*/

Copyright Holder

Validates copyright holder is present and matches expected values.

Severity: warn (for missing), error (for mismatch)

Example violation:

/*
Copyright (c) 2025
*/
// Missing copyright holder

Example passing:

/*
Copyright (c) 2025 Bernier LLC
*/

Parser Utilities

The package exports parser utilities for extracting license header information:

import {
  extractLicenseHeader,
  extractCopyrightYear,
  extractCopyrightHolder,
  extractSpdxIdentifier,
  parseYearSpec,
  isYearAcceptable
} from '@bernierllc/validators-license-headers';

// Extract complete header information
const header = extractLicenseHeader(fileContent);
console.log(header?.copyrightYear);      // "2025"
console.log(header?.copyrightHolder);    // "Bernier LLC"
console.log(header?.spdxIdentifier);     // "MIT"

// Extract specific components
const year = extractCopyrightYear("Copyright (c) 2025 Company");
const holder = extractCopyrightHolder("Copyright (c) 2025 Company");
const spdx = extractSpdxIdentifier("SPDX-License-Identifier: MIT");

// Year validation
const years = parseYearSpec("2020-2025");  // [2020, 2021, 2022, 2023, 2024, 2025]
const acceptable = isYearAcceptable("2025", 2025);  // true

Supported Header Formats

Block Comments

/*
Copyright (c) 2025 Bernier LLC
SPDX-License-Identifier: MIT
*/

/*
 * Copyright (c) 2025 Bernier LLC
 * License: Apache-2.0
 */

Line Comments

// Copyright (c) 2025 Bernier LLC
// SPDX-License-Identifier: ISC

# Copyright (c) 2025 Bernier LLC
# License: MIT

Year Formats

• Single year: Copyright (c) 2025
• Year range: Copyright (c) 2020-2025
• Alternative symbols: © 2025, (c) 2025

Individual Rules Export

For advanced usage, you can import and use individual rules:

import {
  headerPresenceRule,
  copyrightYearRule,
  forbiddenLicensesRule,
  spdxIdentifierRule,
  copyrightHolderRule
} from '@bernierllc/validators-license-headers';

API Reference

validateLicenseHeaders(fileMetadata, options, utils): Promise<ValidationResult>

Validates license headers in a file.

Parameters:

• fileMetadata: FileMetadata - File to validate
• options: LicenseHeaderOptions - Validation options
• utils: SharedUtils - Shared utilities from validators-core

Returns: Promise<ValidationResult> - Validation results with problems and stats

createLicenseHeaderValidator(options): { validate, getMeta }

Creates a configured validator instance.

Parameters:

• options: LicenseHeaderOptions - Validator configuration

Returns: Object with validate function and getMeta function

Integration Status

Logger Integration

Status: Not applicable - Pure validation primitive

This package is a primitive validator that doesn't require logger integration. It's designed to be used by domain validators and validation runners that handle logging at a higher level.

Docs-Suite Integration

Status: Ready - Complete API documentation with examples

The package provides comprehensive documentation including:

• API reference with all exported functions
• Usage examples for common scenarios
• Configuration options with detailed descriptions
• Rule documentation with severity levels

NeverHub Integration

Status: Not applicable - Primitive validator

As a primitive validator in the MECE architecture, this package operates at the lowest level and doesn't require NeverHub integration. Higher-level domain validators and validation services that use this package will handle NeverHub integration for:

• Validation result aggregation
• Compliance monitoring
• License policy enforcement across services

Dependencies

• @bernierllc/validators-core - Core validation framework

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

See Also

• @bernierllc/validators-core - Core validation framework
• @bernierllc/validators-utils - Validation utilities
• @bernierllc/validators-secret-patterns - Secret detection validator