License-header detection could over-match and absorb adjacent source content, which on apply (relicense / year-refresh) caused render.replaceSpan to delete a real doc comment. A false positive in detection means the tool removes content it does not own.
Two distinct over-match paths, both on line-comment file types:
[HIGH]lineCommentRegion tolerated truly-blank lines between comment lines, so the layout license header / blank line / unrelated file doc comment collapsed into one detected span. The doc comment was then deleted on the next relicense or year-refresh.
[MED]spdxIdentifierTag matched SPDX-License-Identifier:anywhere in the leading comment via strings.Index, so a comment that merely mentioned the tag in prose was treated as a managed header.
Fix
lineCommentRegion now spans only contiguous comment lines: any non-comment line, including a truly-blank line, ends the run.
spdxIdentifierTag now requires the tag to begin a comment line (leading whitespace allowed), not appear mid-prose.
When in doubt the detector now under-detects (leaves a foreign comment alone) rather than over-detecting.
Why this is safe for idempotency / round-trip
The renderer never emits a truly-blank internal line in a managed header. For line-comment styles, the separator between REUSE tags and the notice block is rendered as a bare comment prefix (e.g. # or //), which is still a comment line and therefore stays in-region. Confining detection to contiguous comment lines is thus byte-idempotent for every header this tool writes, while it stops absorbing foreign comments that a blank line has separated from the header.
Verified by:
The existing TestSpliceIdempotent, TestApplyFile (re-apply is idempotent), and TestApplyFileIdempotentAfterPreserveFirstConstructs / ...ShebangPHPIdempotent suites — all still green.
A new end-to-end applier test TestApplyFilePreservesDocCommentBelowBlankLine: inserts a header into a Python file whose body opens with a doc comment, relicenses MIT -> Apache-2.0, and asserts the doc comment below the blank separator survives the replace.
TDD
Red-green: failing tests written and observed failing for the right reason before the fix.
detect: blank line ends the region (doc comment excluded); bare-prefix separator stays in-region; SPDX-License-Identifier mentioned mid-prose is not a managed header; own-line tag (incl. leading whitespace) still qualifies; Detect-level span guard.
applier: the relicense round-trip survival test above.
The previously-enshrining region test (detect_test.go) was rewritten to require the corrected contiguous behavior, with the safety rationale inline.
Deferred
The [LOW] sub-issue (block detection spans only the first /* */, so a stacked two-block header is not fully de-stacked) is intentionally deferred. Expanding block detection to span multiple blocks would increase over-detection risk, which contradicts the safety mandate to prefer under-detection. Spanning only the first block remains the safe choice.
Gate
gofmt -l . clean
go vet ./... clean
go test ./... -race -coverpkg=./internal/...,./cmd/... -covermode=atomic passing
coverage threshold: 100% (2079/2079)
golangci-lint run: 0 issues
Closes #30
## Problem (safety-critical)
License-header detection could over-match and absorb adjacent source content, which on `apply` (relicense / year-refresh) caused `render.replaceSpan` to **delete a real doc comment**. A false positive in detection means the tool removes content it does not own.
Two distinct over-match paths, both on line-comment file types:
1. **[HIGH]** `lineCommentRegion` tolerated truly-blank lines between comment lines, so the layout `license header` / blank line / `unrelated file doc comment` collapsed into one detected span. The doc comment was then deleted on the next relicense or year-refresh.
2. **[MED]** `spdxIdentifierTag` matched `SPDX-License-Identifier:` *anywhere* in the leading comment via `strings.Index`, so a comment that merely mentioned the tag in prose was treated as a managed header.
## Fix
1. `lineCommentRegion` now spans only **contiguous** comment lines: any non-comment line, **including a truly-blank line**, ends the run.
2. `spdxIdentifierTag` now requires the tag to **begin a comment line** (leading whitespace allowed), not appear mid-prose.
When in doubt the detector now **under-detects** (leaves a foreign comment alone) rather than over-detecting.
## Why this is safe for idempotency / round-trip
The renderer never emits a truly-blank internal line in a managed header. For line-comment styles, the separator between REUSE tags and the notice block is rendered as a **bare comment prefix** (e.g. `#` or `//`), which is still a comment line and therefore stays in-region. Confining detection to contiguous comment lines is thus byte-idempotent for every header this tool writes, while it stops absorbing foreign comments that a blank line has separated from the header.
Verified by:
- The existing `TestSpliceIdempotent`, `TestApplyFile` (re-apply is idempotent), and `TestApplyFileIdempotentAfterPreserveFirstConstructs` / `...ShebangPHPIdempotent` suites — all still green.
- A new end-to-end applier test `TestApplyFilePreservesDocCommentBelowBlankLine`: inserts a header into a Python file whose body opens with a doc comment, relicenses MIT -> Apache-2.0, and asserts the doc comment below the blank separator survives the replace.
## TDD
Red-green: failing tests written and observed failing for the right reason before the fix.
- detect: blank line ends the region (doc comment excluded); bare-prefix separator stays in-region; `SPDX-License-Identifier` mentioned mid-prose is not a managed header; own-line tag (incl. leading whitespace) still qualifies; Detect-level span guard.
- applier: the relicense round-trip survival test above.
- The previously-enshrining region test (`detect_test.go`) was rewritten to require the corrected contiguous behavior, with the safety rationale inline.
## Deferred
The **[LOW]** sub-issue (block detection spans only the first `/* */`, so a stacked two-block header is not fully de-stacked) is intentionally deferred. Expanding block detection to span multiple blocks would *increase* over-detection risk, which contradicts the safety mandate to prefer under-detection. Spanning only the first block remains the safe choice.
## Gate
- `gofmt -l .` clean
- `go vet ./...` clean
- `go test ./... -race -coverpkg=./internal/...,./cmd/... -covermode=atomic` passing
- coverage threshold: **100% (2079/2079)**
- `golangci-lint run`: 0 issues
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Closes #30
Problem (safety-critical)
License-header detection could over-match and absorb adjacent source content, which on
apply(relicense / year-refresh) causedrender.replaceSpanto delete a real doc comment. A false positive in detection means the tool removes content it does not own.Two distinct over-match paths, both on line-comment file types:
lineCommentRegiontolerated truly-blank lines between comment lines, so the layoutlicense header/ blank line /unrelated file doc commentcollapsed into one detected span. The doc comment was then deleted on the next relicense or year-refresh.spdxIdentifierTagmatchedSPDX-License-Identifier:anywhere in the leading comment viastrings.Index, so a comment that merely mentioned the tag in prose was treated as a managed header.Fix
lineCommentRegionnow spans only contiguous comment lines: any non-comment line, including a truly-blank line, ends the run.spdxIdentifierTagnow requires the tag to begin a comment line (leading whitespace allowed), not appear mid-prose.When in doubt the detector now under-detects (leaves a foreign comment alone) rather than over-detecting.
Why this is safe for idempotency / round-trip
The renderer never emits a truly-blank internal line in a managed header. For line-comment styles, the separator between REUSE tags and the notice block is rendered as a bare comment prefix (e.g.
#or//), which is still a comment line and therefore stays in-region. Confining detection to contiguous comment lines is thus byte-idempotent for every header this tool writes, while it stops absorbing foreign comments that a blank line has separated from the header.Verified by:
TestSpliceIdempotent,TestApplyFile(re-apply is idempotent), andTestApplyFileIdempotentAfterPreserveFirstConstructs/...ShebangPHPIdempotentsuites — all still green.TestApplyFilePreservesDocCommentBelowBlankLine: inserts a header into a Python file whose body opens with a doc comment, relicenses MIT -> Apache-2.0, and asserts the doc comment below the blank separator survives the replace.TDD
Red-green: failing tests written and observed failing for the right reason before the fix.
SPDX-License-Identifiermentioned mid-prose is not a managed header; own-line tag (incl. leading whitespace) still qualifies; Detect-level span guard.detect_test.go) was rewritten to require the corrected contiguous behavior, with the safety rationale inline.Deferred
The [LOW] sub-issue (block detection spans only the first
/* */, so a stacked two-block header is not fully de-stacked) is intentionally deferred. Expanding block detection to span multiple blocks would increase over-detection risk, which contradicts the safety mandate to prefer under-detection. Spanning only the first block remains the safe choice.Gate
gofmt -l .cleango vet ./...cleango test ./... -race -coverpkg=./internal/...,./cmd/... -covermode=atomicpassinggolangci-lint run: 0 issues