Skip to content

Add check-new-line-breaks: advisory, diff-scoped semantic-line-break check - #300

Merged
d-morrison merged 3 commits into
mainfrom
feat/check-new-line-breaks
Jul 25, 2026
Merged

d-morrison merged 3 commits into
mainfrom
feat/check-new-line-breaks

Conversation

@d-morrison

Copy link
Copy Markdown
Collaborator

Summary

Closes #299.

  • New check-new-line-breaks/ Python composite action + .github/workflows/check-new-line-breaks.yml reusable workflow, following check-phi's existing diff-scoped-by-base-ref pattern closely (same three-dot merge-base diff, env-var config, paths-ignore glob handling).
  • Flags newly-added Markdown lines packing more than one sentence/clause onto a single line -- the "semantic line breaks" convention -- so it can complement lint-markdown when a repo has MD013 (line-length) disabled because its corpus already carries pre-existing long-line drift.
  • Deliberately diverges from check-phi in one place: when the diff can't be computed (shallow clone, no base-ref), this skips the check entirely rather than falling back to a whole-tree scan, since scanning the whole tree here would reflag exactly the pre-existing drift diff-scoping exists to avoid.
  • Non-blocking by default (fail: false) -- a long line can legitimately be un-splittable (a URL, a citation, a single genuinely long clause).

Ported from d-morrison/ai-config's scripts/check-new-line-breaks.py (ai-config#682/#684), rewritten to match this repo's own conventions rather than copied verbatim.

Doc/wiring sync

Per CLAUDE.md's own note that a brand-new @v2-only capability needs updates at every site restating the @v1/@v2 scoping, not just the obvious one -- grepped the whole repo for lint-changed-lines (the most recently added @v2-only sibling) as an anchor and updated all of them:

  • README.md (capability table, permissions bullet, Versioning section)
  • website/workflows.qmd (capability table + its own Versioning-summary paragraph)
  • website/versioning.qmd (both of its two restatements)
  • CLAUDE.md (capability list, Layout section, Tests section)
  • examples/check-new-line-breaks.yml + website/reference/check-new-line-breaks.qmd, both pinned to @v2

Also wired _selftest.yml: a new-line-breaks job exercising the real composite against this repo's own tree (base-ref diff mode, mirroring phi's local-composite-not-yet-released precedent), and new-line-breaks-tests for the pytest suite.

Test plan

  • python3 -m pytest check-new-line-breaks/tests/ -q -- 19/19 pass, including the diff-scoping guarantees: a newly-added violation is flagged, pre-existing drift in an untouched line is not reflagged, and a failed diff (bad base-ref) skips rather than falling back to a whole-tree scan
  • All new/edited YAML validated with yaml.safe_load
  • Scanned the full staged diff for banned em-dash/curly-quote/multiplication-sign punctuation -- one pre-existing em-dash found on a CLAUDE.md line this PR was already editing, fixed in the same commit; nothing else
  • No merge conflicts against current main (confirmed via a real stash/rebase onto fresh origin/main, not just an earlier snapshot)

Generated by Claude Code

…check

New Python composite action + workflow_call reusable workflow, following
check-phi's existing diff-scoped-by-base-ref pattern closely. Flags newly
added Markdown lines packing more than one sentence/clause onto a single
line -- the "semantic line breaks" convention -- so it can complement
lint-markdown when a repo has MD013 (line-length) disabled because the
corpus already carries pre-existing long-line drift.

Deliberately diverges from check-phi in one place: when the diff can't be
computed (shallow clone, no base-ref), this skips the check entirely
rather than falling back to a whole-tree scan, since scanning the whole
tree here would reflag exactly the pre-existing drift diff-scoping exists
to avoid.

Ported from d-morrison/ai-config's scripts/check-new-line-breaks.py
(ai-config#682/#684), rewritten to match this repo's own conventions
(three-dot merge-base diff like check-phi, env-var config, pytest suite).

Wires into _selftest.yml (new-line-breaks against this repo's own tree via
base-ref, new-line-breaks-tests for the pytest suite), updates every site
that restates the @v1/@v2 capability-tag scoping (README.md, CLAUDE.md,
website/versioning.qmd x2, website/workflows.qmd x2), and adds the
examples/ stub + reference page.

Closes #299

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DrR2uj9a5QBkAb7RuCA3bC
Copilot AI review requested due to automatic review settings July 25, 2026 00:36

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@codecov

codecov Bot commented Jul 25, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

check-new-line-breaks/tests/test_check_new_line_breaks.py uses a placeholder
git config email (t@t.com) for its throwaway test-repo fixtures, which
check-phi's email detector correctly flagged -- excluded via paths-ignore,
matching the existing check-phi/tests/** and test-coverage/tests/** entries
for the same synthetic-content-in-tests reason.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DrR2uj9a5QBkAb7RuCA3bC
Copilot AI review requested due to automatic review settings July 25, 2026 00:38

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@claude

claude Bot commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

Code review

Reviewed the diff, cross-checked the ported script against its stated upstream source (d-morrison/ai-config), and validated each candidate finding independently before posting. Three findings are posted as inline comments; one (a doc-sync miss on unchanged lines outside the diff, so GitHub won't let me anchor it inline) is below.

README.md:352-361 — The ### Pinning third-party actions subsection carries its own separate @v1/@v2 capability-exception list (a second, independently-worded restatement of the same list the main ## Versioning section carries). This PR updates the main ## Versioning section, website/versioning.qmd, and website/workflows.qmd to add check-new-line-breaks.yml, but misses this subsection, which still ends at altdoc-multiversion-docs.yml. CLAUDE.md calls out this exact section pair by name as the gha#181 repeat-offender for this precise miss.

Everything else checked out: the diff-parsing logic (_added_line_numbers), sentence-splitting, block-exclusion logic, and glob-matching all trace correctly against the included tests; no shell-injection/path-traversal issues; the _glob_to_regex duplication of check-phi's implementation is precedented by lint-yaml/_pathspec.py's documented "keep glob logic local per composite" convention, not a fresh violation; selftest wiring and fixture-generation conventions are followed; and the rest of the @v1/@v2 doc-sync sites (CLAUDE.md, README's main Versioning section, website/versioning.qmd, website/workflows.qmd, examples/, reference page) are all correctly updated.

Verdict

Needs more work — one functional bug (the base-ref-empty path runs a whole-tree scan rather than skipping, contradicting the PR's own documented behavior and its central "never reflags pre-existing drift" claim) plus a real doc-sync gap should be addressed before merge. The docstring/dropped-feature and changelog-formatting findings are minor and non-blocking.

@github-actions

Copy link
Copy Markdown
Contributor

Claude finished review — View run


I've completed the review of PR #300 (d-morrison/gha). Summary of what was posted:

Inline comments (3):

  1. check-new-line-breaks/check-new-line-breaks.py:88-96 — functional bug: an empty/unset base-ref (e.g. on a push) runs a whole-tree scan, not a skip, contradicting action.yml's documented behavior and the PR's central "never reflags pre-existing drift" claim.
  2. check-new-line-breaks/check-new-line-breaks.py:88-96 — docstring falsely claims an "@-import directives" exclusion that was dropped during the port from d-morrison/ai-config.
  3. changelog.d/add-check-new-line-breaks.added.md:8 — non-blocking semantic-line-break style suggestion (ironic given the PR's own purpose).

Top-level summary comment: posted, including a fourth finding that couldn't be anchored inline (unchanged lines outside the diff): README.md:352-361's ### Pinning third-party actions subsection is missing the new capability, a documented gha#181 repeat-offender pattern.

A fifth candidate (DRY duplication of glob-matching logic vs. check-phi) was investigated and refuted — it's precedented by lint-yaml/_pathspec.py's documented convention.

Verdict

Needs more work — one functional bug and one doc-sync gap should be fixed before merge; the other two findings are minor/non-blocking.

@github-actions

Copy link
Copy Markdown
Contributor

💰 Cost: $8.9795 (review) — run

…docs

Real bug: find_violations()'s else branch (no base_ref) built a whole-file
scope and ran the check against it, silently contradicting action.yml's
own documented "skipped, no whole-tree fallback" behavior and the PR's
central design claim. Every push to main via the shipped example stub
(which passes no base-ref) would have reflagged every pre-existing long
line in the caller's corpus -- the exact flood this capability exists to
avoid.

Fixed by treating "no base_ref" the same as "diff unavailable": both skip
cleanly now. Removed the now-dead _tracked_files() whole-tree helper, and
rewrote the module/function docstrings, which had also self-contradicted
(one bullet said "whole tree runs on push", the next said "no whole-tree
fallback"). Renamed find_violations()'s second return value from
diff_unavailable to skipped, since it's no longer diff-specific.

Also:
- Corrected prose_line_numbers()'s docstring, which falsely claimed an
  "@-import directives" exclusion carried over from the ai-config source
  that was never actually ported (no such logic exists in this file --
  ai-config's own @shared/foo.md include-directive convention has no
  equivalent among this repo's consumers).
- Added the missing check-new-line-breaks.yml entry to README.md's
  "### Pinning third-party actions" subsection, a second independent
  restatement of the @v1/@v2 capability-exception list that the main
  Versioning section update in the previous commit missed -- the exact
  gha#181 repeat-offender pattern CLAUDE.md calls out by name.
- Split a three-sentences-on-one-line changelog entry into semantic line
  breaks (ironic given this PR's own purpose).

Test suite updated to match: the removed whole-tree-mode test is replaced
with a test asserting empty base_ref also skips; re-verified end-to-end
with a live dogfood run against a scratch repo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DrR2uj9a5QBkAb7RuCA3bC
Copilot AI review requested due to automatic review settings July 25, 2026 00:58

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copy link
Copy Markdown
Collaborator Author

Addressed all four findings from the review:

  1. Whole-tree-scan-on-empty-base-ref bug (real, confirmed) -- fixed by unifying "no base_ref" with "diff unavailable" into one skip path; removed the dead _tracked_files() helper; verified end-to-end with a live dogfood run.
  2. False "@-import directives" docstring claim (confirmed) -- dropped the claim rather than porting the unused feature; docstring now explains what was/wasn't carried over from ai-config and why.
  3. Changelog semantic-line-break nit -- fixed.
  4. README.md's "### Pinning third-party actions" subsection missing the new capability (confirmed, the exact gha#181 repeat-offender pattern) -- added.

Pushed in 7f695a2.


Generated by Claude Code

@github-actions

github-actions Bot commented Jul 25, 2026 •

Copy link
Copy Markdown
Contributor
PR Preview Action v1.8.1
Preview removed because the pull request was closed.

2026-07-25 01:15 UTC

@github-actions

Copy link
Copy Markdown
Contributor

Claude finished review — View run


This confirms my independent verification of the fix commit matches the author's own accounting. All findings check out as genuinely resolved with no regressions.

Code review

This is a confirming review following up on my prior review round (posted 2026-07-25T00:54:53Z), which flagged four issues: Needs more work.

Commit 7f695a28 ("Fix: empty base-ref was running a whole-tree scan, contradicting the docs"), pushed shortly after that review, addresses all four:

  1. Whole-tree-scan-on-empty-base-ref bug — Verified fixed. find_violations() now returns (skipped=True) uniformly whenever base_ref is falsy or the diff can't be computed (check-new-line-breaks/check-new-line-breaks.py, find_violations/main), matching action.yml's documented "skip, no whole-tree fallback" behavior. The dead _tracked_files() whole-tree helper was removed, and the renamed test test_empty_base_ref_skips_rather_than_scanning_whole_tree now asserts skipped with no violations for base_ref="" — a rewrite of the old test that had asserted the opposite (whole-tree scanning).
  2. False "@-import directives" docstring claim — Verified fixed. prose_line_numbers()'s docstring no longer claims this exclusion exists; it now correctly documents that ai-config's @shared/foo.md convention was deliberately not ported since it has no equivalent among this repo's consumers.
  3. Changelog semantic-line-break nit — Verified fixed. changelog.d/add-check-new-line-breaks.added.md now breaks "...exactly that reason." / "Non-blocking by default..." / "Ported from..." onto separate lines.
  4. README.md's "### Pinning third-party actions" doc-sync gap — Verified fixed. check-new-line-breaks.yml is now listed in that subsection's @v2 exception list (README.md:359), alongside the already-correct main Versioning section and website pages.

I independently re-read the full diff and the fix commit rather than relying solely on the author's own summary comment, and confirm no new issues were introduced by the fix (module/function docstrings were also de-duplicated/reconciled where they had self-contradicted, and both the test suite and _selftest.yml's PHI-scan paths-ignore were updated consistently).

No new findings from this round.

Verdict

Ready for merge — all four findings from the prior review round are confirmed fixed in commit 7f695a2, with no regressions introduced.

@github-actions

Copy link
Copy Markdown
Contributor

💰 Cost: $1.1843 (review) — run

@d-morrison
d-morrison merged commit 209bfb7 into main Jul 25, 2026
32 of 33 checks passed
@d-morrison
d-morrison deleted the feat/check-new-line-breaks branch July 25, 2026 01:15
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.

Add check-new-line-breaks: advisory, diff-scoped semantic-line-break check

3 participants