pubkit 0.1.0__py3-none-any.whl

pubkit/core/checks.py

@@ -0,0 +1,344 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Pre-flight checks.
+
+These exist because of a specific, humbling experience: a scripted pass over 32
+numeric claims in a finished article found 5 that were wrong, including two
+ratios that had been transposed during an edit. Every one of the 5 was real.
+Prose does not have a type checker; this is the closest thing.
+
+Checks are pluggable (`pubkit.checks` entry point). Ship your own house-style
+rule and it runs in the same pipeline.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Protocol
+
+from .ir import Callout, Document, Heading, ListBlock, Paragraph, Quote, Table
+
+
+class Severity(str, Enum):
+    ERROR = "error"
+    WARN = "warn"
+    INFO = "info"
+
+
+@dataclass
+class Finding:
+    check: str
+    severity: Severity
+    message: str
+    where: str = ""
+
+    def __str__(self) -> str:
+        loc = f" [{self.where}]" if self.where else ""
+        return f"{self.severity.value.upper():5} {self.check}{loc}: {self.message}"
+
+
+@dataclass
+class CheckResult:
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def errors(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity is Severity.ERROR]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def extend(self, other: CheckResult) -> None:
+        self.findings.extend(other.findings)
+
+
+class Check(Protocol):
+    name: str
+
+    def __call__(self, doc: Document, ctx: dict) -> CheckResult: ...
+
+
+def _text_blocks(doc: Document) -> Iterable[tuple[str, str]]:
+    for i, b in enumerate(doc.blocks):
+        if isinstance(b, (Paragraph, Quote, Callout)):
+            yield f"block[{i}]", b.text
+        elif isinstance(b, Heading):
+            yield f"heading[{i}]", b.text
+        elif isinstance(b, ListBlock):
+            for j, item in enumerate(b.items):
+                yield f"block[{i}].item[{j}]", item
+        elif isinstance(b, Table):
+            for r, row in enumerate(b.rows):
+                yield f"block[{i}].row[{r}]", " | ".join(row)
+
+
+# --------------------------------------------------------------------------
+# placeholders (failure C3)
+# --------------------------------------------------------------------------
+PLACEHOLDER_RE = re.compile(r"(\$\{[^}]+\}|URL-PART-\d+|TODO|TK|FIXME|XXX|\[\[\s*IMAGE)", re.I)
+SERIES_TOKEN_RE = re.compile(r"\$\{series\.part(\d+)\.url\}")
+
+
+def check_placeholders(doc: Document, ctx: dict) -> CheckResult:
+    """No placeholder token may reach a published document.
+
+    `URL-PART-2` links once existed in a draft because part 2 had no URL yet —
+    the chicken-and-egg every multi-document publish hits. The fix is the
+    two-phase publish; this check is the guard rail that proves it ran.
+    """
+    res = CheckResult()
+    allow: set[str] = set(ctx.get("allow_placeholders", ()))
+    # `${series.partN.url}` is *expected* to be unresolved before phase 1 of a
+    # two-phase publish — the sibling has no URL yet. It is only an error if it
+    # names a part that does not exist, or if it is still there at publish time
+    # (which is what `post_resolution` mode checks).
+    post = bool(ctx.get("post_resolution"))
+    for where, text in _text_blocks(doc):
+        for m in PLACEHOLDER_RE.finditer(text):
+            tok = m.group(0)
+            if tok in allow:
+                continue
+            sm = SERIES_TOKEN_RE.fullmatch(tok)
+            if sm and doc.series:
+                idx = int(sm.group(1))
+                if idx > doc.series.of:
+                    res.findings.append(
+                        Finding(
+                            "placeholders",
+                            Severity.ERROR,
+                            f"{tok!r} names part {idx} but the series has {doc.series.of}",
+                            where,
+                        )
+                    )
+                elif post:
+                    res.findings.append(
+                        Finding(
+                            "placeholders",
+                            Severity.ERROR,
+                            f"{tok!r} survived link resolution — phase 1 did not record that URL",
+                            where,
+                        )
+                    )
+                else:
+                    res.findings.append(
+                        Finding("placeholders", Severity.INFO, f"{tok} resolves during publish", where)
+                    )
+                continue
+            res.findings.append(
+                Finding("placeholders", Severity.ERROR, f"unresolved placeholder {tok!r}", where)
+            )
+    return res
+
+
+# --------------------------------------------------------------------------
+# numeric consistency (failure C1)
+# --------------------------------------------------------------------------
+_NUM = r"(?:\d[\d,]*(?:\.\d+)?)"
+RATIO_RE = re.compile(rf"({_NUM})\s*(?:×|x|times)\b", re.I)
+DEFINE_RE = re.compile(rf"<!--\s*pubkit:define\s+(\w+)\s*=\s*({_NUM})\s*-->")
+ASSERT_RE = re.compile(
+    rf"<!--\s*pubkit:assert\s+({_NUM})\s*(?:×|x)?\s*=\s*(\w+)\s*/\s*(\w+)\s*(?:±\s*({_NUM})%)?\s*-->"
+)
+
+
+def check_numeric(doc: Document, ctx: dict) -> CheckResult:
+    """Re-derive every ratio the author asserted from its declared inputs.
+
+    Authors annotate source values once:
+
+        <!-- pubkit:define nvlink = 900 -->
+        <!-- pubkit:define pcie5  = 128 -->
+
+    and then assert derived claims where they appear:
+
+        NVLink is 7× wider than PCIe Gen5. <!-- pubkit:assert 7x = nvlink/pcie5 ±10% -->
+
+    This is what catches a transposition. Two ratios were once swapped in an
+    edit — 18× and 7× traded places — and no amount of re-reading found it.
+    Arithmetic did, in under a second.
+    """
+    res = CheckResult()
+    defines: dict[str, float] = {}
+    raw = "\n".join(t for _, t in _text_blocks(doc))
+    for name, val in DEFINE_RE.findall(raw):
+        defines[name] = float(val.replace(",", ""))
+
+    for where, text in _text_blocks(doc):
+        for claimed, num, den, tol in ASSERT_RE.findall(text):
+            if num not in defines or den not in defines:
+                res.findings.append(
+                    Finding("numeric", Severity.ERROR, f"assert references undefined {num!r}/{den!r}", where)
+                )
+                continue
+            if defines[den] == 0:
+                res.findings.append(Finding("numeric", Severity.ERROR, f"{den!r} is zero", where))
+                continue
+            actual = defines[num] / defines[den]
+            want = float(claimed.replace(",", ""))
+            tolerance = float(tol) / 100 if tol else 0.10
+            if want == 0 or abs(actual - want) / max(abs(want), 1e-9) > tolerance:
+                res.findings.append(
+                    Finding(
+                        "numeric",
+                        Severity.ERROR,
+                        f"claimed {want:g}× but {num}/{den} = {actual:.3g}× "
+                        f"({defines[num]:g}/{defines[den]:g}), outside ±{tolerance:.0%}",
+                        where,
+                    )
+                )
+    return res
+
+
+def check_number_drift(doc: Document, ctx: dict) -> CheckResult:
+    """Flag the same quantity stated with two different values.
+
+    One section said 5,000 tok/s and another derived 5,150 from the same
+    assumptions; three cost figures downstream inherited the discrepancy.
+    """
+    res = CheckResult()
+    pattern = re.compile(rf"({_NUM})\s*(tok/s|tokens/s|GB/s|TB/s|GB|ms|µs|%|\$/M)", re.I)
+    seen: dict[str, set[str]] = {}
+    for _where, text in _text_blocks(doc):
+        for val, unit in pattern.findall(text):
+            key = unit.lower()
+            seen.setdefault(key, set()).add(val.replace(",", ""))
+    for unit, values in seen.items():
+        if len(values) > 6:  # a table of varied figures, not a drift signal
+            continue
+        floats = sorted(float(v) for v in values)
+        for a, b in zip(floats, floats[1:], strict=False):
+            if a and abs(b - a) / a < 0.08 and a != b:
+                res.findings.append(
+                    Finding(
+                        "number-drift",
+                        Severity.WARN,
+                        f"{a:g} and {b:g} {unit} differ by <8% — same quantity stated twice?",
+                    )
+                )
+    return res
+
+
+# --------------------------------------------------------------------------
+# cross-references (failure C2)
+# --------------------------------------------------------------------------
+XREF_RE = re.compile(r"\b[Pp]art\s+(\d+)\b")
+
+
+def check_xrefs(doc: Document, ctx: dict) -> CheckResult:
+    """"Part N" must resolve, and must not collide with section numbering.
+
+    Splitting one article into three turned seven internal references into
+    lies, and made the phrase "Part 1" ambiguous between a series part and a
+    section. Sections are numbered by generator now; this check enforces that
+    "Part N" only ever means the series.
+    """
+    res = CheckResult()
+    if doc.series is None:
+        for where, text in _text_blocks(doc):
+            if XREF_RE.search(text):
+                res.findings.append(
+                    Finding("xref", Severity.WARN, "'Part N' used but document declares no series", where)
+                )
+        return res
+
+    for where, text in _text_blocks(doc):
+        for n in XREF_RE.findall(text):
+            idx = int(n)
+            if idx < 1 or idx > doc.series.of:
+                res.findings.append(
+                    Finding(
+                        "xref",
+                        Severity.ERROR,
+                        f"refers to Part {idx} but the series has {doc.series.of} parts",
+                        where,
+                    )
+                )
+            elif idx == doc.series.index and "this" not in text.lower():
+                res.findings.append(
+                    Finding(
+                        "xref",
+                        Severity.WARN,
+                        f"Part {idx} refers to itself — probably a leftover from a split",
+                        where,
+                    )
+                )
+    return res
+
+
+# --------------------------------------------------------------------------
+# assets, budget, structure
+# --------------------------------------------------------------------------
+def check_assets(doc: Document, ctx: dict) -> CheckResult:
+    res = CheckResult()
+    for i, fig in enumerate(doc.figures):
+        asset = doc.assets.get(fig.asset_id)
+        if asset is None:
+            res.findings.append(
+                Finding("assets", Severity.ERROR, f"figure references unknown asset {fig.asset_id!r}", f"figure[{i}]")
+            )
+            continue
+        if not asset.path.exists() and asset.generated_from is None:
+            res.findings.append(
+                Finding("assets", Severity.ERROR, f"asset file missing: {asset.path}", f"figure[{i}]")
+            )
+        if not (fig.alt or asset.alt):
+            res.findings.append(
+                Finding("assets", Severity.WARN, f"no alt text for {fig.asset_id!r}", f"figure[{i}]")
+            )
+    unused = set(doc.assets) - {f.asset_id for f in doc.figures}
+    for a in sorted(unused):
+        res.findings.append(Finding("assets", Severity.INFO, f"asset {a!r} declared but never used"))
+    return res
+
+
+def check_budget(doc: Document, ctx: dict) -> CheckResult:
+    res = CheckResult()
+    if not doc.budget or not doc.budget.words:
+        return res
+    target, tol = doc.budget.words, doc.budget.tolerance
+    actual = doc.word_count
+    if abs(actual - target) / target > tol:
+        res.findings.append(
+            Finding(
+                "budget",
+                Severity.WARN,
+                f"{actual:,} words against a target of {target:,} (±{tol:.0%})",
+            )
+        )
+    return res
+
+
+def check_structure(doc: Document, ctx: dict) -> CheckResult:
+    res = CheckResult()
+    if not doc.title.strip():
+        res.findings.append(Finding("structure", Severity.ERROR, "empty title"))
+    levels = [b.level for b in doc.blocks if isinstance(b, Heading)]
+    for a, b in zip(levels, levels[1:], strict=False):
+        if b > a + 1:
+            res.findings.append(
+                Finding("structure", Severity.WARN, f"heading level jumps h{a} → h{b}")
+            )
+            break
+    return res
+
+
+DEFAULT_CHECKS: list[tuple[str, Callable[[Document, dict], CheckResult]]] = [
+    ("structure", check_structure),
+    ("placeholders", check_placeholders),
+    ("numeric", check_numeric),
+    ("number-drift", check_number_drift),
+    ("xref", check_xrefs),
+    ("assets", check_assets),
+    ("budget", check_budget),
+]
+
+
+def run_checks(doc: Document, ctx: dict | None = None, extra: list | None = None) -> CheckResult:
+    ctx = ctx or {}
+    out = CheckResult()
+    for _name, fn in DEFAULT_CHECKS + list(extra or []):
+        out.extend(fn(doc, ctx))
+    return out

pubkit/core/ir.py

@@ -0,0 +1,240 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""The canonical Post IR.
+
+Everything upstream (loaders) produces this; everything downstream (checks,
+planner, adapters) consumes it. No platform detail is allowed in this module —
+that is the whole point of it existing.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class BlockType(str, Enum):
+    HEADING = "heading"
+    PARAGRAPH = "paragraph"
+    CODE = "code"
+    QUOTE = "quote"
+    LIST = "list"
+    TABLE = "table"
+    FIGURE = "figure"
+    EMBED = "embed"
+    RULE = "rule"
+    CALLOUT = "callout"
+
+
+class _Block(BaseModel):
+    model_config = {"extra": "forbid"}
+
+
+class Heading(_Block):
+    type: Literal[BlockType.HEADING] = BlockType.HEADING
+    level: int = Field(ge=1, le=6)
+    text: str
+    #: Generated by the numbering pass. Never authored by hand (failure C2).
+    number: str | None = None
+    anchor: str | None = None
+
+
+class Paragraph(_Block):
+    type: Literal[BlockType.PARAGRAPH] = BlockType.PARAGRAPH
+    #: Inline markdown is permitted here; adapters degrade it as needed.
+    text: str
+
+
+class Code(_Block):
+    type: Literal[BlockType.CODE] = BlockType.CODE
+    language: str = ""
+    text: str
+
+
+class Quote(_Block):
+    type: Literal[BlockType.QUOTE] = BlockType.QUOTE
+    text: str
+    attribution: str | None = None
+
+
+class ListBlock(_Block):
+    type: Literal[BlockType.LIST] = BlockType.LIST
+    ordered: bool = False
+    items: list[str]
+
+
+class Table(_Block):
+    """A *semantic* table.
+
+    Whether this ends up as a real table, a rendered PNG or a bulleted list is
+    the planner's decision, taken per platform. Keeping it semantic here is
+    what lets one source serve Medium (no tables) and Dev.to (tables) without
+    forking the content.
+    """
+
+    type: Literal[BlockType.TABLE] = BlockType.TABLE
+    caption: str | None = None
+    header: list[str]
+    rows: list[list[str]]
+    #: Optional per-column alignment: "l" | "c" | "r"
+    align: list[str] | None = None
+
+    @field_validator("rows")
+    @classmethod
+    def _rectangular(cls, rows: list[list[str]], info) -> list[list[str]]:
+        header = info.data.get("header") or []
+        for i, row in enumerate(rows):
+            if len(row) != len(header):
+                raise ValueError(
+                    f"row {i} has {len(row)} cells, header has {len(header)}"
+                )
+        return rows
+
+
+class Figure(_Block):
+    type: Literal[BlockType.FIGURE] = BlockType.FIGURE
+    #: Reference into Document.assets. Never a filesystem path (failure B5/B6).
+    asset_id: str
+    caption: str | None = None
+    alt: str | None = None
+
+
+class Embed(_Block):
+    type: Literal[BlockType.EMBED] = BlockType.EMBED
+    url: str
+    kind: Literal["youtube", "gist", "tweet", "codepen", "generic"] = "generic"
+
+
+class Rule(_Block):
+    type: Literal[BlockType.RULE] = BlockType.RULE
+
+
+class Callout(_Block):
+    type: Literal[BlockType.CALLOUT] = BlockType.CALLOUT
+    style: Literal["note", "warning", "tip", "key"] = "note"
+    title: str | None = None
+    text: str
+
+
+Block = Annotated[
+    Heading | Paragraph | Code | Quote | ListBlock | Table | Figure | Embed | Rule | Callout,
+    Field(discriminator="type"),
+]
+
+
+class Asset(BaseModel):
+    model_config = {"extra": "forbid"}
+
+    id: str
+    path: Path
+    alt: str = ""
+    #: Set by the renderer when an asset is *generated* (e.g. a table PNG).
+    generated_from: str | None = None
+
+    @property
+    def mime(self) -> str:
+        return {
+            ".png": "image/png",
+            ".jpg": "image/jpeg",
+            ".jpeg": "image/jpeg",
+            ".gif": "image/gif",
+            ".webp": "image/webp",
+            ".svg": "image/svg+xml",
+        }.get(self.path.suffix.lower(), "application/octet-stream")
+
+    @property
+    def animated(self) -> bool:
+        return self.path.suffix.lower() == ".gif"
+
+
+class SeriesRef(BaseModel):
+    model_config = {"extra": "forbid"}
+
+    id: str
+    index: int = Field(ge=1)
+    of: int = Field(ge=1)
+    #: Populated during phase 1 of a two-phase publish (failure C3).
+    sibling_urls: dict[int, str] = Field(default_factory=dict)
+
+
+class Budget(BaseModel):
+    """Length constraints, checked pre-flight (failure C4)."""
+
+    model_config = {"extra": "forbid"}
+
+    words: int | None = None
+    tolerance: float = 0.15
+
+
+class Document(BaseModel):
+    model_config = {"extra": "forbid"}
+
+    id: str
+    title: str
+    subtitle: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    canonical_url: str | None = None
+    blocks: list[Block] = Field(default_factory=list)
+    assets: dict[str, Asset] = Field(default_factory=dict)
+    series: SeriesRef | None = None
+    budget: Budget | None = None
+    #: Free-form, passed through to adapters that understand it.
+    platform_overrides: dict[str, dict] = Field(default_factory=dict)
+
+    # ---------------------------------------------------------------- helpers
+    @property
+    def word_count(self) -> int:
+        parts: list[str] = []
+        for b in self.blocks:
+            if isinstance(b, (Paragraph, Quote, Callout)):
+                parts.append(b.text)
+            elif isinstance(b, Heading):
+                parts.append(b.text)
+            elif isinstance(b, ListBlock):
+                parts.extend(b.items)
+            elif isinstance(b, Table):
+                parts.extend(b.header)
+                for r in b.rows:
+                    parts.extend(r)
+        return len(" ".join(parts).split())
+
+    @property
+    def figures(self) -> list[Figure]:
+        return [b for b in self.blocks if isinstance(b, Figure)]
+
+    @property
+    def tables(self) -> list[Table]:
+        return [b for b in self.blocks if isinstance(b, Table)]
+
+    def canonical_json(self) -> str:
+        """Stable serialisation used for the content id.
+
+        Sorted keys, no whitespace, UTF-8 preserved. Note `ensure_ascii=False`:
+        escaping `×` into `\\u00d7` is how a correction pipeline silently
+        stopped matching once already (failure C5).
+        """
+        payload = self.model_dump(mode="json", exclude={"series"})
+        return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+    @property
+    def content_id(self) -> str:
+        """Idempotency key. Same content ⇒ same id ⇒ update, never re-create."""
+        return hashlib.blake2b(self.canonical_json().encode("utf-8"), digest_size=16).hexdigest()
+
+
+class Series(BaseModel):
+    model_config = {"extra": "forbid"}
+
+    id: str
+    title: str
+    documents: list[Document]
+
+    def by_index(self, i: int) -> Document:
+        for d in self.documents:
+            if d.series and d.series.index == i:
+                return d
+        raise KeyError(f"no document at series index {i}")