backdraft 0.2.0__py3-none-any.whl

backdraft/render/markdown.py

@@ -0,0 +1,313 @@
+"""A small markdown subset, rendered to HTML with stdlib only.
+
+The artifact must be one file with no dependency at read time and none at build
+time either, so the document body goes through this renderer rather than a
+markdown library. The subset is exactly what an authored memo uses: headings,
+paragraphs, lists, tables, blockquotes, fenced code, thematic breaks, and the
+inline forms bold / italic / code / link.
+
+Claims are not parsed here. `to_html` takes the source ranges bind already
+located and splices caller-supplied HTML into them, so the claim spans in the
+artifact are the spans the report recorded — never a second, disagreeing parse.
+
+NOTE (deliberate omissions, the spec is silent on all of them): reference links,
+setext headings, HTML passthrough, footnote syntax, and autolinks are not
+recognized and render as literal text. Images render as their alt text: an
+`<img>` would be an external request, which the artifact does not make.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+__all__ = ["Span", "to_html", "inline"]
+
+_SPLICE = "\x00s{index}\x00"
+_ESCAPED = "\x01e{index}\x01"
+
+_HEADING_RE = re.compile(r"(?P<level>#{1,6})\s+(?P<text>.*?)\s*#*\s*$")
+_RULE_RE = re.compile(r"(?:\*\s*){3,}|(?:-\s*){3,}|(?:_\s*){3,}")
+_FENCE_RE = re.compile(r"(?P<indent>\s*)(?P<fence>```+|~~~+)(?P<info>.*)$")
+_BULLET_RE = re.compile(r"(?P<indent>[ \t]*)(?P<marker>[-*+])[ \t]+(?P<text>.*)$")
+_ORDERED_RE = re.compile(r"(?P<indent>[ \t]*)(?P<marker>\d{1,9})[.)][ \t]+(?P<text>.*)$")
+_QUOTE_RE = re.compile(r"[ \t]*>[ \t]?(?P<text>.*)$")
+_ALIGN_RE = re.compile(r":?-{1,}:?")
+_BACKSLASH_RE = re.compile(r"\\([\\`*_{}\[\]()#+\-.!|>~])")
+_SAFE_HREF_RE = re.compile(r"\s*javascript\s*:", re.IGNORECASE)
+
+_INLINE_RE = re.compile(
+    r"""
+      (?P<fence>`+)(?P<code>.+?)(?P=fence)
+    | !\[(?P<alt>[^\]]*)\]\([^)]*\)
+    | \[(?P<label>(?:[^\[\]]|\[[^\]]*\])*)\]\((?P<href>[^)\s]*)(?:\s+"[^"]*")?\)
+    | (?P<strong_mark>\*\*|__)(?P<strong>.+?)(?P=strong_mark)
+    | (?P<em_mark>[*_])(?P<em>.+?)(?P=em_mark)
+    """,
+    re.VERBOSE | re.DOTALL,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Span:
+    """A source range whose rendered form the caller supplies.
+
+    `start`/`end` are character offsets into the source; `html` replaces that
+    range verbatim and is never escaped or re-parsed.
+    """
+
+    start: int
+    end: int
+    html: str
+
+
+def to_html(source: str, spans: Sequence[Span] = ()) -> str:
+    """Render `source` as HTML, splicing each span's HTML into its source range.
+
+    Spans must not overlap; they are applied in source order.
+    """
+    masked, splices = _mask_spans(source, spans)
+    rendered = _blocks(masked.expandtabs(4).splitlines())
+    for index, markup in enumerate(splices):
+        rendered = rendered.replace(_SPLICE.format(index=index), markup)
+    return rendered
+
+
+def inline(text: str) -> str:
+    """Render one run of inline markdown — the form used inside a claim's text."""
+    escapes: list[str] = []
+
+    def stash(match: re.Match[str]) -> str:
+        escapes.append(html.escape(match.group(1), quote=False))
+        return _ESCAPED.format(index=len(escapes) - 1)
+
+    rendered = _inline(_BACKSLASH_RE.sub(stash, text))
+    for index, literal in enumerate(escapes):
+        rendered = rendered.replace(_ESCAPED.format(index=index), literal)
+    return rendered
+
+
+def _mask_spans(source: str, spans: Sequence[Span]) -> tuple[str, list[str]]:
+    """Replace each span's source range with a splice marker."""
+    ordered = sorted(spans, key=lambda span: span.start)
+    pieces: list[str] = []
+    splices: list[str] = []
+    cursor = 0
+    for span in ordered:
+        if span.start < cursor:
+            raise ValueError(f"overlapping span at {span.start}")
+        pieces.append(source[cursor : span.start])
+        pieces.append(_SPLICE.format(index=len(splices)))
+        splices.append(span.html)
+        cursor = span.end
+    pieces.append(source[cursor:])
+    return "".join(pieces), splices
+
+
+def _blocks(lines: Sequence[str]) -> str:
+    """Render a sequence of lines as block-level HTML."""
+    out: list[str] = []
+    index = 0
+    total = len(lines)
+    while index < total:
+        line = lines[index]
+        if not line.strip():
+            index += 1
+            continue
+        if fence := _FENCE_RE.fullmatch(line):
+            index = _code_block(lines, index, fence, out)
+            continue
+        if heading := _HEADING_RE.fullmatch(line.strip()):
+            level = len(heading["level"])
+            out.append(f"<h{level}>{inline(heading['text'])}</h{level}>")
+            index += 1
+            continue
+        if _RULE_RE.fullmatch(line.strip()):
+            out.append("<hr>")
+            index += 1
+            continue
+        if _QUOTE_RE.fullmatch(line):
+            index = _quote_block(lines, index, out)
+            continue
+        if _BULLET_RE.fullmatch(line) or _ORDERED_RE.fullmatch(line):
+            index = _list_block(lines, index, out)
+            continue
+        if index + 1 < total and _is_table_rule(lines[index + 1]) and "|" in line:
+            index = _table_block(lines, index, out)
+            continue
+        index = _paragraph(lines, index, out)
+    return "\n".join(out)
+
+
+def _code_block(lines: Sequence[str], index: int, fence: re.Match[str], out: list[str]) -> int:
+    """Consume a fenced code block. Its content is never inline-rendered."""
+    marker = fence["fence"]
+    body: list[str] = []
+    index += 1
+    while index < len(lines) and lines[index].strip() != marker:
+        body.append(lines[index])
+        index += 1
+    escaped = html.escape("\n".join(body), quote=False)
+    out.append(f"<pre><code>{escaped}</code></pre>")
+    return index + 1 if index < len(lines) else index
+
+
+def _quote_block(lines: Sequence[str], index: int, out: list[str]) -> int:
+    body: list[str] = []
+    while index < len(lines) and (match := _QUOTE_RE.fullmatch(lines[index])):
+        body.append(match["text"])
+        index += 1
+    out.append(f"<blockquote>{_blocks(body)}</blockquote>")
+    return index
+
+
+def _list_block(lines: Sequence[str], index: int, out: list[str]) -> int:
+    """Consume one list, including indented continuation lines and sublists."""
+    ordered = _ORDERED_RE.fullmatch(lines[index]) is not None
+    items: list[list[str]] = []
+    loose = False
+    pending_blank = False
+    while index < len(lines):
+        line = lines[index]
+        item = _ORDERED_RE.fullmatch(line) if ordered else _BULLET_RE.fullmatch(line)
+        if item is not None and len(item["indent"]) < 2:
+            items.append([item["text"]])
+            loose = loose or (pending_blank and len(items) > 1)
+            pending_blank = False
+            index += 1
+            continue
+        if not line.strip():
+            if not items:
+                break
+            pending_blank = True
+            index += 1
+            continue
+        if items and line.startswith("  "):
+            if pending_blank:
+                items[-1].append("")
+                loose = True
+                pending_blank = False
+            items[-1].append(line[2:])
+            index += 1
+            continue
+        break
+    rendered = [f"<li>{_item(body, loose)}</li>" for body in items]
+    tag = "ol" if ordered else "ul"
+    out.append(f"<{tag}>{''.join(rendered)}</{tag}>")
+    return index
+
+
+def _item(body: Sequence[str], loose: bool) -> str:
+    """One list item: bare inline when it is a single simple line, blocks otherwise."""
+    if not loose and len(body) == 1:
+        return inline(body[0])
+    return _blocks(body)
+
+
+def _table_block(lines: Sequence[str], index: int, out: list[str]) -> int:
+    header = _row(lines[index])
+    alignments = [_alignment(cell) for cell in _row(lines[index + 1])]
+    index += 2
+    rows: list[list[str]] = []
+    while index < len(lines) and "|" in lines[index] and lines[index].strip():
+        rows.append(_row(lines[index]))
+        index += 1
+    head = "".join(
+        f"<th{_align_attr(alignments, column)}>{inline(cell)}</th>"
+        for column, cell in enumerate(header)
+    )
+    body = "".join(
+        "<tr>"
+        + "".join(
+            f"<td{_align_attr(alignments, column)}>{inline(cell)}</td>"
+            for column, cell in enumerate(row)
+        )
+        + "</tr>"
+        for row in rows
+    )
+    out.append(
+        '<div class="table-wrap"><table>'
+        f"<thead><tr>{head}</tr></thead><tbody>{body}</tbody>"
+        "</table></div>"
+    )
+    return index
+
+
+def _paragraph(lines: Sequence[str], index: int, out: list[str]) -> int:
+    body: list[str] = []
+    while index < len(lines) and lines[index].strip():
+        line = lines[index]
+        if body and (
+            _HEADING_RE.fullmatch(line.strip())
+            or _FENCE_RE.fullmatch(line)
+            or _QUOTE_RE.fullmatch(line)
+            or _BULLET_RE.fullmatch(line)
+            or _ORDERED_RE.fullmatch(line)
+        ):
+            break
+        body.append(line.strip())
+        index += 1
+    out.append(f"<p>{inline(' '.join(body))}</p>")
+    return index
+
+
+def _is_table_rule(line: str) -> bool:
+    stripped = line.strip()
+    if "-" not in stripped or not stripped:
+        return False
+    cells = _row(line)
+    return bool(cells) and all(_ALIGN_RE.fullmatch(cell) for cell in cells)
+
+
+def _row(line: str) -> list[str]:
+    stripped = line.strip()
+    if stripped.startswith("|"):
+        stripped = stripped[1:]
+    if stripped.endswith("|"):
+        stripped = stripped[:-1]
+    return [cell.strip() for cell in stripped.split("|")]
+
+
+def _alignment(cell: str) -> str:
+    left, right = cell.startswith(":"), cell.endswith(":")
+    if left and right:
+        return "center"
+    if right:
+        return "right"
+    return "left"
+
+
+def _align_attr(alignments: Sequence[str], column: int) -> str:
+    align = alignments[column] if column < len(alignments) else "left"
+    return "" if align == "left" else f' class="t-{align}"'
+
+
+def _inline(text: str) -> str:
+    """Inline rendering over text whose backslash escapes are already stashed."""
+    out: list[str] = []
+    cursor = 0
+    for match in _INLINE_RE.finditer(text):
+        out.append(html.escape(text[cursor : match.start()], quote=False))
+        out.append(_inline_match(match))
+        cursor = match.end()
+    out.append(html.escape(text[cursor:], quote=False))
+    return "".join(out)
+
+
+def _inline_match(match: re.Match[str]) -> str:
+    if (code := match["code"]) is not None:
+        return f"<code>{html.escape(code.strip(), quote=False)}</code>"
+    if (alt := match["alt"]) is not None:
+        # NOTE: images are not embedded in v0 (no page images, no external
+        # requests), so an image renders as its alt text, marked as such.
+        return f'<span class="bd-image" title="image omitted">{_inline(alt)}</span>'
+    if (label := match["label"]) is not None:
+        href = match["href"] or ""
+        if _SAFE_HREF_RE.match(href):
+            return _inline(label)
+        return f'<a href="{html.escape(href, quote=True)}">{_inline(label)}</a>'
+    if (strong := match["strong"]) is not None:
+        return f"<strong>{_inline(strong)}</strong>"
+    return f"<em>{_inline(match['em'])}</em>"

backdraft/render/placement.py

@@ -0,0 +1,105 @@
+"""Finding each claim's span in the document render receives.
+
+Render's only inputs are an authored document and a sidecar; the registry may be
+gone. A claim carries `start`/`end` into the document bind read, which is usually
+the document render is handed — but bind also rewrites citations into readable
+form, so the file on disk may be the rewritten one and the offsets may have
+moved. Rather than guess, we try three locators in order and record which claims
+could not be placed at all; an unplaced claim still appears in the artifact, in
+its own section, because nothing drops silently.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from ..kernel.model import Claim
+
+__all__ = ["Placement", "locate"]
+
+
+@dataclass(frozen=True, slots=True)
+class Placement:
+    """One claim and where it sits in the document being rendered.
+
+    `number` is the claim's 1-based position in document order — the number the
+    artifact labels it with. `start`/`end` are None when the claim's text could
+    not be found in the document at all.
+    """
+
+    number: int
+    claim: Claim
+    start: int | None = None
+    end: int | None = None
+
+    @property
+    def placed(self) -> bool:
+        """True when this claim has a span in the document body."""
+        return self.start is not None and self.end is not None
+
+
+def locate(source: str, claims: Sequence[Claim]) -> list[Placement]:
+    """Place every claim in `source`, in document order.
+
+    Three locators, in order of confidence:
+
+    1. the recorded offsets, when the construct they bound is still there;
+    2. the first `[claim text](` link at or after the previous claim — the shape
+       bind leaves behind when it rewrites tokens into readable citations;
+    3. the first bare occurrence of the claim's text, for a document whose
+       citations were projected away entirely.
+
+    A claim that matches none of the three is returned unplaced.
+    """
+    placements: list[Placement] = []
+    cursor = 0
+    for number, claim in enumerate(claims, start=1):
+        span = _at_offsets(source, claim) or _as_link(source, claim, cursor)
+        if span is None:
+            span = _as_text(source, claim, cursor)
+        if span is None:
+            placements.append(Placement(number=number, claim=claim))
+            continue
+        start, end = span
+        placements.append(Placement(number=number, claim=claim, start=start, end=end))
+        cursor = end
+    return placements
+
+
+def _at_offsets(source: str, claim: Claim) -> tuple[int, int] | None:
+    """The recorded span, if the document still holds the construct bind saw."""
+    if not 0 <= claim.start < claim.end <= len(source):
+        return None
+    construct = source[claim.start : claim.end]
+    if construct == claim.text:
+        return (claim.start, claim.end)
+    if construct.startswith(f"[{claim.text}](") and construct.endswith(")"):
+        return (claim.start, claim.end)
+    return None
+
+
+def _as_link(source: str, claim: Claim, cursor: int) -> tuple[int, int] | None:
+    """The first `[claim text](...)` link at or after `cursor`.
+
+    NOTE: the closing parenthesis is the first one after the opener. Tokens
+    cannot contain parentheses, and the readable citations bind writes are
+    fragment references, so this is exact for every href render can meet.
+    """
+    start = source.find(f"[{claim.text}](", cursor)
+    if start < 0:
+        return None
+    close = source.find(")", start + len(claim.text) + 3)
+    if close < 0:
+        return None
+    return (start, close + 1)
+
+
+def _as_text(source: str, claim: Claim, cursor: int) -> tuple[int, int] | None:
+    """The first bare occurrence of the claim's text at or after `cursor`."""
+    if not claim.text:
+        return None
+    start = source.find(claim.text, cursor)
+    if start < 0:
+        return None
+    return (start, start + len(claim.text))

backdraft/render/sidecar.py

@@ -0,0 +1,164 @@
+"""The sidecar: one bind run, written as a standalone self-describing JSON file.
+
+The sidecar is the machine-readable half of the artifact. It is exactly a
+`BindReport` payload with two reserved keys in front of it:
+
+* ``$format`` — ``backdraft/artifact-v1``, matched exactly (never parsed, never
+  range-checked); and
+* ``$legend`` — prose that teaches a reader who has never seen backdraft how to
+  decode the rest of the object.
+
+The HTML artifact embeds this same payload, byte for byte, in its JSON island:
+``render --to json`` and the island of ``render --to html`` are the same bytes,
+so a reader can treat either as the record.
+
+The format itself — `FORMAT`, `LEGEND`, `SIDECAR_SUFFIX`, `sidecar_path`, and the
+`sidecar` / `dumps` writers — lives in `kernel/artifact.py`, because bind writes
+it and render reads it and neither owns it; the file's *name* is part of the
+format for the same reason. This module is the render-side door onto it: it
+re-exports those names and adds the reader that turns a sidecar file back into a
+`BindReport`. `spec/artifact.md` is the prose specification; where it and the
+kernel's legend disagree, the spec file decides.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..kernel.artifact import (  # noqa: F401  (re-exported: the format is kernel-owned)
+    FORMAT,
+    LEGEND,
+    SIDECAR_SUFFIX,
+    dumps,
+    record_path,
+    sidecar,
+    sidecar_path,
+)
+from ..kernel.model import (
+    Anchor,
+    BindReport,
+    Citation,
+    CitationStatus,
+    Claim,
+    Receipt,
+    Verdict,
+    VerdictStatus,
+)
+from ..kernel.tokens import parse_locator
+
+__all__ = [
+    "FORMAT",
+    "LEGEND",
+    "SIDECAR_SUFFIX",
+    "sidecar",
+    "dumps",
+    "write",
+    "read",
+    "to_report",
+    "sidecar_path",
+    "find_sidecar",
+]
+
+
+def write(report: BindReport, path: Path) -> Path:
+    """Write the sidecar to `path`. Returns the path written."""
+    path.write_text(dumps(report), encoding="utf-8")
+    return path
+
+
+def read(path: Path) -> BindReport:
+    """Read a sidecar file back into a `BindReport`.
+
+    Raises `ValueError` if the file is not a payload of this exact format.
+    """
+    return to_report(json.loads(path.read_text(encoding="utf-8")))
+
+
+def to_report(payload: dict[str, Any]) -> BindReport:
+    """Rebuild the `BindReport` a sidecar payload carries.
+
+    `$format` is matched exactly; a payload carrying anything else is refused
+    rather than interpreted. Round-trip is stable at the payload level:
+    `sidecar(to_report(payload)) == payload` for any payload this accepts.
+
+    NOTE: `Anchor.extraction_id`, `start` and `end` are registry-side fields the
+    sidecar deliberately does not carry, so they come back `None`; `page_number`
+    is recovered from the locator when the locator has one.
+    """
+    if not isinstance(payload, dict):
+        raise ValueError(f"sidecar payload must be an object, not {type(payload).__name__}")
+    found = payload.get("$format")
+    if found != FORMAT:
+        raise ValueError(f"unknown artifact format {found!r}; this reader speaks {FORMAT!r}")
+    return BindReport(
+        doc_path=payload["doc_path"],
+        mode=payload["mode"],
+        bound_at=payload["bound_at"],
+        session_id=payload.get("session_id"),
+        claims=tuple(_claim(entry) for entry in payload.get("claims", ())),
+        evidence=payload.get("evidence"),
+    )
+
+
+def find_sidecar(doc_path: Path) -> Path | None:
+    """The document's record, or None.
+
+    Looked for in order: beside the document (`<stem>.backdraft.json` — the
+    portable form a reader is handed), the whole-filename variant a person
+    types (`memo.md.backdraft.json`), then the project's records store —
+    `.backdraft/records/` under the nearest ancestor holding a `.backdraft`
+    directory, which is where a rooted bind writes.
+    """
+    for candidate in (sidecar_path(doc_path), doc_path.with_name(doc_path.name + SIDECAR_SUFFIX)):
+        if candidate.is_file():
+            return candidate
+    resolved = doc_path.resolve()
+    for ancestor in resolved.parents:
+        if (ancestor / ".backdraft").is_dir():
+            candidate = record_path(ancestor, resolved)
+            return candidate if candidate.is_file() else None
+    return None
+
+
+def _claim(entry: dict[str, Any]) -> Claim:
+    return Claim(
+        text=entry["text"],
+        start=entry["start"],
+        end=entry["end"],
+        unmatched=bool(entry.get("unmatched", False)),
+        citations=tuple(_citation(item) for item in entry.get("citations", ())),
+    )
+
+
+def _citation(entry: dict[str, Any]) -> Citation:
+    token = entry["token"]
+    anchor = entry.get("anchor")
+    return Citation(
+        token=token,
+        status=CitationStatus(entry["status"]),
+        anchor=_anchor(anchor, token) if anchor is not None else None,
+        drifted_from=entry.get("drifted_from"),
+        error=entry.get("error"),
+        verdicts=tuple(_verdict(item) for item in entry.get("verdicts", ())),
+    )
+
+
+def _anchor(entry: dict[str, Any], token: str) -> Anchor:
+    locator = parse_locator(entry["locator"])
+    return Anchor(
+        slug=entry["slug"],
+        locator=locator,
+        receipt=Receipt(snippet=entry["snippet"], snippet_sha256=entry["snippet_sha256"]),
+        token=token,
+        page_number=getattr(locator, "page", None),
+    )
+
+
+def _verdict(entry: dict[str, Any]) -> Verdict:
+    return Verdict(
+        method=entry["method"],
+        status=VerdictStatus(entry["status"]),
+        detail=entry.get("detail", ""),
+    )