feat(sh): add support for file pragmas

Closes un-ts#377

.changeset/sharp-days-kiss.md

@@ -0,0 +1,5 @@
+---
+'prettier-plugin-sh': minor
+---
+
+add support for file pragmas

packages/sh/package.json

@@ -40,6 +40,10 @@
     "mvdan-sh": "^0.10.1",
     "sh-syntax": "^0.4.2"
   },
+  "devDependencies": {
+    "@types/common-tags": "^1.8.4",
+    "common-tags": "^1.8.2"
+  },
   "publishConfig": {
     "access": "public"
   }

packages/sh/src/index.ts

@@ -108,6 +108,44 @@ const ShPlugin: Plugin<Node | ShSyntaxNode> = {
         }
       },
       astFormat: 'sh',
+      hasPragma: (text: string): boolean => {
+        // We don't want to parse every file twice but Prettier's interface
+        // isn't conducive to caching/memoizing an upstream Parser, so we're
+        // going with some minor Regex hackery.
+        //
+        // Only read empty lines, comments, and shebangs at the start of the file.
+        // We do not support Bash's pseudo-block comments.
+
+        // No, we don't support unofficial block comments.
+        const commentLineRegex = /^\s*(#(?<comment>.*))?$/gm
+        let lastIndex = -1
+
+        // Only read leading comments, skip shebangs, and check for the pragma.
+        // We don't want to have to parse every file twice.
+        for (;;) {
+          const match = commentLineRegex.exec(text)
+
+          // Found "real" content, EoF, or stuck in a loop.
+          if (match == null || match.index !== lastIndex + 1) {
+            return false
+          }
+
+          lastIndex = commentLineRegex.lastIndex
+          const comment = match.groups?.comment?.trim()
+
+          // Empty lines and shebangs have no captures
+          if (comment == null) {
+            continue
+          }
+
+          if (
+            comment.startsWith('@prettier') ||
+            comment.startsWith('@format')
+          ) {
+            return true
+          }
+        }
+      },
       locStart: node =>
         isFunction(node.Pos) ? node.Pos().Offset() : node.Pos.Offset,
       locEnd: node =>

packages/sh/test/parser.spec.ts

@@ -0,0 +1,116 @@
+import { stripIndent } from 'common-tags'
+import { describe, it, assert, expect } from 'vitest'
+
+import ShPlugin from 'prettier-plugin-sh'
+
+describe('parser', () => {
+  const hasPragma = ShPlugin.parsers?.sh?.hasPragma
+  assert(hasPragma != null)
+
+  describe('should detect pragmas', () => {
+    it('at the top of the file', () => {
+      expect(
+        hasPragma(stripIndent`
+        # @prettier
+        FOO="bar"
+      `),
+      ).toBeTruthy()
+    })
+
+    it('with extra leading spaces', () => {
+      expect(
+        hasPragma(stripIndent`
+        #   @prettier
+        FOO="bar"
+      `),
+      ).toBeTruthy()
+    })
+
+    it('with no leading space', () => {
+      expect(
+        hasPragma(stripIndent`
+        #@prettier
+        FOO="bar"
+      `),
+      ).toBeTruthy()
+    })
+
+    it('with "format" pragma instead', () => {
+      expect(
+        hasPragma(stripIndent`
+        # @format
+        FOO="bar"
+      `),
+      ).toBeTruthy()
+    })
+
+    it('after leading whitespace', () => {
+      expect(
+        hasPragma(stripIndent`
+
+
+        # @prettier
+        FOO="bar"
+      `),
+      ).toBeTruthy()
+    })
+
+    it('after leading comments', () => {
+      expect(
+        hasPragma(stripIndent`
+        # Testing!
+
+        #
+        #
+        # @prettier
+        FOO="bar"
+      `),
+      ).toBeTruthy()
+    })
+
+    it('after a shebang', () => {
+      expect(
+        hasPragma(stripIndent`
+        #!/bin/bash
+        #
+
+        # @prettier
+        FOO="bar"
+      `),
+      ).toBeTruthy()
+    })
+
+    it('unless none exist', () => {
+      expect(
+        hasPragma(stripIndent`
+        FOO="bar"
+      `),
+      ).toBeFalsy()
+    })
+
+    it('unless the file is empty', () => {
+      expect(hasPragma('')).toBeFalsy()
+    })
+
+    it('unless it comes after real content', () => {
+      expect(
+        hasPragma(stripIndent`
+        FOO="bar"
+        # @prettier
+      `),
+      ).toBeFalsy()
+    })
+
+    it('unless it comes after real content and comments', () => {
+      expect(
+        hasPragma(stripIndent`
+
+        # Test
+        #!
+        FOO="bar"
+        # @prettier
+      `),
+      ).toBeFalsy()
+    })
+  })
+})