eslint-plugin-header

eslint-plugin-header adds a single ESLint rule, header/header, that checks whether each file begins with a specific comment - commonly a copyright or license notice - and reports a violation when it’s missing or doesn’t match. The expected header can be supplied as a literal string, an array of lines, or read from a separate file, and individual lines can be regular expressions with an optional template used for autofixing.

The rule supports both block and line comment styles, a configurable number of newlines after the header, shebang-aware detection so scripts starting with #! still get checked correctly, and OS-appropriate line endings - with eslint --fix able to insert or repair the header automatically whenever every line is fixable.

What You Get

• header/header rule - A single ESLint rule that checks every file’s leading comment against a configured header.
• String, array, or file-based config - Define the header inline as a string or array of lines, or point to an external file that’s read and parsed at lint time.
• Regex line matching with fix templates - Any header line can be a regular expression, with an optional template so eslint --fix still knows what to insert.
• Autofix support - Missing or incorrect headers can be inserted or replaced automatically via eslint --fix, except when a regex line has no template.
• Line-ending and shebang awareness - Handles both Unix and Windows line endings and skips over shebang lines before checking for a header.

Common Use Cases

• Copyright banner enforcement - Teams require every file to open with a company copyright notice, and CI fails the build when it’s missing or altered.
• License header compliance - Open source projects requiring an SPDX or license notice at the top of every file so contributors don’t strip it accidentally.
• Generated-file markers - Projects mark auto-generated files with a specific comment header that this rule verifies stays intact.
• Monorepo-wide header consistency - A shared ESLint config applies the same header rule across many packages to keep file headers consistent.

Under The Hood

Architecture The plugin is a minimal, single-purpose ESLint rule module: index.js exports a rules map with one entry, header, pointing at lib/rules/header.js, which implements the standard ESLint rule shape (meta + create(context)) and registers a Program visitor that runs once per file. A small isolated helper, lib/comment-parser.js, handles the one alternate code path - parsing a header from an external file - by splitting it into the same [commentType, lines] shape the inline-string/array options already produce, so the rest of the rule logic doesn’t need to branch on where the header came from. There is no layering beyond rule-plus-helper, which suits the narrow scope: one rule, one job, no plugin-wide state or shared context to manage.

Tech Stack Plain, pre-ES6 JavaScript (CommonJS require/module.exports, var/function throughout, no TypeScript, no transpilation step) targeting Node’s built-in fs and os modules only - fs.readFileSync for file-based headers and os.EOL for platform-appropriate line endings. The plugin declares eslint as both a dev dependency and a >=7.7.0 peer dependency, is consumed through the standard ESLint plugin/rule configuration surface, and ships with no build tooling - it’s published to npm as-is.

Code Quality Tests exist and are reasonably thorough for the rule’s surface area: tests/lib/rules/header.js uses ESLint’s own RuleTester across a wide range of valid/invalid option combinations (string, array, regex-with-template, file-based, custom newline counts), and a small separate suite covers comment-parser.js directly. A GitHub Actions workflow runs npm test (lint + unit) on push and PR. The codebase itself is untyped ES5-style JavaScript with no modern tooling beyond the project’s own .eslintrc.yml, and error handling is minimal - malformed header files simply throw.

What Makes It Unique The plugin doesn’t introduce a novel technique - header/license-comment enforcement is a well-established category of ESLint rule - but its option surface is more flexible than most single-purpose competitors: per-line regex patterns with separate template values let a header contain data that varies per file (e.g. a copyright year) while still supporting eslint --fix, and the file-based option lets teams share one header definition across configs without duplicating it inline.