From 0609de824635e6edc3e219fcb361a394c4c86948 Mon Sep 17 00:00:00 2001 From: LGuichet Date: Fri, 30 Oct 2026 19:08:58 +0100 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20fix(index):=20leave=20an=20i?= =?UTF-8?q?ndex=20whose=20content=20is=20current=20untouched?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit index build rewrote every index.md on every run, and an index with mixed line endings (an editor or agent wrote LF lines into a CRLF file) came out LF even when nothing changed. On a core.autocrlf=true checkout git then reports the file modified with an empty diff, since its size no longer matches the CRLF size git recorded. Compare the render with the on-disk file the way index check does (line endings are not content) and skip the write when they match. A changed index still keeps CRLF when it was pure CRLF, and falls back to LF otherwise. Co-Authored-By: Claude Opus 5.5 --- internal/okf/index_eol_test.go | 54 ++++++++++++++++++++++++++++++ internal/okf/reserved_lifecycle.go | 19 ++++++++--- 2 files changed, 68 insertions(+), 5 deletions(-) diff --git a/internal/okf/index_eol_test.go b/internal/okf/index_eol_test.go index 41c12f8..2a689c4 100644 --- a/internal/okf/index_eol_test.go +++ b/internal/okf/index_eol_test.go @@ -19,6 +19,7 @@ import ( "path/filepath" "strings" "testing" + "time" ) // toCRLF rewrites a file with CRLF endings, as a Windows checkout with @@ -120,6 +121,7 @@ func TestWriteIndex_PreservesExistingLineEndings(t *testing.T) { t.Fatal(err) } writeNode(t, dir, "wine/acidity.md", "Reference", "Acidity") // forces a real wine/ change + writeNode(t, dir, "beer/malt.md", "Reference", "Malt") // and a real beer/ change writeNode(t, dir, "cider/apple.md", "Reference", "Apple") // a brand-new index b := buildAndReload(t, dir) @@ -141,6 +143,58 @@ func TestWriteIndex_PreservesExistingLineEndings(t *testing.T) { } } +// index build leaves an index whose content is already current untouched, +// whatever its line endings: same bytes, same mtime. A CRLF checkout whose +// index went LF or mixed (an editor or an older tool rewrote it) is otherwise +// rewritten on every build, and git, which recorded the CRLF size, reports it +// modified with an empty diff. The control: an index whose content did change +// is still rewritten. +func TestWriteIndex_UnchangedIndexIsNotRewritten(t *testing.T) { + dir := t.TempDir() + _ = Scaffold(dir) + writeNode(t, dir, "wine/tannin.md", "Reference", "Tannin") + writeNode(t, dir, "beer/hops.md", "Reference", "Hops") + writeNode(t, dir, "cider/apple.md", "Reference", "Apple") + _ = buildAndReload(t, dir) + + crlf := filepath.Join(dir, "wine", "index.md") + mixed := filepath.Join(dir, "beer", "index.md") + lf := filepath.Join(dir, "cider", "index.md") + toCRLF(t, crlf) + if err := os.WriteFile(mixed, []byte(strings.Replace(readFile(t, mixed), "\n", "\r\n", 1)), 0o644); err != nil { + t.Fatal(err) + } + old := time.Now().Add(-time.Hour) + before := map[string]string{} + for _, p := range []string{crlf, mixed, lf} { + before[p] = readFile(t, p) + if err := os.Chtimes(p, old, old); err != nil { + t.Fatal(err) + } + } + writeNode(t, dir, "perry/pear.md", "Reference", "Pear") // changes the root index only + + b := buildAndReload(t, dir) + if ok, diff := IndexInSync(b); !ok { + t.Fatalf("index must be in sync right after build; got: %s", diff) + } + for p, want := range before { + if got := readFile(t, p); got != want { + t.Errorf("%s: unchanged index must keep its bytes;\nwas %q\nnow %q", p, want, got) + } + fi, err := os.Stat(p) + if err != nil { + t.Fatal(err) + } + if !fi.ModTime().Equal(old) { + t.Errorf("%s: unchanged index must not be rewritten (mtime moved)", p) + } + } + if got := readFile(t, filepath.Join(dir, "index.md")); !strings.Contains(got, "perry/index.md") { + t.Errorf("a changed root index must still be rewritten; got %q", got) + } +} + // A curator-authored subdirectory description in a CRLF index survives a // rebuild intact: the trailing CR must not defeat the shape-suffix strip, which // would capture the old suffix into the description and double it. diff --git a/internal/okf/reserved_lifecycle.go b/internal/okf/reserved_lifecycle.go index 6c64248..4959ee6 100644 --- a/internal/okf/reserved_lifecycle.go +++ b/internal/okf/reserved_lifecycle.go @@ -474,11 +474,20 @@ func WriteIndexWithOptions(b *Bundle, opts IndexShapeOptions) error { return err } out := RenderDirIndexWithOptions(b, dir, opts) - // Keep the line endings of the index being replaced (see usesCRLF): a CRLF - // checkout (Windows, core.autocrlf=true) stays CRLF instead of flipping - // every line. A new or mixed-ending index gets the canonical LF. - if existing, err := os.ReadFile(p); err == nil && usesCRLF(existing) { //nolint:gosec // G304: reading the tool's own generated index file - out = strings.ReplaceAll(out, "\n", "\r\n") + existing, err := os.ReadFile(p) //nolint:gosec // G304: reading the tool's own generated index file + if err == nil { + // Already current (line endings are not content, as in IndexInSync): + // leave the file alone. Rewriting it would only change its line + // endings, which on a CRLF checkout makes git report it modified. + if normalizeEOL(string(existing)) == out { + continue + } + // Keep the line endings of the index being replaced (see usesCRLF): a + // CRLF checkout (Windows, core.autocrlf=true) stays CRLF instead of + // flipping every line. A new or mixed-ending index gets the canonical LF. + if usesCRLF(existing) { + out = strings.ReplaceAll(out, "\n", "\r\n") + } } if err := fsutil.WriteFileAtomic(p, []byte(out), 0o644); err != nil { //nolint:gosec // G306: a bundle index file is shareable content; 0o644 is intended return err From 1d8e768ac2596ddd1076194cdcd303e0b1a855fd Mon Sep 17 00:00:00 2001 From: LGuichet Date: Fri, 30 Oct 2026 19:18:19 +0100 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20fix(migrate):=20double-quote?= =?UTF-8?q?=20an=20okf=5Fversion=20target=20with=20a=20control=20character?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit bumpRootIndexMarker left the scalar style to yaml.v3, which writes a target such as a tab then a newline as a literal block whose tab-led line no parser reads back, so migrate --apply could leave an unparseable bundle-root index.md. FuzzRootIndexMarker caught it in CI on #13. Force double-quoted style when the target holds a control character; every other target is written as before. The input joins the fuzz seeds. Co-Authored-By: Claude Opus 5.5 --- internal/okf/migrate.go | 11 +++++++++++ internal/okf/writepath_fuzz_test.go | 4 +++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/internal/okf/migrate.go b/internal/okf/migrate.go index faa8ba5..748491c 100644 --- a/internal/okf/migrate.go +++ b/internal/okf/migrate.go @@ -544,6 +544,17 @@ func bumpRootIndexMarker(root, target string) error { return nil // no marker to bump, or already at target (idempotent no-op) } setScalar(m, "okf_version", target) + // A target with a control character (the plan is user-editable) is written + // double-quoted, where every such character is escaped. Left to yaml.v3, a + // tab and a newline become a literal block whose tab-led line no parser + // reads back. + if strings.ContainsFunc(target, func(r rune) bool { return r < 0x20 || r == 0x7f }) { + for i := 0; i+1 < len(m.Content); i += 2 { + if m.Content[i].Value == "okf_version" { + m.Content[i+1].Style = yaml.DoubleQuotedStyle + } + } + } var fmBuf bytes.Buffer enc := yaml.NewEncoder(&fmBuf) diff --git a/internal/okf/writepath_fuzz_test.go b/internal/okf/writepath_fuzz_test.go index c434fd4..2e10f1f 100644 --- a/internal/okf/writepath_fuzz_test.go +++ b/internal/okf/writepath_fuzz_test.go @@ -175,7 +175,9 @@ func FuzzTouchModifiedRoundTrip(f *testing.F) { // string, the rewrite keeps the key set and the body, and a target with no // control character is read back by Load as declared. func FuzzRootIndexMarker(f *testing.F) { - for _, s := range []string{"0.2", "0.3", "1.0", "0.2\ninjected: true", "0.2\r---\r", "'", "\"", "- x", "{a: b}", " 0.2 "} { + // "\t\n0": yaml.v3 picks a literal block for it, whose tab-led line no parser + // reads back. + for _, s := range []string{"0.2", "0.3", "1.0", "0.2\ninjected: true", "0.2\r---\r", "'", "\"", "- x", "{a: b}", " 0.2 ", "\t\n0"} { f.Add(s) } const body = "\n# Index\n\n---\n\nA rule above.\n"