render_sections.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/registry/render/roadmap/render_sections.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/roadmap/test_render_sections.py"
"""
The deterministic ``roadmap_render_sections`` layout (Plan 142 P1.6 seam, §6.1).
 
Purpose
-------
``roadmap_render_sections`` is in the §3.2 logical hash but has **no §3.1 source
entity** (the P1.4 build leaves it empty on rebuild — umbrella §12 wave-3). P1.6
owns **defining + seeding** the deterministic render-section set so the
lean / EXTENDED / changelog / root views are produced deterministically and the
logical-state hash is stable. The build-vs-render seam: ``regenerate``'s builder
calls ``seed_render_sections`` so the rows land in the hashed store (the §6.1
"re-pointed at the lean/EXTENDED/changelog file_kinds" requirement).
 
Responsibilities
----------------
- ``RENDER_SECTIONS`` — the canonical, sorted, deterministic section manifest.
- ``seed_render_sections(conn)`` — insert it into the temp DB during the build.
- ``validate_render_sections(...)`` — reject an **active** row with a retired
  file_kind (AC §8.24); retired kinds (``roadmap_exec_order``/``roadmap_todo``)
  are kept ``active=0`` (L-a superset CHECK + active-only liveness rule).
- ``sections_for(conn, file_kind)`` — the renderer's data-driven section list.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - seed lifecycle
    L3 - per-file_kind section counts
    L4 - per-row insert tracing
 
Contracts
---------
- The manifest is a Python constant (no source entity); it is deterministic +
  byte-stable, so seeding it keeps the logical-state hash reproducible.
- ``query_params_json`` is stored as canonical JSON so two rebuilds match and
  the §3.2 ``_canonical_query_params`` re-emit is a no-op.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.canonical (canonical_json)
"""
from __future__ import annotations
 
import sqlite3
from dataclasses import dataclass
from typing import Any, Optional
 
from oc_diagnostics import _dbg
 
from oc_chat.registry.canonical import canonical_json
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
#: Active GeneratedView file_kinds (§6 file set).
FILE_KIND_LEAN = "roadmap"
FILE_KIND_EXTENDED = "roadmap_extended"
FILE_KIND_CHANGELOG = "roadmap_changelog"
FILE_KIND_ROOT_CHANGELOG = "root_changelog"
 
#: Retired output file_kinds — kept in the schema CHECK as ``active=0`` only
#: (L-a / [OP-1]d); no active renderer export path may emit them (AC §8.24).
RETIRED_FILE_KINDS = frozenset({"roadmap_exec_order", "roadmap_todo"})
 
 
@dataclass(frozen=True)
class RenderSection:
    """One declarative render section (a ``roadmap_render_sections`` row)."""
 
    file_kind: str
    section_path: str
    sort_order: int
    query_kind: str
    query_params: Optional[dict[str, Any]] = None
    required_min_version: Optional[str] = None
    active: bool = True
 
    def params_json(self) -> Optional[str]:
        if self.query_params is None:
            return None
        return canonical_json(self.query_params)
 
 
#: Backlog-style non-phase track kinds rendered as item tables.
_NON_PHASE_TRACKS = {"track_kinds": ["pre_m0_era", "backlog", "vision"]}
 
#: The canonical, deterministic render-section manifest (§6.1). Section order
#: within a file_kind is ``sort_order``; the lean view shows live-phase detail
#: only, the EXTENDED view all phases (DESIGN §3). Changelog views read their
#: entries from ``source/changelog/**`` directly (§3.2 store/source boundary), so
#: they carry a single ``prose_only`` anchor section.
RENDER_SECTIONS: tuple[RenderSection, ...] = (
    # --- lean ROADMAP.md (V4) ---
    RenderSection(FILE_KIND_LEAN, "era-overview", 0, "prose_only"),
    RenderSection(FILE_KIND_LEAN, "milestones", 1, "m_phase_table"),
    RenderSection(FILE_KIND_LEAN, "phase-detail", 2, "phase_section_with_subrows",
                  {"scope": "live"}),
    RenderSection(FILE_KIND_LEAN, "backlog", 3, "backlog_track_table", _NON_PHASE_TRACKS),
    # --- comprehensive ROADMAP-EXTENDED.md (V3) ---
    RenderSection(FILE_KIND_EXTENDED, "era-overview", 0, "prose_only"),
    RenderSection(FILE_KIND_EXTENDED, "milestones", 1, "m_phase_table"),
    RenderSection(FILE_KIND_EXTENDED, "phase-detail", 2, "phase_section_with_subrows",
                  {"scope": "all"}),
    RenderSection(FILE_KIND_EXTENDED, "backlog", 3, "backlog_track_table", _NON_PHASE_TRACKS),
    RenderSection(FILE_KIND_EXTENDED, "git-workflow", 4, "git_workflow_table"),
    # --- ROADMAP-CHANGELOG.md (source-only, kind: roadmap) ---
    RenderSection(FILE_KIND_CHANGELOG, "changelog", 0, "prose_only"),
    # --- verbatim root CHANGELOG.md (source-only, kind: product) ---
    RenderSection(FILE_KIND_ROOT_CHANGELOG, "product-changelog", 0, "prose_only"),
    # --- retired output kinds (kept active=0 only — AC §8.24) ---
    RenderSection("roadmap_exec_order", "retired", 0, "prose_only", active=False),
    RenderSection("roadmap_todo", "retired", 0, "prose_only", active=False),
)
 
 
class RetiredFileKindActiveError(ValueError):
    """An active render section names a retired output file_kind (AC §8.24)."""
 
 
def validate_render_sections(sections: "tuple[RenderSection, ...]" = RENDER_SECTIONS) -> None:
    """Reject any **active** section whose file_kind is retired (AC §8.24)."""
    offenders = [
        section.section_path
        for section in sections
        if section.active and section.file_kind in RETIRED_FILE_KINDS
    ]
    if offenders:
        raise RetiredFileKindActiveError(
            f"active render section(s) {offenders} use a retired file_kind "
            f"{sorted(RETIRED_FILE_KINDS)}; retired kinds must be active=0"
        )
 
 
def assert_active_file_kinds_in_db(conn: sqlite3.Connection) -> None:
    """Backstop the active-only liveness rule against the built store (AC §8.24)."""
    rows = conn.execute(
        # OCT-LINT: disable=no_hardcoded_secrets reason="file_kind/query_kind tokens + section ids are schema constants"
        "SELECT file_kind FROM roadmap_render_sections "
        "WHERE active = 1 AND file_kind IN (?, ?)",
        tuple(sorted(RETIRED_FILE_KINDS)),
    ).fetchall()
    if rows:
        raise RetiredFileKindActiveError(
            f"store has active render rows for retired file_kind(s) "
            f"{sorted({row[0] for row in rows})}"
        )
 
 
def seed_render_sections(conn: sqlite3.Connection) -> int:
    """Seed the canonical render-section manifest into ``conn`` (the build seam).
 
    Idempotent: clears + re-inserts the deterministic set. Returns the row count.
    Called by the P1.4 builder so the rows enter the hashed store (§6.1).
    """
    func = "seed_render_sections"
    validate_render_sections()
    conn.execute("DELETE FROM roadmap_render_sections")
    for section in RENDER_SECTIONS:
        conn.execute(
            # OCT-LINT: disable=no_hardcoded_secrets reason="file_kind/query_kind tokens + section ids are schema constants"
            "INSERT INTO roadmap_render_sections(file_kind, section_path, sort_order, "
            "query_kind, query_params_json, required_min_version, active) "
            "VALUES(?,?,?,?,?,?,?)",
            (section.file_kind, section.section_path, section.sort_order,
             section.query_kind, section.params_json(), section.required_min_version,
             int(section.active)),
        )
    _dbg("OC_CHAT.MAIN", func, f"seeded {len(RENDER_SECTIONS)} rows", 3)
    return len(RENDER_SECTIONS)
 
 
def sections_for(conn: sqlite3.Connection, file_kind: str) -> list[sqlite3.Row]:
    """Return the active sections for ``file_kind`` in render order (§6.1)."""
    conn.row_factory = sqlite3.Row
    return conn.execute(
        # OCT-LINT: disable=no_hardcoded_secrets reason="file_kind/query_kind tokens + section ids are schema constants"
        "SELECT section_path, sort_order, query_kind, query_params_json "
        "FROM roadmap_render_sections WHERE file_kind = ? AND active = 1 "
        "ORDER BY sort_order, section_path",
        (file_kind,),
    ).fetchall()
 
 
__all__ = [
    "FILE_KIND_LEAN",
    "FILE_KIND_EXTENDED",
    "FILE_KIND_CHANGELOG",
    "FILE_KIND_ROOT_CHANGELOG",
    "RETIRED_FILE_KINDS",
    "RenderSection",
    "RENDER_SECTIONS",
    "RetiredFileKindActiveError",
    "validate_render_sections",
    "assert_active_file_kinds_in_db",
    "seed_render_sections",
    "sections_for",
]