(fix) contains `self` pointing to a top-level rule breaks

Reference: https://github.com/facebook/docusaurus/issues/1954

From that thread:

---

Grammar with issue: https://www.npmjs.com/package/reason-highlightjs

  let MODULE_MODE = {
    begin: "\\s*\\{\\s*",
    end: "\\s*\\}\\s*",
    keywords: KEYWORDS,
    // most of the order here is important
    contains: [
      hljs.COMMENT('/\\*', '\\*/', { illegal: '^(\\#,\\/\\/)' }),
      // there's also a block mode technically, but for our purpose, a module {}
      // and a block {} can be considered the same for highlighting
      'self',

// ...

  return {
    aliases: ['re'],
    keywords: KEYWORDS,
    illegal: '(:\\-|:=|\\${|\\+=)',
    // lol beautiful
    contains: MODULE_MODE.contains,
  };

You can’t do that last line… because contains has a “self”, but in this case (at compile time) it would refer to the top-level, which makes no sense since the top-most-level include no regex matchers (which would be needed to retrigger itself)…

You have to remember the ruleset is just static data that’s compiled… so while you’re MODULE_MODE rule looks ok on it’s own the self is deceptive because it does NOT refer to MODULE_MODE but instead refers to whichever parent the contains is inside of… which in this case you’ve switched.

I’m not sure what behavior this resulted in before, but I’d guess the child-rule was simply ignored… really this is an error with the grammar from where I stand though - one the new parser is just not swallowing silently like before.

Could be I’m missing something but at this point if I were to fix anything it’d be to add a better error regarding self at the top-level… or perhaps a console.warn is better.

---

Ok, now back here…

I believe this worked before due to how rules without begin were silently dropped on the floor… I think I thought this protection was only for lack of illegal and lack of parent end rules (that need to be propagated) but I guess it would also kick in in a circumstance like this and silently drop the whole rule instead of raising an error.

Either way I’m pretty sure this has never worked as the author of this grammar intends it. The top-level “default” mode cannot be self-referential as it has no way to know when it should match and retrigger itself.

Right now I’m thinking the proper fix for this is to show a warning and then silently ignore and in the next major release we make this a breaking change on purpose, since this is really a broken ruleset issue.

[chenglou]

I can confirm that the previous self did nothing in the old version

[egor-rogov]

@yyyc514 I agree. I think we should stick to our general approach: when something goes wrong, try to do as much as possible and complain in log (in production), or throw an error (in development).