fix(release-doc-sync): keep [Unreleased] on top and match version headings only

The CHANGELOG stub is now inserted before the first versioned heading,
so a Keep a Changelog [Unreleased] section stays above it. Idempotency
checks for a "## [X.Y.Z]" heading instead of any "[X.Y.Z]" substring, so
prose mentions and footer link refs no longer suppress the stub. Removes
the unused _CHANGELOG_VERSION_RE and writes LF line endings.

Closes #108

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

Author: TMHSDigital

scripts/release_doc_sync/sync.py

@@ -85,8 +85,16 @@ def changed(self) -> bool:
 # ---------------------------------------------------------------------------
 
 
-_CHANGELOG_VERSION_RE = re.compile(r"^##\s*\[(\d+\.\d+\.\d+)\]", re.MULTILINE)
-_CHANGELOG_FIRST_RELEASE_RE = re.compile(r"^##\s*\[", re.MULTILINE)
+# First versioned release heading. ``## [Unreleased]`` is deliberately not
+# matched: in Keep a Changelog order it stays above every release.
+_CHANGELOG_FIRST_RELEASE_RE = re.compile(r"^##\s*\[\d", re.MULTILINE)
+
+
+def _has_release_heading(text: str, version: str) -> bool:
+    """True only when ``## [version]`` exists as a heading. Mentions in
+    prose or footer link refs (``[X.Y.Z]: url``) do not count."""
+    pattern = re.compile(r"^##\s*\[" + re.escape(version) + r"\]", re.MULTILINE)
+    return pattern.search(text) is not None
 
 
 def sync_changelog(
@@ -109,12 +117,14 @@ def sync_changelog(
 
         See [release notes](https://github.com/<repo>/releases/tag/vX.Y.Z) for details.
 
-    Idempotency: if ``## [X.Y.Z]`` already appears anywhere in the file,
-    the function returns ``idempotent`` without touching the file.
+    Idempotency: if a ``## [X.Y.Z]`` heading already exists, the function
+    returns ``idempotent`` without touching the file. Prose mentions and
+    footer link refs are ignored.
 
-    Insertion point: immediately before the first existing ``## [`` release
-    section. If no release sections exist yet, append after the file's
-    existing content (one trailing blank line is normalized).
+    Insertion point: immediately before the first existing versioned
+    ``## [N...`` release section, which keeps ``## [Unreleased]`` on top.
+    If no release sections exist yet, append after the file's existing
+    content (one trailing blank line is normalized).
 
     Footer link refs (``[X.Y.Z]: <url>``) are intentionally NOT auto-added.
     Steam's Keep-a-Changelog format uses them, but maintaining the link
@@ -128,7 +138,7 @@ def sync_changelog(
 
     text = path.read_text(encoding="utf-8")
 
-    if f"[{plugin_version}]" in text:
+    if _has_release_heading(text, plugin_version):
         return FileResult(
             path=path,
             action="idempotent",
@@ -154,7 +164,7 @@ def sync_changelog(
             text = text + "\n"
         new_text = text + stub
 
-    path.write_text(new_text, encoding="utf-8")
+    path.write_text(new_text, encoding="utf-8", newline="\n")
     return FileResult(
         path=path,
         action="inserted",
@@ -237,7 +247,7 @@ def _rewrite_version_line(match: re.Match) -> str:
             detail="no version patterns matched or already aligned",
         )
 
-    path.write_text(text, encoding="utf-8")
+    path.write_text(text, encoding="utf-8", newline="\n")
     return FileResult(
         path=path,
         action="updated",
@@ -301,7 +311,7 @@ def sync_roadmap(path: Path, *, plugin_version: str) -> FileResult:
         + f"{match.group(1)}v{plugin_version}"
         + text[match.end() :]
     )
-    path.write_text(new_text, encoding="utf-8")
+    path.write_text(new_text, encoding="utf-8", newline="\n")
     return FileResult(
         path=path,
         action="updated",

tests/test_release_doc_sync.py

@@ -260,6 +260,52 @@ def test_missing_file_returns_missing(self, tmp_path: Path):
         assert result.changed is False
         assert not path.exists()
 
+    def test_inserts_below_unreleased_section(self, tmp_path: Path):
+        path = tmp_path / "CHANGELOG.md"
+        path.write_text(
+            "# Changelog\n\n"
+            "## [Unreleased]\n\n- pending change\n\n"
+            "## [1.0.0] - 2026-01-01\n\n- first\n",
+            encoding="utf-8",
+        )
+        result = sync_changelog(
+            path,
+            plugin_version="1.1.0",
+            repository="TMHSDigital/X",
+            release_date="2026-04-25",
+        )
+        assert result.action == "inserted"
+        text = path.read_text(encoding="utf-8")
+        assert text.index("## [Unreleased]") < text.index("## [1.1.0]") < text.index("## [1.0.0]")
+
+    def test_prose_and_link_refs_do_not_count_as_present(self, tmp_path: Path):
+        path = tmp_path / "CHANGELOG.md"
+        path.write_text(
+            "# Changelog\n\nUpgrading to [2.0.0] soon.\n\n"
+            "## [1.0.0] - 2026-01-01\n\n- first\n\n"
+            "[2.0.0]: https://example.invalid/v2.0.0\n",
+            encoding="utf-8",
+        )
+        result = sync_changelog(
+            path,
+            plugin_version="2.0.0",
+            repository="TMHSDigital/X",
+            release_date="2026-04-25",
+        )
+        assert result.action == "inserted"
+        assert "## [2.0.0] - 2026-04-25" in path.read_text(encoding="utf-8")
+
+    def test_writes_lf_line_endings(self, tmp_path: Path):
+        path = tmp_path / "CHANGELOG.md"
+        path.write_bytes(b"# Changelog\n\n## [1.0.0] - 2026-01-01\n")
+        sync_changelog(
+            path,
+            plugin_version="1.0.1",
+            repository="TMHSDigital/X",
+            release_date="2026-04-25",
+        )
+        assert b"\r\n" not in path.read_bytes()
+
 
 # ---------------------------------------------------------------------------
 # CLAUDE tests