Skip to content

Skip HTML comments in ISO clause structure linter#101

Merged
OleksiyPuzikov merged 3 commits into
aousd:mainfrom
OleksiyPuzikov:main
Jul 1, 2026
Merged

Skip HTML comments in ISO clause structure linter#101
OleksiyPuzikov merged 3 commits into
aousd:mainfrom
OleksiyPuzikov:main

Conversation

@OleksiyPuzikov

Copy link
Copy Markdown
Collaborator

The clause linter treated Pandoc RawBlock(html) nodes — which represent HTML comments — as body content between headings, causing false positive violations. Now _is_html_comment_block() detects these blocks (including sourcepos Div wrappers) and excludes them from both the body_seen flag and the body_lines reported in violations.

Attn @asluk - this covers my comment in https://github.com/aousd/core-spec-wg/pull/517

The clause linter treated Pandoc RawBlock(html) nodes — which represent
HTML comments — as body content between headings, causing false positive
violations. Now _is_html_comment_block() detects these blocks (including
sourcepos Div wrappers) and excludes them from both the body_seen flag
and the body_lines reported in violations.

Adds 21 unit tests covering the helpers and check_file integration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@OleksiyPuzikov
OleksiyPuzikov requested review from dgovil and pmolodo June 29, 2026 09:49
@asluk

asluk commented Jun 29, 2026

Copy link
Copy Markdown
Collaborator

Logic looks correct and conservatively safe (the all() over the unwrapped Div means a comment sharing a block with real prose still flags, so this can't mask a genuine hanging paragraph). One nit:

_is_html_comment_line() is defined and unit-tested but never called in check_file — the body_lines comprehension uses _HTML_COMMENT_RE.match instead. Since that regex only matches a complete single-line comment, a block containing a multi-line comment plus real body text would still leak the comment's <!-- / --> fragments into the violation's displayed context. Cosmetic only (never a false positive — body_seen is governed by the block-level check), but it leaves _is_html_comment_line as dead code. Either wire it into that comprehension or drop the helper.

OleksiyPuzikov and others added 2 commits June 30, 2026 10:47
The clause linter treated Pandoc RawBlock(html) nodes — which represent
HTML comments — as body content between headings, causing false positive
violations. Now _is_html_comment_block() detects these blocks (including
sourcepos Div wrappers) and excludes them from the body_seen flag.

Multi-line comment fragments (<!--, inner lines, -->) are stripped from
violation body_lines by _strip_html_comment_lines(), which tracks
in-comment state across source lines.

Adds 24 unit tests covering the helpers and check_file integration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
# Conflicts:
#	doc_build/iso_clause_lint.py
#	tests/test_iso_clause_lint.py
@OleksiyPuzikov

Copy link
Copy Markdown
Collaborator Author

@asluk updated.

@asluk

asluk commented Jun 30, 2026

Copy link
Copy Markdown
Collaborator

tl;dr the rewrite addresses my earlier nit and it looks good to merge. Pulled the head (b09cab7) and verified locally:

  • All 24 tests pass (python -m unittest tests.test_iso_clause_lint).
  • Run against specification/ drops the count from 114 to 111: the three removed are top-level headings whose only body was a comment (Compliance.md:1, Scope.md:1 (the D7 <!-- ISO TODO --> placeholder), Versioning.md:1). No genuine hanging paragraph is masked, and no surviving violation has a comment line left in its reported body.
  • Clean against current main: ahead 3, behind 0, touching only iso_clause_lint.py and the new test file.

The two-helper split reads well: _is_html_comment_block gating body_seen for the count, _strip_html_comment_lines cleaning the displayed body. Thanks for the thorough test coverage.

This isn't gating #517 (that pin stays at c918081), so it can ride a later routine pin bump. If you consider it done, mind taking it out of draft so we can merge?

@OleksiyPuzikov OleksiyPuzikov changed the title [DRAFT] Skip HTML comments in ISO clause structure linter Skip HTML comments in ISO clause structure linter Jul 1, 2026
@OleksiyPuzikov
OleksiyPuzikov merged commit 26db239 into aousd:main Jul 1, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants