build: add remark plugin to validate expected HTML sections #6156

Planeshifter · 2025-03-18T15:41:49Z

Description

What is the purpose of this pull request?

This pull request:

adds a remark plugin to ensure that README.md files have the expected HTML <section> tag structure as mandated by stdlib conventions.

Related Issues

Does this pull request have any related issues?

This pull request:

progresses [RFC]: add remark plugin(s) for ensuring that each <section> tag has a matching closing tag metr-issue-tracker#49 by resolving 3).

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

Read, understood, and followed the contributing guidelines.

@stdlib-js/reviewers

--- 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 ---

--- 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: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - 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 ---

--- 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: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - 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 ---

Planeshifter · 2025-03-18T15:43:12Z

/stdlib update-copyright-years

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

--- 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: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - 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/lib/linter.js

Signed-off-by: Athan <kgryte@gmail.com>

kgryte · 2025-04-23T03:58:59Z

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

+			var className;
+
+			// Check if this is a section start tag:
+			sectionMatch = RE_SECTION_START.exec( node.value );


Similar question regarding the use of exec.

kgryte · 2025-04-23T04:00:03Z

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

+			else if ( RE_SECTION_END.test( node.value ) ) {
+				if ( sectionStack.length > 0 ) {
+					sectionStack.pop();
+				}
+			}


Suggested change

else if ( RE_SECTION_END.test( node.value ) ) {

if ( sectionStack.length > 0 ) {

sectionStack.pop();

}

}

else if ( RE_SECTION_END.test( node.value ) && sectionStack.length > 0 ) {

sectionStack.pop();

}

You can refactor to avoid an extra level of nesting.

kgryte · 2025-04-23T04:01:20Z

...ode_modules/@stdlib/_tools/remark/plugins/remark-lint-expected-html-sections/lib/validate.js

+		return new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
+	}
+	if ( hasOwnProp( options, 'schema' ) ) {
+		if ( !isObject( options.schema ) ) {


This is a fairly weak check, as I could pass in options.schema = { 'foo': 'bar', 'required': null } and this validation test would pass.

kgryte · 2025-04-23T04:04:28Z

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

+			t.fail( err.message );
+		}
+		t.strictEqual( file.messages.length, 1, 'has one error for invalid asin fixture' );
+		t.strictEqual( file.messages[0].reason.includes('Missing required sections in "c" section: `usage`'), true, 'error identifies the missing C usage section' );


Refactor to avoid use of includes here and below. Also, spacing.

kgryte · 2025-04-23T04:04:37Z

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

+			t.fail( err.message );
+		}
+		t.strictEqual( file.messages.length, 1, 'has one error for fixture missing a required root section' );
+		t.strictEqual( file.messages[0].reason.includes('Missing required root-level sections: `usage`'), true, 'error identifies the missing section' );


Same comment.

kgryte · 2025-04-23T04:04:41Z

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

+			t.fail( err.message );
+		}
+		t.strictEqual( file.messages.length, 1, 'has one error for fixture with an incomplete C section' );
+		t.strictEqual( file.messages[0].reason.includes('Missing required sections in "c" section: `usage`, `examples`'), true, 'error identifies the missing C sections' );


Same comment.

kgryte · 2025-04-23T04:04:47Z

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

+			t.fail( err.message );
+		}
+		t.strictEqual( file.messages.length, 1, 'has correct number of errors with custom schema' );
+		t.strictEqual( file.messages[0].reason.includes('usage') && file.messages[0].reason.includes('related'), true, 'error identifies both missing sections' );


Same comment.

kgryte

Left an initial round of comments.

Planeshifter added 3 commits March 17, 2025 21:51

stdlib-bot added Tools Issue or pull request related to project tooling. Needs Review A pull request which needs code review. labels Mar 18, 2025

stdlib-bot added the bot: In Progress Pull request is currently awaiting automation. label Mar 18, 2025

chore: update copyright years

6973674

stdlib-bot removed the bot: In Progress Pull request is currently awaiting automation. label Mar 18, 2025

Planeshifter requested a review from kgryte March 18, 2025 15:45

kgryte reviewed Apr 16, 2025

View reviewed changes

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

kgryte added Needs Changes Pull request which needs changes before being merged. and removed Needs Review A pull request which needs code review. labels Apr 16, 2025

Planeshifter requested a review from kgryte April 20, 2025 21:42

stdlib-bot added the Needs Review A pull request which needs code review. label Apr 20, 2025

kgryte reviewed Apr 23, 2025

View reviewed changes

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

kgryte reviewed Apr 23, 2025

View reviewed changes

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

kgryte reviewed Apr 23, 2025

View reviewed changes

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

Apply suggestions from code review

5e72ab3

Signed-off-by: Athan <kgryte@gmail.com>

kgryte reviewed Apr 23, 2025

View reviewed changes

kgryte removed the Needs Review A pull request which needs code review. label Apr 23, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

build: add remark plugin to validate expected HTML sections #6156

build: add remark plugin to validate expected HTML sections #6156

Planeshifter commented Mar 18, 2025

Planeshifter commented Mar 18, 2025

kgryte Apr 23, 2025

kgryte Apr 23, 2025

kgryte Apr 23, 2025

kgryte Apr 23, 2025

kgryte Apr 23, 2025

kgryte Apr 23, 2025

kgryte Apr 23, 2025

kgryte left a comment

build: add remark plugin to validate expected HTML sections #6156

Are you sure you want to change the base?

build: add remark plugin to validate expected HTML sections #6156

Conversation

Planeshifter commented Mar 18, 2025

Description

Related Issues

Questions

Other

Checklist

Planeshifter commented Mar 18, 2025

kgryte Apr 23, 2025

Choose a reason for hiding this comment

kgryte Apr 23, 2025

Choose a reason for hiding this comment

kgryte Apr 23, 2025

Choose a reason for hiding this comment

kgryte Apr 23, 2025

Choose a reason for hiding this comment

kgryte Apr 23, 2025

Choose a reason for hiding this comment

kgryte Apr 23, 2025

Choose a reason for hiding this comment

kgryte Apr 23, 2025

Choose a reason for hiding this comment

kgryte left a comment

Choose a reason for hiding this comment