seed_142_changelog_reseed.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tools/seed_142_changelog_reseed.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/seed/test_changelog_reseed.py"
"""
Full changelog re-seed (byte-faithful): ROADMAP-CHANGELOG-v3.38.md ->
source/changelog/** (Plan 142 prose-preservation Phase 1, §9 completeness).
 
Purpose
-------
Tile the COMPLETE authoritative changelog (the WHOLE file: preamble + every
``# ▶`` era/section banner + every ``## `` block + the pre-v2.27 historical
tables + the velocity reference + the end note) into one record per top-level
segment, each record **body = the verbatim original slice**. The render
(``changelog._render_verbatim``) concatenates the bodies in ``changelog_seq``
order joined by ``\\n\\n---\\n\\n`` -> byte-identical to the original (modulo only
the generated provenance header). No frontmatter duplication (no junk
``entries``, no re-typed ``notes``) — the body is the single source of visible
prose, so the ``option_c_specs``-class transcription error cannot recur.
 
Keying (surfaced at the gate): one ``kind: roadmap`` record per segment, ordered
by ``extensions.changelog_seq``; ``version`` = the real ``vN.NN`` for a bumped
round (creates a ``roadmap_versions`` row for the lean/extended render), the real
product SemVer for a ``v0.7.x`` release (no store row), or a synthesized
``v0.0.<seq>`` SemVer for the framing / no-version-bump / summary segments (no
store row, unique). ``era`` = ``v3`` (metadata; the visible era banners live in
the segment bodies, so the renderer needs no era-grouping logic).
 
Responsibilities
----------------
- ``segments`` (split on the ``---`` rule), ``classify``, ``reseed``, ``coverage``.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - reseed lifecycle
    L3 - per-segment classification
    L4 - per-record emission
 
Contracts
---------
- Deterministic; never writes outside the source tree's ``changelog/``; every
  record validates; the segment bodies tile the original byte-for-byte.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.regenerate (imported for the contracts bootstrap it runs)
- option_c_registry_contracts (the Version model, SCHEMA_VERSION and ROADMAP_VERSION_RE for each changelog record)
- oc_chat.registry.source.canonical (format_record_text - writes each record's frontmatter and verbatim body)
"""
from __future__ import annotations
 
import re
from dataclasses import dataclass, field
from pathlib import Path
 
from oc_diagnostics import _dbg
 
import oc_chat.registry.regenerate  # noqa: F401  (contracts bootstrap)
import option_c_registry_contracts as rc
 
from oc_chat.registry.source.canonical import format_record_text
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
_ERA = "v3"
_SEPARATOR = "\n\n---\n\n"
_BUMP_RE = re.compile(r"→\s*v(\d+\.\d{2})\b")
_SEMVER_RE = re.compile(r"\bv(\d+\.\d+\.\d+)\b")
_ISO_DATE_RE = re.compile(r"(\d{4}-\d{2}-\d{2})")
_DEFAULT_DATE = "2026-06-02"
 
 
@dataclass
class ReseedReport:
    records: int = 0
    segments: int = 0
    store_versions: int = 0
    coverage: list = field(default_factory=list)  # (seq, version, header_excerpt)
 
 
def segments(text: str) -> list[str]:
    """Split the changelog into top-level segments on the ``---`` horizontal rule.
 
    Every ``---`` in the file separates two top-level sections (preamble, era
    banners, ``## `` blocks, the historical/velocity tables, the end note); there
    are no ``---`` inside a block, so this tiling is exact + lossless.
    """
    body = text.replace("\r\n", "\n").strip("\n")
    return [chunk.strip("\n") for chunk in body.split(_SEPARATOR)]
 
 
def _iso_date(segment: str) -> str:
    match = _ISO_DATE_RE.search(segment)
    return match.group(1) if match else _DEFAULT_DATE
 
 
def classify(segment: str, seq: int) -> str:
    """Return the ``version`` for a segment (real vN.NN/SemVer or synthesized)."""
    header = segment.splitlines()[0] if segment else ""
    bump = _BUMP_RE.search(header)
    if bump is not None:
        return f"v{bump.group(1)}"  # bumped round -> roadmap-axis (store row)
    if header.startswith("## ") and "v3.00 ROADMAP supersession" in header:
        return "v3.00"
    semver = _SEMVER_RE.search(header)
    if header.startswith("## ") and semver is not None:
        return f"v{semver.group(1)}"  # v0.7.x product release (no store row)
    return f"v0.0.{seq}"  # framing / no-version-bump / summary (no store row)
 
 
def _slug(segment: str) -> str:
    header = (segment.splitlines()[0] if segment else "").lstrip("# ")
    slug = re.sub(r"[^a-z0-9]+", "-", header.lower()).strip("-")
    return slug[:48] or "segment"
 
 
def reseed(changelog_md: Path, source_dir: Path) -> ReseedReport:
    """Tile the legacy changelog into verbatim ``source/changelog/roadmap/*`` records."""
    func = "reseed"
    text = Path(changelog_md).read_text(encoding="utf-8")
    chunks = segments(text)
    out = Path(source_dir) / "changelog" / "roadmap"
    for stale in (Path(source_dir) / "changelog").rglob("*.md"):
        stale.unlink()
    out.mkdir(parents=True, exist_ok=True)
 
    report = ReseedReport(segments=len(chunks))
    for index, chunk in enumerate(chunks, start=1):
        version = classify(chunk, index)
        if re.fullmatch(rc.ROADMAP_VERSION_RE, version):
            report.store_versions += 1
        model = rc.Version(
            schema_version=rc.SCHEMA_VERSION,
            version=version,
            date=_iso_date(chunk),
            era=_ERA,
            kind="roadmap",
            extensions={"changelog_seq": index},
        )
        path = out / f"{index:03d}-{_slug(chunk)}.md"
        path.write_text(format_record_text(model, body=chunk), encoding="utf-8", newline="")
        header = chunk.splitlines()[0] if chunk else ""
        report.coverage.append((index, version, header[:80]))
    report.records = len(chunks)
    _dbg("OC_CHAT.MAIN", func, f"reseeded {len(chunks)} segments", 2)
    return report