todo.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/registry/render/roadmap/todo.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/roadmap/test_render_living_set.py"
"""
The comprehensive V3 ``ROADMAP-EXTENDED.md`` renderer (Plan 142 P1.6, §6).
 
Purpose
-------
Render the full historical record from the verified authored projection. This
module — historically the retired ``ROADMAP-TODO.md`` renderer (the
``roadmap_todo`` output is retired, AC §8.24) — is **repurposed** ([OP-2]) to
produce ``ROADMAP-EXTENDED.md``: the same milestone table as the lean view plus
sub-phase detail for **all** phases, the non-phase + git-workflow item tables,
and a store-derived Versioning Notes section. Section order/selection are driven
by the seeded ``roadmap_render_sections`` manifest for ``file_kind=
'roadmap_extended'``.
 
Responsibilities
----------------
- ``render(conn, *, source_hash, logical_state_hash, published=None)`` — the
  EXTENDED view as a single byte-deterministic markdown string.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - render lifecycle
    L3 - section counts
    L4 - per-line assembly
 
Contracts
---------
- Read-only; deterministic (no wall-clock).
- Reads only INCLUDED §3.2 columns + the verified-derived version ``status``
  (recomputed-and-verified at step-7) through the render guard.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.render.roadmap._common (EXTENDED renderer id, generated header and footer, guarded query)
- oc_chat.registry.render.roadmap.render_sections (EXTENDED file kind for the render-section manifest)
- oc_chat.registry.render.roadmap.roadmap_main (shared manifest sections, version line, current pointer, legend and contents)
- oc_chat.registry.render.roadmap.store_read (selected roadmap version)
- oc_chat.registry.render.roadmap.sections (table cell escaping for the versioning notes)
"""
from __future__ import annotations
 
import sqlite3
from typing import Optional
 
from oc_diagnostics import _dbg
 
from oc_chat.registry.render.roadmap import roadmap_main
from oc_chat.registry.render.roadmap import sections as section_render
from oc_chat.registry.render.roadmap import store_read
from oc_chat.registry.render.roadmap._common import (
    RENDERER_EXTENDED,
    build_generated_header,
    generated_footer,
    guarded_query,
)
from oc_chat.registry.render.roadmap.render_sections import FILE_KIND_EXTENDED
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
_TITLE = "# OC Chat Roadmap — Extended Record"
_VERSION_HEADER = (
    "| Version | Era | Bump | State | Released | Notes |\n"
    "|---------|-----|------|-------|----------|-------|"
)
 
 
def render(
    conn: sqlite3.Connection,
    *,
    source_hash: str,
    logical_state_hash: str,
    published: Optional[str] = None,
    note_sections: Optional[list[str]] = None,
) -> str:
    """Render the comprehensive V3 ``ROADMAP-EXTENDED.md`` as deterministic bytes.
 
    ``note_sections`` are the pre-rendered framing-note sections (Sources /
    Reconciliation / Execution Order / Out Of Scope / Git Workflow) read from
    ``source/notes`` by ``render_living_set`` — appended as an EXTENDED-only
    appendix (the lean view never carries them); store-only ``render`` keeps no
    source handle, so the caller passes them in.
    """
    func = "render"
    header = build_generated_header(
        source_hash=source_hash,
        logical_state_hash=logical_state_hash,
        renderer=RENDERER_EXTENDED,
    )
    version = store_read.selected_roadmap_version(conn)
    body = roadmap_main._render_manifest_sections(conn, FILE_KIND_EXTENDED)
    versioning = _versioning_notes(conn)
    if versioning:
        if body:
            body.append("")
        body.extend(versioning)
    if note_sections:
        if body:
            body.append("")
        body.extend(note_sections)
    lines: list[str] = [
        header,
        "",
        _TITLE,
        "",
        roadmap_main._version_line(version, published),
        "",
        # OCT-LINT: disable=no_hardcoded_secrets reason="Markdown labels + glyphs are presentation, not secrets"
        "A complete index of every OC Chat roadmap phase, sub-phase, non-phase "
        "item, and shipped version — the full historical record (see ROADMAP.md "
        "for the lean working map).",
        "",
        "---",
        "",
        *roadmap_main._current_block(conn),
        "",
        "---",
        "",
        *roadmap_main.legend_lines(),
    ]
    toc = roadmap_main._toc(body)
    if toc:
        lines.extend(["", *toc])
    lines.extend(["", *body])
    lines.extend(["", *generated_footer("roadmap_extended")])
    _dbg("OC_CHAT.MAIN", func, f"extended rendered version={version}", 2)
    return "\n".join(lines).rstrip() + "\n"
 
 
def _versioning_notes(conn: sqlite3.Connection) -> list[str]:
    """Render the EXTENDED-only Versioning Notes table from ``roadmap_versions``."""
    conn.row_factory = sqlite3.Row
    rows = guarded_query(
        conn,
        # OCT-LINT: disable=no_hardcoded_secrets reason="Markdown labels + glyphs are presentation, not secrets"
        "SELECT version_id, era_id, bump_kind, status, released_at, notes "
        "FROM roadmap_versions ORDER BY version_id",
    ).fetchall()
    if not rows:
        return []
    lines = ["## Versioning Notes", "", _VERSION_HEADER]
    for row in rows:
        lines.append(
            "| {version} | {era} | {bump} | {state} | {released} | {notes} |".format(
                version=section_render.escape(row["version_id"]),
                era=section_render.escape(row["era_id"]),
                bump=section_render.escape(row["bump_kind"]),
                state=section_render.escape(row["status"]),
                released=section_render.escape(row["released_at"]),
                notes=section_render.escape(row["notes"] or ""),
            )
        )
    return lines
 
 
__all__ = ["render"]