fux-decoder-drawio 4.1.1__py3-none-any.whl

fux_decoder_drawio/__init__.py

@@ -0,0 +1,12 @@
+"""`fux_decoder_drawio` — the fux-decoder-drawio package (W-289, SR-PLUGINS).
+
+One fux decoder module per format it reads: `fux_decoder_drawio.drawio`. Each is the
+decoder protocol of SR-DECODE — `EXTENSIONS`, `VERSION`, `USES` and
+`decode(raw, rel_path)` — moved here unchanged from `src/fux/decode/` in
+W-289 phase 2.
+
+**fux loads a module from here only when `.fux/plugins.toml` declares this
+package**, after verifying its version and digest (SR-PLUGINS P3, P4), by its
+fixed import name (P7). A same-named file in `.fux/decoders/` overrides it
+(P8). This file runs nothing: importing the package imports no decoder.
+"""

fux_decoder_drawio/drawio.py

@@ -0,0 +1,130 @@
+"""`.drawio` / `.dio` -> Markdown — the labels in an architecture diagram.
+
+Niche and worth it: a team's architecture lives in diagrams, and the box labels
+are exactly the terms someone searches for. Today they are invisible.
+
+The format is XML, but the interesting part is usually **deflated and
+base64'd** inside a `<diagram>` element — draw.io compresses the model by
+default. `zlib` and `base64` are both stdlib, so this stays `$0`; the only
+subtlety is that the payload is *raw* deflate with no zlib header, which needs
+a negative window size.
+
+⚠ **Labels are HTML fragments**, so they are converted through `html` rather
+than stripped by hand — one HTML implementation, per SR-DECODE.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+import zlib
+from urllib.parse import unquote
+from fux.decode.ext.limits import limit
+
+# Imports are ABSOLUTE, not relative, and that is what makes this file work in
+# both places it runs: as a package module, and as a consumer copy in
+# `.fux/decoders/` loaded by path. A path-loaded file has no parent package, so
+# `from . import _xml` raises `attempted relative import with no known parent
+# package` — the copy would be dead on arrival. Absolute imports mean the file
+# fux ships and the file you edit are byte-identical (SR-DECODE decision 11).
+from fux.decode.ext import xml as _xml
+from fux_decoder_html.html import html_to_markdown
+from fux.constants import fixed
+
+#: **The reuse key's handle on this decoder** (W-166). Bump it by hand in the
+#: same change as any edit that can change what `decode()` returns, and the next
+#: `fux ingest` re-extracts the documents bound to THIS decoder and no others.
+#: Leaving it alone is the claim that the edit cannot move a byte of output.
+#: `tests/decode/test_decoder_versions.py` fails on a changed module that did
+#: not bump it. [SR-DECODE](../../../../records/0139_decode.md) decision 11a.
+VERSION = fixed("decoders.drawio", "version")  # not bumped by W-225 4a (caps moved, same values) nor 5b (numerals moved, same output); not bumped by W-288 (imports moved to decode/ext, same output; USES now carries the extensions' VERSIONs)
+
+EXTENSIONS = tuple(fixed("decoders.drawio", "extensions"))
+#: The decoder extensions this decoder calls, read by the reuse key (SR-DECODE decision 24).
+USES = tuple(fixed("decoders.drawio", "uses"))
+
+#: A diagram page is a complete unit — a short page was being absorbed by
+#: the next one and cited under the wrong name.
+
+#: ⚠ **`MAX_INFLATED` is `[limits.drawio] max_inflated` in .fux/formats.toml** since W-225 stage 4a
+#: (SR-LAW-12 decision 9b): read per call through `limit()`, in the extract-config digest.
+_TAG_RE = re.compile(r"<[^>]+>")
+
+
+def decode(raw: bytes, rel_path: str) -> str | None:
+    try:
+        root = _xml.parse(raw)
+    except _xml.UnsafeXml:
+        return None
+
+    blocks: list[str] = []
+    for diagram in root.iter():
+        if _xml.local(diagram.tag) != "diagram":
+            continue
+        name = ""
+        for key, value in diagram.attrib.items():
+            if _xml.local(key) == "name":
+                name = value
+        model = _model(diagram)
+        if model is None:
+            continue
+        labels = _labels(model)
+        if not labels:
+            continue
+        blocks.append(f"## {name}" if name else "## Diagram")
+        blocks.extend(f"- {label}" for label in labels)
+
+    body = "\n\n".join(blocks)
+    return body if body.strip() else None
+
+
+def _model(diagram):
+    """The `mxGraphModel` element, inflating the compressed payload if needed."""
+    for child in diagram:
+        if _xml.local(child.tag) == "mxGraphModel":
+            return child  # stored uncompressed; nothing to do
+    payload = (diagram.text or "").strip()
+    if not payload:
+        return None
+    try:
+        compressed = base64.b64decode(payload, validate=True)
+        # Negative window bits: raw deflate, no zlib header. draw.io writes it
+        # this way and a default-window inflate simply fails, which reads as
+        # "not a diagram".
+        inflated = zlib.decompressobj(-zlib.MAX_WBITS).decompress(
+            compressed, limit("drawio", "max_inflated")
+        )
+    except (ValueError, zlib.error):
+        return None
+    try:
+        return _xml.parse_text(unquote(inflated.decode("utf-8", errors="replace")))
+    except _xml.UnsafeXml:
+        return None
+
+
+def _labels(model) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    # Document order, not sorted: a diagram's cells are laid out in a meaningful
+    # sequence and `extract.py` scores earlier text slightly higher.
+    for cell in model.iter():
+        if _xml.local(cell.tag) != "mxCell":
+            continue
+        value = ""
+        for key, attr in cell.attrib.items():
+            if _xml.local(key) == "value":
+                value = attr
+        if not value.strip():
+            continue
+        text = _plain(value)
+        if text and text not in seen:
+            seen.add(text)
+            out.append(text)
+    return out
+
+
+def _plain(value: str) -> str:
+    if "<" not in value:
+        return " ".join(value.split())
+    converted = html_to_markdown(value)
+    return " ".join(_TAG_RE.sub(" ", converted).split())

fux_decoder_drawio-4.1.1.dist-info/METADATA

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: fux-decoder-drawio
+Version: 4.1.1
+Summary: Fux decoder package: draw.io diagrams.
+Project-URL: Homepage, https://github.com/arpitarya/fux
+Project-URL: Repository, https://github.com/arpitarya/fux
+Author-email: arpit arya <arpitarya.me@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: fux-core==4.1.1
+Requires-Dist: fux-decoder-html==4.1.1
+Description-Content-Type: text/markdown
+
+# fux-decoder-drawio
+
+Part of [fux](https://github.com/arpitarya/fux) — rank your written knowledge
+from a small index committed to git; fetch content from the systems that own
+it; verify freshness at answer time.
+
+**`fux-decoder-drawio` is a fux decoder package: draw.io diagrams.** Only `fux-engine` is mandatory;
+everything else is declared per repository in the committed
+`.fux/plugins.toml`, pinned to one version and digest, and refused loudly when
+it is missing or differs, so two machines on one repository never build
+different indexes.
+
+It reads `.drawio` `.dio`. Install it and declare it in `.fux/plugins.toml` --
+`fux setup` proposes it when your sources hold those files -- or fux does not
+read them, and `fux doctor` says so.
+
+It is released on fux's own version, together with every other fux package.
+Documentation: <https://github.com/arpitarya/fux#readme>

fux_decoder_drawio-4.1.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+fux_decoder_drawio/__init__.py,sha256=Q-K4HIMHkXoehwUQMl1GiqqLuSjDtsfTlWHuSyVt3XM,631
+fux_decoder_drawio/drawio.py,sha256=Ali9ioJJ9XiD-GT303cUsZpmwRFQTFtGqdVmwLtsK_w,5227
+fux_decoder_drawio-4.1.1.dist-info/METADATA,sha256=1eXKxhc7gTUBJhTZ1_ad-y_UWuDlI0lTcJF_PwhF2xE,1310
+fux_decoder_drawio-4.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fux_decoder_drawio-4.1.1.dist-info/RECORD,,

fux_decoder_drawio-4.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any