fix(parser/docs): disallow self mode at the top-level of a language

CHANGES.md

@@ -7,6 +7,7 @@ New styles:
   none.
 
 Improvements:
+- fix(parser/docs): disallow `self` mode at the top-level of a language (#2294) [Josh Goebel][]
 - fix(mercury): don't change global STRING modes (#2271) [Josh Goebel][]
 - fix: freeze built-in modes to prevent grammars altering them (#2271) [Josh Goebel][]
 - enh(xml) expand and improve document type highlighting (#2287) [w3suli][]

docs/language-guide.rst

@@ -126,6 +126,8 @@ This is commonly used to define nested modes:
     contains: [hljs.QUOTE_STRING_MODE, 'self']
   }
 
+Note: ``self`` may not be used in the root level ``contains`` of a language.  The root level mode is special and may not be self-referential.
+
 
 Comments
 --------

src/highlight.js

@@ -499,6 +499,17 @@ https://highlightjs.org/
       mode.terminators = buildModeRegex(mode);
     }
 
+    // self is not valid at the top-level
+    if (language.contains && language.contains.indexOf('self') != -1) {
+      if (!SAFE_MODE) {
+        throw new Error("ERR: contains `self` is not supported at the top-level of a language.  See documentation.")
+      } else {
+        // silently remove the broken rule (effectively ignoring it), this has historically
+        // been the behavior in the past, so this removal preserves compatibility with broken
+        // grammars when running in Safe Mode
+        language.contains = language.contains.filter(function(mode) { return mode != 'self'; });
+      }
+    }
     compileMode(language);
   }