Enforce Blank Line after File Header (palantir#3740)

* Enforce Blank Line after File Header

* Fix linter errors

* Remove extraneous part of enforce argument statement

* Extract regex into a constant, use test() over match(), return results directly rather than variable assignment

* - update fixer for newline, tests

src/rules/fileHeaderRule.ts

@@ -18,50 +18,60 @@
 import * as ts from "typescript";
 import * as Lint from "../index";
 
+const ENFORCE_TRAILING_NEWLINE = "enforce-trailing-newline";
+
 export class Rule extends Lint.Rules.AbstractRule {
     /* tslint:disable:object-literal-sort-keys */
     public static metadata: Lint.IRuleMetadata = {
         ruleName: "file-header",
-        description: "Enforces a certain header comment for all files, matched by a regular expression.",
+        description:
+            "Enforces a certain header comment for all files, matched by a regular expression.",
         optionsDescription: Lint.Utils.dedent`
             The first option, which is mandatory, is a regular expression that all headers should match.
             The second argument, which is optional, is a string that should be inserted as a header comment
-            if fixing is enabled and no header that matches the first argument is found.`,
+            if fixing is enabled and no header that matches the first argument is found.
+            The third argument, which is optional, is a string that denotes whether or not a newline should
+            exist on the header.`,
         options: {
             type: "array",
             items: [
                 {
-                    type: "string",
+                    type: "string"
                 },
                 {
-                    type: "string",
+                    type: "string"
                 },
+                {
+                    type: "string"
+                }
             ],
             additionalItems: false,
             minLength: 1,
-            maxLength: 2,
+            maxLength: 3
         },
-        optionExamples: [[true, "Copyright \\d{4}", "Copyright 2017"]],
+        optionExamples: [[true, "Copyright \\d{4}", "Copyright 2018", ENFORCE_TRAILING_NEWLINE]],
         hasFix: true,
         type: "style",
-        typescriptOnly: false,
+        typescriptOnly: false
     };
     /* tslint:enable:object-literal-sort-keys */
 
-    public static FAILURE_STRING = "missing file header";
+    public static MISSING_HEADER_FAILURE_STRING = "missing file header";
+    public static MISSING_NEW_LINE_FAILURE_STRING = "missing new line following the file header";
 
     public apply(sourceFile: ts.SourceFile): Lint.RuleFailure[] {
         const { text } = sourceFile;
         const headerFormat = new RegExp(this.ruleArguments[0] as string);
         const textToInsert = this.ruleArguments[1] as string | undefined;
+        const enforceExtraTrailingLine =
+            this.ruleArguments.indexOf(ENFORCE_TRAILING_NEWLINE) !== -1;
 
         // ignore shebang if it exists
         let offset = text.startsWith("#!") ? text.indexOf("\n") : 0;
         // returns the text of the first comment or undefined
-        const commentText = ts.forEachLeadingCommentRange(
-            text,
-            offset,
-            (pos, end, kind) => text.substring(pos + 2, kind === ts.SyntaxKind.SingleLineCommentTrivia ? end : end - 2));
+        const commentText = ts.forEachLeadingCommentRange(text, offset, (pos, end, kind) =>
+            text.substring(pos + 2, kind === ts.SyntaxKind.SingleLineCommentTrivia ? end : end - 2)
+        );
 
         if (commentText === undefined || !headerFormat.test(commentText)) {
             const isErrorAtStart = offset === 0;
@@ -71,24 +81,94 @@ export class Rule extends Lint.Rules.AbstractRule {
             const leadingNewlines = isErrorAtStart ? 0 : 1;
             const trailingNewlines = isErrorAtStart ? 2 : 1;
 
-            const fix = textToInsert !== undefined
-                ? Lint.Replacement.appendText(offset, this.createComment(sourceFile, textToInsert, leadingNewlines, trailingNewlines))
-                : undefined;
-            return [new Lint.RuleFailure(sourceFile, offset, offset, Rule.FAILURE_STRING, this.ruleName, fix)];
+            const fix =
+                textToInsert !== undefined
+                    ? Lint.Replacement.appendText(
+                          offset,
+                          this.createComment(
+                              sourceFile,
+                              textToInsert,
+                              leadingNewlines,
+                              trailingNewlines
+                          )
+                      )
+                    : undefined;
+            return [
+                new Lint.RuleFailure(
+                    sourceFile,
+                    offset,
+                    offset,
+                    Rule.MISSING_HEADER_FAILURE_STRING,
+                    this.ruleName,
+                    fix
+                )
+            ];
+        }
+
+        const trailingNewLineViolation =
+            enforceExtraTrailingLine &&
+            headerFormat.test(commentText) &&
+            this.doesNewLineEndingViolationExist(text, offset);
+
+        if (trailingNewLineViolation) {
+            const trailingCommentRanges = ts.getTrailingCommentRanges(text, offset);
+            const endOfComment = trailingCommentRanges![0].end;
+            const lineEnding = this.generateLineEnding(sourceFile);
+            const fix =
+                textToInsert !== undefined
+                    ? Lint.Replacement.appendText(endOfComment, lineEnding)
+                    : undefined;
+
+            return [
+                new Lint.RuleFailure(
+                    sourceFile,
+                    offset,
+                    offset,
+                    Rule.MISSING_NEW_LINE_FAILURE_STRING,
+                    this.ruleName,
+                    fix
+                )
+            ];
         }
+
         return [];
     }
 
-    private createComment(sourceFile: ts.SourceFile, commentText: string, leadingNewlines = 1, trailingNewlines = 1) {
-        const maybeCarriageReturn = sourceFile.text[sourceFile.getLineEndOfPosition(0)] === "\r" ? "\r" : "";
-        const lineEnding = `${maybeCarriageReturn}\n`;
-        return lineEnding.repeat(leadingNewlines) + [
-            "/*!",
-            // split on both types of line endings in case users just typed "\n" in their configs
-            // but are working in files with \r\n line endings
-            // Trim trailing spaces to play nice with `no-trailing-whitespace` rule
-            ...commentText.split(/\r?\n/g).map((line) => ` * ${line}`.replace(/\s+$/, "")),
-            " */",
-        ].join(lineEnding) + lineEnding.repeat(trailingNewlines);
+    private createComment(
+        sourceFile: ts.SourceFile,
+        commentText: string,
+        leadingNewlines = 1,
+        trailingNewlines = 1
+    ) {
+        const lineEnding = this.generateLineEnding(sourceFile);
+        return (
+            lineEnding.repeat(leadingNewlines) +
+            [
+                "/*!",
+                // split on both types of line endings in case users just typed "\n" in their configs
+                // but are working in files with \r\n line endings
+                // Trim trailing spaces to play nice with `no-trailing-whitespace` rule
+                ...commentText.split(/\r?\n/g).map(line => ` * ${line}`.replace(/\s+$/, "")),
+                " */"
+            ].join(lineEnding) +
+            lineEnding.repeat(trailingNewlines)
+        );
+    }
+
+    private generateLineEnding(sourceFile: ts.SourceFile) {
+        const maybeCarriageReturn =
+            sourceFile.text[sourceFile.getLineEndOfPosition(0)] === "\r" ? "\r" : "";
+        return `${maybeCarriageReturn}\n`;
+    }
+
+    private doesNewLineEndingViolationExist(text: string, offset: number): boolean {
+        const entireComment = ts.forEachLeadingCommentRange(text, offset, (pos, end) =>
+            text.substring(pos, end + 2)
+        );
+
+        const NEW_LINE_FOLLOWING_HEADER = /^.*((\r)?\n){2,}$/gm;
+        return (
+            entireComment !== undefined && NEW_LINE_FOLLOWING_HEADER.test(entireComment) !== null
+        );
     }
 }

test/rules/file-header/bad-newline/test.ts.fix

@@ -0,0 +1,11 @@
+/*!
+ * Good header 2
+ */
+
+export class A {
+    public x = 1;
+
+    public B() {
+        return 2;
+    }
+}

test/rules/file-header/bad-newline/test.ts.lint

@@ -0,0 +1,11 @@
+/*!
+~nil [missing new line following the file header]
+ * Good header 2
+ */
+export class A {
+    public x = 1;
+
+    public B() {
+        return 2;
+    }
+}

test/rules/file-header/bad-newline/tslint.json

@@ -0,0 +1,5 @@
+{
+    "rules": {
+        "file-header": [true, "Good header \\d", "Good header 2", "enforce-trailing-newline"]
+    }
+}

test/rules/file-header/bad-single-newline/test.ts.fix

@@ -0,0 +1,12 @@
+/*!
+ * Good header 2
+ */
+
+// Bad header
+export class A {
+    public x = 1;
+
+    public B() {
+        return 2;
+    }
+}

test/rules/file-header/bad-single-newline/test.ts.lint

@@ -0,0 +1,9 @@
+// Bad header
+~nil [missing file header]
+export class A {
+    public x = 1;
+
+    public B() {
+        return 2;
+    }
+}

test/rules/file-header/bad-single-newline/tslint.json

@@ -0,0 +1,5 @@
+{
+    "rules": {
+        "file-header": [true, "Good header \\d", "Good header 2", "enforce-trailing-newline"]
+    }
+}