refactor: allow remark-lint-expected-html-sections to be disabled

PR-URL: #11009
Reviewed-by: Athan Reines <kgryte@gmail.com>

Author: batpigandme

lib/node_modules/@stdlib/_tools/remark/plugins/remark-lint-expected-html-sections/lib/linter.js

@@ -30,6 +30,44 @@ var keys = require( '@stdlib/utils/keys' );
 var debug = logger( 'remark-lint-expected-html-sections' );
 var RE_SECTION_START = /<section(?:\s+class="([^"]*)")?>/;
 var RE_SECTION_END = /<\/section>/;
+var RE_HTML_COMMENT = /^\s*<!--[\s\S]*-->\s*$/;
+
+
+// FUNCTIONS //
+
+/**
+* Returns a message anchor node.
+*
+* @private
+* @param {Node} tree - abstract syntax tree (AST)
+* @returns {Node} anchor node
+*/
+function getAnchorNode( tree ) {
+	var node;
+	var i;
+
+	for ( i = 0; i < tree.children.length; i++ ) {
+		node = tree.children[ i ];
+		if ( node.type === 'html' && RE_HTML_COMMENT.test( node.value ) ) {
+			continue;
+		}
+		return node;
+	}
+	return tree;
+}
+
+/**
+* Reports a lint message.
+*
+* @private
+* @param {File} file - virtual file
+* @param {Node} node - anchor node
+* @param {string} msg - message
+* @returns {void}
+*/
+function reportMessage( file, node, msg ) {
+	file.message( msg, node, 'remark-lint:expected-html-sections' );
+}
 
 
 // MAIN //
@@ -60,6 +98,7 @@ function factory( options ) {
 		var sectionsFound;
 		var sectionStack;
 		var missingRoot;
+		var anchorNode;
 		var missingC;
 		var schema;
 		var msg;
@@ -78,6 +117,9 @@ function factory( options ) {
 			'c': {}
 		};
 
+		// Anchor messages to content nodes so inline lint comments can control reporting:
+		anchorNode = getAnchorNode( tree );
+
 		// Visit all HTML nodes to build section structure:
 		visit( tree, 'html', visitor );
 
@@ -101,7 +143,7 @@ function factory( options ) {
 		if ( missingRoot.length > 0 ) {
 			msg = 'Missing required root-level sections: `' + missingRoot.join( '`, `' ) + '`. Required sections are: `' + requiredRootSections.join( '`, `' ) + '`.   missing-required-sections';
 			debug( msg );
-			file.message( msg, tree, 'remark-lint:expected-html-sections' );
+			reportMessage( file, anchorNode, msg );
 		}
 
 		// If 'c' section exists, check its requirements:
@@ -119,7 +161,7 @@ function factory( options ) {
 			if ( missingC.length > 0 ) {
 				msg = 'Missing required sections in "c" section: `' + missingC.join( '`, `' ) + '`. Required C sections are: `' + requiredCSections.join( '`, `' ) + '`.   missing-required-c-sections';
 				debug( msg );
-				file.message( msg, sectionsFound.root.c.node, 'remark-lint:expected-html-sections' );
+				reportMessage( file, sectionsFound.root.c.node, msg );
 			}
 		}