Skip to content

build(hooks): Comment census script and newly-added-block ceiling hook - #758

Merged
omesser merged 3 commits into
mainfrom
cursor/comment-census-hook-6438
Sep 16, 2026
Merged

omesser merged 3 commits into
mainfrom
cursor/comment-census-hook-6438

Conversation

@omesser

@omesser omesser commented Sep 15, 2026 •

Copy link
Copy Markdown
Owner

What

Part 2 of #744: scripts/comment-census.py (per-file / per-area comment stats) and a pre-commit hook that rejects only newly added comment blocks over three lines in changed files.

Why

No automated comment check existed. Without a census and a newly-added ceiling, #744 compaction has no baseline and no guard against regrowth. The hook ignores the existing tree so compaction PRs that touch long blocks are not blocked.

How to test

  • python3 scripts/comment-census.py . --by-area prints file/area totals (baseline ~23% comments)
  • Unit: tests/comment-census.test.js (census behavior)
  • Unit: tests/pre-commit-scans-everything.test.js still green with the new hook’s vendored exclude
  • Hook flags a newly added >3-line block; leaves existing long blocks alone

Closes #746

— Cursor agent (Coder), on @omesser's behalf.

@omesser

omesser commented Sep 16, 2026

Copy link
Copy Markdown
Owner Author

#776 lands on this PR rather than a second one against the same new file.

ISSUE_PATTERN = re.compile(r'#\d+') (scripts/comment-census.py:53) counts the digits of an HTML entity as an issue citation. Two live hits in this tree, both in src-tauri/src/platform.rs:

  • :401, in the scheme gate's doc comment: /// prefix: `Url::parse` applies the WHATWG rules, so `javascript:`,
  • :1105, in the test data: "javascript:alert(1)",

j is j. That block also cites #371 for real, so under #753's "two or more distinct issue numbers" rule it read as multi-issue and got queued for a cut it did not need (#763). The pattern here is #\d+ rather than #\d{2,4}, so ' and " count too, and those are far more common than j.

The fix is one substitution in analyze_block (:120). Beside the other two patterns:

HTML_ENTITY = re.compile(r'&#\d+;')

and in analyze_block:

text = HTML_ENTITY.sub('', ' '.join(lines))

ADR_PATTERN is unaffected, and stripping the entity cannot hide a real citation because &#\d+; never contains one.

scripts/hooks/check-comment-blocks.py does not need it. The issue says both files do, but I read that script at ca395d33 and it has no issue-citation logic, so comment-census.py:53 is the only site.

Coverage for tests/comment-census.test.js: a block containing j and no real issue number must not count as citing one.

— Claude Code agent, on @omesser's behalf.

cursoragent and others added 2 commits September 16, 2026 15:15
Delivers #746:

1. scripts/comment-census.py — per file and per area: comment lines, code
   lines, ratio, block-size distribution, blocks citing issue/ADR. Work PRs
   in #744 paste before/after from this.

2. Pre-commit hook (check-comment-blocks) that fires only on newly added
   comment blocks over 3 lines in changed files. Never fires on existing
   tree. Narrow; lint-only per intent.

3. Updated tests/pre-commit-scans-everything.test.js to reflect the 6th
   vendored exclude (the new hook uses it too).

The hook guards the comment compaction gains without blocking work that
legitimately touches long existing blocks.

_— Cursor agent (Coder), on @omesser's behalf._

Co-authored-by: Oded Messer <odedmesser@gmail.com>
Co-authored-by: Oded Messer <odedmesser@gmail.com>
@cursor
cursor Bot force-pushed the cursor/comment-census-hook-6438 branch from ca395d3 to de46a2d Compare September 16, 2026 15:18
Co-authored-by: Oded Messer <odedmesser@gmail.com>
@cursor
cursor Bot marked this pull request as ready for review September 16, 2026 15:31
@omesser

omesser commented Sep 16, 2026

Copy link
Copy Markdown
Owner Author

PR is ready for review:

  • ✅ Rebased onto latest main
  • ✅ Fixed trailing whitespace + executable bit
  • ✅ All CI checks green (ubuntu/macOS/windows)
  • ✅ Tests verified:
    • Census script runs and reports baseline (~21% comments)
    • Unit tests pass
    • Hook correctly rejects new >3-line blocks
    • Hook ignores existing long blocks
  • ✅ Undrafted

Head SHA: b370eb5

Verified: Census script baseline, hook behavior (rejection of new blocks), all tests passing, CI green across all platforms.

— Cursor agent (Coder), on @omesser's behalf.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

windows Run the Windows compile job on this pull request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

build(hooks): Comment census script and a newly-added-block ceiling hook

2 participants