@tony.ganchev/eslint-plugin-header 3.1.13 → 3.2.1

package/lib/comment-parser.js

@@ -33,8 +33,8 @@ const assert = require("node:assert");
  * This is a really simple and dumb parser, that looks just for a
  * single kind of comment. It won't detect multiple block comments.
  * @param {string} commentText comment text.
- * @returns {['block' | 'line', string | string[]]} comment type and comment
- *                                                  content broken into lines.
+ * @returns {['block' | 'line', string[]]} comment type and comment content
+ *                                         broken into lines.
  */
 module.exports = function commentParser(commentText) {
     assert.strictEqual(typeof commentText, "string");
@@ -46,7 +46,7 @@ module.exports = function commentParser(commentText) {
             text.split(/\r?\n/).map((line) => line.substring(2))
         ];
     } else if (text.startsWith("/*") && text.endsWith("*/")) {
-        return ["block", text.substring(2, text.length - 2)];
+        return ["block", text.substring(2, text.length - 2).split(/\r?\n/)];
     } else {
         throw new Error(
             "Could not parse comment file: the file must contain either just line comments (//) or a single block " +

package/lib/rules/header.js

@@ -30,7 +30,7 @@ const os = require("node:os");
 const commentParser = require("../comment-parser");
 const { contextSourceCode } = require("./eslint-utils");
 const { description, recommended, url } = require("./header.docs");
-const { commentTypeOptions, lineEndingOptions, schema } = require("./header.schema");
+const { lineEndingOptions, commentTypeOptions, schema } = require("./header.schema");
 
 /**
  * Import type definitions.
@@ -46,13 +46,31 @@ const { commentTypeOptions, lineEndingOptions, schema } = require("./header.sche
 
 /**
  * Local type definitions.
- * @typedef {{ pattern: string, template?: string }} HeaderLinePattern
- * @typedef {string | HeaderLinePattern} HeaderLine
- * @typedef {(HeaderLine | HeaderLine[])} HeaderLines
- * @typedef {'unix' | 'windows'} LineEndingOption
+ * @typedef {{ pattern: string | RegExp, template?: string }} HeaderLinePattern
+ * @typedef {string | RegExp | HeaderLinePattern} HeaderLine
+ * @typedef {HeaderLine | HeaderLine[]} HeaderLines
+ * @typedef {'os' | 'unix' | 'windows'} LineEndingOption
  * @typedef {{ lineEndings?: LineEndingOption }} HeaderSettings
  * @typedef {'block' | 'line'} CommentType
- * @typedef {[template: string] |
+ * @typedef {{
+ *      file: string,
+ *      encoding?: BufferEncoding
+ *  }
+ * } FileBasedConfig
+ * @typedef {{
+ *      commentType: CommentType,
+ *      lines: HeaderLine[]
+ *  }
+ * } InlineConfig
+ * @typedef {{ minimum?: number }} TrailingEmptyLines
+ * @typedef {{
+ *      header: FileBasedConfig | InlineConfig,
+ *      trailingEmptyLines?: TrailingEmptyLines
+ *  }
+ *  & HeaderSettings
+ * } HeaderOptions
+ * @typedef {[HeaderOptions] |
+ *  [template: string] |
  *  [template: string, settings: HeaderSettings] |
  *  [type: CommentType, lines: HeaderLines] |
  *  [type: CommentType, lines: HeaderLines, settings: HeaderSettings] |
@@ -77,7 +95,8 @@ const { commentTypeOptions, lineEndingOptions, schema } = require("./header.sche
  *                                        otherwise.
  */
 function isPattern(object) {
-    return typeof object === "object" && Object.prototype.hasOwnProperty.call(object, "pattern");
+    return typeof object === "object"
+        && (Object.prototype.hasOwnProperty.call(object, "pattern"));
 }
 
 /**
@@ -291,39 +310,25 @@ function genEmptyLinesFixer(leadingComments, eol, missingEmptyLinesCount) {
     };
 }
 
-/**
- * Finds the option parameter within the list of rule config options.
- * @param {AllHeaderOptions} options the config options passed to the rule.
- * @returns {HeaderSettings | null} the settings parameter or `null` if no such
- *                                  is defined.
- */
-function findSettings(options) {
-    const lastOption = options[options.length - 1];
-    if (typeof lastOption === "object" && !Array.isArray(lastOption) && lastOption !== null
-        && !Object.prototype.hasOwnProperty.call(lastOption, "pattern")) {
-        return /** @type {HeaderSettings} */ (lastOption);
-    }
-    return null;
-}
-
 /**
  * Returns the used line-termination characters per the rule's config if any or
  * else based on the runtime environments.
- * @param {AllHeaderOptions} options rule configuration.
+ * @param {LineEndingOption} style line-ending styles.
  * @returns {'\n' | '\r\n'} the correct line ending characters for the
- * environment.
+ *                          environment.
  */
-function getEOL(options) {
-    const settings = findSettings(options);
-    if (settings) {
-        if (settings.lineEndings === lineEndingOptions.unix) {
+function getEol(style) {
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(lineEndingOptions, style), true,
+        "lineEnding style should have been populated in normalizeOptions().");
+    switch (style) {
+        case lineEndingOptions.unix:
             return "\n";
-        }
-        if (settings.lineEndings === lineEndingOptions.windows) {
+        case lineEndingOptions.windows:
             return "\r\n";
-        }
+        case lineEndingOptions.os:
+        default:
+            return /** @type {'\n' | '\r\n'} */ (os.EOL);
     }
-    return /** @type {'\n' | '\r\n'} */ (os.EOL);
 }
 
 /**
@@ -337,6 +342,155 @@ function hasHeader(src) {
     return srcWithoutShebang.startsWith("/*") || srcWithoutShebang.startsWith("//");
 }
 
+/**
+ * asserts on an expression and adds template texts to the failure message.
+ * Helper to write cleaner code.
+ * @param {boolean} condition assert condition.
+ * @param {string} message assert message on violation.
+ */
+function schemaAssert(condition, message) {
+    assert.strictEqual(condition, true, message + " - should have been handled by eslint schema validation.");
+}
+
+/**
+ * Ensures that if legacy options as defined in the original
+ * `eslint-plugin-header` are used, they'd be converted to the new object-based
+ * configuration. This is not a normalized internal representation of the
+ * options in that some settings are still union types and unspecified
+ * properties are not replaced by defaults. If the options follow the new
+ * format, a simple seep copy would be returned.
+ * @param {AllHeaderOptions} originalOptions the options as configured by the
+ *                                           user.
+ * @returns {HeaderOptions} the transformed new-style options with no
+ *                             normalization.
+ */
+function transformLegacyOptions(originalOptions) {
+    schemaAssert(originalOptions?.length > 0,
+        "header options are required (at least one in addition to the severity)");
+    schemaAssert(originalOptions.length <= 4,
+        "header options should not be more than four (five including issue severity)");
+    if (originalOptions.length === 1 && typeof originalOptions[0] === "object") {
+        // The user chose to use the new-style config. We pass a copy of the
+        // incoming sole option to not mess with ESLint not relying on the old
+        // values of the option.
+        return structuredClone(originalOptions[0]);
+    }
+    // The user chose the legacy-style config. Transform them to new-style
+    // config.
+    schemaAssert(typeof originalOptions[0] === "string",
+        "first header option after severity should be either a filename or 'block' | 'line'");
+    /** @type {HeaderOptions} */
+    const transformedOptions = {};
+    // populate header
+    if (
+        originalOptions.length === 1
+        || (
+            originalOptions.length === 2
+            && typeof originalOptions[1] === "object"
+            && !Array.isArray(originalOptions[1])
+            && !isPattern(/** @type {HeaderLine} */(originalOptions[1]))
+        )) {
+        transformedOptions.header = { file: originalOptions[0], encoding: "utf8" };
+    } else {
+        schemaAssert(Object.prototype.hasOwnProperty.call(commentTypeOptions, originalOptions[0]),
+            "Only 'block' or 'line' is accepted as comment type");
+        schemaAssert(
+            typeof originalOptions[1] === "string"
+            || Array.isArray(originalOptions[1])
+            || isPattern(/** @type {HeaderLine} */(originalOptions[1])),
+            "second header option after severity should be a string, a pattern, or an array of the previous two");
+        transformedOptions.header = {
+            commentType: /** @type {CommentType} */ (originalOptions[0]),
+            lines: /** @type {HeaderLine[]} */ (
+                Array.isArray(originalOptions[1])
+                    ? originalOptions[1]
+                    : [originalOptions[1]])
+        };
+    }
+    // configure required line settings
+    if (originalOptions.length >= 3) {
+        if (typeof originalOptions[2] === "number") {
+            transformedOptions.trailingEmptyLines = { minimum: originalOptions[2] };
+            if (originalOptions.length === 4) {
+                schemaAssert(typeof originalOptions[3] === "object",
+                    "Fourth header option after severity should be either number of required trailing empty lines or " +
+                    "a settings object");
+                Object.assign(transformedOptions, originalOptions[3]);
+            }
+        } else {
+            schemaAssert(typeof originalOptions[2] === "object",
+                "Third header option after severity should be either number of required trailing empty lines or a " +
+                "settings object");
+            Object.assign(transformedOptions, originalOptions[2]);
+        }
+    }
+    return transformedOptions;
+}
+
+/**
+ * @param {FileBasedConfig | InlineConfig} config the header configuration.
+ * @returns {config is FileBasedConfig} true if `config` is `FileBasedConfig`.
+ */
+function isFileBasedHeaderConfig(config) {
+    return Object.prototype.hasOwnProperty.call(config, "file");
+}
+
+/**
+ * @param {FileBasedConfig | InlineConfig} config the header configuration.
+ * @returns {asserts config is InlineConfig} asserts `config` is
+ *                                               `LineBasedConfig`.
+ */
+function assertLineBasedHeaderConfig(config) {
+    assert.ok(Object.prototype.hasOwnProperty.call(config, "lines"));
+}
+
+/**
+ * Transforms a set of new-style options adding defaults and standardizing on
+ * one of multiple config styles.
+ * @param {HeaderOptions} originalOptions new-style options to normalize.
+ * @returns {HeaderOptions} normalized options.
+ */
+function normalizeOptions(originalOptions) {
+    const options = structuredClone(originalOptions);
+
+    if (isFileBasedHeaderConfig(originalOptions.header)) {
+        const text = fs.readFileSync(originalOptions.header.file, originalOptions.header.encoding || "utf8");
+        const [commentType, lines] = commentParser(text);
+        options.header = { commentType, lines };
+    }
+    assertLineBasedHeaderConfig(options.header);
+    options.header.lines = options.header.lines.flatMap(
+        (line) => {
+            if (typeof line === "string") {
+                return /** @type {HeaderLine[]} */(line.split(/\r?\n/));
+            }
+            if (line instanceof RegExp) {
+                return [{ pattern: line }];
+            }
+            assert.ok(Object.prototype.hasOwnProperty.call(line, "pattern"));
+            const pattern = line.pattern instanceof RegExp ? line.pattern : new RegExp(line.pattern);
+            if (Object.prototype.hasOwnProperty.call(line, "template")) {
+                return [{
+                    pattern,
+                    template: line.template
+                }];
+            }
+            return [{ pattern }];
+        });
+
+    if (!options.lineEndings) {
+        options.lineEndings = "os";
+    }
+
+    if (!options.trailingEmptyLines) {
+        options.trailingEmptyLines = {};
+    }
+    if (typeof options.trailingEmptyLines.minimum !== "number") {
+        options.trailingEmptyLines.minimum = 1;
+    }
+    return options;
+}
+
 /**
  * Calculates the source location of the violation that not enough empty lines
  * follow the header.
@@ -376,7 +530,15 @@ const headerRule = {
         },
         fixable: "whitespace",
         schema,
-        defaultOptions: [{}],
+        defaultOptions: [
+            /** @type {AllHeaderOptions} */
+            {
+                lineEndings: lineEndingOptions.os,
+                trailingEmptyLines: {
+                    minimum: 1
+                }
+            }
+        ],
         messages: {
             headerLineMismatchAtPos: "header line does not match expected after this position; expected: {{expected}}",
             headerLineTooLong: "header line longer than expected",
@@ -396,55 +558,41 @@ const headerRule = {
      * @returns {NodeListener} the rule definition.
      */
     create: function(context) {
-        let options = /** @type {AllHeaderOptions} */ (context.options);
-        const numNewlines = options.length > 2 && typeof options[2] === "number" ? options[2] : 1;
-        const eol = getEOL(options);
-
-        // If just one option then read comment from file
-        if (options.length === 1 || (options.length === 2 && findSettings(options))) {
-            const text = fs.readFileSync(context.options[0], "utf8");
-            options = commentParser(text);
-        }
 
-        const commentType = /** @type {CommentType} */ (options[0].toLowerCase());
-        /** @type {(string | RegExp)[] | string[]} */
-        let headerLines;
+        const newStyleOptions = transformLegacyOptions(/** @type {AllHeaderOptions} */ (context.options));
+        const options = normalizeOptions(newStyleOptions);
+
+        assertLineBasedHeaderConfig(options.header);
+        const commentType = /** @type {CommentType} */ (options.header.commentType);
+
+        const eol = getEol(
+            /** @type {LineEndingOption} */ (options.lineEndings)
+        );
+
         /** @type {string[]} */
         let fixLines = [];
         // If any of the lines are regular expressions, then we can't
         // automatically fix them. We set this to true below once we
         // ensure none of the lines are of type RegExp
-        let canFix = false;
-        if (Array.isArray(options[1])) {
-            canFix = true;
-            headerLines = options[1].map(function(line) {
-                const isRegex = isPattern(line);
-                // Can only fix regex option if a template is also provided
-                if (isRegex) {
-                    if (line.template) {
-                        fixLines.push(line.template);
-                    } else {
-                        canFix = false;
-                    }
-                    return new RegExp(line.pattern);
+        let canFix = true;
+        const headerLines = options.header.lines.map(function(line) {
+            // Can only fix regex option if a template is also provided
+            if (isPattern(line)) {
+                if (Object.prototype.hasOwnProperty.call(line, "template")) {
+                    fixLines.push(/** @type {string} */ (line.template));
                 } else {
-                    fixLines.push(line);
-                    return line;
+                    canFix = false;
+                    fixLines.push("");
                 }
-            });
-        } else {
-            const line = /** @type {HeaderLine} */ (options[1]);
-            if (isPattern(line)) {
-                headerLines = [new RegExp(line.pattern)];
-                fixLines.push(line.template || "");
-                // Same as above for regex and template
-                canFix = !!line.template;
+                return line.pattern;
             } else {
-                canFix = true;
-                headerLines = line.split(/\r?\n/);
-                fixLines = /** @type {string[]} */ (headerLines);
+                fixLines.push(/** @type {string} */ (line));
+                return line;
             }
-        }
+        });
+
+
+        const numLines = /** @type {number} */ (options.trailingEmptyLines?.minimum);
 
         return {
             /**
@@ -469,7 +617,12 @@ const headerRule = {
                             }
                         },
                         messageId: "missingHeader",
-                        fix: genPrependFixer(commentType, context, fixLines, eol, numNewlines)
+                        fix: genPrependFixer(
+                            commentType,
+                            context,
+                            fixLines,
+                            eol,
+                            numLines)
                     });
                     return;
                 }
@@ -495,7 +648,13 @@ const headerRule = {
                             commentType: commentType
                         },
                         fix: canFix
-                            ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines)
+                            ? genReplaceFixer(
+                                commentType,
+                                context,
+                                leadingComments,
+                                fixLines,
+                                eol,
+                                numLines)
                             : null
                     });
                     return;
@@ -518,7 +677,13 @@ const headerRule = {
                                 },
                                 messageId: "incorrectHeader",
                                 fix: canFix
-                                    ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines)
+                                    ? genReplaceFixer(
+                                        commentType,
+                                        context,
+                                        leadingComments,
+                                        fixLines,
+                                        eol,
+                                        numLines)
                                     : null
                             });
                             return;
@@ -544,7 +709,7 @@ const headerRule = {
                                             leadingComments,
                                             fixLines,
                                             eol,
-                                            numNewlines)
+                                            numLines)
                                         : null
                                 });
                                 return;
@@ -577,7 +742,7 @@ const headerRule = {
                                                 leadingComments,
                                                 fixLines,
                                                 eol,
-                                                numNewlines)
+                                                numLines)
                                         });
                                         return;
                                     }
@@ -599,7 +764,7 @@ const headerRule = {
                                                 leadingComments,
                                                 fixLines,
                                                 eol,
-                                                numNewlines)
+                                                numLines)
                                             : null
                                     });
                                     return;
@@ -621,7 +786,7 @@ const headerRule = {
                                                 leadingComments,
                                                 fixLines,
                                                 eol,
-                                                numNewlines)
+                                                numLines)
                                             : null
                                     });
                                     return;
@@ -647,7 +812,7 @@ const headerRule = {
                                                 leadingComments,
                                                 fixLines,
                                                 eol,
-                                                numNewlines)
+                                                numLines)
                                             : null
                                     });
                                     return;
@@ -659,13 +824,13 @@ const headerRule = {
                     const commentRange = leadingComments[headerLines.length - 1].range;
                     assertDefined(commentRange);
                     const actualLeadingEmptyLines = leadingEmptyLines(sourceCode.text.substring(commentRange[1]));
-                    const missingEmptyLines = numNewlines - actualLeadingEmptyLines;
+                    const missingEmptyLines = numLines - actualLeadingEmptyLines;
                     if (missingEmptyLines > 0) {
                         context.report({
                             loc: missingEmptyLinesViolationLoc(leadingComments, actualLeadingEmptyLines),
                             messageId: "noNewlineAfterHeader",
                             data: {
-                                expected: numNewlines,
+                                expected: numLines,
                                 actual: actualLeadingEmptyLines
                             },
                             fix: genEmptyLinesFixer(leadingComments, eol, missingEmptyLines)
@@ -804,7 +969,13 @@ const headerRule = {
                         messageId: errorMessageId,
                         data: errorMessageData,
                         fix: canFix
-                            ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines)
+                            ? genReplaceFixer(
+                                commentType,
+                                context,
+                                leadingComments,
+                                fixLines,
+                                eol,
+                                numLines)
                             : null
                     });
                     return;
@@ -812,13 +983,13 @@ const headerRule = {
 
                 const actualLeadingEmptyLines =
                     leadingEmptyLines(sourceCode.text.substring(firstLeadingCommentRange[1]));
-                const missingEmptyLines = numNewlines - actualLeadingEmptyLines;
+                const missingEmptyLines = numLines - actualLeadingEmptyLines;
                 if (missingEmptyLines > 0) {
                     context.report({
                         loc: missingEmptyLinesViolationLoc(leadingComments, actualLeadingEmptyLines),
                         messageId: "noNewlineAfterHeader",
                         data: {
-                            expected: numNewlines,
+                            expected: numLines,
                             actual: actualLeadingEmptyLines
                         },
                         fix: genEmptyLinesFixer(leadingComments, eol, missingEmptyLines)

package/lib/rules/header.schema.js

@@ -47,22 +47,31 @@ const schema = Object.freeze({
     definitions: {
         commentType: {
             type: "string",
-            enum: [commentTypeOptions.block, commentTypeOptions.line]
+            enum: [commentTypeOptions.block, commentTypeOptions.line],
+            description: "Type of comment to expect as the header."
+        },
+        regExp: {
+            type: "object",
+            properties: {
+                source: { type: "string" }
+            },
+            required: ["source"],
+            additionalProperties: true,
         },
         line: {
             anyOf: [
-                {
-                    type: "string"
-                },
+                { type: "string" },
+                { $ref: "#/definitions/regExp" },
                 {
                     type: "object",
                     properties: {
                         pattern: {
-                            type: "string"
+                            anyOf: [
+                                { type: "string" },
+                                { $ref: "#/definitions/regExp" },
+                            ]
                         },
-                        template: {
-                            type: "string"
-                        }
+                        template: { type: "string" }
                     },
                     required: ["pattern"],
                     additionalProperties: false
@@ -71,9 +80,7 @@ const schema = Object.freeze({
         },
         headerLines: {
             anyOf: [
-                {
-                    $ref: "#/definitions/line"
-                },
+                { $ref: "#/definitions/line" },
                 {
                     type: "array",
                     items: {
@@ -86,18 +93,89 @@ const schema = Object.freeze({
             type: "integer",
             minimum: 0
         },
+        lineEndings: {
+            type: "string",
+            enum: [lineEndingOptions.unix, lineEndingOptions.windows, lineEndingOptions.os],
+            description: "Line endings to use when aut-fixing the violations. Defaults to 'os' which means 'same as " +
+            "system'."
+        },
         settings: {
             type: "object",
             properties: {
-                lineEndings: {
+                lineEndings: { $ref: "#/definitions/lineEndings" },
+            },
+            additionalProperties: false
+        },
+        fileBasedHeader: {
+            type: "object",
+            properties: {
+                file: {
                     type: "string",
-                    enum: [lineEndingOptions.unix, lineEndingOptions.windows]
+                    description: "Name of a file relative to the current directory (no back-tracking) that contains " +
+                        "the header template. It should contain a single block comment or a contiguous number of " +
+                        "line comments."
+                },
+                encoding: {
+                    type: "string",
+                    description: "Character encoding to use when parsing the file. Valid values are all encodings " +
+                        "that can be passed to `fs.readFileSync()`. If not specified, 'utf8' would be used."
+                    // NOTE: default value not supported by the ajv schema
+                    //       validator and there is no way to fix it through the
+                    //       plugin's `meta.defaultOptions`.
                 }
             },
+            required: ["file"],
             additionalProperties: false
         },
+        inlineHeader: {
+            type: "object",
+            properties: {
+                commentType: { $ref: "#/definitions/commentType" },
+                lines: {
+                    type: "array",
+                    items: { $ref: "#/definitions/line" },
+                    description: "List of each line of the header - each being a string to match exactly or a " +
+                        "combination of a regex pattern to match and an optional template string as the fix."
+                }
+            },
+            required: ["commentType", "lines"],
+            additionalProperties: false
+        },
+        trailingEmptyLines: {
+            type: "object",
+            properties: {
+                minimum: {
+                    type: "number",
+                    description: "Number of empty lines required after the header. Defaults to 1.",
+                }
+            },
+            additionalProperties: false,
+            description: "Configuration for how to validate and fix the set of empty lines after the header."
+        },
+        newOptions: {
+            type: "object",
+            properties: {
+                header: {
+                    anyOf: [
+                        { $ref: "#/definitions/fileBasedHeader" },
+                        { $ref: "#/definitions/inlineHeader" }
+                    ]
+                },
+                lineEndings: { $ref: "#/definitions/lineEndings" },
+                trailingEmptyLines: { $ref: "#/definitions/trailingEmptyLines" }
+            },
+            required: ["header"],
+            additionalProperties: false,
+            description: "Object-based extensible configuration format to use with the `header` rule."
+        },
         options: {
             anyOf: [
+                {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 1,
+                    items: { $ref: "#/definitions/newOptions" }
+                },
                 {
                     type: "array",
                     minItems: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tony.ganchev/eslint-plugin-header",
-  "version": "3.1.13",
+  "version": "3.2.1",
   "description": "ESLint plugin to ensure files begin with a given comment, usually a copyright or license notice.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -52,7 +52,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/tonyganchev/eslint-plugin-header.git"
+    "url": "git+https://github.com/tonyganchev/eslint-plugin-header.git"
   },
   "author": "Stuart Knightley",
   "license": "MIT",

package/types/lib/comment-parser.d.ts

@@ -1,3 +1,3 @@
-declare function _exports(commentText: string): ["block" | "line", string | string[]];
+declare function _exports(commentText: string): ["block" | "line", string[]];
 export = _exports;
 //# sourceMappingURL=comment-parser.d.ts.map