notes.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/registry/render/roadmap/notes.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/seed/test_framing_notes.py"
"""
Source-backed EXTENDED framing-note sections (Plan 142 P3 Part 2, §3.5).
 
Purpose
-------
Render the roadmap-level **framing sections** — Sources Referenced, Reconciliation
notes, Execution Order, Out Of Scope, Git Workflow & Version Convention — from the
``source/notes/<id>.md`` records (``kind: note``, EXTENDED-only, §3.5), mirroring the
changelog-framing pattern: each note's **body is the verbatim legacy section**
(its own ``## `` heading + content), emitted as-is. NOT read from the store (a
note is never a ``roadmap_items_v3`` row); NO prose hard-coded in the renderer.
The lean ``ROADMAP.md`` does not carry these — framing is EXTENDED-only.
 
Responsibilities
----------------
- ``load_note_records(source_dir)`` — scan + load the ``kind: note`` records.
- ``render_note_sections(records)`` — emit each verbatim body in render order.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - render lifecycle
    L3 - per-note counts
    L4 - per-section assembly
 
Contracts
---------
- Deterministic: identical source -> identical bytes; renderer stores no prose.
- Reads no store table (a note is source-only).
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.source.scanner (source tree scan for note records)
- oc_chat.registry.source.canonical (loads each note record into its model and body)
"""
from __future__ import annotations
 
from pathlib import Path
 
from oc_diagnostics import _dbg
 
from oc_chat.registry.source.canonical import load_record
from oc_chat.registry.source.scanner import scan_source_tree
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
#: Render order for the framing notes (legacy reading order). Any note id not
#: listed sorts after these, by id — so a future note still renders (never dropped).
_NOTE_ORDER: tuple[str, ...] = (
    "versioning-policy",
    "sources-referenced",
    "reconciliation-notes",
    "execution-order",
    "out-of-scope",
    "git-workflow",
    # ROADMAP-TODO deferred-decision narrative (rework Phase 2).
    "m11-deferred",
    "active-deferred",
    "post-12-week-backlog",
    "branch-plans-docs-hygiene",
)
 
 
def load_note_records(source_dir: Path) -> list[tuple[object, str]]:
    """Return ``[(Note, body)]`` for every ``source/notes/<id>.md`` record."""
    out: list[tuple[object, str]] = []
    for scanned in scan_source_tree(Path(source_dir)):
        if scanned.kind == "note":
            model, body = load_record(scanned)
            out.append((model, body))
    return out
 
 
def _order_key(model: object) -> tuple[int, str]:
    note_id = str(getattr(model, "id"))
    rank = _NOTE_ORDER.index(note_id) if note_id in _NOTE_ORDER else len(_NOTE_ORDER)
    return (rank, note_id)
 
 
def render_note_sections(records: list[tuple[object, str]]) -> list[str]:
    """Emit each framing note's verbatim body (its own ``## `` heading), in order."""
    func = "render_note_sections"
    ordered = sorted(records, key=lambda pair: _order_key(pair[0]))
    lines: list[str] = []
    for _model, body in ordered:
        text = body.strip()
        if not text:
            continue
        if lines:
            lines.append("")
        lines.extend(text.split("\n"))
    _dbg("OC_CHAT.MAIN", func, f"{len(ordered)} framing-note sections", 2)
    return lines
 
 
__all__ = ["load_note_records", "render_note_sections"]