build: add remark plugin for validating HTML section structure

PR-URL: #6133
Ref: stdlib-js/metr-issue-tracker#49
Co-authored-by: Athan Reines <[email protected]>
Reviewed-by: Athan Reines <[email protected]> 
Co-authored-by: stdlib-bot <[email protected]>

Author: 3 people

lib/node_modules/@stdlib/_tools/remark/plugins/remark-lint-html-section-structure/README.md

@@ -0,0 +1,109 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2025 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# remark-lint-html-section-structure
+
+> [remark][remark] plugin to lint HTML section structure in README files.
+
+<section class="intro">
+
+This plugin validates the HTML section structure in README files, ensuring that:
+
+1.  Each opening `<section>` tag has a corresponding `</section>` closing tag.
+2.  Each opening `<section class="foo">` tag has a corresponding closing comment `<!-- /.foo -->`.
+3.  There is an empty line between the closing `</section>` tag and the closing comment `<!-- /.foo -->`.
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var sectionStructure = require( '@stdlib/_tools/remark/plugins/remark-lint-html-section-structure' );
+```
+
+### sectionStructure()
+
+Plugin to lint HTML section structure in README files.
+
+```javascript
+var remark = require( 'remark' );
+
+remark().use( sectionStructure );
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="examples">
+
+## Examples
+
+```javascript
+var remark = require( 'remark' );
+var report = require( 'vfile-reporter' );
+var sectionStructure = require( '@stdlib/_tools/remark/plugins/remark-lint-html-section-structure' );
+
+// Create a markdown file with HTML sections:
+var markdown = [
+    '# Title',
+    '',
+    '<section class="usage">',
+    '',
+    '## Usage',
+    '',
+    '```javascript',
+    'var foo = require( \'foo\' );',
+    '```',
+    '',
+    '</section>',
+    '',
+    '<!-- /.usge -->',
+    ''
+].join( '\n' );
+
+// Lint using the plugin:
+remark()
+    .use( sectionStructure )
+    .process( markdown, onDone );
+
+function onDone( error, file ) {
+    if ( error ) {
+        throw error;
+    }
+    console.log( report( file ) );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+<section class="links">
+
+[remark]: https://github.com/remarkjs/remark
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/_tools/remark/plugins/remark-lint-html-section-structure/examples/index.js

@@ -0,0 +1,59 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+var remark = require( 'remark' );
+var report = require( 'vfile-reporter' );
+var linter = require( './../lib' );
+
+// Create a markdown file with both valid and invalid HTML sections:
+var markdown = [
+	'# Title',
+	'',
+	'<section class="usage">',
+	'',
+	'## Usage',
+	'',
+	'```javascript',
+	'var foo = require( \'foo\' );',
+	'```',
+	'',
+	'</section>',
+	'',
+	'<!-- /.usge -->'
+].join( '\n' );
+
+// Lint using the plugin:
+remark()
+	.use( linter )
+	.process( markdown, done );
+
+/**
+* Callback invoked upon processing a Markdown file.
+*
+* @private
+* @param {Error|null} error - error object
+* @param {VFile} file - virtual file
+*/
+function done( error, file ) {
+	if ( error ) {
+		throw error;
+	}
+	console.log( report( file ) );
+}

lib/node_modules/@stdlib/_tools/remark/plugins/remark-lint-html-section-structure/lib/index.js

@@ -0,0 +1,50 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+/**
+* remark lint plugin for validating HTML section structure in README files.
+*
+* @module @stdlib/_tools/remark/plugins/remark-lint-html-section-structure
+*
+* @example
+* var remark = require( 'remark' );
+* var lint = require( '@stdlib/_tools/remark/plugins/remark-lint-html-section-structure' );
+*
+* var str = '# Title\n\n<section class="usage">\n\n## Usage\n\n</section><!-- /.usage -->';
+*
+* function done( error, file ) {
+*     var i;
+*     if ( error ) {
+*         throw error;
+*     }
+*     for ( i = 0; i < file.messages.length; i++ ) {
+*         console.error( file.messages[ i ].message );
+*     }
+* }
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;