fix: check rejects symlink/special/unreadable fragments before any read; exactly one Unreleased header enforced (PR #806 review round-3 P1s)

Author: igerber

.claude/scripts/changelog_compile.py

@@ -125,12 +125,26 @@ def _valid_fragment_name(name):
     return True
 
 
+_UNRELEASED_HEADER_RE = re.compile(r"^## \[Unreleased\]\s*$", flags=re.MULTILINE)
+
+
+def _unreleased_headers(changelog_text):
+    """All '## [Unreleased]' header matches, in file order."""
+    return list(_UNRELEASED_HEADER_RE.finditer(changelog_text))
+
+
 def _unreleased_slice(changelog_text):
-    """Return (start, end) character offsets of the Unreleased section body
-    (after the header line, up to the next '## ' line), or None."""
-    m = re.search(r"^## \[Unreleased\]\s*$", changelog_text, flags=re.MULTILINE)
-    if not m:
+    """Return (start, end) character offsets of the FIRST Unreleased section
+    body (after the header line, up to the next '## ' line), or None.
+
+    Callers must separately enforce that exactly one Unreleased header
+    exists (run_check does) — a duplicate header would otherwise hide its
+    body from this slice.
+    """
+    headers = _unreleased_headers(changelog_text)
+    if not headers:
         return None
+    m = headers[0]
     nl = changelog_text.find("\n", m.start())
     if nl == -1:
         # Header is the last line with no trailing newline: empty body.
@@ -165,19 +179,39 @@ def run_check(root):
                     "YYYYMMDD-<kebab-slug>.md with a real calendar date"
                 )
                 continue
+            # lstat-level guard BEFORE any read: a symlink's content is
+            # mutable out-of-band, and a FIFO/device would hang or crash the
+            # read; neither can be certified.
+            if p.is_symlink() or not p.is_file():
+                findings.append(f"changelog.d/{p.name}: not a regular file (symlink or special)")
+                continue
+            try:
+                text = p.read_text()
+            except (OSError, UnicodeDecodeError) as exc:
+                findings.append(f"changelog.d/{p.name}: unreadable ({exc})")
+                continue
             fragments.append(p)
-            _, errors = _parse_fragment(p.read_text())
+            _, errors = _parse_fragment(text)
             findings.extend(f"changelog.d/{p.name}: {e}" for e in errors)
 
     changelog = root / "CHANGELOG.md"
     if not changelog.is_file():
         findings.append("CHANGELOG.md is missing")
     else:
-        sl = _unreleased_slice(changelog.read_text())
-        if sl is None:
+        changelog_text = changelog.read_text()
+        headers = _unreleased_headers(changelog_text)
+        if not headers:
             findings.append("CHANGELOG.md: '## [Unreleased]' header is missing")
+        elif len(headers) > 1:
+            findings.append(
+                f"CHANGELOG.md: {len(headers)} '## [Unreleased]' headers found "
+                "— exactly one is allowed (a duplicate section would hide "
+                "direct edits from the pointer-only guard)"
+            )
         else:
-            body = changelog.read_text()[sl[0] : sl[1]]
+            sl = _unreleased_slice(changelog_text)
+            assert sl is not None
+            body = changelog_text[sl[0] : sl[1]]
             nonblank = [ln for ln in body.splitlines() if ln.strip()]
             if nonblank != [POINTER_COMMENT]:
                 findings.append(

tests/test_changelog_fragments.py

@@ -228,6 +228,36 @@ def test_missing_unreleased_header_fails(self, mod, tmp_path):
         root = make_repo(tmp_path, changelog=MINIMAL_CHANGELOG.replace("## [Unreleased]\n", ""))
         assert any("Unreleased" in f for f in check_findings(mod, root))
 
+    def test_check_rejects_symlink_fragment_before_reading(self, mod, tmp_path):
+        # A symlink at a fragment path must be a finding at check level (CI),
+        # not just at compile time — its target is mutable out-of-band.
+        root = make_repo(tmp_path)
+        target = root / "real-content.md"
+        target.write_text(GOOD_FRAGMENT)
+        (root / "changelog.d" / "20260830-x.md").symlink_to(target)
+        assert any("not a regular file" in f for f in check_findings(mod, root))
+
+    def test_check_rejects_dangling_symlink_without_crashing(self, mod, tmp_path):
+        root = make_repo(tmp_path)
+        (root / "changelog.d" / "20260830-x.md").symlink_to(root / "does-not-exist.md")
+        assert any("not a regular file" in f for f in check_findings(mod, root))
+
+    def test_check_rejects_undecodable_fragment(self, mod, tmp_path):
+        root = make_repo(tmp_path)
+        (root / "changelog.d" / "20260830-x.md").write_bytes(b"### Fixed\n- \xff\xfe junk\n")
+        assert any("unreadable" in f for f in check_findings(mod, root))
+
+    def test_duplicate_unreleased_headers_fail(self, mod, tmp_path):
+        # A second '## [Unreleased]' section could carry direct bullets that
+        # the first-match slice never inspects; exactly one header is allowed.
+        changelog = MINIMAL_CHANGELOG.replace(
+            "## [1.2.0] - 2026-01-15\n",
+            "## [Unreleased]\n\n### Added\n- smuggled direct bullet\n\n"
+            "## [1.2.0] - 2026-01-15\n",
+        )
+        root = make_repo(tmp_path, changelog=changelog)
+        assert any("exactly one is allowed" in f for f in check_findings(mod, root))
+
     def test_eof_only_unreleased_header_is_finding_not_traceback(self, mod, tmp_path):
         # File ending exactly at the header with no trailing newline must
         # produce a validation finding, not a ValueError.
@@ -351,6 +381,18 @@ def test_exit4_rejects_noncanonical_header_date(self, mod, tmp_path):
         root = make_repo(tmp_path, changelog=changelog)
         assert run_compile(mod, root, version="1.2.0") == 1
 
+    def test_compile_refuses_duplicate_unreleased_headers(self, mod, tmp_path):
+        # check runs as compile's first step, so a duplicate Unreleased
+        # section blocks compilation before any insertion or deletion.
+        changelog = MINIMAL_CHANGELOG.replace(
+            "## [1.2.0] - 2026-01-15\n",
+            "## [Unreleased]\n\n### Added\n- smuggled direct bullet\n\n"
+            "## [1.2.0] - 2026-01-15\n",
+        )
+        root = make_repo(tmp_path, changelog=changelog, fragments={"20260830-x.md": GOOD_FRAGMENT})
+        assert run_compile(mod, root) == 1
+        assert (root / "changelog.d" / "20260830-x.md").exists()
+
     def test_exit4_target_header_at_eof_is_error_not_traceback(self, mod, tmp_path):
         # An existing target header ending the file with no trailing newline
         # must produce the empty-section error, not a ValueError (the same