# headers/header-format 📝 Verifies the content and format of a file's leading comment block. 🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). While there are several rules that enforce the existence of headers in source files, these often conflict with tools that use or add preprocessor directives or pragmas embedded in these comments (e.g. jest and `@jest-environment`). This rule exists to enforce the existence of specific header content while maintaining these directives. ## Rule Details This rule allows developers to enforce the format and presence of common header content (e.g. copyright information) while preserving pragma expressions included in the same comment block. ### Templates #### Variables The provided header content can be formatted with variable information using the `variables` configuration option. Keys within the header content must be wrapped in braces to be formatted properly. For example, the configuration: ```json { ... "content": "This is an {exampleKey}.", "variables": { "exampleKey": "example value" } } ``` produces the following header: ```js /** * This is an example value. */ ``` #### Patterns Regular expressions can be enforced using the `patterns` configuration option. Keys within the header content must be wrapped in parens to be validated properly. For example, the configuration: ```json { ... "content": "This is an example (examplePattern).", "patterns": { "examplePattern": { "pattern": "\\d{5}", "defaultValue": "12345" } } } ``` produces the following header: ```js /** * This is an example 12345. */ ``` While **12345** is the default value, any 5 digit number would be a valid substitute for this default. **Note: if any configured pattern does NOT declare a default value, it is not possible to automatically fix a header that fails to validate.** ### Examples Examples of **incorrect** code for this rule: ```js module.exports = 42; ``` Examples of **correct** code for this rule: **Example 0: Enforcing content** Configuration: ```json { "rules": { "headers/header-format": [ "error", { "source": "string", "content": "This is a new header." } ] } } ``` Original file: ```js module.exports = 42; ``` Fixed file: ```js /** * This is a new header. */ module.exports = 42; ``` **Example 1: Enforcing content from a file** Configuration: ```json { "rules": { "headers/header-format": [ "error", { "source": "file", "path": "./LICENSE" } ] } } ``` LICENSE: ```txt Copyright Star Date 100598.1 United Federation of Planets. All rights reserved. ``` Original file: ```js /** * @author James T. Kirk */ module.exports = 1701; ``` Fixed file: ```js /** * Copyright Star Date 100598.1 United Federation of Planets. All rights reserved. * * @author James T. Kirk */ module.exports = 1701; ``` **Example 2: Using template variables** Configuration: ```json { "rules": { "headers/header-format": [ "error", { "source": "string", "content": "Copyright Star Date {stardate} {company}. All rights reserved.", "variables": { "stardate": "101012.2", "company": "United Federation of Planets" } } ] } } ``` Original file: ```js /** * @author Jean-Luc Picard */ module.exports = "1701-D"; ``` Fixed file: ```js /** * Copyright Star Date 101012.2 United Federation of Planets. All rights reserved. * * @author Jean-Luc Picard */ module.exports = "1701-D"; ``` **Example 3: Enforcing patterns** Using the following configuration, patterns are used to validate content in existing headers: ```json { "rules": { "headers/header-format": [ "error", { "source": "string", "content": "Copyright (year) {company}. All rights reserved.", "variables": { "company": "Deep Space 9" }, "patterns": { "year": { "pattern": "\\d{4}", "defaultValue": "2204" } } } ] } } ``` The following file would validate successfully: ```js /** * Copyright 2203 Deep Space 9. All rights reserved. */ module.exports = 42; ``` Alternatively, the plugin can apply a fix to the following invalid file: ```js /** * Copyright 40000 Imperium. All rights reserved. */ module.exports = 42; ``` And get the following header: ```js /** * Copyright 2204 Deep Space 9. All rights reserved. */ module.exports = 42; ``` ### Usage with Vue This project supports the AST generated by the `vue-eslint-parser` package. To properly apply rules from this plugin to Vue files, you must: 1. Specify the `vue-eslint-parser` in the configuration's `languageOptions.parser` field, and 2. Set the `enableVueSupport` flag for the appropriate rules ```js import headers from "eslint-plugin-headers"; import vueEslintParser from "vue-eslint-parser"; export default [ { plugins: { headers, }, files: ["**/*.vue"], rules: { "headers/header-format": [ "error", { source: "string", content: "This is a header.", enableVueSupport: true, }, ], }, languageOptions: { parser: vueEslintParser, }, }, ]; ``` With this configuration the following file would be transformed like so: Before: ```vue ``` After applying the fix: ```vue ``` Since the `vue-eslint-parser` package strives to maintain compatibility with rules targeting JavaScript, it exposes Vue AST tokens to rules in different ways than the default ESlint parser. The means of exposing HTML Comment nodes are of specific interest to this plugin, and the mechanism to access these are substantially different than how a plugin would typically read a comment node, making it necessary to both specify this particular parser as well as setting the flag. ### Options | Name | Type | Required | Default | Description | | ---------------- | ----------------------------------------------------------------- | ----------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | source | `"file" \| "string"` | Yes | | Indicates how the header content is supplied. | | style | `"line" \| "jsdoc"` | No | `"jsdoc"` | Indicates the comment style to enforce. A leading line-style comment block will only include adjacent line comments, although a line comment's content may be empty. No effect if `enableVueSupport: true`. | | content | string | When `source: "string"` | | The string to enforce in the header comment. | | path | string | When `source: "file"` | | The path to a file containing the header content to enforce. | | preservePragmas | boolean | No | `true` | Preserves existing pragma expressions in leading comments when updating header. No effect when `style: "line"`. | | blockPrefix | string | No | [See below](#default-prefixes-and-suffixes) | Content at the start of the leading comment block. | | blockSuffix | string | No | [See below](#default-prefixes-and-suffixes) | Content at the end of the leading comment block. | | linePrefix | string | No | [See below](#default-prefixes-and-suffixes) | Content prepended to the start of each line of content. | | trailingNewlines | number | No | | Number of empty lines to enforce after the leading comment. | | variables | object | No | | The keys to find and values to fill when formatting the provided header. Values must be strings. | | patterns | `{ [key: string] : { pattern: string; defaultValue?: string; } }` | No | | The keys to find and Regex patterns to validate when matching the provided header. **WARNING!** Default values must be provided for errors to be `--fix`able. | | enableVueSupport | boolean | No | `false` | **EXPERIMENTAL!** Enable support for parsing `.vue` files. Must be used with `vue-eslint-parser`. [See above](#usage-with-vue) for details. | #### Default Prefixes and Suffixes Example configuration: ```js export default [ { // ... rules: { "headers/header-format": [ "error", { source: "string", content: "This is a header.", // ...{Additional Configuration} }, ], }, }, ]; ``` The subsequent section titles contain the additional configuration inserted above, and the resulting comment that will be produced. ##### style: "line" Expected/produced header: ```js // This is a header. ``` - Default block prefix: None - Default block suffix: None - Default line prefix: `" "` ##### style: "jsdoc" Expected/produced header: ```js /** * This is a header. */ ``` - Default block prefix: `"*\n"` - Default block suffix: `"\n "` - Default line prefix: `" * "` ##### enableVueSupport: true Expected/produced header: ```vue ``` - Default block prefix: `"\n"` - Default block suffix: `"\n"` - Default line prefix: `" "` ## When Not To Use It Do not use this rule if you have no use for enforcing leading text content in a file header.