# ============================================================
# src/accountable_record/stage_090_docs/base/scalars.py
# ============================================================
"""Scalar/path helpers for stage 090 documentation.

WHY:
    Mirrors the scalar helper layer of earlier stages: small, dependency-free
    functions used by plan/render code. Stage 090 consumes the already-validated
    generated registry from pipeline state rather than parsing raw JSON, so its
    helpers derive page paths and stems rather than checking JSON shape.

OBS (narrow by design):
    Pure derivation. No filesystem walking, no diagnostics, no state mutation,
    no file writes. The caller turns a duplicate or empty result into a precise
    AR.DC.* diagnostic.
"""

from accountable_record.stage_090_docs.base.constants import (
    DOCS_DIRNAME,
    DOCS_ELEMENTS_SUBDIR,
    DOCS_LANG_SUBDIR,
    DOCS_PAGE_SUFFIX,
)


def page_stem_for(compact_id: str) -> str:
    """Return the page stem for an element compact_id.

    The stem is the element's local name, taken as the final dotted segment of
    the compact_id. A compact_id with no separator yields itself.
    """
    return compact_id.rsplit(".", 1)[-1]


def page_rel_path_for(compact_id: str) -> str:
    """Return the repository-relative Markdown page path for an element.

    The path is docs/<lang>/elements/<stem>.md.
    """
    stem = page_stem_for(compact_id)
    return (
        f"{DOCS_DIRNAME}/{DOCS_LANG_SUBDIR}/{DOCS_ELEMENTS_SUBDIR}/"
        f"{stem}{DOCS_PAGE_SUFFIX}"
    )
