mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/nbrender/parse.py

@@ -0,0 +1,394 @@
+"""nbformat 4.x JSON to a typed, escape-ready model, plus the shared render helpers.
+
+Notebook JSON is attacker-shaped: a cell may be any type, ``source`` may be a string or a list,
+``outputs`` may be missing, a mimetype value may be a dict or a list of lines.  Nothing here
+raises on a malformed shape — an unrecognized cell or output degrades to an ``unknown`` kind so a
+single bad record never blanks a render.  Every value that reaches HTML must pass through ``esc``;
+that discipline is enforced downstream, but the model keeps raw strings so callers can escape at
+the point of interpolation rather than trusting pre-escaped data.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from dataclasses import dataclass, field
+from typing import Any, NamedTuple
+
+# Mimetype precedence for a multi-format output bundle.  Highest priority first.
+MIMETYPE_PRECEDENCE: tuple[str, ...] = (
+    "application/vnd.jupyter.widget-view+json",
+    "application/vnd.mostlyright.column-profile.v1+json",
+    "application/vnd.mostlyright.source-observation+json",
+    "application/vnd.mostlyright.stage-observation+json",
+    "application/vnd.mostlyright.stage-observation.v1+json",
+    "text/html",
+    "image/svg+xml",
+    "image/png",
+    "application/json",
+    "text/plain",
+)
+
+# Cell tags the viewer renders (B10); all others are ignored.
+KNOWN_TAGS: tuple[str, ...] = ("cached", "slow", "skip", "hide-input")
+
+_ANSI_RE = re.compile(r"\x1b\[(?P<params>[0-9;]*)m")
+_ENTITY_RE = re.compile(r"\[\[(?P<type>[a-z][a-z0-9_-]*):(?P<id>[^\]]+)\]\]")
+# tqdm renders "<pct>%|bar| n/total [elapsed<remaining, rate]".  Match the leading percent and the
+# n/total fraction; either half may be absent on the first frame.
+_TQDM_RE = re.compile(
+    r"(?P<pct>\d{1,3})%\s*\|.*?\|\s*(?P<n>\d+)\s*/\s*(?P<total>\d+)",
+    re.DOTALL,
+)
+
+
+def esc(value: Any) -> str:
+    """HTML-escape any notebook-derived value, quotes included, for attribute-safe output.
+
+    Coerces non-strings so a malformed numeric or ``None`` field cannot inject unescaped text.
+    """
+    if value is None:
+        return ""
+    return html.escape(str(value), quote=True)
+
+
+class StrippedAnsi(NamedTuple):
+    """Result of ``strip_ansi``: the plain text and whether any SGR-bold code appeared."""
+
+    text: str
+    bold: bool
+
+
+def strip_ansi(value: str) -> StrippedAnsi:
+    """Remove ANSI SGR sequences, keeping only whether bold (SGR 1) was ever set.
+
+    Color codes are discarded per D17/D23 — the viewer re-tokenizes itself.  Bold survives as a
+    single flag the caller maps to weight 600; per-span bold is out of scope for the shared helper.
+    """
+    saw_bold = False
+    for match in _ANSI_RE.finditer(value):
+        params = match.group("params")
+        codes = params.split(";") if params else ["0"]
+        if "1" in codes:
+            saw_bold = True
+    return StrippedAnsi(_ANSI_RE.sub("", value), saw_bold)
+
+
+class TqdmProgress(NamedTuple):
+    """A parsed tqdm frame: ``fraction`` in [0, 1], the label, and the raw n/total stat."""
+
+    fraction: float
+    label: str
+    stat: str
+
+
+def detect_tqdm(text: str) -> TqdmProgress | None:
+    """Return a parsed progress frame when ``text`` matches the tqdm pattern, else ``None``.
+
+    Used to route a text/plain or stdout output to D24 instead of a plain stream well.  A carriage
+    return typically overwrites frames; the last frame in the string wins.
+    """
+    last = text.rsplit("\r", 1)[-1].strip()
+    match = _TQDM_RE.search(last)
+    if match is None:
+        return None
+    n = int(match.group("n"))
+    total = int(match.group("total"))
+    fraction = (n / total) if total else 0.0
+    fraction = max(0.0, min(1.0, fraction))
+    label = last[: match.start()].strip(": ")
+    return TqdmProgress(fraction=fraction, label=label, stat=f"{n}/{total}")
+
+
+class EntityRef(NamedTuple):
+    """A ``[[type:id]]`` reference from markdown source (F29)."""
+
+    type: str
+    id: str
+
+
+def split_entity_refs(source: str) -> list[str | EntityRef]:
+    """Split markdown source into plain runs and ``[[type:id]]`` entity refs, in order.
+
+    Plain text arrives as ``str`` segments; refs as ``EntityRef``.  The markdown engine renders
+    the plain runs normally and hands each ref to the F29 chip renderer.
+    """
+    segments: list[str | EntityRef] = []
+    cursor = 0
+    for match in _ENTITY_RE.finditer(source):
+        if match.start() > cursor:
+            segments.append(source[cursor : match.start()])
+        segments.append(EntityRef(match.group("type"), match.group("id").strip()))
+        cursor = match.end()
+    if cursor < len(source):
+        segments.append(source[cursor:])
+    return segments
+
+
+# Heading anchors (A04 outline links resolve to these).  ``heading_text`` reduces a raw ATX
+# heading to plain link text and ``slugify`` turns that into a deterministic ``#fragment``; both
+# the outline rail (chrome.py) and the rendered markdown headings (markdown_body.py) run the SAME
+# two helpers so an outline anchor always resolves to a real ``id`` on the heading it names.
+_HEADING_IMG_RE = re.compile(r"!\[([^\]]*)\]\([^)]*\)")
+_HEADING_LINK_RE = re.compile(r"\[([^\]]*)\]\([^)]*\)")
+
+
+def heading_text(raw: str) -> str:
+    """Reduce a markdown heading to plain link text: unwrap entity refs, links, images, code."""
+    parts = split_entity_refs(raw)
+    text = "".join(p if isinstance(p, str) else p.id for p in parts)
+    text = _HEADING_IMG_RE.sub(r"\1", text)
+    text = _HEADING_LINK_RE.sub(r"\1", text)
+    text = text.replace("`", "")
+    return text.strip()
+
+
+def slugify(text: str) -> str:
+    """Deterministic anchor fragment from heading text (lowercased, non-alnum collapsed)."""
+    s = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return s or "section"
+
+
+def _join_source(value: Any) -> str:
+    """nbformat stores multiline text as a list of lines or a single string; normalize to str."""
+    if isinstance(value, list):
+        return "".join(str(part) for part in value)
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _normalize_bundle(data: Any) -> dict[str, Any]:
+    """Normalize a mimetype bundle: join text-line lists; keep JSON objects and image blobs."""
+    if not isinstance(data, dict):
+        return {}
+    out: dict[str, Any] = {}
+    for mimetype, value in data.items():
+        if not isinstance(mimetype, str):
+            continue
+        if isinstance(value, list) and all(isinstance(part, str) for part in value):
+            out[mimetype] = "".join(value)
+        else:
+            out[mimetype] = value
+    return out
+
+
+@dataclass
+class Output:
+    """One entry from a code cell's ``outputs`` list, normalized across output types.
+
+    ``kind`` collapses the nbformat ``output_type`` and, for streams, the channel name.  Malformed
+    records land as ``kind == 'unknown'`` with whatever fields survived.
+    """
+
+    kind: str  # stream-stdout | stream-stderr | execute_result | display_data | error | unknown
+    text: str = ""  # stream text or joined text/plain, raw (unescaped, ANSI intact)
+    data: dict[str, Any] = field(default_factory=dict)  # normalized mimetype bundle
+    metadata: dict[str, Any] = field(default_factory=dict)
+    execution_count: int | None = None
+    ename: str | None = None
+    evalue: str | None = None
+    traceback: list[str] = field(default_factory=list)
+
+    def primary_mimetype(self) -> str | None:
+        """Highest-precedence mimetype present in the bundle, or the first unknown key, or None."""
+        if not self.data:
+            return None
+        for mimetype in MIMETYPE_PRECEDENCE:
+            if mimetype in self.data:
+                return mimetype
+        # An unrecognized mimetype still resolves deterministically so section-4 routing can send
+        # it to the labeled unsupported well rather than dropping it.
+        return sorted(self.data)[0]
+
+    def text_of(self, mimetype: str) -> str:
+        """Bundle value for ``mimetype`` as a string (already line-joined at parse time)."""
+        value = self.data.get(mimetype, "")
+        return value if isinstance(value, str) else _join_source(value)
+
+
+@dataclass
+class Cell:
+    """A single notebook cell.  ``cell_type`` is one of markdown/code/raw/unknown."""
+
+    cell_type: str
+    cell_id: str = ""
+    source: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+    execution_count: int | None = None
+    outputs: list[Output] = field(default_factory=list)
+
+    @property
+    def tags(self) -> list[str]:
+        """Known B10 tags on this cell, in ``KNOWN_TAGS`` order; unknown tags are dropped."""
+        raw = self.metadata.get("tags")
+        present = set(raw) if isinstance(raw, list) else set()
+        return [tag for tag in KNOWN_TAGS if tag in present]
+
+    @property
+    def research_activity(self) -> str | None:
+        """Return an exact persisted research activity state, never an inferred one."""
+
+        mostlyright = self.metadata.get("mostlyright")
+        activity = mostlyright.get("activity") if isinstance(mostlyright, dict) else None
+        if (
+            not isinstance(activity, dict)
+            or set(activity) != {"schema_version", "state"}
+            or activity.get("schema_version") != "mostlyright.research-cell-activity.v1"
+            or activity.get("state") not in {"writing", "executing"}
+        ):
+            return None
+        state = str(activity["state"])
+        if state == "executing" and self.cell_type != "code":
+            return None
+        if self.cell_type == "code":
+            if self.execution_count is not None:
+                return None
+            if state == "writing" and self.outputs:
+                return None
+        elif self.cell_type != "markdown" or state != "writing":
+            return None
+        return state
+
+
+@dataclass
+class Notebook:
+    """A parsed notebook: format version, notebook-level metadata, and cells."""
+
+    nbformat: int = 4
+    nbformat_minor: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+    cells: list[Cell] = field(default_factory=list)
+
+    @property
+    def _mostlyright(self) -> dict[str, Any]:
+        block = self.metadata.get("mostlyright")
+        return block if isinstance(block, dict) else {}
+
+    @property
+    def provenance(self) -> dict[str, Any] | None:
+        """``metadata.mostlyright.provenance`` for F27, or None when absent."""
+        block = self._mostlyright.get("provenance")
+        return block if isinstance(block, dict) else None
+
+    @property
+    def leakage(self) -> list[dict[str, Any]]:
+        """``metadata.mostlyright.leakage[]`` entries for F28; empty when absent."""
+        block = self._mostlyright.get("leakage")
+        if not isinstance(block, list):
+            return []
+        return [entry for entry in block if isinstance(entry, dict)]
+
+
+def _parse_output(raw: Any) -> Output:
+    if not isinstance(raw, dict):
+        return Output(kind="unknown")
+    output_type = raw.get("output_type")
+    if output_type == "stream":
+        name = raw.get("name", "stdout")
+        kind = "stream-stderr" if name == "stderr" else "stream-stdout"
+        return Output(kind=kind, text=_join_source(raw.get("text")))
+    if output_type in ("execute_result", "display_data"):
+        return Output(
+            kind=output_type,
+            data=_normalize_bundle(raw.get("data")),
+            metadata=raw.get("metadata") if isinstance(raw.get("metadata"), dict) else {},
+            execution_count=_coerce_int(raw.get("execution_count")),
+        )
+    if output_type == "error":
+        tb = raw.get("traceback")
+        return Output(
+            kind="error",
+            ename=str(raw["ename"]) if "ename" in raw else None,
+            evalue=str(raw["evalue"]) if "evalue" in raw else None,
+            traceback=[str(line) for line in tb] if isinstance(tb, list) else [],
+        )
+    return Output(kind="unknown")
+
+
+def _coerce_int(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    return None
+
+
+def _parse_cell(raw: Any) -> Cell:
+    if not isinstance(raw, dict):
+        return Cell(cell_type="unknown")
+    cell_type = raw.get("cell_type")
+    metadata = raw.get("metadata") if isinstance(raw.get("metadata"), dict) else {}
+    cell_id = str(raw.get("id", ""))
+    source = _join_source(raw.get("source"))
+    if cell_type == "code":
+        outputs_raw = raw.get("outputs")
+        outputs = [_parse_output(o) for o in outputs_raw] if isinstance(outputs_raw, list) else []
+        return Cell(
+            cell_type="code",
+            cell_id=cell_id,
+            source=source,
+            metadata=metadata,
+            execution_count=_coerce_int(raw.get("execution_count")),
+            outputs=outputs,
+        )
+    if cell_type in ("markdown", "raw"):
+        return Cell(cell_type=cell_type, cell_id=cell_id, source=source, metadata=metadata)
+    return Cell(cell_type="unknown", cell_id=cell_id, source=source, metadata=metadata)
+
+
+def coalesce_stream_outputs(outputs: list[Output]) -> list[Output]:
+    """Merge consecutive same-channel stream outputs into one (D16, and D17 by symmetry).
+
+    A kernel emits one ``stream`` record per ``print`` / ``write`` flush, so a single logical block
+    of stdout (or stderr) arrives as a run of adjacent :class:`Output` records.  Consecutive stdout
+    renders as one well, so this concatenates the text of each same-channel run into a
+    single ``Output`` while leaving every non-stream record (results, errors, rich data) untouched
+    and in order.  A fresh ``Output`` is built for each merged run so the parsed model's records are
+    never mutated in place.
+    """
+    merged: list[Output] = []
+    for out in outputs:
+        if (
+            out.kind in ("stream-stdout", "stream-stderr")
+            and merged
+            and merged[-1].kind == out.kind
+        ):
+            prev = merged[-1]
+            merged[-1] = Output(kind=prev.kind, text=prev.text + out.text)
+        else:
+            merged.append(out)
+    return merged
+
+
+def parse_notebook(nb: dict[str, Any]) -> Notebook:
+    """Build a :class:`Notebook` from raw nbformat JSON, tolerating any malformed shape.
+
+    A non-dict document, a non-list ``cells``, or a broken cell/output never raises: the offending
+    record becomes an ``unknown`` cell or output so the render always completes.
+    """
+    if not isinstance(nb, dict):
+        return Notebook()
+    cells_raw = nb.get("cells")
+    cells = [_parse_cell(c) for c in cells_raw] if isinstance(cells_raw, list) else []
+    metadata = nb.get("metadata") if isinstance(nb.get("metadata"), dict) else {}
+    return Notebook(
+        nbformat=_coerce_int(nb.get("nbformat")) or 4,
+        nbformat_minor=_coerce_int(nb.get("nbformat_minor")) or 0,
+        metadata=metadata,
+        cells=cells,
+    )
+
+
+@dataclass
+class RenderContext:
+    """Per-cell render state threaded to every component.
+
+    ``prev_execution_count`` is the execution count of the previous code cell, used by B11 to flag
+    out-of-order runs; it is None before the first executed cell.
+    """
+
+    mode: str = "static"
+    cell_index: int = 0
+    cell_count: int = 0
+    prev_execution_count: int | None = None

mostlyright/data_harness/nbrender/status.py

@@ -0,0 +1,40 @@
+"""Canonical presentation for exact status values in technical tables.
+
+The notebook remains authoritative. This module only normalizes the visible label and tone when a
+recognized status word appears in a semantic status/decision column.
+"""
+
+from __future__ import annotations
+
+STATUS_COLUMNS = frozenset({"status", "decision"})
+
+_STATUS_LABELS = {
+    "pass": ("pass", "Pass"),
+    "passed": ("pass", "Pass"),
+    "fail": ("fail", "Fail"),
+    "failed": ("fail", "Fail"),
+    "pending": ("pending", "Pending"),
+    "running": ("running", "Running"),
+    "warn": ("warning", "Warning"),
+    "warning": ("warning", "Warning"),
+    "skip": ("neutral", "Skipped"),
+    "skipped": ("neutral", "Skipped"),
+    "unavailable": ("neutral", "Unavailable"),
+    "verified": ("pass", "Verified"),
+    "complete": ("pass", "Complete"),
+    "completed": ("pass", "Complete"),
+}
+
+
+def is_status_column(label: str) -> bool:
+    """Return whether a table header declares a semantic status column."""
+    return label.strip().casefold() in STATUS_COLUMNS
+
+
+def render_status(value: str) -> str | None:
+    """Return fixed safe markup for a recognized exact status value."""
+    status = _STATUS_LABELS.get(value.strip().casefold())
+    if status is None:
+        return None
+    tone, label = status
+    return f'<span class="nb-status nb-status--{tone}">{label}</span>'