roadmap_main.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/registry/render/roadmap/roadmap_main.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/roadmap/test_render_living_set.py"
"""
The lean V4 ``ROADMAP.md`` renderer (Plan 142 P1.6, §6 / DESIGN §3).
 
Purpose
-------
Render the lean working map from the verified authored projection: the §6
generated header → title → Version line → ``📍 Now`` current pointer → legend →
era overview → milestone table (with ``Done N/M`` + purpose) → live-phase
sub-phase detail. The section order + selection are driven by the seeded
``roadmap_render_sections`` manifest for ``file_kind='roadmap'`` (the P1.4↔P1.6
seam), so the view is produced deterministically. ``current = null`` renders the
byte-pinned all-complete line (AC §8.52); every status/priority maps through the
§7 glyph table (AC §8.7).
 
Responsibilities
----------------
- ``render(conn, *, source_hash, logical_state_hash, published=None)`` — the lean
  view as a single byte-deterministic markdown string (header included).
- ``legend_lines`` — the shared §7 legend (reused by the EXTENDED view).
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - render lifecycle
    L3 - current pointer + section counts
    L4 - per-line assembly
 
Contracts
---------
- Read-only; deterministic (no wall-clock — ``Updated`` is stamped only when a
  ``published`` boundary date is supplied).
- Reads only INCLUDED §3.2 columns through the ``store_read`` guard.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.render.roadmap._common (lean renderer id, generated header and footer)
- oc_chat.registry.render.roadmap.render_sections (lean file kind and its render-section manifest rows)
- oc_chat.registry.render.roadmap.sections (per-section body rendering and cell escaping)
- oc_chat.registry.render.roadmap.store_read (selected version, current phase and milestone reads)
"""
from __future__ import annotations
 
import re
import sqlite3
from typing import Optional
 
from oc_diagnostics import _dbg
 
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_LEAN,
    build_generated_header,
    generated_footer,
)
from oc_chat.registry.render.roadmap.render_sections import FILE_KIND_LEAN, sections_for
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
_TITLE = "# OC Chat Roadmap"
#: GitHub-slugger semantics: drop everything except word chars / whitespace /
#: hyphen, then map each whitespace char to a hyphen (no collapsing).
_SLUG_DROP_RE = re.compile(r"[^\w\s-]")
_SLUG_WS_RE = re.compile(r"\s")
 
 
def render(
    conn: sqlite3.Connection,
    *,
    source_hash: str,
    logical_state_hash: str,
    published: Optional[str] = None,
) -> str:
    """Render the lean V4 ``ROADMAP.md`` (header + body) as deterministic bytes."""
    func = "render"
    header = build_generated_header(
        source_hash=source_hash,
        logical_state_hash=logical_state_hash,
        renderer=RENDERER_LEAN,
    )
    version = store_read.selected_roadmap_version(conn)
    body = _render_manifest_sections(conn, FILE_KIND_LEAN)
    lines: list[str] = [
        header,
        "",
        _TITLE,
        "",
        _version_line(version, published),
        "",
        "---",
        "",
        *_current_block(conn),
        "",
        "---",
        "",
        *legend_lines(),
    ]
    toc = _toc(body)
    if toc:
        lines.extend(["", *toc])
    lines.extend(["", *body])
    lines.extend(["", *generated_footer("roadmap")])
    _dbg("OC_CHAT.MAIN", func, f"lean rendered version={version}", 2)
    return "\n".join(lines).rstrip() + "\n"
 
 
def _version_line(version: Optional[str], published: Optional[str]) -> str:
    label = version or "—"
    if published:
        return f"**Version:** {label} · **Updated:** {published}"
    return f"**Version:** {label}"
 
 
def _current_block(conn: sqlite3.Connection) -> list[str]:
    code = store_read.current_phase_code(conn)
    if code is None:
        return [store_read.ALL_COMPLETE_LINE]
    milestone = next(
        (row for row in store_read.milestone_rows(conn) if row.phase_code == code), None
    )
    if milestone is None:  # defensive — current_phase_code derives from the same set
        return [store_read.ALL_COMPLETE_LINE]
    done = f"{milestone.done}/{milestone.total}" if milestone.total else "—"
    label = f"{milestone.phase_code} — {section_render.escape(milestone.title)}"
    # Clickable only when a phase-detail section exists to anchor to (the current
    # phase has children -> a rendered '### {code} — {title}' heading); a childless
    # phase has no detail section, so emit plain text rather than a dead link.
    if milestone.total > 0:
        anchor = _slug(f"{milestone.phase_code} — {milestone.title}")
        label = f"[{label}](#{anchor})"
    return [
        f"> ### 📍 We are here now → {label}",
        f"> {done} sub-phases complete · {section_render.escape(milestone.purpose)}",
    ]
 
 
def legend_lines() -> list[str]:
    """The shared §7 legend (state + priority glyph tables)."""
    return [
        "## Legend",
        "",
        "**State:** ✅ complete · 🔄 in progress · ⬜ not started · 🔒 blocked · "
        "↩ deferred/superseded → named successor · 🚫 deferred (no successor)",
        "",
        "**Priority:** 🔴 critical · 🟠 high · 🟡 medium · 🟢 lower · — n/a",
    ]
 
 
def _render_manifest_sections(conn: sqlite3.Connection, file_kind: str) -> list[str]:
    """Render each active manifest section (in order) into body lines."""
    body: list[str] = []
    for row in sections_for(conn, file_kind):
        params = _params(row["query_params_json"])
        rendered = section_render.render_section(
            conn,
            query_kind=str(row["query_kind"]),
            section_path=str(row["section_path"]),
            params=params,
        )
        if not rendered:
            continue
        if body:
            body.append("")
        body.extend(rendered)
    return body
 
 
def _params(value: Optional[str]) -> Optional[dict]:
    if not value:
        return None
    import json
 
    return json.loads(value)
 
 
def _toc(body: list[str]) -> list[str]:
    headings = [line[3:].strip() for line in body if line.startswith("## ")]
    if not headings:
        return []
    toc = ["## Contents", ""]
    toc.extend(f"- [{heading}](#{_slug(heading)})" for heading in headings)
    return toc
 
 
def _slug(text: str) -> str:
    """GitHub-slugger-accurate anchor for a heading (TOC links + the current
    pointer's in-doc link): lowercase, drop punctuation (em-dash / ``+`` / ``&`` /
    backticks…), then each whitespace char -> ``-`` (no run-collapsing, so a
    ``— ``-style separator yields ``--`` exactly as GitHub/VSCode resolve it)."""
    text = _SLUG_DROP_RE.sub("", text.strip().lower())
    return _SLUG_WS_RE.sub("-", text)
 
 
__all__ = ["render", "legend_lines"]