spolvero 0.3.0__py3-none-any.whl

spolvero/engines/vsdx_template.py

@@ -0,0 +1,251 @@
+"""vsdx-template engine.
+
+Mutates a Visio template by copying stamp shapes from a template page to
+represent each IR node, then connecting them to represent IR edges.
+
+Activation:
+- ``vsdx`` Python library must be importable (optional extra ``[vsdx]``).
+- The IR must be a Mermaid flowchart (``is_flowchart_ir``).
+- A template ``.vsdx`` file must be available, either via ``ctx.options['template']``
+  (CLI ``--template PATH``) or the bundled minimal template at
+  ``src/spolvero/templates/minimal_flowchart.vsdx``.
+
+If any precondition fails, the engine falls back to the Data Visualizer engine
+and records a warning explaining what is needed to engage the real path.
+"""
+
+from __future__ import annotations
+
+import importlib.resources as resources
+import importlib.util
+import shutil
+import traceback
+from pathlib import Path
+from typing import Any
+
+from spolvero.engines import EngineContext, EngineResult, register
+from spolvero.engines.data_visualizer import run as data_visualizer_run
+from spolvero.ir import is_flowchart_ir
+from spolvero.utils import backup_if_manual_candidate
+
+# Stamp shapes available in the bundled template.
+_RECTANGLE_STAMP = "RECTANGLE"
+_CIRCLE_STAMP = "CIRCLE"
+_CONNECTOR_STAMP = "STRAIGHT_CONNECTOR"
+_KNOWN_STAMPS = {
+    _RECTANGLE_STAMP,
+    _CIRCLE_STAMP,
+    _CONNECTOR_STAMP,
+    "CONNECTED_SHAPE",
+    "CURVED_CONNECTOR",
+    "LINE",
+}
+
+# IR shape_kind -> stamp name. The bundled template only carries rectangles
+# and circles; richer stencils require a user-supplied template.
+_KIND_TO_STAMP = {
+    "terminator": _CIRCLE_STAMP,
+    "circle": _CIRCLE_STAMP,
+    "decision": _RECTANGLE_STAMP,
+    "process": _RECTANGLE_STAMP,
+    "rounded": _RECTANGLE_STAMP,
+    "subprocess": _RECTANGLE_STAMP,
+    "document": _RECTANGLE_STAMP,
+    "data_io": _RECTANGLE_STAMP,
+    "database": _RECTANGLE_STAMP,
+}
+
+
+def _vsdx_available() -> bool:
+    return importlib.util.find_spec("vsdx") is not None
+
+
+def _bundled_template_path() -> Path | None:
+    try:
+        ref = resources.files("spolvero.templates").joinpath("minimal_flowchart.vsdx")
+        return Path(str(ref)) if ref.is_file() else None
+    except (FileNotFoundError, ModuleNotFoundError):
+        return None
+
+
+def _resolve_template(ctx: EngineContext) -> Path | None:
+    override = ctx.options.get("template")
+    if override:
+        candidate = Path(override).expanduser().resolve()
+        return candidate if candidate.is_file() else None
+    return _bundled_template_path()
+
+
+def _fallback(ctx: EngineContext, reason: str) -> EngineResult:
+    result = data_visualizer_run(ctx)
+    if result.workbook_path is not None:
+        fallback_output = "Generated Data Visualizer workbook and preview fallbacks instead."
+    else:
+        fallback_output = "Generated preview/reference artifacts only."
+    result.warnings.insert(
+        0,
+        f"Requested target '{ctx.target}' (engine '{ctx.requested_engine}'): "
+        f"{reason} Cascading to data-visualizer/internal preview. {fallback_output}",
+    )
+    return result
+
+
+def _layout_inches(ir: dict[str, Any]) -> dict[str, dict[str, float]]:
+    """Compute simple grid coordinates in inches keyed by node id."""
+
+    nodes = ir.get("nodes", [])
+    edges = ir.get("edges", [])
+    node_ids = [n["id"] for n in nodes]
+    outgoing: dict[str, list[str]] = {nid: [] for nid in node_ids}
+    incoming: dict[str, int] = {nid: 0 for nid in node_ids}
+    for edge in edges:
+        if edge["from"] in outgoing and edge["to"] in incoming:
+            outgoing[edge["from"]].append(edge["to"])
+            incoming[edge["to"]] += 1
+
+    queue = [nid for nid in node_ids if incoming[nid] == 0]
+    rank = {nid: 0 for nid in node_ids}
+    seen: set[str] = set()
+    while queue:
+        nid = queue.pop(0)
+        seen.add(nid)
+        for tgt in outgoing[nid]:
+            rank[tgt] = max(rank[tgt], rank[nid] + 1)
+            incoming[tgt] -= 1
+            if incoming[tgt] == 0:
+                queue.append(tgt)
+    if len(seen) < len(node_ids):
+        fallback_rank = max(rank.values(), default=0) + 1
+        for nid in node_ids:
+            if nid not in seen:
+                rank[nid] = fallback_rank
+
+    groups: dict[int, list[str]] = {}
+    for nid in node_ids:
+        groups.setdefault(rank[nid], []).append(nid)
+
+    orientation = ir.get("orientation", "left_to_right")
+    margin_x = 1.0
+    margin_y = 1.0
+    x_gap = 2.5
+    y_gap = 1.5
+    page_top = 10.5  # inches; pin Y is measured from page bottom
+
+    positions: dict[str, dict[str, float]] = {}
+    for rank_value in sorted(groups):
+        for index, nid in enumerate(groups[rank_value]):
+            if orientation == "left_to_right":
+                x = margin_x + rank_value * x_gap
+                y = page_top - index * y_gap - margin_y
+            else:
+                x = margin_x + index * x_gap
+                y = page_top - rank_value * y_gap - margin_y
+            positions[nid] = {"x": x, "y": max(y, 1.0)}
+    return positions
+
+
+def _try_run(ctx: EngineContext) -> EngineResult:
+    template_path = _resolve_template(ctx)
+    if template_path is None:
+        return _fallback(
+            ctx,
+            "no template available (provide --template PATH or reinstall with "
+            "the [vsdx] extra so the bundled template is on disk).",
+        )
+
+    import vsdx  # local import; we already feature-detected
+
+    output_path = ctx.visio_dir / f"{ctx.diagram.id}.vsdx"
+    backup_if_manual_candidate(output_path)
+    shutil.copy2(template_path, output_path)
+
+    visio = vsdx.VisioFile(str(output_path))
+    try:
+        page = visio.pages[0]
+        stamps = {shape.text.strip(): shape for shape in page.child_shapes}
+
+        rect = stamps.get(_RECTANGLE_STAMP)
+        connector = stamps.get(_CONNECTOR_STAMP)
+        if rect is None or connector is None:
+            visio.close_vsdx()
+            return _fallback(
+                ctx,
+                f"template at '{template_path}' is missing required stamp shapes "
+                f"({_RECTANGLE_STAMP}, {_CONNECTOR_STAMP}).",
+            )
+
+        positions = _layout_inches(ctx.ir)
+        new_shapes: dict[str, Any] = {}
+
+        for node in ctx.ir.get("nodes", []):
+            kind = node.get("shape_kind", "process")
+            stamp_name = _KIND_TO_STAMP.get(kind, _RECTANGLE_STAMP)
+            stamp = stamps.get(stamp_name) or rect
+            new_xml = visio.copy_shape(stamp.xml, page)
+            new_id = new_xml.attrib.get("ID")
+            new_shape = page.find_shape_by_id(new_id)
+            pos = positions.get(node["id"], {"x": 1.0, "y": 5.0})
+            visio.set_shape_location(new_shape.xml, pos["x"], pos["y"])
+            visio.set_shape_text(new_shape.xml, node.get("label", node["id"]))
+            new_shapes[node["id"]] = new_shape
+
+        for edge in ctx.ir.get("edges", []):
+            src = new_shapes.get(edge["from"])
+            dst = new_shapes.get(edge["to"])
+            if src is None or dst is None:
+                continue
+            new_xml = visio.copy_shape(connector.xml, page)
+            new_id = new_xml.attrib.get("ID")
+            new_shape = page.find_shape_by_id(new_id)
+            try:
+                new_shape.set_start_and_finish((src.x, src.y), (dst.x, dst.y))
+            except Exception:
+                visio.set_shape_location(
+                    new_shape.xml,
+                    (src.x + dst.x) / 2,
+                    (src.y + dst.y) / 2,
+                )
+            label = edge.get("label", "")
+            if label:
+                visio.set_shape_text(new_shape.xml, label)
+
+        # Remove original stamp shapes so the page only carries diagram content.
+        for shape in list(page.child_shapes):
+            if shape.text.strip() in _KNOWN_STAMPS:
+                shape.remove()
+
+        visio.save_vsdx(str(output_path))
+    except Exception as exc:  # pragma: no cover - defensive guard
+        visio.close_vsdx()
+        last_frame = traceback.format_exc(limit=2).strip().splitlines()[-1]
+        return _fallback(
+            ctx,
+            f"vsdx engine raised {type(exc).__name__}: {exc}. ({last_frame})",
+        )
+    visio.close_vsdx()
+
+    return EngineResult(
+        actual_engine="vsdx_template_mutation",
+        editability="semi_native",
+        output_vsdx=output_path,
+    )
+
+
+def run(ctx: EngineContext) -> EngineResult:
+    if not is_flowchart_ir(ctx.ir):
+        ir_type = str(ctx.ir.get("diagram_type") or "unknown")
+        return _fallback(
+            ctx,
+            f"vsdx-template cannot handle source type '{ctx.diagram.source_type}' "
+            f"with IR type '{ir_type}'; only Mermaid flowchart IR with recognized nodes is supported.",
+        )
+    if not _vsdx_available():
+        return _fallback(
+            ctx,
+            "the 'vsdx' library is not installed (install with: "
+            "pip install 'spolvero[vsdx]').",
+        )
+    return _try_run(ctx)
+
+
+register("vsdx-template", run)

spolvero/hygiene.py

@@ -0,0 +1,205 @@
+"""Repository hygiene checks for migration readiness."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from spolvero.inspection import inspect_vsdx, scan_text
+
+
+DEFAULT_PERSONAL_TERMS = ("Bar" + "ry", "John" + "ston")
+DEFAULT_ALLOWED_VSDX = ("src/spolvero/templates/minimal_flowchart.vsdx",)
+GENERATED_PREFIXES = ("spolvero-handoff/", "spolvero/", "sample-output/", "generated/", "packages/", ".tmp/")
+GENERATED_PREFIX_NAMES = ("spolvero-",)
+TEXT_EXTENSIONS = {
+    ".cfg",
+    ".css",
+    ".dot",
+    ".ini",
+    ".json",
+    ".md",
+    ".mmd",
+    ".puml",
+    ".py",
+    ".txt",
+    ".toml",
+    ".yaml",
+    ".yml",
+}
+
+
+def check_hygiene(
+    root: str | Path = ".",
+    *,
+    forbidden_terms: list[str] | None = None,
+    personal_terms: list[str] | None = None,
+    allowed_vsdx: list[str] | None = None,
+    include_untracked: bool = False,
+    tracked_files: list[str] | None = None,
+) -> dict[str, Any]:
+    """Run migration hygiene checks and return a structured report."""
+
+    repo_root = Path(root).resolve()
+    personal = list(dict.fromkeys([*DEFAULT_PERSONAL_TERMS, *(personal_terms or [])]))
+    forbidden = list(forbidden_terms or []) + _env_terms()
+    allowed = {_normalize_path(path) for path in (allowed_vsdx or list(DEFAULT_ALLOWED_VSDX))}
+    git_error: str | None = None
+    if tracked_files is not None:
+        tracked = tracked_files
+    else:
+        try:
+            tracked = _git_files(repo_root, include_untracked=include_untracked)
+        except RuntimeError as exc:
+            tracked = []
+            git_error = str(exc)
+
+    report: dict[str, Any] = {
+        "root": str(repo_root),
+        "checked_files": len(tracked),
+        "include_untracked": include_untracked,
+        "findings": [],
+        "vsdx_reports": [],
+        "passed": True,
+    }
+    if git_error:
+        _add_finding(report, "git_unavailable", str(repo_root), git_error)
+
+    for raw_path in sorted(tracked):
+        rel_path = _normalize_path(raw_path)
+        path = repo_root / rel_path
+        if not path.exists():
+            _add_finding(report, "missing_file", rel_path, "Listed path does not exist; scan is incomplete.")
+            continue
+        if not path.is_file():
+            _add_finding(report, "non_file", rel_path, "Listed path is not a regular file; scan is incomplete.")
+            continue
+        if _is_generated_package_path(rel_path):
+            _add_finding(report, "generated_artifact", rel_path, "Generated handoff output must stay untracked.")
+        suffix = path.suffix.lower()
+        if suffix == ".xlsx":
+            _add_finding(report, "stray_workbook", rel_path, "Tracked workbooks are generated artifacts.")
+        if suffix == ".vsdx":
+            if rel_path not in allowed:
+                _add_finding(report, "stray_vsdx", rel_path, "Tracked VSDX files need explicit approval.")
+            vsdx_report = inspect_vsdx(path, personal_terms=personal, forbidden_terms=forbidden)
+            report["vsdx_reports"].append(vsdx_report)
+            for finding in vsdx_report["findings"]:
+                _add_finding(
+                    report,
+                    f"vsdx_{finding['category']}",
+                    f"{rel_path}:{finding['source']}",
+                    finding["excerpt"],
+                    line=finding["line"],
+                )
+        if _looks_textual(path):
+            try:
+                text = path.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                text = path.read_text(encoding="utf-8", errors="replace")
+            for finding in scan_text(text, rel_path, personal, forbidden):
+                _add_finding(report, finding["category"], rel_path, finding["excerpt"], line=finding["line"])
+
+    report["passed"] = not report["findings"]
+    return report
+
+
+def render_hygiene_report(report: dict[str, Any]) -> str:
+    """Render a compact Markdown hygiene report."""
+
+    lines = [
+        "# Repository Hygiene Report",
+        "",
+        f"- Root: `{report['root']}`",
+        f"- Checked files: {report['checked_files']}",
+        f"- Included untracked files: {'yes' if report['include_untracked'] else 'no'}",
+        f"- VSDX packages inspected: {len(report['vsdx_reports'])}",
+        f"- Findings: {len(report['findings'])}",
+        f"- Result: {'PASS' if report['passed'] else 'FAIL'}",
+    ]
+    if report["vsdx_reports"]:
+        lines.extend(["", "## VSDX Packages"])
+        for vsdx in report["vsdx_reports"]:
+            lines.append(
+                f"- `{_repo_display(report['root'], vsdx['path'])}`: {vsdx['part_count']} parts, "
+                f"{len(vsdx['media'])} media part(s), {len(vsdx['findings'])} finding(s)"
+            )
+    if report["findings"]:
+        lines.extend(["", "## Findings"])
+        for finding in report["findings"]:
+            line = f"- {finding['category']} in `{finding['path']}`"
+            if finding.get("line") is not None:
+                line += f" line {finding['line']}"
+            line += f": {finding['message']}"
+            lines.append(line)
+    return "\n".join(lines) + "\n"
+
+
+def _git_files(root: Path, *, include_untracked: bool) -> list[str]:
+    cmd = ["git", "-C", str(root), "ls-files", "-z", "--cached"]
+    if include_untracked:
+        cmd.extend(["--others", "--exclude-standard"])
+    result = subprocess.run(cmd, check=False, capture_output=True)
+    if result.returncode != 0:
+        detail = result.stderr.decode("utf-8", errors="replace").strip() or "git ls-files failed"
+        raise RuntimeError(f"Could not enumerate git files: {detail}")
+    return [
+        item
+        for item in result.stdout.decode("utf-8", errors="replace").split("\0")
+        if item and not item.endswith("/")
+    ]
+
+
+def _env_terms() -> list[str]:
+    raw = os.environ.get("SPOLVERO_FORBIDDEN_TERMS", "")
+    return [term.strip() for term in raw.split(",") if term.strip()]
+
+
+def _normalize_path(path: str | Path) -> str:
+    normalized = str(path).replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    return normalized
+
+
+def _is_generated_package_path(path: str) -> bool:
+    if path.startswith(GENERATED_PREFIXES):
+        return True
+    first = path.split("/", 1)[0]
+    return first.startswith(GENERATED_PREFIX_NAMES)
+
+
+def _looks_textual(path: Path) -> bool:
+    if path.suffix.lower() in TEXT_EXTENSIONS:
+        return True
+    try:
+        sample = path.read_bytes()[:2048]
+    except OSError:
+        return False
+    if b"\0" in sample:
+        return False
+    try:
+        sample.decode("utf-8")
+    except UnicodeDecodeError:
+        return False
+    return True
+
+
+def _add_finding(
+    report: dict[str, Any],
+    category: str,
+    path: str,
+    message: str,
+    *,
+    line: int | None = None,
+) -> None:
+    report["findings"].append({"category": category, "path": path, "line": line, "message": message})
+
+
+def _repo_display(root: str, path: str) -> str:
+    try:
+        return Path(path).resolve().relative_to(Path(root).resolve()).as_posix()
+    except ValueError:
+        return path

spolvero/inspection.py

@@ -0,0 +1,222 @@
+"""Read-only VSDX package inspection helpers."""
+
+from __future__ import annotations
+
+import re
+import zipfile
+from pathlib import Path
+from typing import Any
+from xml.etree import ElementTree as ET
+
+
+EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
+PRIVATE_IPV4_RE = re.compile(
+    r"\b(?:10\.(?:\d{1,3}\.){2}\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|"
+    r"172\.(?:1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3})\b"
+)
+
+XML_SUFFIXES = (".xml", ".rels")
+MEDIA_SUFFIXES = (".bmp", ".emf", ".gif", ".jpeg", ".jpg", ".png", ".svg", ".tif", ".tiff", ".wmf")
+
+
+def inspect_vsdx(
+    path: str | Path,
+    *,
+    personal_terms: list[str] | None = None,
+    forbidden_terms: list[str] | None = None,
+) -> dict[str, Any]:
+    """Inspect a Visio package without modifying it."""
+
+    source = Path(path)
+    report: dict[str, Any] = {
+        "path": str(source),
+        "is_zip": False,
+        "part_count": 0,
+        "package_parts": [],
+        "doc_props": {},
+        "relationships": [],
+        "xml_parts": [],
+        "media": [],
+        "findings": [],
+        "warnings": [],
+    }
+    if not source.exists():
+        report["warnings"].append("file does not exist")
+        return report
+    if not zipfile.is_zipfile(source):
+        report["warnings"].append("file is not a valid zip package")
+        return report
+
+    try:
+        with zipfile.ZipFile(source) as archive:
+            report["is_zip"] = True
+            entries = sorted(archive.infolist(), key=lambda item: item.filename)
+            report["part_count"] = len(entries)
+            for entry in entries:
+                name = entry.filename
+                part = {"path": name, "size": entry.file_size}
+                report["package_parts"].append(part)
+                lower_name = name.lower()
+                if _is_media_part(lower_name):
+                    report["media"].append(part)
+                if lower_name.endswith(XML_SUFFIXES):
+                    report["xml_parts"].append(part)
+                    try:
+                        text = _read_zip_text(archive, name)
+                    except (OSError, RuntimeError, zipfile.BadZipFile) as exc:
+                        report["warnings"].append(f"could not read package part '{name}': {exc}")
+                        continue
+                    report["findings"].extend(scan_text(text, name, personal_terms, forbidden_terms))
+                    if lower_name.startswith("docprops/"):
+                        parsed = _parse_properties(text)
+                        report["doc_props"][name] = parsed if parsed else {"_raw_text": _compact_text(text)}
+                    if lower_name.endswith(".rels"):
+                        report["relationships"].extend(_parse_relationships(text, name))
+    except (OSError, zipfile.BadZipFile) as exc:
+        report["is_zip"] = False
+        report["warnings"].append(f"could not open zip package: {exc}")
+
+    return report
+
+
+def scan_text(
+    text: str,
+    source: str,
+    personal_terms: list[str] | None = None,
+    forbidden_terms: list[str] | None = None,
+) -> list[dict[str, Any]]:
+    """Return sensitive-pattern findings for a text blob."""
+
+    patterns: list[tuple[str, re.Pattern[str]]] = [
+        ("email", EMAIL_RE),
+        ("private_ipv4", PRIVATE_IPV4_RE),
+    ]
+    for term in personal_terms or []:
+        if term:
+            patterns.append(("personal_name", re.compile(rf"\b{re.escape(term)}\b", re.IGNORECASE)))
+    for term in forbidden_terms or []:
+        if term:
+            patterns.append(("forbidden_term", re.compile(re.escape(term), re.IGNORECASE)))
+
+    findings: list[dict[str, Any]] = []
+    for line_number, line in enumerate(text.splitlines() or [text], start=1):
+        for category, pattern in patterns:
+            for match in pattern.finditer(line):
+                findings.append(
+                    {
+                        "category": category,
+                        "source": source,
+                        "line": line_number,
+                        "excerpt": _redacted_excerpt(line, match.start(), match.end(), category),
+                    }
+                )
+    return findings
+
+
+def render_vsdx_report(report: dict[str, Any]) -> str:
+    """Render a compact Markdown inspection report."""
+
+    lines = [
+        f"# VSDX Inspection: {report['path']}",
+        "",
+        f"- Valid ZIP package: {_yes_no(report['is_zip'])}",
+        f"- Package parts: {report['part_count']}",
+        f"- XML/relationship parts: {len(report['xml_parts'])}",
+        f"- Media parts: {len(report['media'])}",
+        f"- Sensitive-pattern findings: {len(report['findings'])}",
+    ]
+    if report["warnings"]:
+        lines.extend(["", "## Warnings"])
+        lines.extend(f"- {warning}" for warning in report["warnings"])
+    if report["doc_props"]:
+        lines.extend(["", "## Document Properties"])
+        for part, props in sorted(report["doc_props"].items()):
+            summary = ", ".join(f"{key}={value!r}" for key, value in sorted(props.items()) if value)
+            lines.append(f"- `{part}`: {summary or '(empty)'}")
+    if report["relationships"]:
+        lines.extend(["", "## Relationships"])
+        for rel in report["relationships"]:
+            lines.append(f"- `{rel['part']}` {rel['id']} -> {rel['target']} ({rel['type_name']})")
+    if report["media"]:
+        lines.extend(["", "## Media Inventory"])
+        lines.extend(f"- `{part['path']}` ({part['size']} bytes)" for part in report["media"])
+    if report["findings"]:
+        lines.extend(["", "## Findings"])
+        for finding in report["findings"]:
+            lines.append(
+                f"- {finding['category']} in `{finding['source']}` line {finding['line']}: "
+                f"{finding['excerpt']}"
+            )
+    return "\n".join(lines) + "\n"
+
+
+def _read_zip_text(archive: zipfile.ZipFile, name: str) -> str:
+    raw = archive.read(name)
+    for encoding in ("utf-8", "utf-16", "latin-1"):
+        try:
+            return raw.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+    return raw.decode("utf-8", errors="replace")
+
+
+def _parse_properties(text: str) -> dict[str, str]:
+    try:
+        root = ET.fromstring(text)
+    except ET.ParseError:
+        return {}
+    props: dict[str, str] = {}
+    for element in root.iter():
+        if list(element):
+            continue
+        value = (element.text or "").strip()
+        if not value:
+            continue
+        key = element.attrib.get("name") or _local_name(element.tag)
+        props[key] = value
+    return props
+
+
+def _parse_relationships(text: str, part: str) -> list[dict[str, str]]:
+    try:
+        root = ET.fromstring(text)
+    except ET.ParseError:
+        return []
+    relationships: list[dict[str, str]] = []
+    for element in root.iter():
+        if _local_name(element.tag) != "Relationship":
+            continue
+        rel_type = element.attrib.get("Type", "")
+        relationships.append(
+            {
+                "part": part,
+                "id": element.attrib.get("Id", ""),
+                "target": element.attrib.get("Target", ""),
+                "target_mode": element.attrib.get("TargetMode", ""),
+                "type": rel_type,
+                "type_name": rel_type.rstrip("/").rsplit("/", 1)[-1],
+            }
+        )
+    return relationships
+
+
+def _is_media_part(lower_name: str) -> bool:
+    return "/media/" in lower_name or lower_name.startswith("docprops/thumbnail") or lower_name.endswith(MEDIA_SUFFIXES)
+
+
+def _local_name(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1] if "}" in tag else tag
+
+
+def _compact_text(text: str) -> str:
+    return " ".join(text.split())[:200]
+
+
+def _redacted_excerpt(line: str, start: int, end: int, category: str) -> str:
+    redacted = f"[{category}]"
+    excerpt = line[:start] + redacted + line[end:]
+    return excerpt.strip()[:180]
+
+
+def _yes_no(value: bool) -> str:
+    return "yes" if value else "no"