ummaya 0.2.4 → 0.2.5

package/src/ummaya/tools/documents/formats/text_web.py

@@ -0,0 +1,268 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Promoted text and web-export document engines."""
+
+from __future__ import annotations
+
+import html
+import re
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import NoReturn
+
+from ummaya.tools.documents.engines import DocumentMutationBlockedError
+from ummaya.tools.documents.models import (
+    BlockedReason,
+    DocumentExtraction,
+    DocumentFormat,
+    DocumentPatch,
+    DocumentPatchOperation,
+    KnownDocumentFormat,
+    MetadataValue,
+    OperationType,
+    ParagraphBlock,
+)
+from ummaya.tools.documents.tool_defs import DocumentFieldPatch
+
+_TEXT_BODY_TARGET = "/text/body"
+_TEXT_LINE_RE = re.compile(r"^/text/lines/(?P<index>[1-9][0-9]*)$")
+_RTF_UNICODE_RE = re.compile(r"\\u(?P<code>-?[0-9]+).")
+_RTF_CONTROL_RE = re.compile(r"\\[a-zA-Z]+-?[0-9]* ?")
+_TEXT_WEB_FORMATS = (
+    DocumentFormat.html,
+    DocumentFormat.htm,
+    DocumentFormat.txt,
+    DocumentFormat.rtf,
+    DocumentFormat.md,
+)
+
+
+class TextWebDocumentEngine:
+    """Bounded writer for UTF-8 text, Markdown, HTML, HTM, and RTF exports."""
+
+    render_engine_id = "text-web-structural-svg"
+    render_artifact_extension = "svg"
+    render_mime_type = "image/svg+xml"
+
+    def __init__(self, document_format: DocumentFormat) -> None:
+        if document_format not in _TEXT_WEB_FORMATS:
+            raise ValueError(f"unsupported text-web document format: {document_format.value}")
+        self.document_format = document_format
+        self.engine_id = f"text-web-{document_format.value}"
+
+    def inspect(self, path: Path, *, artifact_id: str) -> DocumentExtraction:
+        """Extract visible text lines from a promoted text/web document."""
+        raw_text = path.read_text(encoding="utf-8", errors="replace")
+        visible_text = _visible_text(raw_text, document_format=self.document_format)
+        return DocumentExtraction(
+            artifact_id=artifact_id,
+            paragraphs=_paragraphs_from_text(visible_text, source_name=path.name),
+            metadata=_metadata(path, document_format=self.document_format),
+        )
+
+    def apply_patch(self, path: Path, patch: DocumentPatch) -> bytes:
+        """Apply bounded text replacement and return derivative document bytes."""
+        raw_text = path.read_text(encoding="utf-8", errors="replace")
+        visible_text = _visible_text(raw_text, document_format=self.document_format)
+        for operation in patch.operations:
+            visible_text = _apply_text_operation(visible_text, operation)
+        output = _serialize_text_web(visible_text, document_format=self.document_format)
+        return output.encode("utf-8")
+
+    def render(self, path: Path, *, artifact_id: str, output_dir: Path) -> tuple[bytes, ...]:
+        """Render visible text as structural SVG evidence."""
+        _ = output_dir
+        extraction = self.inspect(path, artifact_id=artifact_id)
+        lines = [paragraph.text for paragraph in extraction.paragraphs]
+        return (_render_lines_svg(lines, title=f"{self.document_format.value.upper()} document"),)
+
+
+class TextWebDocumentAdapter:
+    """Format adapter for promoted text and web-export engines."""
+
+    adapter_id = "text-web-document-adapter"
+    known_formats: tuple[KnownDocumentFormat, ...] = (
+        KnownDocumentFormat.html,
+        KnownDocumentFormat.htm,
+        KnownDocumentFormat.txt,
+        KnownDocumentFormat.rtf,
+        KnownDocumentFormat.md,
+    )
+    promoted_formats: tuple[DocumentFormat, ...] = _TEXT_WEB_FORMATS
+
+    def __init__(self, engines: dict[DocumentFormat, TextWebDocumentEngine] | None = None) -> None:
+        self._engines = engines or {
+            document_format: TextWebDocumentEngine(document_format)
+            for document_format in _TEXT_WEB_FORMATS
+        }
+
+    def inspect(self, path: Path, *, artifact_id: str) -> DocumentExtraction:
+        """Inspect a text/web artifact using its suffix-selected engine."""
+        return self._engine_for_path(path).inspect(path, artifact_id=artifact_id)
+
+    def normalize_fill_patches(
+        self,
+        patches: tuple[DocumentFieldPatch, ...],
+        *,
+        extraction: DocumentExtraction | None,
+    ) -> tuple[DocumentFieldPatch, ...]:
+        """Return text/web patches unchanged; `/text/*` paths are native."""
+        _ = extraction
+        return patches
+
+    def _engine_for_path(self, path: Path) -> TextWebDocumentEngine:
+        try:
+            document_format = DocumentFormat(path.suffix.lower().lstrip("."))
+        except ValueError as exc:
+            raise DocumentMutationBlockedError(
+                BlockedReason.unsupported_format,
+                f"Unsupported text/web suffix: {path.suffix}",
+            ) from exc
+        engine = self._engines.get(document_format)
+        if engine is None:
+            raise DocumentMutationBlockedError(
+                BlockedReason.unsupported_format,
+                f"Unsupported text/web suffix: {path.suffix}",
+            )
+        return engine
+
+
+class _VisibleHTMLParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self._chunks: list[str] = []
+
+    def handle_data(self, data: str) -> None:
+        stripped = data.strip()
+        if stripped:
+            self._chunks.append(stripped)
+
+    def visible_text(self) -> str:
+        return "\n".join(self._chunks)
+
+
+def _visible_text(raw_text: str, *, document_format: DocumentFormat) -> str:
+    if document_format in {DocumentFormat.html, DocumentFormat.htm}:
+        parser = _VisibleHTMLParser()
+        parser.feed(raw_text)
+        return parser.visible_text()
+    if document_format is DocumentFormat.rtf:
+        return _strip_minimal_rtf(raw_text)
+    return raw_text
+
+
+def _apply_text_operation(text: str, operation: DocumentPatchOperation) -> str:
+    if operation.operation_type not in {OperationType.replace_text, OperationType.set_field_value}:
+        _raise_unsupported_operation(operation)
+    value = operation.value
+    if value is None:
+        _raise_unsupported_operation(operation)
+    replacement = str(value)
+    if operation.target_path == _TEXT_BODY_TARGET:
+        return replacement
+    match = _TEXT_LINE_RE.fullmatch(operation.target_path)
+    if match is None:
+        _raise_unsupported_operation(operation)
+    lines = text.splitlines(keepends=True)
+    line_index = int(match.group("index")) - 1
+    if line_index >= len(lines):
+        _raise_unsupported_operation(operation)
+    newline = "\n" if lines[line_index].endswith("\n") else ""
+    lines[line_index] = replacement.rstrip("\n") + newline
+    return "".join(lines)
+
+
+def _serialize_text_web(text: str, *, document_format: DocumentFormat) -> str:
+    if document_format in {DocumentFormat.html, DocumentFormat.htm}:
+        escaped = html.escape(text).replace("\n", "<br/>\n")
+        return f"<!doctype html>\n<html><body><p>{escaped}</p></body></html>\n"
+    if document_format is DocumentFormat.rtf:
+        return _rtf_payload_from_text(text)
+    return text
+
+
+def _paragraphs_from_text(text: str, *, source_name: str) -> list[ParagraphBlock]:
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    if not lines and text.strip():
+        lines = [text.strip()]
+    return [
+        ParagraphBlock(
+            block_id=f"text-line-{index}",
+            text=line,
+            source_path=f"/text/lines/{index}",
+        )
+        for index, line in enumerate(lines, start=1)
+    ] or [
+        ParagraphBlock(
+            block_id="text-line-1",
+            text="",
+            source_path=f"{source_name}:/text/lines/1",
+        )
+    ]
+
+
+def _strip_minimal_rtf(raw_text: str) -> str:
+    without_unicode = _RTF_UNICODE_RE.sub(lambda match: _rtf_codepoint(match), raw_text)
+    stripped = without_unicode.replace("{", "").replace("}", "")
+    stripped = _RTF_CONTROL_RE.sub("", stripped)
+    return "\n".join(line.strip() for line in stripped.splitlines() if line.strip())
+
+
+def _rtf_codepoint(match: re.Match[str]) -> str:
+    value = int(match.group("code"))
+    if value < 0:
+        value += 65536
+    return chr(value)
+
+
+def _rtf_payload_from_text(text: str) -> str:
+    encoded_chars: list[str] = []
+    for char in text:
+        if char == "\n":
+            encoded_chars.append(r"\par ")
+        elif char in {"\\", "{", "}"}:
+            encoded_chars.append(f"\\{char}")
+        elif ord(char) > 127:
+            codepoint = ord(char)
+            if codepoint > 32767:
+                codepoint -= 65536
+            encoded_chars.append(rf"\u{codepoint}?")
+        else:
+            encoded_chars.append(char)
+    return r"{\rtf1\ansi\uc1 " + "".join(encoded_chars).strip() + "}\n"
+
+
+def _metadata(path: Path, *, document_format: DocumentFormat) -> dict[str, MetadataValue]:
+    return {
+        "adapter_id": "text-web-document-adapter",
+        "engine_id": f"text-web-{document_format.value}",
+        "format": document_format.value,
+        "source_name": path.name,
+        "mutation_policy": "bounded_text_web_write_render_save",
+        "render_oracle": "text-web-structural-svg",
+    }
+
+
+def _render_lines_svg(lines: list[str], *, title: str) -> bytes:
+    escaped_title = html.escape(title)
+    safe_lines = [html.escape(line) for line in lines if line]
+    height = max(160, 72 + len(safe_lines) * 28)
+    text_nodes = [
+        f'<text x="32" y="{84 + index * 28}" font-size="16" font-family="sans-serif">{line}</text>'
+        for index, line in enumerate(safe_lines)
+    ]
+    svg = (
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="960" height="{height}" '
+        f'viewBox="0 0 960 {height}">'
+        '<rect width="100%" height="100%" fill="#ffffff"/>'
+        f'<text x="32" y="40" font-size="22" font-family="sans-serif" '
+        f'font-weight="700">{escaped_title}</text>' + "".join(text_nodes) + "</svg>"
+    )
+    return svg.encode("utf-8")
+
+
+def _raise_unsupported_operation(operation: DocumentPatchOperation) -> NoReturn:
+    raise DocumentMutationBlockedError(
+        BlockedReason.unsupported_operation,
+        f"Text/web operation is not supported: "
+        f"{operation.operation_type.value} {operation.target_path}",
+    )

package/src/ummaya/tools/documents/hwp_conversion_probe.py

@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Local HWP-to-HWPX bridge diagnostics.
+
+This module does not register converters. It reports whether a local candidate
+can satisfy the explicit `DocumentConversionEngine` environment boundary.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from shutil import which
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ummaya.tools.documents.models import DocumentFormat
+
+HWP_CONVERTER_ENV = "UMMAYA_HWP_TO_HWPX_CONVERTER"
+HWP_CONVERTER_ARGS_ENV = "UMMAYA_HWP_TO_HWPX_CONVERTER_ARGS_JSON"
+HWP_CONVERTER_ENGINE_ID_ENV = "UMMAYA_HWP_TO_HWPX_CONVERTER_ENGINE_ID"
+HWP_CONVERTER_TIMEOUT_ENV = "UMMAYA_HWP_TO_HWPX_CONVERTER_TIMEOUT_SECONDS"
+HWPFORGE_CANDIDATE_ID = "hwpforge-cli-convert-hwp5"
+HWPFORGE_HWP5_TO_HWPX_ARGS = (
+    "--json",
+    "convert-hwp5",
+    "{source}",
+    "--output",
+    "{output}",
+)
+HWPXJS_CANDIDATE_ID = "hwpxjs-cli-convert-hwp"
+HWPXJS_HWP_TO_HWPX_ARGS = ("convert:hwp", "{source}", "{output}")
+_HWPFORGE_SOURCE_REF = "upstream:hwpforge-cli-v0.6.0-convert-hwp5"
+_HWPXJS_SOURCE_REF = "upstream:ssabro-hwpxjs-v0.4.0"
+_ADR_REF = "adr:docs/adr/ADR-011-hwp-conversion-bridge.md"
+
+BridgeProbeStatus = Literal["configured", "available", "missing", "misconfigured"]
+
+
+class HwpToHwpxBridgeProbeReport(BaseModel):
+    """Current local availability of the HWP-to-HWPX bridge candidate."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    candidate_id: str = Field(min_length=1)
+    status: BridgeProbeStatus
+    source_format: DocumentFormat
+    output_format: DocumentFormat
+    executable: Path | None
+    recommended_args: tuple[str, ...]
+    recommended_env: dict[str, str]
+    reasons: tuple[str, ...]
+    evidence_refs: tuple[str, ...]
+
+
+def probe_hwp_to_hwpx_bridge(
+    *,
+    env: Mapping[str, str] | None = None,
+    search_path: Sequence[str] | None = None,
+) -> HwpToHwpxBridgeProbeReport:
+    """Report whether a local HwpForge CLI bridge is configured or discoverable."""
+    active_env = os.environ if env is None else env
+    configured = active_env.get(HWP_CONVERTER_ENV)
+    if configured:
+        configured_path = Path(configured).expanduser().resolve(strict=False)
+        if _is_executable_file(configured_path):
+            return _report(
+                candidate_id=active_env.get(HWP_CONVERTER_ENGINE_ID_ENV, HWPFORGE_CANDIDATE_ID),
+                status="configured",
+                executable=configured_path,
+                recommended_args=_configured_args_or_default(active_env),
+                reasons=("explicit_hwp_bridge_configured",),
+                evidence_refs=(_ADR_REF,),
+            )
+        return _report(
+            candidate_id=active_env.get(HWP_CONVERTER_ENGINE_ID_ENV, HWPFORGE_CANDIDATE_ID),
+            status="misconfigured",
+            executable=configured_path,
+            recommended_args=_configured_args_or_default(active_env),
+            reasons=("explicit_hwp_bridge_not_executable",),
+            evidence_refs=(_ADR_REF,),
+        )
+
+    discovered_hwpxjs = _find_executable("hwpxjs", active_env=active_env, search_path=search_path)
+    if discovered_hwpxjs is not None:
+        return _report(
+            candidate_id=HWPXJS_CANDIDATE_ID,
+            status="available",
+            executable=discovered_hwpxjs,
+            recommended_args=HWPXJS_HWP_TO_HWPX_ARGS,
+            reasons=("hwpxjs_cli_found_for_default_registration",),
+            evidence_refs=(_HWPXJS_SOURCE_REF, _ADR_REF),
+        )
+
+    discovered = _find_executable("hwpforge", active_env=active_env, search_path=search_path)
+    if discovered is None:
+        return _report(
+            candidate_id=HWPFORGE_CANDIDATE_ID,
+            status="missing",
+            executable=None,
+            recommended_args=HWPFORGE_HWP5_TO_HWPX_ARGS,
+            reasons=("hwpforge_cli_not_found",),
+            evidence_refs=(_HWPFORGE_SOURCE_REF, _ADR_REF),
+        )
+    return _report(
+        candidate_id=HWPFORGE_CANDIDATE_ID,
+        status="available",
+        executable=discovered,
+        recommended_args=HWPFORGE_HWP5_TO_HWPX_ARGS,
+        reasons=("hwpforge_cli_found_but_not_registered",),
+        evidence_refs=(_HWPFORGE_SOURCE_REF, _ADR_REF),
+    )
+
+
+def _find_executable(
+    name: str,
+    *,
+    active_env: Mapping[str, str],
+    search_path: Sequence[str] | None,
+) -> Path | None:
+    path_env = os.pathsep.join(search_path) if search_path is not None else active_env.get("PATH")
+    if not path_env:
+        return None
+    found = which(name, path=path_env)
+    if found is None:
+        return None
+    candidate = Path(found).expanduser().resolve(strict=False)
+    if not _is_executable_file(candidate):
+        return None
+    return candidate
+
+
+def _is_executable_file(path: Path) -> bool:
+    return path.exists() and path.is_file() and os.access(path, os.X_OK)
+
+
+def _configured_args_or_default(active_env: Mapping[str, str]) -> tuple[str, ...]:
+    raw = active_env.get(HWP_CONVERTER_ARGS_ENV)
+    if not raw:
+        return HWPFORGE_HWP5_TO_HWPX_ARGS
+    try:
+        decoded = json.loads(raw)
+    except json.JSONDecodeError:
+        return HWPFORGE_HWP5_TO_HWPX_ARGS
+    if not isinstance(decoded, list) or not all(isinstance(item, str) for item in decoded):
+        return HWPFORGE_HWP5_TO_HWPX_ARGS
+    return tuple(decoded)
+
+
+def _report(
+    *,
+    candidate_id: str,
+    status: BridgeProbeStatus,
+    executable: Path | None,
+    recommended_args: tuple[str, ...],
+    reasons: tuple[str, ...],
+    evidence_refs: tuple[str, ...],
+) -> HwpToHwpxBridgeProbeReport:
+    recommended_env = {
+        HWP_CONVERTER_ARGS_ENV: json.dumps(list(recommended_args)),
+        HWP_CONVERTER_ENGINE_ID_ENV: candidate_id,
+        HWP_CONVERTER_TIMEOUT_ENV: "120",
+    }
+    if executable is not None:
+        recommended_env[HWP_CONVERTER_ENV] = str(executable)
+    return HwpToHwpxBridgeProbeReport(
+        candidate_id=candidate_id,
+        status=status,
+        source_format=DocumentFormat.hwp,
+        output_format=DocumentFormat.hwpx,
+        executable=executable,
+        recommended_args=recommended_args,
+        recommended_env=recommended_env,
+        reasons=reasons,
+        evidence_refs=evidence_refs,
+    )

package/src/ummaya/tools/documents/hwp_direct_candidate.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+from typing import Final, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+RhwpHardGateFailure = Literal[
+    "license_unverified",
+    "api_surface_unverified",
+    "artifact_size_unverified",
+    "local_only_execution_unverified",
+    "hwp_write_capability_unverified",
+    "sanitized_hwp_round_trip_missing",
+    "render_comparison_missing",
+]
+RhwpPromotionState = Literal["blocked", "ready_for_fixture_round_trip"]
+
+_PERMISSIVE_LICENSES: Final[frozenset[str]] = frozenset(
+    {
+        "MIT",
+        "Apache-2.0",
+        "MIT OR Apache-2.0",
+        "Apache-2.0 OR MIT",
+    }
+)
+_MAX_REVIEWED_ARTIFACT_SIZE_BYTES: Final[int] = 25 * 1024 * 1024
+_GATE_SCORES: Final[dict[RhwpHardGateFailure, int]] = {
+    "license_unverified": 10,
+    "api_surface_unverified": 15,
+    "artifact_size_unverified": 10,
+    "local_only_execution_unverified": 20,
+    "hwp_write_capability_unverified": 15,
+    "sanitized_hwp_round_trip_missing": 20,
+    "render_comparison_missing": 10,
+}
+_GATE_MESSAGES: Final[dict[RhwpHardGateFailure, str]] = {
+    "license_unverified": "license evidence is missing or not permissive",
+    "api_surface_unverified": "local API surface evidence is missing",
+    "artifact_size_unverified": "reviewed artifact size evidence is missing",
+    "local_only_execution_unverified": "local-only execution evidence is missing",
+    "hwp_write_capability_unverified": "HWP write capability evidence is missing",
+    "sanitized_hwp_round_trip_missing": "sanitized HWP round-trip fixture evidence is missing",
+    "render_comparison_missing": "render comparison evidence is missing",
+}
+
+
+class RhwpCandidateEvidence(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    version: str = Field(min_length=1)
+    license_spdx: str | None = None
+    package_ref: str | None = Field(default=None, min_length=1)
+    artifact_size_bytes: int | None = Field(default=None, ge=1)
+    local_only_execution: bool | None = None
+    api_surface_refs: tuple[str, ...] = Field(default_factory=tuple)
+    supports_hwp_read: bool = True
+    supports_hwp_write: bool = True
+    supports_hwpx_read: bool = True
+    supports_hwpx_write: bool = True
+    sanitized_hwp_round_trip_fixture_refs: tuple[str, ...] = Field(default_factory=tuple)
+    render_comparison_refs: tuple[str, ...] = Field(default_factory=tuple)
+    source_refs: tuple[str, ...] = Field(min_length=1)
+    known_risk_refs: tuple[str, ...] = Field(default_factory=tuple)
+
+
+class RhwpCandidateEvaluation(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    engine_id: Literal["rhwp-direct-hwp"]
+    version: str
+    promotion_state: RhwpPromotionState
+    write_enabled: bool
+    total_score: int = Field(ge=0, le=100)
+    required_score: Literal[100]
+    hard_gate_failures: tuple[RhwpHardGateFailure, ...]
+    user_facing_summary: str
+    source_refs: tuple[str, ...]
+    known_risk_refs: tuple[str, ...]
+
+
+def evaluate_rhwp_candidate(evidence: RhwpCandidateEvidence) -> RhwpCandidateEvaluation:
+    failures = _hard_gate_failures(evidence)
+    total_score = 100 - sum(_GATE_SCORES[failure] for failure in failures)
+    write_enabled = not failures
+    promotion_state: RhwpPromotionState = (
+        "ready_for_fixture_round_trip" if write_enabled else "blocked"
+    )
+    return RhwpCandidateEvaluation(
+        engine_id="rhwp-direct-hwp",
+        version=evidence.version,
+        promotion_state=promotion_state,
+        write_enabled=write_enabled,
+        total_score=total_score,
+        required_score=100,
+        hard_gate_failures=failures,
+        user_facing_summary=_user_facing_summary(failures),
+        source_refs=evidence.source_refs,
+        known_risk_refs=evidence.known_risk_refs,
+    )
+
+
+def build_hwp_direct_write_candidate_result(
+    evidence: RhwpCandidateEvidence,
+) -> RhwpCandidateEvaluation:
+    return evaluate_rhwp_candidate(evidence)
+
+
+def _hard_gate_failures(
+    evidence: RhwpCandidateEvidence,
+) -> tuple[RhwpHardGateFailure, ...]:
+    failures: list[RhwpHardGateFailure] = []
+    if evidence.license_spdx not in _PERMISSIVE_LICENSES:
+        failures.append("license_unverified")
+    if not evidence.api_surface_refs:
+        failures.append("api_surface_unverified")
+    if not _artifact_size_is_reviewed(evidence.artifact_size_bytes):
+        failures.append("artifact_size_unverified")
+    if evidence.local_only_execution is not True:
+        failures.append("local_only_execution_unverified")
+    if not (evidence.supports_hwp_read and evidence.supports_hwp_write):
+        failures.append("hwp_write_capability_unverified")
+    if not evidence.sanitized_hwp_round_trip_fixture_refs:
+        failures.append("sanitized_hwp_round_trip_missing")
+    if not evidence.render_comparison_refs:
+        failures.append("render_comparison_missing")
+    return tuple(failures)
+
+
+def _artifact_size_is_reviewed(size: int | None) -> bool:
+    return size is not None and 0 < size <= _MAX_REVIEWED_ARTIFACT_SIZE_BYTES
+
+
+def _user_facing_summary(failures: tuple[RhwpHardGateFailure, ...]) -> str:
+    if not failures:
+        return (
+            "Direct HWP binary writing is ready for promotion evidence review; "
+            "the candidate must still run through the document primitive fixture suite."
+        )
+    reasons = "; ".join(_GATE_MESSAGES[failure] for failure in failures)
+    return f"Direct HWP binary writing remains blocked because {reasons}."