Don't lint a shebang as a comment (#1134)

Tree-sitter reports the `#!` line of a script as a comment, because in
Python, Ruby and Julia that is exactly what it looks like. Vale then lints
the interpreter path as prose, so `#!/usr/bin/env python3` draws an alert
about 'env' that the author has no way to act on.

Drop a comment that starts at the first byte of the file and begins with
`#!`, which is also all the kernel accepts as a shebang, so a `#!` written
anywhere else stays a comment.

Fixes #631

Author: Eljees

internal/lint/code/comments.go

@@ -149,5 +149,26 @@ func GetComments(source []byte, lang *Language) ([]Comment, error) {
 		})
 	}
 
-	return coalesce(comments), nil
+	return coalesce(dropShebang(comments)), nil
+}
+
+// dropShebang removes a leading `#!` line.
+//
+// A shebang names the interpreter a script runs under. Languages that use `#`
+// for comments give tree-sitter no way to tell the two apart, so it arrives
+// here as a comment and is linted as prose -- a path like `/usr/bin/env` then
+// draws alerts about words the author never wrote. See #631.
+//
+// Only the very first line of the file qualifies, which is also all the kernel
+// accepts, so a `#!` written anywhere else stays a comment.
+func dropShebang(comments []Comment) []Comment {
+	for i, c := range comments {
+		if c.Line != 1 || c.Offset != 0 {
+			continue
+		} else if !strings.HasPrefix(c.Source, "#!") {
+			continue
+		}
+		return append(comments[:i:i], comments[i+1:]...)
+	}
+	return comments
 }

testdata/e2e/lint.yaml

@@ -148,6 +148,30 @@ cases:
       test.py:35:8:vale.Annotations:'NOTE' left in text
       test.py:37:5:vale.Annotations:'TODO' left in text
 
+  - name: python/shebang
+    about: "#631 -- a shebang names an interpreter, so it isn't a comment"
+    files:
+      .vale.ini: |
+        StylesPath = styles
+        MinAlertLevel = suggestion
+
+        [*.py]
+        BasedOnStyles = Test
+      styles/Test/Env.yml: |
+        extends: existence
+        message: "Use 'environment' rather than 'env'."
+        level: error
+        tokens:
+          - env
+      test.py: |
+        #!/usr/bin/env python3
+        # Read the env before starting.
+        print("hello")
+    args: test.py
+    exit: 1
+    want: |
+      test.py:2:12:Test.Env:Use 'environment' rather than 'env'.
+
   - name: cpp
     args: test.cc
     exit: 0