59 lines
2 KiB
Python
59 lines
2 KiB
Python
|
"""Read-only rendering of `specs/policies/`/`specs/profiles/` markdown
|
||
|
|
files for the Control Plane (WP-0015-T03).
|
||
|
|
|
||
|
|
Server-side markdown -> HTML at request time, deliberately not a static
|
||
|
|
build pipeline (unlike state-hub's Observable Framework Reference
|
||
|
|
section, confirmed materially heavier during WP-0012-T03) -- this repo's
|
||
|
|
existing lightweight FastAPI+Jinja2 stack needs nothing more than a
|
||
|
|
small markdown library for six profile pages and one policy page.
|
||
|
|
"""
|
||
|
|
|
||
|
|
from __future__ import annotations
|
||
|
|
|
||
|
|
from pathlib import Path
|
||
|
|
from typing import Any
|
||
|
|
|
||
|
|
import markdown
|
||
|
|
import yaml
|
||
|
|
|
||
|
|
_SPECS_DIR = Path(__file__).resolve().parents[3] / "specs"
|
||
|
|
|
||
|
|
# kind -> subdirectory name under specs/. Only these two exist today
|
||
|
|
# (WP-0015-T02); a third kind (e.g. "calculators") can be added here if
|
||
|
|
# a future workplan gives calculators their own reference route.
|
||
|
|
REFERENCE_KINDS = frozenset({"policies", "profiles"})
|
||
|
|
|
||
|
|
|
||
|
|
def load_reference_doc(kind: str, slug: str) -> tuple[str, dict[str, Any]] | None:
|
||
|
|
"""Return (rendered_html, frontmatter) for one spec file, or None if
|
||
|
|
`kind` is unknown or no matching file exists. Read-only: there is no
|
||
|
|
corresponding write path anywhere in this module."""
|
||
|
|
if kind not in REFERENCE_KINDS:
|
||
|
|
return None
|
||
|
|
path = _SPECS_DIR / kind / f"{slug}.md"
|
||
|
|
if not path.is_file():
|
||
|
|
return None
|
||
|
|
|
||
|
|
raw = path.read_text(encoding="utf-8")
|
||
|
|
frontmatter: dict[str, Any] = {}
|
||
|
|
if raw.startswith("---\n"):
|
||
|
|
end = raw.find("\n---\n", 4)
|
||
|
|
if end != -1:
|
||
|
|
frontmatter = yaml.safe_load(raw[4:end]) or {}
|
||
|
|
raw = raw[end + 5 :]
|
||
|
|
|
||
|
|
html = markdown.markdown(raw)
|
||
|
|
return html, frontmatter
|
||
|
|
|
||
|
|
|
||
|
|
def policy_slug_from_id(policy_id: str) -> str:
|
||
|
|
"""`trsl:policy:linear-longstop-v0@1.0` -> `linear-longstop-v0`."""
|
||
|
|
name = policy_id.split(":")[-1]
|
||
|
|
return name.split("@")[0]
|
||
|
|
|
||
|
|
|
||
|
|
def extension_slug_from_id(extension_id: str) -> str:
|
||
|
|
"""`trsl:extension:development-license@1.0` -> `development-license`."""
|
||
|
|
name = extension_id.split(":")[-1]
|
||
|
|
return name.split("@")[0]
|