quirework 0.1.0__py3-none-any.whl

quirework/delivery/artifacts.py

@@ -0,0 +1,210 @@
+"""Explicit delivery transforms, independent of exposure and session topology.
+
+Text is not silently cleaned or summarized. Source shaping is a preparation
+choice; arbitrary files remain opaque unless their declared delivery needs a
+conversion. A registry allows further transports without editing the engine.
+"""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from quirework.runs.storage import digest
+from quirework.runs.storage import relative
+
+TRANSFORMS = {}
+
+
+def register(name):
+    def install(function):
+        if name in TRANSFORMS:
+            raise ValueError(f"duplicate delivery transform: {name}")
+        TRANSFORMS[name] = function
+        return function
+
+    return install
+
+
+def copy(source, target):
+    if source.is_symlink() or not source.is_file():
+        raise ValueError(f"material must be a regular file: {source}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(source, target)
+    return target
+
+
+@register("text")
+def text(source, directory):
+    source.read_text(encoding="utf-8")  # Reject a binary pretending to be text.
+    return [("text", copy(source, directory / "material.txt"))]
+
+
+@register("image")
+def image(source, directory):
+    # SVG is not a native image attachment in these adapters. Make conversion
+    # explicit with delivery=svg; never claim that staging an SVG showed it.
+    if source.suffix.lower() not in (".png", ".jpg", ".jpeg", ".webp"):
+        raise ValueError(
+            "image delivery requires PNG, JPEG or WebP; use svg for conversion"
+        )
+    return [("image", copy(source, directory / ("image" + source.suffix.lower())))]
+
+
+@register("svg")
+def svg(source, directory):
+    frozen = copy(source, directory / "source.svg")
+    dest = directory / "image.png"
+    subprocess.run(
+        ["rsvg-convert", "-w", "1600", "-o", str(dest), str(frozen)],
+        check=True,
+        capture_output=True,
+    )
+    return [("image", dest)]
+
+
+@register("pages")
+def pages(source, directory):
+    from pypdf import PdfReader
+
+    frozen = copy(source, directory / "source.pdf")
+    subprocess.run(
+        ["pdftoppm", "-png", "-scale-to", "1600", str(frozen), str(directory / "page")],
+        check=True,
+        capture_output=True,
+    )
+    files = sorted(
+        directory.glob("page-*.png"), key=lambda p: int(p.stem.rsplit("-", 1)[1])
+    )
+    if not files or len(files) != len(PdfReader(frozen).pages):
+        raise RuntimeError("incomplete PDF page rasterization")
+    return [("image", p) for p in files]
+
+
+@register("file")
+def file(source, directory):
+    return [("file", copy(source, directory / ("material" + source.suffix)))]
+
+
+def prepare(materials, origin, destination, cache=None):
+    """Freeze the exact source plus derived delivery bytes, with neutral names."""
+    if not isinstance(materials, list):
+        raise ValueError("materials must be a list")
+    result = []
+    for index, item in enumerate(materials):
+        if not isinstance(item, dict) or set(item) - {"source", "delivery", "label"}:
+            raise ValueError("material fields: source, delivery, optional label")
+        if item.get("delivery") not in TRANSFORMS:
+            raise ValueError(f"unknown delivery: {item.get('delivery')}")
+        if "label" in item and (
+            not isinstance(item["label"], str) or not item["label"].strip()
+        ):
+            raise ValueError("material label must contain text")
+        source = Path(item["source"]).expanduser()
+        source = source if source.is_absolute() else origin / source
+        directory = destination / f"asset-{index:03d}"
+        directory.mkdir(parents=True)
+        before = digest(source)
+        key = (item["delivery"], before, source.suffix.lower())
+        cached = cache.get(key) if cache is not None else None
+        # Composite prose/figure transforms have multiple source dependencies;
+        # don't cache them under the chapter hash alone.
+        cacheable = item["delivery"] not in ("prose", "prose-images")
+        if cached and cacheable:
+            previous, output_items = cached
+            shutil.copytree(previous, directory, dirs_exist_ok=True)
+            values = [(kind, directory / rel) for kind, rel in output_items]
+        else:
+            values = TRANSFORMS[item["delivery"]](source, directory)
+            if cache is not None and cacheable:
+                cache[key] = (
+                    directory,
+                    [(kind, str(p.relative_to(directory))) for kind, p in values],
+                )
+        if digest(source) != before:
+            raise RuntimeError(f"source changed while freezing: {source}")
+        for kind, path in values:
+            result.append(
+                dict(
+                    kind=kind,
+                    path=str(path.relative_to(destination)),
+                    sha256=digest(path),
+                    source_sha256=before,
+                    delivery=item["delivery"],
+                    label=item.get("label"),
+                )
+            )
+    return result
+
+
+def stage(items, frozen, destination, virtual):
+    """Only the declared current turn is copied; return prompt and attachments."""
+    destination.mkdir(parents=True, exist_ok=True)
+    chunks, images, files = [], [], []
+    for index, item in enumerate(items):
+        source = frozen / relative(item["path"])
+        path = destination / f"material-{index:03d}{source.suffix}"
+        copy(source, path)
+        shown = virtual / path.name
+        if item["kind"] == "text":
+            label = f": {item['label']}" if item.get("label") else ""
+            chunks.append(
+                f"\n=== MATERIAL {index + 1}{label} ===\n{path.read_text()}\n=== END MATERIAL ==="
+            )
+        elif item["kind"] == "image":
+            images.append((path, shown))
+            if item.get("label"):
+                chunks.append(f"\nAttached image {len(images)}: {item['label']}\n")
+        else:
+            files.append((path, shown))
+            if item.get("label"):
+                chunks.append(f"\nFile {shown}: {item['label']}\n")
+    if files:
+        chunks.append(
+            "\nRead the supplied files at these exact paths; do not search for them:\n"
+            + "\n".join(str(v) for _, v in files)
+        )
+    return "\n".join(chunks), images, files
+
+
+@register("prose")
+def prose(source, directory):
+    from quirework.delivery.text import reader_markdown
+
+    frozen = copy(source, directory / ("source" + source.suffix))
+    text, figures = reader_markdown(frozen.read_text())
+    for figure in figures:
+        text = text.replace(
+            f"![{figure['caption']}](../{figure['file']})",
+            f"[Figure caption: {figure['caption']}]",
+        )
+    dest = directory / "material.md"
+    dest.write_text(text)
+    return [("text", dest)]
+
+
+@register("prose-images")
+def prose_images(source, directory):
+    from quirework.delivery.text import reader_markdown
+
+    # The figures travel as images, so their alt text would only restate
+    # them in words, and a seat could rate a figure from that without ever
+    # looking at it. Text-only `prose` keeps it: there the description is
+    # the only account of the figure the seat gets.
+    frozen = copy(source, directory / ("source" + source.suffix))
+    text, figures = reader_markdown(frozen.read_text(), alt=False)
+    dest = directory / "material.md"
+    dest.write_text(text)
+    result = [("text", dest)]
+    for index, figure in enumerate(figures):
+        # A figure travels from beside the page that embeds it. A site-root
+        # path or a URL names something only the published site can find.
+        if "://" in figure["source"] or Path(figure["source"]).is_absolute():
+            raise ValueError(
+                f"{source.name}: figure {figure['source']} is not a file beside "
+                "the page, so it cannot be delivered as an image; deliver the "
+                "page as text, or its figures as their own materials"
+            )
+        original = source.parent / figure["source"]
+        transform = svg if original.suffix.lower() == ".svg" else image
+        result += transform(original, directory / f"figure-{index:03d}")
+    return result

quirework/delivery/text.py

@@ -0,0 +1,166 @@
+"""A reader's copy of a unit's source: the Markdown a reader of the page sees.
+
+A seat handed prose must get what a reader of the rendered page gets and
+nothing the author keeps for themselves: no frontmatter (a draft flag, tags, a
+summary the author wrote about the piece), no comments (the marks), no raw
+output blocks, no anchors and no generator syntax. It is not a renderer and
+makes no layout claim.
+
+The source may be written for Quarto or for a site generator, and the
+projection reads either by its syntax alone, since a delivery never knows the
+project's format and must not import it:
+
+- frontmatter in either convention, TOML between `+++` or YAML between `---`
+- a figure as Pandoc writes it, `![caption](plate.svg){fig-alt="..."}`, whose
+  `fig-alt` is required; as plain Markdown, `![alt text](plate.png)`; or as
+  Hugo's `{{< figure src="..." alt="..." caption="..." >}}`
+- any other shortcode: a paired one keeps its content and loses its tags, a
+  link whose target is one keeps its text, and a standalone one is dropped,
+  since it renders as something no Markdown reader can be handed
+- a Pandoc fenced div, such as a table float or a callout, which is paired
+  syntax too: its fence lines go and what it holds stays
+
+Anything that survives the projection and should not have is refused by name
+rather than delivered.
+"""
+
+import re
+from pathlib import Path
+
+from quirework.core import frontmatter
+
+HTML_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
+
+RAW_BLOCK = re.compile(r"^```\{=[^}]+\}\s*$.*?^```\s*$", re.MULTILINE | re.DOTALL)
+
+ATTR_BLOCK = re.compile(r"\s*\{(?=[#.])[^{}\n]*\}")
+
+# A fenced div's fence line, opening or closing: three or more colons, then
+# an attribute block or a bare class name on an opening fence, and optionally
+# trailing colons. Only the fence goes; the lines between are prose, a table
+# or a caption, and a reader of the page reads them.
+DIV_FENCE = re.compile(
+    r"^[ \t]*:{3,}[ \t]*(?:\{[^{}\n]*\}|[A-Za-z][\w-]*)?[ \t]*:*[ \t]*$",
+    re.MULTILINE,
+)
+
+_IMAGE = r"(?:svg|png|jpe?g|webp)"
+
+# `![text](source){attrs}`: Pandoc's figure when the attribute block is there,
+# plain Markdown when it is not. A title after the source is allowed.
+FIGURE = re.compile(
+    r"!\[(?P<caption>[^\]]*)\]\((?P<name>[^)\"]+?\." + _IMAGE + r")"
+    r"(?:\s+\"[^\"]*\")?\)"
+    r"(?P<attrs>\{[^\n]*\})?"
+)
+
+# A shortcode tag, `{{< ... >}}` or `{{% ... %}}`. The escaped form a page
+# uses to show one literally (`{{</* ... */>}}`) is not a tag.
+_SHORTCODE = r"\{\{[<%](?!/\*)\s*(?P<body>.*?)\s*[%>]\}\}"
+SHORTCODE = re.compile(_SHORTCODE, re.DOTALL)
+SHORTCODE_LINK = re.compile(r"\[(?P<text>[^\]]*)\]\(\s*" + _SHORTCODE + r"\s*\)")
+_PARAM = re.compile(r"""(\w+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+))""")
+
+
+def _params(body: str) -> dict[str, str]:
+    return {
+        m.group(1): next(g for g in m.group(2, 3, 4) if g is not None)
+        for m in _PARAM.finditer(body)
+    }
+
+
+def _paired(text: str) -> str:
+    """Drop the tags of every paired shortcode, keeping what they enclose."""
+    names = {
+        m.group("body").split()[0].lstrip("/")
+        for m in SHORTCODE.finditer(text)
+        if m.group("body").startswith("/")
+    }
+    for name in names:
+        tag = r"\{\{[<%]\s*/?" + re.escape(name) + r"\b.*?[%>]\}\}"
+        text = re.sub(tag, "", text, flags=re.DOTALL)
+    return text
+
+
+def reader_markdown(text: str, alt: bool = True) -> tuple[str, list[dict]]:
+    """Reader-facing Markdown from a unit's source, and its figures.
+
+    ``alt`` prints each figure's alt text as a visible description under the
+    embed. Keep it where the reader gets no image, since it is then the only
+    account of the figure; drop it where the image is delivered, since there
+    it restates the picture and lets a reader rate one it never looked at.
+    """
+    found = frontmatter.block(text)
+    if found:
+        text = text[found.end() :]
+    elif text.startswith(("---\n", "+++\n")):
+        raise RuntimeError("unterminated frontmatter")
+    text = HTML_COMMENT.sub("", text)
+    text = RAW_BLOCK.sub("", text)
+    figures = []
+
+    def figure(name: str, caption: str, description: str) -> str:
+        png = Path(name).with_suffix(".png").name
+        figures.append(
+            {
+                "source": name,
+                "file": f"figures/{png}",
+                "caption": caption,
+                "alt": description,
+            }
+        )
+        embed = f"![{caption}](../figures/{png})"
+        return f"{embed}\n\n*Figure description:* {description}" if alt else embed
+
+    def markdown_figure(match: re.Match) -> str:
+        caption = match.group("caption").strip()
+        name = match.group("name")
+        attrs = match.group("attrs")
+        if attrs is not None:
+            alt_match = re.search(r'fig-alt="([^"]+)"', attrs)
+            if not alt_match:
+                raise RuntimeError(f"figure has no fig-alt: {name}")
+            return figure(name, caption, alt_match.group(1))
+        if not caption:
+            raise RuntimeError(f"figure has no alt text: {name}")
+        return figure(name, caption, caption)
+
+    def shortcode_figure(match: re.Match) -> str:
+        body = match.group("body")
+        if not re.match(r"figure\b", body):
+            return match.group(0)
+        params = _params(body)
+        name = params.get("src", "")
+        if not re.search(r"\." + _IMAGE + r"\Z", name):
+            raise RuntimeError(f"figure shortcode has no image source: {body}")
+        caption = params.get("caption") or params.get("title") or ""
+        description = params.get("alt") or caption
+        if not description:
+            raise RuntimeError(f"figure has no alt text: {name}")
+        return figure(name, caption, description)
+
+    text = FIGURE.sub(markdown_figure, text)
+    text = SHORTCODE.sub(shortcode_figure, text)
+    text = SHORTCODE_LINK.sub(lambda m: m.group("text"), text)
+    text = _paired(text)
+    text = re.sub(r"(?m)^[ \t]*" + _SHORTCODE + r"[ \t]*$", "", text, flags=re.DOTALL)
+    text = SHORTCODE.sub("", text)
+    text = DIV_FENCE.sub("", text)
+    text = ATTR_BLOCK.sub("", text)
+    text = re.sub(r"\n{3,}", "\n\n", text).strip() + "\n"
+    leaks = []
+    if "<!--" in text:
+        leaks.append("HTML comment")
+    if "{#" in text:
+        leaks.append("anchor")
+    if re.search(r"!\[[^\]]*\]\([^)]*\.svg", text):
+        leaks.append("SVG source path")
+    if re.search(r"^```\{=", text, re.MULTILINE):
+        leaks.append("raw-format block")
+    if SHORTCODE.search(text):
+        leaks.append("shortcode")
+    if re.search(r"^[ \t]*:{3,}", text, re.MULTILINE):
+        leaks.append("div fence")
+    if leaks:
+        raise RuntimeError(f"clean Markdown still contains: {', '.join(leaks)}")
+    return text, figures

quirework/manuscript/__init__.py

@@ -0,0 +1 @@
+"""The written work: its units, spec, marks, quotations and trail."""