From d517b22cf0712b4e4f736b9b5f54c9092efc1582 Mon Sep 17 00:00:00 2001
From: Peter Bengtsson <peterbe@github.com>
Date: Mon, 5 Feb 2024 08:41:15 -0500
Subject: [PATCH] Allow code annotations to have hashbangs (#48995)

---
 src/content-render/tests/annotate.js          | 25 +++++++++++++
 src/content-render/unified/annotate.js        |  9 ++++-
 .../foo/code-snippet-with-hashbang.md         | 36 +++++++++++++++++++
 .../fixtures/content/get-started/foo/index.md |  1 +
 src/fixtures/tests/annotations.js             | 34 ++++++++++++++++++
 5 files changed, 104 insertions(+), 1 deletion(-)
 create mode 100644 src/fixtures/fixtures/content/get-started/foo/code-snippet-with-hashbang.md
 create mode 100644 src/fixtures/tests/annotations.js

diff --git a/src/content-render/tests/annotate.js b/src/content-render/tests/annotate.js
index ffd1ab310d..37a2b318cd 100644
--- a/src/content-render/tests/annotate.js
+++ b/src/content-render/tests/annotate.js
@@ -1,3 +1,4 @@
+import cheerio from 'cheerio'
 import { renderContent } from '#src/content-render/index.js'
 
 const example = `
@@ -22,4 +23,28 @@ describe('annotate', () => {
     // If it is indeed correct, run `jest --updateSnapshot` to update it.
     expect(await renderContent(example)).toMatchSnapshot()
   })
+
+  test('renders bash with hash bang annotations', async () => {
+    const example = `
+\`\`\`bash annotate
+# The next line is the hash bang
+#!/usr/bin/env bash
+
+# Sample comment
+echo "Hello, world!"
+\`\`\`
+`.trim()
+    const res = await renderContent(example)
+    const $ = cheerio.load(res)
+
+    const headerCode = $('header pre').text()
+    expect(headerCode).toMatch(example.split('\n').slice(1, -1).join('\n'))
+    const rows = $('.annotate-row')
+    const notes = $('.annotate-note p', rows)
+    const noteTexts = notes.map((i, el) => $(el).text()).get()
+    expect(noteTexts).toEqual(['The next line is the hash bang', 'Sample comment'])
+    const codes = $('.annotate-code pre', rows)
+    const codeTexts = codes.map((i, el) => $(el).text()).get()
+    expect(codeTexts).toEqual(['#!/usr/bin/env bash', 'echo "Hello, world!"'])
+  })
 })
diff --git a/src/content-render/unified/annotate.js b/src/content-render/unified/annotate.js
index 086ec39b38..ef7e04b7c1 100644
--- a/src/content-render/unified/annotate.js
+++ b/src/content-render/unified/annotate.js
@@ -40,7 +40,7 @@ import { header } from './code-header.js'
 const languages = yaml.load(fs.readFileSync('./data/code-languages.yml', 'utf8'))
 
 const commentRegexes = {
-  number: /^\s*#\s*/, // also known has hash or sharp; but the unicode name is "number sign"
+  number: /^\s*#[^!]\s*/, // also known has hash or sharp; but the unicode name is "number sign"
   slash: /^\s*\/\/\s*/,
   xml: /^\s*<!--\s*/,
   percent: /^\s*%%?\s*/,
@@ -71,6 +71,13 @@ function createAnnotatedNode(node) {
 
   // Group groups into rows
   const rows = chunk(groups, 2)
+  for (const [, note] of rows) {
+    if (note === undefined) {
+      throw new Error(
+        "Unbalanced code meaning there's a comment (note) that is not followed by any code.",
+      )
+    }
+  }
 
   // Render the HTML
   return template({ lang, code, rows })
diff --git a/src/fixtures/fixtures/content/get-started/foo/code-snippet-with-hashbang.md b/src/fixtures/fixtures/content/get-started/foo/code-snippet-with-hashbang.md
new file mode 100644
index 0000000000..3f63e0019b
--- /dev/null
+++ b/src/fixtures/fixtures/content/get-started/foo/code-snippet-with-hashbang.md
@@ -0,0 +1,36 @@
+---
+title: Code snippet with hash-bang
+intro: |
+  Code snippets marked as `annotate` should not get choked up on hash bangs
+  by thinking they're a comment.
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+layout: inline
+---
+
+## Not troublemaker
+
+```bash annotate
+# Let's get started
+if [ -z $file ]; then
+  # This is just a sample
+  echo cat
+  head less
+fi
+# End of the script
+exit 123
+```
+
+## Troublemaker
+
+```bash annotate
+# Has to start with a comment.
+#!/usr/bin/env bash
+
+# This is the if statement
+if [ -z $file ]; then
+  echo cat
+fi
+```
diff --git a/src/fixtures/fixtures/content/get-started/foo/index.md b/src/fixtures/fixtures/content/get-started/foo/index.md
index 4262bd4e7a..6dd089b249 100644
--- a/src/fixtures/fixtures/content/get-started/foo/index.md
+++ b/src/fixtures/fixtures/content/get-started/foo/index.md
@@ -17,4 +17,5 @@ children:
   - /html-short-title
   - /page-with-callout
   - /table-with-ifversions
+  - /code-snippet-with-hashbang
 ---
diff --git a/src/fixtures/tests/annotations.js b/src/fixtures/tests/annotations.js
new file mode 100644
index 0000000000..899c15c52d
--- /dev/null
+++ b/src/fixtures/tests/annotations.js
@@ -0,0 +1,34 @@
+import { getDOM } from '#src/tests/helpers/e2etest.js'
+
+describe('annotations', () => {
+  test('code-snippet-with-hashbang', async () => {
+    const $ = await getDOM('/get-started/foo/code-snippet-with-hashbang')
+    const annotations = $('#article-contents .annotate')
+    expect(annotations.length).toBe(2)
+    // Check http://localhost:4000/en/get-started/foo/code-snippet-with-hashbang
+    // to understand the confidence in the assertions.
+
+    // First code snippet block
+    {
+      const annotation = annotations.eq(0)
+      expect(annotation.find('.annotate-header').length).toBe(1)
+      expect(annotation.find('.annotate-beside').length).toBe(1)
+      expect(annotation.find('.annotate-inline').length).toBe(1)
+      expect(annotation.find('.annotate-row').length).toBe(3)
+      const notes = $('.annotate-row .annotate-note p', annotation)
+      const noteTexts = notes.map((i, el) => $(el).text()).get()
+      expect(noteTexts).toEqual(["Let's get started", 'This is just a sample', 'End of the script'])
+    }
+    // Second code snippet block
+    {
+      const annotation = annotations.eq(1)
+      expect(annotation.find('.annotate-header').length).toBe(1)
+      expect(annotation.find('.annotate-beside').length).toBe(1)
+      expect(annotation.find('.annotate-inline').length).toBe(1)
+      expect(annotation.find('.annotate-row').length).toBe(2)
+      const notes = $('.annotate-row .annotate-note p', annotation)
+      const noteTexts = notes.map((i, el) => $(el).text()).get()
+      expect(noteTexts).toEqual(['Has to start with a comment.', 'This is the if statement'])
+    }
+  })
+})