Question about how Bluehawk parsing works

[mongodben]

question about how bluehawk parses comments. i have the following in a JavaScript file:

//someFile.js

// :snippet-start: paginate

const PAGINATE_MOVIES = gql`
  # :snippet-start: paginate-query
  query PaginateMovies(
    $prevTitle: String
    $nextTitle: String
    $limit: Int!
    $sortDirection: MovieSortByInput!
  ) {
    movies(
      # Can add other query filters here if you'd like
      query: { title_gt: $prevTitle, title_lt: $nextTitle }
      limit: $limit
      sortBy: $sortDirection
    ) {
      _id
      title
      year
    }
  }
  # :snippet-end:
`;

// ...rest of snippet
// :snippet-end:

bluehawk successfully parses 2 snippets, paginate and paginate-query, even though the paginate-query snippet is only defined inside a string, not a comment like where we usually put tags. the fact that this worked (pleasantly) surprised me.

based on this behavior, my question is: how does bluehawk identify tags?

• is it dependent on some notion of comment nodes?
• is bluehawk aware of graphql syntax and that's why this worked?
• is it just parsing the raw text of the file looking for bluehawk tags?
• some other mechanism?

[cbush]

While there is actually a bunch of implementation for handling tokens that push another parser (such as the <?php tag that switches from HTML to PHP), this is actually not as smart as any of that. The JS implementation doesn't declare any string types so any Bluehawk token in a string will be picked up. Your JS parser ignores the gql template literal (it's just a string as far as JS is concerned), but Bluehawk finds the tag tokens and uses them. Meanwhile, your gql parser ignores the Bluehawk tokens because they are commented out in gql.

There's an edge case here where if a block comment open token were in a string without a matching close comment token, the Bluehawk parser would treat this as an error while the JS parser would not see the block comment at all. Some additional string-awareness might be worth adding to avoid this case.

[mongodben]

thanks for clarifying. this is super informative. i imagine we could use this behavior to create text-based snippets (if we ever want to).

could be useful to test GQL code snippets, cURL based examples, even bash commands.

for example, to test a cURL request:

test("get app location", () => {
myCurlReq = `
:snippet-start: get-app-location
curl 'https://realm.mongodb.com/api/client/v2.0/app/<AppID>/location'
:snippet-end:
`;

const myAppId = "some-realm-app-id-for-testing";

const testableSnippet = removeBluehawkSnippets(myCurlRequest).replace("<AppID>", myAppId);

// for running cli operations w promises
const util = require('util');
const exec = util.promisify(require('child_process').exec);

const { stdout } = await exec(testableSnippet);

const expectedOutcome = "some string that we'd expect to get from stdout";

expect(stdout).toBe(expectedOutcome);


// maybe cleaner way to do? perhaps Bluehawk Node.js API exposes smthn?
function removeBluehawkSnippets(input: string){
  return input.replaceAll(/(:snippet-start:\s*\S+)|(:snippet-end:)/, "").trim();
}
});

this way the snippet is testable and you can run bluehawk snip on it to get the desired result.