python-hwpx-automation 6.0.3__py3-none-any.whl

hwpx_automation/office/agent/path.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Canonical, non-XPath semantic paths for the HWPX agent facade."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+from .model import AgentContractError, NODE_KINDS
+
+MAX_PATH_CHARS = 2048
+MAX_PATH_SEGMENTS = 32
+PATH_ATTRIBUTES = frozenset({"id", "name"})
+
+_SEGMENT_RE = re.compile(
+    r"^(?P<kind>[a-z][a-z-]*)\["
+    r"(?:(?P<index>0*[1-9][0-9]*)|"
+    r"@(?P<attribute>[a-z]+)=(?P<value>\"(?:[^\"\\]|\\.)*\"))\]$"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class PathSegment:
+    kind: str
+    index: int | None = None
+    attribute: str | None = None
+    value: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.kind not in NODE_KINDS or self.kind in {"document", "unsupported"}:
+            raise AgentContractError("unknown_kind", f"unknown path kind: {self.kind}", target="path")
+        positional = self.index is not None
+        attributed = self.attribute is not None or self.value is not None
+        if positional == attributed:
+            raise AgentContractError(
+                "invalid_syntax", "path segment requires exactly one index or attribute", target="path"
+            )
+        if self.index is not None and (isinstance(self.index, bool) or self.index < 1):
+            raise AgentContractError("invalid_syntax", "path indexes are one-based", target="path")
+        if attributed and self.attribute not in PATH_ATTRIBUTES:
+            raise AgentContractError(
+                "invalid_syntax", f"unsupported path attribute: {self.attribute}", target="path"
+            )
+        if attributed and (not isinstance(self.value, str) or not self.value or len(self.value) > 256):
+            raise AgentContractError("resource_limit", "path attribute value is invalid", target="path")
+
+    def canonical(self) -> str:
+        if self.index is not None:
+            return f"{self.kind}[{self.index}]"
+        value = json.dumps(self.value, ensure_ascii=False, separators=(",", ":"))
+        return f"{self.kind}[@{self.attribute}={value}]"
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticPath:
+    segments: tuple[PathSegment, ...] = ()
+
+    @property
+    def canonical(self) -> str:
+        if not self.segments:
+            return "/"
+        return "/" + "/".join(segment.canonical() for segment in self.segments)
+
+    @property
+    def parent(self) -> "SemanticPath | None":
+        if not self.segments:
+            return None
+        return SemanticPath(self.segments[:-1])
+
+    def child(self, segment: PathSegment) -> "SemanticPath":
+        if len(self.segments) >= MAX_PATH_SEGMENTS:
+            raise AgentContractError("resource_limit", "path nesting exceeds limit", target="path")
+        return SemanticPath((*self.segments, segment))
+
+
+def parse_path(value: str) -> SemanticPath:
+    """Parse and canonicalize a bounded semantic path without invoking XPath."""
+
+    if not isinstance(value, str) or not value:
+        raise AgentContractError("invalid_syntax", "path must be a non-empty string", target="path")
+    if len(value) > MAX_PATH_CHARS:
+        raise AgentContractError("resource_limit", "path is too long", target="path")
+    if value == "/":
+        return SemanticPath()
+    if not value.startswith("/") or value.endswith("/"):
+        raise AgentContractError("invalid_syntax", "path must be absolute and canonical", target="path")
+    raw_segments: list[str] = []
+    start = 1
+    quoted = False
+    escaped = False
+    for index, char in enumerate(value[1:], start=1):
+        if quoted:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                quoted = False
+        elif char == '"':
+            quoted = True
+        elif char == "/":
+            raw_segments.append(value[start:index])
+            start = index + 1
+    if quoted:
+        raise AgentContractError("invalid_syntax", "unterminated path string", target="path")
+    raw_segments.append(value[start:])
+    if any(not segment for segment in raw_segments):
+        raise AgentContractError("invalid_syntax", "path contains an empty segment", target="path")
+    if len(raw_segments) > MAX_PATH_SEGMENTS:
+        raise AgentContractError("resource_limit", "path nesting exceeds limit", target="path")
+    segments: list[PathSegment] = []
+    for raw in raw_segments:
+        match = _SEGMENT_RE.fullmatch(raw)
+        if match is None:
+            raise AgentContractError("invalid_syntax", f"invalid path segment: {raw!r}", target="path")
+        kind = match.group("kind")
+        index_text = match.group("index")
+        if index_text is not None:
+            segments.append(PathSegment(kind=kind, index=int(index_text)))
+            continue
+        quoted_value = match.group("value")
+        try:
+            decoded = json.loads(quoted_value)
+        except (TypeError, ValueError, json.JSONDecodeError) as exc:
+            raise AgentContractError("invalid_syntax", "invalid path string literal", target="path") from exc
+        segments.append(
+            PathSegment(kind=kind, attribute=match.group("attribute"), value=decoded)
+        )
+    return SemanticPath(tuple(segments))
+
+
+def canonicalize_path(value: str) -> str:
+    return parse_path(value).canonical
+
+
+def indexed_segment(kind: str, index: int) -> PathSegment:
+    return PathSegment(kind=kind, index=index)
+
+
+def identified_segment(kind: str, value: str, *, attribute: str = "id") -> PathSegment:
+    return PathSegment(kind=kind, attribute=attribute, value=value)
+
+
+__all__ = [
+    "MAX_PATH_CHARS",
+    "MAX_PATH_SEGMENTS",
+    "PATH_ATTRIBUTES",
+    "PathSegment",
+    "SemanticPath",
+    "canonicalize_path",
+    "identified_segment",
+    "indexed_segment",
+    "parse_path",
+]

hwpx_automation/office/agent/query.py

@@ -0,0 +1,230 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Bounded selector v1 parser and in-memory semantic-tree evaluator."""
+
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from .model import (
+    MAX_QUERY_RESULTS,
+    MAX_SELECTOR_CHARS,
+    AgentContractError,
+    AgentNode,
+    SELECTOR_ATTRIBUTES,
+    SELECTOR_KINDS,
+)
+
+MAX_SELECTOR_STEPS = 8
+MAX_SELECTOR_FILTERS = 4
+_KIND_RE = re.compile(r"[a-z][a-z-]*")
+_ATTR_RE = re.compile(r"\[([a-z]+)=(\"(?:[^\"\\]|\\.)*\"|[^\]\s]+)\]")
+_CONTAINS_RE = re.compile(r":contains\((\"(?:[^\"\\]|\\.)*\")\)")
+
+
+class QueryRecord(Protocol):
+    kind: str
+    path: str
+    parent_path: str | None
+    attributes: Mapping[str, str]
+    search_text: str
+
+
+@dataclass(frozen=True, slots=True)
+class SelectorStep:
+    kind: str
+    attributes: tuple[tuple[str, str], ...] = ()
+    contains: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticSelector:
+    steps: tuple[SelectorStep, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class QueryResult:
+    selector: str
+    revision: str
+    nodes: tuple[AgentNode, ...]
+    truncated: bool
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "schemaVersion": "hwpx.agent-query-result/v1",
+            "selector": self.selector,
+            "revision": self.revision,
+            "count": len(self.nodes),
+            "truncated": self.truncated,
+            "nodes": [node.to_dict() for node in self.nodes],
+        }
+
+
+def normalize_search_text(value: object) -> str:
+    text = unicodedata.normalize("NFKC", str(value or ""))
+    return " ".join(text.split()).casefold()
+
+
+def _split_steps(selector: str) -> list[str]:
+    result: list[str] = []
+    start = 0
+    quoted = False
+    escaped = False
+    bracket_depth = 0
+    paren_depth = 0
+    for index, char in enumerate(selector):
+        if quoted:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                quoted = False
+            continue
+        if char == '"':
+            quoted = True
+        elif char == "[":
+            bracket_depth += 1
+        elif char == "]":
+            bracket_depth -= 1
+        elif char == "(":
+            paren_depth += 1
+        elif char == ")":
+            paren_depth -= 1
+        elif char == ">" and bracket_depth == 0 and paren_depth == 0:
+            result.append(selector[start:index].strip())
+            start = index + 1
+        if bracket_depth < 0 or paren_depth < 0:
+            raise AgentContractError("invalid_syntax", "unbalanced selector", target="selector")
+    if quoted or bracket_depth or paren_depth:
+        raise AgentContractError("invalid_syntax", "unbalanced selector", target="selector")
+    result.append(selector[start:].strip())
+    if any(not step for step in result):
+        raise AgentContractError("invalid_syntax", "empty selector step", target="selector")
+    return result
+
+
+def _decode_literal(value: str) -> str:
+    if value.startswith('"'):
+        try:
+            decoded = json.loads(value)
+        except (ValueError, json.JSONDecodeError) as exc:
+            raise AgentContractError("invalid_syntax", "invalid selector string", target="selector") from exc
+    else:
+        decoded = value
+    if not isinstance(decoded, str) or not decoded or len(decoded) > 256:
+        raise AgentContractError("resource_limit", "selector value is invalid", target="selector")
+    return decoded
+
+
+def _parse_step(raw: str) -> SelectorStep:
+    kind_match = _KIND_RE.match(raw)
+    if kind_match is None:
+        raise AgentContractError("invalid_syntax", "selector step requires a kind", target="selector")
+    kind = kind_match.group(0)
+    if kind not in SELECTOR_KINDS:
+        raise AgentContractError("unknown_kind", f"unknown selector kind: {kind}", target="selector")
+    cursor = kind_match.end()
+    attributes: list[tuple[str, str]] = []
+    contains: str | None = None
+    while cursor < len(raw):
+        attr_match = _ATTR_RE.match(raw, cursor)
+        if attr_match is not None:
+            name = attr_match.group(1)
+            if name not in SELECTOR_ATTRIBUTES:
+                raise AgentContractError(
+                    "unknown_property", f"unsupported selector attribute: {name}", target="selector"
+                )
+            if any(existing == name for existing, _ in attributes):
+                raise AgentContractError("invalid_syntax", "duplicate selector attribute", target="selector")
+            attributes.append((name, _decode_literal(attr_match.group(2))))
+            if len(attributes) > MAX_SELECTOR_FILTERS:
+                raise AgentContractError("resource_limit", "too many selector filters", target="selector")
+            cursor = attr_match.end()
+            continue
+        contains_match = _CONTAINS_RE.match(raw, cursor)
+        if contains_match is not None and contains is None:
+            contains = _decode_literal(contains_match.group(1))
+            cursor = contains_match.end()
+            continue
+        raise AgentContractError(
+            "invalid_syntax", f"invalid selector near {raw[cursor:]!r}", target="selector"
+        )
+    return SelectorStep(kind=kind, attributes=tuple(attributes), contains=contains)
+
+
+def parse_selector(value: str) -> SemanticSelector:
+    if not isinstance(value, str) or not value.strip():
+        raise AgentContractError("invalid_syntax", "selector must be non-empty", target="selector")
+    if len(value) > MAX_SELECTOR_CHARS:
+        raise AgentContractError("resource_limit", "selector is too long", target="selector")
+    raw_steps = _split_steps(value.strip())
+    if len(raw_steps) > MAX_SELECTOR_STEPS:
+        raise AgentContractError("resource_limit", "selector nesting exceeds limit", target="selector")
+    return SemanticSelector(tuple(_parse_step(step) for step in raw_steps))
+
+
+def _matches(record: QueryRecord, step: SelectorStep) -> bool:
+    if record.kind != step.kind:
+        return False
+    for name, expected in step.attributes:
+        actual = record.attributes.get(name)
+        if actual is None or normalize_search_text(actual) != normalize_search_text(expected):
+            return False
+    if (
+        step.contains is not None
+        and normalize_search_text(step.contains) not in normalize_search_text(record.search_text)
+    ):
+        return False
+    return True
+
+
+def evaluate_selector(
+    records: Sequence[QueryRecord] | Iterable[QueryRecord],
+    selector: SemanticSelector,
+    *,
+    limit: int,
+) -> tuple[list[QueryRecord], bool]:
+    if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= MAX_QUERY_RESULTS:
+        raise AgentContractError(
+            "resource_limit", f"query limit must be 1..{MAX_QUERY_RESULTS}", target="limit"
+        )
+    ordered = list(records)
+    by_path = {record.path: record for record in ordered}
+    matches: list[QueryRecord] = []
+    for record in ordered:
+        if not _matches(record, selector.steps[-1]):
+            continue
+        cursor = record
+        valid = True
+        for step in reversed(selector.steps[:-1]):
+            if cursor.parent_path is None:
+                valid = False
+                break
+            parent = by_path.get(cursor.parent_path)
+            if parent is None or not _matches(parent, step):
+                valid = False
+                break
+            cursor = parent
+        if valid:
+            if len(matches) == limit:
+                return matches, True
+            matches.append(record)
+    return matches, False
+
+
+__all__ = [
+    "MAX_SELECTOR_FILTERS",
+    "MAX_SELECTOR_STEPS",
+    "QueryRecord",
+    "QueryResult",
+    "SelectorStep",
+    "SemanticSelector",
+    "evaluate_selector",
+    "normalize_search_text",
+    "parse_selector",
+]

hwpx_automation/office/agent/story.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Private, contract-neutral bindings for existing non-body stories.
+
+The public semantic path grammar intentionally remains frozen at the Feature
+024 catalog.  This module recognizes one narrower command-only seam: an
+existing section header selected by its native id or page type.  It does not
+project headers into the public view, accept package paths, or expose XML.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from .model import AgentContractError
+from .path import MAX_PATH_CHARS
+
+HEADER_STORY_KIND = "header"
+HEADER_STORY_EDITABLE_PROPERTIES = frozenset({"text"})
+HEADER_PAGE_TYPES = frozenset({"BOTH", "EVEN", "ODD"})
+
+_HEADER_STORY_RE = re.compile(
+    r"^/section\[(?P<section>0*[1-9][0-9]*)\]/header\["
+    r"@(?P<attribute>id|page-type)=(?P<value>\"(?:[^\"\\]|\\.)*\")\]$"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class HeaderStoryPath:
+    """Parsed command-only path for one existing section header."""
+
+    section_index: int
+    attribute: str
+    value: str
+
+    @property
+    def kind(self) -> str:
+        return HEADER_STORY_KIND
+
+    @property
+    def canonical(self) -> str:
+        value = json.dumps(self.value, ensure_ascii=False, separators=(",", ":"))
+        return (
+            f"/section[{self.section_index}]/"
+            f"header[@{self.attribute}={value}]"
+        )
+
+    @property
+    def parent_path(self) -> str:
+        return f"/section[{self.section_index}]"
+
+
+@dataclass(frozen=True, slots=True)
+class HeaderStoryBinding:
+    """Request-local native binding for an existing logical header."""
+
+    path: str
+    parent_path: str
+    stable_id: str
+    native_id: str
+    page_type: str
+    section_index: int
+    native: Any
+    text: str
+
+    @property
+    def kind(self) -> str:
+        return HEADER_STORY_KIND
+
+    @property
+    def binding_key(self) -> str:
+        # Native ids are not promised to be document-global.  Section scope is
+        # part of the logical binding even though the receipt exposes the same
+        # kind:id stable-id convention used by projected semantic nodes.
+        return f"{self.section_index}:{self.native_id}"
+
+
+def try_parse_header_story_path(value: object) -> HeaderStoryPath | None:
+    """Return a private header path, or ``None`` for the public path parser.
+
+    Only exact supported forms are intercepted.  Unsupported forms such as
+    ``header[1]`` deliberately continue through :func:`parse_path` and retain
+    the frozen ``unknown_kind`` behavior.
+    """
+
+    if not isinstance(value, str) or "/header[@" not in value:
+        return None
+    if len(value) > MAX_PATH_CHARS:
+        raise AgentContractError("resource_limit", "path is too long", target="path")
+    match = _HEADER_STORY_RE.fullmatch(value)
+    if match is None:
+        return None
+    try:
+        decoded = json.loads(match.group("value"))
+    except (TypeError, ValueError, json.JSONDecodeError) as exc:
+        raise AgentContractError(
+            "invalid_syntax", "invalid header story path string", target="path"
+        ) from exc
+    if not isinstance(decoded, str) or not decoded or len(decoded) > 256:
+        raise AgentContractError(
+            "resource_limit", "header story selector is invalid", target="path"
+        )
+    attribute = match.group("attribute")
+    if attribute == "page-type" and decoded not in HEADER_PAGE_TYPES:
+        raise AgentContractError(
+            "invalid_syntax",
+            "header page type must be BOTH, EVEN, or ODD",
+            target="path",
+        )
+    return HeaderStoryPath(
+        section_index=int(match.group("section")),
+        attribute=attribute,
+        value=decoded,
+    )
+
+
+def parse_header_story_path(value: str) -> HeaderStoryPath:
+    """Parse an exact private header path for focused internal tests."""
+
+    parsed = try_parse_header_story_path(value)
+    if parsed is None:
+        raise AgentContractError(
+            "invalid_syntax", "unsupported header story path", target="path"
+        )
+    return parsed
+
+
+def resolve_header_story(document: Any, path: HeaderStoryPath) -> HeaderStoryBinding:
+    """Resolve one unique direct logical header without scanning descendants."""
+
+    try:
+        sections = document.sections
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise AgentContractError(
+            "unsupported_content", "document section structure is unavailable", target=path.canonical
+        ) from exc
+    if path.section_index > len(sections):
+        raise AgentContractError(
+            "not_found", "header story section does not exist", target=path.canonical
+        )
+    section = sections[path.section_index - 1]
+    try:
+        headers = tuple(section.properties.headers)
+        if path.attribute == "id":
+            matches = [header for header in headers if header.id == path.value]
+        else:
+            matches = [
+                header for header in headers if header.apply_page_type == path.value
+            ]
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise AgentContractError(
+            "unsupported_content", "section header structure is invalid", target=path.canonical
+        ) from exc
+
+    if not matches:
+        raise AgentContractError(
+            "not_found", f"existing header story not found: {path.canonical}", target=path.canonical
+        )
+    if len(matches) > 1:
+        raise AgentContractError(
+            "ambiguous_target",
+            f"header story selector is not unique: {path.canonical}",
+            target=path.canonical,
+        )
+
+    header = matches[0]
+    try:
+        native_id = header.id
+        page_type = header.apply_page_type
+        text = header.text
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise AgentContractError(
+            "unsupported_content", "header story cannot be read safely", target=path.canonical
+        ) from exc
+    if not native_id or len(native_id) > 256:
+        raise AgentContractError(
+            "unsupported_content", "header story has no bounded native identity", target=path.canonical
+        )
+    if page_type not in HEADER_PAGE_TYPES:
+        raise AgentContractError(
+            "unsupported_content", "header story has an unsupported page type", target=path.canonical
+        )
+
+    return HeaderStoryBinding(
+        path=path.canonical,
+        parent_path=path.parent_path,
+        stable_id=f"header:{native_id}",
+        native_id=native_id,
+        page_type=page_type,
+        section_index=path.section_index,
+        native=header,
+        text=text,
+    )
+
+
+__all__ = [
+    "HEADER_PAGE_TYPES",
+    "HEADER_STORY_EDITABLE_PROPERTIES",
+    "HEADER_STORY_KIND",
+    "HeaderStoryBinding",
+    "HeaderStoryPath",
+    "parse_header_story_path",
+    "resolve_header_story",
+    "try_parse_header_story_path",
+]