Skip to content

Latest commit

 

History

History
318 lines (253 loc) · 9.59 KB

header-format.md

File metadata and controls

318 lines (253 loc) · 9.59 KB
Raw

Verifies the content and format of a file's leading comment block (headers/header-format)

🔧 This rule is automatically fixable by the --fix CLI option.

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

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:

{
  ...
  "content": "This is an {exampleKey}.",
  "variables": {
    "exampleKey": "example value"
  }
}

produces the following header:

/**
 * This is an example value.
 */

Examples

Examples of incorrect code for this rule:

module.exports = 42;

Examples of correct code for this rule:

Example 0: Enforcing content Configuration:

{
  "rules": {
    "headers/header-format": [
      "error",
      {
        "source": "string",
        "content": "This is a new header."
      }
    ]
  }
}

Original file:

module.exports = 42;

Fixed file:

/**
 * This is a new header.
 */
module.exports = 42;

Example 1: Enforcing content from a file Configuration:

{
  "rules": {
    "headers/header-format": [
      "error",
      {
        "source": "file",
        "path": "./LICENSE"
      }
    ]
  }
}

LICENSE:

Copyright Star Date 100598.1 United Federation of Planets. All rights reserved.

Original file:

/**
 * @author James T. Kirk
 */
module.exports = 1701;

Fixed file:

/**
 * 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:

{
  "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:

/**
 * @author Jean-Luc Picard
 */
module.exports = "1701-D";

Fixed file:

/**
 * Copyright Star Date 101012.2 United Federation of Planets. All rights reserved.
 *
 * @author Jean-Luc Picard
 */
module.exports = "1701-D";

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
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:

<template>
  <p>This is an example Vue file.</p>
</template>

After applying the fix:

<!--
  This is a header.
-->
<template>
  <p>This is an example Vue file.</p>
</template>

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 Content at the start of the leading comment block.
blockSuffix string No See below Content at the end of the leading comment block.
linePrefix string No See below 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.
enableVueSupport boolean No false EXPERIMENTAL! Enable support for parsing .vue files. Must be used with vue-eslint-parser. See above for details.

Default Prefixes and Suffixes

Example configuration:

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:

// This is a header.
  • Default block prefix: None
  • Default block suffix: None
  • Default line prefix: " "
style: "jsdoc"

Expected/produced header:

/**
 * This is a header.
 */
  • Default block prefix: "*\n"
  • Default block suffix: "\n "
  • Default line prefix: " * "
enableVueSupport: true

Expected/produced header:

<!--
  This is a header.
-->
  • 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.