backdraft 0.2.0__py3-none-any.whl

backdraft/render/__init__.py

@@ -0,0 +1,31 @@
+"""render — the artifact and its projections.
+
+Three renderings of one bind run, from an authored document plus its sidecar and
+nothing else (the registry is never opened here):
+
+* `html` — the single-file artifact: the document, a receipt behind every claim,
+  a visible Unresolved section, and a JSON island that teaches its own decoding.
+* `footnotes` — the plain-markdown projection.
+* `sidecar` — the machine-readable record alone, `backdraft/artifact-v1`.
+
+Export style (shared by every package above the kernel): **names**, never
+submodules. The three renderers each spell their entry point `render`, so they
+are reached by module path — `from backdraft.render import html`, then
+`html.render(...)` — which also means importing this package does not drag all
+three in. `render.cli` is not imported here either: it needs typer; the library
+does not.
+"""
+
+from __future__ import annotations
+
+from .placement import Placement, locate
+from .sidecar import FORMAT, LEGEND, SIDECAR_SUFFIX, sidecar_path
+
+__all__ = [
+    "Placement",
+    "locate",
+    "FORMAT",
+    "LEGEND",
+    "SIDECAR_SUFFIX",
+    "sidecar_path",
+]

backdraft/render/_text.py

@@ -0,0 +1,69 @@
+"""Presentation helpers the renderers share: status prose, elision, quoting.
+
+Both renderers project the same report, so both have to say the same things about
+it. When the artifact and the markdown projection each carried their own copy of
+these, they drifted — the same `not_shown` citation was "a valid anchor the
+writer was never shown" in one and "A valid anchor, but the writer was never
+shown it." in the other, which is two answers to one question.
+
+The wording here is checked against `kernel/artifact.py`'s `LEGEND`
+("citation_status"), which is the normative statement of what each status means;
+these are its one-line renderings, not a second definition.
+
+Private to `render/`: the dependency rule forbids sideways imports, so bind keeps
+its own quoting even where the code looks alike.
+"""
+
+from __future__ import annotations
+
+from ..kernel.model import CitationStatus
+
+__all__ = ["STATUS_NOTE", "quote_lines", "sentence", "short", "status_note"]
+
+STATUS_NOTE: dict[CitationStatus, str] = {
+    CitationStatus.DRIFTED: "the source changed after this claim was written",
+    CitationStatus.NOT_SHOWN: "a valid anchor, but the writer was never shown it",
+    CitationStatus.UNRESOLVED: "no anchor for this token in any generation",
+    CitationStatus.MALFORMED: "the citation text is not a token",
+}
+"""Why a citation did not resolve, as a lowercase fragment.
+
+`resolved` is deliberately absent: a resolved citation needs no explanation, and
+`status_note` returning "" is what the callers test for.
+"""
+
+
+def status_note(status: CitationStatus) -> str:
+    """The one-line reason for a status, or "" when there is nothing to say."""
+    return STATUS_NOTE.get(status, "")
+
+
+def sentence(text: str) -> str:
+    """A fragment as a standalone sentence: capitalized, terminally punctuated.
+
+    The markdown projection puts these after a colon, where a fragment reads
+    correctly; the artifact shows them on their own, where it does not.
+    """
+    if not text:
+        return ""
+    return text[0].upper() + text[1:] + ("" if text.endswith((".", "!", "?")) else ".")
+
+
+def short(text: str, *, limit: int) -> str:
+    """A claim's text, collapsed to one line and elided at `limit` characters.
+
+    `limit` is the caller's, because the two renderers have different room: an
+    artifact's failure list is a styled block, a markdown list item is a line.
+    """
+    flat = " ".join(text.split())
+    return flat if len(flat) <= limit else flat[: limit - 1].rstrip() + "…"
+
+
+def quote_lines(snippet: str) -> list[str]:
+    """A verbatim snippet as markdown blockquote lines, line for line.
+
+    NOTE: `bind.binder` has its own, on purpose — `bind` may not import `render`,
+    and its References section quotes with slightly different blank-line handling
+    besides.
+    """
+    return [f"> {line}" if line.strip() else ">" for line in snippet.splitlines() or [""]]

backdraft/render/cli.py

@@ -0,0 +1,107 @@
+"""`backdraft render` — the artifact, the markdown projection, or the sidecar.
+
+Render's inputs are an authored document and the sidecar bind wrote beside it.
+The registry is never opened here: an artifact must be reproducible from the two
+files a reader was handed, on a machine that has never seen the sources.
+
+Mounted by the top-level CLI as `app`, per SPEC Addendum B:
+
+    from backdraft.render import cli as render_cli
+    app.registered_commands.extend(render_cli.app.registered_commands)
+
+which puts this module's one command at `backdraft render <doc.md>`.
+
+NOTE: typer collapses a single-command app into a bare command, so invoking this
+module's `app` on its own takes the document as its first argument and does not
+want the word `render`. The command name only exists once it is mounted next to
+the top level's other commands.
+"""
+
+from __future__ import annotations
+
+import sys
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from ..cli_context import UsageError, guard
+from ..kernel.artifact import (
+    ARTIFACT_SUFFIX,
+    FOOTNOTES_SUFFIX,
+    SIDECAR_SUFFIX,
+)
+from . import footnotes, html, sidecar
+
+__all__ = ["app", "Target"]
+
+app = typer.Typer(help="Render a bound document as a self-contained artifact.")
+
+
+class Target(StrEnum):
+    """What to render. `html` is the artifact; the others are projections of it."""
+
+    HTML = "html"
+    FOOTNOTES = "footnotes"
+    JSON = "json"
+
+
+_SUFFIX = {
+    Target.HTML: ARTIFACT_SUFFIX,
+    Target.FOOTNOTES: FOOTNOTES_SUFFIX,
+    Target.JSON: SIDECAR_SUFFIX,
+}
+"""The naming family is the format's, so it comes from `kernel/artifact.py`."""
+
+
+@app.command()
+def render(
+    doc: Annotated[Path, typer.Argument(help="The authored markdown document.")],
+    to: Annotated[Target, typer.Option("--to", help="Output form.")] = Target.HTML,
+    out: Annotated[
+        Path | None,
+        typer.Option("-o", "--out", help="Output file; '-' writes to stdout."),
+    ] = None,
+) -> None:
+    """Render `doc` and its sidecar.
+
+    The sidecar is found beside the document as `<doc>.backdraft.json` (see
+    spec/artifact.md). Exit codes: 0 on success, 1 when the document or its
+    sidecar is missing or unreadable.
+
+    NOTE: the spec's exit code 2 belongs to `bind` — render reports unresolved
+    citations in the artifact, which is the whole point, and does not fail on
+    them.
+    """
+    with guard():
+        if not doc.is_file():
+            raise UsageError(f"no such document: {doc}")
+        found = sidecar.find_sidecar(doc)
+        if found is None:
+            raise UsageError(
+                f"no sidecar beside {doc.name}: expected {sidecar.sidecar_path(doc).name}. "
+                "Run `backdraft bind` first."
+            )
+        try:
+            report = sidecar.read(found)
+        except (ValueError, KeyError, OSError) as error:
+            raise UsageError(f"unreadable sidecar {found.name}: {error}") from error
+
+    source = doc.read_text(encoding="utf-8")
+    if to is Target.HTML:
+        text = html.render(source, report)
+    elif to is Target.FOOTNOTES:
+        text = footnotes.render(source, report)
+    else:
+        text = sidecar.dumps(report)
+
+    # NOTE: `--to json` writes to stdout unless told otherwise — its default file
+    # name is the sidecar it just read, and rewriting an input in place is not a
+    # thing a render command should do quietly.
+    if (out is not None and str(out) == "-") or (out is None and to is Target.JSON):
+        sys.stdout.write(text)
+        return
+    target = out or doc.with_name(doc.stem + _SUFFIX[to])
+    target.write_text(text, encoding="utf-8")
+    typer.secho(str(target), fg=typer.colors.GREEN)

backdraft/render/footnotes.py

@@ -0,0 +1,172 @@
+"""The markdown projection: claims become footnote refs, receipts become notes.
+
+The lossy, portable rendering — for a pull request, an email, a wiki, anywhere
+HTML cannot go. Every receipt still travels: document, locator, verbatim quote,
+snippet hash, statuses and verdicts. What it gives up is the click.
+
+The projection is total. Every claim gets a ref, every citation gets a note, and
+every non-resolved citation is repeated in a visible Unresolved section, because
+failures are data.
+"""
+
+from __future__ import annotations
+
+from ..kernel.model import BindReport, Citation, CitationStatus
+from ._text import quote_lines as _quote
+from ._text import short, status_note
+from .placement import Placement, locate
+from .sidecar import FORMAT, SIDECAR_SUFFIX
+
+__all__ = ["render", "LABEL_PREFIX"]
+
+LABEL_PREFIX = "bd"
+"""Footnote labels are `bd1`, `bd2`, ... in document order."""
+
+CLAIM_ECHO_CHARS = 72
+"""How much of a claim a list entry echoes: one markdown line's worth."""
+
+_Note = tuple[str, list[str]]
+
+
+def render(source: str, report: BindReport) -> str:
+    """Render `source` and its bind report as plain markdown with footnotes."""
+    placements = locate(source, report.claims)
+    notes: list[_Note] = []
+    body = _body(source, placements, notes)
+    sections = [body.rstrip(), "---", _receipts(report, notes), _unresolved(placements)]
+    return "\n\n".join(section for section in sections if section) + "\n"
+
+
+def _body(source: str, placements: list[Placement], notes: list[_Note]) -> str:
+    """The document with each claim's citation construct replaced by refs."""
+    pieces: list[str] = []
+    cursor = 0
+    for placement in placements:
+        claim_notes = _notes_for(placement, len(notes))
+        notes.extend(claim_notes)
+        if placement.start is None or placement.end is None:
+            continue
+        pieces.append(source[cursor : placement.start])
+        pieces.append(
+            placement.claim.text + "".join(f"[^{label}]" for label, _ in claim_notes)
+        )
+        cursor = placement.end
+    pieces.append(source[cursor:])
+    return "".join(pieces)
+
+
+def _notes_for(placement: Placement, offset: int) -> list[_Note]:
+    """One note per citation; a claim with no citation still gets one."""
+    claim = placement.claim
+    if not claim.citations:
+        return [(f"{LABEL_PREFIX}{offset + 1}", _unanchored_note(placement))]
+    return [
+        (f"{LABEL_PREFIX}{offset + position}", _note(citation, placement))
+        for position, citation in enumerate(claim.citations, start=1)
+    ]
+
+
+def _note(citation: Citation, placement: Placement) -> list[str]:
+    """The lines of one footnote: source, quote, token, drift, verdicts.
+
+    Groups are separated by blank lines so that the quote is a blockquote in the
+    footnote and not a lazy continuation of the line above it.
+    """
+    anchor = citation.anchor
+    if anchor is not None:
+        groups = [
+            [f"**{anchor.slug}** · `{anchor.locator}` · {citation.status}"],
+            _quote(anchor.receipt.snippet),
+            [f"Token `{citation.token}` · sha256 `{anchor.receipt.snippet_sha256}`"],
+        ]
+    else:
+        groups = [[f"unanchored · {citation.status}"], [f"Token `{citation.token}`"]]
+    if citation.drifted_from is not None:
+        groups.append(["As cited, before the source changed:"])
+        groups.append(_quote(citation.drifted_from))
+    if citation.error:
+        groups.append([f"Error: {citation.error}"])
+    groups.append(
+        ["Verdicts: " + (_verdicts(citation) if citation.verdicts else "none run.")]
+    )
+    groups.append(_claim_notes(placement))
+    return _joined(groups)
+
+
+def _unanchored_note(placement: Placement) -> list[str]:
+    """A claim bind carried but could not cite at all."""
+    head = [f"unmatched · no citation — claim: “{_echo(placement.claim.text)}”"]
+    return _joined([head, _claim_notes(placement)])
+
+
+def _claim_notes(placement: Placement) -> list[str]:
+    """What is true of the claim itself, rather than of one citation."""
+    lines: list[str] = []
+    if placement.claim.unmatched:
+        lines.append("This claim is unmatched: bind could not anchor it.")
+    if not placement.placed:
+        lines.append("This claim was not located in the document text above.")
+    return lines
+
+
+def _joined(groups: list[list[str]]) -> list[str]:
+    """Non-empty groups, separated by one blank line."""
+    out: list[str] = []
+    for group in groups:
+        if not group:
+            continue
+        if out:
+            out.append("")
+        out.extend(group)
+    return out
+
+
+def _verdicts(citation: Citation) -> str:
+    return "; ".join(
+        f"{verdict.method} {verdict.status}" + (f" — {verdict.detail}" if verdict.detail else "")
+        for verdict in citation.verdicts
+    )
+
+
+def _receipts(report: BindReport, notes: list[_Note]) -> str:
+    """The footnote definitions, under a provenance line."""
+    session = f", session `{report.session_id}`" if report.session_id else ""
+    stem = report.doc_path.rsplit("/", 1)[-1].rsplit(".", 1)[0]
+    lines = [
+        "## Receipts",
+        "",
+        f"Bound from `{report.doc_path}` — {report.mode}{session}, {report.bound_at}. "
+        f"Machine-readable record: `{stem}{SIDECAR_SUFFIX}` (`{FORMAT}`).",
+        "",
+    ]
+    for label, note in notes:
+        first, *rest = note
+        lines.append(f"[^{label}]: {first}")
+        lines.extend(f"    {line}" if line else "" for line in rest)
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def _unresolved(placements: list[Placement]) -> str:
+    """Every non-resolved citation and every unmatched claim, visibly."""
+    items: list[str] = []
+    for placement in placements:
+        for citation in placement.claim.citations:
+            if citation.status is CitationStatus.RESOLVED:
+                continue
+            items.append(
+                f"- **{citation.status}** — `{citation.token}` "
+                f"in claim {placement.number}, “{_echo(placement.claim.text)}”: "
+                f"{citation.error or status_note(citation.status)}."
+            )
+        if placement.claim.unmatched:
+            items.append(
+                f"- **unmatched** — claim {placement.number}, "
+                f"“{_echo(placement.claim.text)}”: bind could not anchor it."
+            )
+    return "\n".join(["## Unresolved", "", *(items or ["Every citation resolved."])])
+
+
+def _echo(text: str) -> str:
+    """A claim's text, collapsed to one line for a list entry."""
+    return short(text, limit=CLAIM_ECHO_CHARS)