Skip to content

πŸ› fix(log): handle CRLF log.md β€” normalize on read, preserve on write - #207

Merged
cwest merged 2 commits into
mainfrom
wt/t_59c51fc6-fix-log-s-handle-crlf-log.md-the-same-wa
Oct 28, 2026
Merged

cwest merged 2 commits into
mainfrom
wt/t_59c51fc6-fix-log-s-handle-crlf-log.md-the-same-wa

Conversation

@cwest

@cwest cwest commented Oct 28, 2026

Copy link
Copy Markdown
Owner

Why

A CRLF-checked-out log.md (Windows with core.autocrlf=true, or an editor that writes CRLF) hits the same bug class #185 fixed for index.md: the log read path compared/parsed raw bytes. AppendLog fed parseLog the raw file and parseLog splits on "\n", so every preserved line kept a trailing \r while the newly rendered date group and entry were pure LF β€” a mangled mixed-ending file on every append (whole-file git churn) and a stray \r captured into a folded legacy bullet's message.

Observed before the fix on a CRLF log.md:

"# Change Log\r\n\n## 2026-09-29\n* Fixed a link\n\n## 2026-05-22\n* Added a table reference.\r\n"

What

Fixed at the single log read/write seam with the same decided policy as #205 β€” normalize on read, preserve on write β€” reusing the normalizeEOL / usesCRLF helpers #205 added rather than a second implementation.

  • Normalize on read: parseLog is fed normalizeEOL(existing), so no \r leaks into the verbatim preamble/entries or defeats the $-anchored legacy-bullet regex. Any non-line-ending difference is still real content, so a genuine legacy fold / newest-first insert still happens.
  • Preserve on write: an up-to-date CRLF log is written back CRLF (zero churn); a new file, a mixed-ending file, or a lone-CR file stays LF. The choice depends only on the one file, so it is deterministic on any machine and leaves LF/Linux behavior unchanged.

LF/Linux behavior is unchanged β€” the only place line endings are decided is the single re-ending choice on write.

Tests β€” mirroring #205's EOL set for log.md

New internal/okf/log_eol_test.go:

Test Seam Role
TestAppendLog_CRLFPreservedNoCorruption read + write positive: CRLF append stays CRLF, content is the clean Β§9 render
TestAppendLog_LFStaysLF write LF arm: no CRLF leaks into an LF log
TestAppendLog_NewLogIsLF write a brand-new log.md is LF
TestAppendLog_CRLFLegacyFoldStillWorks read + write genuine-drift / negative control: legacy bullet still regroups, clean Β§9 content, stays CRLF
TestAppendLog_LoneCRNotMangled read boundary negative control: a lone \r (not \r\n) is preserved; non-CRLF file stays LF

Revert controls (each seam goes RED when removed)

  • Preserve-on-write reverted (unconditional LF write) β†’ CRLFPreservedNoCorruption + CRLFLegacyFoldStillWorks FAIL on the usesCRLF assertion; LF/new/lone-CR controls stay green.
  • Normalize-on-read reverted (parse raw bytes) β†’ CRLFPreservedNoCorruption FAILs on the content-equality assertion (CRLF log content mismatch β€” stray \r survives the parse); CRLFLegacyFoldStillWorks FAILs on the exact-content control (a \r captured into the folded message).

Conformance gate β€” all layers, counts pinned

# Layer 1: spec-conformance suite
go test ./internal/okf/ ./cmd/ -run Conformance -race
  ok  internal/okf   ok  cmd

# Layer 2: full suite -race; gofmt; go vet
gofmt -l .   -> (empty)
go vet ./... -> clean
go test ./... -race -> all packages ok

# Layer 3: REAL CORPUS (~/src/knowledge-base/bundles/knowledge, v0.2, 271 nodes)
validate   4 -> 4   (pre-existing legacy-bullet drift; unchanged by this change)
lint --strict   0 -> 0

Before/after counts are the control, proven base-binary vs this change on the same pristine corpus copy: validate 4β†’4, lint 0β†’0. The 4 validate findings are pre-existing legacy-dated-bullet drift in the corpus (not introduced here); the counts do not move, proving the change neither hides nor creates findings.

Real-corpus byte-identity control: appended the same entry via the shipped CLI to 16 log.md files across the LF knowledge bundle with the base binary and this binary β€” 0 differ, byte-identical output, pure LF preserved. LF/Linux behavior is unchanged at corpus scale.

Builds with CGO_ENABLED=0 (no CGO).

Closes #185 for log.md.

A CRLF-checked-out log.md (Windows with core.autocrlf=true, or an editor
that writes CRLF) hit the same bug class #185 fixed for index.md: AppendLog
read the raw bytes and parseLog split on "\n", so every preserved line kept
a trailing \r while the newly rendered date group and entry were pure LF.
The result was a mangled mixed-ending file on every append (whole-file git
churn) and a stray \r captured into a folded legacy bullet's message.

Fixed at the single log read/write seam with the same decided policy as
#205: NORMALIZE ON READ, PRESERVE ON WRITE, reusing the normalizeEOL /
usesCRLF helpers #205 added rather than a second implementation.

  - Normalize on read: parseLog is fed normalizeEOL(existing), so no \r
    leaks into the verbatim preamble/entries or defeats the $-anchored
    legacy-bullet regex. Any non-line-ending difference is still real
    content, so a genuine legacy fold / newest-first insert still happens.
  - Preserve on write: an up-to-date CRLF log is written back CRLF (zero
    churn); a new file, a mixed-ending file, or a lone-CR file stays LF.
    The choice depends only on the one file, so it is deterministic on any
    machine and leaves LF/Linux behavior unchanged.

Closes #185
@cwest
cwest marked this pull request as ready for review October 28, 2026 20:50

@cwest cwest left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

No changes needed.

The log.md EOL handling mirrors the merged index seam line-for-line: normalize on read before the parse, then preserve the file's existing endings on write, gated on usesCRLF. It reuses the shared normalizeEOL and usesCRLF helpers rather than standing up a second copy, so the two reserved files now follow one policy.

I ran the five EOL tests and both revert controls. Removing preserve-on-write turns the two CRLF tests red on the usesCRLF assertion; removing normalize-on-read turns them red on a content mismatch, with a stray carriage return leaking into the preamble and the folded legacy message β€” which is the exact corruption the normalize step prevents. The LF and lone-CR arms stay green under both reverts, so they are independent controls rather than co-triggered.

Against the LF knowledge bundle, this binary produces byte-identical output to the pre-change binary across all sixteen log.md files, pure LF throughout, so the LF path is untouched. Conformance suite, full race suite, gofmt, and vet are all clean.

@cwest
cwest merged commit 5cd4035 into main Oct 28, 2026
10 checks passed
@cwest
cwest deleted the wt/t_59c51fc6-fix-log-s-handle-crlf-log.md-the-same-wa branch October 28, 2026 21:25
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.

πŸ› fix(index): index check reports CRLF index.md as stale; index build doubles curator shape suffixes on CRLF

1 participant