build: add remark plugin to validate expected HTML sections

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: passed
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: passed
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

lib/node_modules/@stdlib/_tools/remark/plugins/remark-lint-expected-html-sections/README.md

@@ -0,0 +1,176 @@
+<!--
+
+@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-expected-html-sections
+
+> [remark][remark] plugin to lint expected HTML sections in README files according to stdlib conventions.
+
+<section class="intro">
+
+This plugin checks for the presence of required HTML sections in README.md files, as defined in stdlib's documentation conventions. It ensures that each README contains the essential sections needed for comprehensive documentation, and that sections with special requirements (such as the C API section) contain their own required subsections.
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var expectedSections = require( '@stdlib/_tools/remark/plugins/remark-lint-expected-html-sections' );
+```
+
+### expectedSections( \[options] )
+
+Validates the presence of expected HTML sections in README files.
+
+```javascript
+var remark = require( 'remark' );
+
+remark().use( expectedSections ).process( '# README', done );
+
+function done( error, file ) {
+    if ( error ) {
+        console.error( error );
+    }
+}
+```
+
+#### options.schema
+
+The plugin can be configured with a custom schema that defines required and optional sections.
+
+```javascript
+var opts = {
+    'schema': {
+        'root': {
+            'required': [ 'usage', 'examples', 'links' ],
+            'optional': [ 'intro', 'notes', 'c', 'references', 'related' ]
+        },
+        'c': {
+            'required': [ 'usage', 'examples' ],
+            'optional': [ 'intro', 'notes' ]
+        }
+    }
+};
+
+remark().use( expectedSections, opts ).process( src, done );
+```
+
+The default schema requires `usage`, `examples`, and `links` at the root level, and if a `c` section exists, it requires `usage` and `examples` subsections.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   The plugin detects HTML sections using pattern matching for `<section class="name">` tags.
+-   The plugin builds a hierarchical model of the document structure to validate both root and nested sections.
+-   Missing required sections will generate lint errors with specific details about which sections are missing.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+```javascript
+var remark = require( 'remark' );
+var expectedSections = require( '@stdlib/_tools/remark/plugins/remark-lint-expected-html-sections' );
+
+var lines = [
+    '# Example Package',
+    '',
+    '<section class="intro">',
+    '',
+    '## Introduction',
+    '',
+    'This is an example package.',
+    '',
+    '</section>',
+    '',
+    '<!-- /.intro -->',
+    '',
+    '<section class="examples">',
+    '',
+    '## Examples',
+    '',
+    '```javascript',
+    'var example = require( \'example\' );',
+    'example();',
+    '```',
+    '',
+    '</section>',
+    '',
+    '<!-- /.examples -->',
+    '',
+    '<!-- Missing usage section! -->',
+    '',
+    '<!-- Missing links section! -->'
+];
+
+var source = lines.join( '\n' );
+
+// Define default options:
+var opts = {
+    'schema': {
+        'root': {
+            'required': [ 'usage', 'examples', 'links' ],
+            'optional': [ 'intro', 'notes', 'c', 'references', 'related' ]
+        }
+    }
+};
+
+// Process source with linter:
+remark().use( expectedSections, opts ).process( source, done );
+
+function done( error, file ) {
+    var i;
+    if ( error ) {
+        console.error( error );
+        return;
+    }
+    if ( file.messages.length === 0 ) {
+        console.log( 'No lint errors found.' );
+    } else {
+        for ( i = 0; i < file.messages.length; i++ ) {
+            console.log( '%d. %s', i+1, file.messages[ i ].reason );
+        }
+    }
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+<section class="links">
+
+[remark]: https://github.com/remarkjs/remark
+
+</section>
+
+<!-- /.links -->

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

@@ -0,0 +1,83 @@
+/**
+* @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 expectedSections = require( './../lib' );
+
+var lines = [
+	'# Example Package',
+	'',
+	'<section class="intro">',
+	'',
+	'## Introduction',
+	'',
+	'This is an example package.',
+	'',
+	'</section>',
+	'',
+	'<!-- /.intro -->',
+	'',
+	'<section class="examples">',
+	'',
+	'## Examples',
+	'',
+	'```javascript',
+	'var example = require( \'example\' );',
+	'example();',
+	'```',
+	'',
+	'</section>',
+	'',
+	'<!-- /.examples -->',
+	'',
+	'<!-- Missing usage section! -->',
+	'',
+	'<!-- Missing links section! -->'
+];
+
+var source = lines.join( '\n' );
+
+// Define default options:
+var opts = {
+	'schema': {
+		'root': {
+			'required': [ 'usage', 'examples', 'links' ],
+			'optional': [ 'intro', 'notes', 'c', 'references', 'related' ]
+		}
+	}
+};
+
+// Process source with linter:
+remark().use( expectedSections, opts ).process( source, done );
+
+function done( error, file ) {
+	var i;
+	if ( error ) {
+		console.error( error );
+		return;
+	}
+	if ( file.messages.length === 0 ) {
+		console.log( 'No lint errors found.' );
+	} else {
+		for ( i = 0; i < file.messages.length; i++ ) {
+			console.log( '%d. %s', i+1, file.messages[ i ].reason );
+		}
+	}
+}

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

@@ -0,0 +1,40 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2022 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 hierarchy in README files.
+*
+* @module @stdlib/_tools/remark/plugins/remark-lint-expected-html-sections
+*
+* @example
+* var remark = require( 'remark' );
+* var expectedHtmlSections = require( '@stdlib/_tools/remark/plugins/remark-lint-expected-html-sections' );
+*
+* var linter = remark().use( expectedHtmlSections );
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;